Source: https://docs.aivax.net/pt-br/docs/inference/structured-responses.html # Respostas Estruturadas AIVAX pode produzir JSON estruturado por dois caminhos: - `response_schema`: AIVAX valida a saída final do modelo contra um JSON Schema e tenta novamente com feedback de validação quando a saída é inválida. Este é o caminho de Reparação JSON. - `response_format`: AIVAX envia um formato de resposta nativo compatível com OpenAI ao provedor, ou aplica reparação quando `healing_options` está presente ou a Reparação JSON automática está habilitada na conta. Use respostas estruturadas quando outro sistema consumirá a saída e texto livre seria frágil. ## Como funciona a Reparação JSON Quando `response_schema` está presente, AIVAX adiciona instruções de esquema à requisição do modelo. Após o modelo gerar uma resposta, AIVAX tenta extrair JSON de: - O texto completo gerado. - Variantes reparadas comuns, como chaves de abertura ou fechamento ausentes. - Blocos de código JSON encontrados no texto gerado. Se o JSON extraído não validar contra o esquema, AIVAX adiciona uma mensagem de feedback com os erros de validação e pede ao modelo que gere o JSON novamente. Isso continua até que um valor JSON válido seja gerado ou o limite de tentativas configurado seja alcançado. A Reparação JSON melhora a confiabilidade, mas não é uma garantia absoluta. Se o modelo falhar repetidamente o esquema, a requisição pode falhar após o limite de tentativas. ## Escolhendo um modo Use `response_schema` quando AIVAX deve ser responsável pela validação e reparação. Este é o modo mais seguro para modelos que não suportam saída estruturada nativamente, para respostas que utilizam ferramentas antes de gerar JSON e para sistemas que não podem tolerar JSON malformado. Use `response_format` com `type: "json_schema"` quando o modelo do provedor deve lidar com a saída estruturada nativamente. AIVAX ainda usará o esquema internamente, e a reparação será aplicada quando `response_format.json_schema.healing_options` for fornecido ou a conta tiver a Reparação JSON automática habilitada. Use `json_only: true` quando o corpo da resposta HTTP deve conter apenas o JSON final. Isso remove o envelope normal de conclusão de chat, escolhas, uso e metadados de geração do corpo da resposta. ## Exemplo básico Referência: [API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Inference%20(chat%20completions))
POST /v1/chat/completions
```json { "model": "@google/gemini-2.5-flash", "prompt": "Search for recent news about electric vehicles.", "stream": true, "builtin_tools": { "tools": [ "WebSearch" ], "options": { "web_search_mode": "full" } }, "response_schema": { "type": "object", "properties": { "news": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "News title" }, "summary": { "type": "string", "description": "News summary" } }, "required": ["title", "summary"] } } }, "required": ["news"] } } ``` `builtin_tools` é opcional. Se você habilitar ferramentas, o modelo selecionado deve suportar chamadas de ferramenta ou o gateway deve fornecer um manipulador de ferramenta. ## Saída estruturada nativa Use `response_format` quando quiser usar o suporte nativo a JSON Schema do provedor: ```json { "model": "@openai/gpt-4o", "messages": [ { "role": "user", "content": "List 3 European capitals." } ], "response_format": { "type": "json_schema", "json_schema": { "schema": { "type": "object", "properties": { "capitals": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" } }, "required": ["city", "country"] } } }, "required": ["capitals"] } } } } ``` Se o modelo integrado selecionado tem suporte estrito a JSON, AIVAX pode encaminhar o esquema usando o formato de resposta JSON Schema do provedor. ## Habilitando reparação em `response_format` Você pode habilitar explicitamente a Reparação JSON dentro de `response_format.json_schema`: ```json { "model": "@openai/gpt-4o", "messages": [ { "role": "user", "content": "Return a short status object." } ], "response_format": { "type": "json_schema", "json_schema": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } }, "required": ["status", "message"] }, "healing_options": { "max_attempts": 5 } } } } ``` `max_attempts` deve estar entre 1 e 10. Cada nova tentativa é outra geração do modelo e pode aumentar custo e latência. Se a reparação frequentemente atinge o limite de tentativas, ajuste a instrução e o esquema antes de aumentar o limite. Causas comuns são esquemas excessivamente rígidos, campos `required` ausentes, prompts vagos, resultados de ferramentas ruidosos ou um modelo pequeno demais para a tarefa. ## Modo `json_only` Defina `json_only: true` quando o cliente deve receber apenas o JSON gerado: ```json { "model": "@openai/gpt-4o", "messages": [ { "role": "user", "content": "List 3 European capitals." } ], "response_schema": { "type": "object", "properties": { "capitals": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" } }, "required": ["city", "country"] } } }, "required": ["capitals"] }, "json_only": true } ``` Com `stream: false`, o corpo da resposta HTTP é o JSON final com `Content-Type: application/json`. Com `stream: true`, AIVAX envia o JSON completo como um único evento de dados SSE e depois envia `[DONE]`. ## Recursos de esquema suportados AIVAX valida o JSON gerado com JSON Schema. Os recursos suportados documentados são: - `string`: `minLength`, `maxLength`, `pattern`, `format` e `enum`. - `number` e `integer`: `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum` e `multipleOf`. - `array`: `items`, `uniqueItems`, `minItems` e `maxItems`. - `object`: `properties` e `required`. - `boolean` e `bool`. - `null`. - Tipos múltiplos, por exemplo `"type": ["string", "number"]`. Use `required` para campos que sua aplicação deve receber. Use `items` explícitos para arrays. Use `enum`, `format` e restrições de comprimento ou padrão quando os valores aceitos são conhecidos. ## Padrões práticos Para extração, indique ao modelo quais campos devem ser inferidos, quais campos devem ser `null` quando ausentes e quais campos não devem ser inventados. Para classificação, use `enum` para o r final e adicione um campo curto `reason` quando humanos precisarem auditar a decisão. Para JSON suportado por ferramentas, permita que o modelo use ferramentas antes de gerar o JSON e inclua campos de origem quando a aplicação precisar de procedência. Para gravações em banco de dados ou chamadas de API externas, valide o JSON novamente em sua aplicação. AIVAX valida a estrutura do JSON, mas sua aplicação continua responsável por regras de negócio como permissões, IDs válidos, intervalos de datas e restrições específicas da conta.