بخش 3.1 · مدل‌ها، پیام‌ها و ابزارها

نصب و نقشه‌ی توزیع پکیج‌ها

Install and the package map

فهرست مطالب
  1. نقشه‌ی پکیج‌ها
  2. چه چیزهایی جابه‌جا شدند
  3. پایتون 3.11
  4. یک فایل قفل
  5. حجم نصب و زمان import

پکیج langchain نسخه‌ی 1.5.0 را روی Python 3.11 یا بالاتر و حتماً با یک فایل قفل (lockfile) نصب کنید؛ چون این مجموعه از چندین پکیج با نسخه‌بندی‌های مستقل تشکیل شده و حتی یک نسخه‌ی فرعی (minor) هم می‌تواند رفتار برنامه را تغییر دهد.

شاید برایتان پیش آمده باشد که عبارت from langchain.chains import LLMChain را از پاسخی قدیمی کپی کنید و پایتون خطای ModuleNotFoundError بدهد. یا برای استفاده از یک لودر، پکیج langchain-community را نصب کنید و بعد بخوانید که توسعه‌ی این پکیج متوقف شده است. یا مثلاً دستور یکسان pip install را یک بار روی Python 3.10 و بار دیگر روی 3.12 اجرا کنید و دو نسخه‌ی کاملاً متفاوت از langchain تحویل بگیرید.

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

نقشه‌ی پکیج‌ها

توزیع (Distribution): پکیج با همان نامی که در pip دارد؛ مثل langchain-core. نام import آن در پایتون به جای خط تیره، زیرخط (_) دارد؛ مثل langchain_core.

این مجموعه در نسخه‌های پین‌شده، میان این توزیع‌ها تقسیم می‌شود:

توزیع نسخه نام import شامل چه مواردی است
langchain 1.5.0 langchain تابع create_agent، میان‌افزارها، init_chat_model، ماژول langchain.mcp، و مسیرهای کوتاه برای import پیام‌ها و ابزارها
langchain-core 1.8.0 langchain_core پیام‌ها و بلوک‌های محتوا، BaseChatModel، ابزارها، کال‌بک‌ها، اسناد، بازیاب‌ها، امبدینگ‌ها، و مدل‌های ساختگی (fake models)
langgraph 1.2.22 langgraph کلاس StateGraph، حلقه‌ی Pregel، دستورات Command و Send، تابع interrupt، رابط کاربری تابعی (functional API)، و استریمینگ
langgraph-prebuilt 1.1.2 langgraph.prebuilt کلاس‌های ToolNode، ToolRuntime، InjectedState، و تابع منسوخ‌شده‌ی create_react_agent
langgraph-checkpoint 4.3.2 langgraph.checkpoint، langgraph.store رابط ذخیره‌ساز (saver interface)، کلاس‌های InMemorySaver، سریالایزرها، و InMemoryStore
langgraph-checkpoint-sqlite 3.1.3 langgraph.checkpoint.sqlite کلاس‌های SqliteSaver و SqliteStore
langgraph-checkpoint-postgres 3.2.1 langgraph.checkpoint.postgres کلاس‌های PostgresSaver و PostgresStore
langsmith 0.14.17 langsmith کلاینت ردگیری محاسبات، traceable، و تابع evaluate
deepagents 0.7.38 deepagents تابع create_deep_agent، بک‌اندهای آن، و میان‌افزارهایش
langchain-text-splitters 1.1.3 langchain_text_splitters تقسیم‌کننده‌های متن
langchain-classic 1.0.8 langchain_classic فضای نام نسخه‌ی 0.3: زنجیره‌ها (chains)، ایجنت‌های قدیمی، ماژول prompt hub، و کلاس‌های حافظه‌ی قدیمی

هر ارائه‌دهنده‌ی مدل، پکیج اختصاصی خود را دارد؛ مثل langchain-openai نسخه 1.8.0، langchain-anthropic نسخه 1.7.10، و langchain-ollama نسخه 1.1.0. همگی در همان مخزن langchain نگه‌داری می‌شوند، ولی هر کدام با تگ مجزایی منتشر می‌شوند. در تگ 1.5.0 برای langchain، پکیج OpenAI موجود در درخت مخزن هنوز نسخه‌ی 1.7.4 است {{code libs/partners/openai/pyproject.toml}}. نسخه‌های 1.0.8 برای langchain-classic و 0.4.2 برای langchain-community از PyPI گرفته شده‌اند، نه از نسخه‌های ثبت‌شده در مخزن.

پکیج‌های langgraph، langgraph-prebuilt، langgraph-checkpoint و langgraph-checkpoint-postgres در نسخه‌های پین‌شده، همگی از یک commit واحد با چهار شماره نسخه‌ی متفاوت تولید شده‌اند. شکل پیش‌نیازهای هر پکیج را نشان می‌دهد.

نیازمندی‌های هر بسته در نسخه‌ی پین‌شدهنصب deepagents بسته‌های langchain، دو بسته ارائه‌دهنده و langsmith را می‌آورد، و نصب langchain بسته langgraph را می‌آورد که خود به langchain-core نیاز دارد.
نیازمندی‌های هر بسته در نسخه پین‌شده درخت وابستگی. بسته deepagents 0.7.38 به langchain 1.5 یا بالاتر، langchain-anthropic 1.7.10 یا بالاتر، langchain-google-genai 4.4.3 یا بالاتر، و langsmith 0.14.17 یا بالاتر نیاز دارد. بسته langchain 1.5.0 به langchain-core 1.8 یا بالاتر و langgraph از 1.2.12 تا کمتر از 1.3 نیاز دارد، با بسته‌های اختیاری openai، anthropic، ollama و mcp که با خط‌چین نشان داده شده‌اند. بسته langgraph 1.2.22 به langchain-core 1.4.7 یا بالاتر، langgraph-checkpoint 4.3 تا کمتر از 5، langgraph-prebuilt 1.1 تا کمتر از 1.2، و langgraph-sdk 0.4.6 تا کمتر از 0.5 نیاز دارد. بسته langchain-core 1.8.0 به langsmith 0.14.9 تا کمتر از 1، langchain-protocol 0.0.20 یا بالاتر، و pydantic 2.7.4 تا کمتر از 3 نیاز دارد. deepagents 0.7.38 بستر آزمایشی اختیاری langchain 1.5.0 create_agent extras openai, ollama, mcp دو ارائه‌دهنده anthropic, google-genai langgraph 1.2.22 >=1.2.12,<1.3.0 langchain-core 1.8.0 >=1.8.0,<2 checkpoint 4.3.2 >=4.3.0,<5 prebuilt 1.1.2 >=1.1.0,<1.2.0 sdk 0.4.14 >=0.4.6,<0.5.0 langsmith 0.14.17 >=0.14.9,<1 langchain-protocol >=0.0.20 pydantic 2.14.3 >=2.7.4,<3 فلش‌ها به معنای نیازمندی هستند، با بازه مشخص‌شده زیر هر نام. deepagents also requires langsmith >=0.14.17 and langchain >=1.5.0.
هر فلش به معنای «نیاز دارد» است، همراه با بازه‌ای که بسته اعلام می‌کند. کادرهای خاکستری خارج از LangChain هستند. کادرهای خط‌چین بسته‌های جانبی اختیاری هستند. برگرفته از فهرست‌های requires_dist در PyPI برای هر نسخه و capture/out/00-versions.txt.

چه چیزهایی جابه‌جا شدند

بخش‌های قدیمی در نسخه‌ی 1.0 از پکیج langchain جدا شدند و سه مخزن نیز در سال 2026 بایگانی (archive) شدند.

  • زنجیره‌ها و ایجنت‌های قدیمی: کلاس‌های LLMChain، AgentExecutor، رابط کاربری نمایه‌سازی (indexing API)، و ماژول hub همگی در پکیج langchain-classic و زیر ماژول langchain_classic قرار دارند {{code libs/langchain/langchain_classic}}.
  • یکپارچه‌سازی‌های جامعه‌ی کاربری (Community integrations): پکیج langchain-community نسخه‌ی 0.4.2 آخرین نسخه‌ی منتشرشده است و مخزن آن بایگانی شده است. فایل README آن اعلام می‌کند که توسعه‌ی پکیج به پایان رسیده است {{issue langchain-community README}}. این پکیج هنوز نصب می‌شود و همچنان به langchain-classic وابستگی دارد.
  • تطبیق‌دهنده‌ی MCP: مخزن langchain-mcp-adapters بایگانی شده است. طبق فهرست تغییرات (changelog)، از نسخه‌ی 1.4.0 پکیج langchain، ماژول langchain.mcp جایگزین آن شده است {{docs oss/python/releases/changelog}}. در نسخه‌های پین‌شده، بسته‌ی اضافیِ langchain[mcp] آن را نصب می‌کند. هرگز هر دوی آن‌ها را در یک محیط نصب نکنید، چون تطبیق‌دهنده‌ی قدیمی به نسخه‌های زیر 2 پکیج mcp نیاز دارد.
  • مخزن LangSmith SDK: مخزن langsmith-sdk بایگانی شده و کلاینت پایتون آن اکنون در langsmith-python نگه‌داری می‌شود. نام پکیج در pip دست‌نخورده مانده و همچنان langsmith است.

تابع create_react_agent از مسیر langgraph.prebuilt هنوز قابل import است، اما هشدار می‌دهد که به create_agent منتقل شده است. بخش 1.3 ایجنت جایگزین آن را معرفی می‌کند.

پایتون 3.11

کف نسخه‌ی پایتون (Python floor): قدیمی‌ترین نسخه‌ی پایتونی است که یک پکیج در فیلد requires-python خود مشخص می‌کند.

مستندات رسمی و پکیج‌ها درباره‌ی این کف نسخه اتفاق نظر ندارند. در صفحه‌ی راهنمای نصب، دستور pip install -U langchain آمده و در توضیحات نوشته شده به Python 3.10 یا بالاتر نیاز است {{docs oss/python/langchain/install}}. اما مدخل فهرست تغییرات برای نسخه‌ی 1.5 پکیج langchain می‌گوید حداقل نسخه، Python 3.11 است {{docs oss/python/releases/changelog}}. متادیتای پکیج‌ها گفته‌ی فهرست تغییرات را تأیید می‌کند: langchain 1.5.0 و langchain-core 1.8.0 رسماً Python 3.11 یا بالاتر را الزامی کرده‌اند {{code libs/langchain_v1/pyproject.toml}}. این در حالی است که langgraph 1.2.22 هنوز نسخه‌ی 3.10 را اعلام می‌کند.

این کتابچه متادیتای پکیج‌ها را ملاک قرار می‌دهد که رتبه‌اش بالاتر از هر دو صفحه‌ی مستندات است. روی Python 3.10، اجرای pip install langchain نسخه‌های 1.4.x را برمی‌گزیند و هیچ هشداری هم دریافت نمی‌کنید که نسخه‌ی قدیمی‌تری گرفته‌اید. از Python 3.11 یا بالاتر استفاده کنید. محیط ضبط این راهنما از نسخه‌ی 3.13 استفاده می‌کند.

همین تغییر، یکی از قوانین صفحه‌ی سیاست انتشار (release policy) را هم نقض می‌کند. آن صفحه می‌گوید کف نسخه‌ی پایتون تنها در انتشارهای اصلی (major) تغییر می‌کند {{docs oss/python/release-policy}}. در حالی که langchain 1.5.0 یک انتشار فرعی به شمار می‌رود. در دفتر ثبت این کتابچه، این مغایرت با عنوان تعارض D101 آمده است.

یک فایل قفل

انتشار فرعی یک پکیج می‌تواند رفتار کدی را که می‌نویسید تغییر دهد. برای نمونه، در نسخه‌ی 1.7.0 از langchain-core، رویدادهای مربوط به فراخوانی ابزار (tool call) در استریمینگ تغییر کرد. مدخل فهرست تغییرات آن نسخه تذکر می‌دهد که برای حفظ ساختار قبلی، باید پکیج را روی نسخه‌های پایین‌تر از 1.7 قفل کنید {{docs oss/python/releases/changelog}}. همچنین طبق تاریخ‌های انتشار PyPI، پکیج langgraph سه نسخه‌ی 1.2.20، 1.2.21 و 1.2.22 را تنها ظرف 9 روز منتشر کرد.

بنابراین، تمام پکیج‌های این مجموعه را روی یک نسخه‌ی دقیق قفل کنید. کیت ضبط این دوره، 25 پکیج را در فایل capture/requirements.txt پین کرده و موارد نصب‌شده را ثبت می‌کند:

نسخه‌های نصب‌شده توسط کیت ضبط capture/out/00-versions.txt
python 3.13

langchain==1.5.0
langchain-core==1.8.0
langgraph==1.2.22
langgraph-checkpoint==4.3.2
langgraph-prebuilt==1.1.2
langgraph-checkpoint-sqlite==3.1.3
deepagents==0.7.38
langsmith==0.14.17
fastmcp==4.2.0
mcp==2.3.0
langchain-text-splitters==1.1.3
langchain-openai==1.8.0
langchain-anthropic==1.7.10
langchain-ollama==1.1.0
…

چهارده خط اول پس از نسخه Python. پین‌های بازگشتی (transitive) حذف شده‌اند.

پکیج deepagents نسخه‌ی 0.7.38 به langchain-anthropic و langchain-google-genai نیاز دارد. مدل پیش‌فرضِ منسوخ‌شده‌ی آن Claude است {{code libs/deepagents/deepagents/graph.py}}. بنابراین فقط زمانی نصبش کنید که واقعاً می‌خواهید از آن استفاده کنید.

برای ساخت ایجنتی با یک مدل OpenAI، نصب روی نسخه‌های پین‌شده به این ترتیب خواهد بود:

python3.13 -m venv .venv
.venv/bin/pip install "langchain==1.5.0" "langchain-core==1.8.0" "langgraph==1.2.22" "langchain-openai==1.8.0"
.venv/bin/pip freeze > requirements.lock

سپس در همه‌ی سیستم‌های دیگر هم بسته‌ها را از روی requirements.lock نصب کنید تا همه‌جا نسخه‌های کاملاً یکسانی مستقر شوند.

حجم نصب و زمان import

ما اندازه‌گیری کردیم: دو نصب کاملاً تازه را روی سیستم‌عامل مک با قیدهای یکسان از فایل قفل، و پیش از آنکه با اجرای پکیجی بایت‌کد تولید شود، سنجیدیم. پکیج openai به‌تنهایی 14 پکیج با حجم کلی 26,356 کیلوبایت نصب کرد. در حالی که langchain به همراه langchain-openai، تعداد 44 پکیج با حجم 54,312 کیلوبایت نصب کرد.

ما زمان import را اندازه‌گیری کردیم: روی مک، 10 بار اجرای هر فرایند import را در یک فرایند (process) مستقل سنجیدیم. شکل هر اجرا را نشان می‌دهد. وقتی بایت‌کد از قبل آماده بود، میانه‌ی زمان اجرای import openai برابر با 0.329 ثانیه شد و زمان import برای create_agent به همراه ChatOpenAI به 0.831 ثانیه رسید. اما بدون وجود بایت‌کد، این زمان‌ها به ترتیب 1.064 ثانیه و 2.64 ثانیه بودند. لپ‌تاپ مک مورد استفاده اشتراکی بوده است، بنابراین این ارقام را به چشم حد بالا (upper bound) ببینید.

زمان ایمپورت چهار ماژول، 10 اجرا برای هرکدامایمپورت‌ها برای create_agent با ChatOpenAI حدود 0.8 ثانیه در حالت گرم و 2.6 ثانیه بدون بایت‌کد زمان می‌برند، یعنی حدود دو و نیم برابر زمان ایمپورت تنهای openai.
زمان ایمپورت چهار ماژول، 10 اجرا برای هرکدام نمودار نقطه‌ای زمان ایمپورت بر حسب ثانیه روی Mac، با 10 اجرا از هر ایمپورت در یک فرایند جدید Python؛ با بایت‌کد روی دیسک در سمت چپ و بدون بایت‌کد در سمت راست. میانه‌ها با بایت‌کد: دستور pass معادل 0.023 ثانیه، import openai معادل 0.329 ثانیه، StateGraph در langgraph معادل 0.477 ثانیه، و create_agent با ChatOpenAI معادل 0.831 ثانیه. میانه‌ها بدون بایت‌کد: 0.063 ثانیه، 1.064 ثانیه، 1.85 ثانیه، و 2.64 ثانیه. 0 0.5 1 1.5 2 2.5 3 ثانیه با بایت‌کد روی دیسک بدون بایت‌کد 0.023 pass 0.329 openai 0.477 langgraph 0.831 agent 0.063 pass 1.064 openai 1.85 langgraph 2.64 agent pass: an empty program. agent: create_agent with ChatOpenAI. هر نقطه یک اجرا در Mac است. هر خط کوتاه میانه 10 اجراست.
هر نقطه نشان‌دهنده یک اجرا در یک فرایند جدید Python روی Mac است. هر خط کوتاه میانه ده اجراست. گروه سمت چپ دارای بایت‌کد روی دیسک بودند و گروه سمت راست بدون بایت‌کد بودند. برگرفته از capture/lab/summary/import-times-mac.json.

زمان import معادل 2.6 ثانیه در یک تابع سرورلس (serverless) یا در یک ابزار خط فرمان (CLI) که با هر فراخوانی از نو آغاز به کار می‌کند، تفاوت بزرگی ایجاد می‌کند. پکیج‌ها را فقط یک بار در زمان راه‌اندازی (start-up) فراخوانی کنید و فایل‌های بایت‌کد را داخل ایمیج نگه دارید.

منابع: capture/out/00-versions.txt، capture/requirements.txt؛ capture/lab/summary/install-size-mac.json، capture/lab/summary/import-times-mac.json، capture/lab/T01-overhead-mac/07-install-size.txt، capture/lab/T01-overhead-mac/06-import-times.jsonl؛ سایت docs.langchain.com در commit شماره‌ی 04d4d4a مستندات (مسیرهای oss/python/langchain/install، oss/python/releases/changelog، oss/python/release-policy)؛ فایل‌های libs/langchain_v1/pyproject.toml، libs/partners/openai/pyproject.toml و libs/langchain/langchain_classic در langchain==1.5.0؛ libs/deepagents/deepagents/graph.py در deepagents==0.7.38؛ دیتای JSON پکیج‌ها در PyPI و فایل‌های README بایگانی‌شده‌ی langchain-community، langchain-mcp-adapters و langsmith-sdk، خوانده‌شده در 2026-11-14.

ترجمه‌ی فارسی Install and the package map از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما