یک ایجنت بازیابی (Retrieval agent) دو بخش مجزا دارد که هرکدام ممکن است جداگانه خراب شوند: بازیاب (Retriever) یا قطعهمتن درست را پیدا میکند یا نه، و مدل یا بازیاب را صدا میزند یا نه؛ پس عملکرد هر بخش را جداگانه ارزیابی کنید.
تیم شما میخواهد پاسخ سوالهایش را از دل اسناد داخلی خودش بگیرد و منبع هر ادعا دقیقاً با نام فایل مشخص شود. یک پایگاه داده برداری (Vector store) راه میاندازید و ابزار جستجو را در اختیار ایجنت میگذارید. پاسخهای اولیه خوب به نظر میرسند. اما ناگهان کاربری سوالی میپرسد که پاسخش کلمهبهکلمه در یکی از اسناد آمده است، ولی ایجنت میگوید اسناد پاسخی برای آن ندارند.
با اتمام این بخش، میتوانید یک ایجنت بازیابی را با یک مدل امبدینگ محلی بسازید و منبع هر پاسخ را ثبت کنید. همچنین میتوانید مشخص کنید که یک پاسخ نادرست، از بازیاب سرچشمه گرفته یا تقصیر مدل بوده است.
دموی این درس چه میسازد
پیکره متنی (Corpus) این دمو شامل 6 فایل درسی از همین مخزن است که موضوعاتی مثل امبدینگ، RAG، LangGraph، فریمورکهای ایجنت و اجرای پایدار (Durable Execution) را پوشش میدهند؛ یعنی در مجموع حدود 89,600 کاراکتر. از آنجا که این مخزن مجوز MIT دارد، دمو فایلها را مستقیماً از جای اصلیشان میخواند و هش SHA-256 آنها را ثبت میکند.
این دمو مباحث بخشهای زیر را پیادهسازی میکند:
- امبدینگها، بخشبندیکنندهها، پایگاههای برداری و بازیابها: بخشبندیکننده (Splitter)، پایگاه برداری و
create_retriever_tool. - ابزارها، ToolRuntime و خطاهای ابزار: مدل فقط محتوای درون
ToolMessageرا میبیند؛ بنابراین مسیر فایل منبع باید درون همین متن قرار بگیرد. - پرامپت سیستم: قاعدهای برای ارجاع دقیق به ازای هر ادعا، و اعلام صریح وقتی که درسها پاسخی برای سوال ندارند.
پایپلاین
مدل nomic-embed-text برای هر متن یک پیشوند وظیفه (Task prefix) میخواهد: search_document: برای قطعهمتنهای اسناد و search_query: برای سوالات. کلاس OllamaEmbeddings متنها را به محض دریافت و بدون تغییر میفرستد {{code langchain_ollama/embeddings.py}}، بنابراین در این دمو یک کلاس پوششی (Wrapper) دور آن مینویسیم:
class NomicEmbeddings(Embeddings):
def __init__(self, model="nomic-embed-text"):
self.inner = OllamaEmbeddings(model=model)
def embed_documents(self, texts):
return self.inner.embed_documents([f"search_document: {t}" for t in texts])
def embed_query(self, text):
return self.inner.embed_query(f"search_query: {text}")بخشبندیکننده، فایلها را به تکههای حداکثر 1,000 کاراکتری با 150 کاراکتر همپوشانی (Overlap) تقسیم میکند. آرگومان add_start_index=True موقعیت مکانی شروع هر تکه را نگه میدارد تا هر نتیجه، جایگاه مشخصی در فایل داشته باشد. پایگاه داده برداری از نوع InMemoryVectorStore است که با هر بار اجرا از نو ساخته میشود.
ابزار جستجو با create_retriever_tool ساخته میشود. پرامپت سند در این ابزار، مسیر فایل را داخل براکت و درست قبل از هر قطعهمتن قرار میدهد. با تنظیم content_and_artifact، اسناد به عنوان دستسازه (Artifact) به پیام متصل میمانند تا اسکریپت بتواند ارجاعات را با نتایج واقعی جستجو تطبیق دهد:
retriever = store.as_retriever(search_kwargs={"k": 4})
search = create_retriever_tool(
retriever,
"search_lessons",
"Search the engineering lessons. Returns the four best passages, each with its source path.",
document_prompt=PromptTemplate.from_template("[{source}]\n{page_content}"),
response_format="content_and_artifact",
)
agent = create_agent(model(), tools=[search], system_prompt=SYSTEM_PROMPT)اسکریپت پیش از هر بار اجرای ایجنت، خودش پایگاه داده برداری را جستجو کرده و 4 نتیجهی برتر را چاپ میکند. این خط عملکرد بازیاب را بهتنهایی نشان میدهد؛ فارغ از اینکه مدل بعداً چه تصمیمی بگیرد.
اجرای ثبتشده
در این دمو 5 سوال مطرح میشود. 4 سوال در فایلهای درسی پاسخ مشخص دارند و یک سوال (دربارهی اینکه چه مدلی از GPU را بخریم) در اسناد نیست. این آزمون یک بار با مدل Qwen3 4B و یک بار با Qwen3 8B اجرا میشود.
مرحلهی بخشبندی 122 تکهمتن تولید کرد و فرایند امبدینگ آنها 2.2 ثانیه طول کشید. برای سوال مربوط به امبدینگهای ماتریوشکا (Matryoshka embeddings)، اولین نتیجهی جستجو دقیقاً فایل درست بود. مدل Qwen3 8B جستجو کرد، پاسخ داد و به همان فایل ارجاع داد:
== matryoshka: How much storage does Matryoshka truncation from 1536 to 256 dimensions save, and what does it cost in accuracy?
top-4 0.791 phases/11-llm-engineering/04-embeddings/docs/en.md @ 12305
top-4 0.664 phases/11-llm-engineering/06-rag/docs/en.md @ 4675
top-4 0.658 phases/11-llm-engineering/04-embeddings/docs/en.md @ 21476
top-4 0.654 phases/11-llm-engineering/04-embeddings/docs/en.md @ 12982
search Matryoshka truncation from 1536 to 256 dimensions
returned 11-llm-engineering/04-embeddings, 11-llm-engineering/06-rag, 11-llm-engineering/04-embeddings, 11-llm-engineering/04-embeddings
answer Requesting 256 dimensions instead of 1536 cuts storage by 6x with roughly 3-5% accuracy loss on MTEB benchmarks [phases/11-llm-engineering/04-embeddings/docs/en.md].
cited phases/11-llm-engineering/04-embeddings/docs/en.md
check cited an expected source: True; every citation was returned by a search: True
model calls 2, prompt tokens 1802, 10.3 sمدل Qwen3 4B هم دقیقاً همان 4 نتیجهی برتر را دریافت کرد، چرا که عملکرد بازیاب به مدل گفتوگو وابسته نیست. با این حال، این مدل اصلاً ابزار را صدا نزد:
== matryoshka: How much storage does Matryoshka truncation from 1536 to 256 dimensions save, and what does it cost in accuracy?
…
answer The lessons do not cover the topic of Matryoshka truncation, storage savings, or accuracy costs. Therefore, the lessons do not cover it [none].
cited nothing
check cited an expected source: False; every citation was returned by a search: True
model calls 1, prompt tokens 291, 0.9 sچهار نتیجهی برتر حذف شدهاند؛ آنها مشابه نتایج اجرای Qwen3 8B هستند.
تحلیل نتایج ارزیابی
دادههای ارزیابی از یک بار اجرای هر مدل روی سیستم Mac (با مشخصات Apple M1 Max، پردازندهی 10 هستهای، 64 گیگابایت حافظه، نرمافزار Ollama 0.31.1 و 5 سوال به ازای هر مدل) به دست آمده است.
| سوال | نتیجهی اول، فایل درست است؟ | Qwen3 4B | Qwen3 8B |
|---|---|---|---|
| فیلدی بدون کاهنده | بله | بدون جستجو؛ اعلام کرد پوشش داده نشده | بدون جستجو؛ اعلام کرد پوشش داده نشده |
| کوتاهسازی ماتریوشکا | بله | بدون جستجو؛ اعلام کرد پوشش داده نشده | جستجو کرد و به فایل درست ارجاع داد |
| افت قابلیت اطمینان | بله | بدون جستجو؛ اعلام کرد پوشش داده نشده | جستجو کرد و به فایل درست ارجاع داد |
| کلید یک چکپوینت | بله | بدون جستجو؛ اعلام کرد پوشش داده نشده | جستجو کرد و به فایل درست ارجاع داد |
| کدام GPU را بخریم | در پیکره متنی نیست | اعلام کرد پوشش داده نشده | اعلام کرد پوشش داده نشده |
بازیاب برای هر 4 سوالی که پاسخی در پیکره متنی داشتند، فایل درست را در رتبهی اول برگرداند. بنابراین تمام خطاهای رخداده از خروجیهای خود مدل است. مدل Qwen3 4B به تمام سوالات صرفاً بر اساس خوانش خودش از متن پرامپت پاسخ داد و هرگز search_lessons را فراخوانی نکرد. مدل Qwen3 8B فقط یک بار، آن هم روی سوال مربوط به کاهنده، از جستجو صرفنظر کرد. از طرفی، تمام ارجاعاتی که هر دو مدل ثبت کردند، فایلهایی بودند که جستجو در همان نوبت برگردانده بود.
بنابراین هر وقت پاسخی ادعا کرد که اسناد موضوع سوال را پوشش نمیدهند، قبل از دستکاری و بهینهسازی بازیاب، ردگیری محاسبات (Trace) را چک کنید تا ببینید آیا فراخوانی ابزار (Tool call) انجام شده یا نه. اجرایی بدون جستجو، مشکل مدل است؛ اما اجرایی با جستجو و قطعهمتنهای نادرست، به بازیاب برمیگردد.
منابع: capture/demos/retrieval-agent/retrieval_agent.py، capture/demos/retrieval-agent/run.sh، capture/demos/retrieval-agent/README.md؛ capture/lab/retrieval-agent/run-4b.log، capture/lab/retrieval-agent/run-8b.log، capture/lab/retrieval-agent/run-4b.jsonl، capture/lab/retrieval-agent/run-8b.jsonl، capture/lab/retrieval-agent/corpus.txt، capture/lab/summary/demos-mac.json؛ libs/core/langchain_core/tools/retriever.py در langchain-core 1.8.0؛ langchain_ollama/embeddings.py در langchain-ollama 1.1.0.