0Pricing
AI Prompt Engineering · Lección

Arquitectura de un registro de prompts

Almacene los prompts como artefactos versionados con metadatos y etiquetas.

Arquitectura de un registro de prompts es una lección gratuita de AI Prompt Engineering en CoddyKit. Esta es la lección 1 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de AI Prompt Engineering, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de AI Prompt Engineering incluye 4 lecciones en total.

¿Por qué usar un registro de prompts?

Sin un registro, los prompts quedan dispersos entre el código, los archivos de configuración y la memoria de los desarrolladores. Un registro de prompts es un almacén centralizado que trata cada prompt como un artefacto versionado y rastreable, igual que el código de software.

Entre sus beneficios se encuentran la reproducibilidad, la auditabilidad, la capacidad de rollback y la colaboración en equipo.

Campos principales de un artefacto de prompt

Cada artefacto de prompt debe incluir estos campos:

  • prompt_id — identificador único y estable (p. ej., summarize-article)
  • version — cadena de versión semántica (p. ej., 2.1.0)
  • template — el texto real del prompt con marcadores {variable}
  • metadata — autor, etiquetas, modelo objetivo, created_at y descripción

Diseño del esquema de la base de datos

Un esquema relacional para un registro de prompts almacena los prompts y su historial de versiones en tablas separadas, lo que permite realizar consultas y auditorías de forma eficiente.

-- 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)
);

Diseño de un registro basado en archivos

Para equipos pequeños, un registro basado en archivos utiliza una estructura de directorios organizada. Cada prompt tiene una carpeta y cada versión es un archivo YAML o JSON dentro de ella.

# 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}

Clase Python PromptRegistry

Una clase sencilla de Python encapsula el acceso a la base de datos y expone métodos claros: register(), get_active() y 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álisis detallado del esquema de metadatos

Unos metadatos completos hacen que el registro sea útil más allá del simple almacenamiento. Campos de metadatos principales:

  • author — responsabilidad y punto de contacto
  • tags — etiquetas que permiten búsquedas, como ['production', 'summarization', 'v2']
  • model — modelo objetivo (el prompt puede no ser independiente del modelo)
  • changelog — descripción legible de los cambios realizados
  • test_suite — enlace al conjunto de datos de evaluación de este 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
}

Renderizado de plantillas con variables

Las plantillas de prompts utilizan una sintaxis de marcadores. El registro genera el prompt final sustituyendo las variables de ejecución en la plantilla. Usar str.format_map() de Python es seguro y sencillo.

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. ...

Activación de una versión

En producción, solo una versión de un prompt debe estar activa a la vez. La activación debe ser atómica: desactivar la actual y activar la nueva, todo en una única transacción para evitar interrupciones.

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}')

Listado y búsqueda de prompts

Un registro solo es útil si puede descubrir su contenido. Permita búsquedas por etiquetas y listar todas las versiones de un prompt determinado.

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'])

Endpoints de la API del registro

Exponga el registro como una API REST para que todos los servicios (backend, canalizaciones de ML y herramientas de evaluación) compartan la misma fuente de verdad. Endpoints principales:

  • POST /prompts/{id}/versions — registrar una nueva versión
  • GET /prompts/{id}/active — obtener la plantilla activa
  • PUT /prompts/{id}/activate/{version} — activar una versión
  • GET /prompts — listar todos los prompts con sus metadatos
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 auditoría e historial de cambios

Cada evento de activación, desactivación y registro debe anotarse con una marca de tiempo y el actor que lo realizó. Esta traza de auditoría es esencial para depurar incidentes en producción y cumplir los requisitos de conformidad.

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();

Comprobación rápida

En el esquema de una base de datos de registro de prompts, ¿qué campo garantiza que solo se sirva una versión de un prompt en producción en un momento dado?

Resumen de la arquitectura del registro

Un registro de prompts centraliza la gestión de prompts al tratarlos como artefactos versionados. Decisiones de diseño principales:

  • Separar la tabla de identidades (prompt_id) de la tabla de versiones (version, template, metadata)
  • Un único indicador is_active con intercambios atómicos evita errores con dos versiones activas
  • Los metadatos completos (autor, etiquetas, modelo, registro de cambios) facilitan el descubrimiento y la auditoría
  • La capa de API REST hace que el registro sea accesible para todos los servicios
  • El registro de auditoría proporciona soporte para la conformidad y la depuración de incidentes

Los registros basados en archivos funcionan para equipos pequeños; para sistemas de producción con varios equipos y alta disponibilidad se prefieren los registros respaldados por una base de datos.

Preguntas frecuentes

¿La lección «Arquitectura de un registro de prompts» es gratis?

Sí — el texto completo de «Arquitectura de un registro de prompts» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de AI Prompt Engineering, actualiza a CoddyKit PRO. El curso de AI Prompt Engineering incluye 4 lecciones en total.

¿Qué aprenderé en «Arquitectura de un registro de prompts»?

Almacene los prompts como artefactos versionados con metadatos y etiquetas. Practicas AI Prompt Engineering con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar AI Prompt Engineering?

No se requiere experiencia previa. AI Prompt Engineering en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 1 de 4.

¿Cuánto tiempo toma la lección «Arquitectura de un registro de prompts»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de AI Prompt Engineering?

Sí. Cada lección de AI Prompt Engineering incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

  1. Arquitectura de un registro de prompts
  2. Control de versiones para prompts
  3. Estrategias de despliegue y reversión
  4. Monitorización del rendimiento de prompts en producción
← Volver a AI Prompt Engineering