Vertex AI RAG Engine

Recupere contexto fundamentado de corpora gerenciados do Vertex AI RAG Engine — sem necessidade de armazenamento vetorial autogerenciado, provedor de embeddings ou pipeline de ingestão.

---

O que é

O Vertex AI RAG Engine é o backend gerenciado RAG do Google Cloud: você importa documentos para um RAG corpus e a plataforma cuida da divisão em partes, geração de embeddings e busca vetorial. O recurso vertex-rag de adk-rag fornece:

• VertexRagEngineClient — um cliente de plano de dados somente leitura, autenticado via ADC: obtém e lista corpora, lista arquivos importados e recupera contextos
• VertexAiRagRetrievalTool — recuperação como um adk_core::Tool, o equivalente em Rust ao VertexAiRagRetrieval de adk-python

Escopo: somente recuperação. A criação de corpora e a importação de arquivos são responsabilidades de provisionamento — use o console do Vertex AI ou o APIs de gerenciamento RagCorpora/RagFiles.

---

Instalação

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

A autenticação usa as Credenciais Padrão do Aplicativo:

gcloud auth application-default login

---

Cliente

use adk_rag::vertex_rag::{RetrieveContextsRequest, VertexRagConfig, VertexRagEngineClient};

#[tokio::main]
async fn main() -> adk_core::Result<()> {
    // Or VertexRagConfig::from_env() reading GOOGLE_CLOUD_PROJECT / GOOGLE_CLOUD_LOCATION
    let config = VertexRagConfig::new("my-project", "us-central1");
    let client = VertexRagEngineClient::new_with_adc(config)?;

    // Verify the corpus exists and has imported files; fails with
    // actionable guidance when it is missing, empty, or in ERROR state.
    let corpus = client.ensure_corpus_ready("1234567890").await?;
    println!("corpus: {:?} ({:?} files)", corpus.display_name, corpus.rag_files_count);

    // Enumerate what's in the project and the corpus.
    let corpora = client.list_corpora().await?;
    let files = client.list_rag_files("1234567890").await?;
    println!("{} corpora, {} files", corpora.len(), files.len());

    // Retrieve the most relevant passages for a query.
    let request = RetrieveContextsRequest::new("what is the refund policy?", ["1234567890"])
        .similarity_top_k(5)
        .vector_distance_threshold(0.7);
    for context in client.retrieve_contexts(&request).await? {
        println!(
            "[{:.3}] {} — {}",
            context.score.unwrap_or_default(),
            context.source_display_name.as_deref().unwrap_or("<unknown>"),
            context.text.as_deref().unwrap_or(""),
        );
    }
    Ok(())
}

Os corpora podem ser fornecidos como IDs simples (resolvidos com base no projeto e no local do cliente) ou como nomes de recursos projects/*/locations/*/ragCorpora/* completos.

Observação: similarity_top_k e vector_distance_threshold mantêm os nomes de adk-python, mas são enviados pelo caminho de comunicação atual — query.ragRetrievalConfig.topK e query.ragRetrievalConfig.filter.vectorDistanceThreshold. As grafias obsoletas v1beta1 (query.similarityTopK, vertexRagStore.vectorDistanceThreshold) foram removidas do v1 e nunca são emitidas. vector_similarity_threshold é o outro ramo, mutuamente exclusivo, do filtro.

---

Ferramenta de recuperação

VertexAiRagRetrievalTool aceita uma única string query obrigatória e retorna um array JSON de objetos {text, sourceUri, sourceDisplayName, score}. Ela informa ser somente leitura e segura para uso concorrente, portanto ToolExecutionStrategy::Auto pode despachá-la em paralelo com outras leituras.

use std::sync::Arc;
use adk_agent::LlmAgentBuilder;
use adk_model::GeminiModel;
use adk_rag::vertex_rag::{VertexAiRagRetrievalTool, VertexRagConfig, VertexRagEngineClient};

fn main() -> anyhow::Result<()> {
    let config = VertexRagConfig::new("my-project", "us-central1");
    let client = Arc::new(VertexRagEngineClient::new_with_adc(config)?);

    let retrieval = VertexAiRagRetrievalTool::new(client, vec!["1234567890".into()])
        .similarity_top_k(5)
        .vector_distance_threshold(0.7);

    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let agent = LlmAgentBuilder::new("rag-assistant")
        .description("Answers questions grounded in a Vertex AI RAG Engine corpus")
        .model(Arc::new(GeminiModel::new(&api_key, "gemini-3.7-flash")?))
        .tool(Arc::new(retrieval))
        .instruction(
            "Answer using the vertex_rag_retrieval tool. Retrieve first, then \
             answer strictly from the retrieved passages, citing sourceDisplayName.",
        )
        .build()?;
    let _ = agent;
    Ok(())
}

Consulte examples/vertex_rag para ver o agente completo executável:

cargo run --manifest-path examples/vertex_rag/Cargo.toml

---

Referência de API

Os tipos de resposta são desserializados de forma flexível — todos os campos são opcionais e os campos desconhecidos são ignorados, portanto novos campos do servidor não podem interromper a análise. Os erros carregam o componente Memory (a recuperação é o domínio da memória; AdkError não possui um componente RAG dedicado), o provedor vertex_ai e códigos rag.vertex.* legíveis por máquina.

---

Variáveis de ambiente

---

Prefere RAG auto-hospedado?

Para um pipeline executado por você — segmentadores conectáveis, provedores de embeddings e armazenamentos vetoriais (Qdrant, LanceDB, pgvector, SurrealDB) — consulte RAG.