Usar a ingestão de dados com o mecanismo RAG da Vertex AI

Nesta página, explicamos como fazer a ingestão de dados usando uma fonte de dados compatível, como Cloud Storage, Google Drive, Slack, Jira ou SharePoint, e como usar esses dados com o mecanismo de RAG da Vertex AI. A API Import RagFiles oferece conectores de dados para essas fontes.

Fontes de dados compatíveis com RAG

As seguintes fontes de dados são compatíveis:

  • 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 projetoGoogle Cloud .
    2. Selecione Incluir concessão de papel fornecida pelo Google.
    3. Pesquise a conta de serviço do Agente de serviço de dados do RAG da Vertex AI.
    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.

Para mais informações, consulte a referência da API RAG.

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 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 da resposta

Use response.metadata (um objeto de resposta no SDK) para conferir os resultados da importação, o tempo de solicitação e o tempo de 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 com falha e bem-sucedidos serão gravados no gravador. Com todos os resultados gravados no gravador, é mais fácil entender por que alguns arquivos não foram importados e quais não foram.

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

  • Se 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 trabalho 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 import_result_sink for uma tabela do BigQuery, use 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 resultado da importação do BigQuery for fornecido, você vai informar uma tabela que não existe. Caso contrário, reutilize a tabela atual.

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 seguindo as instruções em Crie um corpus de RAG.

  2. Para importar arquivos do Cloud Storage ou do Google Drive, use o modelo.

    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. Siga as instruções disponíveis em Crie um corpus de RAG.
  2. Receba o CHANNEL_ID do ID do canal do Slack.
  3. Crie e configure um app para usar com o mecanismo de RAG da Vertex AI.
    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 RAG Engine da Vertex AI 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. Siga as instruções disponíveis em Crie um corpus de RAG.
  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 de RAG da Vertex AI 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 seu site do SharePoint para o corpus, faça o seguinte:

  1. Crie um corpus, que é um índice que estrutura e otimiza seus dados para pesquisa. Siga as instruções disponíveis em Crie um corpus de RAG.
  2. Crie um app do Azure para acessar seu site do SharePoint.
    1. Para criar um registro, acesse Registros de app.
      1. Dê um nome ao aplicativo.
      2. Escolha a opção Apenas contas neste diretório organizacional.
      3. Verifique se os URIs de redirecionamento estão vazios.
    2. Na seção Visão geral, use seu 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 as mudanças de permissão entrem em vigor.
    4. Na seção Gerenciar, faça o seguinte:
      1. Atualize Certificados e chaves secretas com uma nova chave secreta do cliente.
      2. Use o API_KEY_SECRET_VERSION para adicionar o valor do secret ao Secret Manager.
  3. Conceda o papel de Acessador de secrets do Secret Manager à conta de serviço do mecanismo de RAG da Vertex AI do projeto.
  4. Use {YOUR_ORG_ID}.sharepoint.com como o SHAREPOINT_SITE_NAME.
  5. Um nome ou ID de unidade no site do SharePoint precisa ser especificado na solicitação.
  6. Opcional: é possível especificar um caminho ou ID de pasta na unidade. Se o caminho ou ID da pasta não for especificado, todas as pastas e arquivos no drive 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