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

امبدینگ‌ها، اسپلیترها، پایگاه‌های برداری و رتریورها

Embeddings, splitters, vector stores, and retrievers

فهرست مطالب
  1. محل قرارگیری هر بخش
  2. پایپ‌لاین موجود در کیت ثبت
  3. اسپلیتر
  4. مدل امبدینگ
  5. پایگاه برداری
  6. رتریور در قالب یک ابزار

اینترفیس‌های بازیابی در langchain-core قرار دارند، اسپلیترها در langchain-text-splitters، هر پایگاه برداری در پکیج شریک اختصاصی خود، و دسترسی ایجنت به رتریور نیز از طریق ابزار انجام می‌شود.

فرض کنید نمونه‌کدی از بازیابی (retrieval) مربوط به سال 2024 را کپی می‌کنید. در آن کد، RetrievalQA از langchain.chains و پایگاه برداری (vector store) از langchain_community.vectorstores ایمپورت شده‌اند. ایمپورت اول در نسخه‌ی پین‌شده با خطا مواجه می‌شود و ایمپورت دوم هم متعلق به پکیجی است که منسوخ شده.

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

محل قرارگیری هر بخش

رتریور (Retriever): شیئی مجهز به متد invoke(query) که فهرستی از شیءهای Document را برمی‌گرداند. کلاس پایه‌ی آن BaseRetriever در langchain-core است.

در فضای نام نسخه‌های 0.x، لودرها، اسپلیترها، پایگاه‌ها و زنجیره‌ها همگی در یک پکیج قرار داشتند. اما در نسخه‌ی پین‌شده، در پنج جای مختلف پخش شده‌اند:

بخش پکیج در نسخه‌ی پین‌شده محتویات
Embeddings، VectorStore، BaseRetriever، Document langchain-core 1.8.0 کلاس‌های پایه، InMemoryVectorStore، DeterministicFakeEmbedding، create_retriever_tool، و API نمایه‌سازی
init_embeddings langchain 1.5.0 تبدیل رشته‌ی نام مدل، مانند openai:text-embedding-3-small، به شیء امبدینگ
اسپلیترهای متن langchain-text-splitters 1.1.3 RecursiveCharacterTextSplitter، CharacterTextSplitter، و اسپلیترهای مخصوص Markdown، HTML، کد، و JSON
پایگاه برداری واقعی یا مدل امبدینگ پکیج شریک (partner package) مانند langchain-chroma، langchain-qdrant، langchain-openai، و langchain-ollama
MultiQueryRetriever، RetrievalQA، CacheBackedEmbeddings langchain-classic 1.0.8 {{code libs/langchain/pyproject.toml}} زنجیره‌ها و رتریورهای قدیمی که صرفاً برای مهاجرت نگه داشته شده‌اند

کلاس‌های پایه در هسته (core) قرار دارند {{code libs/core/langchain_core/retrievers.py}}. کلاس InMemoryVectorStore بردارها را درون یک دیکشنری نگه می‌دارد و امتیاز آن‌ها را با شباهت کسینوسی در NumPy محاسبه می‌کند {{code libs/core/langchain_core/vectorstores/in_memory.py}}. ماژول langchain.embeddings تنها Embeddings و init_embeddings را اکسپورت می‌کند و در داک‌استرینگ آن آمده که سایر ماژول‌های امبدینگ به langchain-classic منتقل شده‌اند {{code libs/langchain_v1/langchain/embeddings/init.py}}. در یادداشت‌های انتشار نسخه‌ی v1، نام رتریورهای قدیمی هم در میان موارد منتقل‌شده دیده می‌شود {{docs oss/python/releases/langchain-v1}}.

در PyPI، نسخه‌ی 0.4.2 به‌عنوان آخرین انتشار langchain-community ثبت شده و مخزن آن نیز آرشیو شده است {{site pypi.org/project/langchain-community}}. بیشتر لودرها و پایگاه‌های برداری دوران 0.x از آنجا می‌آمدند. پکیج‌های Chroma و Qdrant درون مخزن اصلی و زیرمسیر libs/partners قرار دارند و هرکدام نسخه‌بندی خودشان را دارند. برای هر پایگاه برداری دیگری، قبل از اینکه به سراغ پکیج community بروید، بررسی کنید که آیا پکیج شریک برای آن وجود دارد یا خیر.

در مستندات، درون تب LangChain صفحه‌ای برای retrieval وجود ندارد. گزینه‌ی Retrieval در منوی ناوبری، صفحه‌ی Deep Agents را باز می‌کند {{docs oss/python/deepagents/retrieval}}. آن صفحه به دو سبک اشاره می‌کند: مرحله‌ی ثابتِ «اول بازیابی بعد پاسخ»، و حالتی که ایجنت خودش تصمیم می‌گیرد چه زمانی جستجو کند. آموزش جستجوی معنایی، پایپ‌لاین این بخش را گام‌به‌گام می‌سازد {{docs oss/python/langchain/knowledge-base}}.

پایپ‌لاین موجود در کیت ثبت

تصویر پایپ‌لاین این کیت را نشان می‌دهد. این پایپ‌لاین در زمان نمایه‌سازی (index time) یک‌بار اجرا می‌شود و ایجنت در زمان پرس‌وجو (query time) در هر فراخوانی ابزار از آن استفاده می‌کند.

زمان ایندکس و زمان کوئری در ضبط بازیابیسه فایل یک‌بار به هفت چانک و هفت بردار تبدیل می‌شوند، سپس هر فراخوانی search_docs از یک رتریور استعلام می‌گیرد که همان ذخیره‌ساز درون‌حافظه‌ای را جستجو می‌کند.
زمان ایندکس و زمان کوئری در ضبط بازیابی دو ردیف. در زمان ایندکس، سه فایل Markdown به RecursiveCharacterTextSplitter از langchain-text-splitters داده می‌شوند که 7 چانک با حداکثر 80 کاراکتر می‌سازد. OllamaEmbeddings از langchain-ollama با مدل nomic-embed-text هر چانک را به 768 عدد تبدیل می‌کند و InMemoryVectorStore از langchain-core آن‌ها را به‌صورت doc-0 تا doc-6 نگه می‌دارد. در زمان کوئری، تابع create_agent از مدل می‌پرسد، مدل ابزار search_docs را فراخوانی می‌کند، ابزار رتریور حاصل از as_retriever با مقدار k برابر 1 را صدا می‌زند، رتریور ذخیره‌ساز را جستجو می‌کند، و پیام ToolMessage چانک doc-0 را به مدل بازمی‌گرداند که با «[checkpoints.md] A checkpointer saves graph state after each step.» آغاز می‌شود. زمان ایندکس: یک‌بار 3 فایل checkpoints.md و دو تای دیگر TextSplitter Recursive، اندازه 80 7 چانک امبدینگ nomic-embed-text هر کدام 768 عدد vector store InMemory doc-0 تا doc-6 langchain-text-splitters langchain-ollama langchain-core زمان کوئری: هر فراخوانی ابزار create_agent نود model نود tools search_docs یک tool@ آرگومان: query رتریور as_retriever k=1 search شروع ToolMessage برگشتی به مدل: [checkpoints.md] A checkpointer saves graph state after each step. مدل nomic-embed-text روی Ollama چانک 0 از 7 را برای پرسش مدل انتخاب کرد.
ردیف بالا را از چپ به راست برای زمان ایندکس بخوانید، سپس ردیف پایین را برای یک فراخوانی ابزار دنبال کنید. پکیج مربوط به هر بخش زیر کادر آن نوشته شده است. برگرفته از capture/out/39-retrieval.txt و capture/s_integrations.py.

اسپلیتر

اسپلیتر متن (Text splitter): شیئی که سند را به تکه‌هایی (chunks) با حداکثر chunk_size نویسه خرد می‌کند، به‌طوری که chunk_overlap نویسه میان دو تکه تکرار شود.

کلاس RecursiveCharacterTextSplitter ابتدا تلاش می‌کند برش را در محل شکست پاراگراف‌ها بزند، سپس در شکست سطرها، و در نهایت روی فاصله‌ها. این کیت، سه فایل کوتاه را با اندازه‌ی 80 و همپوشانی 20 برش می‌دهد:

دو چانک اول از checkpoints.md capture/out/39-retrieval.txt
  {
    "source": "checkpoints.md",
    "chars": 77,
    "text": "A checkpointer saves graph state after each step. InMemorySaver keeps it in a"
  },
  {
    "source": "checkpoints.md",
    "chars": 75,
    "text": "keeps it in a dict. SqliteSaver writes it to a file, so a thread survives a"
  },

دو چانک از میان هفت چانک. همپوشانی شامل کلمات keeps it in a است.

اسپلیتر متن را روی یک فاصله برش می‌زند؛ بنابراین انتهای یک تکه در میانه‌ی جمله قرار می‌گیرد. تکه‌ی اول روی in a تمام می‌شود و تکه‌ی بعدی همین کلمات را تکرار می‌کند. هر تکه متادیتای source مربوط به فایل خود را حفظ می‌کند، زیرا کیت آن را به create_documents ارسال کرده است.

مدل امبدینگ

مدل امبدینگ (Embedding model): شیئی مجهز به متدهای embed_query و embed_documents که متن را به برداری از اعداد تبدیل می‌کند.

این کیت از OllamaEmbeddings(model="nomic-embed-text") موجود در پکیج langchain-ollama استفاده می‌کند که روی سرور Ollama در سیستم‌عامل مهمان x86 سرور اجرا می‌شود. مدل امبدینگ یک مدل واقعی است؛ از این رو فایل‌هایی که از آن استفاده می‌کنند فایل‌های ثبت‌شده به‌شمار می‌روند و نام مدل در سطر زیر عنوان آن‌ها درج شده است.

یک بردار از nomic-embed-text capture/out/39-retrieval.txt
{
  "dims": 768,
  "first 4": [
    0.051004,
    -0.024986,
    -0.178736,
    0.040572
  ],
  "repeat equal": true,
  "other text equal": false
}

هر بردار شامل 768 عدد است. در طول اجرا، یک متن یکسان دو بار بردار یکسانی تولید کرد و متن دیگر بردار متفاوتی داد. اسکریپت run.py --check این اعداد را مقایسه نمی‌کند، چون یک مدل آن‌ها را ساخته است؛ بلکه فقط بررسی می‌کند که فایل شامل سطر نام مدل و رشته‌های مشخص‌شده در expect.py باشد.

پایگاه برداری

متد add_documents همراه با شناسه‌های صریح، هفت تکه متن را به‌صورت doc-0 تا doc-6 ذخیره می‌کند. متد similarity_search_with_score جفت‌هایی شامل سند و امتیاز برمی‌گرداند. اگر پرسمان دقیقاً متن یک تکه باشد، امتیاز 1.0 را می‌گیرد:

یک جستجو با متن دقیق چانک اول capture/out/39-retrieval.txt
query 'A checkpointer saves graph state after each step. InMemorySaver keeps it in a':
[
  {
    "id": "doc-0",
    "source": "checkpoints.md",
    "score": 1.0,
…

خط کوئری، سپس اولین نتیجه. نتیجه‌ی دوم حذف شده است.

نتیجه‌ی بعدی، یعنی doc-2، امتیاز 0.556317 را به دست آورد که آخرین تکه‌ی همان فایل است. پرسمانی با کلمات دیگر، مانند Where does long-term memory live?، تکه‌ی doc-3 (اولین تکه‌ی stores.md) را با امتیاز 0.683653، و doc-1 از فایل checkpoints.md را با امتیاز 0.455558 برگرداند. پرسمان What does a checkpointer do? نیز doc-0 را با امتیاز 0.68785 و doc-2 را با 0.507239 برگرداند.

کلاس InMemoryVectorStore یک تابع پایتون را به‌عنوان filter می‌پذیرد. کیت با اعمال فیلتر فقط تکه‌های مربوط به stores.md را نگه داشت و doc-3 و doc-4 را دریافت کرد. اما پایگاه‌های شریک نحو فیلترنویسی خاص خود را دارند؛ به همین دلیل فیلتر از یک پایگاه به پایگاه دیگر منتقل نمی‌شود. متد delete(["doc-0"]) تکه‌ی اول را حذف کرد و پس از آن متد get_by_ids فقط doc-1 را برگرداند. اجرای max_marginal_relevance_search برای memory نیز doc-3 و doc-2 را برگرداند.

رتریور در قالب یک ابزار

رتریور پایگاه برداری (Vector store retriever): رتریوری که متد as_retriever() برمی‌گرداند. این رتریور با آرگومان‌های search_kwargs که به آن داده‌اید، یک‌بار جستجو روی پایگاه برداری را اجرا می‌کند.

تابع create_agent پارامتری برای بازیابی ندارد. شما یک ابزار به ایجنت می‌دهید و آن ابزار، رتریور را فراخوانی می‌کند. این کیت، رتریور را درون یک @tool ساده می‌پیچد:

رتریور و ابزار capture/s_integrations.py
    retriever = store.as_retriever(search_kwargs={"k": 1})

    @tool
    def search_docs(query: str) -> str:
        """Search the local corpus."""
        return "\n".join(f"[{d.metadata['source']}] {d.page_content}" for d in retriever.invoke(query))

کیت از مدل Qwen3 4B پرسید: What does a checkpointer do?. مدل یک‌بار search_docs را با همان پرسش فراخوانی کرد و ابزار نیز یک تکه متن را همراه با منبع آن داخل براکت برگرداند:

فراخوانی ابزار و نتیجه‌ی آن capture/out/47-retrieval-agent.txt
    "type": "ToolMessage",
    "content": "[checkpoints.md] A checkpointer saves graph state after each step. InMemorySaver keeps it in a",
    "name": "search_docs",
    "id": "<uuid-3>",
    "tool_call_id": "<uuid-2>",
    "status": "success"

تنها ToolMessage. فراخوانی مدل قبل از آن و پاسخ پس از آن حذف شده‌اند.

رتریور تکه‌ی 0 از 7 را برگرداند که اولین تکه‌ی فایل checkpoints.md است و پاسخ سؤال را در خود دارد. مدل بر اساس همان پاسخ داد: A checkpointer saves the graph state after each step. For example, the InMemorySaver keeps the state in memory.. با تنظیم k=1، مدل تنها یک تکه متن را دید. این تکه روی keeps it in a قطع می‌شود، و کلمات dict و SqliteSaver در doc-1 قرار دارند که در اختیار مدل گذاشته نشد. بنابراین پاسخ مدل درست است، اما فقط به اندازه‌ی همان یک تکه کامل است.

منبع را درون متن نتیجه قرار دهید. مدل فقط محتوای ToolMessage را می‌بیند؛ بنابراین تنها زمانی می‌تواند به یک فایل استناد کند که ابزار نام آن را درون متن نوشته باشد. پکیج Core تابعی به نام create_retriever_tool نیز دارد که دقیقاً همین نوع ابزار را از روی یک رتریور، یک نام و یک توضیحات می‌سازد {{code libs/core/langchain_core/tools/retriever.py}}. با تنظیم response_format="content_and_artifact"، اسناد را در قالب دست‌سازه (artifact) پیام نیز نگه می‌دارد.

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

منابع: capture/s_integrations.py، capture/out/39-retrieval.txt، capture/out/47-retrieval-agent.txt؛ libs/core/langchain_core/retrievers.py، libs/core/langchain_core/vectorstores/in_memory.py، libs/core/langchain_core/vectorstores/base.py، libs/core/langchain_core/tools/retriever.py، libs/langchain_v1/langchain/embeddings/init.py، و libs/partners در langchain==1.5.0؛ libs/partners/ollama/langchain_ollama/embeddings.py در langchain-ollama 1.1.0؛ docs.langchain.com در commit مستندات 04d4d4a (oss/python/releases/langchain-v1، oss/python/deepagents/retrieval، oss/python/langchain/knowledge-base)؛ مخزن آرشیوشده‌ی langchain-community، خوانده‌شده در 2026-11-14.