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, a hora da solicitação e a hora da resposta.

Coletor de resultados da 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.

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.

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": {
    "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/PROJECT_ID/locations/"
            "REGION/ragCorpora/RAG_CORPUS_ID"
        ),
        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

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": ["JIRA_PROJECT"],
        "customQueries": ["CUSTOM_QUERY"],
        "email": "EMAIL",
        "serverUri": "SERVER_URI",
        "apiKeyConfig": {
          "apiKeySecretVersion": "API_KEY_SECRET_VERSION"
        }
      }]
    }
  }
}'

Python 

    # Jira Example
    jira_query = rag.JiraQuery(
        email="EMAIL",
        jira_projects=["JIRA_PROJECT"],
        custom_queries=["CUSTOM_QUERY"],
        api_key="API_KEY_SECRET_VERSION",
        server_uri="SERVER_URI"
    )
    source = rag.JiraSource(
        queries=[jira_query],
    )

    response = rag.import_files(
        corpus_name=(
            "projects/PROJECT_ID/locations/"
            "REGION/ragCorpora/RAG_CORPUS_ID"
        ),
        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 app.

      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 the 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.

Localizar o ID do site

  1. Abra o navegador e acesse o URL do site do SharePoint de destino.

  2. Anexe /_api/site/id/ ao final desse URL.

    Exemplo:https://example-sp.sharepoint.com/sites/example-site/_api/site/id/

    A página retorna um payload XML. Anote a string após Edm.Guid. Esse é o ID do site.

Localizar o ID da unidade

Com o ID do site coletado, faça uma solicitação GET autenticada usando o Microsoft Graph Explorer ou o cliente da API:

GET https://graph.microsoft.com/v1.0/sites/SITE_ID/drive

Receba o SHAREPOINT_DRIVE_ID. O valor é listado no campo id na resposta JSON.

Localizar um ID de pasta específico

Use o ID da unidade para listar os filhos do diretório raiz:

GET https://graph.microsoft.com/v1.0/drives/SHAREPOINT_DRIVE_ID/root/children

  • Encontre o objeto que corresponde ao nome da pasta selecionada na resposta JSON e copie a string id correspondente. Esse é o SHAREPOINT_FOLDER_ID.

curl

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": "SHAREPOINT_TENANT_ID",
        "sharepointSiteName": "SHAREPOINT_SITE_NAME",
        "sharepointFolderId": "SHAREPOINT_FOLDER_ID",
        "driveId": "SHAREPOINT_DRIVE_ID"
      }]
    }
  }
}'

Python 

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

    vertexai.init(
        project="PROJECT_ID",
        location="REGION",
    )

    # SharePoint Example.
    source = resources.SharePointSources(
        share_point_sources=[
            resources.SharePointSource(
                client_id="CLIENT_ID",
                client_secret="API_KEY_SECRET_VERSION",
                tenant_id="SHAREPOINT_TENANT_ID",
                sharepoint_site_name="SHAREPOINT_SITE_NAME",
                sharepoint_folder_id="SHAREPOINT_FOLDER_ID",
                drive_id="SHAREPOINT_DRIVE_ID",
            )
        ]
    )

    response = rag.import_files(
        corpus_name=(
            "projects/PROJECT_ID/locations/"
            "REGION/ragCorpora/RAG_CORPUS_ID"
        ),
        source=source,
        chunk_size=512,
        chunk_overlap=100,
    )

A seguir