langfuse

Langfuse LLM 可观测性

补充说明

Langfuse 是开源的 LLM 可观测性平台，记录 trace、span、generation、prompt 版本、评分和成本。适合排查 RAG/Agent 的延迟、token 消耗和回答质量。

核心概念：trace、observation、prompt、dataset、score 和 session。

常用示例

Docker Compose 启动：

git clone https://github.com/langfuse/langfuse.git
cd langfuse
docker compose up -d

配置环境变量：

export LANGFUSE_PUBLIC_KEY=pk-lf-***
export LANGFUSE_SECRET_KEY=sk-lf-***
export LANGFUSE_HOST=http://localhost:3000

Python SDK：

from langfuse import Langfuse
langfuse = Langfuse()

trace = langfuse.trace(name="rag-query", input={"q": "磁盘满"})
span = trace.span(name="retrieval")
span.end(output={"docs": 4})
generation = trace.generation(
    name="answer",
    model="qwen2.5-7b",
    input=[{"role": "user", "content": "磁盘满"}],
    output="先看 df -h",
)
langfuse.flush()

评分：

trace.score(name="helpful", value=1, comment="回答准确")

易错点与排错

• 环境变量没有设置，SDK 静默丢弃事件。
• 没有调用 flush()，进程退出前数据未上报。
• 自建实例的 LANGFUSE_HOST 指向错误端口。
• 高频 trace 产生大量数据，按采样率采集。
• Prompt 中包含敏感信息，先脱敏再上报。
• 版本升级后数据库迁移失败，先备份 PostgreSQL。
• 多租户场景没有隔离 project，数据互相可见。
• 只记录输入输出，没有记录检索文档和 token 成本，排障信息不足。