פלטים מובנים של LLM שנשברים: איך באמת כותבים Schema למצב strict
שורה תחתונה: הפעלת strict על JSON Schema שרירותית מחזירה כמעט תמיד 400: כל השדות required, additionalProperties:false בכל אובייקט, ו-$ref ו-allOf נדחים מיד. המדריך הזה מראה איך לשכתב סכימה פתוחה לגרסה תואמת strict — עם union nullable, מגבלות קשיחות וצ'קליסט ל-refusal.

העיקר: strict: true הוא לא מתג "התנהג יותר ברצינות" — זה חוזה שמקבל רק תת-קבוצה של JSON Schema. כל השדות required, additionalProperties: false בכל אובייקט, ו-$ref ו-allOf אסורים מיד. אם שולחים סכימה במצב strict בלי לשכתב אותה, התשובה היא 400, לא פלט אמין.
בעבודת היום־יום התמונה חוזרת בדיוק כך: לצוות יש סכימה מתוכננת היטב, עם שדות אופציונליים, $defs שניתנים לשימוש חוזר ו-additionalProperties פתוח מטעמי תאימות. ואז מישהו מוסיף "strict": true לקריאת ה-API, בביטחון שהמודל עכשיו "יכבד" את הסכימה. התוצאה המיידית היא שגיאת 400 עם הודעה ארוכה, או גרוע — סכימה שנתקבלת אבל מייצרת פלטים בלתי צפויים. מצב strict לא מפרש את הסכימה בסובלנות: הוא שוכתב אותה מחדש לדקדוק שמנוע הייצור יכול לעקוב אחריו מילה במילה, וכל מה שלא נכנס לדקדוק הזה נדחה או מתעלם בשקט. הבנה אילו כללים בתוקף בפועל, לפני שליחת הבקשה, היא ההבדל בין צינור יציב לשבוע של דיבוג.
מצב strict = ה-JSON Schema שלך מתקמפל לדקדוק שהמודל חייב לעקוב אחריו מילה אחר מילה. כל מה שהדקדוק לא יכול לבטא נדחה בשליחה או מתעלם בשקט — ובשני המקרים הבעיה מתגלה אחרי שהמשתמש כבר ראה אותה.
איך מנוע מצב strict באמת עובד
המודלים לא קוראים את ה-JSON Schema שלך כמו מאמת רגיל. כש-strict: true מופעל, הסכימה מומרת לדקדוק מוגבל — אוטומט מצבים סופי שמחליט, טוקן אחר טוקן, אילו המשכים חוקיים. המודל מייצר רק מעברים שהאוטומט מרשה; אין בקרה שלאחר הייצור שמתקנת את הפלט — הנכונות היא מבנית.
הארכיטקטורה הזו מסבירה את כל ההתנהגויות שנראות מסתוריות. אם שדה לא כלול ב-required, האוטומט צריך להחליט מתי לעצור: הפתרון הבטוח היחיד הוא לתת למודל חופש לפלוט null, ולכן הסכימה האפקטיבית שהמנוע מקבל תכיל את השדה הזה תמיד. אם אובייקט מרשה מאפיינים נוספים, האוטומט לא יכול לחזות אילו מפתחות יופיעו, ולכן כל אובייקט חייב להיסגר בחוזקה. כל "אסור" בתיעוד נולד מהגבלה קונקרטית של האוטומט הזה, לא מבחינה סגנונית של OpenAI.
ההשלכה השנייה ערמומית יותר: מילות מפתח מסוימות ב-JSON Schema (כמו pattern, minLength, maximum) תקפות לסכימה אבל לא נאכפות על ידי הדקדוק. הסכימה מתקבלת, התשובה מגיעה נקייה, אבל האילוץ לא ממולא לעולם. זו הדרך השקטה ביותר לשבור צינור: הוולידציה הבאה נופלת בפרודקשן ואף לוג לא מראה שגיאת סכימה.
שלושת הכללים שאי אפשר למקח עליהם
אם יש לך זמן לתקן רק דבר אחד — תקן את שלושת אלה. הם פותרים את הרוב המכריע של ה-400.
1. כל השדות ב-required, תמיד. במצב strict, כל מפתח שמוכרז ב-properties חייב להופיע ב-required — גם האופציונליים. התחבולה הרשמית להגיד "אופציונלי" היא union nullable:
{
"type": "object",
"properties": {
"couponCode": { "type": ["string", "null"] }
},
"required": ["couponCode"],
"additionalProperties": false
}
כך האוטומט יודע בדיוק מתי המפתח חוקי, והמודל מביע "אין קופון" ב-null במקום להשמיט את המפתח.
2. additionalProperties: false בכל אובייקט. לא רק באובייקט השורש: כל אובייקט מקונן, ללא יוצאים מן הכלל. רמה אחת פתוחה עושה את כל הסכימה לא תואמת.
3. $ref ו-allOf אסורים. בלי הפניות, בלי $defs, בלי קומפוזיציה. הסכימה חייבת להיות מורחבת לגמרי — עץ יחיד שעומד בפני עצמו. if/then/else ו-oneOf בשורש חולקים את אותו גורל.
טבלת מונחים אסורים וחסרי תוקף
| מילת מפתח | תוצאה במצב strict | תחליף מומלץ |
|---|---|---|
$ref, $defs |
דחייה עם 400 | הרחבה מלאה של הסכימה |
allOf |
דחייה עם 400 | מיזוג מאפיינים ידני |
if/then/else |
דחייה עם 400 | enum + טיפול בצד הלקוח |
oneOf בשורש |
בעיות / תשובה לא תואמת | אובייקט שורש אחד בלבד |
שדה מחוץ ל-required |
הופך לחובה תמידית | union nullable ["string", "null"] |
pattern, minLength |
סכימה מתקבלת אך האילוץ מתעלם | ולידציה מפורשת אחרי התשובה |
maximum, format |
סכימה מתקבלת אך האילוץ מתעלם | בדיקה בצד האפליקציה |
השורה המסוכנת ביותר היא הזוג האחרון: הסכימה עוברת ולידציה אבל האילוץ לא קיים. אם הלוגיקה שלך סומכת על pattern, אתה בונה על חול.
המגבלות הקשיחות שאף אחד לא קורא
לפני כתיבת הסכימה, ודא שאתה בתוך הגבולות האלה — חריגה מהם מייצרת שגיאות כלליות שקשה לאבחן:
| אילוץ | מקסימום |
|---|---|
| סך המאפיינים לסכימה | 5000 |
| עומק הקינון | 10 רמות |
| גודל מחרוזת הסכימה | 120,000 תווים |
| סך ערכי ה-enum | 1000 |
סכימות שנוצרות אוטומטית מפריימוורקים או הגדרות OpenAPI חורגות לעיתים קרובות מהמגבלות האלה בלי שאיש מבחין: 6000 מאפיינים בסך הכול, 12 רמות קינון, 1500 ערכי enum פזורים. הודעת השגיאה של ה-API נדירה שמציינת איזה סף נחצה, לכן כדאי לבדוק בעצמך לפני השליחה.
שכתוב אוטומטי: סקריפט make_strict
לסכימות גדולות, שכתוב ידני אינו מעשי. הסקריפט הזה בפייתון עובר על העץ ומיישם את שלושת הכללים באופן רקורסיבי:
import json
def make_strict(node):
if isinstance(node, dict):
if node.get("type") == "object":
props = node.get("properties", {})
# כל מאפיין הופך ל-required
node["required"] = list(props.keys())
node["additionalProperties"] = False
# שדות "אופציונליים" חייבים לסמן nullable מראש בעצמך
# הסר את מה ש-strict לא מקבל
for k in ("$ref", "$defs", "allOf", "if", "then", "else"):
node.pop(k, None)
return {k: make_strict(v) for k, v in node.items()}
if isinstance(node, list):
return [make_strict(v) for v in node]
return node
schema = json.load(open("schema.json"))
print(json.dumps(make_strict(schema), indent=2))
שתי אזהרות. ראשונה: הסקריפט לא מנחש אילו שדות היו אופציונליים — union nullable תצטרך לסמן בעצמך, רצוי במקור הסכימה ולא בתוצאה. שנייה: אחרי ההמרה, הרץ תמיד בקשת ניסיון: ההרחבה עלולה לחצות מגבלות גודל או מספר מאפיינים שבעבר עמדת בהן.
הדרך המקבילה ב-Anthropic
Anthropic לא חושפת דגל strict, אבל מגיעה לאותה תוצאה במנגנון tool: הגדרת הכלי משמשת כסכימה, והמודל קשור לצורתה. הגישה זהה כמעט במלואה:
const tool = {
name: "extract_invoice",
description: "מחלץ נתוני חשבונית מהטקסט",
input_schema: {
type: "object",
properties: {
invoiceNumber: { type: "string" },
totalAmount: { type: ["number", "null"] },
lineItems: {
type: "array",
items: {
type: "object",
properties: {
description: { type: "string" },
quantity: { type: "number" }
},
required: ["description", "quantity"],
additionalProperties: false
}
}
},
required: ["invoiceNumber", "totalAmount", "lineItems"],
additionalProperties: false
}
};
// המודל עונה בקריאת tool תואמת
const response = await anthropic.messages.create({
model: "claude-sonnet-4-5",
max_tokens: 1024,
tools: [tool],
tool_choice: { type: "tool", name: "extract_invoice" },
messages: [{ role: "user", content: invoiceText }]
});
הכלל המעשי זהה: גם ב-Anthropic, כל אובייקט זקוק ל-required מלא ו-additionalProperties: false. ההבדל בערוץ התשובה — tool_use במקום תוכן טקסטואלי — ובכך שהשדה refusal הוא ייחודי ל-OpenAI.
refusal, חיתוך וצורה שבורה: שלושה תקלות, שלושה פתרונות
גם עם סכימה מושלמת, הפלט עלול להיכשל משלוש סיבות שונות, ובלבול ביניהן הוא הדרך המהירה לאבד יום שלם:
1. refusal לא ריק. OpenAI במצב strict עשויה להחזיר שדה refusal עם הסיבה שבגינה דחתה את הבקשה. זו לא שגיאת סכימה — המודל סירב למשימה באופן סמנטי. הפתרון הוא לעיין מחדש בפרומפט או במדיניות, לא בסכימה.
2. חיתוך בגלל max_tokens. הייצור נקטע באמצע מחרוזת וה-JSON לא נסגר. במצב strict, התשובה אם היא מגיעה תואמת — אבל אם תקציב הטוקנים נגמר, היא מגיעה חתוכה. העלה את max_tokens או הקטן את גודל הפלט הצפוי. לתרחישים חוזרים, התיקון האוטומטי של JSON חתוך מציע דפוסים מוכנים.
3. צורה שבורה לא תואמת. הסכימה הייתה פתוחה (מאפיינים נוספים מורשים, שדות מחוץ ל-required) ו-strict לא היה פעיל: המודל מייצר JSON תקין שלא מקיים את החוזה. הפתרון הוא לשכתב את הסכימה כמו במדריך הזה, לא להוסיף בקרות שלאחר הייצור.
אבחון נכון תמיד מתחיל בהבחנה בין שלושת המקרים: להסתכל על השדה finish_reason, על נוכחות refusal, ולהשוות את התשובה לסכימה שנשלחה בפועל.
צ'קליסט סופי לפני עלייה לפרודקשן
| נקודת בדיקה | מה לבדוק |
|---|---|
required מלא |
כל מאפיין מוכרז נמצא ב-required |
| nullable מפורש | שדות אופציונליים הם union ["...", "null"] |
additionalProperties: false |
בכל אובייקט, לא רק בשורש |
אפס $ref / allOf / if-then-else |
הסכימה מורחבת לגמרי |
| מגבלות מקוימות | ≤ 5000 מאפיינים, ≤ 10 רמות, ≤ 120k תווים |
| אילוצים חסרי תוקף הועברו | pattern/format נבדקים בצד האפליקציה |
טיפול ב-refusal |
הקוד מבדיל סירוב משגיאת סכימה |
| בדיקה בבקשה אמיתית | תשובת ניסיון אומתה לפני deploy |
אם אתה רוצה להבין למה additionalProperties: false כל כך מרכזי, הניתוח המעמיק של מילת המפתח additionalProperties מראה כיצד כל אובייקט פתוח מרחיב את מרחב הייצור. להכנסת הסכימה לצינור CI עם בדיקות חוזה אוטומטיות, הזרימה המתוארת ב-JSON Schema contract testing סוגרת רגרסיות שקטות. ואם עליך לבנות סכימה מדוגמאות JSON קיימות, הכלי להמרה ל-JSON Schema בפלטפורמה נותן לך להתחיל מנתונים אמיתיים — עם זאת, למצב strict עדיין תצטרך להחיל את השכתוב מהמדריך הזה.
FAQ
למה התיעוד מחייב שכל השדות יהיו required, גם האופציונליים?
כי האוטומט מצבים סופי צריך להחליט מראש מתי כל מפתח חוקי. "אופציונליות" מבוטאת ב-null, לא בהיעדר המפתח: union nullable היא הדרך הרשמית להגיד זאת.
הסכימה התקבלה אבל ה-pattern לא עובד. זה באג?
לא. במצב strict, pattern, minLength, maximum ו-format לא נאכפים על ידי דקדוק הייצור. הסכימה תקפה תחבירית אבל האילוץ לא קיים: בדוק בצד האפליקציה.
אפשר להשתמש ב-$ref אם מכריזים גם $defs?
לא, בשני המקרים זה אסור. הסכימה חייבת להיות עץ יחיד, מורחב לגמרי. סקריפטים של שכתוב אוטומטי מטפלים בהרחבה.
מה ההבדל בין refusal לשגיאת סכימה? refusal היא תשובה תואמת שבה המודל מצהיר סמנטית שאינו רוצה לבצע את המשימה. שגיאת סכימה היא 400 בשליחה או פלט לא תואם. שתי בעיות שונות עם שני פתרונות שונים.
עד כמה עמוק אפשר לקנן אובייקטים? 10 רמות קינון מקסימום ו-5000 מאפיינים בסך הכול לסכימה. סכימות שנוצרות אוטומטית חורגות לעיתים קרובות מהמגבלות האלה: בדוק לפני השליחה.
סיכום
מצב strict אינו אפשרות קוסמטית: זו המעבר מ"אני מקווה שהמודל יכבד את הסכימה" ל"הדקדוק מונע פיזית פלטים לא תואמים". המחיר הוא תת-קבוצה נוקשה של JSON Schema — required מלא, אובייקטים סגורים, בלי הפניות — וכמה אילוצים שעוברים בלי לב ואינם נאכפים. הקדש חצי שעה לשכתוב בסקריפט make_strict, סמן union nullable בשיקול דעת, ותמיד בדוק בבקשה אמיתית לפני deploy: הצינור שמתקבל שונה באיכותו מצינור שנבנה על retry ותיקונים אחרי העובדה.