Langfuse: observar tus LLM locales (trazas, prompts, evaluaciones)

#¿Por qué observar un LLM local?

Langfuse es una plataforma de observabilidad para aplicaciones LLM, cuyo repositorio principal está bajo licencia MIT, que puedes alojar en tu propia infraestructura para que las trazas de tus conversaciones permanezcan en ella. Registra, para cada solicitud, el prompt realmente enviado al modelo, la respuesta, la duración de cada etapa y, si se define un precio, el coste. Sirve para saber por qué una respuesta es mala: un fragmento recuperado que no viene al caso, un prompt distinto del que creías o un fallo del modelo. Resulta útil en cuanto una segunda persona depende del resultado o la cadena tiene varias etapas; para un uso exploratorio en solitario, basta con un archivo de registro. Cuenta con una pila de varios contenedores (servidor web, worker, PostgreSQL, ClickHouse, Redis, almacenamiento de objetos) y, para producción, con Kubernetes en lugar de Docker Compose.

Cuando una respuesta decepciona, tres causas son posibles y solo una es visible sin instrumentación: el prompt final enviado al modelo no era el que creías, los pasajes recuperados por la búsqueda documental eran irrelevantes, o el modelo en sí mismo falló. Sin registro, se cambia el prompt al azar hasta que mejora, sin nunca saber por qué.

El argumento es el mismo en local que en línea, con una diferencia: la factura ya no es el indicador que te avisa. Nadie recibe un extracto de consumo cuando una cadena de agentes entra en bucle en tu propia tarjeta gráfica; la latencia y el calor son los que lo indican. La observabilidad sustituye esta señal de precio por mediciones: número de tokens, duración, tasa de fallos y calidad.

#Lo que registra Langfuse

El proyecto se presenta como una plataforma open source de evaluación de agentes y observabilidad: rastrear, evaluar y mejorar aplicaciones LLM en una sola plataforma abierta. Sus SDK en Python (versión 4) y JS/TS (versión 5) se basan en OpenTelemetry, y otros lenguajes pueden enviar sus trazas mediante este protocolo. El repositorio principal supera las 35.000 estrellas en GitHub. Su README indica que Langfuse forma parte de ClickHouse desde enero de 2026, y ClickHouse también es la base que almacena las trazas.

Trazas

El recorrido completo de una solicitud de usuario: cada paso, en orden, con su duración. Es la unidad básica.

Observaciones

Dentro de una traza: las llamadas al modelo con su prompt exacto y su respuesta, las etapas de recuperación documental y las llamadas a herramientas.

Sesiones y usuarios

El agrupamiento de las trazas por conversación y por persona, para seguir un recorrido en lugar de una llamada aislada.

Puntuaciones

Una nota adjunta a una traza: pulgar arriba de un usuario, resultado de una evaluación automática, anotación manual.

Prompts

Las plantillas de prompt, con control de versiones, que la aplicación recupera durante la ejecución en lugar de estar codificadas directamente en el código.

Costos

Langfuse calcula un coste a partir de una definición de modelo que asocia un precio a cada tipo de uso. Proporciona estas definiciones para modelos de OpenAI, Anthropic y Google. Para un modelo local, no existe ningún precio hasta que lo añadas: sin una definición, no busques un coste en la interfaz, o define un precio ficticio para reflejar la electricidad y la amortización.

#Instalarlo en casa

Langfuse se puede alojar en tu propia infraestructura con Docker Compose. El README anuncia una puesta en marcha en cinco minutos; la documentación de despliegue indica que pasan entre dos y tres minutos hasta que el contenedor web muestra «Ready». La pila no se limita a un contenedor: incluye dos contenedores de aplicaciones (el servidor web, que sirve la interfaz y la API, y un worker que procesa los eventos de forma asíncrona) y cuatro componentes de almacenamiento: PostgreSQL para los datos transaccionales, ClickHouse para las trazas, observaciones y puntuaciones, Redis o Valkey para la cola y la caché, y un almacenamiento de objetos compatible con S3 que conserva todos los eventos entrantes. Es más pesado que un simple panel de control, y es consecuencia de lo que se le pide: ingerir muchos eventos sin perder ninguna traza, incluso si la base de datos no está disponible temporalmente.

Dos limitaciones que debes conocer antes de instalarlo junto a un modelo. Primero, la documentación dice que Docker Compose sirve para hacer pruebas: esta configuración no ofrece alta disponibilidad, escalabilidad ni copias de seguridad, y para producción recomienda Kubernetes con Helm. Segundo, para una máquina virtual, recomienda al menos 4 núcleos, 16 GiB de memoria y 100 GiB de almacenamiento. En un equipo que ya sirve un modelo, estas magnitudes importan: una pila de observabilidad que consume parte de la memoria del modelo lo hace en el peor momento. Por último, cambia los secretos del archivo docker-compose.yml, marcados CHANGEME: no existe una cuenta predeterminada; el primer usuario se crea pulsando el botón Sign up en http://localhost:3000.

git clone --depth=1 https://github.com/langfuse/langfuse.git
cd langfuse
# Éditer docker-compose.yml : remplacer chaque secret marqué CHANGEME
docker compose up
# Après 2 à 3 minutes, le conteneur web affiche « Ready » : ouvrir http://localhost:3000

#Conectarlo a Ollama o vLLM

Langfuse no es un servidor de inferencia y no se intercala en el tráfico: es tu aplicación la que le envía las trazas. El proyecto documenta tres caminos concretos según la forma en que llamas a tu modelo, y una página dedicada a Ollama, cuyo ejemplo utiliza el SDK OpenAI: Ollama expone una API compatible con OpenAI en la dirección http://localhost:11434/v1, y Langfuse proporciona un reemplazo directo de este SDK, que solo requiere cambiar el import. También existe una página para vLLM.

1. 01
   A través del SDK, en tu código

   Decoras las funciones que llaman al modelo. Es el método más explícito y fiel, ya que eliges lo que se registra.
2. 02
   Mediante la integración con un framework

   Existe instrumentación automatizada mediante un reemplazo directo del SDK de OpenAI, un gestor de callbacks conectado a una aplicación LangChain y el sistema de callbacks de LlamaIndex: las trazas se recopilan sin modificar la lógica de negocio.
3. 03
   A través de una pasarela de API

   Si tus llamadas ya pasan por un router compatible con OpenAI, la instrumentación se realiza en ese nivel y cubre todas las aplicaciones a la vez.

En los tres casos, el punto a verificar es que el prompt realmente transmitido se registre, y no solo la pregunta del usuario: es precisamente la diferencia entre los dos lo que explica la mayoría de las respuestas incorrectas de un sistema de búsqueda documental. Con Ollama, la configuración a continuación apunta LANGFUSE_BASE_URL a tu instancia auto-hospedada (http://localhost:3000) y declara tus claves pública y secreta en variables de entorno.

# pip install langfuse openai
# Variables d'environnement : LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY,
# LANGFUSE_BASE_URL=http://localhost:3000
from langfuse.openai import OpenAI  # remplace : from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1',
    api_key='ollama',  # requis mais inutilisé
)
reponse = client.chat.completions.create(
    model='llama3.1',
    messages=[{'role': 'user', 'content': 'Bonjour !'}],
)

• Centralizar tus llamadas con una pasarela compatible con OpenAI
• Desplegar vLLM para atender a varios usuarios
• Llamar a Ollama desde Python
• Ragas: evaluar un RAG local con números
• Fuente: detalles de las integraciones de SDK, frameworks y pasarelas

#Gestionar y versionar prompts

Sacar los prompts del código es el primer beneficio que observan los equipos. Según el README, un sistema de caché sólido tanto en el servidor como en el cliente permite iterar sobre los prompts sin añadir latencia a la aplicación. La plantilla reside en Langfuse, la aplicación la recupera durante la ejecución y cada modificación crea una versión. Corregir una formulación ya no requiere volver a desplegar la aplicación y, sobre todo, la traza indica qué versión produjo qué respuesta: cuando la calidad cae tras un cambio, se sabe cuál es el responsable sin tener que cruzar registros de despliegue separados.

#Conjuntos de pruebas y evaluación

Las trazas reales alimentan los conjuntos de pruebas: marcas los casos interesantes —sobre todo los fallos— y se convierten en una colección con la que volver a probar una nueva versión del prompt u otro modelo. Así puedes responder seriamente a «¿basta con el modelo de 14 mil millones de parámetros?» en lugar de limitarte a debatirlo.

Las puntuaciones provienen de varias fuentes: los usuarios, una anotación humana en la interfaz, evaluadores basados en código o un modelo que juzga la respuesta de otro según una rúbrica de evaluación —el método llamado LLM-as-a-judge, que Langfuse ofrece de forma nativa—. En este último caso, es necesario crear una conexión LLM. La documentación indica que cualquier modelo que siga el esquema de la API de OpenAI es válido, reemplazando la URL base: un modelo local servido por Ollama puede actuar como juez, siempre que su dirección sea accesible desde el contenedor de Langfuse. Este método es útil y presenta sesgos: los autores del artículo de referencia sobre el tema (arXiv 2306.05685) describen sesgos de posición, de verbosidad y de preferencia por las propias respuestas, a la vez que registran más del 80 % de acuerdo entre un juez de tipo GPT-4 y las preferencias humanas. Se utiliza para comparar dos versiones, no para otorgar una puntuación absoluta.

Una herramienta dedicada a la evaluación del RAG, como Ragas, complementa a Langfuse en lugar de reemplazarlo: Langfuse captura la traza y almacena la puntuación, mientras que Ragas calcula métricas específicas —fidelidad al contexto, pertinencia de la respuesta— que Langfuse puede mostrar luego como cualquier otro puntaje asociado a una traza.

#Casos de uso concretos

Asistente de soporte con RAG

Una respuesta fuera de tema se puede investigar mediante la traza: ¿el fragmento recuperado era relevante o el modelo ignoró un fragmento correcto? La traza permite distinguir entre las dos hipótesis.

Agente que llama a herramientas

En una cadena de varios pasos —búsqueda, cálculo, redacción—, el registro muestra cuál falló en lugar de indicar un fallo global sin detalles.

Comparación de dos modelos antes de decidir

Volver a ejecutar el mismo conjunto de pruebas con un modelo de 8 mil millones y luego con uno de 27 mil millones de parámetros proporciona una cifra de calidad y una duración, en lugar de una impresión.

Seguimiento de una regresión tras actualización

Un cambio de versión del prompt o del modelo que degrada la calidad se refleja en las puntuaciones agregadas antes de que un usuario se queje.

El punto común a estos casos: ninguno se resuelve releyendo el código. La causa de una mala respuesta se encuentra en los datos que han pasado por el sistema —el prompt exacto, los pasajes recuperados, la respuesta generada—, y esos datos no existen en ningún otro lugar si no se registraron en el momento de la llamada. Esa es la razón para incorporar observabilidad antes de la puesta en servicio, en lugar de hacerlo después del primer incidente.

#Cuánto cuesta y qué no hace

No mejora un modelo

La observabilidad mide, no corrige nada. Te dice dónde buscar.

Almacena tus conversaciones

Aunque sea auto-hospedado, el contenido de los prompts se escribe en disco, y sin política de retención (función de la edición empresarial), los datos se conservan indefinidamente. Los SDK, por otro lado, ofrecen funciones de ocultación (masking) para eliminar los datos sensibles antes de enviar las trazas.

Es una pila que requiere mantenimiento

Copias de seguridad, actualizaciones, migraciones: la propia documentación indica que Docker Compose no ofrece copias de seguridad. Para una experimentación personal, resulta desproporcionado.

A menudo ocurre tarde

El momento adecuado para instalarlo es antes de ponerlo en servicio, no después de la primera falla silenciosa.

• Fuente: repositorio oficial Langfuse en GitHub
• Fuente: repositorio oficial Ragas, para la evaluación de RAG

#FAQ