اگر مدل زبانی‌ات فقط از حافظه عمومی جواب می‌دهد و به اسناد شرکت یا جزوه‌های خودت دسترسی ندارد، دیر یا زود دچار توهم می‌شود. ترکیب RAG با LangChain و Chroma دقیقاً همین خلأ را پر می‌کند: اسنادت را به بردار تبدیل می‌کنی، در یک پایگاه برداری ذخیره می‌کنی و هنگام هر سؤال، مرتبط‌ترین تکه‌ها را به مدل می‌دهی تا پاسخی دقیق، مستند و به‌روز تولید کند. این مقاله همان مسیر را قدم‌به‌قدم، با کد قابل اجرا، روی پایتون جلو می‌برد.

ساخت RAG هوشمند با LangChain و Chroma چیست و چطور کار می‌کند؟

ساخت RAG هوشمند با LangChain و Chroma یعنی اتصال مدل زبانی به دانش خصوصی‌ات از طریق جستجوی معنایی. متن‌ها را تکه‌تکه می‌کنی، با مدل امبدینگ به بردار تبدیل می‌کنی، در Chroma ذخیره می‌کنی و هنگام پرسش، نزدیک‌ترین تکه‌ها را بازیابی و به پرامپت اضافه می‌کنی تا پاسخ مستند باشد. در ادامه نصب، کدنویسی و بهینه‌سازی را کامل می‌بینی.

فهرست مطالب

پیش‌نیازها و نصب ابزارهای RAG
معماری RAG به زبان ساده
گام اول: بارگذاری و تکه‌تکه کردن داده‌ها
گام دوم: ساخت بردارها و ذخیره در Chroma
گام سوم: بازیابی هوشمند و تولید پاسخ
مقایسه Chroma با پایگاه‌های برداری دیگر
اشتباهات رایج در ساخت RAG
سوالات متداول
جمع‌بندی

پیش‌نیازها و نصب ابزارهای RAG

برای این آموزش به پایتون 3.10 به بالا، یک محیط مجازی تمیز و یک کلید OpenAI یا هر سرویس امبدینگ سازگار نیاز داری. LangChain چارچوب ارکستراسیون است، Chroma پایگاه برداری سبک و سریع برای نمونه‌سازی لوکال، و مدل امبدینگ پل بین متن و فضای برداری. اگر قبلاً با مدیریت وابستگی‌ها کار کرده‌ای، تجربه آموزش Poetry در پایتون به نظم پروژه‌ات کمک می‌کند، ولی اجباری نیست.

نصب LangChain، Chroma و OpenAI

محیط مجازی را بساز و بسته‌ها را نصب کن. نسخه‌های زیر در بهار ۱۴۰۵ تست شده و با هم سازگارند. اگر از pip استفاده می‌کنی، بهتر است ابتدا pip را به‌روزرسانی کنی.

python -m venv venv
# ویندوز
venv\Scripts\activate
# مک/لینوکس
# source venv/bin/activate

pip install -U pip
pip install langchain langchain-community langchain-openai chromadb openai pypdf tiktoken

نکته: langchain-openai برای امبدینگ و چت، chromadb برای ذخیره بردارها، و pypdf برای خواندن PDF استفاده می‌شود. اگر می‌خواهی همه‌چیز آفلاین بماند، می‌توانی به‌جای OpenAI از sentence-transformers با مدل all-MiniLM-L6-v2 استفاده کنی.

دریافت کلید API و تنظیم متغیر محیطی

کلید را هرگز در کد هاردکد نکن. در ریشه پروژه یک فایل .env بساز:

OPENAI_API_KEY=sk-proj-...your_key...

سپس در پایتون آن را بخوان:

import os
from dotenv import load_dotenv

load_dotenv()
os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY")

اگر کلید را در سیستم‌عامل ست کرده‌ای، همین بخش را رد شو. برای دیباگ، چاپ len(os.getenv("OPENAI_API_KEY","")) کافی است تا مطمئن شوی خالی نیست.

معماری RAG به زبان ساده

RAG مخفف Retrieval-Augmented Generation است: «بازیابی، بعد تولید». به‌جای اینکه مدل را فاین‌تیون کنی، دانش را بیرون مدل نگه می‌داری. هنگام پرسش، سیستم نزدیک‌ترین تکه‌های مرتبط را از Chroma پیدا می‌کند، آن‌ها را در قالب «زمینه» به پرامپت اضافه می‌کند و مدل پاسخ را فقط بر اساس همان زمینه می‌سازد. نتیجه: به‌روزرسانی دانش بدون آموزش مجدد، هزینه کمتر و منبع‌پذیری.

از Embedding تا Vector Store

هر پاراگراف به یک بردار چندصد بعدی تبدیل می‌شود؛ فاصله کسینوسی بین بردارها نشان می‌دهد دو متن چقدر از نظر معنایی نزدیک‌اند. Chroma این بردارها را همراه متادیتا مثل نام فایل و شماره صفحه ذخیره می‌کند. ترفند مهم این است که تکه‌ها را معنادار ببری نه مکانیکی: ۵۰۰ تا ۸۰۰ توکن با هم‌پوشانی ۱۰۰ توکن معمولاً تعادل خوبی بین دقت و هزینه ایجاد می‌کند.

from langchain_text_splitters import RecursiveCharacterTextSplitter

splitter = RecursiveCharacterTextSplitter(
    chunk_size=700,
    chunk_overlap=100,
    separators=["\n\n", "\n", "。", "؛", " ", ""]
)
chunks = splitter.split_documents(docs)
print(f"تعداد تکه‌ها: {len(chunks)}")

گام اول: بارگذاری و تکه‌تکه کردن داده‌ها

هر RAG خوب از داده تمیز شروع می‌شود. فرض کن پوشه‌ای به نام data/ داری که شامل PDF، Markdown و فایل‌های متنی است. LangChain لودرهای آماده دارد:

from langchain_community.document_loaders import DirectoryLoader, PyPDFLoader, TextLoader

loader_pdf = DirectoryLoader("data", glob="**/*.pdf", loader_cls=PyPDFLoader)
loader_txt = DirectoryLoader("data", glob="**/*.txt", loader_cls=TextLoader)

docs = loader_pdf.load() + loader_txt.load()
print(f"تعداد اسناد خام: {len(docs)}")
for d in docs[:2]:
    print(d.metadata, d.page_content[:200])

بعد از بارگذاری، نویز را بگیر: هدر/فوتر تکراری، شماره صفحات و فاصله‌های اضافی را حذف کن. سپس اسپلیتر بالا را اعمال کن. نکته حرفه‌ای: متادیتای هر تکه را نگه دار (نام فایل، صفحه، تاریخ) تا در پاسخ بتوانی ارجاع بدهی: «بر اساس صفحه ۱۲ گزارش فروش».

اگر اسناد وب‌محور داری، می‌توانی از WebBaseLoader هم استفاده کنی، ولی برای شروع همین دو لودر کافی است.

گام دوم: ساخت بردارها و ذخیره در Chroma

حالا هر تکه را به بردار تبدیل و در Chroma ذخیره می‌کنیم. این مرحله یک‌بار اجرا می‌شود و بعد می‌توانی فقط تکه‌های جدید را اضافه کنی.

from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import Chroma

embeddings = OpenAIEmbeddings(model="text-embedding-3-small")

vectorstore = Chroma.from_documents(
    documents=chunks,
    embedding=embeddings,
    persist_directory="./chroma_db",
    collection_name="my_knowledge"
)
vectorstore.persist()
print("بردارها ذخیره شدند. تعداد:", vectorstore._collection.count())

اگر می‌خواهی آفلاین باشی:

# جایگزین آفلاین
from langchain_community.embeddings import HuggingFaceEmbeddings
embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-MiniLM-L6-v2")

برای بارگذاری مجدد در اجرای بعدی:

vectorstore = Chroma(
    persist_directory="./chroma_db",
    embedding_function=embeddings,
    collection_name="my_knowledge"
)

وقتی داده جدید اضافه شد، فقط همان تکه‌ها را add_documents کن تا کل پایگاه را از نو نسازی.

گام سوم: بازیابی هوشمند و تولید پاسخ

قلب RAG همین‌جاست: سؤال کاربر را بگیر، ۴ تا ۶ تکه مرتبط را بازیابی کن، آن‌ها را به پرامپت تزریق کن و از مدل بخواه فقط بر اساس همان زمینه جواب دهد.

from langchain_openai import ChatOpenAI
from langchain.chains import RetrievalQA
from langchain.prompts import PromptTemplate

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.2)

template = """تو یک دستیار دقیق هستی. فقط بر اساس زمینه زیر پاسخ بده.
اگر پاسخ در زمینه نیست، بگو «در اسناد یافت نشد».

زمینه:
{context}

سؤال: {question}
پاسخ مستند و کوتاه:"""

prompt = PromptTemplate(template=template, input_variables=["context", "question"])

qa = RetrievalQA.from_chain_type(
    llm=llm,
    chain_type="stuff",
    retriever=vectorstore.as_retriever(search_kwargs={"k": 5}),
    chain_type_kwargs={"prompt": prompt},
    return_source_documents=True
)

result = qa.invoke({"query": "سیاست بازگشت کالا در فروشگاه چیست؟"})
print(result["result"])
for doc in result["source_documents"]:
    print("— منبع:", doc.metadata.get("source"), "| صفحه:", doc.metadata.get("page"))

دو تنظیم طلایی:

k را هوشمند انتخاب کن: برای اسناد فنی ۵ مناسب است؛ اگر تکه‌ها کوتاه‌اند ۶ تا ۷ بگذار. k خیلی زیاد، نویز می‌آورد.
آستانه تشابه: می‌توانی از similarity_score_threshold استفاده کنی تا تکه‌های کم‌ربط حذف شوند.

retriever = vectorstore.as_retriever(
    search_type="similarity_score_threshold",
    search_kwargs={"score_threshold": 0.75, "k": 5}
)

برای تجربه تعاملی بهتر، می‌توانی یک رابط ساده با Gradio بسازی. اگر با Gradio آشنا نیستی، معرفی Llama 4 متا را ببین تا بفهمی چرا مدل‌های چندوجهی اخیر، RAG را حتی ارزشمندتر کرده‌اند — چون زمینه متنی دقیق، توهم چندوجهی را هم کاهش می‌دهد.

مقایسه Chroma با پایگاه‌های برداری دیگر

انتخاب پایگاه برداری به مقیاس و بودجه‌ات بستگی دارد. برای نمونه‌سازی لوکال Chroma بی‌رقیب است، اما برای مقیاس تولید گزینه‌های دیگری هم هست.

پایگاه	نقطه قوت	محدودیت	بهترین سناریو
Chroma	نصب آنی، API ساده، فایل‌محور	برای ترافیک بسیار بالا نیاز به تنظیم	پروتوتایپ، تیم کوچک، داده زیر ۱M بردار
FAISS	بسیار سریع، کنترل دقیق ایندکس	مدیریت دستی ذخیره/متادیتا	تحقیق و بنچمارک آفلاین
Qdrant	مقیاس‌پذیر، فیلتر متادیتا قوی	نیاز به سرویس جدا	محصول تولیدی با فیلتر پیشرفته
Pinecone	مدیریت‌شده، مقیاس ابری	هزینه ماهانه	استارتاپ بدون تیم DevOps

اگر فقط می‌خواهی سریع شروع کنی و بعد مهاجرت کنی، با Chroma شروع کن؛ LangChain لایه انتزاعی‌اش مهاجرت به Qdrant یا Pinecone را با تغییر چند خط ممکن می‌کند.

اشتباهات رایج در ساخت RAG

بیشتر RAGهای ضعیف به‌خاطر همین پنج خطا شکست می‌خورند:

تکه‌های خیلی بزرگ یا خیلی کوچک: تکه ۲۰۰۰ توکنی زمینه را شلوغ می‌کند، تکه ۱۰۰ توکنی معنای جمله را می‌برد. ۶۰۰ تا ۸۰۰ توکن با هم‌پوشانی ۸۰ تا ۱۲۰ نقطه امن است.
نادیده گرفتن تمیزکاری متن: باقی ماندن هدر/فوتر تکراری باعث می‌شود هر جستجو همان تکه‌های بی‌ربط را برگرداند. یک تابع نرمال‌سازی ساده قبل از اسپلیت بنویس.
امبدینگ نامناسب: استفاده از مدل قدیمی یا چندزبانه ضعیف برای فارسی، دقت بازیابی را ۱۵ تا ۲۰ درصد می‌اندازد. برای فارسی، text-embedding-3-small یا مدل‌های فارسی‌محور را تست کن.
پاسخ بدون ارجاع: اگر منبع را نشان ندهی، کاربر به جواب اعتماد نمی‌کند. همیشه return_source_documents=True را روشن نگه دار.
عدم ارزیابی: بدون مجموعه تست ۳۰ تا ۵۰ سؤالی، نمی‌فهمی کجا بازیابی شکست می‌خورد. یک فایل CSV از سؤال و پاسخ طلایی بساز و هر تغییر را با آن بسنج.

سوالات متداول

تفاوت RAG با فاین‌تیون چیست؟

فاین‌تیون وزن‌های مدل را تغییر می‌دهد و برای دانش ثابت و سبک نگارش مفید است، اما به‌روزرسانی‌اش پرهزینه است. RAG دانش را بیرون مدل نگه می‌دارد؛ کافی است سند جدید را به Chroma اضافه کنی تا پاسخ‌ها همان لحظه به‌روز شوند، بدون آموزش مجدد.

برای اسناد فارسی چه امبدینگی بهتر است؟

برای شروع text-embedding-3-small تعادل خوبی بین هزینه و دقت دارد و فارسی را قابل قبول می‌فهمد. اگر دقت بیشتری می‌خواهی، مدل‌های paraphrase-multilingual یا امبدینگ‌های اختصاصی فارسی را بنچمارک کن و با ۵۰ جستجوی نمونه، میانگین امتیاز تشابه را مقایسه کن.

Chroma را چطور در تولید نگه‌داری کنم؟

برای تولید، Chroma را در حالت سرور با Docker بالا بیاور، persist_directory را روی volume پایدار بگذار و به‌صورت دوره‌ای vacuum یا بکاپ بگیر. برای مقیاس بالاتر، مهاجرت به Qdrant با همان رابط LangChain فقط چند خط تغییر می‌خواهد.

چرا مدل گاهی می‌گوید «در اسناد یافت نشد» در حالی که سند وجود دارد؟

معمولاً به‌خاطر تکه‌بندی بد یا آستانه تشابه خیلی سخت‌گیرانه است. اندازه تکه را ۱۰ تا ۱۵ درصد کوچک‌تر کن، هم‌پوشانی را بیشتر کن و score_threshold را از ۰.۸ به ۰.۷ کاهش بده. همچنین مطمئن شو متن PDF درست استخراج شده؛ برخی PDFهای اسکن‌شده نیاز به OCR دارند.

آیا می‌توانم بدون OpenAI یک RAG کاملاً آفلاین بسازم؟

بله. به‌جای OpenAI از HuggingFaceEmbeddings و به‌جای GPT از یک مدل لوکال مثل Llama 3 یا Qwen با Ollama استفاده کن. کافی است ChatOpenAI را با ChatOllama جایگزین کنی؛ باقی زنجیره LangChain بدون تغییر می‌ماند.

چطور کیفیت بازیابی را بسنجم؟

یک مجموعه ارزیابی کوچک بساز: ۳۰ سؤال واقعی + پاسخ صحیح + آدرس تکه طلایی. برای هر سؤال، ببین تکه طلایی در ۵ نتیجه اول هست یا نه (Recall@5) و آیا پاسخ نهایی حاوی ارجاع درست است یا نه. این عدد را هر هفته بعد از هر تغییر ثبت کن.

جمع‌بندی

RAG هوشمند با LangChain و Chroma سه گام ساده دارد، اما جزئیات همان‌جاست که کیفیت را می‌سازد:

اسناد را تمیز کن، با RecursiveCharacterTextSplitter تکه‌بندی معنادار انجام بده و متادیتا را نگه دار.
امبدینگ مناسب انتخاب کن، بردارها را در ./chroma_db ذخیره کن و قابلیت افزودن تدریجی را فراموش نکن.
بازیابی را با k=5 و پرامپت «فقط از زمینه» بساز و همیشه منبع را برگردان.
از همین امروز یک مجموعه ۳۰ سؤالی برای ارزیابی بساز و بعد سراغ بهینه‌سازی برو.
وقتی نمونه لوکال جواب داد، مهاجرت به Qdrant یا Pinecone فقط در حد تعویض کلاس VectorStore است.

حالا پوشه data/ را با سه سند واقعی خودت پر کن، کدهای بالا را اجرا کن و اولین پرسش مستند را بپرس. اگر در اجرا به اجرای تسک‌های پس‌زمینه نیاز داشتی، نگاهی به آموزش Celery با Redis بینداز تا ایندکس‌سازی بزرگ را در بک‌گراند انجام دهی.

آموزش ساخت RAG هوشمند با LangChain و Chroma از صفر