RAG local con FastAPI y Ollama: de una simple llamada a un LLM a un backend de producción

Un desarrollador de Habr analiza un momento concreto: cuando una llamada aislada a un modelo local deja de ser suficiente y qué hay que añadir para obtener un auténtico sistema backend.

Cuando una llamada simple no basta

La primera versión tiene un aspecto evidente: el frontend envía una pregunta, FastAPI recibe `POST /ask`, el backend llama a Ollama y devuelve una cadena con la respuesta. Para una demo es suficiente. Para un asistente de documentación, no.

Las preguntas aparecen enseguida: ¿en qué documentos se apoya la respuesta? ¿Qué fragmentos han llegado al prompt? ¿Por qué una petición se procesa en dos segundos y otra en quince? ¿Qué ocurre si el índice no se ha actualizado en tres semanas? Con una simple llamada a un LLM es imposible responder a ninguna de ellas.

Qué aporta la capa de backend

El autor introduce los componentes uno a uno y explica el problema concreto que resuelve cada uno:

• request_id: identificador único de la petición para correlacionar logs y depurar un fallo concreto
• sources: lista de los fragmentos de documentos que han entrado en el contexto del modelo, con indicación de su origen
• timings: desglose del tiempo por etapas: búsqueda en el índice, construcción del prompt y generación de la respuesta
• rebuild index: un endpoint independiente para reconstruir el índice sin reiniciar el servicio
• negative tests: comprobación del comportamiento con un corpus vacío, preguntas fuera de tema y un índice desactualizado

El stack es completamente local: FastAPI para la capa HTTP, Ollama para la generación y embeddings propios. Sin claves de APIs externas.

El contrato de API como frontera del sistema

Una de las tesis centrales del artículo es la importancia de un contrato explícito en la respuesta. Mientras `/ask` devuelve solo una cadena, el servicio sigue siendo una caja negra. En cuanto la respuesta incluye `request_id`, `sources`, `timings` y el estado del índice, se puede monitorizar, depurar y mejorar.

«No muestro cómo funciona RAG en general, sino el camino que va de una

simple llamada a un LLM local a un pequeño proyecto de backend con contrato de API, logging, sources, timings y limitaciones honestas».

Este enfoque cambia la relación con el servicio: en lugar de «el modelo responde como sea», se pasa a «el sistema se comporta de forma predecible».

Honestidad sobre las limitaciones

El autor enumera de forma explícita lo que el proyecto no incluye: autenticación, caché, soporte para carga multiusuario y CI/CD. Eso hace que el artículo sea más útil que la mayoría de los tutoriales, donde la sección de limitaciones o no existe o se reduce a una frase de compromiso.

Los negative tests merecen mención aparte. Se comprueba el comportamiento con un corpus de documentos vacío, con preguntas sin contenido relevante en el índice y al consultar el índice después de añadir archivos nuevos sin reconstruirlo. Es un conjunto mínimo, pero ya permite entender dónde falla exactamente el sistema.

Qué significa esto

El artículo cubre una laguna concreta: la mayoría de los materiales sobre RAG explican la teoría o muestran un «hello world» con LangChain. Aquí hay un servicio local que funciona, con herramientas de observability, y que se puede tomar como base de un proyecto real.