Saiba como usar o modo JSON

O modo JSON permite que você defina o formato de resposta do modelo para retornar um objeto JSON válido como parte de uma conclusão de chat. Embora a geração de JSON válida fosse possível anteriormente, poderia haver problemas com a consistência de resposta que levariam à 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 corresponda a um esquema específico. Caso precise de garantias de integridade de esquema, use Saídas Estruturadas.

Nota

Embora ainda haja suporte para o modo JSON, quando possível, recomendamos o uso de saídas estruturadas. Assim como as saídas estruturadas do modo JSON, geram JSON válido, mas com o benefício adicionado, você pode restringir o modelo para usar um esquema JSON específico.

Nota

Atualmente, saídas estruturadas não são suportadas no cenário de traga seus próprios dados.

Suporte ao modo JSON

Atualmente, o modo JSON só tem suporte com os seguintes modelos:

Suporte à API

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

Exemplo

Antes de executar os exemplos:

  • Substitua YOUR-RESOURCE-NAME pelo nome do recurso Azure OpenAI.
  • Substitua YOUR-MODEL_DEPLOYMENT_NAME pelo nome da implementação do modelo.

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

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)

Saída

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

Dois requisitos devem ser atendidos para usar o modo JSON com êxito:

  • Defina o formato de resposta como json_object em sua solicitação. Em Python, passe response_format={ "type": "json_object" }; em .NET, use ChatResponseFormat.CreateJsonObjectFormat(); no PowerShell, defina response_format = @{type = 'json_object'}.
  • Inclua a palavra "JSON" em algum lugar na conversa de mensagens (normalmente a mensagem do sistema).

A inclusão de diretrizes para o modelo de que ele deve produzir JSON como parte da conversa de mensagens é necessária. Recomendamos adicionar esta instrução como parte da mensagem do sistema. De acordo com o OpenAI, a falha ao adicionar essa instrução pode fazer com que o modelo "gere um fluxo sem fim de espaço em branco e a solicitação pode ser executada continuamente até atingir o limite do token".

A falha na inclusão de "JSON" nas mensagens resulta em:

Saída

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

Você deve verificar finish_reason em busca do valor length antes de interpretar a resposta. O modelo pode gerar JSON parcial. Isso significa que a saída do modelo era maior do que os max_tokens disponíveis que foram definidos como parte da solicitação, ou a conversa em si excedeu o limite de tokens.

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

Solucionando problemas

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