פלט מובנה עם מודלים של Anthropic Claude

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

פלט מובנה מספק שתי תכונות משלימות שאפשר להשתמש בהן בנפרד או ביחד באותה בקשה:

  • ‫JSON outputs (output_config.format): מגבילים את תשובת הטקסט של המודל לאובייקט JSON שתואם לסכימה שאתם מספקים. השתמשו בזה כשאתם צריכים לחלץ נתונים מובְנים מטקסט, ליצור דוחות מובְנים או לעצב תשובות של API.
  • שימוש מדויק בכלי (tools[].strict): מוודא שהארגומנטים שהמודל מעביר לכלי תואמים לinput_schema של הכלי. משתמשים בפונקציה הזו כשצריך לבצע קריאות לפונקציות בטוחות לסוגים בתהליכי עבודה של סוכנים.

מידע נוסף זמין במאמרים של Anthropic בנושא יצירת פלט מובנה באמצעות Claude ושימוש קפדני בכלי.

מודלים נתמכים של Anthropic Claude

‫Gemini Enterprise Agent Platform תומכת בפלט מובנה בכל המודלים של Anthropic Claude 4.5 ומגרסאות מתקדמות יותר.

שליטה בגישה לפלט מובנה

כברירת מחדל, פלט מוּבְנֶה מושבת על ידי אילוץ מדיניות הארגון constraints/vertexai.allowedPartnerModelFeatures. כדי להפעיל פלט מובנה, צריך להגדיר את האילוץ הזה כך שיאפשר באופן מפורש את התכונה structured_outputs.

בנוסף, אפשר להגדיר את אילוץ מדיניות הארגון constraints/vertexai.allowedModels כדי להגביל את הגישה למודלים של Claude.

הוראות מפורטות להגדרת אילוצים של מדיניות הארגון זמינות במאמר בנושא שליטה בגישה למודלים ב-Model Garden.

שליחת בקשה לפלט מובנה

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

REST

בדוגמה הבאה מוסבר איך לשלוח בקשה ל-Agent Platform API כדי לחלץ פרטים מובְנים ליצירת קשר מאימייל לא מובְנה. התגובה מוגבלת לאובייקט JSON עם השדות name, email, plan_interest ו-demo_requested.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫LOCATION: אזור שתומך במודלים של Anthropic Claude. כדי להשתמש בנקודת הקצה הגלובלית, אפשר לעיין במאמר בנושא הגדרת נקודת הקצה הגלובלית.
  • ‫MODEL: מודל Claude נתמך, לדוגמה claude-opus-4-7.
  • ROLE: התפקיד שמשויך להודעה. אפשר לציין user או assistant. ההודעה הראשונה חייבת להשתמש בתפקיד user. מודלים של Claude פועלים עם תחלופה בין תורות של user ושל assistant. אם ההודעה האחרונה משתמשת בתפקיד assistant, תוכן התגובה ממשיך מיד מהתוכן שבהודעה הזו. אתם יכולים להשתמש בזה כדי להגביל חלק מהתשובה של המודל.
  • ‫CONTENT: התוכן, למשל הטקסט, של ההודעה user או assistant. לדוגמה, Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm.
  • ‫MAX_TOKENS: המספר המקסימלי של טוקנים שאפשר ליצור בתשובה. טוקן הוא בערך 3.5 תווים. ‫100 טוקנים מקבילים בערך ל-60 עד 80 מילים.

    כדי לקבל תשובות קצרות יותר, מציינים ערך נמוך יותר, וכדי לקבל תשובות ארוכות יותר, מציינים ערך גבוה יותר.

  • ‫STREAM: ערך בוליאני שמציין אם התגובה מועברת בסטרימינג או לא. הערך true מאפשר להציג את התשובה באופן שוטף, והערך false מאפשר להציג את התשובה כשהיא מוכנה. בדרך כלל, פלט מובנה מוחזר עם false.

בדוגמה נעשה שימוש בשדות הפלט המובנים הבאים. פרטים על כל שדה מופיעים בקטע שדות הבקשה.

  • ‫output_config: בלוק ההגדרות ברמה העליונה ששולט במבנה של התשובה של המודל.
  • ‫output_config.format.type: מגדירים את הערך json_schema כדי להגביל את התשובה לאובייקט JSON שתואם לסכימה שצוינה.
  • ‫output_config.format.schema: סכימת JSON שמגדירה את המבנה הנדרש של התשובה של המודל. הסכימה חייבת להיות תואמת לקבוצת המשנה הנתמכת של סכימת JSON.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict

גוף בקשת JSON: 

{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_TOKENS,
  "stream": STREAM,
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "email": {"type": "string"},
          "plan_interest": {"type": "string"},
          "demo_requested": {"type": "boolean"}
        },
        "required": ["name", "email", "plan_interest", "demo_requested"],
        "additionalProperties": false
      }
    }
  }
}

כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו: השדה text של הבלוק content מכיל מחרוזת JSON שתואמת לסכימה שציינתם ב-output_config.

שדות של בקשות

השדות הבאים ספציפיים לפלט JSON. מידע על שדות בקשות אחרים מופיע במאמר בנושא Claude messages API.

  • ‫output_config: בלוק ההגדרות ברמה העליונה ששולט במבנה של התשובה של המודל.
  • ‫output_config.format: הגדרת הפורמט של הפלט. יש תמיכה רק בסוג json_schema.
  • ‫output_config.format.type: סוג פורמט הפלט שרוצים לאכוף. מגדירים את הערך הזה ל-json_schema כדי שהתגובה תהיה אובייקט JSON.

  • ‫output_config.format.schema: סכימת JSON שמגדירה את המבנה הנדרש של התשובה של המודל. הפלט המובנה תומך בסכימת JSON רגילה עם כמה מגבלות, כמו הדרישה להגדיר את additionalProperties ל-false לאובייקטים, ואי-תמיכה באילוצים מספריים או באילוצים של אורך מחרוזת. רשימה מלאה של התכונות הנתמכות והלא נתמכות מופיעה במסמכי התיעוד של Anthropic בנושא מגבלות של סכימת JSON. בסכימה, בדרך כלל מציינים:

    • ‫type: סוג ה-JSON של הערך ברמה הזו (בדרך כלל object עבור סכימת הבסיס).
    • ‫properties: מפה של שמות שדות להגדרות הסוג שלהם, שמתארות כל שדה שהמודל צריך להחזיר.
    • ‫required: רשימה של שמות מאפיינים שהמודל צריך לכלול בתשובה שלו.
    • ‫additionalProperties: ערך בוליאני. אם הערך הוא false, המודל לא יכלול שדות שלא הוגדרו ב-properties.

שימוש קפדני בכלים

שימוש קפדני בכלי מבטיח שהארגומנטים שהמודל מעביר לכלי תואמים ל-input_schema של הכלי. בלי מצב קפדני, יכול להיות שהמודל יפעיל כלי עם ארגומנטים שסוג הנתונים שלהם לא נכון (לדוגמה, "2" במקום 2) או ישמיט שדות נדרשים, מה שיכול לשבש את הפונקציות הבאות ולדרוש לוגיקה של ניסיון חוזר. כשמפעילים את המצב הקפדני, ה-API משתמש בדגימה מוגבלת על ידי כללי הדקדוק כדי לוודא ש:

  • הכלי name הוא תמיד אחד מהכלים שסיפקתם.
  • הכלי input תמיד פועל בהתאם לinput_schema שלו.

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

כדי להפעיל שימוש קפדני בכלי, מגדירים את "strict": true כשדה ברמה העליונה בהגדרת הכלי, לצד name,‏ description ו-input_schema.

REST

בדוגמה הבאה אפשר לראות איך שולחים בקשה ל-Agent Platform API שמגדירה כלי get_weather מחמיר. המודל מתחייב להפעיל את הכלי עם מחרוזת location ועם unit אופציונלי שהוא celsius או fahrenheit.

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

  • ‫LOCATION: אזור שתומך במודלים של Anthropic Claude. כדי להשתמש בנקודת הקצה הגלובלית, אפשר לעיין במאמר בנושא הגדרת נקודת הקצה הגלובלית.
  • ‫MODEL: מודל Claude נתמך, לדוגמה claude-opus-4-7.
  • ROLE: התפקיד שמשויך להודעה. ההודעה הראשונה חייבת להשתמש בתפקיד user.
  • ‫CONTENT: התוכן, למשל הטקסט, של ההודעה user או assistant. לדוגמה, What is the weather in San Francisco?
  • ‫MAX_TOKENS: המספר המקסימלי של טוקנים שאפשר ליצור בתשובה. טוקן הוא בערך 3.5 תווים. ‫100 טוקנים מקבילים בערך ל-60 עד 80 מילים.

    כדי לקבל תשובות קצרות יותר, מציינים ערך נמוך יותר, וכדי לקבל תשובות ארוכות יותר, מציינים ערך גבוה יותר.

  • ‫STREAM: ערך בוליאני שמציין אם התגובה מועברת בסטרימינג או לא. הערך true מאפשר להציג את התשובה באופן שוטף, והערך false מאפשר להציג את התשובה כשהיא מוכנה.

בדוגמה הזו נעשה שימוש בשדות הבאים של שימוש בכלי: פרטים על כל שדה זמינים בקטע שדות של שימוש קפדני בכלי.

  • ‫tools[].strict: ערך בוליאני. אם הערך הוא true, הכלי יבצע דגימה עם אילוצים של דקדוק. מודל מובטח להפעיל את הכלי עם ארגומנטים שתואמים ל-input_schema.
  • ‫tools[].input_schema: סכימת JSON שמגדירה את הארגומנטים שהמודל יכול להעביר לכלי. אם strict הוא true, הסכימה צריכה להיות תואמת לאותו קבוצת משנה נתמכת של סכימת JSON כמו סכימת output_config עבור פלט JSON.

ה-method של ה-HTTP וכתובת ה-URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict

גוף בקשת JSON: 

{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_TOKENS,
  "stream": STREAM,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, for example San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"],
        "additionalProperties": false
      }
    }
  ]
}

כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

curl

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict"

PowerShell

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו: בלוק התוכן tool_use מכיל שדה input שהמפתחות וסוגי הערכים שלו תואמים בוודאות ל-input_schema של הכלי.

שדות של שימוש קפדני בכלים

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

  • ‫tools[].strict: ערך בוליאני. אם הערך הוא true, הכלי יבצע דגימה עם אילוצים של דקדוק. כשהערך של strict הוא true, קלט הכלי של המודל מוגבל כך שיתאים לסכימה ב-input_schema. ערך ברירת המחדל הוא false.

  • ‫tools[].input_schema: סכימת JSON שמגדירה את הארגומנטים שהמודל יכול להעביר לכלי. אם strict הוא true, הסכימה צריכה להיות תואמת לאותו קבוצת משנה של סכימת JSON שמשמשת בפלט JSON. באופן ספציפי, אתם צריכים:

    • מגדירים את additionalProperties ל-false בכל אובייקט בסכימה.
    • מפרטים כל מאפיין במערך required.

    הרשימה המלאה של התכונות הנתמכות והלא נתמכות מופיעה במסמכי התיעוד של Anthropic בנושא מגבלות של סכימת JSON.