JSON Toolkit

פלטים מובנים של LLM שנשברים: איך באמת כותבים Schema למצב strict

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

בינוניכ-8 דקות קריאהפורסם 2026-11-19עודכן 2026-11-19
דיאגרמת כללי שכתוב JSON Schema למצב strict ב-LLM

העיקר: 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 ותיקונים אחרי העובדה.

מקורות

מאמרים קשורים

בדיקות חוזה עם JSON Schema: ריתוך כללי האימות אל ה-CI

הסכמה לא מסתיימת כשכותבים אותה — שם מתחילה הידרדרות. שגיאת הקלדה אחת מרפה את האימות בשקט, רפקטורינג אחד שובר את כל הפיקסטורות. המדריך הזה מפרק מערכת בדיקות חוזה שאפשר להריץ: פיקסטורות חיוביות, שליליות וסנאפשוט, lint לסכמה עצמה, הידור פעם אחת עם שימוש חוזר, וארבעה שערי CI שהופכים שינויים שוברי-חוזה לבילדים אדומים.

בינוניכ-8 דקות קריאהעודכן 2026-11-05

JSON ממודל שפה שנחתך באמצע: קודם סיבת העצירה, אחר כך תיקון

המודל מחזיר JSON שקטוע באמצע ערך, והמנתח נותן רק מספר עמודה. סגירת סוגריים הופכת אותו שוב לניתן לניתוח, אבל כל שדה שנעלם מוסתר עכשיו בתוך הנתונים. המאמר משרטט את הגבול בין מה שתיקון חיתוך יכול להחזיר ביושר לבין מה שחייבים לבקש מחדש.

מעשיכ-5 דקות קריאהעודכן 2026-11-14

בלי additionalProperties, אימות הסכמה לא מאמת כלום

עמידה באימות לא אומרת שהנתונים נקיים. Pydantic מתעלם משדות לא מוכרים כברירת מחדל, Zod מסיר אותם, Ajv מרשה להם לעבור — פרמטרים מומצאים ומפתחות עם שגיאת הקלדה עוברים בשקט. המאמר מציג שלוש צורות של קבלה שקטה ונותן מתכונים מלאים: לסגור אובייקטים, לשלוט בהמרת טיפוסים ולהדק כל רמת קינון.

Intermediateכ-8 דקות קריאהעודכן 2026-11-02