Use o Pinecone com o Vertex AI RAG Engine

Esta página mostra como associar o seu corpus RAG à base de dados Pinecone.

Também pode seguir este bloco de notas Vertex AI RAG Engine com Pinecone.

Pode usar a instância da base de dados do Pinecone com o motor RAG da Vertex AI para indexar e realizar uma pesquisa de similaridade baseada em vetores. Uma pesquisa de semelhanças é uma forma de encontrar fragmentos de texto semelhantes ao texto que está a procurar, o que requer a utilização de um modelo de incorporação. O modelo de incorporação produz dados vetoriais para cada fragmento de texto que está a ser comparado. A pesquisa de semelhanças é usada para obter contextos semânticos para a fundamentação, de modo a devolver o conteúdo mais preciso do seu MDG.

Com o motor RAG do Vertex AI, pode continuar a usar a sua instância de base de dados vetorial totalmente gerida, da qual é responsável pelo aprovisionamento. O motor RAG da Vertex AI usa a sua base de dados vetorial para armazenamento, gestão de índices e pesquisa.

Considere se deve usar o Pinecone com o Vertex AI RAG Engine

Considere se a utilização da base de dados Pinecone é a melhor escolha para a sua aplicação RAG revendo o seguinte:

  • Tem de criar, configurar e gerir o dimensionamento da instância da base de dados do Pinecone.

  • O Vertex AI RAG Engine usa o espaço de nomes predefinido no seu índice. Certifique-se de que este espaço de nomes não é modificável por mais nada.

  • Tem de fornecer uma chave da API Pinecone, que permite ao motor RAG da Vertex AI interagir com a base de dados Pinecone. O motor RAG do Vertex AI não armazena nem gere a sua chave da API Pinecone. Em vez disso, tem de fazer o seguinte:

    • Armazene a chave no Google Cloud Secret Manager.
    • Conceda autorizações à conta de serviço do seu projeto para aceder ao seu segredo.
    • Conceda ao motor RAG do Vertex AI acesso ao nome do recurso do seu segredo.
    • Quando interage com o seu corpus RAG, o Vertex AI RAG Engine acede ao seu recurso secreto através da sua conta de serviço.

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

Crie o seu índice do Pinecone

Para criar o seu índice do Pinecone, tem de seguir estes passos:

  1. Consulte o guia de início rápido do Pinecone para obter as configurações de índice que têm de ser especificadas no seu índice para tornar o índice compatível com o corpus RAG.

  2. Quer garantir que a localização do índice do Pinecone é igual ou próxima da localização onde usa o Vertex AI RAG Engine pelos seguintes motivos:

    • Quer manter as latências reduzidas.
    • Quer cumprir os requisitos de residência dos dados definidos pelas leis aplicáveis.

  3. Durante a criação do índice do Pinecone, especifique a dimensão da incorporação a usar com o Vertex AI RAG Engine. Esta tabela indica os tamanhos das dimensões ou a localização dos tamanhos das dimensões:

    Modelo Tamanho da dimensão
    Geco original 768
    Geco original otimizado 768
    E5 Consulte o artigo Use modelos de incorporação de software de código aberto.

  4. Escolha uma das seguintes métricas de distância suportadas:

    • cosine
    • dotproduct
    • euclidean

  5. Opcional: quando cria um índice baseado em pods, tem de especificar o file_id no campo pod.metadata_config.indexed. Para mais informações, consulte o artigo Indexação seletiva de metadados.

Crie a sua chave da API Pinecone

O motor RAG da Vertex AI só pode estabelecer ligação ao seu índice do Pinecone através da sua chave da API para autenticação e autorização. Tem de seguir o guia oficial da Pinecone para a autenticação para configurar a autenticação baseada em chaves da API no seu projeto Pinecone.

Armazene a chave da API no Secret Manager

Uma chave de API contém informações de identificação pessoal confidenciais (SPII), que estão sujeitas a requisitos legais. Se os dados SPII forem comprometidos ou usados indevidamente, um indivíduo pode sofrer um risco ou um dano significativo. Para minimizar os riscos para um indivíduo ao usar o motor RAG da Vertex AI, não armazene nem faça a gestão da sua chave da API e evite partilhar a chave da API não encriptada.

Para proteger as SPII, tem de fazer o seguinte:

  1. Armazene a chave da API no Secret Manager.

  2. Conceda à sua conta de serviço do Vertex AI RAG Engine as autorizações para os seus segredos e faça a gestão do controlo de acesso ao nível do recurso secreto.

    1. Navegue para as autorizações do projeto.

    2. Ative a opção Incluir concessões de funções fornecidas pela Google.

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

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

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

    5. Adicione a função Secret Manager Secret Accessor à conta de serviço.

  3. Durante a criação ou a atualização do corpus de RAG, transmita o nome do recurso secreto para o motor de RAG da Vertex AI e armazene o nome do recurso secreto.

Quando faz pedidos de API aos seus índices do Pinecone, o motor RAG do Vertex AI usa cada conta de serviço para ler a chave de API que corresponde aos seus recursos secretos no Secret Manager dos seus projetos.

Aprovisione a sua conta de serviço do Vertex AI RAG Engine

Quando cria o primeiro corpus de RAG no seu projeto, o Vertex AI RAG Engine cria uma conta de serviço dedicada. Pode encontrar a sua conta de serviço na página de gestão de identidade e de acesso do seu 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

Prepare o seu corpus de RAG

Para usar o seu índice do Pinecone com o motor RAG da Vertex AI, tem de associar o índice a um corpus RAG durante a fase de criação. Após a associação, esta ligação é permanente durante a duração do corpus RAG. A associação pode ser feita através da API CreateRagCorpus ou da API UpdateRagCorpus.

Para que a associação seja considerada concluída, tem de definir três campos principais no corpus de RAG:

  • rag_vector_db_config.pinecone: este campo ajuda a definir a escolha de uma base de dados vetorial que quer associar ao seu corpus RAG e tem de ser definido durante a chamada API CreateRagCorpus. Se não estiver definida, a escolha da base de dados vetorial predefinida RagManagedDb é atribuída ao seu corpus de RAG.

  • rag_vector_db_config.pinecone.index_name: este é o nome usado para criar o índice do Pinecone que é usado com o corpus RAG. Pode definir o nome durante a chamada CreateRagCorpus ou especificá-lo quando chamar a API UpdateRagCorpus.

  • rag_vector_db_config.api_auth.api_key_config.api_key_secret_version: Este é o nome completo do recurso do segredo armazenado no Secret Manager, que contém a sua chave da API Pinecone. Pode definir o nome durante a chamada CreateRagCorpus ou especificá-lo quando chamar a API UpdateRagCorpus. Até especificar este campo, não pode importar dados para o corpus RAG.
    Este campo deve ter o formato:
    projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

Crie o seu corpus de RAG

Se tiver acesso ao nome do índice do Pinecone e ao nome do recurso secreto com as suas autorizações definidas, pode criar o seu corpus de RAG e associá-lo ao seu índice do Pinecone, o que é demonstrado neste exemplo de código.

Quando cria um corpus RAG pela primeira vez, não tem as informações da conta de serviço disponíveis. No entanto, os campos são opcionais e podem ser associados ao corpus RAG através da API UpdateRagCorpus.

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

Python

Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Python Vertex AI.

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local. 


from vertexai 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.RagEmbeddingModelConfig(
    vertex_prediction_endpoint=rag.VertexPredictionEndpoint(
        publisher_model="publishers/google/models/text-embedding-005"
    )
)

# 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,
    backend_config=rag.RagVectorDbConfig(
        rag_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}

Crie um corpus RAG sem um nome de índice nem uma chave da API

Se este for o seu primeiro corpus RAG e não tiver acesso aos detalhes da conta de serviço ou não tiver concluído os passos de aprovisionamento para o seu índice do Pinecone, pode continuar a criar o seu corpus RAG. Em seguida, pode associar o corpus RAG a uma configuração do Pinecone vazia e adicionar os detalhes mais tarde.

É necessário ter em consideração o seguinte:

  • Quando não fornece o nome do índice e o nome secreto da chave da API, não é possível importar ficheiros para o corpus de RAG.
  • Se escolher o Pinecone como base de dados vetorial para o seu corpus RAG, não pode mudar posteriormente para uma base de dados diferente.

Este exemplo de código demonstra como criar um corpus RAG com o Pinecone sem fornecer um nome de índice do Pinecone nem um nome secreto da API. Use a API UpdateRagCorpus para especificar posteriormente as informações em falta.

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}

Atualize o seu corpus de RAG

A API UpdateRagCorpus permite-lhe atualizar a configuração da base de dados vetorial. Se o nome do índice do Pinecone e a versão secreta da chave da API não estiverem definidos anteriormente, pode usar a API Pinecone para atualizar os campos. Não é possível atualizar a escolha de uma base de dados vetorial. É opcional fornecer o segredo da chave da API. No entanto, se não especificar o segredo da chave da API, pode importar dados para o corpus da RAG.

Campo Mutabilidade Obrigatório ou opcional
rag_vector_db_config.vector_db Imutável depois de fazer uma escolha. Obrigatória
rag_vector_db_config.pinecone.index_name Imutável depois de definir o campo no corpus RAG. Obrigatória
rag_vector_db_config.api_auth.api_key_config.api_key_secret_version Mutável. Depois de definir a chave da API, não pode eliminá-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}

O que se segue?