Output terstruktur untuk model terbuka

Output terstruktur memungkinkan model menghasilkan output yang selalu sesuai dengan skema tertentu. Misalnya, model dapat diberi skema respons untuk memastikan bahwa respons menghasilkan JSON yang valid. Semua model terbuka yang tersedia di Vertex AI Model as a Service (MaaS) mendukung output terstruktur.

Untuk mengetahui informasi konseptual selengkapnya tentang kemampuan output terstruktur, lihat Pengantar output terstruktur.

Menggunakan output terstruktur

Kasus penggunaan berikut menetapkan skema respons yang memastikan bahwa output model adalah objek JSON dengan properti berikut: name, date, dan participants. Kode Python menggunakan OpenAI SDK dan objek Pydantic untuk membuat skema 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)

Output model akan mematuhi skema JSON berikut:

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

Jika diberi perintah, "Alice dan Bob akan pergi ke pameran sains pada hari Jumat", model dapat menghasilkan respons berikut:

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

Contoh mendetail

Kode berikut adalah contoh skema rekursif. Class UI berisi daftar children, yang juga dapat berupa class 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)

Output model akan mematuhi skema objek Pydantic yang ditentukan dalam cuplikan sebelumnya. Dalam contoh ini, model dapat menghasilkan formulir UI berikut:

Form
  Input
    Name
    Email
    Age

Responsnya dapat terlihat seperti berikut:

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='john.doe@example.com'),
        Attribute(name='age', value='30')
    ]
)

Mendapatkan respons objek JSON

Anda dapat membatasi model untuk hanya menghasilkan objek JSON yang valid secara sintaksis dengan menetapkan kolom response_format ke { "type": "json_object" }. Hal ini sering disebut mode JSON. Mode JSON berguna saat membuat JSON untuk digunakan dengan panggilan fungsi atau tugas hilir lainnya yang memerlukan input JSON.

Jika mode JSON diaktifkan, model hanya akan menghasilkan string yang diuraikan menjadi objek JSON yang valid. Meskipun mode ini memastikan output adalah JSON yang benar secara sintaksis, mode ini tidak menerapkan skema tertentu. Untuk memastikan model menghasilkan JSON yang mengikuti skema tertentu, Anda harus menyertakan petunjuk dalam perintah, seperti yang ditunjukkan dalam contoh berikut.

Contoh berikut menunjukkan cara mengaktifkan mode JSON dan menginstruksikan model untuk menampilkan objek JSON dengan struktur tertentu:

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Python Vertex AI.

Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

Sebelum menjalankan contoh ini, pastikan untuk menetapkan variabel lingkungan OPENAI_BASE_URL. Untuk mengetahui informasi selengkapnya, lihat Autentikasi dan kredensial.

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)

Ganti MODEL dengan nama model yang ingin Anda gunakan, misalnya meta/llama3-405b-instruct-maas.

REST

Setelah Anda menyiapkan lingkungan, Anda dapat menggunakan REST untuk menguji perintah teks. Contoh berikut mengirim permintaan ke endpoint model penayang.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: ID project Google Cloud Anda.
  • LOCATION: Region yang mendukung model terbuka.
  • MODEL: Nama model yang ingin Anda gunakan, misalnya meta/llama3-405b-instruct-maas.

Metode HTTP dan URL: 

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

Isi JSON permintaan: 

{
  "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."
    }
  ]
}

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

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

Simpan isi permintaan dalam file bernama request.json, dan jalankan perintah berikut: 

$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

Anda akan melihat respons JSON yang mirip seperti berikut:

Langkah berikutnya