DSPy na prática: programe e otimize tarefas com IA

Informações verificadas em 15 de outubro de 2026 na documentação atual do DSPy, no PyPI e na tabela de preços de modelos do Google. O PyPI lista o DSPy 3.4.1, lançado em 12 de outubro de 2026, compatível com Python 3.10 ou superior, abaixo de 3.16. O pacote a instalar é dspy. Metadados do pacote no PyPI.

O que é DSPy e o que significa compilar um programa?

DSPy é um framework de código aberto em Python para definir tarefas de modelos de linguagem como programas e, depois, melhorar seus prompts ou, com otimizadores específicos, os pesos dos modelos. Sua proposta é permitir melhorias que possam ser repetidas e avaliadas segundo a sua definição de sucesso. Isso não significa que o primeiro prompt gerado será melhor do que um escrito com cuidado. Visão geral do DSPy.

Pense em um ensaio. A assinatura é o roteiro da tarefa, o módulo define como ela será executada e a métrica estabelece o critério de avaliação. O otimizador faz uma mudança, observa o resultado e mantém o que funciona. Sem um critério de avaliação, é possível ensaiar de maneiras diferentes indefinidamente sem saber se houve alguma melhora.

Assinaturas definem a tarefa

Uma assinatura declara as entradas, as saídas e as instruções da tarefa. "ticket -> category" indica que entra um chamado e sai uma categoria. Uma assinatura definida como classe pode acrescentar campos tipados e uma docstring que explica a tarefa. A escolha dos campos continua sendo importante: um otimizador não resolve uma definição ambígua do que a empresa considera “urgente”. Documentação de assinaturas.

Módulos do DSPy definem como executar a tarefa

Um módulo implementa uma estratégia de execução. dspy.Predict é o componente básico de predição. dspy.ChainOfThought acrescenta um campo de raciocínio antes da resposta. dspy.ReAct permite um ciclo de raciocínio e uso de ferramentas. Quando uma única etapa com o modelo não basta, você pode combinar módulos em Python. Documentação de módulos.

Para encaminhar chamados de suporte, comece com Predict. Acrescentar um ciclo de uso de ferramentas só para classificar uma mensagem curta aumenta a complexidade antes de você demonstrar que precisa dela.

Compilar é executar um processo de otimização

Um otimizador altera partes específicas de um programa com base em exemplos e uma métrica. Na otimização de prompts, .compile() devolve um programa com instruções revisadas ou demonstrações — isto é, exemplos incluídos no prompt. O método não transforma a aplicação em um executável nativo nem elimina chamadas futuras ao modelo. Treinar os pesos exige escolher outro tipo de otimizador. Guia de escolha de otimizadores.

Tutorial de DSPy: o exemplo mínimo da documentação atual

O programa introdutório da documentação atual gera um haicai. Esse exemplo simples mostra a interface sem envolver banco de dados, ferramentas ou uma busca de otimização.

Instale a versão verificada no seu ambiente Python:

python -m pip install 'dspy[litellm]==3.4.1'

Defina a variável de ambiente GEMINI_API_KEY com uma chave válida da API do Google Gemini. Salve o código como first_dspy.py e execute python first_dspy.py:

import os
import dspy

lm = dspy.LM(
    "gemini/gemini-2.5-flash-lite",
    api_key=os.environ["GEMINI_API_KEY"],
    engine="litellm",
)
dspy.configure(lm=lm)

haiku_signature = "subject -> haiku"
haiku_generator = dspy.Predict(haiku_signature)
result = haiku_generator(subject="computer science")
print(result.haiku)

As quatro últimas linhas são o primeiro programa da documentação atual. A configuração segue o padrão de configuração de modelos do DSPy, com a substituição pelo Google Gemini 2.5 Flash-Lite para usar o mesmo modelo de baixo custo no experimento a seguir. O identificador do provedor segue a integração do LiteLLM com o Gemini; a escolha explícita do backend é compatível com a API LM do DSPy.

O DSPy monta um prompt a partir da assinatura, envia esse prompt ao modelo configurado e extrai o campo haiku da resposta. Este é um exemplo de inferência, não uma execução de otimização. Não há aqui uma promessa de poema específico nem de ganho de qualidade.

Otimização de prompts com DSPy exige uma métrica

Sem métrica, a otimização perde o sentido. Uma métrica é uma função que converte uma predição em uma pontuação. No encaminhamento de chamados, ela pode comparar a categoria prevista com um rótulo aprovado por uma pessoa. Para uma resposta gerada, avaliar a correção pode exigir critérios de avaliação ou uma verificação executável. A interface de métricas do DSPy aceita a sua função de pontuação; o framework não decide quais resultados a empresa deve valorizar. Métricas e avaliação.

Por isso, mesmo um conjunto pequeno de avaliação com rótulos faz diferença. Se você cansou de trocar “seja conciso” por “responda brevemente”, reúna falhas reais: um pedido de reembolso encaminhado ao suporte técnico, um problema de login confundido com cobrança ou uma mensagem com duas solicitações. Defina o resultado esperado antes de olhar a saída de um novo prompt.

Para um primeiro piloto, use 60 exemplos distintos, divididos de propósito em 20 de treinamento, 20 de validação e 20 de teste final. Esses tamanhos são uma proposta de experimento, não uma exigência do DSPy nem uma prova de confiabilidade em produção.

• Exemplos de treinamento fornecem o material com que o otimizador pode aprender.
• Exemplos de validação ajudam a comparar versões e orientar as decisões de desenvolvimento.
• Exemplos de teste final ficam intocados até que você congele o candidato e as regras de avaliação.

Mantenha chamados relacionados ao mesmo cliente ou incidente em uma única divisão. Caso contrário, exemplos quase duplicados podem dar a impressão de que o prompt otimizado generaliza melhor do que de fato generaliza. Inclua falhas raras que sejam relevantes, em vez de preencher todos os conjuntos com casos fáceis.

A afirmação “sem métrica” pede uma ressalva precisa. É possível executar um programa DSPy sem otimização e sem métrica, e o LabeledFewShot pode anexar exemplos sem pontuá-los. Isso é configuração, não evidência de que uma alteração melhorou a tarefa. Também não é obrigatório ter uma resposta de referência escrita à mão para toda tarefa: uma verificação executável de correção pode fornecer o sinal necessário. Para classificações de negócio, rótulos aprovados costumam ser o ponto de partida mais claro. Referência inicial com few-shot.

Otimizadores do DSPy: os nomes da documentação atual

Comece pelo otimizador mais simples capaz de tratar uma falha que você consiga identificar. Ampliar a busca só ajuda quando a métrica consegue distinguir candidatos melhores de candidatos piores.

O índice atual da API de otimizadores lista exatamente estas entradas: BetterTogether, BootstrapFewShot, BootstrapFewShotWithRandomSearch, BootstrapFinetune, BootstrapRS, COPRO, Ensemble, GEPA, InferRules, KNN, KNNFewShot, LabeledFewShot, MIPROv2 e SIMBA.

Nem todas são algoritmos de busca independentes. BootstrapRS é um nome alternativo para BootstrapFewShotWithRandomSearch; KNN é o componente auxiliar de recuperação usado por KNNFewShot. O guia atual de escolha também cita AvatarOptimizer para programas no formato de agentes, embora ele não apareça nesse índice da API. Detalhes da família de otimizadores, guia de escolha.

O MIPROv2 propõe instruções e usa otimização bayesiana, um método de busca orientado pelas pontuações anteriores, para explorar combinações de instruções e demonstrações. O SIMBA trabalha com pequenos lotes e propõe regras ou demonstrações. São abordagens diferentes, não versões do BootstrapFewShot com outro nome. API do MIPROv2, API do SIMBA.

O GEPA usa um modelo de reflexão para ler o retorno das execuções e propor mudanças nas instruções. Uma pontuação acompanhada de uma explicação específica, como “pedidos de reembolso devem ir para cobrança mesmo quando mencionam uma funcionalidade com defeito”, oferece um sinal mais útil do que apenas uma nota de falha. A documentação detalhada permite métricas exclusivamente numéricas, mas explica que elas perdem esse retorno mais rico. Funcionamento do GEPA.

Defina limites para a primeira execução de otimização

É mais fácil contabilizar um pequeno experimento com BootstrapFewShot do que uma busca de instruções sem limites definidos. A proposta a seguir usa um módulo Predict, uma métrica determinística para os rótulos e o mesmo modelo como professor e como preditor.

DSPy BootstrapFewShot: um experimento pequeno de propósito

Prepare train.jsonl, validation.jsonl e test.jsonl, cada um com 20 chamados distintos e rotulados por pessoas. Cada linha deve ser um objeto JSON com text e label; os rótulos permitidos são billing, technical, account e other. Por exemplo, um pedido de alteração do endereço em uma fatura poderia receber o rótulo billing. Use seus próprios exemplos, não a saída do gerador de haicais.

Salve este script separado como optimize_tickets.py e execute-o depois de definir a mesma chave de API:

import json
import os
from typing import Literal
import dspy

lm = dspy.LM(
    "gemini/gemini-2.5-flash-lite",
    api_key=os.environ["GEMINI_API_KEY"],
    engine="litellm",
    cache=False,
)
dspy.configure(lm=lm)

class RouteTicket(dspy.Signature):
    """Choose the support queue responsible for the ticket's main request."""
    text: str = dspy.InputField()
    label: Literal["billing", "technical", "account", "other"] = (
        dspy.OutputField()
    )

def load_examples(path):
    with open(path, encoding="utf-8") as source:
        rows = [json.loads(line) for line in source if line.strip()]
    assert len(rows) == 20
    return [dspy.Example(**row).with_inputs("text") for row in rows]

train = load_examples("train.jsonl")
validation = load_examples("validation.jsonl")
test = load_examples("test.jsonl")
assert len({e.text for e in train + validation + test}) == 60

def correct_label(example, prediction, trace=None):
    return prediction.label == example.label

program = dspy.Predict(RouteTicket)
evaluate = dspy.Evaluate(
    devset=validation, metric=correct_label, num_threads=1
)
print("Baseline validation:", evaluate(program).score)

optimizer = dspy.BootstrapFewShot(
    metric=correct_label,
    max_bootstrapped_demos=4,
    max_labeled_demos=0,
    max_rounds=1,
)
optimized = optimizer.compile(program, trainset=train)
print("Optimized validation:", evaluate(optimized).score)

# Freeze this candidate before opening the final test results.
final_test = dspy.Evaluate(
    devset=test, metric=correct_label, num_threads=1
)
print("Baseline final test:", final_test(program).score)
print("Optimized final test:", final_test(optimized).score)
optimized.save("candidate_ticket_router.json")

Esta é uma adaptação que usa o construtor documentado do BootstrapFewShot e a interface de avaliação, não a apresentação de um benchmark. Ela solicita até quatro demonstrações bem-sucedidas, permite uma tentativa de bootstrap por exemplo de treinamento e não acrescenta demonstrações rotuladas diretamente, sem passar pelo bootstrap. O arquivo salvo é um candidato para revisão, não uma aprovação automática para produção.

A contagem de execuções dessa proposta fica assim:

• Versão de referência na validação: 20 execuções do programa.
• Bootstrap sobre o conjunto de treinamento: até 20 execuções do professor, possivelmente menos se já houver demonstrações aprovadas em quantidade suficiente.
• Programa otimizado na validação: 20 execuções do programa.
• As duas versões no conjunto de teste final: 40 execuções do programa.

São até 100 execuções de uma única etapa, incluindo a avaliação; a compilação sozinha responde por, no máximo, 20. Se cada execução fizer uma chamada bem-sucedida ao modelo, sem novas tentativas nem mecanismos alternativos de interpretação da resposta, serão no máximo 100 chamadas ao modelo da tarefa. A verificação inicial com o haicai é contabilizada à parte. Um LLM avaliador, um ciclo de agente, novas tentativas ou outra rodada de otimização alteram esse total.

Pelos preços de tabela do Google na modalidade paga Standard para texto do Gemini 2.5 Flash-Lite, de US$ 0.10 por milhão de tokens de entrada e US$ 0.40 por milhão de tokens de saída, 100 chamadas com uma média hipotética de 1,000 tokens de entrada e 100 de saída custam US$ 0.014: 100,000 ÷ 1,000,000 × US$ 0.10 + 10,000 ÷ 1,000,000 × US$ 0.40. Preços do Google.

Esse cálculo cobre apenas o modelo; não é uma fatura medida nem um teto de gastos. A hipótese de tokens de entrada precisa incluir a formatação do DSPy e as demonstrações anexadas. Chamados mais longos, saídas maiores e raciocínio cobrado aumentam o valor. A estimativa não considera descontos por lote ou cache. O registro para a contabilidade é o consumo real informado pelo provedor.

DSPy, prompts manuais ou fine-tuning: quando usar cada um?

Use DSPy quando precisar de um processo repetível para melhorar um programa cujo desempenho possa ser medido. Mantenha um prompt escrito à mão quando ele já atender aos requisitos da tarefa. Considere fine-tuning quando houver evidências de que mudar os prompts não basta e treinar um modelo for compatível com as restrições da sua implantação.

Essas técnicas são compatíveis entre si. O DSPy inclui BootstrapFinetune, e o BetterTogether combina otimização de prompts e de pesos. A diferença prática está no que você altera e mantém, não no nome que parece mais avançado. Otimização de prompts e pesos.

O ponto de virada aparece na operação: se toda troca de modelo ou nova falha faz um engenheiro voltar a editar vários prompts manualmente, um ciclo de otimização com pontuação começa a valer a pena. Se um prompt curto já passa pelos critérios de aceitação, não há benefício demonstrado em substituí-lo por um framework.

Quem deve adotar, esperar ou deixar o DSPy de lado?

Engenheiros devem avançar quando há uma tarefa recorrente, uma versão de referência funcional e falhas representativas. Encaminhamento de chamados e extração estruturada são bons pontos de partida porque as saídas esperadas podem ser verificadas. Otimize um componente pequeno antes de ampliar o sistema. O limite do DSPy é a qualidade do objetivo: ele pode selecionar um candidato com pontuação maior mesmo quando a métrica recompensa o comportamento errado.

As equipes de operação devem assumir os rótulos e as prioridades dos erros. Para um gestor de suporte, encaminhar incorretamente um incidente de acesso à conta pode ser muito mais grave do que errar uma dúvida comum sobre cobrança. Se a pontuação tratar os dois casos da mesma forma, a otimização pode contrariar as prioridades do gestor. Defina essa regra antes de pedir a um engenheiro que melhore a pontuação.

Quem contrata deve exigir evidências com exemplos ainda não vistos. Pergunte qual versão de referência foi usada na comparação, quais casos pioraram, o que passou a fazer parte do programa em operação e se o fluxo ainda atende aos requisitos de latência. O nome do otimizador não é evidência suficiente para aprovar a adoção. A análise do Promptfoo publicada no site é uma leitura complementar para equipes que estão organizando o trabalho de avaliação.

Uma equipe de negócio deve deixar o DSPy de lado para textos ocasionais, pesquisas pontuais ou um fluxo que muda antes de acumular exemplos. O mesmo vale quando ninguém pode manter código Python ou chegar a um acordo sobre a regra de pontuação. Um bom prompt, uma lista de verificação e revisão humana podem ser uma solução mais proporcional. Espere se o problema real for a falta de dados de origem ou um processo indefinido: otimizar a redação não resolve nenhuma dessas lacunas.

Onde as promessas sobre DSPy passam do ponto?

“Programar em vez de escrever prompts” não faz os prompts desaparecerem. O DSPy os cria e gerencia; as pessoas continuam definindo a tarefa, avaliando falhas e decidindo se o resultado é aceitável.

“Compilar” não significa que o modelo aprendeu de forma permanente. Com otimizadores de prompts, o artefato aprendido são instruções ou demonstrações. A inferência continua exigindo chamadas a um modelo, e as demonstrações ocupam espaço no prompt. É possível salvar o estado aprendido em JSON e carregá-lo em um novo programa. Como salvar e carregar.

“Otimização automática” não garante uma melhora automática. A comparação útil é com a abordagem que você já usa, aplicada a entradas ainda não vistas. Uma pontuação maior durante o desenvolvimento pode ser consequência de sobreajuste, de um avaliador permissivo ou de um conjunto de dados que não inclui falhas de alto custo.

Além disso, chamadas à métrica não são chamadas ao provedor. O max_metric_calls do GEPA limita as invocações de pontuação; a reflexão também chama um modelo, e o próprio programa avaliado pode fazer várias requisições. As configurações auto não correspondem a um valor de fatura universal. Controles de orçamento do GEPA.

Perguntas frequentes de quem desenvolve com DSPy

Qual é o próximo passo?

Na segunda-feira, escolha uma falha recorrente de encaminhamento de chamados ou de extração e peça ao responsável pelo processo que rotule exemplos representativos. Congele uma versão de referência, defina uma regra de pontuação e rode um experimento com limites claros. Revise as respostas que mudaram antes de aprovar o candidato. Se não for possível definir a pontuação, a próxima tarefa útil é chegar a um acordo sobre a regra de negócio.

Receba explicações práticas sobre engenharia de IA na newsletter.