Meer informatie over het gebruik van de JSON-modus

Met de JSON-modus kunt u de antwoordindeling van modellen instellen om een geldig JSON-object te retourneren als onderdeel van een chatvoltooiing. Hoewel het eerder mogelijk was om geldige JSON te genereren, kunnen er problemen zijn met responsconsistentie die zouden leiden tot het genereren van ongeldige JSON-objecten.

Notitie

Hoewel de JSON-modus nog steeds wordt ondersteund, raden we u aan gestructureerde uitvoer te gebruiken. Net zoals gestructureerde uitvoer in JSON-modus genereert het geldige JSON, met als extra voordeel dat u het model kunt dwingen een specifiek JSON-schema te gebruiken.

Notitie

Gestructureerde uitvoer wordt momenteel niet ondersteund in de bring-your-own-data-situatie.

Ondersteuning voor JSON-modus

De JSON-modus wordt momenteel alleen ondersteund met de volgende modellen:

Ondersteunde modellen

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

API-ondersteuning

Ondersteuning voor de JSON-modus is voor het eerst toegevoegd in API-versie 2023-12-01-preview

Voorbeeld

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)

Uitvoer

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

Powershell

In dit voorbeeld vraagt de gebruiker om historische informatie in een specifiek JSON-schema, omdat ze de uitvoer willen gebruiken voor verdere scripting.

$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

Uitvoer

Met de JSON-uitvoerfunctie kan PowerShell het antwoord eenvoudig converteren naar een .NET-object. Geef de gegevens door via een | pijp om meer scriptstappen uit te voeren, zoals sorteren.

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"

Er zijn twee belangrijke factoren die aanwezig moeten zijn om de JSON-modus te kunnen gebruiken:

• response_format={ "type": "json_object" }
• We hebben het model verteld JSON uit te voeren als onderdeel van het systeembericht.

Het opnemen van richtlijnen voor het model dat het JSON moet produceren als onderdeel van het berichtengesprek is vereist. U wordt aangeraden instructies toe te voegen als onderdeel van het systeembericht. Volgens de OpenAI-fout om deze instructie toe te voegen, kan het model ertoe leiden dat 'een niet-gecodeerde stroom van witruimte genereert en de aanvraag voortdurend kan worden uitgevoerd totdat de tokenlimiet is bereikt'.

Als u 'JSON' niet opneemt in de berichten, wordt het volgende geretourneerd:

Uitvoer

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

Andere overwegingen

finish_reason Controleer de waarde length voordat u het antwoord parseert. Het model kan gedeeltelijke JSON genereren. Dit betekent dat de uitvoer van het model groter is dan de beschikbare max_tokens die zijn ingesteld als onderdeel van de aanvraag, of dat het gesprek zelf de tokenlimiet heeft overschreden.

De JSON-modus produceert JSON die geldig is en zonder fouten parseert. Er is echter geen garantie dat de uitvoer overeenkomt met een specifiek schema, zelfs als dit wordt aangevraagd in de prompt.