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

تابع init_chat_model و پروفایل مدل‌ها

init_chat_model and model profiles

فهرست مطالب
  1. رشته‌های مدل
  2. پروفایل مدل‌ها
  3. تلاش‌های مجدد

متد init_chat_model رشته‌ی provider:model را به یک مدل چت از پکیج همان ارائه‌دهنده (provider) تبدیل می‌کند؛ و این خود آن پکیج است — نه LangChain — که تصمیم می‌گیرد فراخوانی ناموفق چند بار دوباره تلاش (retry) شود.

رشته‌ی "qwen3:4b" را به create_agent می‌دهید و پیش از اولین درخواست، با یک ValueError روبه‌رو می‌شوید. یا مهلت زمانی (timeout) کلاینت را روی 15 ثانیه می‌گذارید، اما فراخوانی‌ای که مدام تایم‌اوت می‌دهد، بعد از 46.3 ثانیه خروجی برمی‌گرداند. هر دو رفتار به نحوه‌ی تبدیل رشته‌ی مدل (model string) و لایه‌ای که تلاش مجدد را انجام می‌دهد برمی‌گردند.

با پایان این بخش، می‌توانید رشته‌های مدلی بنویسید که به‌درستی شناسایی شوند و پروفایل یک مدل را بخوانید. همچنین می‌توانید تعداد تلاش‌های یک فراخوانی ناموفقِ مدل را بشمارید.

رشته‌های مدل

رشته‌ی مدل (Model string): شکل متنی یک مدل، مانند openai:gpt-4.1، که init_chat_model و create_agent به‌جای شیء مدل می‌پذیرند.

مستندات قالب آن را به‌صورت ارائه‌دهنده، دونقطه و مدل مشخص کرده است، مانند openai:o1 {{docs oss/python/langchain/models}}. متد init_chat_model تنها زمانی رشته را از محل اولین دونقطه جدا می‌کند که بخش پیش از آن، یکی از 30 ارائه‌دهنده‌ی شناخته‌شده باشد {{code libs/langchain_v1/langchain/chat_models/base.py}}. سپس کلاس مربوط را از پکیج ارائه‌دهنده ایمپورت می‌کند:

سه رشته‌ی مدل و کلاسی که هر یک ساخت capture/out/01-init-chat-model.txt
openai:gpt-4.1 -> langchain_openai.chat_models.base.ChatOpenAI
…
anthropic:claude-sonnet-4-6 -> langchain_anthropic.chat_models.ChatAnthropic
…
ollama:qwen3:4b -> langchain_ollama.chat_models.ChatOllama

به سه خط نتیجه خلاصه شده است. پروفایل‌های بین آن‌ها حذف شده‌اند.

اگر پیشوند شناخته‌شده‌ای وجود نداشته باشد، init_chat_model ارائه‌دهنده را از روی ابتدای نام حدس می‌زند. پیشوندهای gpt- و o3 به‌معنای OpenAI هستند و claude به‌معنای Anthropic است. اگر نام مدل با هیچ قاعده‌ای نخواند، بلافاصله خطا می‌دهد:

نامی بدون ارائه‌دهنده‌ی شناخته‌شده capture/out/01-init-chat-model.txt
init_chat_model('qwen3:4b'):

raised builtins.ValueError: Unable to infer model provider for model='qwen3:4b'. Please specify 'model_provider' directly.

فهرست ارائه‌دهندگان و خط راهنما حذف شده‌اند.

بنابراین ollama:qwen3:4b کار می‌کند اما qwen3:4b نه. دونقطه‌ی درون تگ Ollama بخشی از نام مدل است، چون رشته فقط از محل اولین دونقطه جدا می‌شود. تصویر این سه مسیر را نشان می‌دهد.

نحوه‌ی تفکیک رشته‌ی مدل توسط init_chat_modelیک پیشوند شناخته‌شده ارائه‌دهنده را تعیین می‌کند، سپس شروع نامِ شناخته‌شده آن را برمی‌گزیند، و هر رشته‌ی دیگری قبل از ارسال درخواست خطای ValueError می‌دهد.
نحوه‌ی تفکیک رشته‌ی مدل توسط init_chat_model نمودار تصمیم‌گیری با سه بررسی به ترتیب. اول، آیا بخش قبل از اولین دونقطه ارائه‌دهنده‌ای شناخته‌شده است؟ openai:gpt-4.1 و ollama:qwen3:4b بله هستند و ChatOpenAI و ChatOllama را می‌سازند. دوم، آیا نام با پیشوندی شناخته‌شده مانند gpt-، o3 یا claude آغاز می‌شود؟ gpt-4.1-mini و claude-haiku-4-5 بله هستند و ChatOpenAI و ChatAnthropic را می‌سازند. سوم، هر رشته‌ی دیگری مانند qwen3:4b قبل از هر درخواستی خطای ValueError: Unable to infer model provider می‌دهد. پیشوند ارائه‌دهنده شناخته‌شده است؟ بخش قبل از اولین دونقطه ollama:qwen3:4b ChatOllama، مدل qwen3:4b شروع نام شناخته‌شده است؟ gpt-، o1، o3، claude، gemini claude-haiku-4-5 ChatAnthropic qwen3:4b ValueError: Unable to infer بله بله no no qwen3 ارائه‌دهنده شناخته‌شده نیست، پس فقط اولین دونقطه‌ی ollama:qwen3:4b جدا می‌شود. خطا قبل از رسیدن هرگونه درخواست به ارائه‌دهنده رخ می‌دهد.
از بالا بخوانید. هر سطر یک بررسی به ترتیب اجرای کد است، به همراه رشته‌ای از خروجی ذخیره‌شده در مسیری که طی می‌کند. برگرفته از capture/out/01-init-chat-model.txt.

فراخوانی init_chat_model بدون تعیین مدل و با آرگومان configurable_fields، یک _ConfigurableModel برمی‌گرداند. مدل این شیء در زمان اجرا از روی پیکربندی (config) و ذیل پیشوندی که تعیین می‌کنید (مانند llm_model) انتخاب می‌شود.

پروفایل مدل‌ها

پروفایل مدل (Model profile): یک دیکشنری در model.profile شامل محدودیت‌ها و امکانات یک مدل، مانند اندازه بافت (context size) و پشتیبانی از خروجی ساختاریافته (structured output).

پکیج‌های ارائه‌دهنده، پروفایل‌ها را از فایل‌های داده‌ای درون همان پکیج می‌خوانند. بخشی از پروفایل gpt-4.1 به این صورت است:

بخشی از پروفایل openai:gpt-4.1 capture/out/01-init-chat-model.txt
  "max_input_tokens": 1047576,
  "max_output_tokens": 32768,
…
  "tool_calling": true,
  "structured_output": true,
…
  "tool_call_streaming": true,
…
  "mid_conversation_tools": false

به محدودیت‌های اندازه و چهار قابلیت خلاصه شده است.

پروفایل ollama:qwen3:4b مقدار null است و پروفایل مدل ChatOllama در کیت هم همین‌طور است. کدی که پروفایل را می‌خواند باید مقدار None را بپذیرد. متد create_agent مقدار structured_output را از آن می‌خواند تا راهبرد خروجی ساختاریافته را تعیین کند؛ موضوعی که در بخش 4 توضیح داده شده است.

تلاش‌های مجدد

لایه‌ی تلاش مجدد (Retry layer): بخشی از کد که پس از خطا، مدل را دوباره فراخوانی می‌کند. کلاینت درون پکیجِ ارائه‌دهنده یک لایه است و ModelRetryMiddleware لایه‌ای دیگر.

صفحه‌ی مدل‌ها در مستندات می‌گوید که یک مدل چت به‌طور پیش‌فرض برای خطاهای شبکه، کدهای 429 و 5xx تا 6 بار تلاش مجدد انجام می‌دهد {{docs oss/python/langchain/models}}. صفحه‌ی میدل‌ور تلاش مجدد هم می‌گوید که در حالت پیش‌فرض در مجموع 3 بار تلاش می‌کند {{docs oss/python/langchain/middleware/built-in}}. ما هر دو مورد را روی نسخه‌ی پین‌شده سنجیدیم.

ما تعداد تلاش‌ها را روی ماشین مهمان سرور x86 اندازه گرفتیم؛ 3 بار اجرا برای هر سلول جدول. کلاس ChatOpenAI از نسخه‌ی 1.8.0 پکیج langchain-openai، مدل Qwen3 4B را روی مسیر /v1 در Ollama فراخوانی کرد. یک رله (relay) جلوی Ollama قرار گرفت که اتصال‌ها را قطع می‌کرد یا آن‌ها را تا بعد از پایان مهلت زمانی نگه می‌داشت.

برای بررسی خطای اتصال ردشده (refused connection)، هیچ سرویسی روی پورت گوش نمی‌داد. ChatOllama هم مسیر محلی (native) Ollama را به همین ترتیب فراخوانی کرد. تعداد دفعات در هر 3 اجرا یکسان بود. تصویر هر اجرا را نشان می‌دهد.

نوع خرابی در رله پیش‌فرض کلاینت فقط میدل‌ور هر دو لایه
قطع اتصال در هر فراخوانی 3 تلاش، سپس OpenAIConnectionError 3 تلاش، سپس یک AIMessage 9 تلاش
رد اتصال در هر فراخوانی 3 تلاش، سپس OpenAIConnectionError 3 تلاش، سپس یک AIMessage 9 تلاش
تایم‌اوت در هر فراخوانی 3 تلاش، سپس OpenAITimeoutError 3 تلاش، سپس یک AIMessage 9 تلاش
خطای واقعی 404 در Ollama برای مدل ناشناخته 1 تلاش، سپس OpenAIModelNotFoundError 1 تلاش 1 تلاش
ChatOllama، هریک از خطاهای بالا 1 تلاش، سپس خطای کلاینت ollama 3 تلاش، سپس یک AIMessage، برای 404 هم به همین شکل بدون لایه‌ی کلاینت

تنظیمات پیش‌فرض کلاینت در ChatOpenAI تعداد 3 تلاش انجام داد که یعنی 2 بار تلاش مجدد. کلاس ChatOpenAI مقدار max_retries را به کلاینت openai می‌سپارد که پیش‌فرض آن 2 است {{code libs/partners/openai/langchain_openai/chat_models/base.py}}. همین 3 تلاش از فراخوانی init_chat_model("openai:...") هم ثبت شد. عدد 6 موجود در مستندات برای این پکیج صادق نبود. ChatOllama هم 1 تلاش انجام داد، چون کلاینت ollama تلاش مجددی ندارد.

وقتی هر دو لایه فعال باشند، اثر لایه‌ها در هم ضرب می‌شود. هرکدام از 3 تلاش میدل‌ور، باعث 3 تلاش کلاینت شد. تایم‌اوت کلاینت 15 ثانیه بود و رله هر درخواست را 20 ثانیه نگه می‌داشت. بنابراین میانه‌ی زمان 9 تلاش به 142 ثانیه رسید، در حالی که 3 تلاشِ کلاینت به‌تنهایی 46.3 ثانیه طول کشید.

وقتی فقط میدل‌ور کار می‌کرد، خطایی رخ نداد. اجرا با یک AIMessage تمام شد که متن آن چنین بود: Model call failed after 3 attempts with OpenAIConnectionError؛ چون مقدار پیش‌فرض on_failure برابر با continue است. ارسال خطای 429 یا 500 از سوی رله به‌جای مدل هم به همین تعداد تلاش منجر شد.

تلاش‌های مدل در رله برای یک فراخوانی ناموفق مدلپیش‌فرض کلاینت و میان‌افزار هر کدام 3 تلاش انجام دادند، و دو لایه با هم 9 تلاش داشتند، در تمام دفعات اجرای هر شکست پایدار.
تلاش‌های مدل در رله برای یک فراخوانی ناموفق مدل نمودار نقطه‌ای تلاش‌های مدل در یک رله جلوی Ollama با Qwen3 4B روی سرور مهمان x86، با 3 اجرا برای هر خانه. سه گروه برای قطع اتصال، رد پورت و پایان مهلت زمانی در هر فراخوانی. در هر گروه، حالت پیش‌فرض کلاینت ChatOpenAI تعداد 3 تلاش انجام داد، ModelRetryMiddleware با خاموش بودن تلاش‌های مجدد کلاینت 3 تلاش داشت و هر دو لایه با هم 9 تلاش کردند. هر سه اجرای هر خانه تعداد یکسانی نشان دادند. 0 1 3 7 9 تلاش‌های مدل در رله 6 تلاش مجدد و 7 تلاش طبق مستندات قطع تماس در هر فراخوانی رد اتصال در هر فراخوانی تایم‌اوت در هر فراخوانی پیش‌فرض کلاینت فقط میان‌افزار هر دو لایه هر نقطه یک اجرا روی سرور مهمان x86 است. خطای واقعی 404 در هر مورد 1 تلاش داشت.
هر نقطه نمایانگر یک اجرا و هر ستون نمایانگر یک پیکربندی است. سه گروه شامل قطع اتصال، رد پورت و پایان مهلت زمانی (timeout) در هر فراخوانی است. خطای واقعی 404 با ChatOpenAI تنها 1 تلاش داشت و رسم نشده است. برگرفته از capture/lab/summary/retries-x86.json.

قطعی، رد اتصال یا تایم‌اوتی که فقط یک بار پیش می‌آمد، در همه‌ی پیکربندی‌ها جبران شد؛ به‌جز ChatOllama بدون میدل‌ور که خطا داد. کلاینت در حالت پیش‌فرض و در وضعیتِ فعال بودن هر دو لایه، تلاش مجدد را انجام داد. میدل‌ور هم وقتی به‌تنهایی فعال بود دوباره تلاش کرد، چون تلاش‌های کلاینت در آن غیرفعال بود. اجراهای جبران‌شده 3 تلاشِ مدل داشتند که فراخوانی مدل پس از مرحله‌ی اجرای ابزار را هم در بر می‌گرفت.

یک لایه را انتخاب کنید. اگر از ModelRetryMiddleware استفاده می‌کنید، مقدار max_retries=0 را روی مدل بگذارید، یا اصلاً میدل‌ور را اضافه نکنید. سپس بر اساس تعداد تلاش‌های همان لایه، مهلت زمانی دلخواهتان را مشخص کنید.

منابع: capture/out/01-init-chat-model.txt؛ capture/lab/summary/retries-x86.json، capture/lab/T05-retries-x86/01-model-faults.jsonl، capture/lab/T05-retries-x86/t05_real.py، capture/lab/T05-retries-x86/lr_common.py؛ مستندات docs.langchain.com در commit مستندات 04d4d4a (بخش‌های oss/python/langchain/models و oss/python/langchain/middleware/built-in)؛ فایل libs/langchain_v1/langchain/chat_models/base.py در نسخه langchain==1.5.0؛ فایل libs/partners/openai/langchain_openai/chat_models/base.py در نسخه langchain-openai==1.8.0.

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