學習如何使用 JSON 模式

JSON 模式可讓您設定模型回應格式，在聊天完成時傳回有效的 JSON 物件。 雖然先前可產生有效的 JSON，但回應一致性可能有問題，導致產生的 JSON 對象無效。

注意

雖然仍支援 JSON 模式，但可能的話，建議您使用結構化輸出。 如同 JSON 模式，結構化輸出會產生有效的 JSON，但具有可限制模型使用特定 JSON 結構描述的額外優點。

注意

目前自備資料案例不支援結構化輸出。

JSON 模式支援

JSON 模式目前只獲得下列模型支援：

支援的模型

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

API 支援

API 版本 2023-12-01-preview 首次新增對 JSON 模式的支援

範例

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)

輸出

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

PowerShell

在此範例中，使用者要求特定 JSON 結構描述中的歷程記錄資訊，因為他們計劃使用輸出進一步處理指令碼。

$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

輸出

JSON 輸出功能可讓 PowerShell 將回應輕鬆轉換成 .NET 物件。 透過 | 管道傳遞資料，以執行更多指令碼處理步驟，例如排序。

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"

兩個關鍵因素必須存在，才能成功使用 JSON 模式：

• response_format={ "type": "json_object" }
• 我們告訴模型將 JSON 當成系統訊息的一部分輸出。

包含需要模型應該在訊息交談中產生 JSON 的指導。 建議將指令新增為系統訊息的一部分。 根據 OpenAI，無法新增此指令可能導致模型「產生未傳送的空格資料流，而且要求可能會持續執行，直到達到權杖限制為止」。

無法在訊息包含「JSON」會傳回：

輸出

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}}

其他考量

剖析回應之前，您應該先檢查 finish_reason 是否有值 length。 模型可能產生部分 JSON。 這表示模型的輸出大於設定為要求一部分的可用max_tokens，或交談本身超過權杖限制。

JSON 模式會產生有效且剖析無誤的 JSON。 不過，即使在提示中要求，仍無法保證輸出與特定結構描述相符。