JSON modunu kullanmayı öğrenin

JSON modu, sohbet tamamlama işleminin bir parçası olarak geçerli bir JSON nesnesi döndürmek için modelin yanıt biçimini ayarlamanıza olanak tanır. Daha önce geçerli JSON oluşturmak mümkün olsa da, geçersiz JSON nesnelerinin oluşturulmasına neden olabilecek yanıt tutarlılığı sorunları olabilir.

JSON modu geçerli JSON çıkışını garanti eder, ancak çıkışın belirli bir şemayla eşleştiğinden emin değildir. Şema garantilerine ihtiyacınız varsa Yapılandırılmış Çıkışlar'ı kullanın.

Not

JSON modu hala destekleniyor olsa da, mümkün olduğunda yapılandırılmış çıkışları kullanmanızı öneririz. JSON modu yapılandırılmış çıkışlarının geçerli JSON oluşturması gibi, ancak eklenen avantajla modeli belirli bir JSON şemasını kullanacak şekilde kısıtlayabilirsiniz.

Not

Şu anda yapılandırılmış çıkışlar kendi verilerinizi getirme senaryosunda desteklenmemektedir.

JSON modu desteği

JSON modu şu anda yalnızca aşağıdaki modellerle desteklenmektedir:

API desteği

JSON modu desteği ilk olarak API sürümü 2023-12-01-preview eklendi

Örnek

Örnekleri çalıştırmadan önce:

• YOUR-RESOURCE-NAME değerini Azure OpenAI kaynak adınızla değiştirin.
• YOUR-MODEL_DEPLOYMENT_NAME öğesini model dağıtımınızın adıyla değiştirin.

Aşağıdaki örneklerde Python ve .NET SDK'larını kullanan JSON modu ve doğrudan REST etkileşimi için PowerShell gösterilmektedir.

Python

import os
from openai import OpenAI

client = OpenAI(
  base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
  api_key=os.getenv("AZURE_OPENAI_API_KEY")
)

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)

Çıkış

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

C#

Projenize aşağıdaki paketleri ekleyin:

dotnet add package OpenAI
dotnet add package Azure.Identity

using Azure.Identity;
using OpenAI;
using OpenAI.Chat;
using System.ClientModel;
using System.Text.Json;

ChatClient client = new(
    model: "YOUR-MODEL_DEPLOYMENT_NAME",
    credential: new ApiKeyCredential(
        Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")),
    options: new OpenAIClientOptions()
    {
        Endpoint = new Uri(
            "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/")
    }
);

ChatCompletionOptions options = new()
{
    ResponseFormat = ChatResponseFormat.CreateJsonObjectFormat()
};

ChatCompletion completion = client.CompleteChat(
    [
        new SystemChatMessage(
            "You are a helpful assistant designed to output JSON."),
        new UserChatMessage("Who won the world series in 2020?")
    ],
    options);

Console.WriteLine(completion.Content[0].Text);

Çıkış

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

Powershell

Bu örnekte, kullanıcı belirli bir JSON şemasında geçmiş bilgilerini ister çünkü çıkışı daha fazla betik yazmak için kullanmayı planlamaktadır.

$openai = @{
   api_key     = $Env:AZURE_OPENAI_API_KEY
   api_base    = 'https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/'
   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)/chat/completions"

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

Çıkış

JSON çıkış özelliği, PowerShell'in yanıtı .NET nesnesine dönüştürmesini kolaylaştırır. Verileri sıralama gibi daha fazla betik adımını çalıştırmak için | kanaldan geçirin.

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 modunun başarıyla kullanılabilmesi için iki gereksinimin de karşılanması gerekir:

• İsteğinizde yanıt biçimini olarak json_object ayarlayın. Python'da response_format={ "type": "json_object" } geçin; .NET'te ChatResponseFormat.CreateJsonObjectFormat() kullanın; PowerShell'de response_format = @{type = 'json_object'} ayarlayın.
• İleti konuşmasında bir yere "JSON" sözcüğünü ekleyin (genellikle sistem iletisi).

İleti konuşmasının bir parçası olarak JSON üretmesi gereken modele yönelik yönergeler de gereklidir. Bu yönergeyi sistem iletisinin bir parçası olarak eklemenizi öneririz. OpenAI'ye göre, bu talimatın eklenmemesi, modelin "sonsuz boşluk karakterleri dizisi oluşturmasına neden olabilir ve istek, belirteç sınırına ulaşana kadar kesintisiz olarak çalışmaya devam edebilir."

"İletilere 'JSON' eklenmemesi şu hatayı döndürür:"

Çıkış

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

Dikkat edilmesi gereken diğer noktalar

Yanıtı ayrıştırmadan önce finish_reason'da length değerini denetlemelisiniz. Model kısmi JSON oluşturabilir. Bu, modelden gelen çıktının isteğe dahil edilen max_tokens limitinden daha büyük olduğu ya da konuşmanın kendisinin belirteç sınırını aştığı anlamına gelir.

JSON modu geçerli olan JSON üretir ve hatasız ayrıştırılır. Ancak, talep edilse bile çıkışın belirli bir şemayla eşleşmesi kesin değildir.

Sorun giderme

• Eğer finish_reasonlength ise, max_tokens'yi artırın (veya istemin uzunluğunu azaltın) ve yeniden deneyin. JSON verisini kısmen ayrıştırmayın.
• Şema garantilerine ihtiyacınız varsa Yapılandırılmış Çıkışlar'a geçin.