Armazenamento vetorial do Agent Retrieval

O Agent Retrieval (anteriormente Vector Search 2.0) é o banco de dados vetorial gerenciado do Google na Gemini Enterprise Agent Platform, geralmente disponível em vectorsearch.googleapis.com. O recurso agent-retrieval de adk-rag implementa o trait [VectorStore] para ele, portanto é integrado ao pipeline RAG existente exatamente como os backends pgvector, Qdrant, LanceDB e SurrealDB.

[dependencies]
adk-rag = { version = "2.1.0", features = ["agent-retrieval"] }

Início rápido

use adk_rag::VectorStore;
use adk_rag::agent_retrieval::{AgentRetrievalConfig, AgentRetrievalStore};

async fn run() -> adk_rag::Result<()> {
    // Application Default Credentials; project/location from the environment.
    let store = AgentRetrievalStore::new_with_adc(AgentRetrievalConfig::from_env()?)?;

    store.create_collection("docs", 768).await?;
    // upsert / search / delete exactly as with any other VectorStore backend
    Ok(())
}

Mapeamento para a plataforma

Operação de trait	Chamada de recuperação do agente
`create_collection`	`POST {parent}/collections` (operação de longa duração; `ALREADY_EXISTS` é uma no-op)
`delete_collection`	`DELETE {collection}` (operação de longa duração; `NOT_FOUND` é uma no-op)
`upsert`	`dataObjects:batchCreate` (≤1000, atômico), com fallback para create-else-patch por objeto para last-write-wins
`delete`	`dataObjects:batchDelete`, com fallback para exclusão por objeto quando os IDs estão ausentes
`search`	`dataObjects:search` com uma consulta `vectorSearch`

O texto e os metadados dos chunks são armazenados no Data Object junto com o vetor — não é necessário um armazenamento complementar. O armazenamento funciona no modo BYOE (traga seus próprios embeddings): os embeddings vêm do pipeline de embedder do adk-rag, mantendo o comportamento idêntico entre os backends. As pontuações são distâncias de DOT_PRODUCT, que equivalem à similaridade de cosseno para embeddings normalizados (quanto maior, mais relevante).

Configuração

Opção	Efeito
`with_collection_prefix("rag-")`	Prefixa cada ID de coleção, isolando as coleções deste armazenamento
`with_existing_collections_only(true)`	`create_collection` valida se a coleção existe em vez de criá-la — para implantações que fazem o provisionamento prévio com ferramentas da plataforma
`with_endpoint(...)`	Origem API personalizada (HTTP de loopback permitida para testes)

Os nomes das coleções são sanitizados em rótulos RFC 1035 (convertidos para minúsculas; caracteres inválidos tornam-se hífens), portanto my_docs torna-se o ID da coleção my-docs. Nomes distintos que são sanitizados de forma idêntica entram em conflito — escolha nomes que sejam diferentes em mais do que apenas maiúsculas/minúsculas ou pontuação.

Além do trait

Para chamadores que mantêm o AgentRetrievalStore concreto, hybrid_search executa uma consulta semântica e uma consulta por palavra-chave em uma única chamada dataObjects:batchSearch e retorna a lista classificada por fusão de posições recíprocas:

# use adk_rag::agent_retrieval::{AgentRetrievalConfig, AgentRetrievalStore};
# async fn run(store: AgentRetrievalStore, embedding: Vec<f32>) -> adk_rag::Result<()> {
let results = store
    .hybrid_search("docs", &embedding, "quarterly revenue", 10, (0.6, 0.4))
    .await?;
# Ok(())
# }

Observações sobre a plataforma

Regiões: Agent Retrieval é regional; as regiões compatíveis incluem us-central1, us-east4, us-west1, europe-north1, europe-west2, europe-west4, asia-east1, asia-northeast1 e asia-southeast1.
CMEK: o Agent Retrieval independente é compatível com chaves de criptografia gerenciadas pelo cliente por meio de encryptionSpec da coleção (imutável no momento da criação). Provisione previamente coleções CMEK com as ferramentas da plataforma e use with_existing_collections_only(true).
Vector Search 1.0 deliberadamente não é implementado. Seu modelo de infraestrutura de índice/endpoint se adapta mal ao trait VectorStore, e o Google posiciona o Agent Retrieval como seu sucessor.
Cotas: as gravações em lote são limitadas a 1000 objetos por solicitação e são atômicas; o armazenamento divide automaticamente as operações de inserção/atualização maiores em partes.

Testes

O backend passa pelo contrato compartilhado VectorStore e pelo conjunto de testes de propriedades executado por todos os backends adk-rag, portanto é comportamentalmente intercambiável com os outros armazenamentos. O teste ativo #[ignore] cria e exclui sua própria coleção com nome exclusivo (plano de dados, assim como os testes ativos de pgvector e Qdrant):

GOOGLE_CLOUD_PROJECT=my-project GOOGLE_CLOUD_LOCATION=us-central1 \
  cargo test -p adk-rag --features agent-retrieval -- --ignored