Saída estruturada garantida: como o Outlines elimina as alucinações de formato dos LLMs

Saída estruturada garantida: como o Outlines elimina as alucinações de formato dos LLMs

Quem já tentou fazer um LLM gerar um JSON perfeitamente formatado sabe a frustração: você passa 20 minutos refinando o prompt, pede “por favor” e “obrigado”, e ainda assim o modelo insiste em colocar uma vírgula a mais, esquecer uma chave, ou incluir um comentário onde não deveria.

O Outlines resolve esse problema de raiz. Em vez de tentar consertar a saída depois que ela já foi gerada — a abordagem tradicional de “prompt engineering + regex na gambiarra” — essa biblioteca open-source atua no nível da inferência, bloqueando tokens sintaticamente ilegais durante a geração. O resultado é deterministicamente correto: o modelo simplesmente não consegue produzir uma saída que viole as regras do formato desejado.

Desenvolvido pela comunidade open-source e compatível com qualquer modelo do Hugging Face (via transformers), o Outlines constrói uma máquina de estados finita internamente que restringe as opções do modelo a cada passo da geração. Isso significa que, para formatos como JSON, expressões regulares ou até tipos Python nativos, a saída sempre será válida.

Como funciona na prática

Classificação com escolha forçada

O caso mais simples é quando você quer que o modelo escolha exatamente uma opção de uma lista fechada — como classificar o sentimento de um ticket de suporte:

import outlines
from transformers import AutoTokenizer, AutoModelForCausalLM
from typing import Literal

model = outlines.from_transformers(
    AutoModelForCausalLM.from_pretrained("microsoft/Phi-3-mini-4k-instruct"),
    AutoTokenizer.from_pretrained("microsoft/Phi-3-mini-4k-instruct")
)

sentimento = model(
    "Classifique o sentimento: 'Estou esperando meu pedido há duas semanas e ainda não chegou.'",
    Literal["Positivo", "Negativo", "Neutro"]
)
print(sentimento)  # Garantido: "Negativo"

O modelo não pode gerar “Negativo.” (com ponto), “negativo” (minúsculo) ou qualquer outra variante. A máquina de estados força exatamente uma das três strings.

Objetos JSON com Pydantic

Para saídas mais complexas, o Outlines se integra com modelos Pydantic. Defina a estrutura uma vez e o modelo preenche os campos obrigatoriamente:

from pydantic import BaseModel

class Personagem(BaseModel):
    nome: str
    descricao: str
    idade: int

resultado = model(
    "Gere um personagem fictício chamado 'Anya' em JSON.",
    Personagem,
    max_new_tokens=200
)
# Saída: Personagem(nome='Anya', descricao='Uma guerreira...', idade=28)

O objeto retornado é uma instância Pydantic válida — você pode acessar resultado.nome diretamente, serializar para JSON com .model_dump(), e integrar com qualquer pipeline de dados downstream. Sem parsing frágil. Sem try/except. Sem surpresas.

Por que isso importa agora

A demanda por LLMs em pipelines de produção disparou em 2026, e o principal gargalo não é mais a qualidade do texto — é a confiabilidade da saída estruturada. Empresas que usam LLMs para extrair dados de documentos, classificar tickets, ou gerar respostas de API precisam de garantias, não de probabilidades.

Enquanto soluções como function calling da OpenAI e constrained decoding do vLLM atacam o mesmo problema, o Outlines se destaca por ser agnóstico de modelo: funcione com qualquer modelo do Hugging Face, incluindo opções menores como Phi-3 que rodam localmente. Isso é especialmente relevante para o mercado brasileiro, onde o custo de API em dólar é um fator limitante e a capacidade de rodar modelos on-premise é uma vantagem competitiva.

Instalação: pip install outlines[transformers]. Compatível com Python 3.10+ e qualquer modelo suportado pelo ecossistema transformers.