פלט מובנה למודלים פתוחים

פלט מובנה מאפשר למודל ליצור פלט שתמיד תואם לסכימה ספציפית. לדוגמה, אפשר לספק למודל סכימת תשובה כדי לוודא שהתשובה תהיה JSON תקין. כל המודלים הפתוחים שזמינים בפלטפורמת הסוכנים של Gemini Enterprise בתור Model as a Service‏ (MaaS) תומכים בפלטפוטים מובנים.

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

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

בתרחיש השימוש הבא מוגדרת סכימת תגובה שמבטיחה שהפלט של המודל יהיה אובייקט JSON עם המאפיינים הבאים: name,‏ date ו-participants. קוד ה-Python משתמש ב-OpenAI SDK ובאובייקטים של Pydantic כדי ליצור סכימת JSON.

from pydantic import BaseModel
from openai import OpenAI

client = OpenAI()

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

completion = client.beta.chat.completions.parse(
    model="MODEL_NAME",
    messages=[
        {"role": "system", "content": "Extract the event information."},
        {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
    ],
    response_format=CalendarEvent,
)

print(completion.choices[0].message.parsed)

הערה: התגובה כוללת אובייקט CalendarEvent, שמאוכלס בשדות המוגדרים. הפלט של המודל הוא JSON, שערכת ה-SDK מנתחת לאובייקט Pydantic.

פלט המודל יהיה בהתאם לסכימת ה-JSON הבאה:

{ "name": STRING, "date": STRING, "participants": [STRING] }

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

{
  "name": "science fair",
  "date": "Friday",
  "participants": [
    "Alice",
    "Bob"
  ]
}

דוגמה מפורטת

הקוד הבא הוא דוגמה לסכימה רקורסיבית. הכיתה UI מכילה רשימה של children, שיכולים להיות גם מהכיתה UI.

from pydantic import BaseModel
from openai import OpenAI
from enum import Enum
from typing import List

client = OpenAI()

class UIType(str, Enum):
  div = "div"
  button = "button"
  header = "header"
  section = "section"
  field = "field"
  form = "form"

class Attribute(BaseModel):
  name: str
  value: str

class UI(BaseModel):
  type: UIType
  label: str
  children: List["UI"]
  attributes: List[Attribute]

UI.model_rebuild() # This is required to enable recursive types

class Response(BaseModel):
  ui: UI

completion = client.beta.chat.completions.parse(
  model="MODEL_NAME",
  messages=[
    {"role": "system", "content": "You are a UI generator AI. Convert the user input into a UI."},
    {"role": "user", "content": "Make a User Profile Form"}
  ],
  response_format=Response,
)

print(completion.choices[0].message.parsed)

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

Form
  Input
    Name
    Email
    Age

התגובה יכולה להיראות כך:

ui = UI(
    type=UIType.div,
    label='Form',
    children=[
        UI(
            type=UIType.div,
            label='Input',
            children=[],
            attributes=[
                Attribute(name='label', value='Name')
            ]
        ),
        UI(
            type=UIType.div,
            label='Input',
            children=[],
            attributes=[
                Attribute(name='label', value='Email')
            ]
        ),
        UI(
            type=UIType.div,
            label='Input',
            children=[],
            attributes=[
                Attribute(name='label', value='Age')
            ]
        )
    ],
    attributes=[
        Attribute(name='name', value='John Doe'),
        Attribute(name='email', value='[e-mail]'),
        Attribute(name='age', value='30')
    ]
)

קבלת תגובות של אובייקט JSON

כדי להגביל את המודל כך שיפיק רק אובייקטים של JSON שתקפים מבחינת התחביר, צריך להגדיר את השדה response_format לערך { "type": "json_object" }. האפשרות הזו נקראת לעיתים קרובות מצב JSON. מצב JSON שימושי כשיוצרים JSON לשימוש בקריאה לפונקציות או במשימות אחרות בהמשך התהליך שדורשות קלט JSON.

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

בדוגמאות הבאות מוסבר איך להפעיל את מצב JSON ולהנחות את המודל להחזיר אובייקט JSON עם מבנה ספציפי:

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי Pythonההוראות להגדרה במאמר מדריך למתחילים של Agent Platform באמצעות ספריות לקוח.

כדי לבצע אימות ב-Agent Platform, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לסביבת פיתוח מקומית.

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

from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
  model="MODEL",
  response_format={ "type": "json_object" },
  messages=[
    {"role": "user", "content": "List 5 rivers in South America. Your response must be a JSON object with a single key \"rivers\", which has a list of strings as its value."},
  ]
)
print(response.choices[0].message.content)

מחליפים את MODEL בשם המודל שרוצים להשתמש בו, לדוגמה meta/llama3-405b-instruct-maas.

פלט לדוגמה

{
  "rivers": [
    "Amazon River",
    "Paraná River",
    "Orinoco River",
    "São Francisco River",
    "Magdalena River"
  ]
}

REST

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

• PROJECT_ID: מזהה הפרויקט ב-Google Cloud.
• ‫LOCATION: אזור שתומך במודלים פתוחים.
• ‫MODEL: שם המודל שרוצים להשתמש בו, לדוגמה meta/llama3-405b-instruct-maas.

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

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions

גוף בקשת JSON:

{
  "model": "MODEL",
  "response_format": {
    "type": "json_object"
  },
  "messages": [
    {
      "role": "user",
      "content": "List 5 rivers in South America. Your response must be a JSON object with a single key \"rivers\", which has a list of strings as its value."
    }
  ]
}

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

curl

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם 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/endpoints/openapi/chat/completions"

PowerShell

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם 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/endpoints/openapi/chat/completions" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:

תשובה

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "{\n  \"rivers\": [\n    \"Amazon River\",\n    \"Paraná River\",\n    \"Orinoco River\",\n    \"São Francisco River\",\n    \"Magdalena River\"\n  ]\n}",
        "role": "assistant"
      }
    }
  ],
  "created": 1721860000,
  "id": "123456789",
  "model": "meta/llama3-405b-instruct-maas",
  "object": "chat.completion",
  "system_fingerprint": "12345",
  "usage": {
    "completion_tokens": 54,
    "prompt_tokens": 46,
    "total_tokens": 100
  }
}

המאמרים הבאים

• מידע על הפעלת פונקציות
• מידע נוסף על Thinking
• מידע על חיזויים רבים בבת אחת