Use a ingestão de dados com o Vertex AI RAG Engine

Esta página explica como realizar a ingestão de dados através de uma origem de dados suportada, como o Cloud Storage, o Google Drive, o Slack, o Jira ou o SharePoint, e como usar esses dados com o Vertex AI RAG Engine. A API Import RagFiles fornece conetores de dados a estas origens de dados.

Origens de dados suportadas para a RAG

As seguintes origens de dados são suportadas:

  • Carregar um ficheiro local: um carregamento de ficheiro único através de upload_file (até 25 MB), que é uma chamada síncrona.
  • Cloud Storage: importe ficheiros do Cloud Storage.

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

    A conta de serviço tem de ter as autorizações corretas para importar ficheiros. Caso contrário, não são importados ficheiros nem é apresentada qualquer mensagem de erro. Para mais informações sobre os limites de tamanho dos ficheiros, consulte o artigo Tipos de documentos suportados.

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

    1. Aceda à página IAM do seu Google Cloud projeto.
    2. Selecione Incluir concessão de função fornecida pela Google.
    3. Pesquise a conta de serviço Vertex AI RAG Data Service Agent.
    4. Clique em Partilhar na pasta do Drive e partilhe-a com a conta de serviço.
    5. Conceda autorização à conta de serviço na pasta ou no ficheiro do Google Drive.Viewer Pode encontrar o ID do recurso do Google Drive no URL da Web.

  • Slack: Importe ficheiros do Slack através de um conetor de dados.

  • Jira: Importe ficheiros do Jira através de um conetor de dados.

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

Remoção de duplicados de dados

Se o mesmo ficheiro for importado várias vezes sem alterações, o ficheiro é ignorado, uma vez que já existe. Por conseguinte, o elemento response.skipped_rag_files_count refere-se ao número de ficheiros que foram ignorados durante o processo de importação.

Um ficheiro é ignorado quando as seguintes condições são cumpridas:

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

Compreenda as falhas de importação

Para compreender as falhas de importação, esta secção explica os metadados numa resposta a um pedido de importação e um destino de dados, que é o destino dos dados que está a importar.

Metadados de resposta

Pode usar response.metadata (um objeto de resposta no SDK) para ver os resultados da importação, a hora do pedido e a hora da resposta.

Import result sink

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 dos ficheiros com êxito e com falhas são escritos no destino. Ter todos os resultados escritos no destino facilita a compreensão do motivo pelo qual alguns ficheiros podem não ser importados e que ficheiros não foram importados.

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

  • Se import_result_sink for um caminho do Cloud Storage, deve usar o formato gs://my-bucket/my/object.ndjson e o objeto não pode existir. Após a conclusão da tarefa de importação, cada linha do objeto do Cloud Storage contém um objeto JSON, que tem um ID de operação, uma data/hora de criação, um nome de ficheiro, um estado e um ID de ficheiro.

  • Se import_result_sink for uma tabela do BigQuery, deve usar o formato bq://my-project.my-dataset.my-table. A tabela não tem de existir. Se a tabela não existir, é criada. Se a tabela existir, o esquema é validado. Na primeira vez que fornecer o destino do resultado da importação do BigQuery, vai fornecer uma tabela inexistente; caso contrário, pode reutilizar a tabela existente.

Importe ficheiros do Cloud Storage ou do Google Drive

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

  1. Crie um corpus seguindo as instruções em Crie um corpus RAG.

  2. Para importar os seus ficheiros do Cloud Storage ou do Google Drive, use o modelo.

    O sistema verifica automaticamente o caminho, o nome do ficheiro e o version_id. O version_id é um hash de ficheiro calculado através do conteúdo do ficheiro, o que impede a reindexação do ficheiro.

    Se um ficheiro com o mesmo nome de ficheiro e caminho tiver uma atualização de conteúdo, o ficheiro é reindexado.

Importe ficheiros do Slack

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

  1. Crie um corpus, que é um índice que estrutura e otimiza os seus dados para pesquisa. Siga as instruções em Crie um corpus de RAG.
  2. Obtenha o seu CHANNEL_ID a partir do ID do canal do Slack.
  3. Crie e configure uma app para usar com o motor RAG do Vertex AI.
    1. Na IU do Slack, na secção Adicionar funcionalidades, clique em Autorizações.
    2. Adicione as seguintes autorizações:
      • channels:history
      • groups:history
      • im:history
      • mpim:history
    3. Clique em Instalar no Workspace para instalar a app no seu espaço de trabalho do Slack.
  4. Clique em Copiar para obter o token da API, que autentica a sua identidade e concede-lhe acesso a uma API.
  5. Adicione o token da API ao Secret Manager.
  6. Para ver o segredo armazenado, conceda a função Secret Manager Secret Accessor à conta de serviço do Vertex AI RAG Engine do seu projeto.

Os seguintes exemplos de código curl e Python demonstram como importar ficheiros dos seus recursos do Slack.

curl

Se quiser receber mensagens de um canal específico, altere a 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 quiser receber mensagens para um determinado intervalo de tempo ou de um canal específico, altere qualquer 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,
    )

Importe ficheiros do Jira

Para importar ficheiros do Jira para o seu corpus, faça o seguinte:

  1. Crie um corpus, que é um índice que estrutura e otimiza os seus dados para pesquisa. Siga as instruções em Crie um corpus de RAG.
  2. Para criar um token de API, inicie sessão no site da Atlassian.
  3. Use {YOUR_ORG_ID}.atlassian.net como SERVER_URI no pedido.
  4. Use o seu email da Atlassian como EMAIL no pedido.
  5. Indique projects ou customQueries no seu pedido. Para saber mais sobre as consultas personalizadas, consulte o artigo Use a pesquisa avançada com a linguagem de consulta do Jira (JQL).

    Quando importa projects, projects é expandido nas consultas correspondentes para obter o projeto completo. Por exemplo, MyProject é expandido para project = MyProject.

  6. Clique em Copiar para obter o token da API, que autentica a sua identidade e concede-lhe acesso a uma API.
  7. Adicione o token da API ao Secret Manager.
  8. Conceda a função Secret Manager Secret Accessor à conta de serviço do Vertex AI RAG Engine do seu 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,
    )

Importe ficheiros do SharePoint

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

  1. Crie um corpus, que é um índice que estrutura e otimiza os seus dados para pesquisa. Siga as instruções em Crie um corpus de RAG.
  2. Crie uma app Azure para aceder ao seu site do SharePoint.
    1. Para criar um registo, aceda a Registos de apps.
      1. Indique um nome para a aplicação.
      2. Escolha a opção Apenas contas neste diretório organizacional.
      3. Verifique se os URIs de redirecionamento estão vazios.
    2. Na secção Vista geral, use o ID (de cliente) da aplicação como CLIENT_ID e use o "ID (de inquilino) do diretório" como TENANT_ID.
    3. Na secção Gerir, atualize as autorizações da API fazendo o seguinte:
      1. Adicione a autorização do SharePoint Sites.Read.All.
      2. Adicione as autorizações do Microsoft Graph Files.Read.All e Browser SiteLists.Read.All.
      3. Conceda o consentimento do administrador para que estas alterações de autorizações entrem em vigor.
    4. Na secção Gerir, faça o seguinte:
      1. Atualize Certificados e segredos com um novo segredo do cliente.
      2. Use o API_KEY_SECRET_VERSION para adicionar o valor secreto ao Secret Manager.
  3. Conceda a função Secret Manager Secret Accessor à conta de serviço do Vertex AI RAG Engine do seu projeto.
  4. Use {YOUR_ORG_ID}.sharepoint.com como SHAREPOINT_SITE_NAME.
  5. Tem de especificar um nome ou um ID do disco no site do SharePoint no pedido.
  6. Opcional: pode especificar um caminho da pasta ou um ID da pasta na unidade. Se o caminho da pasta ou o ID da pasta não for especificado, todas as pastas e ficheiros no disco sã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,
    )

O que se segue?