مخزن المتجهات لاسترجاع الوكيل

إن Agent Retrieval (المعروف سابقًا باسم Vector Search 2.0) هو قاعدة بيانات متجهات مُدارة من Google على منصة Gemini Enterprise Agent Platform، ومتاح عمومًا في vectorsearch.googleapis.com. تعمل ميزة agent-retrieval في adk-rag على تنفيذ سمة [VectorStore] مقابله، ولذلك تندمج في مسار RAG الحالي تمامًا مثل الواجهات الخلفية pgvector وQdrant وLanceDB وSurrealDB.

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

البدء السريع

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

المطابقة مع المنصة

عملية السمة	استدعاء استرداد الوكيل
`create_collection`	`POST {parent}/collections` (عملية طويلة الأمد؛ `ALREADY_EXISTS` لا تنفّذ أي إجراء)
`delete_collection`	`DELETE {collection}` (عملية طويلة الأمد؛ `NOT_FOUND` لا تنفّذ أي إجراء)
`upsert`	`dataObjects:batchCreate` (≤1000، ذرّي)، مع الرجوع إلى الإنشاء ثم التصحيح لكل كائن لضمان فوز آخر كتابة
`delete`	`dataObjects:batchDelete`، مع الرجوع إلى الحذف لكل كائن عند فقدان المعرّفات
`search`	`dataObjects:search` مع استعلام `vectorSearch`

يتم تخزين نص الجزء وبياناته الوصفية في كائن البيانات إلى جانب المتجه — ولا حاجة إلى مخزن مرافق. يعمل المخزن في وضع BYOE (إحضار التضمينات الخاصة بك): تأتي التضمينات من مسار تضمين adk-rag، مما يحافظ على تطابق السلوك عبر الواجهات الخلفية. وتُعد الدرجات مسافات DOT_PRODUCT، وهي تساوي تشابه جيب التمام للتضمينات المُطبَّعة (تكون القيم الأعلى أكثر صلة).

التكوين

الخيار	التأثير
`with_collection_prefix("rag-")`	يضيف بادئة إلى كل معرّف مجموعة، مما يعزل مجموعات هذا المخزن
`with_existing_collections_only(true)`	يتحقق `create_collection` من وجود المجموعة بدلًا من إنشائها — لعمليات النشر التي تهيئها مسبقًا باستخدام أدوات المنصة
`with_endpoint(...)`	أصل API مخصص (يُسمح بـ HTTP الاسترجاع المحلي للاختبارات)

تُنقّى أسماء المجموعات إلى تسميات RFC 1035 (تُحوّل إلى أحرف صغيرة؛ وتتحول الأحرف غير الصالحة إلى واصلات)، ولذلك يصبح my_docs معرّف المجموعة my-docs. تتعارض الأسماء المميزة التي تُنقّى إلى الشكل نفسه — لذا اختر أسماء تختلف بأكثر من حالة الأحرف أو علامات الترقيم.

ما وراء السمة

بالنسبة إلى المستدعين الذين يحتفظون بـ AgentRetrievalStore الملموس، يشغّل hybrid_search استعلامًا دلاليًا واستعلامًا بالكلمات المفتاحية ضمن استدعاء dataObjects:batchSearch واحد، ويُرجع القائمة المرتبة وفق دمج الرتب التبادلية:

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

ملاحظات المنصة

المناطق: ‏Agent Retrieval إقليمي؛ وتشمل المناطق المدعومة us-central1 وus-east4 وus-west1 وeurope-north1 وeurope-west2 وeurope-west4 وasia-east1 وasia-northeast1 وasia-southeast1.
CMEK: يدعم Agent Retrieval المستقل مفاتيح التشفير المُدارة من العميل عبر encryptionSpec الخاص بالمجموعة (غير قابل للتغيير عند الإنشاء). أنشئ مجموعات CMEK مسبقًا باستخدام أدوات المنصة، واستخدم with_existing_collections_only(true).
لم يُنفّذ Vector Search 1.0 عمدًا. فنموذج البنية التحتية للفهرس/نقطة النهاية فيه لا يتلاءم جيدًا مع السمة VectorStore، وتضع Google ‏Agent Retrieval بوصفه خليفته.
الحصص: تقتصر عمليات الكتابة الدفعية على 1000 كائن لكل طلب، وتتم بصورة ذرّية؛ ويقسّم المخزن عمليات الرفع الأكبر تلقائيًا إلى أجزاء.

الاختبار

يجتاز الطرف الخلفي مجموعة اختبارات التعاقد والخصائص المشتركة VectorStore التي تشغّلها جميع الأطراف الخلفية adk-rag، ولذلك فهو قابل للتبادل سلوكيًا مع المخازن الأخرى. ينشئ الاختبار المباشر #[ignore] مجموعته ذات الاسم الفريد ويحذفها (على مستوى البيانات، مثل الاختبارات المباشرة لـ pgvector وQdrant):

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