Cómo Construir una API REST para Gestionar Prompts con FastAPI y PostgreSQL

promptstack-backend: Arquitectura moderna para gestionar prompts en aplicaciones de IA generativa

En los últimos años, la explosión de modelos generativos ha traído consigo la necesidad de gestionar y reutilizar prompts de manera eficiente. Cuando trabajo en proyectos de IA, me he encontrado una y otra vez con la misma problemática: ¿cómo centralizar, versionar y consultar prompts para distintos modelos y contextos? Así nació promptstack-backend, una API RESTful escalable y fácil de desplegar, pensada para integrarse en pipelines de desarrollo de IA generativa.

En este post detallo el porqué detrás de este proyecto, la arquitectura técnica, los retos que enfrenté y algunas lecciones aprendidas. Además, comparto snippets y reflexiones sobre decisiones clave. Si estás pensando en construir una infraestructura robusta para gestionar prompts, este post es para ti.

¿Por qué era necesario promptstack-backend?

A medida que los equipos de IA crecen y se diversifican, la gestión de prompts se vuelve un cuello de botella:

• Los prompts suelen estar dispersos entre notebooks, archivos de texto y código fuente.
• No hay control de versiones ni trazabilidad de cambios.
• Reutilizar prompts entre proyectos se vuelve tedioso.
• Es difícil automatizar flujos de trabajo que dependan de prompts dinámicos.

Quería una solución que permitiera:

• Centralizar prompts en una base de datos robusta.
• Consultar, versionar y actualizar prompts vía una API RESTful.
• Integrarse fácilmente con aplicaciones web, pipelines de ML o scripts.
• Ser fácil de desplegar (¡nada de dependencias manuales ni instalaciones eternas!).

Así nació promptstack-backend (repositorio privado): una API moderna, documentada y con despliegue simplificado vía Docker.

Arquitectura general y decisiones de diseño

Quería una arquitectura que fuera:

• Escalable: soportar muchos prompts y consultas concurrentes.
• Fácil de mantener: tecnologías modernas, tipadas y con buen soporte.
• Desplegable en cualquier entorno: local, cloud, CI/CD.

Stack tecnológico seleccionado

• FastAPI: framework web asíncrono en Python, ideal para APIs RESTful rápidas y con OpenAPI de serie.
• PostgreSQL: base de datos relacional robusta, perfecta para queries complejas y consistencia.
• Prisma ORM: un ORM moderno y tipado, con excelente experiencia de desarrollo (aunque menos común en Python, lo adopté por su eficiencia y modelo declarativo).
• Docker + Docker Compose: para aislar dependencias y facilitar el despliegue en cualquier entorno.

¿Por qué FastAPI?

FastAPI ha revolucionado el desarrollo de APIs en Python:

• Es asíncrono (ideal para concurrencia y rendimiento).
• Genera documentación OpenAPI automáticamente (Swagger UI, Redoc).
• Integra Pydantic para validación y serialización de datos.
• Excelente performance y comunidad activa.

¿Por qué Prisma ORM?

Aunque Prisma es más conocido en el ecosistema Node.js, su versión para Python me permitió:

• Declarar el esquema de la base de datos en un solo archivo.
• Migraciones automáticas y reversibles.
• Generación de tipados y modelos, lo que reduce bugs y acelera el desarrollo.

¿Por qué Docker Compose?

• Permite levantar tanto la API como la base de datos con un solo comando.
• Facilita la replicación de entornos (dev, staging, prod).
• Simplifica el onboarding de nuevos developers.

Componentes principales del sistema

El backend se compone de varios módulos:

1. Modelo de datos (Prisma + PostgreSQL)
2. API REST (FastAPI)
3. Gestión de autenticación y CORS
4. Scripts y utilidades para despliegue y testing

1. Modelo de datos

El corazón es el modelo de Prompt, que incluye:

• id: UUID único para trazabilidad.
• content: el texto del prompt.
• tags: lista de etiquetas para categorizar.
• model_type: para asociar a diferentes motores (GPT-3, Llama, etc.).
• created_at / updated_at: timestamps para auditar cambios.
• version: control de versiones para evolucionar prompts sin perder historial.

Ejemplo de modelo en Prisma:

1model Prompt {
2  id         String   @id @default(uuid())
3  content    String
4  tags       String[]
5  modelType  String
6  version    Int      @default(1)
7  createdAt  DateTime @default(now())
8  updatedAt  DateTime @updatedAt
9}

Esta estructura permite queries complejas como: "dame todos los prompts para GPT-4 con la etiqueta 'summarization' y versión > 2".

2. API REST

Con FastAPI, cada endpoint está bien tipado y documentado. Los endpoints principales incluyen:

• GET /prompts: listar prompts (con filtros por modelo, tags, versión).
• POST /prompts: crear un nuevo prompt.
• PUT /prompts/{id}: actualizar prompt existente.
• DELETE /prompts/{id}: eliminar prompt.
• GET /prompts/{id}: consultar prompt por ID.

Snippet de endpoint de creación:

1from fastapi import APIRouter, HTTPException
2from app.schemas import PromptCreate, PromptOut
3from app.db import prisma
4 
5@router.post("/prompts", response_model=PromptOut)
6async def create_prompt(prompt: PromptCreate):
7    try:
8        prompt_db = await prisma.prompt.create(
9            data=prompt.dict()
10        )
11        return prompt_db
12    except Exception as e:
13        raise HTTPException(status_code=400, detail=str(e))

La integración con Pydantic v2 asegura que la validación y la serialización sean robustas y performantes.

3. Autenticación y CORS

• CORS: configurable vía variable de entorno API_API_CORS_ORIGINS. Esto permite restringir el acceso solo a frontends específicos.
• Cabeceras de desarrollo: con API_ALLOW_DEV_HEADERS es posible habilitar autenticación simplificada en local/staging.
• En próximas versiones, planeo añadir OAuth2/JWT para entornos productivos.

4. Dockerización y despliegue

Un único docker-compose.yml orquesta:

• La base de datos PostgreSQL (con persistencia en volúmenes).
• El backend FastAPI (auto-reload en dev, producción con Uvicorn).
• Variables de entorno parametrizables (DB URL, CORS, modo dev, etc.).

Fragmento de Dockerfile:

1FROM python:3.11
2 
3WORKDIR /app
4COPY requirements.txt .
5RUN pip install -r requirements.txt
6 
7COPY . .
8CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Esto permite levantar todo el stack con:

1docker compose up --build -d

Retos técnicos y cómo los resolví

1. Integración de Prisma con Python

Prisma está menos maduro en Python que en Node.js, y la documentación puede ser limitada. Para garantizar estabilidad:

• Usé prisma-client-py, revisando issues abiertos y ejemplos reales.
• Automatizé la regeneración del cliente Prisma en el pipeline de build.
• Añadí tests básicos para los endpoints más críticos.

2. Versionado de prompts

No basta con sobrescribir el prompt; era crucial mantener versiones:

• Añadí un campo version y lógica para soft-updates: cada edición relevante crea una nueva versión, preservando el historial.
• Implementé endpoints para consultar el historial de un prompt.

3. Performance y concurrencia

• FastAPI con Uvicorn brinda excelente rendimiento asíncrono.
• Configuré PostgreSQL para aceptar múltiples conexiones concurrentes.
• Añadí índices en campos clave (modelType, tags) para acelerar búsquedas.

4. Experiencia de desarrollador y despliegue

• El objetivo era que cualquier developer pueda tener todo funcionando en 5 minutos: sólo git clone y docker compose up.
• Documenté bien los comandos para conectar a la base de datos, reiniciar el entorno y depurar errores.

Métricas y resultados

Aunque el proyecto está aún en early adopters, los primeros resultados son positivos:

• Tiempo de onboarding: menos de 10 minutos para developers nuevos.
• Consultas típicas: <100ms para búsquedas complejas gracias a la indexación.
• Despliegue reproducible: el stack se levanta igual en local y en cloud.
• Extensibilidad: fácil de añadir nuevos modelos de datos (por ejemplo, historial de uso de prompts).

Lecciones aprendidas y mejoras futuras

Lecciones

• Prisma en Python es usable, pero hay que estar atento a breaking changes y bugs menores.
• La documentación clara (README, ejemplos de comandos) es indispensable.
• Docker Compose facilita muchísimo la vida, pero hay que controlar bien los volúmenes y variables de entorno.

Mejoras futuras

• Añadir autenticación robusta (OAuth2/JWT).
• Endpoint para importar/exportar prompts en bulk (YAML, JSON).
• Mejorar la gestión de versiones (ramificación, comparación de versiones).
• Añadir métricas de uso por prompt (para priorizar mejoras).
• Frontend web/admin para gestionar la biblioteca de prompts visualmente.

Conclusión

Construir promptstack-backend me permitió experimentar con tecnologías modernas y resolver un problema real en el flujo de desarrollo de IA generativa. Me siento satisfecho con la arquitectura lograda: es modular, escalable y fácil de usar. Si quieres centralizar y versionar tus prompts, este proyecto demuestra una arquitectura sólida para lograrlo. 🚀

¿Tienes dudas técnicas o quieres compartir tu experiencia con la gestión de prompts? ¡Déjame un comentario o abre un Issue en el repo!

Javier Santos Criado – Ingeniero de inteligencia artificial apasionado por la tecnología y la automatización de flujos de trabajo complejos.