Versionamento de prompts e gestão de catálogo
Nesta página
Lição atualizada a 3 de novembro de 2026 com base na documentação da OpenAI:
temperatureetop_psó são aceites com um esforço de raciocínio denone, enquanto os modelos GPT-5.6 raciocinam por predefinição (medium). As chamadas que definem estes parâmetros devem, portanto, especificarreasoning={"effort": "none"}(API de Respostas) oureasoning_effort="none"(Chat Completions). Fontes: Utilizar o GPT-6 · GPT-5.6 Terra.
Versionamento de prompts e gestão de catálogo
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.
Estrutura do catálogo
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