بخش 7.2 · اکوسیستم

ساخت ایجنت بازیابی روی یک پیکره متنی محلی

A retrieval agent over a local corpus

فهرست مطالب
  1. دموی این درس چه می‌سازد
  2. پایپ‌لاین
  3. اجرای ثبت‌شده
  4. تحلیل نتایج ارزیابی

یک ایجنت بازیابی (Retrieval agent) دو بخش مجزا دارد که هرکدام ممکن است جداگانه خراب شوند: بازیاب (Retriever) یا قطعه‌متن درست را پیدا می‌کند یا نه، و مدل یا بازیاب را صدا می‌زند یا نه؛ پس عملکرد هر بخش را جداگانه ارزیابی کنید.

تیم شما می‌خواهد پاسخ سوال‌هایش را از دل اسناد داخلی خودش بگیرد و منبع هر ادعا دقیقاً با نام فایل مشخص شود. یک پایگاه داده برداری (Vector store) راه می‌اندازید و ابزار جستجو را در اختیار ایجنت می‌گذارید. پاسخ‌های اولیه خوب به نظر می‌رسند. اما ناگهان کاربری سوالی می‌پرسد که پاسخش کلمه‌به‌کلمه در یکی از اسناد آمده است، ولی ایجنت می‌گوید اسناد پاسخی برای آن ندارند.

با اتمام این بخش، می‌توانید یک ایجنت بازیابی را با یک مدل امبدینگ محلی بسازید و منبع هر پاسخ را ثبت کنید. همچنین می‌توانید مشخص کنید که یک پاسخ نادرست، از بازیاب سرچشمه گرفته یا تقصیر مدل بوده است.

دموی این درس چه می‌سازد

پیکره متنی (Corpus) این دمو شامل 6 فایل درسی از همین مخزن است که موضوعاتی مثل امبدینگ، RAG، LangGraph، فریم‌ورک‌های ایجنت و اجرای پایدار (Durable Execution) را پوشش می‌دهند؛ یعنی در مجموع حدود 89,600 کاراکتر. از آنجا که این مخزن مجوز MIT دارد، دمو فایل‌ها را مستقیماً از جای اصلی‌شان می‌خواند و هش SHA-256 آن‌ها را ثبت می‌کند.

این دمو مباحث بخش‌های زیر را پیاده‌سازی می‌کند:

پایپ‌لاین

مدل nomic-embed-text برای هر متن یک پیشوند وظیفه (Task prefix) می‌خواهد: search_document: برای قطعه‌متن‌های اسناد و search_query: برای سوالات. کلاس OllamaEmbeddings متن‌ها را به محض دریافت و بدون تغییر می‌فرستد {{code langchain_ollama/embeddings.py}}، بنابراین در این دمو یک کلاس پوششی (Wrapper) دور آن می‌نویسیم:

پوشش‌دهنده‌ی امبدینگ (embedding wrapper) capture/demos/retrieval-agent/retrieval_agent.py
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) به پیام متصل می‌مانند تا اسکریپت بتواند ارجاعات را با نتایج واقعی جستجو تطبیق دهد:

بازیاب در نقش یک ابزار capture/demos/retrieval-agent/retrieval_agent.py
    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 جستجو کرد، پاسخ داد و به همان فایل ارجاع داد:

یک پرسش، Qwen3 8B capture/lab/retrieval-agent/run-8b.log
== 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 نتیجه‌ی برتر را دریافت کرد، چرا که عملکرد بازیاب به مدل گفت‌وگو وابسته نیست. با این حال، این مدل اصلاً ابزار را صدا نزد:

همان پرسش، Qwen3 4B capture/lab/retrieval-agent/run-4b.log
== 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.

ترجمه‌ی فارسی A retrieval agent over a local corpus از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما