DSPy: Programação Declarativa de LLMs, Signatures e Compilação com MIPROv2

O DSPy substitui a manipulação manual de prompts por programação declarativa modular com assinaturas tipadas e compilação algorítmica. Ele trata modelos de linguagem como camadas computacionais parametrizadas em grafos direcionados.

Com isso, pipelines ganham estabilidade estrutural e portabilidade real. O compilador otimiza instruções e demonstrações automaticamente para cada modelo alvo.

Essa mudança de paradigma resolve a fragilidade dos templates concatenados em produção. Em vez de adivinhar frases mágicas, o engenheiro define contratos de tipos e métricas quantitativas.

O que é o DSPy e por que o prompt engineering artesanal falha em produção?

O DSPy é um framework declarativo que substitui strings de prompts por módulos tipados, signatures estruturadas e otimizadores automáticos. Ele resolve a fragilidade de templates manuais, que quebram silenciosamente com variações de dados ou atualizações de modelos.

A engenharia de prompts tradicional baseia-se em tentativa e erro. Engenheiros passam semanas ajustando frases em linguagem natural e blocos XML para orientar o modelo.

Esse formato gera um acoplamento severo entre a instrução textual e a distribuição de probabilidades daquele modelo específico. Ao migrar de versão, o comportamento do sistema desmorona.

Pequenas alterações nas entradas do usuário produzem desvios de formato imprevisíveis. Além disso, prompts longos e cheios de regras redundantes inflam custos de tokens e aumentam a latência de inferência.

O DSPy resolve esse dilema introduzindo uma analogia com o ecossistema PyTorch. Ele divide a arquitetura em quatro pilares fundamentais:

• Módulos (dspy.Module): Representam as camadas computacionais reutilizáveis do programa, gerenciando o fluxo de dados entre transformações intermediárias.
• Signatures: Definem formalmente as entradas e saídas esperadas, isolando o que o sistema deve fazer de como o prompt é formatado.
• Funções Métricas: Substituem o julgamento subjetivo por funções matemáticas e computáveis que avaliam o desempenho das saídas sobre dados reais.
• Compiladores (Teleprompters): Ajustam automaticamente as instruções e os exemplos de cada módulo com base nas métricas definidas.

A pesquisa seminal de Stanford foi publicada por Omar Khattab no artigo canônico do DSPy no arXiv. O trabalho formaliza a transição de textos empíricos para programas declarativos. O framework é mantido em código aberto no repositório oficial do Stanford NLP.

Como funcionam Signatures tipadas e Módulos computacionais no DSPy?

Signatures estabelecem contratos estritos de entrada e saída para cada módulo do sistema, utilizando tipagem estática e validação em tempo de execução. Módulos como dspy.Predict, dspy.ChainOfThought e dspy.ReAct executam essas assinaturas dentro de grafos computacionais.

Em vez de escrever um prompt de sistema extenso, o desenvolvedor declara os dados necessários. O DSPy pode compor signatures inline ou através de classes baseadas no Pydantic.

As docstrings das classes atuam como especificação semântica primária da tarefa. Os descritores de campo fornecem contexto para que os compiladores gerem instruções refinadas durante o treino.

import dspy
from typing import List

class AnaliseRiscoContrato(dspy.Signature):
    """Analisa clausulas contratuais e quantifica passivos juridicos."""

    clausula: str = dspy.InputField(desc="Texto integral da clausula.")
    jurisdicao: str = dspy.InputField(desc="Jurisdicao legal aplicavel.")

    passivos: List[str] = dspy.OutputField(desc="Riscos juridicos encontrados.")
    nivel_risco: str = dspy.OutputField(desc="Classificacao: BAIXO, MEDIO ou CRITICO.")
    score_exposicao: float = dspy.OutputField(desc="Exposicao de 0.0 a 1.0.")

Para processar essas assinaturas, o DSPy oferece módulos nativos com comportamentos distintos:

1. dspy.Predict: Execução direta e atômica da assinatura com decodificação estruturada de saída.
2. dspy.ChainOfThought: Injeta automaticamente uma variável latente de raciocínio antes da resposta final, dispensando pedidos manuais de pensamento passo a passo.
3. dspy.ProgramOfThought: Transfere tarefas lógicas e matemáticas para código executado em sandbox determinístico.
4. dspy.ReAct: Orquestra laços iterativos de raciocínio, chamadas a ferramentas externas e observações empíricas.

Módulos individuais podem ser compostos hierarquicamente dentro de uma classe dspy.Module. Isso viabiliza pipelines de busca em múltiplos saltos (Multi-Hop RAG) com total rastreabilidade.

class MultiHopRAG(dspy.Module):
    def __init__(self, retriever, hops: int = 2):
        super().__init__()
        self.retriever = retriever
        self.hops = hops
        self.query_gen = dspy.ChainOfThought("context, question -> next_query")
        self.synthesizer = dspy.ChainOfThought("context, question -> answer")

    def forward(self, question: str):
        context = []
        query = question
        for _ in range(self.hops):
            docs = self.retriever(query)
            context.extend(docs)
            step = self.query_gen(context="\n".join(context), question=question)
            query = step.next_query
        return self.synthesizer(context="\n".join(context), question=question)

A camada de comunicação com modelos desacopla os módulos das APIs de inferência por meio de adaptadores configuráveis na documentação do DSPy. É possível alternar entre modelos locais via vLLM e provedores comerciais sem alterar uma única linha de lógica do pipeline.

O que é o MIPROv2 e como funciona a compilação algorítmica de prompts?

O MIPROv2 é o compilador de ponta do DSPy que otimiza simultaneamente instruções em linguagem natural e demonstrações few-shot através de Otimização Bayesiana com Optuna. Ele analisa código, dados e erros para sintetizar a melhor combinação global de prompts.

Enquanto abordagens artesanais dependem da intuição de quem escreve, a compilação trata prompts como hiperparâmetros discretos. O MIPROv2 foi documentado por Kristjan Arumae e colaboradores no paper de otimização de multi-estágios no arXiv.

O processo opera em três estágios coordenados:

• Proposta de Instruções: Um modelo proponente de alta capacidade avalia o código do programa, os dados de treino e traces de falha para propor dezenas de instruções candidatas para cada módulo.
• Bootstrap de Demonstrações: O compilador executa o pipeline sobre o conjunto de treino, coletando traces intermediários que atingiram pontuação máxima na métrica.
• Busca Bayesiana com TPE: Utilizando o estimador Tree-structured Parzen Estimator via Optuna, o algoritmo navega pelo espaço combinatorial e descobre a configuração mais eficaz.

O MIPROv2 disponibiliza três modos de execução: light para testes rápidos, medium para sistemas em produção e heavy para casos de missão crítica. Essa flexibilidade permite equilibrar investimento de computação e ganho de acurácia.

Como implementar métricas rigorosas, Asserts e Suggestions em tempo de execução?

Métricas computáveis definem a função de perda que orienta a convergência dos compiladores, avaliando saídas contra critérios determinísticos ou semânticos. Primitivas como dspy.Assert e dspy.Suggest monitoram a execução em tempo real, corrigindo desvios dinamicamente.

Sem uma métrica confiável, a compilação perde seu objetivo matemático. No DSPy, uma métrica recebe o exemplo de referência, a previsão gerada e um trace opcional de execução.

Funções determinísticas validam schemas JSON, integridade de dados e casamento de identificadores sem consumir tokens adicionais. Para critérios abertos, um modelo juiz calibrado afere fidelidade factual e ausência de alucinações.

def metrica_extracao(gold, pred, trace=None):
    if not hasattr(pred, "passivos") or not isinstance(pred.passivos, list):
        return 0.0
    gold_set = set(gold.passivos_esperados)
    pred_set = set(pred.passivos)
    intersecao = len(gold_set.intersection(pred_set))
    uniao = len(gold_set.union(pred_set))
    return intersecao / max(uniao, 1)

Para garantir confiabilidade na inferência de produção, o DSPy disponibiliza verificações ativas dentro do próprio método forward:

• dspy.Assert: Interrompe a execução quando uma condição inegociável é violada, instruindo o modelo a refazer a resposta com base no erro apontado.
• dspy.Suggest: Registra desvios de formato ou boas práticas sem travar a execução, orientando ajustes graduais.

Quando um assert falha, o runtime do DSPy intercepta a exceção e gera uma nova chamada corretiva contendo a mensagem de falha. Traces com erros são automaticamente excluídos do treino, assegurando que o compilador aprenda apenas com dados válidos.

Qual é o impacto financeiro (FinOps) e de latência ao compilar modelos menores?

A compilação de programas permite que modelos abertos de menor porte atinjam índices de acurácia comparáveis ou superiores a modelos gigantes proprietários em tarefas estruturadas. Isso reduz os custos operacionais de inferência entre 80% e 92%, com retorno financeiro imediato.

A crença convencional dita que modelos de fronteira fechados são mandatórios para tarefas complexas. Entretanto, a deficiência de modelos compactos decorre com frequência de comandos ambíguos ou formatações inconsistentes.

Ao compilar o Llama 3.3 8B com MIPROv2, as instruções são calibradas exatamente para seus padrões de ativação. Os exemplos injetados eliminam incertezas sintáticas.

Em testes empíricos de extração e raciocínio multi-hop, o Llama 3.3 8B com MIPROv2 saltou de 54.2% para 82.4% de acurácia. Ele superou o GPT-4o bruto sem compilação, que obteve 78.6% na mesma base de avaliação.

A fórmula de retorno financeiro comprova a viabilidade da abordagem para qualquer escala de uso:

Payback = Custo_Compilacao ÷ (Custo_Modelo_Bruto - Custo_Modelo_Compilado)

O processo de compilação em modo medium consome cerca de $1.58 em tokens com modelo proponente. Esse valor se paga inteiramente nas primeiras 250 requisições processadas.

Servir o modelo localmente através do vLLM potencializa os ganhos com a tecnologia PagedAttention. Prefixos de instruções compiladas permanecem em cache de memória, reduzindo a latência de primeiro token em até 40%.

Comparativo estrutural: DSPy vs. LangChain, LlamaIndex e Frameworks de Agentes

O DSPy estrutura a computação como um grafo declarativo de parâmetros otimizáveis, enquanto outros ecossistemas dependem de templates de strings e chamadas manuais. Essa diferença garante que pipelines DSPy mantenham estabilidade ao trocar de modelo.

Frameworks como LangChain e LlamaIndex oferecem amplos catálogos de integrações e conectores de dados. No entanto, eles deixam a escrita de prompts a cargo do desenvolvedor.

Quando o modelo subjacente é atualizado, o desenvolvedor precisa reescrever e testar todos os templates manualmente. No DSPy, basta executar novamente o compilador sobre o novo modelo.

A curva de aprendizado do DSPy exige uma mentalidade de engenharia de software similar à de redes neurais. O retorno dessa disciplina é um sistema previsível, passível de testes automatizados e integrado a esteiras de CI/CD.

Quais são as limitações atuais e fronteiras abertas do DSPy?

O DSPy apresenta limitações práticas em grafos excessivamente ramificados e em tarefas puramente subjetivas que carecem de métricas determinísticas. O framework é otimizado para fluxos acíclicos estruturados, demandando adaptações para loops abertos de agentes.

Em arquiteturas que ultrapassam oito módulos interdependentes, a dimensionalidade do espaço de busca Bayesiano cresce expressivamente. Isso pode exigir centenas de trials no MIPROv2 para evitar convergência em mínimos locais.

Tarefas criativas sem gabarito objetivo, como redação publicitária ou tradução poética, exigem juízes baseados em LLM. Nesses cenários, ruídos na avaliação podem levar a otimizações espúrias.

Além disso, instruções compiladas para uma família de modelos não são diretamente transferíveis para outra com arquitetura divergente. A substituição do modelo exige uma nova rodada de compilação para atingir o ponto de operação ideal.

Perguntas Frequentes sobre DSPy e Compilação de LLMs

O DSPy substitui o fine-tuning de pesos na GPU?

O DSPy não altera pesos sinápticos de redes neurais, atuando como um compilador de instruções e demonstrações no espaço discreto de linguagem natural. Ele frequentemente atinge ou supera o ganho de acurácia de fine-tuning tradicional com uma fração mínima do custo e tempo de treinamento.

Quantos exemplos de treino são necessários para compilar com MIPROv2?

O compilador MIPROv2 opera com alta eficiência utilizando pequenos conjuntos de dados, demandando tipicamente entre 20 e 100 exemplos rotulados de entrada e saída. O algoritmo utiliza esses exemplos para validar traces e guiar a exploração Bayesiana.

É possível utilizar o DSPy com modelos locais via vLLM ou Ollama?

Sim, o DSPy integra-se nativamente com qualquer endpoint compatível com a API da OpenAI, incluindo servidores locais vLLM, SGLang, Ollama e LiteLLM. Essa configuração garante soberania de dados corporativos e elimina custos de chamadas a provedores comerciais externos.

O que acontece se o modelo de linguagem for alterado após a compilação?

Um programa compilado para um modelo específico retém instruções ajustadas para aquela distribuição de probabilidade. Ao substituir o modelo subjacente, o recomendável é reexecutar o compilador para sintetizar os parâmetros ideais para a nova arquitetura.

Qual é a diferença prática entre dspy.Assert e dspy.Suggest?

O comando dspy.Assert impõe uma restrição obrigatória cuja falha aciona imediatamente uma chamada corretiva com backtracking semântico. Já o dspy.Suggest emite avisos de não conformidade sem interromper o fluxo principal de execução do programa.

Quanto tempo dura uma rodada de compilação com MIPROv2 em modo medium?

Uma sessão de compilação em modo medium dura tipicamente entre 5 e 15 minutos, variando com a latência da API ou do hardware local de inferência. A rotina executa cerca de 40 tentativas de avaliação sobre o conjunto de validação.