Langfuse 使用教程：从入门到上手

什么是 Langfuse

Langfuse 是一个开源的 LLM 观测平台，由德国团队开发，主要用来追踪、调试和评估大语言模型应用的运行情况。你可以把它理解成 LLM 版的 Sentry 或 Datadog，但它更专注于 AI 应用的调用链路分析。

它的核心能力包括：Trace（调用链追踪）、Eval（评估与打分） 和 开源自托管。你可以用它记录每次 LLM 请求的完整过程，包括 Prompt、Token 消耗、响应时间、错误信息，甚至给不同输出打上评分标签，方便后续做质量评估和模型对比。

核心功能怎么用

Trace（调用链） 是 Langfuse 最基础的功能。当你调用 OpenAI、Anthropic 或其他 LLM 接口时，可以在代码中嵌入 Langfuse 的 SDK，自动记录每次请求的耗时、Token 数、输入输出内容。如果需要追踪更复杂的调用（比如多轮对话、RAG 检索链），可以通过 span 和 generation 手动构建调用树，直观看到哪个环节耗时最长或出错。

Eval（评估） 是它的进阶功能。你可以用两种方式评估 LLM 输出：一种是人工打分，直接在 UI 上给某条记录打 1-5 分或写评语；另一种是自动评估，通过编写 Python 脚本或集成第三方评估库（如 LangChain 的 Eval 模块），让 Langfuse 自动对输出进行质量评分。评分结果会关联到对应的 Trace，方便你筛选出低质量输出进行分析。

开源自托管 意味着你可以把 Langfuse 部署在自己的服务器上。官方提供 Docker Compose 文件，支持 PostgreSQL 作为后端存储，数据完全留在本地。这对于有数据合规需求的企业来说很实用。

第一次上手步骤

1. 注册或部署：如果你只是试用，可以直接去 Langfuse 官网注册 Cloud 账号（注意：国内访问可能受限，可考虑国产替代方案如 Dify 或 FastGPT 的观测功能）。如果想自托管，在服务器上执行 git clone 官方仓库，然后 docker-compose up -d 启动，访问 localhost:3000 即可。

2. 创建项目和 API Key：登录后创建一个项目，然后在项目设置里生成一对 SECRET_KEY 和 PUBLIC_KEY。这两个 Key 会用在你的代码中。

3. 安装 SDK 并接入代码：以 Python 为例，先 pip install langfuse，然后在你的 LLM 调用代码中初始化 Langfuse 客户端：

   from langfuse import Langfuse
   langfuse = Langfuse(
       secret_key="your-secret-key",
       public_key="your-public-key",
       host="http://localhost:3000"  # 自托管时填你的服务器地址
   )
   

   接着用 trace = langfuse.trace(name="my-trace") 创建一个追踪，再通过 trace.generation() 记录每次 LLM 调用。

4. 查看数据：运行你的应用几次后，回到 Langfuse 的 Dashboard，就能看到每条请求的详细记录，包括耗时、Token 数、输入输出。点击任意一条可以展开调用链。

适合什么场景

• 调试 LLM 应用：当你的 AI 应用出现奇怪输出或报错时，用 Trace 查看完整调用链，快速定位是 Prompt 问题还是模型问题。
• 质量监控：在线上环境中持续记录 LLM 输出，配合自动评估功能，自动标记低质量回答，触发告警或回滚。
• 模型对比：同时接入 GPT-4 和 Claude，用相同的 Prompt 测试，通过 Eval 功能给两个模型的输出打分，客观对比效果。
• 成本核算：Trace 会记录每次调用的 Token 数，你可以按项目或用户维度统计总消耗，方便做成本分摊。

价格说明

Langfuse 提供免费和付费两种模式。免费版有使用量限制（比如每月 5 万次 Trace 记录、7 天数据保留），适合个人开发者或小项目试用。

付费版起价为 Cloud 约 $59/月，提供更高的调用量上限、更长的数据保留时间（如 30 天或 90 天），以及团队协作功能（多成员、权限管理）。如果你选择自托管，则完全免费，但需要自己维护服务器和数据库。

对于国内用户，如果 Cloud 版本访问不稳定，建议优先考虑自托管部署，或者寻找国产替代方案。