استراتژی
ToolStrategyدرخواست فراخوانی ابزار (tool call) میدهد و بدون محدودیت تلاش مجدد میکند؛ProviderStrategyاز ارائهدهنده JSON میخواهد و هرگز تلاش مجدد نمیکند؛ وAutoStrategyپیش از هر بار فراخوانی مدل یکی از این دو را انتخاب میکند.
فرض کنید میخواهید یک شیء سفارش را از دل ایمیلی استخراج کنید؛ بنابراین یک کلاس Pydantic را بهعنوان response_format میفرستید. در یک مدل، خروجی همان شیء مدنظر خواهد بود. در مدلی کوچکتر، اجرا آنقدر در حلقه میافتد تا به حد بازگشت (recursion limit) برسد. در ارائهدهندهای دیگر، فرایند حتی پیش از نخستین درخواست متوقف میشود و خطا میدهد. استراتژیِ اجراشده تعیین میکند که کدامیک از این سه حالت نصیبتان شود.
پس از پایان این بخش، میتوانید پیشبینی کنید که یک ایجنت (agent) از کدام استراتژی استفاده میکند، چه چیزی به مدل میفرستد و چگونه با شکست روبهرو میشود. همچنین میتوانید بر اساس نرخ شکستهایی که روی چهار اندازه مختلف از مدلها سنجیدهایم، استراتژی مناسب را انتخاب کنید.
سه استراتژی موجود
استراتژی خروجی ساختاریافته: روشی است که create_agent به کمک آن، شیئی منطبق بر اسکیمای شما از مدل تحویل میگیرد. نتیجهی کار در structured_response درون وضعیت خروجی (output state) مینشیند.
- ToolStrategy: برای هر اسکیما یک ابزار متصل میکند، گزینهی
tool_choice="any"را تحمیل مینماید و آرگومانهای فراخوانی ابزار را تجزیه (parse) میکند. در صورت بروز خطای تجزیه (Parse Error)، خطا را به مدل پس میفرستد و دوباره درخواست میدهد. - ProviderStrategy: اسکیما را بهعنوان
response_formatبه ارائهدهنده میدهد و متن JSON پاسخ را تجزیه میکند. این روش فقط یک بار تلاش میکند. - AutoStrategy: یک اسکیما نگه میدارد و پیش از هر بار فراخوانی مدل، آن را به یکی از دو استراتژی دیگر تبدیل میکند.
یک اسکیمای ساده، مانند یک کلاس Pydantic، به AutoStrategy تبدیل میشود {{code libs/langchain_v1/langchain/agents/factory.py}}. این استراتژیها در مسیر langchain.agents.structured_output قرار دارند.
شیوه انتخاب در AutoStrategy
هنگامی که پروفایل مدل مقدار structured_output را true نشان دهد، AutoStrategy استراتژی ProviderStrategy را انتخاب میکند. مدلهای Gemini پیش از سری 3، در صورتی که ایجنت ابزار داشته باشد، از این قاعده مستثنا هستند. در همهی موارد دیگر، نام مدل با فهرستی ثابت از نامها مقایسه میشود؛ نامهایی مثل gpt-4o، gpt-4.1 و برخی مدلهای Claude. اگر هیچ نامی همخوانی نداشته باشد، ToolStrategy را انتخاب میکند {{code libs/langchain_v1/langchain/agents/factory.py:581-626}}. تصویر این روند تصمیمگیری را نشان میدهد.
کیت آزمایش، همین اسکیما را روی دو مدل ChatOllama اجرا میکند که خودشان هیچ ابزاری ندارند. اولی پروفایلی ندارد و ایجنت ابزاری همنام با اسکیما به آن متصل میکند:
"messages": [
"human: What is 2 + 3?"
],
"tools": [
"Answer"
]اولین فراخوانی مدل، خلاصهشده به پیامها و ابزارهای متصلشده.
ایجنت همچنین tool_choice="any" را درخواست میکند. متد ChatOllama.bind_tools این آرگومان را نادیده میگیرد، چون Ollama چنین گزینهای ندارد {{code libs/partners/ollama/langchain_ollama/chat_models.py}}. بنابراین در Ollama چیزی مدل را مجبور به فراخوانی ابزارِ اسکیما نمیکند. در این مورد، مدل بههرحال ابزار Answer را با value برابر 5 فراخوانی کرد.
مدل دوم پروفایل {"structured_output": True} دارد. ایجنت هیچ ابزاری برای اسکیما متصل نمیکند و response_format را میفرستد؛ مقداری که ChatOllama آن را در قالب اسکیمای JSON (JSON Schema) به Ollama ارسال میکند:
"messages": [
"human: What is 2 + 3?"
],
"format": "json schema"اولین فراخوانی مدل، خلاصهشده به پیامها و فرمت آن.
پاسخ مدل متن {"value": 5} بود و ایجنت فیلد unit را با مقدار پیشفرض آن پر کرد.
کلاس ChatOllama پروفایلی ندارد و نام مدلهای Ollama نیز در فهرست نیست. بنابراین در Ollama، یک اسکیمای ساده و AutoStrategy همیشه در قالب ToolStrategy اجرا میشوند. در مورد claude-haiku-5-5 در نسخهی پینشده نیز AutoStrategy به ToolStrategy تبدیل میشود؛ چراکه در پروفایل آن structured_output برابر false است و نام این مدل در فهرست نامهایی که به ProviderStrategy ختم میشوند وجود ندارد.
استراتژی ToolStrategy
استراتژی ToolStrategy کلاس Pydantic، دیتاکلاس، TypedDict، دیکشنری اسکیمای JSON یا اجتماعی از کلاسها (Union) را میپذیرد. این استراتژی، تایپ اجتماع را به ازای هر عضو به یک ابزار مجزا میشکند؛ بنابراین مدل با انتخاب ابزار، در واقع نوع موردنظر را انتخاب میکند:
"tools": [
"Answer",
"Refusal"
]ابزارهای متصلشده در اجرای union.
خروجی یک TypedDict بهصورت dict و خروجی یک دیتاکلاس بهصورت نمونهای از خود آن برمیگردد. دیکشنری اسکیمای JSON نیز آرگومانها را بدون اعتبارسنجی تحویل میدهد {{code libs/langchain_v1/langchain/agents/structured_output.py}}. کیت آزمایش مقدار را در قالب یک واژهی انگلیسی خواست تا رشتهای را به فیلدی از نوع عدد صحیح (integer) بفرستد. مدل Qwen3 4B با وجود این، خود عدد را فرستاد:
structured_response:
{
"value": 5
}مقدار structured_response در اجرای اسکیمای JSON.
هنگامی که اعتبارسنجی آرگومانها با شکست روبهرو شود، ToolStrategy خطا را در یک ToolMessage مینویسد و دوباره مدل را فراخوانی میکند. این پیام با عبارت .Please fix your mistakes تمام میشود که همان قالب STRUCTURED_OUTPUT_ERROR_TEMPLATE است {{code libs/langchain_v1/langchain/agents/factory.py:128}}. مدل ما هرگز مقدار نامعتبری نفرستاد. وقتی از آن خواسته شد 3.5 را در فیلد عددی value بگذارد، مقدار value را 3 و unit را "5" فرستاد که ساختاری کاملاً معتبر است.
دو فراخوانی ابزار ساختاریافته در یک پیام هوش مصنوعی (AI message) هم به همین سازوکار تلاش مجدد منجر میشود. کیت آزمایش در یک پاسخ، همزمان Answer و Refusal (امتناع مدل) را خواست و مدل هر دو را فرستاد:
"content": "Error: Model incorrectly returned multiple structured responses (Answer, Refusal) when only one is expected.\n Please fix your mistakes.",
"name": "Answer",
…
"status": "success"اولین پیام از دو ToolMessage. پیام دوم متنی مشابه دارد.
سپس مدل فقط یک فراخوانی Answer فرستاد و اجرا با value برابر 5 تمام شد. وضعیت (status) هر پیامِ تلاش مجدد، با اینکه خطا حمل میکند، success ثبت میشود. کدهایی که اشیای خطای ToolMessage را میشمارند، این تلاشهای مجدد را بهحساب نمیآورند.
handle_errors: پارامتری در ToolStrategy است که نحوهی تلاش مجدد را مشخص میکند. مقدار پیشفرض یعنی True، با هر بار خطای تجزیه دوباره تلاش میکند. اگر یک رشته بدهید، جایگزین متن تلاش مجدد میشود. اگر نوع استثنا یا تاپلی از استثناها بدهید، تلاش مجدد تنها به همان خطاها محدود میشود. یک تابع فراخوانپذیر (callable) هم خطا را میگیرد و متن تلاش مجدد را برمیگرداند. مقدار False در همان نخستین فراخوانی ناموفق، خطای StructuredOutputValidationError میدهد.
منطق تلاش مجدد همان تابع _handle_structured_output_error است {{code libs/langchain_v1/langchain/agents/factory.py:649-671}}. دو خطی که استثنا صادر میکنند در {{code libs/langchain_v1/langchain/agents/factory.py:1271}} و {{code libs/langchain_v1/langchain/agents/factory.py:1333}} قرار دارند. این پارامتر، بههمراه تایپ و مقدار پیشفرض True، در {{code libs/langchain_v1/langchain/agents/structured_output.py:212-253}} آمده است. متن داکاسترینگ آن میگوید که اسکیماهای دیکشنری اعتبارسنجی نمیشوند؛ بنابراین handle_errors اثری روی آنها ندارد.
استراتژی ProviderStrategy
استراتژی ProviderStrategy اسکیما را به ارائهدهنده میفرستد و متن پاسخ را بهصورت JSON میخواند. اگر متن JSON نباشد یا در اعتبارسنجی رد شود، اجرا در همان نخستین فراخوانی با خطا متوقف میشود.
در Ollama اسکیما به قالب درخواست تبدیل میشود و پاسخ حتماً باید بر آن منطبق باشد. کیت آزمایش یک واژه، عدد 3.5 و یک جملهی سادهی انگلیسی را خواست. مدل در هر بار یک JSON معتبر مانند { "value": 5 } برگرداند. شکست زمانی پیش آمد که یک ابزار در میان بود. با متصل بودن add، پاسخ حاوی هیچ متنی نبود و ایجنت متن خالی را بهجای JSON تجزیه کرد:
raised langchain.agents.structured_output.StructuredOutputValidationError: Failed to parse structured output for tool 'Answer': Native structured output expected valid JSON for Answer, but parsing failed: Expecting value: line 1 column 1 (char 0)..تایپ اجتماع (Union) حتی به اینجا هم نمیرسد. استراتژی ProviderStrategy(Union[Refund, Exchange]) در تمام اجراهای ما، موقع ساخت استراتژی و پیش از اجرای create_agent، خطای ValueError: Unsupported schema type داد {{code libs/langchain_v1/langchain/agents/structured_output.py:180-194}}.
عدم تغییر استراتژی در زمان اجرا
صفحهی مستندات خروجی ساختاریافته میگوید اگر مدل از خروجی ساختاریافته پشتیبانی نکند، ایجنت بهجای خروجی ارائهدهنده از فراخوانی ابزار استفاده میکند. این موضوع را هم برای یک اسکیمای ساده و هم برای ProviderStrategy مطرح کرده است {{docs oss/python/langchain/structured-output}}. اما سورسکد استراتژی صریح را دستنخورده نگه میدارد و AutoStrategy را تنها بر پایهی پروفایل و نام مدل تعیین میکند {{code libs/langchain_v1/langchain/agents/factory.py}}. این کتابچه از کد تبعیت میکند و این مغایرت را بهعنوان تضادهای D121 و D209 ثبت مینماید.
ما آن را روی پنج مدل در Ollama، با ChatOpenAI و ChatOllama (هر کدام 3 اجرا) تست کردیم. هیچ مدل چتی این قالب را رد نکرد. ProviderStrategy مقدار response_format را با json_schema در مسیر v1/ و با format در مسیر api/chat/ فرستاد و در 24 اجرا از 24 اجرا، شیء معتبر Contact را گرفت. AutoStrategy برای همهی مدلهای Ollama استراتژی ToolStrategy را برگزید، چون هیچ پروفایلی آنها را برای خروجی ساختاریافته علامت نزده است. تنها رد شدن واقعی از سمت nomic-embed-text رخ داد که یک مدل امبدینگ (embedding) است:
{"kind": "run", "client": "ChatOpenAI", "strategy": "ProviderStrategy", "model": "nomic-embed-text:latest", …"outcome": "raised", "error_type": "OpenAIInvalidRequestError", "error": "Error code: 400 - \"nomic-embed-text:latest\" does not support chat", …"requests": [{"path": "/v1/chat/completions", "status": 400, "req_keys": ["messages", "model", "response_format", "seed", "stream", "temperature", "tools"], "response_format_type": "json_schema", …}], "n_requests": 1, …}خلاصهشده به کلاینت، استراتژی، مدل، نتیجه، خطا و تکدرخواست.
یک درخواست، یک خطا، و بدون درخواست دومی با ابزارها. کد با بروز خطا استراتژی را تغییر نمیدهد؛ بنابراین گفتهی آن صفحه تنها در جایی اعتبار دارد که کد از قبل مدل را بشناسد.
این دو مسیر از نظر زمانی هم فرق دارند. روی مک، با مدل Qwen3 4B، استراتژی ProviderStrategy در هر اجرا 18 تا 27 ثانیه طول کشید، در حالی که فراخوانی ابزار 2.3 تا 3.9 ثانیه زمان برد. مدل با این قالب 239 توکن (token) نوشت، اما برای فراخوانی ابزار فقط 35 توکن تولید کرد. در مدلهای gpt-oss:20b و qwen3:8b، قالب 35 تا 46 ثانیه زمان برد، هرچند مدل توکنهای کمتری نسبت به حالت فراخوانی ابزار تولید کرد. مدل qwen3:0.6b در هر دو مسیر 2.3 تا 3.9 ثانیه طول کشید.
دو اجرایی که به هیچ نتیجهای نمیرسند
گزینهی handle_errors=True سقفی برای تعداد تلاش مجدد ندارد. با فرض tools=[]، گراف ایجنت یالی از model به model دارد که تا زمان شکلگیری یک پاسخ ساختاریافته، در حلقه میچرخد. تنها سدِ راه آن حد بازگشت است که پیشفرض ایجنت برای آن 9999 گام تعیین شده است. در محیط آزمایش، مدل Qwen3 0.6B روی Ollama هرگز ابزار را فراخوانی نکرد. در هر نوبت متنی یا با پیامی خالی پاسخ داد و ایجنت هم هر پاسخ را همراه با پاسخهای قبلی پس فرستاد. این مدل در recursion_limit=12 تعداد 12 فراخوانی مدل و در حد 25 تعداد 25 فراخوانی انجام داد و سپس در هر 10 اجرا از 10 اجرا، خطای GraphRecursionError داد.
مدل Qwen3 4B Instruct این حلقه را زودتر و در سطح ارائهدهنده تمام میکند. با TypedDict و با دیتاکلاس، مدل دو بار بهصورت متنی جواب داد: .2 + 3 = 5. ایجنت درخواست سوم را با دو پیام هوش مصنوعی پیاپی در انتها فرستاد و Ollama با خطای 400 جلوی آن را گرفت.
روی مک این اتفاق در 40 اجرا از 40 اجرا افتاد؛ هم با ChatOllama و هم با ChatOpenAI در v1/، با recursion_limit روی 12 و 25. با وجود اینکه ChatOpenAI مقدار tool_choice: "required" را فرستاد، مدل باز هم متنی جواب داد. مدل Qwen3 0.6B روی همین سرور خطای 400 نگرفت؛ پس این بررسی به خود مدل وابسته است. اجرای کیت آزمایش روی سرور مهمان x86 سومین درخواست را نشان میدهد:
raised ollama._types.ResponseError: {"error":{"code":400,"message":"Cannot have 2 or more assistant messages at the end of the list.","type":"invalid_request_error"}} (status code: 400)
…
"call": 3,
"messages": [
"human: What is 2 + 3?",
"ai: 2 + 3 = 5.",
"ai: 2 + 3 = 5."
],خطا و سپس پیامهای سومین فراخوانی مدل.
اگر دستکم یکی از ابزارهای خودتان متصل باشد، یک پاسخ متنی ساده به اجرای برنامه خاتمه میدهد. با اتصال add، مدل ابتدا add را فراخوانی کرد و سپس پاسخی متنی داد. پس از دو بار فراخوانی مدل، structured_response بدون هیچ استثنایی None شد. بعد از هر بار اجرا، بررسی کنید که structured_response حتماً مقداری داشته باشد و None نباشد.
نرخ شکست در چهار اندازه مختلف از مدلها
ما عملکرد هر استراتژی را روی مک با چهار مدل Qwen3 در Ollama، با خاموش بودن فرایند تفکر (thinking) و با دمای 0 سنجیدیم. ایجنت هیچ ابزاری نداشت و سقف 10 فراخوانی مدل برای هر اجرا تنظیم شد. چهار اسکیما بررسی شدند: ساده (flat)، تودرتو (nested)، اجتماع (union) و دو enum. برای مدل 0.6B روی هر مدل و اسکیما 20 ورودی و برای مدلهای دیگر 10 ورودی در نظر گرفته شد؛ یعنی در مجموع 600 اجرا. این اجراها بدون ابزار بودند. با متصل کردن ابزارهای جستجو، هر دو استراتژی در Ollama شکست خوردند که بخش 4.3 این حالت را بررسی میکند.
استراتژیهای AutoStrategy و ToolStrategy در Ollama پیکربندی یکسانی داشتند و اجراهایشان به نتایج برابری رسید. منظور از شکست یک اجرا این است که خطایی بدهد یا هیچ structured_response بازنگرداند:
| مدل | شکست ToolStrategy |
شکست ProviderStrategy |
ProviderStrategy بدون اجتماع |
|---|---|---|---|
qwen3:0.6b |
36 از 80، 45% | 20 از 80، 25% | 0 از 60 |
qwen3:1.7b |
6 از 40، 15% | 10 از 40، 25% | 0 از 30 |
qwen3:4b-instruct |
11 از 40، 27.5% | 13 از 40، 32.5% | 3 از 30 |
qwen3:8b |
10 از 40، 25% | 10 از 40، 25% | 0 از 30 |
همهی موارد شکست ProviderStrategy در مدلهای 0.6B و 1.7B و 8B مربوط به خطای اسکیمای اجتماع در زمان ساخت بود. اگر اجتماع را کنار بگذاریم، ToolStrategy در 36 مورد از 60، 6 از 30، 11 از 30 و 10 از 30 شکست خورد. تصویر جزئیات هر اجرا را نمایش میدهد.
اسکیمای تودرتو در مدل 8B در هر 10 اجرای ToolStrategy به سقف 10 فراخوانی رسید. در مدل 0.6B هم در 19 اجرا از 20 اجرا به این سقف برخورد کرد. مدل بهجای دادهها، خودِ اسکیما را پس میفرستاد و هر تلاش مجدد نیز همین کار را تکرار میکرد. در مدل 4B، سه اجرای اسکیمای تودرتو با خطای Ollama در رابطه با ناقص بودن JSON فراخوانی ابزار متوقف شدند. سه اجرای اسکیمای enum هم با خطای 400 از سوی Ollama به بنبست رسیدند؛ چراکه تلاشهای مجدد، دو پیام متوالی هوش مصنوعی در پی داشت.
مستندات خروجی ساختاریافته، ProviderStrategy را در صورت در دسترس بودن، مطمئنترین روش مینامد {{docs oss/python/langchain/structured-output}}. در اسکیمای تودرتو، این روش روی سه مدل اشیای معتبر بیشتری نسبت به ToolStrategy تولید کرد و روی مدل 1.7B به نتیجهی مساوی رسید. در اسکیمای enum هم روی مدلهای 0.6B و 1.7B بهتر ظاهر شد و روی مدلهای 4B و 8B نتیجه مساوی بود. این روش امکان پذیرش اجتماع را ندارد و هرگز تلاش مجدد نمیکند.
معتبر بودن به معنای درست بودن نیست
شیء معتبر یعنی شیئی که با اسکیما مطابقت دارد؛ اما همچنان ممکن است مقادیر اشتباهی داشته باشد. در اسکیمای enum، مدل یک اولویت و یک دستهبندی برای تیکت پشتیبانی انتخاب کرد. اگر به اجراهای ProviderStrategy که structured_response داشتند از کوچکترین مدل به بزرگترین مدل نگاه کنید، مقادیر خروجی در 4 از 20، 3 از 10، 4 از 7 و 4 از 10 با برچسبهای ما همخوانی داشتند. این برچسبها مبتنی بر قضاوت شخصی هستند؛ بنابراین این نتایج را بهمنزلهی توافق مدل با نظر یک ارزیاب در نظر بگیرید.
منابع: capture/out/07-structured-output.txt، capture/out/08-structured-errors.txt، capture/s_agents.py؛ libs/partners/ollama/langchain_ollama/chat_models.py در langchain-ollama 1.1.0؛ capture/lab/summary/structured-output-mac.json، capture/lab/T06-structured-output-mac/01-ollama-runs.jsonl، capture/lab/T06-structured-output-mac/03-ollama-seq-n10.jsonl، capture/lab/T06-structured-output-mac/t06_run.py، capture/lab/T06-structured-output-mac/t06_schemas.py؛ capture/lab/last-two-mac/01-toolstrategy-text.jsonl، capture/lab/last-two-mac/04-small-model-probe.jsonl، capture/lab/last-two-mac/lt1_toolstrategy_text.py، capture/lab/last-two-mac/lt1b_small_model_probe.py، capture/lab/last-two-mac/lt_common.py؛ capture/lab/summary/structured-output-mac-real.json، capture/lab/T06-structured-output-mac-real/01-provider-paths.jsonl، capture/lab/T06-structured-output-mac-real/t06_provider_real.py؛ docs.langchain.com در کامیت مستندات 04d4d4a (oss/python/langchain/structured-output)؛ libs/langchain_v1/langchain/agents/factory.py و libs/langchain_v1/langchain/agents/structured_output.py در langchain==1.5.0.