بخش 8.5 · بهره‌برداری و نگهداری

مهاجرت از نسخه‌ی 0.x و توصیه‌های منسوخ

Migration from 0.x, and stale advice

فهرست مطالب
  1. بازه‌ی زمانی پشتیبانی
  2. تغییر مسیر Importها
  3. از create_react_agent به create_agent
  4. تغییرات نام‌گذاری در LangGraph
  5. صفحات منسوخ در مستندات
  6. نوت‌بوک‌ها و آموزش‌های قدیمی

بخش عمده‌ی کدهای نسخه‌ی 0.x به پکیج langchain-classic منتقل شده یا نامشان تغییر کرده است. از طرفی آموزش‌ها، نوت‌بوک‌ها و برخی صفحات مستندات هنوز پر از توصیه‌های قدیمی هستند؛ بنابراین تک‌تک importها را با نسخه‌های قفل‌شده تطبیق دهید.

پروژه‌ای از سال 2024 را باز می‌کنید. در این پروژه، AgentExecutor از langchain.agents، یک لودر از langchain_community و MultiServerMCPClient از langchain_mcp_adapters ایمپورت شده‌اند. روی نسخه‌ی 1.5.0 پکیج langchain، اولین import با خطا مواجه می‌شود، دومی از پکیجی می‌آید که دوره‌ی پشتیبانی‌اش تمام شده و سومی با langchain[mcp] تداخل دارد.

با پایان این بخش، می‌توانید کدهای نسخه‌ی 0.x را به نام‌های 1.x منتقل کنید و صفحات یا نوت‌بوک‌های قدیمی را از منابع به‌روز تشخیص دهید.

بازه‌ی زمانی پشتیبانی

بر اساس سیاست انتشار رسمی {{docs oss/python/release-policy}}، نسخه‌ی 0.3 فریم‌ورک LangChain تا دسامبر 2026 در فاز نگهداری باقی می‌ماند. این شاخه هنوز نسخه دریافت می‌کند: طبق تاریخ‌های انتشار در PyPI، نسخه‌های langchain 0.3.30 و langchain-core 0.3.86 در تاریخ 2026-05-07 منتشر شدند. نسخه‌ی langchain 0.3.30 شامل مقاوم‌سازی توابع loads و dumps است و langchain-core 0.3.86 آسیب‌پذیری پیمایش مسیر (path traversal) با شناسه‌ی CVE-2026-34070 را برطرف می‌کند. بنابراین کدهای 0.3 امروز هم اجرا می‌شوند، اما اصلاحات امنیتی آن‌ها پس از سال 2026 متوقف خواهد شد.

همین سیاست تصریح می‌کند که ارتقای جزئی (minor) در شاخه‌ی 1.x هیچ کدی را نمی‌شکند. با این حال، دو انتشار جزئی شرایط متفاوتی برای ارتقادهندگان ایجاد کردند: نسخه‌ی langchain 1.5.0 حداقل نسخه‌ی Python را به 3.11 افزایش داد (همان‌طور که در بخش 3.1 آمده است) و نسخه‌ی langchain-core 1.7.0، بر اساس یادداشت‌های انتشار، آرگومان‌های استریم‌شده‌ی فراخوانی ابزار (streamed tool call arguments) را از اسنپ‌شات به برش‌ها تغییر داد. نسخه‌ها را در یک فایل قفل تثبیت کنید و قبل از ارتقای هر نسخه‌ی جزئی، گزارش تغییرات آن را بخوانید.

شاخه‌ی پکیج حداقل نسخه‌ی Python
0.3 3.9
langchain از 1.0 تا 1.4 و langchain-core از 1.0 تا 1.7 طبق متادیتای PyPI {{site pypi.org/project/langchain}} 3.10
langchain 1.5.0، langchain-core 1.8.0، langchain-openai 1.8.0 و deepagents 0.7.38 3.11
langchain-anthropic 1.7.10 و langchain-ollama 1.1.0 3.10
langgraph 1.2.22، چک‌پوینترهای آن و langsmith 0.14.17 3.10

تغییر مسیر Importها

نحوه‌ی فراخوانی در 0.x در نسخه‌ی قفل‌شده بخش مربوطه
from langchain.chains import LLMChain به langchain_classic.chains منتقل شده؛ از نسخه‌ی 0.1.17 منسوخ شده و در 2.0.0 به‌طور کامل حذف می‌شود {{code libs/langchain/langchain_classic/chains/llm.py}} 3.1
from langchain.agents import AgentExecutor, initialize_agent در langchain_classic.agents قرار گرفته و initialize_agent منسوخ است. ایجنت‌های جدید از langchain.agents.create_agent استفاده می‌کنند 4.1
from langchain import hub در langchain_classic.hub؛ توابع push و pull آن منسوخ شده‌اند و باید از LangSmith SDK استفاده کرد {{code libs/langchain/langchain_classic/hub.py}} 3.5
langchain.retrievers.MultiQueryRetriever, RetrievalQA به langchain-classic منتقل شده‌اند. کلاس BaseRetriever در langchain_core.retrievers باقی مانده است 7.1
langchain_community.* پشتیبانی آن در نسخه‌ی 0.4.2 تمام شده و مخزن آن آرشیو است. در صورت وجود، از پکیج اختصاصی ارائه‌دهنده (provider package) استفاده کنید 3.1
from langchain_mcp_adapters.client import MultiServerMCPClient در نسخه‌ی بتای langchain.mcp.MCPAdapter که با langchain[mcp] نصب می‌شود 7.3
from langgraph.prebuilt import create_react_agent به langchain.agents.create_agent منتقل شده؛ تابع قبلی هنوز ایمپورت می‌شود ولی هشدار می‌دهد 4.1
from langgraph.checkpoint.memory import MemorySaver به InMemorySaver تغییر یافته؛ MemorySaver همچنان به‌عنوان یک نام مستعار (alias) فعال مانده است {{code libs/checkpoint/langgraph/checkpoint/memory/init.py}} 5.2
from langgraph.errors import NodeInterrupt به langgraph.types.interrupt تغییر یافته و با Command(resume=...) از سر گرفته می‌شود 6.4
from langgraph.constants import Send به from langgraph.types import Send تغییر یافته است 6.2

مخزن LangSmith SDK نیز به langchain-ai/langsmith-python منتقل شده، اما نام پکیج langsmith تغییر نکرده است.

از create_react_agent به create_agent

راهنمای مهاجرت در انتشار v1، تک‌تک آرگومان‌های تغییریافته را فهرست کرده است {{docs oss/python/migrate/langchain-v1}}. ما تمام سطرها را بر اساس کد در نسخه‌ی قفل‌شده تطبیق داده‌ایم.

create_react_agent create_agent
prompt= system_prompt=، به‌صورت یک رشته یا SystemMessage
پرامپت قابل فراخوانی (callable) میان‌افزار (middleware) با دکوراتور @dynamic_prompt
قلاب‌های pre_model_hook و post_model_hook میان‌افزارهای before_model و after_model
وضعیت از نوع Pydantic یا dataclass استفاده از TypedDict که AgentState را از طریق state_schema گسترش می‌دهد
انتخاب مدل از طریق تابعی قابل فراخوانی میان‌افزار wrap_model_call به همراه request.override(model=...)
مدلی که متد bind_tools از قبل روی آن صدا زده شده در امضای تابع جایی ندارد (ورودی فقط یک رشته یا چت‌مدل می‌گیرد) و بررسی هم نمی‌شود؛ مدل خام و ابزارها را ارسال کنید
ToolNode(handle_tool_errors=...) استفاده از ToolErrorMiddleware(on_error) یا میان‌افزار wrap_tool_call
آرگومان response_format در یک نود نهایی مجزا خروجی ساختاریافته در حلقه‌ی اصلی، با استفاده از ToolStrategy، ProviderStrategy یا AutoStrategy
نام نود agent هنگام استریمینگ model
داده‌های ایستا در config["configurable"] پارامتر context= در متد invoke با تعیین نوع از طریق context_schema
حد بازگشت (recursion limit) در LangGraph 9999 مرحله، که توسط create_agent تعیین می‌شود {{code libs/langchain_v1/langchain/agents/factory.py}}

بخش 4.1 گرافی را نشان می‌دهد که create_agent می‌سازد و بخش 4.5 جایگزین‌های قلاب‌های قبلی را معرفی می‌کند.

تغییرات نام‌گذاری در LangGraph

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

‏checkpoint_during در پین capture/out/31-durability.txt
warning LangGraphDeprecatedSinceV10: `checkpoint_during` is deprecated and will be removed. Please use `durability` instead. Deprecated in LangGraph V1.0 to be removed in V2.0.

دومی زمانی رخ می‌دهد که خروجی invoke(version="v2") را به‌صورت دیکشنری بخوانید:

خواندن دیکشنری از GraphOutput capture/out/24-stream-v2.txt
warning LangGraphDeprecatedSinceV11: Accessing GraphOutput via `result[key]` is deprecated. Use `result.value` to access the output value directly, or `result.interrupts` for interrupts. Deprecated in LangGraph V1.1 to be removed in V3.0.

سه تغییر دیگر هیچ هشداری نمی‌دهند و کدهای قدیمی آن‌ها را اشتباه تفسیر خواهند کرد:

  • حد بازگشت: توصیه‌های قدیمی عدد 25 را نام می‌برند. در نسخه‌ی قفل‌شده، StateGraph در 10007 مرحله متوقف می‌شود و create_agent در 9999 مرحله. بخش 6.8 هر دو را پوشش می‌دهد.
  • Interrupt: فیلدهای ns، when و resumable حذف شده‌اند و در نسخه‌ی 0.6.0، فیلد interrupt_id جای خود را به id داد {{code libs/langgraph/langgraph/types.py}}.
  • پکیج Deep Agents 0.7.0: تابع create_deep_agent دیگر میان‌افزار TodoListMiddleware را اضافه نمی‌کند؛ بنابراین write_todos ابزار پیش‌فرض نیست. مجموعه‌ی ابزارهای پیش‌فرض را در بخش 7.4 ببینید.

صفحات منسوخ در مستندات

سایت مستندات LangChain همواره branch اصلی خود را نمایش می‌دهد؛ بنابراین اغلب صفحات وضعیت قفل‌شده یا نسخه‌های جدیدتر را توصیف می‌کنند. ما تمام صفحات ذخیره‌شده‌ی مستندات را برای نام‌های قدیمی مثل AgentExecutor، initialize_agent، create_react_agent، MultiServerMCPClient و LangGraph Platform جستجو کردیم. دو مورد اول و نام‌های پلتفرم قدیمی هیچ نتیجه‌ای نداشتند و بقیه فقط در صفحات مهاجرت و گزارش انتشار آمدند که جای درستشان است.

صفحات زیر در commit شماره‌ی 04d4d4a مستندات هنوز محتوای قدیمی را آموزش می‌دهند. برای هرکدام یک ورودی در جدول تداخلات این راهنما ثبت شده است:

صفحه بخش منسوخ شناسه‌ی تداخل
oss/python/langchain/install و oss/python/release-policy معرفی Python 3.10 به‌عنوان حداقل نسخه D101
oss/python/releases/langchain-v1 فهرست ارائه‌دهندگان دارای content block و جدول namespace بدون langchain.mcp D117
هر دو صفحه‌ی انتشار v1 لینکی برای create_react_agent که به تابع هم‌نام خود در langchain-classic اشاره دارد D107
langsmith/faq جدولی که چک‌پوینترها را کد جامعه‌ی کاربری و استریمینگ را ابتدایی معرفی می‌کند D108
langsmith/manage-prompts-programmatically کار با hub از طریق langchain_classic و پایپ کردن پرامپت به مدل D113
langsmith/trace-with-langchain ارائه‌ی زنجیره‌ی LCEL به‌عنوان اولین مثال D114
oss/python/deepagents/overview برنامه‌ریزی (planning) به‌عنوان قابلیت پیش‌فرض در اولین پاراگراف D109
oss/python/langgraph/local-server نام قدیمی LangGraph Studio D116

نوت‌بوک‌ها و آموزش‌های قدیمی

یک نوت‌بوک یا آموزش، روی همان نسخه‌هایی اجرا می‌شود که نویسنده‌اش آن‌ها را قفل کرده است. تعیین حداقل نسخه مثل langchain>=0.3.9 باعث می‌شود pip نسخه‌ی 1.5.0 را نصب کند؛ در نتیجه کد روی شاخه‌ای اجرا می‌شود که نویسنده هرگز آن را آزمایش نکرده است. ابتدا فایل قفل را بخوانید، سپس کد را طوری اجرا کنید که هشدارها نمایش داده شوند. جدول نام‌های منتقل‌شده در بالا راهکار هر نام قدیمی را آورده است.

دو مورد از این نام‌های قدیمی در نسخه‌ی قفل‌شده همچنان ایمپورت می‌شوند و هشدار می‌دهند: NodeInterrupt هشدار منسوخ‌شدن می‌دهد و به interrupt ارجاع می‌دهد {{code libs/langgraph/langgraph/errors.py}}. ایمپورت Send از langgraph.constants نیز هشدار داده و به langgraph.types هدایت می‌کند {{code libs/langgraph/langgraph/constants.py}}.

تعریف ایستای interrupt_before روی متد compile منسوخ نشده است، چون compile هنوز آن را می‌پذیرد {{code libs/langgraph/langgraph/graph/state.py}}. اول interrupt() را آموزش دهید و interrupt_before را برای خطایابی نگه دارید.

منابع: capture/out/31-durability.txt، capture/out/24-stream-v2.txt؛ libs/langchain/langchain_classic/chains/llm.py، libs/langchain/langchain_classic/hub.py، libs/langchain/langchain_classic/agents/initialize.py و libs/langchain_v1/langchain/agents/factory.py در langchain==1.5.0؛ libs/langgraph/langgraph/types.py، libs/langgraph/langgraph/errors.py، libs/langgraph/langgraph/constants.py، libs/langgraph/langgraph/graph/state.py، libs/prebuilt/langgraph/prebuilt/chat_agent_executor.py و libs/checkpoint/langgraph/checkpoint/memory/init.py در langgraph 1.2.22؛ انتشارهای گیت‌هاب langchain==0.3.30، langchain-core==0.3.86، langchain-core==1.7.0، langchain==1.5.0 و deepagents==0.7.0؛ سایت docs.langchain.com در commit مستندات به شماره‌ی 04d4d4a (شامل oss/python/migrate/langchain-v1، oss/python/migrate/langgraph-v1، oss/python/release-policy، oss/python/releases/changelog و صفحات جدول منسوخات).

ترجمه‌ی فارسی Migration from 0.x, and stale advice از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما