Pelajari cara menggunakan mode JSON

Mode JSON memungkinkan Anda mengatur format respons model untuk mengembalikan objek JSON yang valid sebagai bagian dari penyelesaian obrolan. Meskipun menghasilkan JSON yang valid dimungkinkan sebelumnya, mungkin ada masalah dengan konsistensi respons yang akan menyebabkan objek JSON yang tidak valid dibuat.

Nota

Meskipun mode JSON masih didukung, jika memungkinkan, sebaiknya gunakan output terstruktur. Seperti output terstruktur mode JSON menghasilkan JSON yang valid, tetapi dengan manfaat tambahan yang dapat Anda batasi model untuk menggunakan skema JSON tertentu.

Nota

Output terstruktur saat ini tidak didukung pada skenario bawa data sendiri.

Dukungan mode JSON

Mode JSON saat ini hanya didukung dengan model berikut:

Model yang didukung

• gpt-35-turbo (1106)
• gpt-35-turbo (0125)
• gpt-4 (1106-Pratinjau)
• gpt-4 (Pratinjau 0125)
• gpt-4o
• gpt-4o-mini

Dukungan API

Dukungan untuk mode JSON pertama kali ditambahkan dalam versi API 2023-12-01-preview

Contoh

Python

import os
from openai import AzureOpenAI

client = AzureOpenAI(
  azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT"), 
  api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
  api_version="2025-03-01-preview"
)

response = client.chat.completions.create(
  model="YOUR-MODEL_DEPLOYMENT_NAME", # Model = should match the deployment name you chose for your model deployment
  response_format={ "type": "json_object" },
  messages=[
    {"role": "system", "content": "You are a helpful assistant designed to output JSON."},
    {"role": "user", "content": "Who won the world series in 2020?"}
  ]
)
print(response.choices[0].message.content)

Keluaran

{
  "winner": "Los Angeles Dodgers",
  "event": "World Series",
  "year": 2020
}

PowerShell

Dalam contoh ini, pengguna meminta informasi historis dalam skema JSON tertentu karena mereka berencana menggunakan output untuk pembuatan skrip lebih lanjut.

$openai = @{
   api_key     = $Env:AZURE_OPENAI_API_KEY
   api_base    = $Env:AZURE_OPENAI_ENDPOINT # like the following https://YOUR_RESOURCE_NAME.openai.azure.com/
   api_version = '2024-03-01-preview' # may change in the future
   name        = 'YOUR-DEPLOYMENT-NAME-HERE' # name you chose for your deployment
}

$headers = @{
  'api-key' = $openai.api_key
}

$messages  = @()
$messages += @{
  role     = 'system'
  content  = 'You are a helpful assistant designed to output JSON.'
}
$messages += @{
  role     = 'user'
  content  = 'Who threw the final pitch during the world series each year from 1979 to 1989?'
}
$messages += @{
  role     = 'user'
  content  = 'Respond using schema. response:{year, team, player, player_height}.'
}

$body      = @{
  response_format = @{type = 'json_object'}
  messages = $messages
} | ConvertTo-Json

$url = "$($openai.api_base)/openai/deployments/$($openai.name)/chat/completions?api-version=$($openai.api_version)"

$response = Invoke-RestMethod -Uri $url -Headers $headers -Body $body -Method Post -ContentType 'application/json'
$response.choices[0].message.content

Keluaran

Kemampuan output JSON memudahkan PowerShell untuk mengonversi respons menjadi objek .NET. Teruskan data melalui | pipa untuk menjalankan langkah pembuatan skrip tambahan seperti pengurutan.

if ($response.choices[0].finish_reason -eq 'stop') {
  $response.choices[0].message.content | ConvertFrom-Json | ForEach-Object response | Sort player_height -Descending
} else { write-warning 'the JSON response was incomplete'}

year team                  player           player_height
---- ----                  ------           -------------
1979 Pittsburgh Pirates    Kent Tekulve     6' 4"
1984 Detroit Tigers        Willie Hernandez 6' 3"
1988 Los Angeles Dodgers   Orel Hershiser   6' 3"
1982 St. Louis Cardinals   Bruce Sutter     6' 2"
1985 Kansas City Royals    Dan Quisenberry  6' 2"
1986 New York Mets         Jesse Orosco     6' 2"
1989 Oakland Athletics     Dennis Eckersley 6' 2"
1981 Los Angeles Dodgers   Steve Howe       6' 1"
1980 Philadelphia Phillies Tug McGraw       6' 0"
1987 Minnesota Twins       Jeff Reardon     6' 0"
1983 Baltimore Orioles     Tippy Martinez   5' 10"

Ada dua faktor utama yang perlu ada agar berhasil menggunakan mode JSON:

• response_format={ "type": "json_object" }
• Kami memberi tahu model untuk mengeluarkan JSON sebagai bagian dari pesan sistem.

Termasuk panduan bahwa model harus menghasilkan JSON sebagai bagian dari percakapan pesan adalah diperlukan. Sebaiknya tambahkan instruksi sebagai bagian dari pesan sistem. Menurut Kegagalan OpenAI untuk menambahkan instruksi ini dapat menyebabkan model "menghasilkan aliran spasi kosong yang tidak berujung dan permintaan dapat berjalan terus sampai mencapai batas token."

Kegagalan untuk menyertakan "JSON" dalam pesan mengembalikan:

Keluaran

BadRequestError: Error code: 400 - {'error': {'message': "'messages' must contain the word 'json' in some form, to use 'response_format' of type 'json_object'.", 'type': 'invalid_request_error', 'param': 'messages', 'code': None}}

Pertimbangan lain

Anda harus memeriksa finish_reason untuk nilai length sebelum mengurai respons. Model mungkin menghasilkan JSON parsial. Ini berarti bahwa output dari model lebih besar dari max_tokens yang tersedia yang ditetapkan sebagai bagian dari permintaan, atau percakapan itu sendiri melebihi batas token.

Mode JSON menghasilkan JSON yang valid dan diurai tanpa kesalahan. Namun, tidak ada jaminan output untuk mencocokkan skema tertentu, bahkan jika diminta dalam perintah.