文章

LangFuse使用简介

发表于 更新于
Preview Image
作者 handsomestwei
13 分钟阅读
LangFuse使用简介

LangFuse使用简介

面向企业知识库问答、制度规程助手等 RAG 应用的可观测与评测管理说明。本文侧重概念、流程与和 RAGAS 的配合方式。技术细节以 Langfuse 官方文档 为准。

1. Langfuse 是什么

Langfuse 是一款开源的 LLM 工程平台，面向大模型应用的全生命周期：可观测性（Tracing）、评分（Scores）、数据集（Datasets）、Prompt 管理、实验对比等。其核心功能包括全链路执行追踪、多模态数据支持、延迟与 Token 消耗监控，支持用户反馈收集及 LLM-as-Judge 自动化评估。平台内置提示版本管理与 A/B 测试功能，可通过可视化日志分析优化模型性能。

与「只看一次对话结果」不同，Langfuse 关心的是：

  • 每次请求里检索、生成、工具调用分别发生了什么；
  • 调参、改 Prompt、换知识库之后，效果变好还是变差；
  • 线上真实问题如何沉淀为可回归的测试用例。

因此它常和 RAGAS 等离线评测框架配合：RAGAS 负责算分，Langfuse 负责存链路、存分数、管用例、做版本对比。

2. 官方资源

资源链接
官网https://langfuse.com
文档首页https://langfuse.com/docs
可观测性（Tracing）https://langfuse.com/docs/observability/overview
评测与数据集https://langfuse.com/docs/evaluation/overview
自托管总览https://langfuse.com/self-hosting
Docker Compose 部署https://langfuse.com/self-hosting/deployment/docker-compose
GitHub 仓库https://github.com/langfuse/langfuse
托管云服务https://cloud.langfuse.com

3. 核心能力架构

1
2
3
4
5
6
7
8
9
10
11
12

┌─────────────────────────────────────────────────────────┐
│                    Langfuse 功能架构                      │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Tracing   │  │   Scores    │  │  Datasets   │     │
│  │   调用追踪    │  │   评分管理   │  │   用例管理   │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
│        │                │                │              │
│        └────────────────┴────────────────┘              │
│                         ▼                               │
│              统一数据存储与可视化（Web UI）                 │
└─────────────────────────────────────────────────────────┘

3.1 Tracing（调用追踪）

记录单次用户请求的完整链路，典型包括：

  • 用户问题、最终回答；
  • 检索返回的 contexts、条数、耗时；
  • 各次 LLM 调用的 prompt、response、token、延迟；
  • 自定义 metadata（来源、用户、实验版本等）。

在 UI 的 Traces 页面可按时间、用户、标签筛选，用于排查幻觉、慢请求、检索为空等问题。

3.2 Scores（评分管理）

为某次 Trace 或某次 Dataset Run 挂载数值/布尔/分类分数，例如：

  • 用户点赞/差评；
  • RAGAS 的 faithfulness、context_precision 等；
  • 业务自定义规则（是否编造事实、是否先澄清必要参数等）。

便于在仪表盘上按版本、按批次对比质量变化。

3.3 Datasets（用例管理）

集中管理评测用例，支持：

  • 版本与协作（避免 JSON/Excel 散落、多人改乱）；
  • 每条用例的 input（如 question、contexts）与 expected_output（如 ground_truth）；
  • 从生产 Trace 一键加入 Dataset，再人工补全标准答案。

4. 业务系统如何接入

要实现「生产数据 → 测试用例 → 持续评估」闭环，需先把业务 LLM/RAG 调用上报到 Langfuse。常见三类方式（择一或组合）：

方式适用场景要点
LangChain Callback应用基于 LangChain/LCEL在链路上挂 Callback，自动记录各步
OpenAI SDK 包装已用 OpenAI 兼容接口使用 Langfuse 提供的 SDK 包装，对业务侵入小
手动 Trace自研 RAG、知识库平台等自定义流程自行创建 Trace，为「检索」「生成」等步骤建 Span/Generation

接入成功后，线上每次问答都会在 Langfuse 留下可回溯记录。

离线评测场景：业务系统未嵌入 SDK 时，也可在评测脚本侧为每条金标准样本单独创建 Trace 并回写 RAGAS 分数，无需先改造线上服务。

5. 生产数据 → 用例集闭环

这是 Langfuse 在 RAG 场景中最有价值的能力之一：把真实请求变成可回归用例。

1
2
3
4
5
6
7
8
9
10
11
12
13

┌─────────────────────────────────────────────────────────────┐
│              生产数据 → 用例集 闭环流程                        │
├─────────────────────────────────────────────────────────────┤
│   用户请求 → RAG 系统（已接入 Langfuse）                      │
│              ↓                                              │
│         Langfuse Traces（question / contexts / answer）      │
│              ↓ 筛选 & 标注                                    │
│   问题用例 / 典型用例 / 回归用例                               │
│              ↓ 加入 Dataset                                   │
│         人工补充 ground_truth                                 │
│              ↓                                              │
│         RAGAS 持续评估、版本对比                               │
└─────────────────────────────────────────────────────────────┘

5.1 添加用例的常用方式

  • UI 单条：Traces 详情页 →「Add to dataset」→ 选择 Dataset，确认 input/期望字段映射。
  • UI 批量：Observations 表多选 → Actions → Add to dataset。
  • 自动化：结合用户评分回调，差评自动进入「待审核」Dataset，人工确认后再进入正式金标准集。

5.2 用例积累策略

来源优先级说明
用户差评高真实痛点，应优先覆盖
人工抽检问题高质量缺陷的直接证据
修复后 Bug高防止回归
高频问题中覆盖主场景
边界 Case中长文本、缺参、多意图等
随机采样低保持多样性

5.3 闭环价值

  1. 零成本获取真实用例：不必凭空编造问法。
  2. 问题驱动：差评与抽检优先。
  3. 持续积累：用例随业务运行增长。
  4. 可追溯：每条用例可关联原始 Trace ID。

6. Dataset：评估用例的单一数据源

Langfuse Dataset 可解决：

  • 用例散落在 JSON、Excel、代码常量中；
  • 多人协作版本混乱、无法追溯变更；
  • 线上问题难以快速转为测试条目。

典型字段约定（与 RAGAS 对齐）：

  • input：question、contexts（若离线已采集）等；
  • expected_output：ground_truth、answer（可选）等；
  • metadata：场景分类、难度、来源 Trace ID 等。

生产 Trace 转入 Dataset 时，可自动带上当时的 question、contexts、answer，再由标注人员补全 ground_truth。

7. 与 RAGAS 的集成

RAGAS 负责离线量化（faithfulness、answer_relevancy、context_precision、context_recall 等）；Langfuse 不负责「替你算 RAGAS」，而是承接输入输出、沉淀结果。

7.1 推荐整体流程

1
2
3
4
5
6
7
8
9
10
11

┌─────────────────────────────────────────────────────────┐
│              Langfuse + RAGAS 评估流程                    │
├─────────────────────────────────────────────────────────┤
│  Langfuse Dataset（用例集，可来自 Trace）                  │
│           ↓ 读取用例                                      │
│  评测脚本：调用 RAG 获取 answer/contexts（或使用已采集数据）  │
│           ↓                                              │
│  RAGAS evaluate → 四大指标                                 │
│           ↓                                              │
│  Langfuse Scores / Dataset Run → 可视化、多版本对比         │
└─────────────────────────────────────────────────────────┘

7.2 两种常见集成方式

方式作用
Callback 集成RAGAS 内部若走 LangChain，可通过 Callback 自动记录评判 LLM 的每次调用，便于分析评测成本与失败原因
Score API 集成评测结束后，将每条样本的 ragas_faithfulness、ragas_context_precision 等写入 Langfuse Score，关联到对应 Trace 或 Dataset Run Item

7.3 典型落地方式

  1. 用例来源：金标准 JSONL/CSV，或从 Langfuse Dataset 导出；亦可由生产 Trace 筛选后入库。
  2. 数据采集：批量调用 RAG 应用 API，保存 question、answer、contexts。
  3. 打分：调用 RAGAS evaluate，得到各指标。
  4. 回写：通过 Langfuse Score API 将分数挂到当次 Trace；未配置 Langfuse 时仍可仅保留本地 CSV/JSON 汇总。

配置时需在 Langfuse 项目中创建 Public Key 与 Secret Key，并将客户端 host（或 SDK 的 LANGFUSE_HOST）指向对应环境：

环境地址（示例）
线上托管（Langfuse Cloud）https://cloud.langfuse.com（默认，在 cloud.langfuse.com 注册并创建项目）
自托管（Docker Compose 等）http://localhost:3000 或 http://<内网/公网 IP>:3000

8. Docker 自托管部署

Langfuse 开源可自托管，与 Langfuse Cloud 同源。适合内网、数据不出域或 PoC 环境。

8.1 部署方式选择

方式适用说明
Docker Compose本地 / 单机 VM、测试、小规模最简单，无高可用、无水平扩展、需自行备份
Kubernetes (Helm)生产、高可用官方推荐的生产路径
Terraform（AWS/Azure/GCP）云上生产一键基础设施
Langfuse Cloud免运维官方托管，最快上手

8.2 Docker Compose 快速步骤

环境要求：已安装 Git、Docker 与 Docker Compose（Windows/macOS 可用 Docker Desktop）。

步骤概览：

  1. 克隆官方仓库：https://github.com/langfuse/langfuse
  2. 进入仓库目录，编辑 docker-compose.yml 中标记为 # CHANGEME 的密钥与密码（务必改为足够长的随机值）。
  3. 执行 docker compose up，等待约 2～3 分钟，日志中出现 langfuse-web 容器 Ready。
  4. 浏览器访问 http://localhost:3000 打开 Web UI。
  5. 停止服务：Ctrl+C 或 docker compose down（加 -v 会删除数据卷，慎用）。

生产 VM 建议（官方文档）：至少约 4 核 CPU、16 GiB 内存、100 GiB 级磁盘（追踪与观测数据量大）；仅对外开放 Web（约 3000）及对象存储相关端口，其余组件留在内网。

8.3 自托管架构组件

  • Langfuse Web：UI 与 API
  • Langfuse Worker：异步处理事件
  • PostgreSQL：事务型元数据
  • ClickHouse：追踪与观测类分析数据
  • Redis/Valkey：缓存与队列
  • S3/兼容对象存储（Compose 中常为 MinIO）：原始事件与多模态附件

所有依赖组件时区需为 UTC，否则查询可能出现异常（见官方 FAQ）。

8.4 升级与限制

  • 升级：停止后执行 docker compose up --pull always，详见 Upgrade 文档。
  • 横向扩展：Compose 不支持多实例负载均衡，流量大时应改用 Kubernetes 或垂直扩容更大 VM。
  • 部分高级能力可能需要 License Key。

自托管完成后，在 Langfuse 项目设置中创建 API Keys，将客户端 host 指向自建地址（如 http://your-server:3000），即可供业务 SDK 或离线评测脚本上报。

AI, RAG
AI RAG LangFuse
本文由作者按照 CC BY 4.0 进行授权