Usar a pesquisa vetorial 2.0 com RAG

Nesta página, mostramos como o mecanismo RAG na Gemini Enterprise Agent Platform usa a busca vetorial 2.0 da Gemini Enterprise Agent Platform, que é um produto do Cloud de Confiance by S3NS que serve como um sistema abrangente de armazenamento e recuperação para armazenar e gerenciar representações vetoriais dos seus documentos. A Pesquisa Vetorial 2.0 da Gemini Enterprise Agent Platform é usada para recuperar documentos relevantes com base na similaridade semântica do documento com uma determinada consulta.

A RAG vai gerenciar as coleções da Pesquisa Vetorial 2.0 para você, e você terá acesso total a elas no seu projeto.

Como escolher um back-end de RAG

Ao usar o mecanismo RAG na Gemini Enterprise Agent Platform, é possível escolher entre diferentes opções de armazenamento de back-end para seus corpora RAG. A tabela a seguir resume as principais diferenças:

Escolha RagManagedVertexVectorSearch para ter os recursos mais recentes, gerenciamento automatizado e transparência nos dados da Pesquisa Vetorial 2.0. Se o suporte a CMEK for um requisito estrito, considere o RagManagedDb, tendo em mente a falta de visibilidade direta do banco de dados de back-end.

Ativar a API de busca vetorial

Para usar a pesquisa vetorial da Gemini Enterprise Agent Platform gerenciada por RAG, primeiro é necessário ativar a API Vector Search.

Criar um corpus de RAG com RagManagedVertexVectorSearch

Este exemplo de código demonstra como criar um corpus RAG usando RagManagedVertexVectorSearch.

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
DISPLAY_NAME = YOUR_RAG_CORPUS_DISPLAY_NAME

# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

vector_db = rag.RagManagedVertexVectorSearch()
rag_corpus = rag.create_corpus(
    display_name=DISPLAY_NAME, backend_config=rag.RagVectorDbConfig(vector_db=vector_db))

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
CORPUS_DISPLAY_NAME=CORPUS_DISPLAY_NAME

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora \
-d '{
      "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
      "vector_db_config": {
        "rag_managed_vertex_vector_search": {}
      }
    }'

Importar seus dados para o RagManagedVertexVectorSearch

É possível usar a API ImportRagFiles ou UploadRagFile para importar seus dados para o RagManagedVertexVectorSearch.

Para fazer upload do arquivo local para o corpus de RAG, consulte Fazer upload de um arquivo RAG. Para importar dados para seu corpus de RAG, consulte o exemplo de código a seguir, que demonstra como importar do Cloud Storage. Para saber mais sobre as fontes de dados compatíveis, consulte Fontes de dados compatíveis com RAG.

from vertexai.preview import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION
CORPUS_ID = YOUR_CORPUS_ID
PATHS = ["gs://my_bucket/my_files_dir"]

# Initialize Agent Platform API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

corpus_name = f"projects/{PROJECT_ID}/locations/{LOCATION}/ragCorpora/{CORPUS_ID}"
# This is a non blocking call.
response = await rag.import_files_async(
    corpus_name=corpus_name,
    paths=PATHS,
)

# Wait for the import to complete.
await response.result()

GCS_URI=GCS_URI

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": '\""${GCS_URI}"\"',
      },
  }
}'

Criar um índice para seu corpus

O mecanismo RAG cria uma coleção da Pesquisa Vetorial 2.0 para cada corpus, mas não cria um índice nessa coleção. Até que você crie um, cada recuperação será uma verificação de KNN de força bruta.

Uma verificação de força bruta é mais lenta do que uma pesquisa indexada, e o KNN é executado apenas em coleções de até 100.000 objetos de dados. O mecanismo RAG armazena um bloco por objeto de dados. Portanto, quando um corpus ultrapassa esse limite, a recuperação falha até que um índice seja criado.

Não indexe todos os corpora. Um índice é executado na própria infraestrutura de exibição e é faturado enquanto existir, independentemente de ser consultado ou não. Para decidir quais corpora precisam de um, consulte Decidir quais corpora indexar.

Depois que um índice é criado, a recuperação o usa automaticamente. O corpus não muda, e seus dados não precisam ser importados novamente.

Se você estiver indexando vários corpora, use um script para o loop: não há um caminho de criação em massa. As operações de índice simultâneas são limitadas por cota. Portanto, crie os índices em série ou em pequenos lotes. Para mais informações, consulte Cotas.

Antes de começar

A criação de um índice requer a permissão vectorsearch.indexes.create na coleção, e a contagem dos objetos de dados requer vectorsearch.dataObjects.query. As duas permissões estão incluídas no papel de Administrador da Pesquisa Vetorial (roles/vectorsearch.admin). O Gravador de Índice da Pesquisa Vetorial (roles/vectorsearch.indexWriter) concede a primeira. A API Vector Search também precisa estar ativada no projeto.

Encontrar os IDs do corpus

No seu projeto, cada corpus tem exatamente uma coleção, chamada vertex-rag-RAG_CORPUS_ID. Liste seus corpora para ver os IDs deles.

Substitua PROJECT_ID pelo ID do projeto:

PROJECT_ID=PROJECT_ID
LOCATION=us-central1

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora?pageSize=100"

A parte numérica no final de cada corpus name é o RAG_CORPUS_ID. Cada corpus também informa o nome completo do recurso Collection em vectorDbConfig.ragManagedVertexVectorSearch.collectionName.

A resposta lista no máximo 100 corpora e no máximo 25 se você omitir pageSize. Se a resposta incluir um nextPageToken, transmita esse valor como pageToken para buscar a próxima página.

Se você já souber o RAG_CORPUS_ID que quer indexar, busque apenas esse corpus. A resposta carrega o mesmo collectionName:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/RAG_CORPUS_ID"

Decidir quais corpora indexar

Para cada corpus, conte os objetos de dados na coleção. Transmita um filter vazio para contar toda a coleção:

COLLECTION_ID=vertex-rag-RAG_CORPUS_ID

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://vectorsearch.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/collections/${COLLECTION_ID}/dataObjects:aggregate" \
-d '{"aggregate": "COUNT", "filter": {}}'

A contagem é retornada em aggregateResults:

{
  "aggregateResults": [
    {
      "count": 95217
    }
  ]
}

Crie um índice para esse corpus quando uma das seguintes condições for verdadeira:

• A contagem está próxima ou acima de 100.000. O limite conta objetos de dados, não arquivos. Portanto, um corpus com um pequeno número de arquivos grandes ainda pode estar bem acima dele.
• A recuperação é muito lenta na sua taxa de consulta. Uma pesquisa indexada é mais rápida do que uma verificação de força bruta, e a diferença aumenta à medida que a coleção cresce.

Caso contrário, deixe o corpus sem indexação e evite o custo de veiculação. Você pode adicionar um índice mais tarde, se ele crescer.

Analisar o esquema da coleção

O RAG Engine cria cada coleção com o esquema a seguir. Use esses nomes ao especificar o campo de índice e os campos de filtro.

Escolha as configurações do índice

UpdateIndex altera apenas o nome de exibição, a descrição, os rótulos e as contagens de réplicas. Portanto, para alterar qualquer uma das configurações nesta seção, é necessário excluir o índice e criar um novo.

Campo de índice:defina como text_embedding, o único campo de vetor no esquema da coleção.

Métrica de distância:defina como cosseno. O mecanismo de RAG sempre envia COSINE_DISTANCE nas solicitações de recuperação, e a Pesquisa Vetorial 2.0 rejeita uma solicitação de recuperação cuja métrica não corresponde ao índice. A métrica assume como padrão DOT_PRODUCT quando você a omite. Portanto, um índice criado sem ela interrompe a recuperação desse corpus. O RAG Engine informa a falha como FAILED_PRECONDITION com a mensagem Failed to process Rag Managed Vertex Vector Search response., que não identifica a métrica como a causa. A grafia varia de acordo com a plataforma: o corpo REST usa COSINE_DISTANCE, e a flag da CLI gcloud usa cosine-distance.

Infraestrutura:deixe o índice na infraestrutura padrão otimizada para desempenho, porque a distância de cosseno não é compatível com a infraestrutura otimizada para armazenamento. Um índice é executado em uma infraestrutura de exibição dedicada e é cobrado enquanto existir. No v1, min_replica_count e max_replica_count têm como padrão 2. Portanto, por padrão, o índice é disponibilizado por duas réplicas e não é escalonado automaticamente. Para mais informações, consulte Índices de coleção.

Campos de filtro:defina filter_fields como file_id. É o único campo em que o RAG Engine filtra no momento da recuperação, e isso só acontece quando uma solicitação de recuperação restringe a pesquisa a arquivos específicos. Em particular, corpus_id tem o mesmo valor para cada objeto de dados em uma determinada coleção. Portanto, filtrá-lo não oferece nenhum benefício.

A filtragem de metadados também não precisa de outros campos de filtro. Quando uma solicitação de recuperação define ragRetrievalConfig.filter.metadataFilter, o RAG Engine resolve o filtro em relação aos metadados do arquivo primeiro, converte o resultado no conjunto de IDs de arquivo RAG correspondentes e envia esse conjunto para a Pesquisa Vetorial como o mesmo filtro file_id. Adicionar rag_metadata a filter_fields aumenta o tamanho do índice sem mudar a recuperação.

Campos de armazenamento:deixe store_fields sem definição. O mecanismo RAG solicita todos os campos de dados em cada recuperação, o que nunca se qualifica para a exibição inline. Portanto, os dados do bloco são lidos do banco de dados de backup de qualquer maneira. Os campos listados em store_fields são enviados para o índice e contam para o tamanho dele. Portanto, defini-los adiciona custo sem mudar a recuperação.

Criar o índice

from google.cloud import vectorsearch_v1

client = vectorsearch_v1.VectorSearchServiceClient()

index = vectorsearch_v1.Index(
    index_field="text_embedding",
    distance_metric=vectorsearch_v1.DistanceMetric.COSINE_DISTANCE,
    filter_fields=["file_id"],
)
request = vectorsearch_v1.CreateIndexRequest(
    parent="projects/PROJECT_ID/locations/us-central1/collections/vertex-rag-RAG_CORPUS_ID",
    index_id="vertex-rag-RAG_CORPUS_ID-index",
    index=index,
)

operation = client.create_index(request=request)

# Wait for the result (note this may take up to several minutes).
operation.result()

PROJECT_ID=PROJECT_ID
RAG_CORPUS_ID=RAG_CORPUS_ID
LOCATION=us-central1
COLLECTION_ID=vertex-rag-${RAG_CORPUS_ID}
INDEX_ID=${COLLECTION_ID}-index

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://vectorsearch.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/collections/${COLLECTION_ID}/indexes?indexId=${INDEX_ID}" \
-d '{
      "index_field": "text_embedding",
      "distance_metric": "COSINE_DISTANCE",
      "filter_fields": ["file_id"]
    }'

gcloud vector-search collections indexes create vertex-rag-RAG_CORPUS_ID-index \
  --collection=vertex-rag-RAG_CORPUS_ID \
  --index-field=text_embedding \
  --distance-metric=cosine-distance \
  --filter-fields=file_id \
  --location=us-central1 \
  --project=PROJECT_ID

Verificar a conclusão

A criação de um índice retorna uma operação de longa duração:

{
  "name": "projects/PROJECT_ID/locations/us-central1/operations/operation-1770302393524-64a14a54fa197-0dea326c-5a90efda",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vectorsearch.v1.OperationMetadata",
    "createTime": "2026-02-05T14:39:53.558308609Z",
    "target": "projects/PROJECT_ID/locations/us-central1/collections/vertex-rag-RAG_CORPUS_ID/indexes/vertex-rag-RAG_CORPUS_ID-index",
    "verb": "create",
    "apiVersion": "v1"
  },
  "done": false
}

Pesquise a operação usando o nome dessa resposta:

OPERATION_NAME=OPERATION_NAME

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://vectorsearch.googleapis.com/v1/${OPERATION_NAME}"

Quando done é true, um campo response significa que o índice foi criado com sucesso, e um campo error informa o motivo da falha. A criação de um índice leva vários minutos e mais tempo para um corpus grande.

Para listar as operações no projeto e no local, execute o seguinte:

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/operations"

Para inspecionar um índice, execute o seguinte:

gcloud vector-search collections indexes describe vertex-rag-RAG_CORPUS_ID-index \
  --collection=vertex-rag-RAG_CORPUS_ID \
  --location=us-central1 \
  --project=PROJECT_ID

Para excluir um índice, o que é necessário para mudar qualquer uma das configurações permanentes, execute o seguinte. A recuperação volta para uma verificação de KNN de força bruta até que o índice de substituição seja criado e falha totalmente se o corpus exceder 100.000 blocos.

gcloud vector-search collections indexes delete vertex-rag-RAG_CORPUS_ID-index \
  --collection=vertex-rag-RAG_CORPUS_ID \
  --location=us-central1 \
  --project=PROJECT_ID

A seguir

• Para importar arquivos e pastas do Google Drive ou do Cloud Storage, consulte o exemplo de importação de arquivos RAG.

• Para listar arquivos RAG, consulte o exemplo de listagem de arquivos RAG.

• Para usar um reclassificador para recuperação, consulte Reclassificação para o mecanismo RAG da Gemini Enterprise Agent Platform.

• Para ajustar a infraestrutura de índice, as métricas de distância e os parâmetros do ScaNN, consulte Índices de coleção.