Usar a ingestão de dados com o mecanismo RAG

Esta página explica como realizar a ingestão de dados usando uma fonte de dados compatível, como o Cloud Storage, o Google Drive, o Slack, o Jira ou o SharePoint, e como usar esses dados com o mecanismo RAG. O ragFiles.import fornece conectores de dados para essas fontes.

Fontes de dados compatíveis com RAG

Há suporte para as seguintes fontes de dados:

  • Fazer upload de um arquivo local:um upload de arquivo único usando upload_file (até 25 MB), que é uma chamada síncrona.
  • Cloud Storage:importe arquivos do Cloud Storage.

  • Google Drive:importe um diretório do Google Drive.

    A conta de serviço precisa receber as permissões corretas para importar arquivos. Caso contrário, nenhum arquivo será importado e nenhuma mensagem de erro será exibida. Para mais informações sobre os limites de tamanho de arquivo, consulte Tipos de documentos compatíveis.

    Para autenticar e conceder permissões, faça o seguinte:

    1. Acesse a página do IAM do seu Google Cloud projeto.
    2. Selecione Incluir concessão de papel fornecida pelo Google.
    3. Busque a conta de serviço do Agente de serviço de dados do RAG da Agent Platform.
    4. Clique em Compartilhar na pasta do drive e compartilhe com a conta de serviço.
    5. Conceda a permissão Viewer à conta de serviço na sua pasta ou arquivo do Google Drive. O ID do recurso do Google Drive pode ser encontrado no URL da Web.

  • Slack: importe arquivos do Slack usando um conector de dados.

  • Jira: importe arquivos do Jira usando um conector de dados.

Eliminação de duplicação de dados

Se o mesmo arquivo for importado várias vezes sem alterações, ele será ignorado porque já existe. Portanto, response.skipped_rag_files_count se refere ao número de arquivos que foram ignorados durante o processo de importação.

Um arquivo é ignorado quando as seguintes condições são atendidas:

  • O arquivo foi importado.
  • O arquivo não foi alterado.
  • A configuração de divisão em blocos do arquivo não foi alterada.

Entender falhas de importação

Para entender as falhas de importação, esta seção explica os metadados em uma resposta a uma solicitação de importação e um coletor de dados, que é o destino dos dados que você está importando.

Metadados de resposta

É possível usar response.metadata (um objeto de resposta no SDK) para conferir os resultados da importação, o horário da solicitação e o horário da resposta.

Coletor de resultados de importação

No SDK, import_result_sink é um parâmetro de função opcional que pode ser definido como um valor de string válido.

Se o import_result_sink for fornecido, os resultados de arquivos bem-sucedidos e com falha serão gravados no coletor. Ter todos os resultados gravados no coletor facilita a compreensão de por que alguns arquivos podem falhar na importação e quais arquivos não foram importados.

O import_result_sink precisa ser um caminho do Cloud Storage ou uma tabela do BigQuery.

  • Se o import_result_sink for um caminho do Cloud Storage, ele precisará usar o formato gs://my-bucket/my/object.ndjson, e o objeto não poderá existir. Depois que o job de importação for concluído, cada linha do objeto do Cloud Storage vai conter um objeto JSON, que tem um ID de operação, um carimbo de data/hora de criação, um nome de arquivo, um status e um ID de arquivo.

  • Se o import_result_sink for uma tabela do BigQuery, ele precisará usar o formato bq://my-project.my-dataset.my-table. A tabela não precisa existir. Se a tabela não existir, ela será criada. Se a tabela existir, o esquema será verificado. Na primeira vez que o coletor de resultados de importação do BigQuery for fornecido, você vai fornecer uma tabela inexistente. Caso contrário, será possível reutilizar a tabela existente.

Importar arquivos do Cloud Storage ou do Google Drive

Para importar arquivos do Cloud Storage ou do Google Drive para seu corpus, faça o seguinte:

  1. Crie um corpus RAG. Para mais informações, consulte Método: ragCorpora.create.

  2. Para importar arquivos do Cloud Storage ou do Google Drive, use o ragFiles.import método.

    O sistema verifica automaticamente o caminho, o nome do arquivo e o version_id. O version_id é um hash de arquivo calculado usando o conteúdo do arquivo, o que impede que ele seja reindexado.

    Se um arquivo com o mesmo nome e caminho tiver uma atualização de conteúdo, ele será reindexado.

Importar arquivos do Slack

Para importar arquivos do Slack para seu corpus, faça o seguinte:

  1. Crie um corpus, que é um índice que estrutura e otimiza seus dados para pesquisa. Para mais informações, consulte Método: ragCorpora.create.
  2. Receba o CHANNEL_ID do ID do canal do Slack.
  3. Crie e configure um app para usar com o mecanismo RAG.
    1. Na interface do Slack, na seção Adicionar recursos e funcionalidades, clique em Permissões.
    2. Adicione as seguintes permissões:
      • channels:history
      • groups:history
      • im:history
      • mpim:history
    3. Clique em Instalar no workspace para instalar o app no workspace do Slack.
  4. Clique em Copiar para receber o token da API, que autentica sua identidade e concede a você acesso a uma API.
  5. Adicione o token da API ao Secret Manager.
  6. Para conferir o secret armazenado, conceda o papel de Acessador de secrets do Secret Manager à conta de serviço do mecanismo RAG do projeto.

Os exemplos de código curl e Python a seguir demonstram como importar arquivos de recursos do Slack.

curl

Se você quiser receber mensagens de um canal específico, mude o CHANNEL_ID.

API_KEY_SECRET_VERSION=SLACK_API_KEY_SECRET_VERSION
CHANNEL_ID=SLACK_CHANNEL_ID
PROJECT_ID=us-central1

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ ENDPOINT }/v1beta1/projects/${ PROJECT_ID }/locations/${ PROJECT_ID }/ragCorpora/${ RAG_CORPUS_ID }/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "slack_source": {
      "channels": [
        {
          "apiKeyConfig": {
            "apiKeySecretVersion": "'"${ API_KEY_SECRET_VERSION }"'"
          },
          "channels": [
            {
              "channel_id": "'"${ CHANNEL_ID }"'"
            }
          ]
        }
      ]
    }
  }
}'

Python

Se você quiser receber mensagens de um determinado período ou de um canal específico, mude um dos seguintes campos:

  • START_TIME
  • END_TIME
  • CHANNEL1 ou CHANNEL2
    # Slack example
    start_time = protobuf.timestamp_pb2.Timestamp()
    start_time.GetCurrentTime()
    end_time = protobuf.timestamp_pb2.Timestamp()
    end_time.GetCurrentTime()
    source = rag.SlackChannelsSource(
        channels = [
            SlackChannel("CHANNEL1", "api_key1"),
            SlackChannel("CHANNEL2", "api_key2", START_TIME, END_TIME)
        ],
    )

    response = rag.import_files(
        corpus_name="projects/my-project/locations/us-central1/ragCorpora/my-corpus-1",
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

Importar arquivos do Jira

Para importar arquivos do Jira no corpus, faça o seguinte:

  1. Crie um corpus, que é um índice que estrutura e otimiza seus dados para pesquisa. Para mais informações, consulte Método: ragCorpora.create.

  2. Para criar um token de API, faça login no site da Atlassian.

  3. Use {YOUR_ORG_ID}.atlassian.net como SERVER_URI na solicitação.

  4. Use seu e-mail da Atlassian como EMAIL na solicitação.

  5. Forneça projects ou customQueries com a solicitação. Para saber mais sobre consultas personalizadas, consulte Usar a pesquisa avançada com a linguagem de consulta do Jira (JQL).

    Quando você importa projects, projects é expandido nas consultas correspondentes para abarcar todo o projeto. Por exemplo, MyProject é expandido para project = MyProject.

  6. Clique em Copiar para receber o token da API, que autentica sua identidade e concede a você acesso a uma API.

  7. Adicione o token da API ao Secret Manager.

  8. Conceda o papel de Acessador de secrets do Secret Manager à conta de serviço do mecanismo RAG do projeto.

curl

EMAIL=JIRA_EMAIL
API_KEY_SECRET_VERSION=JIRA_API_KEY_SECRET_VERSION
SERVER_URI=JIRA_SERVER_URI
CUSTOM_QUERY=JIRA_CUSTOM_QUERY
PROJECT_ID=JIRA_PROJECT
REGION= "us-central1"

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ ENDPOINT }/v1beta1/projects/${ PROJECT_ID }/locations/REGION>/ragCorpora/${ RAG_CORPUS_ID }/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "jiraSource": {
      "jiraQueries": [{
        "projects": ["'"${ PROJECT_ID }"'"],
        "customQueries": ["'"${ CUSTOM_QUERY }"'"],
        "email": "'"${ EMAIL }"'",
        "serverUri": "'"${ SERVER_URI }"'",
        "apiKeyConfig": {
          "apiKeySecretVersion": "'"${ API_KEY_SECRET_VERSION }"'"
        }
      }]
    }
  }
}'

Python 

    # Jira Example
    jira_query = rag.JiraQuery(
        email="xxx@yyy.com",
        jira_projects=["project1", "project2"],
        custom_queries=["query1", "query2"],
        api_key="api_key",
        server_uri="server.atlassian.net"
    )
    source = rag.JiraSource(
        queries=[jira_query],
    )

    response = rag.import_files(
        corpus_name="projects/my-project/locations/REGION/ragCorpora/my-corpus-1",
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

Importar arquivos do SharePoint

Para importar arquivos do site do SharePoint para seu corpus, faça o seguinte:

  1. Crie um corpus, que é um índice que estrutura e otimiza seus dados para pesquisa. Para mais informações, consulte Método: ragCorpora.create.

  2. Crie um app do Azure para acessar o site do SharePoint.

    1. Para criar um registro, acesse Registros de apps.

      1. Forneça um nome para o aplicativo.

      2. Escolha a opção Somente contas neste diretório organizacional.

      3. Verifique se os URIs de redirecionamento estão vazios.

    2. Na seção Visão geral, use o ID do aplicativo (cliente) como o CLIENT_ID e o "ID do diretório (locatário)" como o TENANT_ID.

    3. Na seção Gerenciar, atualize as permissões da API fazendo o seguinte:

      1. Adicione a permissão Sites.Read.All do SharePoint.

      2. Adicione as permissões Files.Read.All e Browser SiteLists.Read.All do Microsoft Graph.

      3. Conceda o consentimento do administrador para que essas mudanças de permissão entrem em vigor.

    4. Na seção Gerenciar, faça o seguinte:

      1. Atualize Certificados e secrets com um novo chave secreta do cliente.

      2. Use o API_KEY_SECRET_VERSION para adicionar o secret valor ao Secret Manager.

  3. Conceda o papel de Acessador de secrets do Secret Manager à conta de serviço do mecanismo RAG do projeto.

  4. Use {YOUR_ORG_ID}.sharepoint.com como el SHAREPOINT_SITE_NAME.

  5. Um nome ou ID de unidade no site do SharePoint precisa ser especificado na solicitação.

  6. Opcional: um caminho ou ID de pasta na unidade pode ser especificado. Se o caminho ou ID da pasta não for especificado, todas as pastas e arquivos na unidade serão importados.

curl

CLIENT_ID=SHAREPOINT_CLIENT_ID
API_KEY_SECRET_VERSION=SHAREPOINT_API_KEY_SECRET_VERSION
TENANT_ID=SHAREPOINT_TENANT_ID
SITE_NAME=SHAREPOINT_SITE_NAME
FOLDER_PATH=SHAREPOINT_FOLDER_PATH
DRIVE_NAME=SHAREPOINT_DRIVE_NAME

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ ENDPOINT }/v1beta1/projects/${ PROJECT_ID }/locations/REGION>/ragCorpora/${ RAG_CORPUS_ID }/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "sharePointSources": {
      "sharePointSource": [{
        "clientId": "'"${ CLIENT_ID }"'",
        "apiKeyConfig": {
          "apiKeySecretVersion": "'"${ API_KEY_SECRET_VERSION }"'"
        },
        "tenantId": "'"${ TENANT_ID }"'",
        "sharepointSiteName": "'"${ SITE_NAME }"'",
        "sharepointFolderPath": "'"${ FOLDER_PATH }"'",
        "driveName": "'"${ DRIVE_NAME }"'"
      }]
    }
  }
}'

Python 

    from vertexai.preview import rag
    from vertexai.preview.rag.utils import resources

    CLIENT_ID="SHAREPOINT_CLIENT_ID"
    API_KEY_SECRET_VERSION="SHAREPOINT_API_KEY_SECRET_VERSION"
    TENANT_ID="SHAREPOINT_TENANT_ID"
    SITE_NAME="SHAREPOINT_SITE_NAME"
    FOLDER_PATH="SHAREPOINT_FOLDER_PATH"
    DRIVE_NAME="SHAREPOINT_DRIVE_NAME"

    # SharePoint Example.
    source = resources.SharePointSources(
        share_point_sources=[
            resources.SharePointSource(
                client_id=CLIENT_ID,
                client_secret=API_KEY_SECRET_VERSION,
                tenant_id=TENANT_ID,
                sharepoint_site_name=SITE_NAME,
                folder_path=FOLDER_PATH,
                drive_id=DRIVE_ID,
            )
        ]
    )

    response = rag.import_files(
        corpus_name="projects/my-project/locations/REGION/ragCorpora/my-corpus-1",
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

A seguir