متد
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}}. سپس کلاس مربوط را از پکیج ارائهدهنده ایمپورت میکند:
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 است. اگر نام مدل با هیچ قاعدهای نخواند، بلافاصله خطا میدهد:
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 بدون تعیین مدل و با آرگومان configurable_fields، یک _ConfigurableModel برمیگرداند. مدل این شیء در زمان اجرا از روی پیکربندی (config) و ذیل پیشوندی که تعیین میکنید (مانند llm_model) انتخاب میشود.
پروفایل مدلها
پروفایل مدل (Model profile): یک دیکشنری در model.profile شامل محدودیتها و امکانات یک مدل، مانند اندازه بافت (context size) و پشتیبانی از خروجی ساختاریافته (structured output).
پکیجهای ارائهدهنده، پروفایلها را از فایلهای دادهای درون همان پکیج میخوانند. بخشی از پروفایل gpt-4.1 به این صورت است:
"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 از سوی رله بهجای مدل هم به همین تعداد تلاش منجر شد.
قطعی، رد اتصال یا تایماوتی که فقط یک بار پیش میآمد، در همهی پیکربندیها جبران شد؛ بهجز 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.