Guia prático de Constraint Decoding: nunca mais implore por JSON válido

Guia prático de Constraint Decoding: nunca mais implore por JSON válido

Quem trabalha com LLMs sabe a frustração: você pede um JSON, o modelo responde com markdown, comentários no meio do objeto, ou — pior — inventa campos que não existem no schema. Constraint decoding (também conhecido como structured generation ou guided decoding) resolve isso de forma definitiva: torna matematicamente impossível o modelo gerar algo fora das regras.

O tutorial de Iván Palomares Carrascosa no KDnuggets explica o mecanismo de forma clara e prática, usando a biblioteca outlines — considerada o padrão ouro atual para geração estruturada em Python.

Como funciona

Diferente da abordagem tradicional de “torcer para o modelo acertar”, o constraint decoding atua diretamente no processo de seleção de tokens:

1. Compilação: antes da inferência começar, uma máquina de estados finita (FSM) é construída a partir do schema alvo — por exemplo, um modelo Pydantic
2. Máscara: a cada passo da geração, a FSM avalia o estado atual e fornece uma lista de tokens permitidos
3. Filtro: os logits dos tokens fora da lista são setados para -infinito, forçando o modelo a escolher apenas entre os tokens válidos
4. Amostragem: o modelo aplica softmax e sampling normalmente sobre os tokens sobreviventes

O resultado é uma garantia de 100% de sintaxe correta — sem regex de limpeza, sem try/except, sem retry.

Exemplo prático com outlines

from pydantic import BaseModel
import outlines
from transformers import AutoTokenizer, AutoModelForCausalLM

class UserProfile(BaseModel):
    name: str
    age: int
    is_active: bool

model_name = "TinyLlama/TinyLlama-1.1B-Chat-v1.0"
llm = AutoModelForCausalLM.from_pretrained(model_name)
tokenizer = AutoTokenizer.from_pretrained(model_name)

model = outlines.from_transformers(llm, tokenizer)
result = model(
    "Extract the user: John is a 34 year old pilot.",
    UserProfile
)
# Output: {"name": "John", "age": 34, "is_active": true}

O que impressiona é que mesmo um modelo de 1 bilhão de parâmetros (TinyLlama) — que normalmente seria incapaz de gerar JSON confiável — produz saída perfeitamente estruturada quando guiado pelo constraint decoding.

Vantagens e limitações

✅ Prós:

• Garantia de 100% de sintaxe correta — elimina a necessidade de parsing defensivo
• Economia drástica de tokens no prompt (não precisa de exemplos few-shot mostrando o formato)
• Democratiza modelos pequenos — um modelo de 1B parâmetros gera JSON tão confiável quanto um de 70B
• Integração simples com Pydantic, JSON Schema e regex

⚠️ Contras:

• Se o schema força um inteiro, mas o modelo não sabe a resposta, ele inventa um número — a honestidade do modelo é sacrificada em favor da estrutura
• A primeira execução com um schema novo tem latência maior (a FSM precisa ser compilada — execuções subsequentes são rápidas)
• Nem todos os modelos e frameworks têm suporte maduro ainda

Quando usar

Constraint decoding é essencial em cenários onde a saída estruturada é crítica: extração de entidades, geração de código, APIs que esperam JSON estrito, sistemas multi-agente onde um agente passa dados para outro, e pipelines de dados que não toleram falhas de parsing.

Se você ainda está usando prompts como “responda APENAS com JSON válido, sem markdown, sem comentários”, está na hora de migrar para constraint decoding.