Saltar a contenido

Backend en local

Guía paso a paso para levantar el backend de Camarero IA en tu máquina: entorno virtual de Python, base de datos PostgreSQL en un contenedor, variables de entorno y arranque de uvicorn.

Qué vas a conseguir

Un servidor FastAPI escuchando en http://localhost:8000, conectado a una BD PostgreSQL local y a un LLM servido por un proxy OpenAI-compatible.

Requisitos previos

  • Python 3.12
  • podman (o docker) para la base de datos
  • Un proxy LLM OpenAI-compatible escuchando en http://localhost:4800/v1 (ver LLM local vía proxy)

Todos los comandos asumen que tu directorio de trabajo es backend/ (la raíz del backend), salvo que se indique lo contrario.

1. Entorno virtual (venv)

El repo espera un venv/ en la raíz del backend (lo usan el Makefile y los comandos de arranque).

python3.12 -m venv venv
venv/bin/pip install --upgrade pip
venv/bin/pip install -r requirements.txt

Tip

No es necesario activar el venv: los comandos de esta guía invocan los binarios directamente con venv/bin/....

2. Base de datos PostgreSQL

El backend usa PostgreSQL tanto en local como en producción (driver asyncpg). No uses la CLI de sqlite3 para inspeccionar datos.

Levanta un contenedor postgres:15 con las credenciales que espera la configuración por defecto:

podman run -d \
  --name camarero-test-db \
  -e POSTGRES_USER=camarero_user \
  -e POSTGRES_PASSWORD=camarero_password \
  -e POSTGRES_DB=camarero_db \
  -p 5432:5432 \
  docker.io/postgres:15-alpine
Parámetro Valor
Contenedor camarero-test-db
Imagen postgres:15-alpine
Host / puerto localhost:5432
Usuario camarero_user
Contraseña camarero_password
Base de datos camarero_db

Estos valores coinciden con el DATABASE_URL por defecto de backend/.env.example:

DATABASE_URL=postgresql+asyncpg://camarero_user:camarero_password@localhost:5432/camarero_db

Parar y reiniciar

Para detener el contenedor: podman stop camarero-test-db. Para volver a arrancarlo sin recrearlo: podman start camarero-test-db.

3. Variables de entorno

La configuración se carga desde .env y .env.local (ver app/core/config.py). Crea tu .env a partir del ejemplo:

cp .env.example .env

Edita los valores que necesites. Campos relevantes para desarrollo local:

Variable Para qué sirve
DATABASE_URL Conexión a PostgreSQL (ver tabla anterior).
NVIDIA_API_KEY Clave del proveedor LLM (el proxy local no la valida, ver abajo).
NVIDIA_BASE_URL URL base del LLM OpenAI-compatible.
NVIDIA_MODEL Modelo a usar.
AI_STREAM_TIMEOUT_SECONDS Segundos máximos que el caso de uso espera el primer frame de la IA.
EMBEDDINGS_ENABLED Activa los embeddings (clasificador de intents y recomendador).

Embeddings y descarga del modelo

Con EMBEDDINGS_ENABLED=true se carga el modelo de embeddings en proceso (descarga la primera vez). En tests se fija siempre EMBEDDINGS_ENABLED=false para no descargar el modelo.

4. LLM local vía proxy

El LLM local se sirve a través de un proxy OpenAI-compatible en http://localhost:4800/v1. La integración del backend habla el dialecto NVIDIA NIM (variables con prefijo NVIDIA_), por lo que el proxy se configura apuntando esas variables a la URL local.

  • Base URL: http://localhost:4800/v1
  • Modelo: opencode/deepseek-v4-flash-free
  • Thinking: desactivado
  • API key: no la valida el proxy local (cualquier valor sirve; se usa KAKAKAKA como placeholder)

El proxy debe estar corriendo antes de arrancar

El chat necesita el proxy en :4800. Asegúrate de tenerlo levantado, o las llamadas a la IA fallarán por timeout.

5. Arrancar uvicorn

Comando que funciona, con todas las variables del LLM local en línea (desde backend/):

NVIDIA_API_KEY=KAKAKAKA \
NVIDIA_BASE_URL=http://localhost:4800/v1 \
NVIDIA_MODEL=opencode/deepseek-v4-flash-free \
AI_STREAM_TIMEOUT_SECONDS=120 \
EMBEDDINGS_ENABLED=true \
PYTHONPATH=. \
venv/bin/python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

Con esto el backend queda escuchando en http://localhost:8000.

Por qué PYTHONPATH=.

Fija la raíz del backend como ruta de importación para que app.main:app se resuelva al ejecutar uvicorn como módulo.

Alternativa: docker-compose vía scripts/dev.sh

Para levantar el entorno completo (BD + backend con recarga en vivo) con un solo comando, usa el script scripts/dev.sh desde la raíz del repo:

scripts/dev.sh

El script:

  • Verifica que exista backend/.env; si no, copia backend/.env.example y te pide editarlo antes de continuar.
  • Para los contenedores que pudieran estar corriendo.
  • Construye y arranca backend/docker-compose.dev.yml con docker compose ... up --build (acepta argumentos extra que se pasan a up).

Warning

scripts/dev.sh usa docker compose. Si trabajas con podman, te resultará más directo el arranque manual de uvicorn descrito arriba junto con el contenedor camarero-test-db.

Comprobaciones de arquitectura (opcional)

El backend/Makefile expone gates de arquitectura que usan el venv/:

make lint-arch    # contratos de import (import-linter, ADR-004)
make typecheck    # mypy sobre app/modules + app/shared

Note

make lint-arch y pytest tests/contract/ son los gates duros en CI. El baseline de mypy puede salir en rojo por errores preexistentes; no bloquea localmente.