چیت‌شیت
خروجی‌های ساختاریافته و رمزگشایی مقید
Structured Outputs and Constrained Decoding
همیشه JSON معتبر بگیرید. اسکیماها، حالت سخت‌گیرانه، ماسک‌های لاجیت، اعتبارسنج‌ها، تلاش‌های مجدد و پروژه‌ی محافظ خروجی.
فهرست مطالب
پایپ‌لاین محافظ خروجی
معمارییک گام رمزگشایی مقید
گام‌به‌گام- مدلیک بردار لاجیت روی کل واژگان (حدود 100k توکن) صادر می‌کند.
- FSMتابع
fsm.valid_tokens(state, tokenizer)توکن‌هایی را که مسیر پذیرش را حفظ می‌کنند فهرست می‌کند. - ماسکتابع
mask_logitsمقدار سایر لاجیت‌ها را برابرfloat("-inf")قرار می‌دهد. - نمونه‌گیریسافت‌مکس همه‌ی احتمال را روی توکن‌های معتبر می‌گذارد. یکی را انتخاب کنید.
- پیشرویتابع
fsm.transition(state, tok). توقف وقتیfsm.is_accept(state)برقرار باشد.
اجرای پروژه‌ی محافظ خروجی
دستورها| دستور | کارکرد |
|---|---|
python3 scripts/project_test.py json-schema-output-guard --init <ws> | محیط کاری شما را یک‌بار می‌سازد. کد آغازین خام ناموفق می‌شود |
python3 scripts/project_test.py json-schema-output-guard --stage 1 --path <ws> --strict | نمره‌دهی به یک مرحله، از 1 تا 4 |
python3 scripts/project_test.py json-schema-output-guard --all --solution --strict | نمره‌دهی به راه‌حل مرجع |
node cli.ts --schema samples/schema.json --attempts samples/attempts.json --output guard.json --html guard.html | ترمیم ثبت‌شده. تلاش 1 در $/confidence ناموفق می‌شود |
وظایف در کد
کار و کد| وظیفه | کد |
|---|---|
| تولید JSON محلی با یک FSM | generator = outlines.generate.json(model, Review) |
| Pydantic به همراه تلاش مجدد، با هر ارائه‌دهنده‌ای | client = instructor.from_anthropic(Anthropic()) |
| حالت اسکیمای ارائه‌دهنده | client.beta.chat.completions.parse(..., response_format=Product) |
| اعتبارسنجی یک دیکشنری | `validate_schema(data, schema)` returns a list of errors |
| تجزیه، اعتبارسنجی، تلاش مجدد | extract_with_retry(text, schema, max_retries=3) |
| کنترل‌کننده‌ی سه‌شاخه (three-branch) | process_model_output(raw, INVOICE_SCHEMA) |
| محافظت از یک رشته‌ی خام | `guard(raw, schema)` returns `ok`, `value`, `issues` |
| ترمیم محدودشده | await repair(generate, schema, maxAttempts) |
پرسش‌ها
پرسش و پاسخ- آیا امتناع مدل باید تلاش مجدد را فعال کند؟
- خیر. آن را لاگ کنید و یک امتناع تایپ‌شده برگردانید.
- آیا رمزگشایی مقید کندتر است؟
- اغلب سریع‌تر است. توکن‌های اجباری فرایند تولید را دور می‌زنند.
- آیا به مدل بزرگی نیاز دارد؟
- خیر. یک مدل 3B مجهز به گرامر از یک مدل 70B با پرامپت‌ها بهتر عمل می‌کند.
- آیا پذیرش، درستی پاسخ را ثابت می‌کند؟
- خیر. صحت محتوایی و واقعی را تضمین نمی‌کند.
- چرا باید اول checkSchema فراخوانی شود؟
- یک اسکیمای خراب دیگر نمی‌تواند بودجه‌ی ارائه‌دهنده را هدر دهد.
نکات
نکته‌ها- مدل محلی، اسکیمای مسطح: Outlines. اسکیمای بازگشتی: XGrammar یا llguidance.
- سرور خودمیزبان: vLLM گزینه‌های
guided_json،guided_regexوguided_choiceدارد. - زمانی که مدل باید یکی از چند اسکیما را برگزیند از استفاده از ابزار کمک بگیرید.
- به‌جای متن آزاد، آرایه‌ی ساختاریافته‌ی
Issue[]را به مدل بازگردانید. - تمام تلاش‌ها را در ردگیری محاسبات نگه دارید. موفقیت دیرهنگام، شکست‌های قبلی را پنهان نمی‌کند.
- محافظ
$ref، فرمت و ترکیب‌کننده‌ها را رد می‌کند. - در دستورات پروژه،
<ws>همانlearning-artifacts/json-schema-output-guardاست.
اسکیمای Pydantic با Instructor
کدpython
class Invoice(BaseModel):
vendor: str
total_usd: float = Field(ge=0) # محدوده‌ی عددی
line_items: list[str]
client = instructor.from_anthropic(Anthropic())
invoice = client.messages.create(
model="claude-opus-4-7",
max_tokens=1024,
response_model=Invoice, # تلاش مجدد هنگام نقض اعتبارسنجی
messages=[{"role": "user", "content": "<text>"}],
)
ترمیم محدودشده در TypeScript
کدtypescript
const schema: Schema = {
type: "object",
properties: {
answer: { type: "string", minLength: 1 },
confidence: { type: "number", minimum: 0, maximum: 1 },
},
required: ["answer", "confidence"],
additionalProperties: false, // ویژگی ناشناخته یک مشکل محسوب می‌شود
};
await repair(async (_, i) => outputs[i - 1], schema) // وضعیت و ردگیری محاسبات
سطوح کنترل
مفهوم‌ها- مبتنی بر پرامپت
- "در قالب JSON معتبر پاسخ دهید". حدود 90% معتبر. بدون اجبار قطعی.
- حالت JSON
- نحوِ معتبر JSON. بدون ضمانت انطباق با اسکیما.
- حالت اسکیما
- خروجی با اسکیمای JSON مطابقت دارد. به‌صورت بومی در همه‌ی ارائه‌دهندگان بزرگ موجود است.
- رمزگشایی مقید
- توکن‌های نامعتبر را ماسک می‌کند. 100% معتبر بر پایه‌ی ساختار.
- Instructor
- لاجیت‌ها را دستکاری نمی‌کند. تجزیه، اعتبارسنجی و تلاش مجدد انجام می‌دهد.
- Outlines
- اسکیما یا regex را به یک FSM کامپایل می‌کند. بازگشت نیازمند مسطح‌سازی است.
- XGrammar، llguidance
- موتورهای CFG. اسکیماهای بازگشتی را پردازش می‌کنند.
- حالت سخت‌گیرانه
- تمام فیلدها درون
required،additionalProperties: falseو بدون$ref.
پیش‌فرض‌ها و اعداد
پیش‌فرض‌ها| تنظیم | پیش‌فرض | نکته |
|---|---|---|
max_retries | 3 | در extract_with_retry |
Instructor retries | 3 | هنگام نقض اعتبارسنجی |
Retry limit | 3x | تلاش‌های مجددِ بیشتر نشانهٔ یک اسکیمای نامناسب است |
maxAttempts | 3 | بودجه باید بین 1..10 باشد |
Depth limit | 32 | checkSchema و validate |
Output size cap | 100_000 | بایت‌ها، پیش از JSON.parse بررسی می‌شوند |
CLI exit code | 2 | نتیجه‌ی ردشده یا پایان‌یافته |
Prompt-only JSON | 85 to 95 percent | نرخ موفقیت در مدل‌های مرزی |
عیب‌یابی
عیب‌یابیJSON معتبر، پاسخ اشتباه
- علت
answerقبل ازreasoning- راه‌حل
- فیلدهای استدلال را اول قرار دهید
مدل تاریخ ساختگی تولید می‌کند
- علت
- گرامر بیش از حد سخت‌گیر است
- راه‌حل
- اجازه‌ی مقدار
nullیا یک مقدار نشانگر (sentinel) را بدهید
تایم‌اوت در enum با 10,000 گزینه
- علت
- enum بسیار بزرگ
- راه‌حل
- موارد k تای برتر را بازیابی و خروجی را به آن‌ها محدود کنید
خروجی درختی در Outlines با شکست مواجه می‌شود
- علت
- FSM بازگشت را مسطح می‌کند
- راه‌حل
- از XGrammar یا llguidance استفاده کنید
JSON معتبر، ساختار اشتباه
- علت
- حالت JSON بدون اسکیما
- راه‌حل
- همیشه یک اسکیمای کامل ارسال کنید
خطای 400 از API
- علت
- نقض قوانین حالت سخت‌گیرانه
- راه‌حل
- اصلاح
required، فیلدهای اضافی و$ref
نوع داده درست، مقدار ساختگی
- علت
- مقدار توهم‌شده
- راه‌حل
- اسکیما جلوی آن را نمی‌گیرد. مقادیر را اعتبارسنجی کنید
فیلد اختیاری حذف شده است
- علت
- فیلد جزو required نیست
- راه‌حل
- آن را اجباری کنید، اما مقدار
nullرا بپذیرید
کوته‌نوشت‌ها
اصطلاح‌ها- FSM
- ماشین وضعیت متناهی. جستجوی توکن معتبر بعدی با پیچیدگی $O(1)$.
- CFG
- گرامر مستقل از متن. ساختارهای بازگشتی را مدیریت می‌کند.
- پردازنده‌ی لاجیت
- تابع
(logits, state) -> masked_logits. - رمزگشایی هدایت‌شده
- همان مفهوم در سرور استنتاج.
- امتناع مدل
- خروجی تایپ‌شده زمانی که ورودی با اسکیما همخوانی ندارد.
- خطای تجزیه
- خروجی JSON نیست. در حالت سخت‌گیرانه غیرممکن است.
- نقض اسکیما
- خروجی تجزیه می‌شود اما اسکیما را نقض می‌کند.
- مشکل
- ساختار
{ path: string; message: string }در پروژه‌ی محافظ.