Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Versionamento de prompts e gestão de catálogo

Aula 14 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Versionamento de prompts e gestão de catálogo
  2. Por que versionar prompts
  3. Estrutura do catálogo
  4. Utilizar o catálogo na sua aplicação
  5. Versionamento com Git
  6. Boas práticas
  7. Testar o catálogo com um rollback
  8. Pontos-chave

Lição atualizada a 3 de novembro de 2026 com base na documentação da OpenAI: temperature e top_p só são aceites com um esforço de raciocínio de none, enquanto os modelos GPT-5.6 raciocinam por predefinição (medium). As chamadas que definem estes parâmetros devem, portanto, especificar reasoning={"effort": "none"} (API de Respostas) ou reasoning_effort="none" (Chat Completions). Fontes: Utilizar o GPT-6 · GPT-5.6 Terra.

Em produção, os seus prompts evoluem tanto quanto o seu código. Sem versionamento, perde o rasto das alterações, não consegue reverter e não faz ideia de qual a versão que está a correr em produção. Esta lição mostra-lhe como gerir prompts como artefactos de software.

Por que versionar prompts

Uma alteração num prompt pode mudar radicalmente o comportamento da sua aplicação. Ao contrário do código, estas alterações são muitas vezes subtis e difíceis de detetar sem testes automatizados: uma frase reformulada, uma palavra deslocada, e o modelo começa a classificar mal um em cada dez casos limite. Nenhum teste unitário padrão detetará esta falha, mas o suporte sinalizá-la-á três semanas depois como uma queixa vaga sobre tickets mal direcionados.

O versionamento responde a quatro necessidades distintas. Primeiro, a rastreabilidade: saber quem alterou o quê e quando transforma um debate estéril na equipa numa simples verificação do histórico. Segundo, o rollback: quando surge uma regressão, o objetivo imediato não é entender o porquê, mas restaurar um comportamento conhecido. Terceiro, a comparação de desempenho: isto exige que as versões antigas permaneçam executáveis exatamente como estavam, com o seu modelo e definições originais. Por fim, a auditoria: para sistemas sujeitos ao RGPD (Regulamento Geral sobre a Proteção de Dados) ou outras estruturas de conformidade, deve demonstrar quais as instruções em vigor numa determinada data — uma captura de ecrã não será suficiente.

A classe PromptCatalog responde a estas necessidades com uma infraestrutura mínima: uma pasta por prompt, um ficheiro JSON por versão, numerados sequencialmente. Cada ficheiro agrupa o texto do prompt de sistema juntamente com o modelo e a temperatura associados — um prompt afinado para 0,1 e o mesmo prompt a 0,7 não são a mesma coisa, e bloqueá-los em conjunto impede restaurar o texto enquanto se esquecem as suas definições.

O campo status acompanha o ciclo de vida. Uma versão começa como draft, permitindo preparação e testes sem afetar o tráfego em direto. Chamar activate muda o estado para active e despromove automaticamente a versão anterior para deprecated, garantindo que apenas uma versão serve tráfego em qualquer momento. Este método torna o rollback trivial: reativar uma versão anterior é uma única chamada, não uma implementação. A sua aplicação chama get_active em produção, enquanto list_versions suporta revisões e auditorias.

import json
from datetime import datetime
from pathlib import Path

class PromptCatalog:
    """Gestor de catálogo de prompts com versionamento."""

    def __init__(self, catalog_dir: str = "prompts/"):
        self.catalog_dir = Path(catalog_dir)
        self.catalog_dir.mkdir(parents=True, exist_ok=True)

    def save_prompt(self, name: str, system_prompt: str,
                    model: str, temperature: float,
                    metadata: dict = None) -> str:
        """Guarda uma nova versão de um prompt."""
        prompt_dir = self.catalog_dir / name
        prompt_dir.mkdir(exist_ok=True)

        # Determinar o número da versão
        versions = sorted(prompt_dir.glob("v*.json"))
        version = len(versions) + 1
        version_str = f"v{version:03d}"

        # Guardar
        prompt_data = {
            "name": name,
            "version": version_str,
            "created_at": datetime.now().isoformat(),
            "model": model,
            "temperature": temperature,
            "system_prompt": system_prompt,
            "metadata": metadata or {},
            "status": "draft"  # draft | active | deprecated
        }

        filepath = prompt_dir / f"{version_str}.json"
        filepath.write_text(json.dumps(prompt_data, indent=2,
                                        ensure_ascii=False))

        return version_str

    def get_prompt(self, name: str,
                   version: str = "latest") -> dict:
        """Recupera um prompt pelo nome e versão."""
        prompt_dir = self.catalog_dir / name

        if version == "latest":
            versions = sorted(prompt_dir.glob("v*.json"))
            if not versions:
                raise FileNotFoundError(f"Prompt '{name}' não encontrado")
            filepath = versions[-1]
        else:
            filepath = prompt_dir / f"{version}.json"

        return json.loads(filepath.read_text())

    def get_active(self, name: str) -> dict:
        """Recupera a versão ativa de um prompt."""
        prompt_dir = self.catalog_dir / name
        for filepath in sorted(prompt_dir.glob("v*.json"),
                               reverse=True):
            data = json.loads(filepath.read_text())
            if data["status"] == "active":
                return data
        raise FileNotFoundError(
            f"Nenhuma versão ativa para '{name}'"
        )

    def activate(self, name: str, version: str):
        """Ativa uma versão e desativa as outras."""
        prompt_dir = self.catalog_dir / name

        for filepath in prompt_dir.glob("v*.json"):
            data = json.loads(filepath.read_text())
            if data["version"] == version:
                data["status"] = "active"
            elif data["status"] == "active":
                data["status"] = "deprecated"
            filepath.write_text(json.dumps(data, indent=2,
                                            ensure_ascii=False))

    def list_versions(self, name: str) -> list[dict]:
        """Lista todas as versões de um prompt."""
        prompt_dir = self.catalog_dir / name
        versions = []
        for filepath in sorted(prompt_dir.glob("v*.json")):
            data = json.loads(filepath.read_text())
            versions.append({
                "version": data["version"],
                "status": data["status"],
                "created_at": data["created_at"],
                "model": data["model"]
            })
        return versions

Utilizar o catálogo na sua aplicação

Do lado de quem chama, a regra é simples: o seu código não contém texto de prompt; solicita a versão ativa ao catálogo. Isto mantém os prompts modificáveis sem tocar no código da aplicação e impede que cadeias de trinta linhas fiquem soterradas no meio de uma função. Os metadados guardados durante o armazenamento — autor, descrição, registo de alterações — não têm efeito na execução, mas tornam o histórico legível seis meses depois, quando ninguém se lembrar porque é que a redação mudou.

O detalhe crítico está no fim de classifier_ticket: a resposta devolvida inclui prompt_version. Registe este campo com cada resultado, e a análise de incidentes torna-se possível — saberá que os tickets mal classificados na tarde de terça-feira vieram todos da v004, sem cruzar carimbos de tempo de implementação.

from openai import OpenAI

client = OpenAI()
catalog = PromptCatalog("prompts/")

# Guardar um prompt
catalog.save_prompt(
    name="ticket-classifier",
    system_prompt="""You are a support ticket classifier.
Categorize each ticket as: bug, feature, question, billing.
Respond in JSON with category, priority (1-5), summary.""",
    model="gpt-5.6-terra",
    temperature=0.1,
    metadata={
        "author": "marie.dupont",
        "description": "Classificação automática de tickets Zendesk",
        "changelog": "Versão inicial"
    }
)

# Em produção: usar a versão ativa
def classifier_ticket(ticket_text: str) -> dict:
    """Classifica um ticket utilizando o prompt ativo."""
    prompt_config = catalog.get_active("ticket-classifier")

    response = client.responses.create(
        model=prompt_config["model"],
        reasoning={"effort": "none"},  # temperature requer effort none
        instructions=prompt_config["system_prompt"],
        input=ticket_text,
        temperature=prompt_config["temperature"]
    )

    return {
        "result": json.loads(response.output_text),
        "prompt_version": prompt_config["version"]
    }

Versionamento com Git

Para equipas, guarde os seus prompts num repositório Git dedicado. A árvore abaixo segue uma convenção simples: uma pasta por prompt, contendo a sua definição, casos de teste e registo de alterações. Manter os testes ao lado do prompt que verificam não é cosmético — um pull request modifica ambos em conjunto, e o revisor julga a alteração com base em evidências e não em intenções declaradas.

prompts/
  ticket-classifier/
    prompt.yaml
    tests/
      test_cases.json
    CHANGELOG.md
  invoice-extractor/
    prompt.yaml
    tests/
      test_cases.json
    CHANGELOG.md

O YAML substitui o JSON aqui por uma razão específica: os prompts são textos multilinea, e a sintaxe | exibe-os exatamente como são enviados, sem caracteres de escape ou \n erráticos. Um diff do Git neste ficheiro lê-se como um diff de prosa — o revisor vê que uma frase foi adicionada. O esquema de saída viaja no mesmo ficheiro, pelo que a configuração completa de uma chamada cabe num único artefacto.

# prompts/ticket-classifier/prompt.yaml
name: ticket-classifier
model: gpt-5.6-terra
temperature: 0.1
max_output_tokens: 500
system_prompt: |
  You are a support ticket classifier.
  Categorize each ticket as: bug, feature, question, billing.
  Respond in JSON with category, priority (1-5), summary.
schema:
  type: object
  properties:
    category:
      type: string
      enum: [bug, feature, question, billing]
    priority:
      type: integer
    summary:
      type: string
  required: [category, priority, summary]
  additionalProperties: false

Boas práticas

O que separa um catálogo vivo de uma pasta de arquivo resume-se a algumas regras de manutenção. Mantenha um prompt por ficheiro: misturar vários prompts num único documento torna os diffs ilegíveis e os rollbacks impossíveis de direcionar. Imponha um registo de alterações que documente não o que mudou — o diff mostra isso — mas porquê: «adicionada instrução sobre tickets multilingues após feedback do suporte» vale mais do que dez linhas de descrição técnica.

Associe sistematicamente um conjunto de testes a cada prompt; caso contrário, serão os utilizadores os primeiros a dizer-lhe quando uma modificação quebra um comportamento estabelecido. Encaminhe as alterações de prompts pelo mesmo processo de revisão de código que o próprio código: um prompt que vai para produção sem revisão produz as mesmas surpresas que código não revisto. Verifique se o rollback demora menos de um minuto e teste-o num dia calmo, em vez de durante um incidente. Por fim, marque as versões implementadas com tags para ligar inequivocamente o comportamento observado a um estado específico do repositório.

Testar o catálogo com um rollback

Configure um PromptCatalog para três prompts reais da sua aplicação e registe duas ou três versões de cada um, evoluindo as instruções em pequenos passos — uma instrução de tom, uma categoria adicionada. O versionamento prova o seu valor nestas alterações de pormenor, porque são aquelas de que não se lembrará de ter feito. Configure a ativação e desativação e anexe um conjunto de testes a cada prompt.

Termine com o exercício mais instrutivo: ative deliberadamente uma versão degradada, observe a regressão através dos testes e execute o rollback cronometrando o tempo. Se a operação exceder um minuto, corrija o procedimento antes de adicionar um único prompt ao catálogo — um rollback lento não é um rollback, é um incidente prolongado.

Pontos-chave

  • Os prompts são artefactos de software que exigem versionamento
  • Cada versão é um ficheiro JSON ou YAML com metadados
  • O estado (draft, active, deprecated) permite uma implementação gradual
  • Guarde os prompts no Git com testes e um registo de alterações
  • O rollback deve ser instantâneo em caso de regressão