بخش 4.3 · ایجنت، خروجی ساختاریافته و میان‌افزار

خروجی ساختاریافته (Structured Output): کدام استراتژی، روی کدام ارائه‌دهنده

Structured output: which strategy, on which provider

فهرست مطالب
  1. موضع ما
  2. آزمایش
  3. چرا ToolStrategy روی Ollama هیچ خروجی‌ای نمی‌دهد
  4. چرا ProviderStrategy روی Ollama خطا می‌دهد
  5. فراخوانی استخراج
  6. متن آزاد روی Claude هم شکست می‌خورد
  7. هزینه و زمان
  8. کدام روش، روی کدام ارائه‌دهنده

روی Qwen3 4B، استراتژی ToolStrategy در 39 وظیفه از 39 وظیفه هیچ شیئی برنگرداند و ProviderStrategy در 10 مورد از 10 مورد خطا داد؛ در حالی که یک فراخوانی استخراج (extraction call) توانست با بهترین امتیازِ هر مدل برابری کند.

ایجنت شما قیمتی را جستجو می‌کند، آن را تبدیل می‌کند، و باید عددی را تحویل کدتان بدهد. شما طبق مستندات، یک کلاس Pydantic را به عنوان response_format به آن پاس می‌دهید. روی Claude، عدد با موفقیت تحویل داده می‌شود. اما روی یک مدل محلی از طریق Ollama، همان ایجنت تمام جستجوها را تمام می‌کند و structured_response=None برمی‌گرداند، یا حتی پیش از فراخوانی هر ابزاری خطا می‌دهد و متوقف می‌شود.

با پایان این بخش، می‌توانید بر اساس نرخ‌های اندازه‌گیری‌شده، روش خروجی ساختاریافته‌ی مناسب را برای هر ارائه‌دهنده انتخاب کنید. همچنین با بررسی کد، علت هر دو خطای Ollama را توضیح می‌دهید و آن تک‌فراخوانیِ اضافه‌ای را که روی هر دو ارائه‌دهنده جواب می‌دهد به کار می‌گیرید.

موضع ما

  • روی Ollama، پارامتر response_format را از ایجنت‌های مجهز به ابزار دور نگه دارید. بگذارید ایجنت تا رسیدن به پاسخ نهایی اجرا شود، سپس یک فراخوانی with_structured_output روی همان پاسخ اجرا کنید.
  • روی Claude، از ProviderStrategy یا ToolStrategy استفاده کنید. این دو به ترتیب در 39 و 38 وظیفه از 39 وظیفه، مقدار درست را برگرداندند.
  • هرگز متن آزاد را با الگو پارس نکنید. مدل Claude Haiku 5.5 در 37 وظیفه از 39 وظیفه مقدار درست را در پاسخش داشت، اما آخرین عددِ موجود در پاسخ فقط در 15 مورد همان مقدار درست بود.

بخش 4.2 سازوکار هر استراتژی و نحوه‌ی انتخاب AutoStrategy را شرح می‌دهد. این بخش عملکرد آن‌ها را روی وظایف واقعی با جستجوهای واقعی اندازه می‌گیرد.

آزمایش

این بنچ‌مارک، 20 وظیفه‌ی زنجیره‌ای و 19 وظیفه‌ی پایگاه داده‌ی SQL از مجموعه‌وظایف را با create_agent اجرا کرد. هر وظیفه پیش از رسیدن به پاسخ، به دو تا شش بار جستجو نیاز دارد. اسکیما تنها یک فیلد داشت:

طرح‌واره‌ی (Schema) هر اجرای خروجی ساختاریافته capture/lab/bench/kit/structured.py
class FinalAnswer(BaseModel):
    answer: str = Field(description="Only the final answer value: a number or a name, with no units and no explanation.")

ایجنت ابزارهای جستجوی آن خانواده را در اختیار داشت اما به submit_answer دسترسی نداشت. پرامپت سیستم از آن می‌خواست که با مقدار پاسخ نهایی به کار پایان دهد. چهار روش روی همین وظایف سنجیده شدند:

  • متن آزاد (Free text): بدون response_format. ابزار بنچ‌مارک آخرین عدد موجود در پاسخ نهایی (یا کل متن را برای نام‌ها) در نظر گرفت.
  • استراتژی ToolStrategy: با response_format=ToolStrategy(FinalAnswer).
  • استراتژی ProviderStrategy: با response_format=ProviderStrategy(FinalAnswer).
  • فراخوانی استخراج (Extraction call): بدون response_format. پس از اجرا، یک فراخوانی دیگر از همان مدل، از طریق with_structured_output(FinalAnswer)، صورت سوال و پاسخ نهایی را خواند.

اجرایی درست به حساب می‌آید که جستجوها با آرگومان‌های صحیح انجام شده باشند و مقدار ساختاریافته دقیقاً با حقیقت مطابقت داشته باشد.

ما همه‌ی ردیف‌ها را روی مک اندازه گرفتیم: Qwen3 4B و Qwen3 8B روی Ollama با دمای 0، و Claude Haiku 5.5 از طریق API. هر خانه حاصل یک بار اجرا به ازای هر وظیفه روی 39 وظیفه است؛ به جز ProviderStrategy روی Qwen3 4B که 10 بار اجرا شد. ProviderStrategy روی Qwen3 8B اجرا نشد. تصویر وضعیت تک‌تک وظایف را نشان می‌دهد.

خروجی ساختاریافته، پاسخ هر وظیفه بر اساس روش و مدلروی Qwen3 4B هر دو استراتژی هیچ شیئی برنگرداندند، فراخوانی استخراج تمام مقادیر موجود در پاسخ را حفظ کرد، و روی Claude همه‌چیز جز متن آزاد کار کرد.
خروجی ساختاریافته: پاسخ هر وظیفه، بر اساس استراتژی و مدل جدولی با یک سطر به ازای هر مدل و استراتژی و یک ستون به ازای هر وظیفه: 20 وظیفه chain و 19 وظیفه SQL، هرکدام همراه با ابزارهای جستجو. مربع آبی پاسخ ساختاریافته درست، مربع صورتی روشن مقدار اشتباه، مربع خالی نبود پاسخ ساختاریافته، و مربع صورتی پررنگ رخداد خطا است. روی Qwen3 4B، استراتژی ToolStrategy در 39 مورد از 39 وظیفه هیچ پاسخی نداد و ProviderStrategy در 10 مورد از 10 وظیفه با خطا متوقف شد. فراخوانی مدلِ دوم که پاسخ را از متن نهایی استخراج می‌کند، روی Qwen3 4B در 30 از 39، روی Qwen3 8B در 26، و روی Claude Haiku 5.5 در 39 مورد درست بود. خواندن متن آزاد بر اساس آخرین عدد آن، روی Haiku در 15 مورد از 39 درست عمل کرد. مدل استراتژی درست chain، 20 وظیفه sql، 19 وظیفه Qwen3 4B متن آزاد 25/39 ToolStrategy 0/39 ProviderStrategy 0/10 فراخوانی استخراج 30/39 Qwen3 8B متن آزاد 18/39 ToolStrategy 14/39 فراخوانی استخراج 26/39 Haiku 5.5 متن آزاد 15/39 ToolStrategy 38/39 ProviderStrategy 39/39 فراخوانی استخراج 39/39 مقدار درست مقدار نادرست بدون پاسخ ساختاریافته خطا رخ داد استراتژی ProviderStrategy مدل Qwen3 4B روی 10 وظیفه اجرا شد. تمام اجراها روی Mac و Haiku از طریق API.
هر ستون یک وظیفه و هر سطر یک مدل و روش است. آبی مقدار درست، صورتی روشن مقدار اشتباه، مربع خالی بدون پاسخ ساختاریافته، و صورتی پررنگ خطای رخ‌داده است. برگرفته از capture/lab/bench/summary-mac.json.
مدل متن آزاد ToolStrategy ProviderStrategy فراخوانی استخراج
Qwen3 4B 25 از 39، 0.48 تا 0.77 0 از 39، 0.00 تا 0.09 0 از 10، 0.00 تا 0.28 30 از 39، 0.62 تا 0.87
Qwen3 8B 18 از 39، 0.32 تا 0.61 14 از 39، 0.23 تا 0.52 اجرا نشد 26 از 39، 0.51 تا 0.79
Claude Haiku 5.5 15 از 39، 0.25 تا 0.54 38 از 39، 0.87 تا 1.00 39 از 39، 0.91 تا 1.00 39 از 39، 0.91 تا 1.00

فاصله‌ها بر مبنای بازه‌ی اطمینان 95% ویلسون (Wilson intervals) هستند.

چرا ToolStrategy روی Ollama هیچ خروجی‌ای نمی‌دهد

استراتژی ToolStrategy ابزاری هم‌نام با اسکیما را مقید (bind) می‌کند و tool_choice="any" می‌خواهد تا مدل حتماً ابزاری را فراخوانی کند. متد ChatOllama.bind_tools این آرگومان را می‌گیرد و دور می‌اندازد، چون Ollama چنین گزینه‌ای ندارد {{code libs/partners/ollama/langchain_ollama/chat_models.py:1410-1431}}. در نتیجه هیچ چیزی مدل را مجبور به فراخوانی FinalAnswer نمی‌کند.

بنابراین مدل همان کاری را می‌کند که بدون اسکیما انجام می‌داد: جستجوها را فراخوانی می‌کند، سپس پاسخ متنی می‌دهد. پاسخ متنی بدون فراخوانی ابزار، حلقه‌ی ایجنت (Agent loop) را به پایان می‌برد و structured_response همان None باقی می‌ماند، بدون آنکه خطایی به شما اعلام شود.

مدل Qwen3 4B در 39 وظیفه از 39 وظیفه تمام جستجوهای لازم را انجام داد اما در هیچ‌کدام FinalAnswer را فراخوانی نکرد. Qwen3 8B در 14 وظیفه از 39 وظیفه آن را فراخوانی کرد و هر 14 مقدار هم درست بودند. همان‌طور که بخش 4.2 نشان می‌دهد، روی Ollama استراتژی AutoStrategy به ToolStrategy تبدیل می‌شود. بنابراین نوشتن ساده‌ی response_format=FinalAnswer نیز همان نتیجه را می‌دهد. روی نسخه‌ی مشخص‌شده‌ی claude-haiku-5-5 هم AutoStrategy به ToolStrategy تبدیل می‌شود، چنان‌که بخش 4.2 توضیح می‌دهد.

چرا ProviderStrategy روی Ollama خطا می‌دهد

استراتژی ProviderStrategy اسکیما را به عنوان پارامتر format درخواست Ollama و در کنار ابزارها ارسال می‌کند. ایجنت تنها زمانی پاسخ را به عنوان JSON پارس می‌کند که در آن هیچ فراخوانی ابزاری نباشد {{code libs/langchain_v1/langchain/agents/factory.py:1260-1275}}. در هر 10 اجرای Qwen3 4B، اولین پاسخ مدل نه فراخوانی ابزار داشت و نه متن:

اولین و تنها فراخوانی مدل از یک اجرای ProviderStrategy روی Qwen3 4B capture/lab/bench/runs/structured.jsonl
{"run_id": "bd6e197e", "ts": "2026-11-14T20:21:06", "task_id": "chain01", "family": "chain", "model": "qwen3:4b-instruct-2507-q4_K_M", "variant": "provider", "answer_present": false, …"lookups_ok": false, "model_calls": 1, "tool_calls": 0, "in_tokens": 682, "out_tokens": 1024, "wall_s": 38.814, …"final_text": "", "error": "StructuredOutputValidationError: Failed to parse structured output for tool 'FinalAnswer': Native structured output expected valid JSON for FinalAnswer, but parsing failed: Expecting value: line 1 column 1 (char 0).."}

یک سطر، خلاصه‌شده به متد، تعداد فراخوانی‌ها، توکن‌ها، زمان و خطا.

هر 10 پاسخ، تمام 1,024 توکن خروجی مجاز را ظرف 18 تا 43 ثانیه مصرف کردند و محتوایی خالی به جا گذاشتند. ایجنت متن خالی را پارس کرد و در همان فراخوانی اول—پیش از اجرای هرگونه جستجو—خطا داد. با قرار گرفتن اسکیما به عنوان format، مدل در اجراهای ما هرگز فراخوانی ابزاری تولید نکرد؛ بنابراین کار اصلاً نتوانست شروع شود.

بخش 4.2 با یک ابزار ساده‌ی add به همین خطا خورده بود. اینجا خطا در تک‌تک وظایفی که به جستجو نیاز داشتند پیش آمد.

فراخوانی استخراج

فراخوانی استخراج: یک بار فراخوانی with_structured_output پس از اجرای ایجنت، که صورت سوال و پاسخ نهایی را می‌خواند و اسکیما را برمی‌گرداند.

فراخوانی استخراج بنچمارک capture/lab/bench/kit/structured.py
                            ex = model.with_structured_output(FinalAnswer).invoke(
                                [{"role": "system", "content": "Extract the final answer value from the assistant reply. Return only the value."},
                                 {"role": "user", "content": f"Question: {t['turns'][0]}\n\nAssistant reply: {ft}"}], config={"callbacks": [meter]})

فراخوانی و دو پیام آن. مدیریت خطای پیرامون آن حذف شده است.

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

روی Qwen3 4B، فراخوانی استخراج در 30 وظیفه از 39 وظیفه درست عمل کرد. دقیقاً در همان 30 مورد هم مقدار درست در جایی از پاسخ نهایی آمده بود. روی Qwen3 8B هر دو آمار 26 بودند. یعنی روش استخراج، هیچ پاسخی را که ایجنت پیدا کرده بود روی هیچ‌کدام از این دو مدل از دست نداد. سایر خطاها ناشی از جستجوهای اشتباه یا محاسبات غلط در حلقه‌ی ایجنت بودند که هیچ روش خروجی‌ای قادر به اصلاح آن‌ها نیست.

روی Claude Haiku 5.5، فراخوانی استخراج در 39 وظیفه از 39 وظیفه درست بود؛ یعنی دقیقاً مشابه ProviderStrategy.

متن آزاد روی Claude هم شکست می‌خورد

مدل Claude Haiku 5.5 در 37 وظیفه از 39 وظیفه مقدار درست را در پاسخ نهایی نوشت. اما آخرین عددِ موجود در پاسخ فقط در 15 مورد همان عدد درست بود. این مدل ابتدا جواب را می‌گوید و سپس به توضیح آن می‌پردازد:

یک پاسخ درست که آخرین عدد آن جواب مسئله نیست capture/lab/bench/runs/structured.jsonl
{"run_id": "d2c25350", "ts": "2026-11-15T11:40:49", …"value": "1.086957", "truth": 138.587, "correct": false, "correct_any_number_in_text": true, …"final_text": "The total for 3 trail lanterns is **$138.59 USD**. The unit price is \u20ac42.50, converted at 1 EUR = 1.086957 USD.", "error": null}

یک سطر از روش متن آزاد، خلاصه‌شده به مقداری که کیت خوانده، واقعیت، و پاسخ.

آخرین عدد در واقع نرخ تبدیل ارز است. روی Qwen3 4B همین الگو در 25 وظیفه از 39 وظیفه درست بود، در حالی که 30 پاسخ شامل آن مقدار بودند. استخراج با الگو روی تک‌تک مدل‌هایی که سنجیدیم بخشی از پاسخ‌ها را از بین می‌برد.

هزینه و زمان

ما هزینه‌ی چهار روش را روی Claude Haiku 5.5 در طول این 39 وظیفه بر اساس قیمت رسمی اندازه گرفتیم. اجراکننده‌ی (Runner) خروجی ساختاریافته در این بنچ‌مارک کَش پرامپت (Prompt cache) نداشت؛ بنابراین تخفیف کَش در این اعداد اعمال نشده است.

روش روی Claude Haiku 5.5 درست فراخوانی‌های مدل، میانه هزینه‌ی 39 وظیفه زمان هر وظیفه، میانه
متن آزاد 15 4 $0.0267 4.5 ثانیه
ToolStrategy 38 4 $0.0287 4.4 ثانیه
ProviderStrategy 39 4 $0.0284 5.0 ثانیه
فراخوانی استخراج 39 5 $0.0307 4.3 ثانیه

فراخوانی استخراج به خاطر یک فراخوانی بیشتر با پرامپتی کوتاه، تنها 8% بیشتر از ProviderStrategy هزینه داشت. روی Qwen3 4B میانه‌ی زمان هر وظیفه 9.3 ثانیه شد (در مقایسه با 9.8 ثانیه برای متن آزاد)، چرا که فراخوانی استخراج کوتاه بسیار سریع اجرا می‌شود.

کدام روش، روی کدام ارائه‌دهنده

ارائه‌دهنده آیا ایجنت ابزار دارد؟ روش مورد استفاده آمار پشت آن
Ollama از طریق ChatOllama بله فراخوانی استخراج 30 از 39 در برابر 0 از 39 و 0 از 10 روی Qwen3 4B
Ollama از طریق ChatOllama خیر ToolStrategy یا ProviderStrategy، با اعمال سقف روی فراخوانی‌ها نرخ خطای هر اسکیما در بخش 4.2 آمده است
Anthropic از طریق ChatAnthropic بله ProviderStrategy یا ToolStrategy 39 و 38 از 39 روی Claude Haiku 5.5
هر ارائه‌دهنده‌ای هر حالتی هرگز از الگو روی متن آزاد استفاده نکنید 15 از 39 روی Claude Haiku 5.5

ارائه‌دهنده‌ای را که در محیط عملیاتی (Production) اجرا می‌کنید حتماً بسنجید. این نتایج روی langchain نسخه 1.5.0، langchain-ollama نسخه 1.1.0، و langchain-anthropic نسخه 1.7.10 معتبرند.

منابع: capture/lab/bench/summary-mac.json، capture/lab/bench/summarize.py، capture/lab/bench/runs/structured.jsonl، capture/lab/bench/runs/cost-ledger.jsonl، capture/lab/bench/kit/structured.py، capture/lab/bench/kit/harnesses.py، capture/lab/bench/data/tasks.jsonl؛ کتابخانه‌ی libs/partners/ollama/langchain_ollama/chat_models.py در langchain-ollama 1.1.0؛ libs/langchain_v1/langchain/agents/factory.py و libs/langchain_v1/langchain/agents/structured_output.py در langchain==1.5.0؛ libs/partners/anthropic/langchain_anthropic/chat_models.py در langchain-anthropic 1.7.10.