خروجی ساختاریافته و اعتبارسنجی در n8n
خروجی مدل را در n8n با Output Parser یا Information Extractor ساختاریافته کن، شکست تجزیه را با مسیر خطا بگیر و پس از آن، درستی مقدار را با گره قطعی بررسی کن.
بعد از این درس میتوانی
- در n8n با Basic LLM Chain و Structured Output Parser یا با Information Extractor خروجی ساختاریافته بگیرد.
- تفاوت خروجی ساختاریافته اجراشده توسط ارائهدهنده و Schema درجشده در پرامپت را بگوید و برای هر ارائهدهنده درست انتخاب کند.
- شکست تجزیه را با خروجی خطای گره، یک تکرار و صف بررسی مدیریت کند.
- پس از تجزیه موفق، با گره قطعی دستکم یک قاعده معنایی را بررسی کند.
چرا این درس مهم است
ورکفلوی طبقهبندی برگ سبز با گره مدل خروجی میگرفت و گره بعدی {{ $json.output.category }} را میخواند. هر از گاهی مدل جملهای مثل «دسته این پیام order_shipping است» برمیگرداند، Expression خالی میشد و پیام بیصدا به شاخه پیشفرض میرفت. روزی که مدل عوض شد، این «هر از گاهی» شد «هر ده پیام یکی».
در پروژه ۲ خروجی ساختاریافته را با کد ساختی. این درس همان را با گرههای آماده n8n میسازد و دو لایه را جدا نگه میدارد: شکل (که Parser و Schema میگیرند) و درستی (که فقط بررسی تو میگیرد).
مفاهیم کلیدی
یادآوری: JSON Schema، Structured Output و اعتبارسنجی معنایی را در دوره FND-102 و پروژه ۲ دیدی؛ گره Information Extractor را در درس قبل.
- Output Parser (تجزیهگر خروجی): زیرگرهی در n8n که از مدل قالب مشخص میخواهد و پاسخ را به ساختار تبدیل میکند.
- Structured Output Parser (تجزیهگر خروجی ساختاریافته): Output Parserی که خروجی را بر اساس Schema به شیء JSON تبدیل میکند.
- Auto-fixing Output Parser (تجزیهگر خودترمیم): Output Parserی که اگر تجزیه شکست بخورد، از مدل میخواهد پاسخ را درست کند.
- Parse Failure (شکست تجزیه): وقتی پاسخ مدل با قالب خواستهشده نمیخواند و به ساختار تبدیل نمیشود.
- Schema-in-Prompt (Schema در پرامپت): درج قالب خروجی در دستور بهجای اجرای آن توسط ارائهدهنده؛ بدون تضمین.
مدل ذهنی
خروجی مدل را مثل فرم کاغذی که کارمند پر میکند ببین. Schema فرم با خانههای مشخص است. Parser کسی است که فرم را تحویل میگیرد و اگر خانهای خالی یا جای اشتباه نوشته شده، پس میدهد. ولی Parser نمیداند عددی که در خانه «شماره سفارش» نوشته شده واقعاً در نامه مشتری بوده یا نه؛ آن را بررسیکننده دوم (قاعده معنایی) میفهمد.
دو لایه بررسی خروجی مدل در n8n
این تشبیه کجا غلط است؟ کارمند فرم را خودش با خانهها میبیند. بعضی ارائهدهندهها خروجی را در خود مدل به Schema محدود میکنند، و بعضی فقط Schema را بهشکل متن در پرامپت میگیرند و هیچ تضمینی نمیدهند. یعنی گاهی «فرم» واقعاً خانه دارد و گاهی فقط به کارمند گفتهای «لطفاً در این قالب بنویس».
گامبهگام
گام ۱: دو راه در n8n
- Basic LLM Chain + Output Parser: در Basic LLM Chain گزینه «Require Specific Output Format» را روشن کن؛ n8n میخواهد یکی از Output Parserها را وصل کنی: Auto-fixing، Item List یا Structured Output Parsersrc-n8n-basic-llm-chain. پرامپت یا از گره قبل گرفته میشود (که فیلد
chatInputانتظار دارد) یا در فیلد پرامپت تعریف میشود؛ اگرchatInputنباشد خطای «No prompt specified» میگیریsrc-n8n-basic-llm-chain. - Information Extractor: برای استخراج؛ Schema را از توضیح فیلدها، از یک نمونه JSON یا با JSON Schema تعریف میکنی. وقتی از نمونه JSON ساخته شود، همه فیلدها اجباریاند؛ و n8n دستور قالب را خودش به پرامپت سیستمی اضافه میکندsrc-n8n-information-extractor.
برای Schema دقیق (enum، nullable)، «Define using JSON Schema» را انتخاب کن و از assets/triage-schema.json شروع کن. حالت «از نمونه JSON» همه فیلدها را اجباری میکند و جایی برای «اگر نیست، null» نمیگذارد؛ همان چیزی که مدل را به ساختن مقدار تشویق میکند.
گام ۲: چه کسی Schema را اجرا میکند؟
| حالت | یعنی | نمونهها (مهر ۱۴۰۵) |
|---|---|---|
| اجرا توسط ارائهدهنده | مدل در تولید پاسخ به Schema محدود میشود | OpenAI Structured Outputs که پایبندی به Schema را تضمین میکندsrc-openai-structured-outputs؛ Ollama با format یا response_formatsrc-ollama-structured-outputs |
| Schema در پرامپت | فقط دستور؛ تضمینی نیست | لایه سازگار با OpenAI در Claude که response_format را نادیده میگیردsrc-claude-openai-sdk-compat؛ Output Parserهایی که دستور قالب را به پرامپت اضافه میکنند |
حتی وقتی ارائهدهنده Schema را اجرا میکند، JSON معتبر به معنی مقدار درست نیست؛ مستندات Gemini هم صریحاً میگوید خروجی از نظر نحوی معتبر است ولی ممکن است از نظر معنایی درست نباشد و باید مقدارها را در برنامه بررسی کنیsrc-gemini-structured-output.
گام ۳: شکست تجزیه را مدیریت کن
حتی با Parser، تجزیه گاهی شکست میخورد (بهویژه وقتی Schema فقط در پرامپت است).
- روی گره مدل، On Error را روی Continue (using error output) بگذار (درس خطا در AUT-202).
- شاخه خطا: یک بار تکرار با یادآوری کوتاه («فقط JSON طبق Schema برگردان»)؛ دوباره شکست ← صف بررسی.
- Auto-fixing Output Parser همین «یک تکرار» را خودکار میکند، با یک فراخوانی اضافه مدل. راحت است، ولی هزینه و تأخیر را بشمار و سقف داشته باش.
گام ۴: قاعده معنایی با گره قطعی
پس از تجزیه موفق، یک If (یا Code کوتاه) با قاعدههایی مثل:
categoryدر فهرست بسته است (اگر Schema در پرامپت است، این لازم است).order_idتهی است یا در متن پیام وجود دارد.- اگر
urgentدرست است،needs_humanهم درست باشد (قاعده کسبوکار).
نامعتبر ← صف بررسی، با دلیل. شمار هر دلیل را ثبت کن؛ اگر یک دلیل زیاد تکرار شد، پرامپت یا Schema را اصلاح کن.
مثالها
پیادهسازی عملی
طبقهبندی با خروجی ساختاریافته و دو لایه بررسی. حدود ۲۲ دقیقه.
- ورکفلو: Manual Trigger ← Edit Fields با پنج پیام ساختگی (یکیشان شامل
BROKENبرای مسیر آزمایشی) ← Edit Fields که متن را درchatInputبگذارد. - Basic LLM Chain با Require Specific Output Format و Structured Output Parser با Schema assets/triage-schema.json؛ یا Information Extractor با «Define using JSON Schema».
- On Error: Continue (using error output) ← یک تکرار ← صف بررسی (Edit Fields).
- If با سه قاعده معنایی گام ۴ ← صف بررسی با دلیل.
- شش مورد assets/validation-cases.md را جواب بده.
اجرای محلی
گره مدل را به Ollama محلی وصل کن (اگر n8n در Docker است، Ollama از host.docker.internal:11434 در دسترس است). Ollama خروجی ساختاریافته را با Schema میپذیرد؛ با این حال قاعده معنایی را حذف نکن.
بدون اجرا / شبیهساز
اگر گره مدل نمیتواند به مدل آزمایشی وصل شود، بهجای Basic LLM Chain یک HTTP Request به http://host.docker.internal:8787/v1/chat/completions از API آزمایشی (shared/barg-sabz-mock-api.py) بگذار (پیام سیستمی باید کلمه JSON داشته باشد) و پس از آن یک گره Code که choices[0].message.content را تجزیه کند و در شکست، خطا بدهد. بقیه گامها یکسان است. بدون n8n: شش مورد فایل اعتبارسنجی را حل کن.
سرویس میزبانیشده (در دسترس قانونی)
با ارائهدهندهای که از نظر قانونی در دسترس توست. ببین آیا گره مدل n8n برای آن ارائهدهنده خروجی ساختاریافته بومی را به کار میبرد یا Schema را در پرامپت میگذارد (مستندات گره و ارائهدهنده)؛ در هر دو حالت، قاعده معنایی بماند. فقط داده ساختگی.
اشتباههای رایج
| اشتباه | نتیجه | کار درست |
|---|---|---|
| خواندن مستقیم خروجی متنی مدل با Expression | خالیشدن بیصدا | Output Parser یا Information Extractor |
| Schema از نمونه JSON برای فیلدهای اختیاری | مدل مقدار میسازد | JSON Schema با nullable |
| اعتماد به «Schema معتبر» برای درستی | مقدار غلط ولی معتبر | قاعده معنایی |
| شکست تجزیه بدون خروجی خطا | کل اجرا میایستد یا داده خالی جلو میرود | خروجی خطا، یک تکرار، صف |
| Auto-fixing بدون سقف | فراخوانی اضافه بیحساب | یک تکرار، شمارش هزینه |
| تغییر Schema بدون آزمون | رگرسیون | نسخه Schema و اجرای مجموعه آزمون |
اشکالزدایی
گره مدل با خطای تجزیه شکست میخورد، بهویژه برای پیامهای بلند یا عجیب.
Schema فقط در پرامپت است و مدل متن توضیحی یا بلوک کد اضافه میکند.
خروجی خام چند مورد شکست را ببین؛ مستندات ارائهدهنده را برای خروجی ساختاریافته بومی بخوان.
خروجی ساختاریافته بومی اگر هست؛ وگرنه دستور کوتاهتر، یک مثال، و مسیر تکرار و صف.
گره قبلی متن را دارد ولی Basic LLM Chain خطای «No prompt specified» میدهد.
حالت «Take from previous node automatically» انتظار فیلد chatInput دارد و ورودی آن را ندارد.
ورودی گره را ببین: نام فیلد متن چیست؟
با Edit Fields فیلد را chatInput بنام یا پرامپت را در خود گره با Expression تعریف کن.
با تعویض مدل یا ارائهدهنده، نرخ شکست تجزیه ناگهان بالا رفت.
ارائهدهنده تازه Schema را اجرا نمیکند یا لایه سازگارش پارامتر را بیصدا نادیده میگیرد.
مستندات ارائهدهنده تازه؛ نرخ شکست پیش و پس از تعویض روی همان مجموعه آزمون.
تنظیم حالت Schema متناسب با ارائهدهنده (مثل پروژه ۲)، یا گره و Credential بومی آن ارائهدهنده.
تمرین کوتاه
تمرین · 10 دقیقه
هدف: جداکردن شکل از درستی.
گامها: شش خروجی assets/validation-cases.md را بخوان. برای هرکدام بنویس: آیا Parser آن را رد میکند؟ آیا قاعده معنایی آن را رد میکند؟ کدام قاعده؟
معیار پذیرش: دستکم پنج مورد درست؛ تشخیص اینکه دو مورد از Parser رد میشوند و دو مورد فقط با قاعده معنایی گرفته میشوند.
راهحل نمونه
پاسخ کامل پایین فایل assets/validation-cases.md است: موارد ۲ و ۴ را Parser رد میکند (JSON نیست؛ فیلد اجباری نیست)؛ موارد ۳ و ۵ شکل درستی دارند ولی قاعده معنایی ردشان میکند (شماره سفارش در متن نیست؛ urgent بدون needs_human)؛ ۱ و ۶ معتبرند.
چالش
تمرین · 30 دقیقه
موقعیت: گام طبقهبندی یا استخراجی که در چالش درس قبل برای کار خودت طراحی کردی را در n8n با خروجی ساختاریافته بساز. دادهها ساختگی یا ناشناس باشند.
- Schema را با JSON Schema (enum و nullable جایی که لازم است) بنویس و نسخه بگذار.
- گره مدل با Output Parser یا Information Extractor، و خروجی خطا با یک تکرار و صف.
- دستکم دو قاعده معنایی در If یا Code.
- با ده نمونه (شامل دو مورد لبه) اجرا کن و جدول کن: چند مورد Parser رد کرد، چند مورد قاعده معنایی، چند مورد معتبر.
خروجی مورد انتظار: Schema نسخهدار، ورکفلو، و جدول نتیجه ده نمونه با دلیل هر رد.
معیار پذیرش:
- شکست تجزیه بیصدا نیست و کل اجرا را متوقف نمیکند.
- دستکم دو قاعده معنایی وجود دارد و دستکم یکیشان در نمونهها فعال شده است.
- حالت Schema (اجرا توسط ارائهدهنده یا در پرامپت) برای ارائهدهنده انتخابی مشخص شده است.
- هیچ داده واقعی حساس در نمونهها نیست.
پرسشهای سنجش
جمعبندی
- در n8n: Basic LLM Chain با Output Parser، یا Information Extractor با JSON Schema.
- برای فیلدهای اختیاری از JSON Schema با nullable استفاده کن، نه Schema ساختهشده از نمونه.
- بدان Schema را ارائهدهنده اجرا میکند یا فقط در پرامپت است؛ «سازگار» یعنی یکسان نیست.
- شکست تجزیه: خروجی خطا، یک تکرار، صف بررسی.
- Schema شکل را میگیرد؛ درستی را قاعده معنایی با گره قطعی.
- Schema را نسخهبندی کن و با هر تغییر، مجموعه آزمون را اجرا کن.
پرسشهای سنجش
در n8n میخواهی از متن ایمیل، نام سازمان، تعداد کل و موعد (که ممکن است نیامده باشد) را استخراج کنی. گره و تنظیم Schema را بنویس و بگو چرا حالت «Generate From JSON Example» اینجا مناسب نیست.
پاسخ نمونه و معیار ارزیابی
Information Extractor با Schema Type برابر «Define using JSON Schema»: organization (string)، total_qty (integer)، due_date (string با قالب تاریخ یا null)، همه در required ولی due_date از نوع [string, null]. حالت از نمونه JSON همه فیلدها را اجباری میکند و جایی برای null نمیگذارد؛ مدل برای موعدی که نیامده تاریخ میسازد.
- Information Extractor یا Chain با Parser (1 امتیاز)
- JSON Schema با nullable برای موعد (1 امتیاز)
- دلیل نامناسب بودن حالت نمونه (1 امتیاز)
- از نمونه JSON بساز ← طبق مستندات، همه فیلدها اجباری میشوند.
تیم میتواند طبقهبندی را با ارائهدهندهای انجام دهد که خروجی ساختاریافته را خودش اجرا میکند، یا با ارائهدهندهای که در لایه سازگارش فقط Schema در پرامپت میرود ولی برای متن فارسی دقیقتر بوده است. موازنه را بنویس و بگو در هر انتخاب چه چیزی در ورکفلو ثابت میماند.
پاسخ نمونه و معیار ارزیابی
اولی: شکست تجزیه تقریباً حذف میشود و مسیر خطا کمتر فعال میشود، ولی ممکن است دقت معنایی کمتر باشد. دومی: دقت بهتر، ولی شکست تجزیه بیشتر و نیاز به تکرار و صف (هزینه و تأخیر بیشتر)؛ یا نوشتن آداپتور بومی که خروجی ساختاریافته را اجرا کند. انتخاب با سنجش روی مجموعه آزمون (دقت، نرخ شکست تجزیه، هزینه). در هر دو حالت ثابت میماند: قاعدههای معنایی، مسیر خطا و صف بررسی.
- مزیت و هزینه هر گزینه (2 امتیاز)
- تصمیم با سنجش روی مجموعه آزمون (1 امتیاز)
- ثابت ماندن قاعده معنایی و مسیر خطا (1 امتیاز)
- اولی چون Schema را اجرا میکند پس کافی است ← Schema شکل را تضمین میکند، نه دقت دسته را.
در ورکفلوی طبقهبندی صد پیام، اگر یک پیام شکست تجزیه بدهد، کل اجرا متوقف میشود و ۹۹ پیام دیگر هم طبقهبندی نمیشوند. علت و اصلاح؟
پاسخ نمونه و معیار ارزیابی
On Error گره مدل روی Stop Workflow است. اصلاح: Continue (using error output)؛ شاخه خطا یک بار با یادآوری تکرار کند و اگر باز شکست خورد، آن پیام را با دلیل به صف بررسی بفرستد؛ بقیه پیامها ادامه پیدا کنند. شمار شکستها در گزارش.
- Stop Workflow را علت میداند (1 امتیاز)
- خروجی خطا با تکرار و صف (1 امتیاز)
- Continue ساده ← پیام شکستخورده با داده خالی جلو میرود.
کدام خطا را Structured Output Parser نمیگیرد و فقط قاعده معنایی میگیرد؟
- پاسخ متنی بدون JSON.
- نبودن فیلد اجباری category.
- order_id برابر «10482» در حالی که این عدد در پیام نیست.
- urgent بهشکل رشته «yes».
پاسخ نمونه و معیار ارزیابی
- a ← تجزیه شکست میخورد؛ Parser آن را میگیرد.
- b ← Schema فیلد اجباری را میگیرد.
- d ← نوع بولی در Schema است؛ Parser یا اعتبارسنجی Schema آن را میگیرد.
برای خروجی Schema این درس، سه قاعده معنایی قطعی بنویس که در If قابل پیادهسازی باشند، و برای هرکدام بگو اگر نقض شد چه میشود.
پاسخ نمونه و معیار ارزیابی
(۱) order_id تهی است یا در متن پیام (با یکسانسازی ارقام) هست ← نقض: صف بررسی با دلیل «شماره ساختگی». (۲) اگر urgent درست است، needs_human هم درست است ← نقض: needs_human را درست کن یا صف. (۳) اگر category برابر payment یا returns_exchange است، needs_human درست است ← نقض: درست کن و ثبت. (قاعدههای معادل مثل طول summary یا دسته در فهرست بسته هم پذیرفته است.)
- سه قاعده قطعی و قابل پیادهسازی (2 امتیاز)
- رفتار روشن برای نقض (1 امتیاز)
- از مدل بپرس درست است یا نه ← اینها قاعده ثابتاند؛ گره قطعی ارزانتر و قابل اعتمادتر است.
فایلهای درس
مدل آزمایشی با حالت خروجی خراب برای آزمون مسیر خطا
barg-sabz-mock-api.pyJSON Schema طبقهبندی و استخراج تیکت
triage-schema.jsonشش خروجی مدل برای تمرین اعتبارسنجی شکلی و معنایی، با پاسخ
validation-cases.mdابزارها و جایگزینها
- n8n 2.x — گرههای AI و اعتبارسنجی — مسیر بدون نصب
- یک مدل زبانی — تولید خروجی — Ollama محلی — مدل آزمایشی
منابع
Basic LLM Chain node n8n accessed 2026-10-20
Information Extractor node n8n accessed 2026-10-20
Structured model outputs OpenAI docs 2026-10
Structured outputs Ollama docs 2026-10
OpenAI SDK compatibility Anthropic accessed 2026-10-16
Structured output Google docs 2026-10