DSPy para Engenheiros de Backend: Signatures, Otimizadores e GEPA vs MIPROv2
Se você já manteve um serviço Spring Boot de vida longa, conhece a diferença entre configuração e
código. Ninguém edita valores do application.yml à mão nos servidores de produção, nem define o
tamanho do pool de conexões no chute: você declara, mede e altera por meio de um processo revisado e
reproduzível.
Agora olhe para o desenvolvimento com LLM por essa mesma lente. A maioria dos times “faz IA” do jeito que fazíamos ops em 2009: alguém edita uma string de prompt à mão em um PR, confere cinco saídas em um notebook, faz o deploy, e seis semanas depois uma atualização de modelo quebra tudo em silêncio.
O DSPy (dspy.ai), framework da Stanford NLP, diz: pare. Trate o prompt como um artefato compilado. Você escreve o código-fonte, uma declaração tipada da tarefa composta em Python comum, mais uma métrica que avalia as saídas. Um componente do framework chamado otimizador gera e ajusta os prompts de verdade, automaticamente, contra a sua métrica e com os seus dados.
Este artigo explica como isso funciona e depois se aprofunda na pergunta que você vai encarar assim que adotar o framework: qual otimizador usar. As duas estratégias principais hoje são o MIPROv2 (busca bayesiana sobre instruções e exemplos few-shot) e o GEPA (evolução reflexiva de prompts em uma fronteira de Pareto, ICLR 2026 Oral). Elas buscam de formas diferentes, custam de formas diferentes e exigem coisas diferentes da sua métrica.
Tudo se apoia em um pequeno exemplo executável que montei para este artigo: um programa de triagem de incidentes de produção em Spring Boot, que classifica linhas de log e stack traces em categorias de causa raiz. É o domínio em que este blog costuma atuar, e é pequeno o bastante para que uma execução completa de otimização saia barata.
Stack: Python 3.11+, DSPy 3.5, qualquer provedor de LLM.
TL;DR
- DSPy = prompts como artefatos de build. Você declara uma
Signature(entradas e saídas tipadas), compõeModules em Python, escreve uma métrica, e um otimizador compila tudo em instruções ajustadas + exemplos few-shot. Trocar de modelo vira recompilar, não reescrever prompts. - O ciclo central é o mesmo em qualquer caso: programa + ~30 exemplos rotulados + métrica →
optimizer.compile(program, trainset=...)→ um artefato salvo e comparável com diff. Nenhuma string de prompt no seu código-fonte. - MIPROv2 = propõe uma grade de candidatos (instruções × demos) e escolhe o vencedor com otimização bayesiana sobre avaliações em minibatches. Ótimo para uso geral; pede 200+ exemplos para execuções longas; a métrica é um float simples.
- GEPA = evolução reflexiva: um LLM forte reescreve as instruções com base em feedback textual sobre por que as previsões erraram, e uma fronteira de Pareto preserva os candidatos que vencem em qualquer caso individual. Superou o MIPROv2 em mais de 10 pontos em seis tarefas de benchmark, a custo comparável (ICLR 2026 Oral), e superou o fine-tuning por GRPO usando até 35x menos rollouts.
- Regra de decisão: a métrica consegue explicar os erros em palavras → GEPA. A métrica é um escalar caixa-preta, ou você precisa selecionar demos → MIPROv2. Nenhum dos dois mexe no código do seu programa.
O Que É o DSPy?
O DSPy é um framework Python open source da Stanford NLP. Nasceu da pesquisa Demonstrate-Search-Predict (dezembro de 2022), e a linha atual, a 3.x, é amplamente usada: vários milhões de downloads mensais no PyPI e cerca de 40 mil estrelas no GitHub no momento em que escrevo. O lema do próprio projeto resume a filosofia: programar, e não escrever prompts para, modelos de linguagem.
A premissa: prompt não é código-fonte. É um resultado, o produto compilado de três entradas que você pode manter como código-fonte:
- O que a tarefa é: uma interface tipada com entradas, saídas e restrições.
- Como as etapas se compõem: fluxo de controle em Python comum.
- O que significa “correto”: uma função de métrica sobre exemplos rotulados.
Escreva à mão os itens 1 a 3 e deixe um algoritmo produzir o prompt. Quando o modelo muda, você não reescreve o prompt: você recompila.
Se você já manteve em paralelo um prompt para GPT-4, outro para Claude e outro para um Llama local na mesma funcionalidade, já entende por que isso importa. É o mesmo instinto que nos levou da configuração de servidor editada à mão para a infraestrutura declarada.
Como o DSPy Funciona: Signatures, Módulos e Otimizadores
O DSPy tem exatamente três abstrações para aprender. O framework é isso.
flowchart LR
A["Signature<br/>(especificação tipada da tarefa)"] --> B["Módulo<br/>(Predict, ChainOfThought, ReAct...)"]
B --> C["Seu programa<br/>(composição em Python comum)"]
C --> D["Otimizador<br/>(MIPROv2 / GEPA / BootstrapFewShot)"]
E["Métrica + exemplos"] --> D
D --> F["Programa compilado<br/>(instruções + demos ajustadas)"]
F --> G["dspy.Evaluate<br/>(gate de regressão)"]
O Que É uma Signature do DSPy?
Uma signature é uma especificação declarativa do comportamento de entrada e saída de uma tarefa. Pense nela como a assinatura de um método, mas com semântica, e não só com tipos. Os nomes dos campos carregam significado; o DSPy os transforma em prompts por baixo dos panos.
class IncidentTriage(dspy.Signature):
"""Classify a Spring Boot production incident by its root cause and severity,
and propose a fix."""
incident_report: str = dspy.InputField(
desc="Log line, stack trace excerpt or error description"
)
root_cause: Literal[
"config-misconfiguration",
"dependency-conflict",
"connection-pool-exhaustion",
"serialization-error",
"memory-pressure",
"thread-starvation",
] = dspy.OutputField(desc="One of the fixed root-cause categories")
severity: Literal["P1", "P2", "P3"] = dspy.OutputField(
desc="P1 = service down / data risk, P2 = degraded, P3 = contained"
)
action: str = dspy.OutputField(desc="One-sentence remediation")
Veja o que uma signature oferece e uma string de prompt não: estrutura que o parser consegue impor.
root_cause é um tipo Literal, então o modelo não pode responder Probably database stuff; ele
precisa devolver um dos seis valores, ou o adapter do DSPy tenta de novo e acaba lançando uma exceção.
É o mesmo reflexo de mapear JSON para um DTO tipado em vez de parsear strings na mão.
O Que É um Módulo do DSPy?
Um módulo é uma estratégia de prompting reutilizável, generalizada para qualquer signature: a ideia
do nn.Module do PyTorch aplicada a prompts. Todos são construídos sobre o dspy.Predict. Os mais
conhecidos:
| Módulo | Estratégia que abstrai |
|---|---|
dspy.Predict(sig) |
Completion direta |
dspy.ChainOfThought(sig) |
Acrescenta uma etapa de raciocínio antes da resposta |
dspy.ReAct(sig, tools=[...]) |
Ciclo de raciocínio + uso de ferramentas, para agentes |
dspy.ProgramOfThought(sig) |
Gera e executa código para responder |
dspy.BestOfN(sig, N) |
Amostra N candidatos e fica com o de maior pontuação |
Seu programa é uma subclasse de dspy.Module cujo forward() compõe submódulos com Python comum:
condicionais, laços, suas próprias classes. Este é o modelo inteiro do nosso exemplo de triagem de
incidentes:
class IncidentTriageProgram(dspy.Module):
def __init__(self):
super().__init__()
self.triage = dspy.ChainOfThought(IncidentTriage)
def forward(self, incident_report: str) -> dspy.Prediction:
return self.triage(incident_report=incident_report)
Repare no que não está nesse arquivo: nenhum texto de prompt, nenhum exemplo few-shot, nenhum nome
de modelo, nenhuma temperatura. Tudo isso existe, mas como parâmetros, e é exatamente isso que os
torna otimizáveis. Chamar o programa devolve campos tipados (root_cause, severity, action) mais
um campo reasoning, que o ChainOfThought adiciona para a etapa de raciocínio.
O Que É um Otimizador do DSPy?
Um otimizador (antes chamado de teleprompter) é um algoritmo que ajusta os parâmetros do seu programa, isto é, as instruções e/ou as demos few-shot, para maximizar a sua métrica. Uma demo few-shot é um exemplo já resolvido de entrada→saída, injetado no prompt; uma instrução é a diretriz em nível de sistema que o DSPy gera para cada módulo.
optimizer.compile(program, trainset=...) é literalmente uma etapa de compilação: roda o seu programa
sobre os dados, mede, busca e devolve um programa compilado, cujos predictors agora carregam
instruções e demos ajustadas. Você o salva com program.save("optimized.json"), um artefato
revisável e comparável com diff, como faria com um script de migration.
A avaliação é uma única chamada:
evaluate = dspy.Evaluate(
devset=valset,
metric=triage_metric,
num_threads=4,
display_table=3,
)
result = evaluate(program)
A orientação de dimensionamento da documentação do DSPy: ~30 exemplos rotulados para ver valor, ~300 para qualidade de produção, divididos em ~20% treino / 80% validação, porque os otimizadores pontuam cada candidato contra a validação. É deliberadamente o oposto da prática de deep learning: você não está ajustando pesos, está buscando em um espaço muito menor, e o conjunto de validação é a bússola.
Vale ainda internalizar mais um ponto: a sua métrica é o contrato. Todo otimizador deste artigo
é tão inteligente quanto a função que avalia as saídas. Para classificação, uma métrica de
correspondência exata resolve. Para tarefas mais subjetivas, o DSPy traz o dspy.evaluate.SemanticF1,
ele próprio implementado como um pequeno programa DSPy, e você também pode escrever métricas que
devolvem crédito parcial.
Um Exemplo Funcional: Triagem de Incidentes em Spring Boot
Chega de teoria. O repositório complementar deste artigo implementa uma tarefa que todo engenheiro de backend conhece: a triagem de on-call. Dada uma linha de log ou um trecho de stack trace, classificar a causa raiz (seis categorias) e a severidade (P1/P2/P3) e produzir uma correção em uma frase.
O dataset tem 24 incidentes feitos à mão, deliberadamente realistas: timeouts do pool do Hikari, um
NoSuchMethodError após um upgrade do Jackson, um método @Transactional segurando uma conexão
durante uma chamada remota lenta, um pod morto por OOMKilled com o heap saudável mas o metaspace não…
14 para treino, 10 para validação. Pequeno de propósito: a documentação do DSPy diz que o valor começa
por volta de 30 exemplos, e assim cada execução sai barata.
A métrica tem duas variantes, e essa divisão é a chave para a pergunta GEPA vs MIPROv2 mais adiante:
def triage_metric(example, pred, trace=None) -> float:
"""Plain scalar metric — what MIPROv2 and dspy.Evaluate consume."""
root_ok = pred.root_cause == example.root_cause
sev_ok = pred.severity == example.severity
return (1.0 if root_ok else 0.0) + (0.25 if sev_ok else 0.0)
def triage_metric_with_feedback(example, pred, trace=None, pred_name=None, pred_trace=None):
"""GEPA metric: a score PLUS natural-language feedback about the miss."""
problems = []
if pred.root_cause == example.root_cause:
root_score = 1.0
else:
root_score = 0.0
problems.append(
f"Wrong root cause: you said '{pred.root_cause}', the correct label is "
f"'{example.root_cause}'."
)
# ... same for severity ...
return dspy.Prediction(score=root_score + sev_score,
feedback=" ".join(problems) or "Correct root cause and severity.")
Mesma tarefa, mesma avaliação: uma versão responde “quanto?” e a outra também responde “por que errou?”. Essa diferença é o que separa os dois otimizadores a seguir.
As Principais Estratégias de Otimização
O DSPy traz cerca de uma dúzia de otimizadores, em quatro famílias. Os dois entre os quais você vai de fato escolher são os dois últimos.
| Otimizador | O que ajusta | Estratégia de busca | Dados de que precisa |
|---|---|---|---|
BootstrapFewShot |
Só demos | Roda um teacher e mantém os traces que passam na métrica | ~10+ |
BootstrapFewShotWithRandomSearch |
Só demos | Bootstrapping + busca aleatória sobre variantes | 50+ |
COPRO |
Só instruções | Hill-climbing por coordinate ascent sobre reescritas | qualquer quantidade |
MIPROv2 |
Instruções + demos | Propõe uma grade de candidatos e aplica otimização bayesiana | 200+ para execuções longas |
GEPA |
Instruções (e código, via dspy.Flex) |
Evolução reflexiva em uma fronteira de Pareto | um punhado, se a métrica der feedback |
MIPROv2: Busca Bayesiana sobre Instruções e Demos
O MIPROv2 (Multiprompt Instruction PRoposal Optimizer v2) é o carro-chefe do DSPy, a resposta padrão de longa data para “só otimiza isso aí”. Ele roda em três estágios:
- Bootstrap de demos: cria
num_candidatesconjuntos de exemplos few-shot, alguns copiados dos rótulos e outros bootstrapped, rodando o seu próprio programa e mantendo os traces cujas saídas passam na métrica. - Proposta de instruções: um
prompt_modelescreve candidatas de instrução para cada módulo, com base em um resumo do dataset, no código-fonte do seu programa, nas demos geradas por bootstrap e em uma dica aleatória de criatividade. - Busca bayesiana: amostra combinações (instrução, demo), avalia cada uma em um minibatch de 35
exemplos, atualiza um modelo surrogate e reamostra onde ele prevê melhoria. A cada poucos passos há
uma avaliação completa na validação. Ao fim de
num_trials, vence o melhor programa.
optimizer = dspy.MIPROv2(
metric=triage_metric, # plain scalar is fine here
auto="light", # ~6 candidates; "medium"/"heavy" scale up
num_threads=4,
)
optimized = optimizer.compile(
program,
trainset=trainset,
valset=valset,
max_bootstrapped_demos=2,
max_labeled_demos=2,
)
optimized.save("optimized/miprov2_triage.json")
O modelo mental é uma grade fixa de candidatos explorada por um amostrador esperto. Isso tem uma consequência real: o MIPROv2 só consegue escolher entre as instruções candidatas que o seu proposer pensou em gerar de antemão. Se nenhuma delas codificar o insight de domínio de que a sua tarefa precisava (“case a assinatura do stack trace antes de julgar a severidade”), a busca bayesiana não tem como inventá-lo; só consegue escolher o ponto menos ruim da grade.
GEPA: Evolução Reflexiva de Prompts em uma Fronteira de Pareto
O GEPA (Genetic-Pareto), de Agrawal et al., 2025 e aceito como ICLR 2026 Oral, ataca essa limitação diretamente. É uma busca evolutiva em que o operador de mutação é um LLM que lê feedback:
flowchart TD
S["Início: programa não otimizado"] --> P["Fronteira de Pareto = candidatos que são<br/>os melhores em pelo menos um caso de validação"]
P --> M["Sorteia um candidato (probabilidade ∝ cobertura)<br/>+ minibatch do trainset"]
M --> R["Executa o programa, coleta traces<br/>+ feedback textual da métrica"]
R --> L["O LLM de reflexão propõe<br/>uma instrução reescrita"]
L --> E["Executa o novo candidato no minibatch"]
E -- "melhorou?" --> V["Avalia no valset completo<br/>e atualiza a fronteira"]
E -- "não" --> P2["Descarta e sorteia o próximo"]
V --> P
P2 --> M2["Repete até esgotar o orçamento de rollouts"]
M2 --> W["Devolve o melhor candidato agregado"]
Quatro ideias fazem isso funcionar:
- A métrica devolve feedback, não só um número. Por isso o nosso exemplo tem a
triage_metric_with_feedback, que devolvedspy.Prediction(score, feedback). A documentação do DSPy é direta: se você der ao GEPA um float puro, ele vira “uma versão bem mais fraca de si mesmo”. O texto de feedback vai literalmente para o prompt do LM de reflexão (“você dissethread-starvation, o rótulo correto émemory-pressure; OOMKilled no limite do container com baixo uso de heap significa que a restrição é o container”), de modo que cada mutação é informada, não aleatória. - Seleção de Pareto em vez de “o vencedor leva tudo”. O MIPROv2 mantém um único incumbent; candidatos medianos no geral, mas os melhores em uma fatia específica (digamos, erros de serialização), são eliminados mesmo assim. A fronteira do GEPA mantém vivos todos esses especialistas e amostra a partir deles. Candidatos especialistas do início sobrevivem para se recombinar depois, o mesmo motivo pelo qual algoritmos genéticos preservam populações diversas. O artigo faz a ablação disso: no Qwen3 8B, a amostragem de Pareto superou a escolha sempre do melhor candidato atual por cerca de 6 pontos de pontuação agregada.
- Merge ciente do sistema (
use_merge=True): quando duas linhagens aprenderam pontos fortes complementares, o GEPA tenta combinar os melhores módulos de cada uma, um operador de crossover, na linguagem dos algoritmos genéticos. - Orçamento em um único parâmetro: exatamente um entre
auto(light/medium/heavy),max_full_evalsoumax_metric_calls. Olightavalia cerca de seis prompts candidatos; o número real de chamadas à métrica cresce com o tamanho do valset e a quantidade de predictors, então teste antes em um valset pequeno.
optimizer = dspy.GEPA(
metric=triage_metric_with_feedback, # score + textual feedback
reflection_lm=reflection_model(), # a STRONG model, temperature 1.0
auto="light",
num_threads=4,
track_stats=True, # fills detailed_results
perfect_score=1.25, # this metric's max; the default is 1.0
)
optimized = optimizer.compile(program, trainset=trainset, valset=valset)
Duas observações operacionais. Primeiro, o LM de reflexão é onde vale gastar: ele é chamado só
algumas vezes por execução, então dê a ele um modelo mais forte que o da tarefa; a documentação do DSPy
recomenda um modelo maior ali quando se otimiza um modelo menor. Segundo, ative track_stats=True: o
resultado traz detailed_results com todos os candidatos, a linhagem de pais de cada um e as
pontuações de validação por exemplo, uma trilha de auditoria de como o prompt evoluiu, que você pode
exportar para JSON e revisar como um PR.
Uma pegadinha que enfrentei de verdade: o GEPA pula a reflexão em qualquer exemplo cuja pontuação
alcance perfect_score, que por padrão vale 1.0. A nossa métrica chega a no máximo 1.25 (1.0 pela
causa raiz mais 0.25 pela severidade), então, com o padrão, todo exemplo com a causa raiz certa contava
como perfeito e o GEPA nunca olhava para os erros de severidade. Ele explorou um ou dois candidatos e
devolveu o programa original. Se o máximo da sua métrica não é 1.0, defina perfect_score.
O que o GEPA muda é deliberadamente restrito: só o signature.instructions de cada predictor. A
composição dos seus módulos, o seu código e as suas demos ficam intocados. As instruções otimizadas
também se transferem muito bem entre modelos: o artigo relata que prompts evoluídos no Qwen3-8B
ganharam ~9% quando reaproveitados no GPT-4.1 Mini.
GEPA vs MIPROv2: Qual Otimizador Usar?
Mesmo framework, mesmo programa, mesma função de métrica, paradigmas de busca diferentes:
| Dimensão | MIPROv2 | GEPA |
|---|---|---|
| Paradigma | Otimização bayesiana sobre uma grade fixa de candidatos | Evolução reflexiva sobre um conjunto aberto de candidatos |
| O que ajusta | Instruções + demos few-shot, em conjunto | Só instruções (código também, via dspy.Flex) |
| Contrato da métrica | Escalar simples (float/bool) | dspy.Prediction(score, feedback), com feedback por predictor |
| Memória da busca | Um único incumbent, o melhor até o momento | Fronteira de Pareto com os vencedores por instância + merge |
| Parâmetros de orçamento | auto ou num_candidates + num_trials |
exatamente um: auto / max_full_evals / max_metric_calls |
| Prompts típicos | Mais longos (as demos few-shot os inflam) | Instruções até 9,2x mais curtas (medição do artigo) |
| Orientação sobre dados | Com 200+ exemplos, as execuções longas rendem mais | Um punhado funciona se o feedback for rico; mantenha o valset pequeno |
| Resultados de destaque | Padrão sólido; exemplo ReAct da documentação: 8% → ~42% (MIPROv2, medium) |
Mais de 10 pontos acima do MIPROv2 em 6 tarefas (segundo o abstract) |
Os números de custo do artigo são mais interessantes que os de acurácia. Nos experimentos com GPT-4.1 Mini, o gasto total com LM foi de US$ 86 para o GEPA contra US$ 76 para o MIPROv2, valores comparáveis, para cerca do dobro do ganho agregado (+12,2 pontos contra +5,6; GEPA+Merge: +13,3). Contra o fine-tuning por RL (GRPO), o GEPA igualou as melhores pontuações de validação com 243 a 1.179 rollouts contra 24.000, até 78x mais eficiente em amostras, e ficou em média 6 pontos (até 20) acima do GRPO. São os benchmarks e as configurações do próprio artigo, não a sua carga de trabalho, mas é a versão revisada por pares da afirmação de que “é mais barato que RL” que você vê nas redes sociais.
A regra de decisão que eu usaria, com base em como os dois são construídos:
- Escolha o GEPA quando a sua métrica consegue explicar os erros em palavras. Classificação com justificativas, extração validada contra schemas, agentes avaliados por traces passo a passo: onde quer que dê para expressar “por que isso está errado”. Esse feedback é o combustível; sem ele, você roda uma evolução com uma função de fitness cega.
- Escolha o MIPROv2 quando a sua métrica é uma caixa-preta, ou quando as demos importam mais que as instruções. Se o seu programa sofre de underfitting porque faltam exemplos em contexto (e não porque as instruções estão erradas), a busca conjunta de instruções e demos do MIPROv2 é a melhor alavanca. Ele também é o primeiro degrau mais suave: não exige configurar um segundo modelo, e métricas escalares são bem-vindas.
- Uma sondagem barata, em qualquer caso: o
BootstrapFewShotWithRandomSearchcom uma métrica escalar custa quase nada e costuma mostrar se a lacuna está nas demos (ele a fecha) ou nas instruções (ele não fecha, e aí é território de MIPROv2/GEPA).
E eles não são mutuamente exclusivos. O DSPy 3.x traz o BetterTogether, que encadeia a otimização
de prompts e a de pesos (por exemplo, GEPA e depois fine-tuning) no mesmo programa: a evolução de
prompts para achar a estratégia, e o RL para comprimi-la nos pesos quando você pode bancar os rollouts.
Rodando o Exemplo
Tudo o que vimos acima é código que você roda em cinco minutos. O repositório complementar:
git clone https://github.com/javaAndScriptDeveloper/dspy-article
cd dspy-article
uv sync # Python 3.11+, installs DSPy 3.5
# Offline sanity check — drives the whole pipeline against a DummyLM:
uv run python smoke_test.py # no API key needed
# Real runs:
export GEMINI_API_KEY=... # free key: aistudio.google.com/apikey
# or set DSPY_MODEL to any dspy.LM string
uv run python 01_baseline.py # score the unoptimized program
uv run python 02_optimize_miprov2.py # Bayesian search → optimized/miprov2_triage.json
uv run python 03_optimize_gepa.py # reflective evolution → optimized/gepa_triage.json
Padrões: modelo da tarefa gemini/gemini-3.5-flash-lite, modelo de reflexão do GEPA
gemini/gemini-3.5-flash (sobrescreva com DSPY_MODEL / DSPY_REFLECTION_MODEL; qualquer string de
dspy.LM funciona, inclusive openai/gpt-4o-mini). Uma chave do Google AI Studio é gratuita, mas as cotas
do plano gratuito são pequenas e o Google as altera, então confira os limites do seu projeto antes de
rodar o otimizador: ele faz centenas de chamadas, e o código tenta de novo em caso de 429 em vez de
falhar. O dataset tem 24 exemplos, então a execução é pequena. O que ela produziu quando eu a rodei está
na próxima seção.
O que vale fazer por conta própria: depois de cada execução, compare com diff o JSON salvo e o
programa-fonte. O 02_optimize_miprov2.py terá escrito instruções e injetado demos few-shot. O
03_optimize_gepa.py terá reescrito a instrução, e o optimized/gepa_results.json guarda a linhagem
evolutiva completa: cada candidato, seus pais e as pontuações por exemplo. Abra esse arquivo ao lado do
código-fonte do programa e a conclusão salta aos olhos: o prompt é saída, não código-fonte.
O Que Aconteceu Quando Eu Rodei
Rodei os três scripts em 17 de novembro de 2026 no plano gratuito do Google AI Studio:
gemini-3.5-flash-lite como modelo da tarefa, gemini-3.5-flash como modelo de reflexão do GEPA,
auto="light" nos dois otimizadores, num_threads=4. A métrica é a de 1.25 ponto vista acima; as
pontuações abaixo são médias por incidente nos 10 incidentes de validação.
| Execução | Pontuação (máx. 1.25) | Notas |
|---|---|---|
| Programa não otimizado, 3 execuções sem cache | 1.10 / 1.12 / 1.10 | 88–90% do máximo |
MIPROv2, light |
1.12 | dentro do ruído entre execuções acima |
GEPA, light, perfect_score padrão |
1.10 | 1–2 candidatos, nada a aprender (veja acima) |
GEPA, light, perfect_score=1.25 |
1.175 (94%) | 21 candidatos, 420 chamadas à métrica, ~18 min de relógio |
Leia isso com estas ressalvas, porque os números são pequenos e prefiro que você desconfie deles a citá-los:
- O baseline já estava perto do teto. O modelo acertou a causa raiz nos 10 incidentes de validação. Todo ponto perdido foi de severidade: ele classificou como P1 onde o rótulo diz P2 ou P3. Essa era toda a folga disponível, então o experimento inteiro gira em torno de 2 rótulos de severidade em 10.
- O GEPA escolhe o vencedor nos mesmos 10 exemplos em que reporto o resultado, então 1.175 é otimista. Não há conjunto de teste separado. É uma demo de integração, não um benchmark.
- O 1.12 do MIPROv2 não é uma vitória. O programa não otimizado oscilou entre 1.10 e 1.12 entre reexecuções.
- O DSPy faz cache das respostas do LM em disco por padrão. Minhas primeiras “três execuções
idênticas do baseline” foram três acertos de cache, não evidência de estabilidade. O repositório agora
aceita
DSPY_CACHE=0para desativá-lo quando você quiser variância real.
O resultado mais útil veio de abrir o optimized/gepa_triage.json, que é o passo de comparar o artefato
com diff recomendado acima. A instrução evoluída parece uma cola rotulada. Ela cita incidentes de
treino quase literalmente (HikariPool - Connection is not available, management.server.port in use,
placeholders ${...} não resolvidos) e associa cada um a uma severidade. Também lista uma causa raiz,
management-port-conflict, que não é uma das seis categorias permitidas, e a sua lista de causas raiz
já não menciona thread-starvation. O nosso tipo Literal rejeitaria o rótulo inventado, e a instrução
agora afasta o modelo de um rótulo real.
A pontuação melhorou e o artefato ficou pior de maneiras que a métrica não enxerga. É exatamente por isso
que o JSON salvo merece passar por code review, e por que um conjunto de teste separado e uma métrica que
verifique o conjunto de categorias importam mais do que o otimizador que você escolhe.
Não tirei um veredito GEPA vs MIPROv2 desta execução, e uma execução com 10 exemplos não consegue. O que ela sustenta é mais restrito: numa tarefa que o modelo já resolve na maior parte, confira o baseline antes de pagar por otimização, garanta que a faixa da sua métrica corresponda às premissas do otimizador e leia o prompt evoluído antes de confiar na pontuação dele.
Quando Não Usar o DSPy?
Seção de honestidade, porque todo discurso de venda de framework precisa de uma.
- Sem métrica, sem DSPy. Se você não consegue avaliar as saídas, nem que seja com ruído, o otimizador não tem nada para subir. Montar o conjunto de avaliação e a métrica é o trabalho de verdade; o DSPy só automatiza a busca contra elas. (Times que pulam essa etapa e ajustam prompts à mão fazem a mesma busca no feeling, com dados piores.)
- Um único prompt estável em um problema já resolvido? Não pague o custo de abstração. O DSPy compensa quando os programas têm várias etapas, os modelos mudam o tempo todo ou as falhas de qualidade estão custando dinheiro de verdade.
- Orçamento de RL ilimitado e pesos treináveis? O artigo do GEPA é explícito: a evolução de prompts vence quando os rollouts são caros, os dados são limitados ou os pesos estão congelados atrás de uma API. O fine-tuning no estilo GRPO ainda vence quando há rollouts em abundância. São ferramentas diferentes, com economias diferentes.
- O prompt é responsabilidade sua. O artefato compilado é ajustado à sua métrica: se você otimizar contra uma métrica substituta que não corresponde à produção, vai entregar um programa lindamente otimizado para o objetivo errado. Vale a regra de sempre: a sua suíte de avaliação é a sua especificação.
Todas as camadas de um backend já passaram por isso: a configuração virou código, o schema virou migrations, a infraestrutura virou declarativa. A string de prompt é o último artefato que as pessoas ainda editam à mão às 2 da manhã. A resposta do DSPy é a mesma que funcionou nas outras camadas: declare, meça, versione. Os otimizadores são a parte interessante, mas o que traz retorno é a disciplina: o prompt deixa de ser algo que alguém ajusta na madrugada e passa a ser algo que o CI regenera quando o modelo, os dados ou a métrica mudam.
Se quiser uma segunda passada, mais profunda, sobre os otimizadores, as fontes primárias são excelentes: o artigo do GEPA (ICLR 2026 Oral), o artigo do MIPROv2 e o guia oficial de otimização do DSPy, que inclui um passo a passo para escolher o otimizador.
O código deste artigo está disponível em
github.com/javaAndScriptDeveloper/dspy-article.
O pipeline inteiro é verificável offline (uv sync && uv run python smoke_test.py roda um ciclo
completo de otimização do GEPA sem chave de API), e as execuções reais usam um dataset pequeno, de 24
exemplos.
Perguntas frequentes
O que é o DSPy, em termos simples?
O DSPy é um framework Python open source da Stanford NLP que substitui prompts escritos à mão por declarações de tarefa tipadas e um compilador otimizador. Você descreve o que a tarefa recebe de entrada e produz de saída (uma signature), compõe as etapas em Python comum (módulos), escreve uma métrica, e um otimizador gera automaticamente os prompts e os exemplos few-shot que maximizam essa métrica. Ao trocar de modelo, você recompila em vez de reescrever prompts.
Qual é a diferença entre GEPA e MIPROv2 no DSPy?
Ambos são otimizadores do DSPy, mas buscam de formas diferentes. O MIPROv2 pré-gera uma grade fixa de instruções candidatas e de conjuntos de demos few-shot, e escolhe a melhor combinação por otimização bayesiana sobre avaliações em minibatches. O GEPA (Genetic-Pareto) faz evolução reflexiva: um LLM de reflexão mais forte reescreve as instruções com base em feedback em linguagem natural sobre por que uma previsão errou, e uma fronteira de Pareto mantém todo candidato que é o melhor em pelo menos um caso de validação. O artigo do GEPA relata que ele superou o MIPROv2 em mais de 10 pontos em seis tarefas, a um custo parecido (cerca de US$ 86 contra US$ 76 de gasto com LM nas execuções com GPT-4.1 Mini). Regra prática: métrica rica em feedback → GEPA; métrica escalar simples ou necessidade de selecionar demos → MIPROv2.
De quantos exemplos eu preciso para otimizar um programa com DSPy?
A documentação do DSPy recomenda pelo menos 30 exemplos para começar a ver valor e cerca de 300 para qualidade de produção. Separe aproximadamente 20% para treino e 80% para validação (o oposto do treino de redes neurais), porque os otimizadores pontuam cada candidato no conjunto de validação. Regra de bolso da documentação: cerca de 10 exemplos bastam para o BootstrapFewShot, 50+ para o BootstrapFewShotWithRandomSearch, e com 200+ vale a pena rodar o MIPROv2 por mais tempo. O GEPA funciona com um punhado de exemplos se a sua métrica devolver bom feedback textual.
O DSPy faz fine-tuning dos pesos do modelo?
Não por padrão. Os otimizadores principais (MIPROv2, GEPA, COPRO) ajustam os parâmetros do prompt: instruções e demonstrações few-shot. As chamadas de API ao seu modelo continuam somente leitura. O DSPy 3.x também traz otimizadores que treinam pesos (BootstrapFinetune, um módulo GRPO experimental para reinforcement learning e o BetterTogether, que encadeia a otimização de prompt com o fine-tuning), mas, para modelos acessíveis só por API, a otimização de prompt é a parte que você de fato vai usar.
O DSPy funciona com modelos locais ou self-hosted?
Sim. O dspy.LM suporta Ollama (ollama_chat/llama3.2:1b), vLLM, SGLang e qualquer endpoint compatível com OpenAI via openai/... com um api_base personalizado. As instruções otimizadas também se transferem entre modelos: o artigo do GEPA relata que prompts evoluídos no Qwen3-8B ganharam cerca de 9% quando reaproveitados no GPT-4.1 Mini. É esse o padrão por trás da redução de custo de ~75x que a Shopify teria obtido ao mover uma tarefa do GPT-5 para um modelo Qwen pequeno (número citado na documentação do DSPy a partir de uma palestra da Shopify; não encontrei o material original, então trate-o como uma alegação do fornecedor).
Quando não usar o DSPy?
Evite-o quando você não tem como avaliar as saídas: todo otimizador é tão bom quanto a sua métrica. Evite-o também para um único prompt estável em um problema já resolvido, em que o custo de abstração do framework não traz nada. E, se você pode bancar rollouts ilimitados para fine-tuning por RL, a otimização de pesos ainda pode superar a evolução de prompts. O artigo do GEPA é explícito: a evolução de prompts vence quando os rollouts são caros ou os pesos são inacessíveis.