Aprenda a usar o modo JSON

O modo JSON permite-lhe definir o formato de resposta do modelo para devolver um objeto JSON válido como parte de uma conclusão de chat. Embora anteriormente fosse possível gerar JSON válido, podiam surgir problemas de consistência de resposta que levassem à geração de objetos JSON inválidos.

O modo JSON garante uma saída JSON válida, mas não garante que a saída corresponde a um esquema específico. Se precisar de garantias de esquema, use Saídas Estruturadas.

Nota

Embora o modo JSON ainda seja suportado, sempre que possível recomendamos o uso de saídas estruturadas. Tal como o modo JSON, as saídas estruturadas geram JSON válido, mas com o benefício adicional de poderes restringir o modelo a usar um esquema JSON específico.

Nota

Atualmente, os resultados estruturados não são suportados no cenário de "traga seus próprios dados".

Suporte ao modo JSON

O modo JSON é atualmente suportado apenas com os seguintes modelos:

Suporte para API

O suporte ao modo JSON foi adicionado pela primeira vez na versão da API 2023-12-01-preview

Exemplo

Antes de apresentares os exemplos:

  • Substitua YOUR-RESOURCE-NAME pelo nome do seu recurso Azure OpenAI.
  • Substitui YOUR-MODEL_DEPLOYMENT_NAME pelo nome do teu modelo de implementação.

Os exemplos abaixo mostram o modo JSON usando os SDKs Python e .NET, e PowerShell para interação direta com REST.

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)

Produção

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

Dois requisitos devem ser cumpridos para usar o modo JSON com sucesso:

  • Defina o formato da resposta para json_object no seu pedido. No Python, passe response_format={ "type": "json_object" }; no .NET, use ChatResponseFormat.CreateJsonObjectFormat(); no PowerShell, defina response_format = @{type = 'json_object'}.
  • Inclua a palavra "JSON" em algum lugar da conversa de mensagens (normalmente a mensagem do sistema).

É necessário incluir orientações ao modelo de que deve produzir JSON como parte da conversa das mensagens. Recomendamos adicionar esta instrução como parte da mensagem do sistema. Segundo a OpenAI, a falha em adicionar esta instrução pode fazer com que o modelo "gere um fluxo interminável de espaços em branco e o pedido pode ser executado continuamente até atingir o limite dos tokens."

A falha em incluir "JSON" nas mensagens devolve:

Produção

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

Outras considerações

Deves verificar finish_reason o valor length antes de analisar a resposta. O modelo pode gerar JSON parcial. Isto significa que a saída do modelo era maior do que as max_tokens disponíveis que foram definidas como parte do pedido, ou que a própria conversa excedeu o limite do token.

O modo JSON produz JSON válido e analisa sem erro. No entanto, não há garantia de que a saída corresponda a um esquema específico, mesmo que seja solicitada no prompt.

Resolução de problemas

  • Se finish_reason é length, aumente max_tokens (ou reduza o comprimento do prompt) e tente novamente. Não analise JSON parcial.
  • Se precisar de garantias de esquema, mude para Saídas Estruturadas.