Como empezar con langfuse: guía práctica para llevar LLMs a producción
Tiempo estimado de lectura: 5 min
- Instrumentar primero: arrancar con trazas por token, spans y versionado de prompts para entender coste y fallos.
- Despliegue según necesidad: cloud para PoC rápido, self-hosted para cumplimiento y control de datos.
- Integración mínima: usar @observe o CallbackHandler en LangChain para trazabilidad sin reescribir la app.
- Métricas desde el día 1: coste por trace, latencia p95, tokens por prompt y tasa de fallos.
Como empezar con langfuse es la primera pregunta que hace cualquier equipo cuando la prueba de concepto con un LLM deja de ser un hobby y empieza a costar dinero. Si quieres dejar de adivinar por qué un prompt alucina, cuánto te cuesta cada conversación o dónde se cuelga tu pipeline RAG, Langfuse es la herramienta que necesitas instrumentar primero.
En las próximas secciones verás pasos concretos, ejemplos de código y criterios técnicos para decidir despliegue, métricas a monitorear y cómo integrar Langfuse con LangChain. Documentación oficial — repositorio — cloud
Resumen rápido (lectores con prisa)
Qué es: plataforma de observabilidad para aplicaciones LLM que captura generaciones, spans, versionado de prompts y datasets de evaluación.
Cuándo usarlo: cuando necesitas coste por usuario/prompt, reproducibilidad y trazas jerárquicas.
Por qué importa: permite decidir modelo/prompt/retriever basándose en métricas reales.
Cómo funciona: instrumentas SDK o CallbackHandler y obtienes traces con spans, tokens y costes.
¿Qué hace Langfuse y por qué importa?
Langfuse es una plataforma de observabilidad y gestión para aplicaciones LLM. No es solo trazas: captura generaciones (tokens, coste), spans (retrieval, postprocessing), versionado de prompts y datasets de evaluación. Eso significa dos cosas:
- Puedes detectar coste por usuario, por prompt y por modelo.
- Puedes depurar cadenas complejas (retriever → LLM → herramientas) con trazas jerárquicas.
Si pagas por token y dependes de resultados reproducibles, no es opcional.
Paso 1 — Elegir despliegue: Cloud vs Self-hosted
Cloud (rápido): Regístrate en cloud.langfuse.com, crea un proyecto y copia PUBLIC_KEY / SECRET_KEY. Ideal para PoC y equipos que quieren empezar en horas.
Self-hosted (compliance): Clona github.com/langfuse/langfuse y levanta con Docker Compose si necesitas controlar datos y cumplir regulaciones.
Ejemplo mínimo: docker-compose
services:
langfuse:
image: ghcr.io/langfuse/langfuse
ports: ["3000:3000"]
environment:
DATABASE_URL: postgresql://user:pass@db:5432/langfuse
NEXTAUTH_SECRET: your-secretPaso 2 — SDK e instrumentación básica
Instala el SDK (elige tu stack):
- Python:
pip install langfuse - Node.js:
npm install langfuse
Variables de entorno mínimas:
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.com
OPENAI_API_KEY=sk-...Instrumentación rápida en Python
from langfuse.decorators import observe
from langfuse.openai import openai
@observe()
def answer_user(query: str):
res = openai.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role":"user","content":query}],
name="answer-v1"
)
return res.choices[0].message.contentResultado: una Trace en el dashboard con spans y generación (tokens, coste, parámetros).
Paso 3 — Integración con LangChain y orquestadores
Si usas LangChain o LlamaIndex, no decoras todo: añades un CallbackHandler.
from langfuse.callback import CallbackHandler
from langchain.chains import LLMChain
from langchain_openai import OpenAI
from langchain.prompts import PromptTemplate
handler = CallbackHandler()
llm = OpenAI()
prompt = PromptTemplate.from_template("Resume: {text}")
chain = LLMChain(llm=llm, prompt=prompt)
result = chain.run("Documento grande...", callbacks=[handler])Langfuse trazará retrievals, llamadas a LLM y pasos intermedios, con breakdown de latencia.
Paso 4 — Prompt Registry y control de cambios
No hardcodees prompts. Usa el Prompt Registry para versionado y A/B:
- Crea prompt en el dashboard:
summarizer-v1. - En código pide la versión “production” y compila variables.
- Cambia el prompt desde UI sin redeploy.
from langfuse import Langfuse
lf = Langfuse()
prompt = lf.get_prompt("summarizer-v1")
compiled = prompt.compile(text="texto largo")Métricas y alertas que debes configurar desde el día 1
- Coste por trace y coste por usuario (alerta si crece >20%).
- Latencia p95 (alerta si >2s en >5% traces).
- Tokens input por prompt (detecta drift del prompt).
- Rate de fallos/completions incompletos.
Estas métricas convierten intuición en decisiones: cambiar a modelo más barato, optimizar retriever o ajustar tiempo de espera.
Buenas prácticas operativas
- Empieza por instrumentar solo 3 endpoints críticos (hot-paths).
- Mantén modo solo-lectura primero (trazas, sin escrituras al modelo).
- Añade guardrails para escrituras: simulación y aprobaciones manuales.
- Versiona eventos y prompts; añade pruebas automáticas contra datasets (Langfuse Datasets).
Limitaciones y costes
- Curva inicial: entender Trace/Span toma horas.
- Coste cloud: gratuito en niveles bajos; luego pago por traces. Revisa precios en cloud.langfuse.com.
- Ecosistema joven: integra pruebas y rollbacks para evitar dependencias fuertes en early-stage.
Checklist de lanzamiento (lista corta)
- Levantar proyecto en cloud o self-host.
- Instrumentar 3 funciones LLM con @observe o CallbackHandler.
- Crear 2 prompts versionados y un dataset de evaluación.
- Configurar alertas: coste diario, latencia p95, tokens.
- Medir 2 semanas, optimizar prompts/modelos/retriever.
Conclusión — empezar y aprender rápido
Como empezar con langfuse no es un ritual largo: en horas puedes tener trazas reales y en días tomar decisiones de coste y calidad. Lo que cambia es la disciplina: medir antes de optimizar. Haz la primera integración hoy, monitorea 100 traces y actúa sobre los tres mayores consumidores de tokens — esa es la ingeniería que realmente reduce coste y riesgo. Esto no acaba aquí: instrumenta, compara y deja que los datos guíen las siguientes iteraciones.
Si trabajas en flujos de automatización o sistemas que combinan agentes y workflows, es útil complementar la instrumentación con prácticas de operación y experimentación. Para recursos y experimentos prácticos adicionales considera Dominicode Labs como continuación lógica de pruebas y validación en pipelines de IA.
FAQ
- ¿Qué es Langfuse?
- ¿Cuándo debo usar cloud vs self-hosted?
- ¿Cómo integro Langfuse en un proyecto existente?
- ¿Qué métricas son esenciales desde el inicio?
- ¿Puedo versionar prompts sin redeploy?
- ¿Cuál es el coste típico de usar Langfuse?
- ¿Funciona con LangChain y otros orquestadores?
¿Qué es Langfuse?
Langfuse es una plataforma de observabilidad para aplicaciones LLM que captura generaciones, spans, versionado de prompts y datasets de evaluación.
¿Cuándo debo usar cloud vs self-hosted?
Usa cloud para PoC y despliegues rápidos. Elige self-hosted si necesitas control de datos, cumplimiento o auditoría completa.
¿Cómo integro Langfuse en un proyecto existente?
Puedes instrumentar funciones clave con @observe en Python o añadir un CallbackHandler en LangChain para trazabilidad sin reescribir toda la app.
¿Qué métricas son esenciales desde el inicio?
Coste por trace/usuario, latencia p95, tokens por prompt y tasa de fallos. Configura alertas para cambios significativos.
¿Puedo versionar prompts sin redeploy?
Sí. Usa el Prompt Registry en el dashboard para versionado y A/B; compila la versión desde el SDK en tiempo de ejecución.
¿Cuál es el coste típico de usar Langfuse?
Hay niveles gratuitos bajos y luego pago por traces en cloud. Revisa precios y modelos en cloud.langfuse.com.
¿Funciona con LangChain y otros orquestadores?
Sí. Langfuse proporciona CallbackHandler para LangChain y puede trazar retrievals, llamadas LLM y pasos intermedios.
