۱۰۰ هزار تومان هدیهٔ ثبت‌نام، تا ۱ میلیونبا ثبت‌نام گردونهٔ هدیه را بچرخان: دست‌کم ۱۰۰٬۰۰۰ تومان و تا ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه، بدون کارت بانکیگردونهٔ هدیه۱ میلیون برای تو، ۱ میلیون برای دوستتدوستانت را دعوت کن: برای هر دوستی که فعال شود ۱٬۰۰۰٬۰۰۰ تومان اعتبار هدیه می‌گیری و خودش هم ۱٬۰۰۰٬۰۰۰ تومانجوایز
1xAi
مقاله

آموزش LangChain ۲۰۲۶: ساخت چت‌بات با حافظه از ایران

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

  • منتشر: ۱۷ آبان ۱۴۰۵
  • بروزرسانی: ۱ آذر ۱۴۰۵
  • ۹ دقیقه مطالعه
  • آموزش
  • langchain

تیمِ فنیِ 1xAi گیت‌وی را می‌سازد و می‌گرداند — همان‌هایی که هر روز با APIهای OpenAI‏، Anthropic‏، Google و DeepSeek از داخلِ ایران کار می‌کنند. آنچه اینجا می‌خوانی از همان کارِ روزمره درآمده، نه از بازنویسیِ مستنداتِ انگلیسی.

آموزش LangChain ۲۰۲۶: ساخت چت‌بات با حافظه از ایران

در این مقاله (۱۷)

LangChain کتابخانه‌ای پایتونی برای وصل کردن مدل زبانی، قالب پرامپت، حافظه گفتگو و ابزار در یک برنامه است. چون از base_url سازگار با OpenAI پشتیبانی می‌کند، می‌توانید آن را از ایران و با پرداخت تومانی به مدل‌هایی مثل GPT، Claude، Gemini و DeepSeek وصل کنید.

شرط مهم این است که نسخه‌ها را قفل کنید، چون API این کتابخانه زیاد تغییر می‌کند و کدی که امروز اجرا می‌شود ممکن است با نسخه بعدی خطا بدهد. ما در 1xAi همین گیت‌وی را اداره می‌کنیم، پس دیدگاه این مقاله دیدگاه فروشنده است؛ در ادامه گام‌به‌گام یک چت‌بات با حافظه می‌سازیم.

LangChain کتابخانه‌ای است که مدل زبانی، پرامپت، حافظه و ابزار را در یک برنامه به هم وصل می‌کند. اگر base_url سازگار با OpenAI را روی https://1xai.ir/v1 بگذارید، همین کتابخانه از ایران و با پرداخت تومانی به GPT، Claude، Gemini و DeepSeek وصل می‌شود، بدون کارت خارجی و بدون VPN.

یک شرط مهم هم همین ابتدا بگوییم: نسخه‌ی langchain و پکیج‌های جانبی‌اش را در requirements.txt قفل کنید. API این کتابخانه زیاد تغییر می‌کند و کدی که از یک آموزش قدیمی‌تر برمی‌دارید ممکن است روی نسخه‌ی تازه اجرا نشود.

ما در 1xAi همین گیت‌وی را اداره می‌کنیم، پس دیدگاه این مقاله دیدگاه فروشنده است.

LangChain چیست و چه مشکلی را حل می‌کند؟

LangChain فریم‌ورکی برای ساخت اپلیکیشن‌های مبتنی بر مدل زبانی است که کار را به اجزای مستقل و قابل‌ترکیب تقسیم می‌کند. با تغییر یک پارامتر می‌توان مدل را عوض کرد و قالب پرامپت، حافظه و ابزار را بدون بازنویسی بخش زیادی از کد استفاده کرد.

اگر دنبال جواب «langchain چیه» یا «what is lang chain» بودید، همین است. اجزای اصلی‌اش این‌ها هستند:

  • مدل چت: رابط یکسان برای گفتگو با مدل‌ها.
  • ChatPromptTemplate: قالب پرامپت با متغیرهای جاگذاری‌شدنی.
  • Parser: تبدیل خروجی مدل به متن ساده یا ساختار مشخص.
  • زنجیره (LCEL): اتصال این اجزا به هم، همان «chain in langchain».
  • حافظه: نگه‌داشتن تاریخچه گفتگو.
  • ابزار و ایجنت: مدل تصمیم می‌گیرد کدام تابع را صدا بزند. این بخش را در «langchain agents» جداگانه می‌بینیم.

اکوسیستم سه بخش دارد: LangChain برای زنجیره‌ها، LangGraph برای گردش‌کارهای حالت‌دار و شرطی، و LangSmith برای ردگیری و ارزیابی. مرجع اصلی یادگیری هم مستندات رسمی، LangChain Academy و وبلاگ LangChain است.

«چرا نه فقط SDK خام؟» دلیلش این است که با SDK خام، قالب پرامپت و حافظه و ابزارها را خودتان سیم‌کشی می‌کنید و مدل جدید یعنی بازنویسی بخشی از کد. در LangChain مدل با تغییر یک پارامتر عوض می‌شود:

# pip install langchain-openai
from langchain_openai import ChatOpenAI

kwargs = dict(base_url="https://1xai.ir/v1", api_key="YOUR_1XAI_KEY")
llm = ChatOpenAI(model="gemini-2.5-flash-lite", **kwargs)
llm = ChatOpenAI(model="deepseek-chat", **kwargs)  # فقط model عوض شد

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

آموزش فارسی‌ای که در ۱۴۰۲ دیدیم برای ثبت‌نام و گرفتن کلید فقط مسیر VPN، DNS و شماره مجازی را نشان می‌داد. با 1xAi پرداخت به تومان انجام می‌شود و برای استفاده از سرویس به کارت خارجی یا VPN نیازی نیست.

چطور بدون VPN و کارت خارجی LangChain را راه بیندازیم؟

با ساخت حساب در 1xAi، شارژ تومانی از درگاه ایرانی و تغییر base_url به https://1xai.ir/v1، LangChain بدون VPN و کارت خارجی کار می‌کند. چون API سازگار با OpenAI است، همان کلاس ChatOpenAI را بدون تغییر دیگری به کار می‌بریم. جزئیات ساخت کلید و SDK در راهنمای API OpenAI برای توسعه‌دهندگان ایرانی آمده و اینجا تکرارش نمی‌کنیم.

۱. محیط مجازی و نصب

python -m venv .venv
source .venv/bin/activate        # ویندوز: .venv\Scripts\activate
pip install langchain langchain-openai langchain-core
export ONEXAI_API_KEY="کلید-شما"   # PowerShell: $env:ONEXAI_API_KEY="کلید-شما"

کلید را فقط در متغیر محیطی نگه دارید و هیچ‌وقت داخل فایل کد یا مخزن Git نگذارید.

برای requirements.txt عدد نسخه‌ای نمی‌نویسیم که روی سیستم شما اجرا نشده باشد. نسخه‌های قفل‌شده را از نصبِ سالم خودتان بگیرید:

pip freeze | grep -iE "^(langchain|langchain-openai|langchain-core|openai)==" > requirements.txt

خروجی به شکل langchain-openai==<نسخه‌ی نصب‌شده> درمی‌آید. این فایل همان نسخه‌هایی را ثبت می‌کند که کد شما با آن‌ها واقعاً اجرا شده است.

۲. تست سریع با curl

curl https://1xai.ir/v1/chat/completions \
  -H "Authorization: Bearer $ONEXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"سلام"}]}'

اگر JSON حاوی choices برگشت، کلید و شارژ درست‌اند. نام مدل‌ها را از فهرست مدل‌ها بردارید. deepseek-chat فقط نمونه است.

۳. اولین chain در LangChain

import os
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

llm = ChatOpenAI(
    model="deepseek-chat",
    base_url="https://1xai.ir/v1",
    api_key=os.environ["ONEXAI_API_KEY"],
)
prompt = ChatPromptTemplate.from_messages([
    ("system", "تو دستیار فنی هستی و کوتاه جواب می‌دهی."),
    ("human", "{question}"),
])
chain = prompt | llm | StrOutputParser()
print(chain.invoke({"question": "LangChain در یک جمله چیست؟"}))

خروجی یک جمله فارسی است و متنش در هر اجرا فرق می‌کند. اگر بخواهید همین پایه را به یک پشتیبان مشتری تبدیل کنید، چت با مشتری با API: ساخت پشتیبانی هوشمند ادامه‌ی منطقی کار است.

۴. شارژ کیف پول

کیف پول تومانی را با درگاه ایرانی (ZarinPal) شارژ می‌کنید و هنگام پرداخت ۱۰٪ ارزش افزوده اضافه می‌شود. هیچ مرحله‌ای VPN نمی‌خواهد.

برای امتحان بدون هزینه‌ی اولیه، چرخ شانس ثبت‌نام به هر حساب یک چرخش می‌دهد. اعتبار برنده‌شده بین ۱۰۰ هزار تا ۱٬۰۲۴٬۶۸۵ تومان است و منقضی نمی‌شود. این هدیه‌ی یک‌باره است و استفاده‌ی رایگان نامحدود نیست.

چطور اولین زنجیره را با ChatPromptTemplate و LCEL بنویسیم؟

اولین زنجیره سه حلقه دارد: قالب پیام با ChatPromptTemplate.from_messages، مدل ChatOpenAI که به https://1xai.ir/v1 وصل است، و StrOutputParser که خروجی را به رشته تبدیل می‌کند. فرض کردم langchain-core و langchain-openai را با pip install -U نصب کرده‌اید و کلید API در متغیر محیطی ONEXAI_API_KEY است.

import os
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="deepseek-chat",
    api_key=os.environ["ONEXAI_API_KEY"],
    base_url="https://1xai.ir/v1",
    temperature=0.3,
)

prompt = ChatPromptTemplate.from_messages([
    ("system", "تو دستیار فنی هستی و به فارسی ساده و دقیق جواب می‌دهی. حداکثر سه جمله بنویس."),
    ("human", "مفهوم «{topic}» را برای {audience} توضیح بده."),
])

chain = prompt | llm | StrOutputParser()

print(chain.invoke({"topic": "LCEL", "audience": "برنامه‌نویس پایتون"}))

خروجی (نمونه تقریبی، متن واقعی هر بار فرق می‌کند):

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

عملگر | چه می‌کند؟

عملگر | خروجی هر مرحله را به ورودی مرحله بعد می‌دهد. دیکشنری ورودی به prompt می‌رسد و پیام‌های ساخته‌شده به مدل می‌روند. پاسخ مدل هم به parser می‌رسد و رشته تحویل می‌دهد. چون کل زنجیره یک شیء واحد است، همان chain متدهای stream و batch را هم دارد:

inputs = {"topic": "LCEL", "audience": "برنامه‌نویس پایتون"}

for chunk in chain.stream(inputs):
    print(chunk, end="", flush=True)

answers = chain.batch([inputs, {"topic": "Runnable", "audience": "دانشجو"}])

عوض کردن مدل

برای عوض کردن مدل فقط مقدار model تغییر می‌کند؛ کلید و base_url همان می‌مانند:

def make_chain(model_name: str):
    llm = ChatOpenAI(
        model=model_name,
        api_key=os.environ["ONEXAI_API_KEY"],
        base_url="https://1xai.ir/v1",
    )
    return prompt | llm | StrOutputParser()

for name in ["deepseek-chat", "gemini-2.5-flash-lite", "claude-sonnet-4-6"]:
    print(name, "→", make_chain(name).invoke(inputs))

نام مدل باید دقیقاً مطابق فهرست مدل‌های 1xAi باشد. یک حرف اضافه یا تفاوت در شماره نسخه معمولاً به خطای «مدل پیدا نشد» ختم می‌شود. فهرست و قیمت زنده هر مدل همان‌جا است و مارک‌آپ ما بسته به مدل بین ۱۵ تا ۳۰٪ است.

چطور برای چت‌بات حافظه گفتگو بسازیم و هزینه‌اش را کنترل کنیم؟

با RunnableWithMessageHistory تاریخچه هر کاربر زیر یک session_id نگه‌داری و خودکار وارد پرامپت می‌شود. برای کنترل هزینه می‌توانید تاریخچه را با بریدن، خلاصه‌سازی یا کش پرامپت کوتاه‌تر و ارزان‌تر کنید.

هزینه را هم با کوتاه‌کردن تاریخچه مهار می‌کنید. برای کلید API و تنظیم SDK، راهنمای API OpenAI برای توسعه‌دهندگان ایرانی را ببینید.

نصب: pip install -U langchain-openai langchain-core

from langchain_openai import ChatOpenAI
from langchain_core.chat_history import InMemoryChatMessageHistory
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_core.runnables.history import RunnableWithMessageHistory

llm = ChatOpenAI(
    model="deepseek-chat",
    base_url="https://1xai.ir/v1",
    api_key="YOUR_1XAI_API_KEY",
)

prompt = ChatPromptTemplate.from_messages([
    ("system", "تو یک دستیار فارسی‌زبان هستی."),
    MessagesPlaceholder("history"),
    ("human", "{input}"),
])

store = {}  # برای هر session_id یک تاریخچه

def get_history(session_id: str):
    if session_id not in store:
        store[session_id] = InMemoryChatMessageHistory()
    return store[session_id]

chat = RunnableWithMessageHistory(
    prompt | llm,
    get_history,
    input_messages_key="input",
    history_messages_key="history",
)

cfg = {"configurable": {"session_id": "user-42"}}
print(chat.invoke({"input": "اسم من سارا است."}, config=cfg).content)
print(chat.invoke({"input": "اسم من چیست؟"}, config=cfg).content)

خروجی دوم باید اسم «سارا» را برگرداند. متن دقیق جواب مدل فرق می‌کند، اما اگر session_id را عوض کنید، مدل اسم را نمی‌داند.

InMemoryChatMessageHistory با بسته‌شدن برنامه پاک می‌شود. در نسخه تولیدی تاریخچه را در Redis یا پایگاه داده نگه دارید. برای پروژه‌های تازه، مسیر persistence در LangGraph هم راهنمای عمومی رایج است.

هزینه حافظه

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

  • بریدن تاریخچه: فقط N پیام آخر را نگه دارید (مثلاً با trim_messages و strategy="last").
  • خلاصه‌سازی: پیام‌های قدیمی را یک‌بار به خلاصه کوتاه تبدیل کنید.
  • کش پرامپت: بخش ثابت ابتدای پرامپت، مثل پیام سیستمی، ارزان‌تر محاسبه می‌شود.

مثلاً deepseek-chat برای هر یک میلیون توکن ورودی ۹۸٬۰۲۸ تومان و برای خروجی ۳۹۲٬۱۱۲ تومان است. قیمت claude-sonnet-4-6 برای ورودی ۹۸۰٬۲۸۰ تومان است.

مدل ورودی (تومان / ۱M توکن) خروجی (تومان / ۱M توکن) قیمت رسمی دلاری
deepseek-chat ۹۸٬۰۲۸ ۳۹۲٬۱۱۲ صفحه قیمت DeepSeek
gemini-2.5-flash-lite ۳۵٬۳۹۹ ۱۴۱٬۵۹۶ صفحه قیمت Gemini API
claude-sonnet-4-6 ۹۸۰٬۲۸۰ ۴٬۹۰۱٬۴۰۰ صفحه قیمت Anthropic

کارمزد ۱۵ تا ۳۰٪ بسته به مدل است و قیمت‌ها هر صبح با نرخ بازار همگام می‌شوند؛ مرجع نهایی صفحه مدل‌ها است.

پژوهش و نگارش: CodeNest

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

LangChain چیست؟ (langchain چیه / what is lang chain)

LangChain کتابخانه‌ای برای ساخت اپ‌های مبتنی بر مدل زبانی است. اجزای مستقلی مثل مدل چت، ChatPromptTemplate، parser، زنجیره‌های LCEL، حافظه، ابزار و ایجنت را با یک رابط یکسان به هم وصل می‌کند. به این ترتیب لازم نیست اتصال این بخش‌ها را برای هر پروژه از صفر بنویسید.

چرا از LangChain استفاده کنم و فقط SDK خام را به کار نبرم؟

مزیت اصلی آن رابط یکسان است. با تغییر یک پارامتر می‌توانید مدل را عوض کنید، قالب‌های پرامپت را دوباره استفاده کنید و حافظه و ابزار را با همان ساختار اضافه کنید. برای یک فراخوانی ساده SDK خام کافی است. چون API کتابخانه زیاد تغییر می‌کند، نسخه‌ها را در requirements.txt قفل کنید.

LangChain، LangGraph و LangSmith چه تفاوتی دارند؟

LangChain برای ساخت زنجیره‌ها و ایجنت‌های ساده است. LangGraph برای گردش‌کارهای حالت‌دار و شرطی به کار می‌رود، و LangSmith برای ردگیری و ارزیابی اجراهای برنامه. برای شروع معمولاً LangChain کافی است. جزئیات هر سه در مستندات رسمی و LangChain Academy آمده است.

چطور از ایران، بدون VPN و کارت خارجی، LangChain را به GPT، Claude، Gemini یا DeepSeek وصل کنم؟

کلید API را از گیت‌وی بگیرید و در LangChain آدرس سازگار با OpenAI را با پارامتر base_url تنظیم کنید. پرداخت تومانی است و به VPN یا کارت خارجی نیاز ندارید. ما در 1xAi همین گیت‌وی را اداره می‌کنیم، پس این پاسخ دیدگاه فروشنده است. آدرس دقیق را از پنل بردارید.

هزینه اجرای یک چت‌بات LangChain با 1xAi چقدر است؟

هزینه به تعداد توکن بستگی دارد. قیمت‌های صفحه مدل‌های 1xAi هر صبح با نرخ بازار دلار هماهنگ می‌شوند و کارمزد ۱۵ تا ۳۰٪ بسته به مدل است. در gemini-2.5-flash-lite هر یک میلیون توکن ورودی ۳۵٬۳۹۹ و خروجی ۱۴۱٬۵۹۶ تومان است. در deepseek-chat ورودی ۹۸٬۰۲۸ و خروجی ۳۹۲٬۱۱۲ تومان است.

مدل‌هایی که در این مقاله دیدی را از داخل ایران امتحان کن.

بدون VPN، صورت‌حساب تومانی، کارمزدِ ۱۵ تا ۳۰٪ بسته به مدل روی نرخِ هر سرویس‌دهنده.