Usar o Pinecone com o mecanismo RAG

Esta página mostra como conectar o corpus RAG ao seu Pinecone do Pinecone.

Você também pode acompanhar usando o notebook RAG Engine with Pinecone.

É possível usar a instância do banco de dados do Pinecone com o mecanismo RAG para indexar e realizar uma pesquisa de similaridade baseada em vetores. Uma pesquisa de similaridade é uma maneira de encontrar trechos de texto que são semelhantes ao texto que você está procurando, o que exige o uso de um modelo de embedding. O modelo de embedding produz dados de vetor para cada trecho de texto que está sendo comparado. A pesquisa de similaridade é usada para recuperar contextos semânticos para embasamento e retornar o conteúdo mais preciso do LLM.

Com o mecanismo RAG, você pode continuar usando a instância do banco de dados de vetores totalmente gerenciada, que é de sua responsabilidade provisionar. O mecanismo RAG usa o banco de dados de vetores para armazenamento, gerenciamento de índice e pesquisa.

Considerar o uso do Pinecone com o mecanismo RAG

Considere se o uso do banco de dados do Pinecone é a melhor opção para seu aplicativo RAG revisando o seguinte:

  • É necessário criar, configurar e gerenciar o escalonamento da instância do banco de dados do Pinecone.

  • O mecanismo RAG usa o namespace padrão no índice. Verifique se esse namespace não pode ser modificado por mais nada.

  • É necessário fornecer uma chave de API do Pinecone, que permite que o mecanismo RAG interaja com o banco de dados do Pinecone. O mecanismo RAG não armazena nem gerencia a chave de API do Pinecone. Em vez disso, faça o seguinte:

    • Armazene a chave no Google Cloud Secret Manager.
    • Conceda permissões à conta de serviço do projeto para acessar o secret.
    • Forneça ao mecanismo RAG acesso ao nome do recurso do secret.

    • Ao interagir com o corpus RAG, o mecanismo RAG acessa o recurso secret usando a conta de serviço.

    • O corpus RAG e o índice do Pinecone têm um mapeamento de um para um. Essa associação é feita como parte do ragCorpora.create método ou do ragCorpora.patch método.

Criar o índice do Pinecone

Para criar o índice do Pinecone, siga estas etapas:

  1. Consulte o guia de início rápido do Pinecone para receber as configurações de índice que precisam ser especificadas no índice para torná-lo compatível com o corpus RAG.

  2. É recomendável garantir que o local do índice do Pinecone seja o mesmo ou próximo de onde você usa o mecanismo RAG pelos seguintes motivos:

    • Você quer manter latências reduzidas.
    • Você quer atender aos requisitos de residência de dados definidos pelas leis aplicáveis.

  3. Durante a criação do índice do Pinecone, especifique a dimensão de embedding a ser usada com o mecanismo RAG. Esta tabela fornece os tamanhos de dimensão ou o local dos tamanhos de dimensão:

    Modelo Tamanho da dimensão
    Gecko próprio 768
    Gecko próprio ajustado 768
    E5 Consulte Usar modelos de embedding do OSS.

  4. Escolha uma das seguintes métricas de distância compatíveis:

    • cosine
    • dotproduct
    • euclidean

  5. Opcional: ao criar um índice baseado em pods, é necessário especificar o file_id no campo pod.metadata_config.indexed. Para mais informações, consulte Indexação seletiva de metadados.

Criar a chave de API do Pinecone

O mecanismo RAG só pode se conectar ao índice do Pinecone usando a chave de API para autenticação e autorização. Siga o guia oficial do Pinecone para autenticação para configurar a autenticação baseada em chave de API no projeto do Pinecone.

Armazenar a chave de API no Secret Manager

Uma chave de API contém informações sensíveis de identificação pessoal (SPII), que estão sujeitas a requisitos legais. Se os dados de SPII forem comprometidos ou usados de forma inadequada, uma pessoa poderá sofrer um risco ou dano significativo. Para minimizar os riscos para uma pessoa ao usar o mecanismo RAG, não armazene nem gerencie a chave de API e evite compartilhar a chave de API não criptografada.

Para proteger as SPII, faça o seguinte:

  1. Armazene a chave de API no Secret Manager.

  2. Conceda à conta de serviço do mecanismo RAG as permissões para os secrets e gerencie o controle de acesso no nível do recurso secret.

    1. Navegue até as permissões do projeto.

    2. Ative a opção Incluir concessões de papéis fornecidas pelo Google.

    3. Encontre a conta de serviço, que tem o formato:

      service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

    4. Edite as principais da conta de serviço.

    5. Adicione o papel Secret Manager Secret Accessor à conta de serviço.

  3. Durante a criação ou atualização do corpus RAG, transmita o nome do recurso secret para o mecanismo RAG e armazene o nome do recurso secret.

Ao fazer solicitações de API para os índices do Pinecone, o mecanismo RAG usa cada conta de serviço para ler a chave de API que corresponde aos recursos secret no Secret Manager dos projetos.

Provisionar a conta de serviço do mecanismo RAG

Ao criar o primeiro corpus RAG no projeto, o mecanismo RAG cria uma conta de serviço dedicada. É possível encontrar a conta de serviço na página Identity and Access Management do projeto.

A conta de serviço segue este formato fixo:

service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

Por exemplo,

service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com

Preparar o corpus RAG

Para usar o índice do Pinecone com o mecanismo RAG, é necessário associar o índice a um corpus RAG durante a fase de criação. Depois que a associação é feita, essa vinculação é permanente durante todo o ciclo de vida do corpus RAG. A associação pode ser feita usando a API CreateRagCorpus ou UpdateRagCorpus.

Para que a associação seja considerada concluída, é necessário definir três campos principais no corpus RAG:

  • rag_vector_db_config.pinecone: esse campo ajuda a definir a escolha de um banco de dados de vetores que você quer associar ao corpus RAG e precisa ser definido durante a chamada de API CreateRagCorpus. Se não estiver definido, a opção de banco de dados de vetores padrão RagManagedDb será atribuída ao corpus RAG.

  • rag_vector_db_config.pinecone.index_name: esse é o nome usado para criar o índice do Pinecone que é usado com o corpus RAG. É possível definir o nome durante a chamada CreateRagCorpus ou especificar o nome ao chamar a API UpdateRagCorpus.

  • rag_vector_db_config.api_auth.api_key_config.api_key_secret_version: esse é o nome completo do recurso do secret armazenado no Secret Manager, que contém a chave de API do Pinecone. É possível definir o nome durante a chamada CreateRagCorpus ou especificar o nome ao chamar a API UpdateRagCorpus. Até que você especifique esse campo, não será possível importar dados para o corpus RAG.

    Esse campo precisa ter o seguinte formato:

    projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

Criar o corpus RAG

Se você tiver acesso ao nome do índice do Pinecone e ao nome do recurso secret com as permissões definidas, poderá criar o corpus RAG e associá-lo ao índice do Pinecone, conforme demonstrado neste exemplo de código.

Quando você cria um corpus RAG pela primeira vez, as informações da conta de serviço não estão prontas. No entanto, os campos são opcionais e podem ser associados ao corpus RAG usando a API UpdateRagCorpus.

Para conferir um exemplo de como criar o corpus RAG sem fornecer as informações da conta de serviço, consulte Criar um corpus RAG sem um nome de índice ou uma chave de API.

Python

Antes de testar esta amostra, siga as instruções de configuração Python no Guia de início rápido do Agent Platform: como usar bibliotecas de cliente.

Para autenticar no Agent Platform, configure o Application Default Credentials. Se quiser mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 


import agentplatform
from agentplatform import types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# pinecone_index_name = "pinecone-index-name"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Agent Platform client once per session
client = agentplatform.Client(project=PROJECT_ID, location="us-central1")

# Configure embedding model (Optional)
embedding_model_config = types.RagEmbeddingModelConfig(
    vertex_prediction_endpoint=types.RagEmbeddingModelConfigVertexPredictionEndpoint(
        endpoint="publishers/google/models/text-embedding-005"
    )
)

# Configure Vector DB
vector_db = types.RagVectorDbConfig(
    pinecone=types.RagVectorDbConfigPinecone(
     index_name=pinecone_index_name,
    ),
    rag_embedding_model_config=embedding_model_config,
)

corpus = client.rag.create_corpus(
    rag_corpus=types.RagCorpus(
        display_name=display_name,
        description=description,
        rag_vector_db_config=vector_db,
    )
)
print(corpus)
# Example response:
# RagCorpus(name='projects/1234567890/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description', embedding_model_config=...
# ...

REST

   # Set your project ID under which you want to create the corpus
   PROJECT_ID = "YOUR_PROJECT_ID"

   # Choose a display name for your corpus
   CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

   # Set your Pinecone index name
   PINECONE_INDEX_NAME=YOUR_INDEX_NAME

   # Set the full resource name of your secret. Follows the format
   # projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
   SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

   # Call CreateRagCorpus API with all the Vector DB information.
   # You can also add the embedding model choice or set other RAG corpus parameters on
   # this call per your choice.
   curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
         "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
         "rag_vector_db_config" : {
            "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
            "api_auth": {"api_key_config":
                  {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
            }
         }
      }'

   # To poll the status of your RAG corpus creation, get the operation_id returned in
   # response of your CreateRagCorpus call.
   OPERATION_ID="YOUR_OPERATION_ID"

   # Poll Operation status until done = true in the response.
   # The response to this call will contain the ID for your created RAG corpus
   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

Criar um corpus RAG sem um nome de índice ou uma chave de API

Se este for o primeiro corpus RAG e você não tiver acesso aos detalhes da conta de serviço ou não tiver concluído as etapas de provisionamento do índice do Pinecone, ainda será possível criar o corpus RAG. Em seguida, associe o corpus RAG a uma configuração vazia do Pinecone e adicione os detalhes mais tarde.

O seguinte precisa ser considerado:

  • Quando você não fornece o nome do índice e o nome do secret da chave de API, não é possível importar arquivos para o corpus RAG.

  • Se você escolher o Pinecone como banco de dados de vetores para o corpus RAG, não será possível mudar para um banco de dados diferente mais tarde.

Este exemplo de código demonstra como criar um corpus RAG com o Pinecone sem fornecer um nome de índice ou um nome de secret da API do Pinecone. Use a API UpdateRagCorpus para especificar as informações ausentes mais tarde.

Python 

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone()

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST 

# Set your project ID under which you want to create the corpus
PROJECT_ID = "YOUR_PROJECT_ID"

# Choose a display name for your corpus
CORPUS_DISPLAY_NAME=YOUR_CORPUS_DISPLAY_NAME

# Call CreateRagCorpus API with all the Vector DB information.
# You can also add the embedding model choice or set other RAG corpus parameters on
# this call per your choice.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "rag_vector_db_config" : {
         "pinecone": {}
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

Atualizar o corpus RAG

A API UpdateRagCorpus permite atualizar a configuração do banco de dados de vetores. Se o nome do índice do Pinecone e a versão do secret da chave de API não estiverem definidos anteriormente, use a API do Pinecone para atualizar os campos. A escolha de um banco de dados de vetores não pode ser atualizada. É opcional fornecer o secret da chave de API. No entanto, se você não especificar o secret da chave de API, poderá importar dados para o corpus RAG.

Campo Mutabilidade Obrigatório ou opcional
rag_vector_db_config.vector_db Imutável depois de fazer uma escolha. Obrigatório
rag_vector_db_config.pinecone.index_name Imutável depois de definir o campo no corpus RAG. Obrigatório
rag_vector_db_config.api_auth.api_key_config.api_key_secret_version Mutável. Depois de definir a chave de API, não é possível descartá-la. Opcional

Python 

import vertexai
from vertexai.preview import rag

# Set Project
PROJECT_ID = "YOUR_PROJECT_ID"
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure the Pinecone vector DB information
vector_db = rag.Pinecone(index_name=)

# Name your corpus
DISPLAY_NAME = "YOUR_CORPUS_NAME"

rag_corpus = rag.create_corpus(display_name=DISPLAY_NAME, vector_db=vector_db)

REST 

# Set your project ID for the corpus that you want to create.
PROJECT_ID = "YOUR_PROJECT_ID"

# Set your Pinecone index name
PINECONE_INDEX_NAME=YOUR_INDEX_NAME

# Set the full resource name of your secret. Follows the format
# projects/{PROJECT_NUMER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
SECRET_RESOURCE_NAME=YOUR_SECRET_RESOURCE_NAME

# Call UpdateRagCorpus API with the Vector DB information.
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com}/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora -d '{
      "rag_vector_db_config" : {
         "pinecone": {"index_name": '\""${PINECONE_INDEX_NAME}"\"'},
         "api_auth": {"api_key_config":
               {"api_key_secret_version": '\""${SECRET_RESOURCE_NAME}"\"'}
         }
      }
   }'

# To poll the status of your RAG corpus creation, get the operation_id returned in
# response of your CreateRagCorpus call.
OPERATION_ID="YOUR_OPERATION_ID"

# Poll Operation status until done = true in the response.
# The response to this call will contain the ID for your created RAG corpus
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

A seguir