آموزش LangChain پایتون ۲۰۲۶ با کلید تومانی 1xAi
LangChain کتابخانهای پایتونی برای اتصال مدل، قالب پرامپت و ابزار به هم است و با تنظیم baseurl سازگار با OpenAI، با یک کلید تومانی به 1xAi وصل میشود، بدون VPN و کارت خارجی.
- تیم 1xAi
- منتشر: ۲۲ آبان ۱۴۰۵
- بروزرسانی: ۱ آذر ۱۴۰۵
- ۱۰ دقیقه مطالعه
- langchain
- tutorial
تیمِ فنیِ 1xAi گیتوی را میسازد و میگرداند — همانهایی که هر روز با APIهای OpenAI، Anthropic، Google و DeepSeek از داخلِ ایران کار میکنند. آنچه اینجا میخوانی از همان کارِ روزمره درآمده، نه از بازنویسیِ مستنداتِ انگلیسی. پروفایلِ نویسنده

در این مقاله (۱۹)
- LangChain چیست و چرا از ایران با یک کلید سراغش بروید؟
- چطور ChatOpenAI را به 1xAi وصل کنیم؟
- نصب و اجرا
- نکتهی مدلهای نسل ۵ Claude
- عوض کردن مدل
- مثال ۱: یک زنجیرهی ساده با پرامپت فارسی چطور ساخته میشود؟
- مقایسهی همین زنجیره روی چند مدل
- نکتهی عملی: پرامپت سیستم کوتاه و صریح
- مثال ۲: ابزار جستوجو در مستندات محصول برای تیم استارتاپی
- محدودیتها
- کجا همین ابزار کوچک کافی است
- مثال ۳: هزینهی تومانی هر فراخوانی بین GPT، Claude، Gemini و DeepSeek
- خواندن توکن مصرفی از usage_metadata
- سوالات متداول
- LangChain چیست؟
- چطور LangChain را از ایران بدون VPN و کارت خارجی به مدلها وصل کنم؟
- هزینهی deepseek-reasoner از طریق 1xAi چقدر است؟
- چرا مدلهای Claude نسل ۵ در LangChain خطای پارامتر میدهند؟
- آیا پیش از نوشتن کد میتوانم مدل را امتحان کنم؟
LangChain کتابخانهای پایتونی برای اتصال مدل، قالب پرامپت و ابزار به هم است و با تنظیم base_url سازگار با OpenAI، با یک کلید تومانی به 1xAi وصل میشود، بدون VPN و کارت خارجی. شرط کار این است که نسخههای کتابخانه را قفل کنید، چون API آن زیاد تغییر میکند و کد یک آموزش قدیمی ممکن است اجرا نشود.
ما در 1xAi همین گیتوی را اداره میکنیم، پس این مقاله دیدگاه فروشنده را دارد.
LangChain چیست و چرا از ایران با یک کلید سراغش بروید؟
LangChain کتابخانهای پایتونی (با نسخهی TypeScript) است که مدل زبانی، قالب پرامپت، خروجیپارسر و ابزار را به هم وصل میکند. به جای نوشتن دستی هر مرحله، آنها را مثل حلقههای یک زنجیره پشت هم میچینید و مدل را با عوض کردن یک نام جابهجا میکنید.
ما در 1xAi درگاه API سازگار با OpenAI را اداره میکنیم، پس این راهنما از زاویهی ما نوشته شده است. چون آدرس پایهی https://1xai.ir/v1 با SDKهای OpenAI کار میکند، همان کلاس چت LangChain با یک کلید به مدلهای OpenAI، Claude، Gemini و DeepSeek میرسد. برای این کار نه VPN لازم است و نه کارت خارجی.
این مقاله سه مثال اجرایی دارد:
- یک زنجیرهی فارسی در پایتون با قالب پرامپت و خروجیپارسر
- یک ابزار جستوجوی مستندات که مدل در صورت نیاز صدا میزند
- مقایسهی هزینهی همان زنجیره روی چند مدل، با کارمزد ۱۵ تا ۳۰٪ بسته به مدل
حافظهی گفتگو و ساخت چتبات را قبلاً در آموزش LangChain ۲۰۲۶ برای ساخت چتبات با حافظه از ایران پوشش دادهایم و اینجا تکرارش نمیکنیم. تمرکز اینجا فقط پیکربندی چندمدلی و هزینه است.
اگر LangChain را از صفر شروع میکنید، دورهی LangChain for LLM Application Development در DeepLearning.AI را ببینید که مدرسان آن Harrison Chase و Andrew Ng هستند. برای محتوای فارسی، دورهی «آموزش ساخت دستیار هوش مصنوعی با LangChain» در کدیاد همراه با کدنویسی و ساخت ابزار است.
هر دو منبع مستقل از 1xAiاند و فقط بهعنوان مسیر یادگیری بیشتر معرفی شدهاند.
چطور ChatOpenAI را به 1xAi وصل کنیم؟
برای وصل کردن ChatOpenAI به 1xAi، مقدار base_url="https://1xai.ir/v1" را بدهید و کلیدی را که در داشبورد 1xai.ir ساختهاید بهعنوان api_key بگذارید. اگر میخواهید قبل از کدنویسی مدل را بسنجید، پلیگراند وب همان داشبورد این امکان را میدهد. جزئیات ساخت کلید و پرداخت از داخل ایران را راهنمای API OpenAI برای توسعهدهندگان ایرانی توضیح داده است.
نصب و اجرا
# نسخهها را با نسخهی نصبشدهی خودتان جایگزین کنید (با pip show langchain-openai ببینید)
pip install "langchain-openai==0.3.0"
export ONEXAI_API_KEY="کلید-شما"
import os
from langchain_core.messages import HumanMessage, SystemMessage
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="gpt-5.2",
base_url="https://1xai.ir/v1",
api_key=os.environ["ONEXAI_API_KEY"],
)
response = llm.invoke([
SystemMessage(content="به فارسی و کوتاه جواب بده."),
HumanMessage(content="LangChain را در یک جمله توضیح بده."),
])
print(response.content)
خروجی نمونه (متن هر بار کمی فرق میکند):
LangChain کتابخانهای است که مدل زبانی، قالب پرامپت، حافظه و ابزارها را در یک برنامه به هم وصل میکند.
نکتهی مدلهای نسل ۵ Claude
مدلهای claude-sonnet-5، claude-fable-5 و claude-opus-5 پارامترهای temperature و top_p و همچنین prefill پیام assistant را رد میکنند. برای این مدلها این پارامترها را در ChatOpenAI ست نکنید و لیست پیامها را با پیام assistant تمام نکنید. اگر نسخهی نصبشدهی شما خودش مقدار پیشفرضی برای temperature میفرستد، آن را صریح None بگذارید.
عوض کردن مدل
برای جابهجایی بین مدلها فقط رشتهی model را عوض کنید؛ نامهای معتبر در فهرست مدلهای 1xAi آمده است. SDKهای Anthropic و Google GenAI هم روی اندپوینتهای اختصاصی 1xAi کار میکنند، ولی ادامهی این مقاله روی مسیر OpenAI-سازگار میماند.
دربارهی حریم خصوصی: IP، کوکی و user-agent شما به ارائهدهندهی بالادستی نمیرسد، چون هر درخواست از زیرساخت 1xAi دوباره ارسال میشود.
مثال ۱: یک زنجیرهی ساده با پرامپت فارسی چطور ساخته میشود؟
یک زنجیرهی LCEL با اتصال سه جزء بهوسیلهی عملگر | ساخته میشود: ChatPromptTemplate، سپس ChatOpenAI و در پایان StrOutputParser. وظیفهی نمونه، خلاصهکردن و دستهبندی یک تیکت پشتیبانی فارسی است. کلید API را از داشبورد 1xAi میگیریم و base_url را روی https://1xai.ir/v1 میگذاریم.
برای اجرا باید langchain-core و langchain-openai نصب باشند و کلید در متغیر محیطی ONEXAI_API_KEY قرار گیرد. API لانگچین زود تغییر میکند، پس نسخهها را در requirements.txt قفل کنید.
import os
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_openai import ChatOpenAI
prompt = ChatPromptTemplate.from_messages([
("system",
"تو دستیار پشتیبانی فارسیزبان هستی. تیکت را در یک جمله خلاصه کن، "
"سپس دسته را فقط از این فهرست انتخاب کن: پرداخت، ارسال، فنی، سایر. "
"پاسخ کوتاه و فارسی باشد."),
("human", "متن تیکت:\n{ticket}"),
])
ticket = "سه روز پیش سفارش دادم ولی هنوز کد رهگیری نیامده و پیگیریهایم بیجواب مانده."
llm = ChatOpenAI(
model="gpt-5.2",
base_url="https://1xai.ir/v1",
api_key=os.environ["ONEXAI_API_KEY"],
)
chain = prompt | llm | StrOutputParser()
print(chain.invoke({"ticket": ticket}))
خروجی نمونه (نمونهی تقریبی؛ خروجی واقعی هر بار فرق میکند):
خلاصه: مشتری سه روز پس از ثبت سفارش هنوز کد رهگیری دریافت نکرده است.
دسته: ارسال
مقایسهی همین زنجیره روی چند مدل
پرامپت و پارسر ثابت میمانند و فقط مدل عوض میشود. در حلقهی زیر temperature را عمداً تنظیم نکردهایم، چون برخی مدلهای استدلالی آن را نمیپذیرند.
for name in ["gpt-5.2", "deepseek-chat", "gemini-3.1-flash-lite", "o4-mini"]:
llm = ChatOpenAI(
model=name,
base_url="https://1xai.ir/v1",
api_key=os.environ["ONEXAI_API_KEY"],
)
chain = prompt | llm | StrOutputParser()
print(f"--- {name} ---")
print(chain.invoke({"ticket": ticket}))
قیمت رسمی هر مدل (دلار به ازای هر یک میلیون توکن) در جدول آمده است. قیمت تومانی زنده، که با نرخ بازار هر روز بهروز میشود، در صفحهی مدلها است.
| مدل | ورودی (دلار) | خروجی (دلار) |
|---|---|---|
| gpt-5.2 | ۱٫۷۵ | ۱۴ |
| o4-mini | ۱٫۱ | ۴٫۴ |
| deepseek-chat | ۰٫۳ | ۱٫۲ |
| gemini-3.1-flash-lite | ۰٫۲۵ | ۱٫۵ |
در گیتوی ما در ۳۰ روز گذشته ۴٬۶۲۷ درخواست برای deepseek-chat و ۳٬۹۶۳ درخواست برای gemini-3.1-flash-lite ثبت شده و نرخ موفقیت هر دو ۱۰۰٪ بوده است. اگر کلید و SDK را هنوز راه نینداختهاید، راهنمای نصب SDK و اولین درخواست Gemini API مراحل آن را توضیح میدهد.
نکتهی عملی: پرامپت سیستم کوتاه و صریح
پرامپت سیستم را در چند جمله نگه دارید. نقش، قالب خروجی و فهرست بستهی دستهها را صریح بنویسید، همانطور که در کد بالا هست. هرچه فهرست دستهها بستهتر باشد، مقایسهی خروجی مدلها در حلقه سادهتر میشود.
مثال ۲: ابزار جستوجو در مستندات محصول برای تیم استارتاپی
با دکوراتور @tool یک تابع جستوجو تعریف میشود و با bind_tools به مدل داده میشود؛ سپس خود مدل تصمیم میگیرد چه زمانی آن را صدا بزند. کد نیازمند langchain-core و langchain-openai است.
با @tool یک تابع جستوجو تعریف میکنید، با bind_tools آن را به مدل میدهید و خود مدل تصمیم میگیرد چه موقع صدایش بزند. کد زیر نیاز به langchain-core و langchain-openai دارد؛ نسخهها را در requirements.txt قفل کنید. کلید را هم از داشبورد 1xai.ir بسازید و در متغیر ONEXAI_API_KEY بگذارید.
import os
import re
from langchain_core.messages import HumanMessage, ToolMessage
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
# دادهی نمایشی: محصول و متنها فرضیاند
DOCS = [
"سفارشیار هر سفارش جدید را در پنل مدیریت نشان میدهد و اعلانش را به تلگرام مدیر میفرستد.",
"برای بازگشت وجه، سفارش را از بخش «سفارشها» باز کنید و دکمهی «درخواست بازگشت وجه» را بزنید؛ پس از تأیید مدیر انجام میشود.",
"کلید API از بخش «تنظیمات» و زیربخش «اتصالها» ساخته میشود و فقط یک بار نمایش داده میشود.",
]
def _words(text: str) -> set[str]:
return {w for w in re.findall(r"\w+", text.lower()) if len(w) > 2}
@tool
def search_docs(query: str) -> str:
"""جستوجوی کلیدواژهای در مستندات محصول سفارشیار. کلیدواژههای کوتاه فارسی بدهید."""
scored = []
for doc in DOCS:
score = sum(1 for w in _words(query) if w in doc.lower())
if score:
scored.append((score, doc))
scored.sort(reverse=True)
return "\n".join(d for _, d in scored[:2]) or "موردی در مستندات پیدا نشد."
llm = ChatOpenAI(
model="gpt-5.2",
base_url="https://1xai.ir/v1",
api_key=os.environ["ONEXAI_API_KEY"],
)
llm_with_tools = llm.bind_tools([search_docs])
messages = [HumanMessage("چطور کلید API بسازم؟")]
ai = llm_with_tools.invoke(messages)
while ai.tool_calls: # تا وقتی مدل ابزار میخواهد
messages.append(ai)
for call in ai.tool_calls:
print("فراخوانی ابزار:", call["name"], call["args"])
result = search_docs.invoke(call["args"])
messages.append(ToolMessage(content=result, tool_call_id=call["id"]))
ai = llm_with_tools.invoke(messages) # مدل با نتیجهی ابزار جواب میدهد
print(ai.content)
خروجی نمونه (نمایشی؛ عبارت دقیق مدل و کلیدواژهای که انتخاب میکند هر بار کمی فرق دارد):
فراخوانی ابزار: search_docs {'query': 'ساخت کلید API'}
کلید API را از «تنظیمات» و زیربخش «اتصالها» بسازید. توجه کنید که کلید فقط یک بار نمایش داده میشود.
محدودیتها
این نسخه RAG کامل نیست. جستوجو فقط تطبیق کلیدواژه است، پس اگر کاربر «پول را پس بگیرم» بنویسد و مستند «بازگشت وجه» داشته باشد، چیزی پیدا نمیشود.
برای انبوه مستندات به embedding و پایگاه برداری نیاز دارید. دربارهی اندپوینت embedding در 1xAi ادعایی نمیکنیم؛ اندپوینت و مدل مناسب را در فهرست مدلهای 1xAi بررسی کنید.
کجا همین ابزار کوچک کافی است
اگر مستندات شما چند صفحهی FAQ و راهنمای راهاندازی است و هر پرسش را میتوان با چند کلیدواژه پیدا کرد، همین الگو برای دستیار داخلی تیم کافی است. وقتی حجم مستندات بالا میرود یا کاربران به زبان آزاد میپرسند، باید به جستوجوی معنایی و ساخت سفارشی بروید.
مثال ۳: هزینهی تومانی هر فراخوانی بین GPT، Claude، Gemini و DeepSeek
هزینهی هر فراخوانی از قیمت رسمی ارائهدهنده بهاضافهی مارکآپ ما به دست میآید، یعنی «کارمزد ۱۵ تا ۳۰٪ بسته به مدل». نرخ دلار هم هر روز ساعت ۹ صبح تهران با بازار هماهنگ میشود، پس هیچ مبلغ ثابتی در متن نمینویسیم و عددها از قیمت زنده خوانده میشوند.
| مدل | ورودی هر ۱ میلیون توکن | خروجی هر ۱ میلیون توکن |
|---|---|---|
gpt-5.2 |
۵۷۱٬۸۳۰ تومان | ۴٬۵۷۴٬۶۴۰ تومان |
o4-mini |
۳۵۹٬۴۳۶ تومان | ۱٬۴۳۷٬۷۴۴ تومان |
gemini-3.1-flash-lite |
۸۱٬۶۹۰ تومان | ۴۹۰٬۱۴۰ تومان |
deepseek-chat |
۹۸٬۰۲۸ تومان | ۳۹۲٬۱۱۲ تومان |
برای نمونه، ورودی deepseek-chat همین امروز ۹۸٬۰۲۸ تومان برای هر ۱ میلیون توکن است و خروجی gpt-5.2 ۴٬۵۷۴٬۶۴۰ تومان. قیمت مدلهای Claude را از فهرست زندهی مدلها ببینید.
هر عدد تومانی که در صفحههای قدیمی یا اسکرینشاتها میبینید روی نرخ دلار همان روز بسته شده است. آن را کپی نکنید و فقط مقدار زنده را بخوانید.
خواندن توکن مصرفی از usage_metadata
پاسخ هر مدل در LangChain یک AIMessage است و توکن مصرفیاش در usage_metadata میآید. کد زیر را با langchain-openai اجرا کنید و نسخهی پکیج را در requirements.txt قفل کنید. قیمتها را از جدول بالا یا صفحهی مدلها در دو متغیر بگذارید:
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="deepseek-chat",
base_url="https://1xai.ir/v1",
api_key=os.environ["API_KEY_1XAI"],
)
msg = llm.invoke("در یک جمله بگو LangChain چیست.")
usage = msg.usage_metadata
print(usage)
# قیمتها را خودتان از صفحهی مدلها بگذارید (تومان برای هر ۱ میلیون توکن)
IN_1M = ... # ورودی
OUT_1M = ... # خروجی
def call_cost(u, in_1m, out_1m):
return (u["input_tokens"] * in_1m + u["output_tokens"] * out_1m) / 1_000_000
# print(call_cost(usage, IN_1M, OUT_1M)) # بعد از پر کردن قیمتها
خروجی print(usage) یک دیکشنری با کلیدهای input_tokens، output_tokens و total_tokens است و مقدارهایشان به پرامپت و پاسخ شما بستگی دارد. برای مقایسهی چهار مدل، فقط model و دو قیمت را عوض کنید.
پژوهش و نگارش: CodeNest's AI SEO content engine
سوالات متداول
LangChain چیست؟
LangChain کتابخانهای پایتونی (و TypeScript) است که مدل زبانی، قالب پرامپت، خروجیپارسر و ابزارها را به هم وصل میکند تا برنامههای مبتنی بر LLM را زنجیرهوار بسازید. API آن زیاد تغییر میکند، پس نسخهی کتابخانهها را قفل کنید.
چطور LangChain را از ایران بدون VPN و کارت خارجی به مدلها وصل کنم؟
LangChain با تنظیم base_url سازگار با OpenAI روی 1xAi کار میکند و به VPN یا کارت بانکی خارجی نیاز ندارد. کلید را از داشبورد 1xai.ir میسازید و هر SDK استاندارد OpenAI بدون تغییر کار میکند. طبق دادهی تأییدشده در ۱۳ نوامبر ۲۰۲۶، SDKهای Anthropic و Google GenAI هم روی اندپوینتهای اختصاصی پشتیبانی میشوند.
هزینهی deepseek-reasoner از طریق 1xAi چقدر است؟
deepseek-reasoner در 1xAi برای هر یک میلیون توکن ورودی ۹۸٬۰۲۸ تومان و برای هر یک میلیون توکن خروجی ۳۹۲٬۱۱۲ تومان است. این رقم با مارکآپ ۲۰٪ روی قیمت رسمی (۰٫۳ و ۱٫۲ دلار) و نرخ ۲۷۲٬۳۰۰ تومان به ازای هر دلار محاسبه شده است (تأیید: ۱۳ نوامبر ۲۰۲۶). قیمت توکن ورودی کششده (کش پرامپت) هم با نرخ روزانهی دلار بهروز میشود و مقدار جاری آن در صفحهی مدلهای 1xAi دیده میشود.
چرا مدلهای Claude نسل ۵ در LangChain خطای پارامتر میدهند؟
مدلهای claude-sonnet-5 و claude-fable-5 و claude-opus-5 پارامترهای temperature و top_p و همچنین prefill پیام دستیار را رد میکنند. اگر در LangChain برای این مدلها دما یا top_p تعیین کردهاید، آنها را حذف کنید.
آیا پیش از نوشتن کد میتوانم مدل را امتحان کنم؟
بله، 1xAi یک playground تحت وب دارد که پیش از نوشتن کد، مدلها را در آن امتحان میکنید. طبق اطلاعات 1xAi، IP، کوکیها و user-agent مشتری به ارائهدهندهی بالادستی نمیرسد، چون هر درخواست از زیرساخت 1xAi دوباره ارسال میشود.


