Usar o Pinecone com o mecanismo RAG da Vertex AI

Esta página mostra como conectar seu corpus RAG ao banco de dados do Pinecone.

Você também pode seguir este notebook Vertex AI RAG Engine com Pinecone.

Você pode usar sua instância de banco de dados da Pinecone com o mecanismo RAG da Vertex AI para indexar e realizar uma pesquisa de similaridade baseada em vetor. Uma pesquisa de similaridade é uma maneira de encontrar trechos de texto semelhantes ao que você está procurando, o que exige o uso de um modelo de embedding. O modelo de embedding produz dados de vetor para cada parte do 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 seu LLM.

Com o mecanismo de RAG da Vertex AI, você pode continuar usando a instância de banco de dados de vetor totalmente gerenciada, pela qual você é responsável. O mecanismo de RAG da Vertex AI usa seu banco de dados de vetores para armazenamento, gerenciamento de índices e pesquisa.

Considere usar o Pinecone com o mecanismo RAG da Vertex AI

Considere se o uso do banco de dados da Pinecone é a melhor escolha para seu aplicativo RAG. Para isso, analise o seguinte:

  • Você precisa criar, configurar e gerenciar o escalonamento da instância do banco de dados da Pinecone.

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

  • Você precisa fornecer uma chave de API da Pinecone, que permite que o mecanismo de RAG da Vertex AI interaja com o banco de dados da Pinecone. O mecanismo de RAG da Vertex AI não armazena nem gerencia sua chave da API Pinecone. Em vez disso, faça o seguinte:

    • Armazene sua chave no Google Cloud Secret Manager.
    • Conceda permissões à conta de serviço do projeto para acessar o secret.
    • Forneça ao mecanismo RAG da Vertex AI acesso ao nome do recurso do segredo.
    • Quando você interage com o corpus do RAG, o mecanismo RAG da Vertex AI acessa seu recurso secreto usando sua conta de serviço.

  • O corpus RAG e o índice Pinecone têm um mapeamento de um para um. Essa associação é feita como parte da chamada de API CreateRagCorpus ou da chamada de API UpdateRagCorpus.

Criar seu índice Pinecone

Para criar seu índice da Pinecone, siga estas etapas:

  1. Consulte o guia de início rápido da Pinecone para conferir as configurações de índice que precisam ser especificadas para que o índice seja compatível com o corpus RAG.

  2. Você quer garantir que o local do índice do Pinecone seja o mesmo ou próximo de onde você usa o mecanismo de RAG da Vertex AI 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 da Pinecone, especifique a dimensão de embedding a ser usada com o mecanismo RAG da Vertex AI. Esta tabela mostra os tamanhos ou a localização das dimensões:

    Modelo Tamanho da dimensão
    Gecko próprio 768
    Gecko próprio com ajustes finos 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 pod, especifique o file_id no campo pod.metadata_config.indexed. Para mais informações, consulte Indexação seletiva de metadados.

Criar sua chave de API Pinecone

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

Armazenar a chave de API no Secret Manager

Uma chave de API contém informações sensíveis de identificação pessoal (SPII, na sigla em inglês), que estão sujeitas a requisitos legais. Se os dados do SPII forem comprometidos ou usados indevidamente, um indivíduo poderá sofrer um risco ou dano significativo. Para minimizar os riscos a um indivíduo ao usar o mecanismo RAG da Vertex AI, não armazene e gerencie sua chave de API e evite compartilhar a chave de API não criptografada.

Para proteger o SPII, faça o seguinte:

  1. Armazene sua chave de API no Secret Manager.

  2. Conceda à sua conta de serviço do mecanismo RAG da Vertex AI as permissões para seus segredos e gerencie o controle de acesso no nível do recurso secreto.

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

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

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

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

    4. Edite os 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 secreto para o mecanismo RAG da Vertex AI e armazene o nome do recurso secreto.

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

Provisionar a conta de serviço do mecanismo RAG da Vertex AI

Quando você cria o primeiro corpus RAG no seu projeto, o Vertex AI RAG Engine cria uma conta de serviço dedicada. Você pode encontrar sua conta de serviço na página Gerenciamento de identidade e acesso 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 da Vertex AI, é 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 completa, você precisa 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 vetor que você quer associar ao seu corpus de RAG. Ele precisa ser definido durante a chamada de API CreateRagCorpus. Se não estiver definido, a escolha padrão do banco de dados de vetor RagManagedDb será atribuída ao seu corpus de RAG.

  • rag_vector_db_config.pinecone.index_name: é o nome usado para criar o índice Pinecone 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: é o nome completo do recurso do secret armazenado no Secret Manager, que contém sua chave de API da 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 formato:
    projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

Criar seu corpus RAG

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

Se você estiver criando um corpus de RAG pela primeira vez, as informações da conta de serviço não estarão prontas. No entanto, os campos são opcionais e podem ser associados ao corpus de 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 corpus RAG sem um nome de índice ou uma chave de API.

Python

Antes de testar esse exemplo, siga as instruções de configuração para Python no Guia de início rápido da Vertex AI sobre como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Vertex AI para Python.

Para autenticar na Vertex AI, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 


from vertexai.preview import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# pinecone_index_name = "pinecone-index-name"
# pinecone_api_key_secret_manager_version = "projects/{PROJECT_ID}/secrets/{SECRET_NAME}/versions/latest"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure embedding model (Optional)
embedding_model_config = rag.EmbeddingModelConfig(
    publisher_model="publishers/google/models/text-embedding-004"
)

# Configure Vector DB
vector_db = rag.Pinecone(
    index_name=pinecone_index_name,
    api_key=pinecone_api_key_secret_manager_version,
)

corpus = rag.create_corpus(
    display_name=display_name,
    description=description,
    embedding_model_config=embedding_model_config,
    vector_db=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 seu primeiro corpus RAG e você não tiver acesso aos detalhes da sua conta de serviço ou não tiver concluído as etapas de provisionamento para o índice da Pinecone, ainda será possível criar o corpus RAG. Em seguida, você pode associar o corpus RAG a uma configuração vazia do Pinecone e adicionar os detalhes mais tarde.

Considere o seguinte:

  • Quando você não fornece o nome do índice e o nome secreto da chave de API, os arquivos não podem ser importados para o corpus RAG.
  • Se você escolher o Pinecone como seu banco de dados de vetores para o corpus RAG, ele não poderá ser alterado para outro banco de dados.

Este exemplo de código demonstra como criar um corpus RAG com o Pinecone sem fornecer um nome de índice do Pinecone ou um nome secreto da API. 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 da Pinecone e a versão secreta da chave de API não tiverem sido definidos anteriormente, use a API Pinecone para atualizar os campos. A escolha de um banco de dados vetorial não pode ser atualizada. O secret da chave de API é opcional. No entanto, se você não especificar o segredo da chave de API, poderá importar dados para o corpus do RAG.

Campo Mutabilidade Obrigatório ou opcional
rag_vector_db_config.vector_db Imutável depois que você faz uma escolha. Obrigatório
rag_vector_db_config.pinecone.index_name Imutável depois de definir o campo no corpus de 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 excluí-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