Versionamento de prompts e avaliações em produção

1. Fundamentos do Versionamento de Prompts

1.1. Por que prompts precisam de versionamento: mutabilidade, regressão e rastreabilidade

Prompts em produção são artefatos vivos. Uma alteração aparentemente inocente — como reordenar instruções ou ajustar um exemplo few-shot — pode causar regressões silenciosas. Sem versionamento, equipes perdem a capacidade de rastrear qual versão gerou qual saída, tornando a depuração de comportamentos inesperados um exercício de adivinhação. O versionamento de prompts resolve três problemas centrais:

  • Mutabilidade: Prompts mudam com frequência. Cada iteração precisa ser capturada como um snapshot imutável.
  • Regressão: Uma versão nova pode piorar métricas que a anterior havia otimizado. Sem histórico, o rollback é cego.
  • Rastreabilidade: Em auditorias ou análises de incidentes, é essencial saber exatamente qual prompt foi usado em cada chamada.

1.2. Diferenças entre versionamento de código e versionamento de prompts

Enquanto código fonte tem compilação e testes unitários bem definidos, prompts são avaliados por heurísticas e julgamento humano. O versionamento de prompts precisa lidar com:

  • Saída não determinística: Mesmo com o mesmo prompt, o modelo pode gerar respostas diferentes.
  • Dependência de modelo: Um prompt otimizado para GPT-4 pode falhar em GPT-3.5.
  • Contexto externo: Exemplos few-shot, funções e parâmetros (temperatura, top_p) fazem parte do artefato.

1.3. Estrutura básica de um artefato de prompt versionado

Um artefato de prompt versionado deve conter:

# Estrutura de um prompt versionado (YAML)
version: "2.1.0"
created_at: "2025-03-15T10:30:00Z"
author: "equipe-nlp"
model: "gpt-4-turbo"
parameters:
  temperature: 0.3
  max_tokens: 500
template: |
  Você é um assistente especializado em {dominio}.
  Responda à pergunta do usuário de forma clara e concisa.
  {instrucoes_adicionais}

  Pergunta: {pergunta}

  Resposta:
variables:
  dominio: string
  instrucoes_adicionais: string
  pergunta: string
few_shot_examples:
  - input: "O que é versionamento?"
    output: "Versionamento é o processo de gerenciar mudanças em artefatos ao longo do tempo."
  - input: "Por que versionar prompts?"
    output: "Para garantir rastreabilidade, rollback e avaliação consistente."

2. Estratégias de Armazenamento e Controle de Versão

2.1. Repositórios dedicados (Git + arquivos YAML/JSON) vs. bancos de dados especializados

A escolha entre Git e banco de dados depende da escala:

  • Git + YAML/JSON: Ideal para equipes pequenas. Cada prompt é um arquivo versionado. Permite code review tradicional.
  • Bancos especializados: Ferramentas como LangSmith, Weights & Biases Prompts ou MLflow oferecem armazenamento com busca por versão, linhagem e métricas associadas.

2.2. Nomenclatura e semântica de versões (major, minor, patch para prompts)

Adote semântica inspirada no SemVer:

  • Major: Mudança estrutural que quebra compatibilidade (ex: novo formato de saída).
  • Minor: Adição de instruções ou exemplos sem quebrar contratos existentes.
  • Patch: Correções de typos, ajustes de wording sem impacto funcional.
# Exemplo de changelog de prompt
## [2.1.0] - 2025-03-15
### Added
- Instrução para evitar alucinações em respostas financeiras

## [2.0.0] - 2025-03-10
### Changed
- Formato de saída alterado de texto livre para JSON estruturado

## [1.3.2] - 2025-03-05
### Fixed
- Correção de typo no exemplo few-shot sobre cálculos

2.3. Blobs de contexto e dependências externas (exemplos, few-shot, funções)

Prompts frequentemente dependem de artefatos externos. Versionar apenas o template não é suficiente. É preciso incluir:

  • Exemplos few-shot: Cada exemplo pode ter sua própria versão.
  • Funções (tools): Definições de funções que o modelo pode chamar.
  • Documentos de contexto: Bases de conhecimento RAG.
# Referência a dependências externas no artefato de prompt
dependencies:
  few_shot_db:
    version: "3.0.1"
    path: "data/examples_v3.json"
  functions:
    version: "1.2.0"
    path: "tools/calculator_v1.json"
  knowledge_base:
    version: "2025-03-01"
    index: "product-docs-2025-03"

3. Pipeline de Avaliação de Prompts em Produção

3.1. Métricas objetivas: precisão, recall, tempo de resposta, custo por chamada

Métricas quantitativas são a primeira linha de defesa:

# Exemplo de registro de métricas por versão de prompt
prompt_version: "2.1.0"
period: "2025-03-15T00:00:00Z - 2025-03-15T23:59:59Z"
metrics:
  total_calls: 15234
  avg_latency_ms: 1240
  p95_latency_ms: 3200
  total_cost_usd: 45.70
  avg_cost_per_call_usd: 0.003
  error_rate: 0.02
  timeout_rate: 0.005

3.2. Avaliação subjetiva assistida: rubricas, LLM-as-judge e feedback humano

Para métricas qualitativas, combine:

  • Rubricas: Critérios como clareza, completude e tom.
  • LLM-as-judge: Modelo avaliador que pontua respostas.
  • Feedback humano: Amostragem de avaliações manuais.
# Rubrica de avaliação de prompt
criteria:
  - name: "clareza"
    description: "A resposta é compreensível para um leigo?"
    scale: 1-5
  - name: "completude"
    description: "Todos os aspectos da pergunta foram abordados?"
    scale: 1-5
  - name: "tom"
    description: "O tom é profissional e respeitoso?"
    scale: 1-5

llm_judge_prompt: |
  Avalie a resposta do assistente com base nos critérios abaixo.
  Atribua notas de 1 a 5 para cada critério.
  Forneça uma justificativa breve.

3.3. Coleta de logs e rastreamento de sessões para análise offline

Cada chamada deve gerar um log imutável:

# Log de chamada com versionamento
{
  "session_id": "abc-123",
  "timestamp": "2025-03-15T14:30:00Z",
  "prompt_version": "2.1.0",
  "model": "gpt-4-turbo",
  "parameters": {"temperature": 0.3, "max_tokens": 500},
  "input_variables": {"dominio": "finanças", "pergunta": "O que é EBITDA?"},
  "output": "EBITDA é a sigla para Lucros antes de Juros, Impostos, Depreciação e Amortização...",
  "latency_ms": 1100,
  "cost_usd": 0.0025,
  "evaluation": {
    "clareza": 5,
    "completude": 4,
    "tom": 5
  }
}

4. Testes Automatizados e Regressão de Prompts

4.1. Suíte de testes invariantes: saídas esperadas para entradas conhecidas

Crie testes que verificam comportamentos esperados:

# Teste invariante para prompt versão 2.1.0
test_cases:
  - input: {"dominio": "finanças", "pergunta": "O que é EBITDA?"}
    expected_contains: ["Lucros antes de Juros", "Impostos", "Depreciação"]
    expected_not_contains: ["alucinação", "invenção"]
  - input: {"dominio": "finanças", "pergunta": "Quanto é 2+2?"}
    expected_behavior: "deve recusar responder cálculos simples"

4.2. Detecção de drift semântico e mudanças de comportamento não intencionais

Compare embeddings das respostas entre versões:

# Script de detecção de drift semântico
1. Para cada caso de teste, gere embedding da resposta da versão atual
2. Calcule similaridade cosseno com embedding da versão anterior
3. Se similaridade < 0.85, sinalize drift potencial
4. Se drift for confirmado, bloqueie deploy automático

4.3. Integração contínua (CI) para validação de novos prompts antes do deploy

Pipeline CI para prompts:

# Pipeline CI para validação de prompt
steps:
  - name: "Validar estrutura do artefato"
    run: "validate-prompt-artifact prompt_v2.1.0.yaml"
  - name: "Executar testes invariantes"
    run: "run-invariant-tests prompt_v2.1.0.yaml"
  - name: "Comparar com versão estável atual"
    run: "compare-prompt-versions --base v2.0.0 --candidate v2.1.0"
  - name: "Avaliar custo estimado"
    run: "estimate-cost prompt_v2.1.0.yaml --model gpt-4-turbo"
  - name: "Aprovar ou rejeitar"
    condition: "todos os passos anteriores com sucesso"

5. Deploy e Rollback de Prompts

5.1. Estratégias de release: canary, blue-green e feature flags para prompts

  • Canary: 5% do tráfego para nova versão, monitora por 1 hora.
  • Blue-green: Swap completo entre versões com possibilidade de reversão instantânea.
  • Feature flags: Ativar/desativar versão por segmento de usuário.
# Configuração de canary para prompt
deployment:
  strategy: canary
  versions:
    - version: "2.0.0"
      traffic: 90%
    - version: "2.1.0"
      traffic: 10%
  evaluation_window: 3600  # segundos
  rollback_conditions:
    - metric: "error_rate"
      threshold: 0.05
    - metric: "avg_latency_ms"
      threshold: 2000

5.2. Mecanismos de rollback automático baseados em métricas de avaliação

Se métricas degradarem além do limiar, rollback automático:

# Alerta de rollback automático
alert:
  metric: "avg_user_satisfaction"
  condition: "< 3.5"
  window: "5m"
  action: "rollback_to_previous_version"
  notification: "slack #prompts-alerts"

5.3. Versionamento de configurações de modelo (parâmetros, temperatura) junto com prompts

Parâmetros fazem parte do artefato versionado:

# Artefato completo com parâmetros
version: "2.1.0"
model: "gpt-4-turbo"
parameters:
  temperature: 0.3
  top_p: 0.9
  frequency_penalty: 0.1
  presence_penalty: 0.0
  max_tokens: 500
  stop: ["\n\n", "FIM"]

6. Governança e Colaboração entre Equipes

6.1. Fluxo de revisão e aprovação de alterações em prompts (code review adaptado)

# Fluxo de aprovação de prompt
1. Autor cria branch: "prompt/feature/v2.1.0"
2. Abre pull request com diff do prompt
3. Revisor verifica:
   - Mudanças no template
   - Impacto em testes invariantes
   - Custo estimado
4. CI executa pipeline de validação
5. Aprovação de pelo menos 2 revisores
6. Merge para main e deploy automático (canary)

6.2. Controle de acesso e auditoria de modificações em produção

# Log de auditoria de modificação
{
  "action": "update_prompt",
  "prompt_id": "customer-support-v2",
  "old_version": "2.0.0",
  "new_version": "2.1.0",
  "user": "maria.silva@empresa.com",
  "timestamp": "2025-03-15T10:30:00Z",
  "approved_by": ["joao.santos@empresa.com"],
  "reason": "Adicionar instrução para evitar alucinações financeiras"
}

6.3. Documentação de mudanças e changelogs específicos para prompts

# Changelog de prompts - Release 2.1.0
## Novidades
- Instrução para verificar fontes antes de responder sobre finanças
- Exemplo few-shot atualizado para incluir caso de dados insuficientes

## Correções
- Typos nos exemplos de cálculos (issue #42)
- Temperatura reduzida de 0.5 para 0.3 para maior consistência

## Impacto
- Custo por chamada: +5% (devido a tokens extras na instrução)
- Precisão esperada: +3% (baseado em testes offline)

7. Monitoramento Contínuo e Ciclo de Vida

7.1. Dashboards de saúde dos prompts: taxa de erro, qualidade percebida, latência

# Dashboard de saúde de prompts (métricas em tempo real)
Prompt: customer-support-v2 (versão 2.1.0)
- Calls/min: 450
- Error rate: 1.2% (threshold: 3%)
- Avg latency: 1.1s (threshold: 2s)
- User satisfaction: 4.3/5 (threshold: 3.5)
- Cost/hour: $2.45
- Drift score: 0.92 (threshold: 0.85)

7.2. Alertas baseados em degradação de avaliações e outliers

# Regras de alerta
- Se error_rate > 5% por 5 minutos: alerta crítico
- Se avg_latency > 3s por 10 minutos: alerta de performance
- Se user_satisfaction < 3.0 por 15 minutos: alerta de qualidade
- Se drift_score < 0.80: alerta de drift semântico

7.3. Políticas de descontinuação de versões antigas e migração forçada

# Política de ciclo de vida de prompts
- Versões com mais de 30 dias sem uso: arquivadas
- Versões com taxa de erro > 10% por 24h: desativadas automaticamente
- Migração forçada: usuários em versões com vulnerabilidade conhecida
- Notificação: 7 dias antes da descontinuação

Referências