0Pricing
AI Prompt Engineering · Aula

Arquitetura de registro de prompts

Armazenamento de prompts como artefatos versionados, com metadados e etiquetas.

Arquitetura de registro de prompts é uma aula grátis de AI Prompt Engineering no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Prompt Engineering, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Prompt Engineering inclui 4 aulas no total.

Por que um registro de prompts?

Sem um registro, os prompts ficam espalhados pelo código, pelos arquivos de configuração e pela memória dos desenvolvedores. Um registro de prompts é um repositório centralizado que trata cada prompt como um artefato versionado e rastreável — assim como o código de software.

Entre os benefícios estão a reprodutibilidade, a possibilidade de auditoria, a capacidade de rollback e a colaboração entre equipes.

Campos essenciais do artefato de prompt

Cada artefato de prompt deve conter estes campos:

  • prompt_id — identificador exclusivo e estável (por exemplo, summarize-article)
  • version — cadeia de caracteres de versão semântica (por exemplo, 2.1.0)
  • template — o texto real do prompt com marcadores {variable}
  • metadata — autor, etiquetas, modelo-alvo, data de criação e descrição

Projeto do esquema do banco de dados

Um esquema relacional para um registro de prompts armazena os prompts e seu histórico de versões em tabelas separadas, permitindo consultas e auditorias eficientes.

-- prompts table: one row per unique prompt identity
CREATE TABLE prompts (
  prompt_id   VARCHAR(100) PRIMARY KEY,
  description TEXT,
  created_at  TIMESTAMP DEFAULT NOW()
);

-- prompt_versions table: one row per versioned artifact
CREATE TABLE prompt_versions (
  id          SERIAL PRIMARY KEY,
  prompt_id   VARCHAR(100) REFERENCES prompts(prompt_id),
  version     VARCHAR(20)  NOT NULL,
  template    TEXT         NOT NULL,
  author      VARCHAR(100),
  tags        TEXT[],
  model       VARCHAR(50),
  is_active   BOOLEAN DEFAULT FALSE,
  created_at  TIMESTAMP DEFAULT NOW(),
  UNIQUE(prompt_id, version)
);

Projeto de registro baseado em arquivos

Para equipes menores, um registro baseado em arquivos usa uma estrutura de diretórios organizada. Cada prompt recebe uma pasta; cada versão é um arquivo YAML ou JSON dentro dela.

# Directory structure
prompts/
  summarize-article/
    1.0.0.yaml
    1.1.0.yaml
    latest -> 1.1.0.yaml  # symlink
  classify-sentiment/
    1.0.0.yaml

# Example: summarize-article/1.1.0.yaml
prompt_id: summarize-article
version: '1.1.0'
model: gpt-4o-mini
author: alice@company.com
tags: [summarization, articles, english]
created_at: '2024-06-01T10:00:00Z'
template: |
  Summarize the following article in {num_sentences} sentences.
  Focus on: {focus_area}.

  Article:
  {article_text}

Classe PromptRegistry em Python

Uma classe simples em Python encapsula o acesso ao banco de dados e expõe métodos claros: register(), get_active() e list_versions().

import psycopg2
import json
from datetime import datetime

class PromptRegistry:
    def __init__(self, dsn):
        self.conn = psycopg2.connect(dsn)

    def register(self, prompt_id, version, template, author, tags, model):
        with self.conn.cursor() as cur:
            # Ensure prompt identity exists
            cur.execute(
                'INSERT INTO prompts (prompt_id) VALUES (%s) ON CONFLICT DO NOTHING',
                (prompt_id,)
            )
            cur.execute(
                '''INSERT INTO prompt_versions
                   (prompt_id, version, template, author, tags, model)
                   VALUES (%s, %s, %s, %s, %s, %s)''',
                (prompt_id, version, template, author, tags, model)
            )
        self.conn.commit()
        print(f'Registered {prompt_id}@{version}')

    def get_active(self, prompt_id):
        with self.conn.cursor() as cur:
            cur.execute(
                'SELECT template, version FROM prompt_versions '
                'WHERE prompt_id=%s AND is_active=TRUE LIMIT 1',
                (prompt_id,)
            )
            row = cur.fetchone()
        if not row:
            raise ValueError(f'No active version for {prompt_id}')
        return {'template': row[0], 'version': row[1]}

Análise aprofundada do esquema de metadados

Metadados detalhados tornam o registro útil para muito mais do que um simples armazenamento. Principais campos de metadados:

  • autor — responsabilidade e ponto de contato
  • etiquetas — rótulos pesquisáveis, como ['production', 'summarization', 'v2']
  • modelo — modelo-alvo (o prompt pode não ser independente de modelo)
  • registro de alterações — descrição legível das mudanças realizadas
  • conjunto de testes — link para o conjunto de dados de avaliação deste prompt
# Extended metadata example
prompt_metadata = {
    'prompt_id': 'extract-key-dates',
    'version': '2.0.0',
    'author': 'bob@company.com',
    'tags': ['extraction', 'dates', 'contracts', 'production'],
    'model': 'gpt-4o',
    'changelog': 'Added support for relative dates (next quarter, end of year)',
    'test_suite': 's3://company-evals/extract-key-dates/v2-testset.jsonl',
    'created_at': '2024-07-15T09:30:00Z',
    'is_active': True
}

Renderização de modelos com variáveis

Os modelos de prompt usam uma sintaxe de marcadores de posição. O registro gera o prompt final substituindo as variáveis de execução no modelo. Usar str.format_map() do Python é seguro e simples.

class PromptRegistry:
    # ... (previous methods)

    def render(self, prompt_id, variables: dict) -> str:
        artifact = self.get_active(prompt_id)
        template = artifact['template']
        try:
            rendered = template.format_map(variables)
        except KeyError as e:
            raise ValueError(f'Missing variable {e} for prompt {prompt_id}')
        return rendered

# Usage
registry = PromptRegistry(dsn='postgresql://...')
prompt = registry.render(
    'summarize-article',
    {
        'num_sentences': 3,
        'focus_area': 'financial impact',
        'article_text': 'Apple reported record revenue of $119B...'
    }
)
print(prompt)
# Output: Summarize the following article in 3 sentences.
# Focus on: financial impact. ...

Ativando uma versão

Apenas uma versão de um prompt deve estar ativa por vez em produção. A ativação deve ser atômica: desative a versão atual e ative a nova — tudo em uma única transação, para evitar lacunas.

def activate_version(self, prompt_id, version):
    with self.conn.cursor() as cur:
        # Deactivate all current versions
        cur.execute(
            'UPDATE prompt_versions SET is_active=FALSE '
            'WHERE prompt_id=%s AND is_active=TRUE',
            (prompt_id,)
        )
        # Activate target version
        cur.execute(
            'UPDATE prompt_versions SET is_active=TRUE '
            'WHERE prompt_id=%s AND version=%s',
            (prompt_id, version)
        )
        if cur.rowcount == 0:
            self.conn.rollback()
            raise ValueError(f'Version {version} not found for {prompt_id}')
    self.conn.commit()
    print(f'Activated {prompt_id}@{version}')

Listando e pesquisando prompts

Um registro só é útil se for possível descobrir seu conteúdo. Ofereça pesquisa por etiquetas e a possibilidade de listar todas as versões de um determinado prompt.

def list_versions(self, prompt_id):
    with self.conn.cursor() as cur:
        cur.execute(
            'SELECT version, author, is_active, created_at '
            'FROM prompt_versions WHERE prompt_id=%s '
            'ORDER BY created_at DESC',
            (prompt_id,)
        )
        return cur.fetchall()

def search_by_tag(self, tag):
    with self.conn.cursor() as cur:
        cur.execute(
            'SELECT prompt_id, version, tags FROM prompt_versions '
            'WHERE %s = ANY(tags)',
            (tag,)
        )
        return cur.fetchall()

# Usage
for v in registry.list_versions('summarize-article'):
    print(v)  # ('1.1.0', 'alice', True, datetime(...))

for p in registry.search_by_tag('production'):
    print(p)  # ('summarize-article', '1.1.0', ['production', 'summarization'])

Pontos de acesso da API do registro

Exponha o registro como uma API REST para que todos os serviços (back-end, fluxos de ML e ferramentas de avaliação) compartilhem a mesma fonte de verdade. Principais pontos de acesso:

  • POST /prompts/{id}/versions — registrar uma nova versão
  • GET /prompts/{id}/active — obter o modelo ativo
  • PUT /prompts/{id}/activate/{version} — ativar uma versão
  • GET /prompts — listar todos os prompts com metadados
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()
registry = PromptRegistry(dsn='postgresql://user:pass@localhost/prompts')

class VersionPayload(BaseModel):
    version: str
    template: str
    author: str
    tags: list
    model: str

@app.post('/prompts/{prompt_id}/versions')
def register_version(prompt_id: str, payload: VersionPayload):
    registry.register(
        prompt_id, payload.version, payload.template,
        payload.author, payload.tags, payload.model
    )
    return {'status': 'registered'}

@app.get('/prompts/{prompt_id}/active')
def get_active(prompt_id: str):
    try:
        return registry.get_active(prompt_id)
    except ValueError as e:
        raise HTTPException(404, str(e))

@app.put('/prompts/{prompt_id}/activate/{version}')
def activate(prompt_id: str, version: str):
    registry.activate_version(prompt_id, version)
    return {'status': 'activated'}

Registro de auditoria e histórico de alterações

Cada evento de ativação, desativação e registro deve ser armazenado com data e hora e com o responsável pela ação. Essa trilha de auditoria é essencial para depurar incidentes em produção e atender aos requisitos de conformidade.

CREATE TABLE prompt_audit_log (
  id          SERIAL PRIMARY KEY,
  prompt_id   VARCHAR(100),
  version     VARCHAR(20),
  action      VARCHAR(50),  -- 'registered', 'activated', 'deactivated'
  actor       VARCHAR(100), -- user or service that performed the action
  reason      TEXT,
  created_at  TIMESTAMP DEFAULT NOW()
);

-- Trigger to auto-log activations
CREATE OR REPLACE FUNCTION log_activation()
RETURNS TRIGGER AS $func$
BEGIN
  IF NEW.is_active != OLD.is_active THEN
    INSERT INTO prompt_audit_log (prompt_id, version, action)
    VALUES (NEW.prompt_id, NEW.version,
            CASE WHEN NEW.is_active THEN 'activated' ELSE 'deactivated' END);
  END IF;
  RETURN NEW;
END;
$func$ LANGUAGE plpgsql;

CREATE TRIGGER trg_activation
AFTER UPDATE ON prompt_versions
FOR EACH ROW EXECUTE FUNCTION log_activation();

Verificação rápida

Em um esquema de banco de dados de um registro de prompts, qual campo garante que apenas uma versão de um prompt seja disponibilizada em produção a qualquer momento?

Resumo da arquitetura do registro

Um registro de prompts centraliza o gerenciamento de prompts ao tratá-los como artefatos versionados. Principais decisões de projeto:

  • Separar a tabela de identidade (identificador do prompt) da tabela de versões (versão, modelo e metadados)
  • Um único sinalizador is_active, com trocas atômicas, evita erros causados por duas versões ativas
  • Metadados detalhados (autor, etiquetas, modelo e registro de alterações) facilitam a descoberta e a auditoria
  • A camada da API REST torna o registro acessível a todos os serviços
  • O registro de auditoria oferece suporte à conformidade e à depuração de incidentes

Registros baseados em arquivos funcionam para equipes pequenas; registros respaldados por banco de dados são preferíveis para sistemas de produção de alta disponibilidade usados por várias equipes.

Perguntas Frequentes

A aula “Arquitetura de registro de prompts” é grátis?

Sim — o texto completo de “Arquitetura de registro de prompts” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Prompt Engineering, atualize para CoddyKit PRO. O curso de AI Prompt Engineering inclui 4 aulas no total.

O que vou aprender em “Arquitetura de registro de prompts”?

Armazenamento de prompts como artefatos versionados, com metadados e etiquetas. Você pratica AI Prompt Engineering com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar AI Prompt Engineering?

Nenhuma experiência prévia é necessária. AI Prompt Engineering no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “Arquitetura de registro de prompts”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de AI Prompt Engineering?

Sim. Cada aula de AI Prompt Engineering inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

  1. Arquitetura de registro de prompts
  2. Controle de versões para prompts
  3. Estratégias de implantação e reversão
  4. Monitorando o desempenho dos prompts em produção
← Voltar para AI Prompt Engineering