Cura de JSON

A Cura de JSON (JSON Healing) é o recurso do AIVAX que faz qualquer modelo retornar um JSON compatível com um esquema, incluindo modelos sem suporte nativo a saída estruturada. Utilize-o quando a aplicação precisar analisar um valor JSON previsível em vez de texto livre.

Ative-o de uma das seguintes formas:

• Envie response_schema.
• Envie healing_options dentro de response_format.
• Ative a Cura de JSON automática nas configurações da conta.

Use response_format quando desejar o suporte nativo ao JSON Schema do provedor. Adicione healing_options dentro de response_format.json_schema quando essa solicitação também deve usar a Cura de JSON.

Como funciona a Cura de JSON #

Quando response_schema está presente, o AIVAX segue este loop.

1. O AIVAX adiciona instruções de esquema à solicitação do modelo.
2. Após o modelo gerar uma resposta, o AIVAX tenta extrair o JSON de:
   • Todo o texto gerado.
   • Variantes comuns reparadas, como chaves de abertura ou fechamento ausentes.
   • Blocos de código JSON encontrados no texto gerado.
3. Se o JSON extraído não for válido conforme o esquema, o AIVAX adiciona uma mensagem de feedback com os erros de validação e solicita que o modelo gere o JSON novamente.
4. Isso continua até que um valor JSON válido seja gerado ou o limite de tentativas configurado seja atingido.

A Cura de JSON melhora a confiabilidade, mas não é uma garantia absoluta. Se o modelo falhar repetidamente na validação do esquema, a solicitação pode falhar após o limite de tentativas; consulte Quando a cura falha.

Exemplo básico #

Use response_schema quando quiser ativar a Cura de JSON em uma conclusão de chat, inclusive após a execução de ferramentas. A solicitação abaixo permite que o modelo pesquise na web e retorne os resultados como JSON validado contra response_schema.

Referência:

{
    "model": "@google/gemini-3.8-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 chamada de ferramentas ou o gateway deve fornecer um manipulador de ferramentas.

Saída estruturada nativa #

Use response_format quando desejar o suporte nativo ao JSON Schema do provedor. Se o modelo integrado selecionado tiver suporte estrito para JSON, o AIVAX pode encaminhar o esquema usando o formato de resposta JSON Schema do provedor.

{
    "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"]
            }
        }
    }
}

Habilitando a cura em response_format #

Use healing_options quando a solicitação já usa response_format e você também deseja a Cura de JSON. Coloque as opções dentro de response_format.json_schema:

{
    "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 o custo e a latência.

Quando a cura falha #

A cura falha quando todas as tentativas produzem JSON inválido. A solicitação então falha com a mensagem Failed to generate a valid JSON response. Please, try again later.

O que o cliente recebe:

• Sem streaming, a resposta é HTTP 503 com o código de erro service_unavailable e o cabeçalho Retry-After: 5.
• Com streaming, o stream termina com um chunk cujo finish_reason é error e cujo objeto error carrega o código e a mensagem, seguido por [DONE]. Consulte Streaming.

Se a cura frequentemente atingir o limite de tentativas, ajuste a instrução e o esquema antes de aumentar o limite. Causas comuns:

• Esquemas excessivamente rígidos.
• Campos obrigatórios (required) ausentes.
• Prompts vagos.
• Resultados de ferramentas ruidosos.
• Um modelo muito pequeno para a tarefa.

Recursos de esquema suportados #

O AIVAX valida o JSON gerado com JSON Schema. Use estes recursos quando precisar restringir um valor. Os recursos documentados suportados 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.
• Múltiplos tipos, por exemplo "type": ["string", "number"].

Aplique restrições desta forma:

• 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 forem conhecidos.

Padrões práticos #

Use estes padrões ao projetar o esquema, não apenas ao ativar a cura.

Extração #

Informe ao modelo quais campos devem ser inferidos, quais campos devem ser null quando ausentes e quais campos não devem ser inventados.

Classificação #

Use enum para o rótulo final. Adicione um campo reason curto quando humanos precisarem auditar a decisão.

JSON baseado em ferramentas #

Permita que o modelo use ferramentas antes de produzir o JSON. Inclua campos de origem quando a aplicação precisar de proveniência.

Gravações em outros sistemas #

Para gravações em banco de dados ou chamadas de API externas, valide o JSON novamente em sua aplicação. O AIVAX valida a estrutura do JSON, mas sua aplicação permanece responsável pelas regras de negócio, como permissões, IDs válidos, intervalos de datas e restrições específicas da conta.