Vertex AI RAG Engine

관리형 Vertex AI RAG Engine 코퍼스에서 기반 컨텍스트를 검색합니다. 자체 호스팅 벡터 저장소, 임베딩 제공자 또는 수집 파이프라인이 필요하지 않습니다.

---

개요

Vertex AI RAG Engine은 Google Cloud의 관리형 RAG 백엔드입니다. 문서를 RAG 코퍼스로 가져오면 플랫폼이 청킹, 임베딩 및 벡터 검색을 처리합니다. adk-rag의 vertex-rag 기능은 다음을 제공합니다.

• VertexRagEngineClient — ADC 인증을 사용하는 읽기 전용 데이터 플레인 클라이언트로, 코퍼스 가져오기/목록 조회, 가져온 파일 목록 조회 및 컨텍스트 검색을 지원합니다.
• VertexAiRagRetrievalTool — adk_core::Tool로서의 검색 기능으로, adk-python의 VertexAiRagRetrieval에 해당하는 Rust 구현입니다.

범위: 검색만 지원합니다. 코퍼스 생성 및 파일 가져오기는 프로비저닝 작업이므로 Vertex AI 콘솔 또는 RagCorpora/RagFiles 관리 APIs을 사용하십시오.

---

설치

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

인증에는 Application Default Credentials를 사용합니다.

gcloud auth application-default login

---

클라이언트

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(())
}

코퍼스는 단순 ID로 전달할 수 있으며(클라이언트의 프로젝트와 위치를 기준으로 확인됨), 전체 projects/*/locations/*/ragCorpora/* 리소스 이름으로도 전달할 수 있습니다.

참고: similarity_top_k 및 vector_distance_threshold는 adk-python의 이름을 유지하지만 현재 와이어 경로인 query.ragRetrievalConfig.topK 및 query.ragRetrievalConfig.filter.vectorDistanceThreshold로 전송됩니다. 더 이상 사용되지 않는 v1beta1 표기인 query.similarityTopK, vertexRagStore.vectorDistanceThreshold는 v1에서 제거되었으며 절대 생성되지 않습니다. vector_similarity_threshold은 필터의 다른 상호 배타적 분기입니다.

---

검색 도구

VertexAiRagRetrievalTool은 필수 query 문자열 하나를 받아 {text, sourceUri, sourceDisplayName, score} 객체의 JSON 배열을 반환합니다. 이 도구는 자체적으로 읽기 전용이며 동시성에 안전하다고 보고하므로, ToolExecutionStrategy::Auto는 다른 읽기 작업과 병렬로 이를 디스패치할 수 있습니다.

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(())
}

전체 실행 가능한 에이전트는 examples/vertex_rag를 참조하십시오.

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

---

API 참조

응답 유형은 관대하게 역직렬화됩니다. 모든 필드는 선택 사항이며 알 수 없는 필드는 무시되므로 새 서버 필드가 파싱을 중단시키지 않습니다. 오류에는 구성 요소 Memory(검색은 메모리 도메인에 해당하며, AdkError에는 전용 RAG 구성 요소가 없음), 제공자 vertex_ai, 그리고 기계 판독 가능한 rag.vertex.* 코드가 포함됩니다.

---

환경 변수

---

대신 자체 호스팅 RAG을 사용하시겠습니까?

직접 실행하는 파이프라인—플러그형 청커, 임베딩 제공자 및 벡터 저장소(Qdrant, LanceDB, pgvector, SurrealDB)—에 대해서는 RAG를 참조하세요.