Vertex AI RAG Engine

استرجع السياق المؤسَّس من مجموعات Vertex AI RAG Engine المُدارة — من دون الحاجة إلى مخزن متجهات مستضاف ذاتيًا أو موفّر تضمين أو مسار لإدخال البيانات.

---

ماهيته

يُعد Vertex AI RAG Engine واجهة RAG خلفية مُدارة من Google Cloud: تستورد المستندات إلى مجموعة RAG وتتولى المنصة تقسيمها إلى أجزاء وتضمينها والبحث المتجهي. توفّر ميزة vertex-rag في adk-rag ما يلي:

• VertexRagEngineClient — عميل لطبقة البيانات للقراءة فقط، موثَّق باستخدام ADC: للحصول على المجموعات وسردها، وسرد الملفات المستوردة، واسترجاع السياقات
• VertexAiRagRetrievalTool — الاسترجاع باعتباره adk_core::Tool، النظير المكتوب بلغة Rust لـ VertexAiRagRetrieval في adk-python

النطاق: الاسترجاع فقط. يُعد إنشاء المجموعات واستيراد الملفات من مهام التجهيز — استخدم وحدة تحكم Vertex AI أو APIs لإدارة RagCorpora/RagFiles.

---

التثبيت

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

تستخدم المصادقة بيانات الاعتماد الافتراضية للتطبيق:

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

يمكن تمرير المجموعات كمعرّفات مجردة (يُحلّ أمرها باستخدام مشروع العميل وموقعه) أو كأسماء موارد كاملة لـ 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 واحدة مطلوبة، وتُرجع مصفوفة JSON من كائنات {text, sourceUri, sourceDisplayName, score}. وتُعرّف نفسها بأنها للقراءة فقط وآمنة للتزامن، ولذلك يمكن لـ 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.