Langfuse快速入门教程 · WeKnora 集成指南

最新推荐文章于 2026-08-09 17:29:10 发布

原创最新推荐文章于 2026-08-09 17:29:10 发布 · 518 阅读

本内容遵循CC 4.0 BY-SA版权协议

1. Langfuse 是什么

Langfuse 是一款开源的 LLM 应用可观测性平台（AI Engineering Platform），专门为大语言模型应用而设计。你可以把它类比为 LLM 世界里的「Sentry + Grafana + Postman」——既能帮你发现问题，又能让你看懂数据，还能管理和测试 Prompt。

1.1 核心能力一览

能力模块	解决什么问题	你能看到什么
Observability（可观测性）	LLM 应用黑盒：不知道发了什么 Prompt、花了多少钱、为什么慢	完整 Trace 树：每次 LLM 调用的输入/输出/耗时/Token 费用
Prompt Management（Prompt 管理）	Prompt 散落在代码里，改了不知道影响什么	版本历史、A/B 测试、与 Trace 联动
Evaluation（评估）	不知道模型质量好不好、改 Prompt 是否有效	自动/手动打分、数据集回归测试
Dashboard & Metrics（看板）	运营同学无法量化 AI 使用情况	Token 用量、费用、延迟、错误率聚合图表

1.2 几个关键概念（必读）

在看界面之前，先理解三个概念，否则界面上会看不懂：

概念	类比	说明
Trace（追踪）	一次完整请求	用户发起一次问答 → WeKnora 调用 RAG + LLM → 返回结果，这整个过程是一个 Trace
Span / Observation（观测节点）	请求中的子步骤	一个 Trace 可包含多个 Span，如「检索向量库」「调用 LLM」「重排序」各自是一个 Span
Generation（生成节点）	一次 LLM 调用	Generation 是特殊的 Span，专门记录 LLM 的输入 Prompt、输出内容、Token 数、模型名
Session（会话）	多轮对话	把同一个用户的多个 Trace 串成一条会话时间线

用一张图理解

一次 WeKnora 问答 = 1 个 Trace → 包含多个 Span（检索 / Rerank / Agent 工具调用 / LLM 生成） → 其中 LLM 调用那个 Span 就是 Generation，记录 Token 费用。

1.3 WeKnora 如何使用 Langfuse

WeKnora 在 v0.5.1 引入 Langfuse 集成，v0.6.2 成为唯一追踪后端（移除了 Jaeger）。WeKnora 通过 Go SDK 在以下位置主动埋点：

Agent ReAct 推理循环：每轮 Think / Act / Observe 各一个 Span
LLM 调用：每次调用 LLM Provider 时生成一个 Generation，记录模型名、Token 用量、耗时
文档解析（docreader）：从投递任务到各解析阶段（OCR / 分块 / Embedding）的 Span 时间线
asynq 异步任务：任务队列全链路追踪
Web 搜索：搜索引擎调用的延迟与结果

2. 在 WeKnora 中集成 Langfuse（新手实操）

2.1 整体流程

集成分四步，每步独立，出问题可以单步排查：

1	部署 Langfuse 服务用 Docker Compose 启动 Langfuse（WeKnora 自带配置）

2	创建项目并获取 API Key 在 Langfuse 界面创建 Project，拿到 Public Key 和 Secret Key

3	配置 WeKnora 环境变量把 Key 和 Langfuse 地址填入 .env 文件

4	验证数据是否上报发一条问答，在 Langfuse 界面看到 Tra

2.2 第一步：启动 Langfuse 服务

WeKnora 的 docker-compose.yml 已经内置了 Langfuse 的 Profile，无需单独安装：

# 终端 - 启动 WeKnora + Langfuse（推荐方式）

# 克隆 WeKnora 仓库（如已克隆跳过）

git clone https://github.com/Tencent/WeKnora.git

cd WeKnora

# 复制环境变量模板

cp .env.example .env

# 启动核心服务 + Langfuse（加 --profile langfuse）

docker compose --profile langfuse up -d

# 确认所有容器正常运行

docker compose ps

启动成功后可访问以下地址：

服务	默认地址	说明
WeKnora Web UI	http://localhost	主界面
WeKnora Backend API	http://localhost:8080	后端 API
Langfuse 界面	http://localhost:3000	本节主角

⚠️ 内网部署注意

在内网环境部署时，将 localhost 替换为服务器 IP 即可（如 http://192.168.1.100:3000）。Langfuse 服务的数据默认存储在本地 PostgreSQL 中，无任何数据出网。

2.3 第二步：在 Langfuse 创建项目并获取 API Key

打开浏览器访问 http://localhost:3000，按以下步骤操作：

注册账号：首次访问会要求注册管理员账号，填写邮箱和密码即可（本地部署无需验证邮件）
创建组织：登录后点击「Create Organization」，输入组织名（如「公司名-AI中台」）
创建项目：在组织内点击「New Project」，建议命名与 WeKnora 租户名对应（如「weknora-prod」）
获取 API Key：进入项目 → 左侧菜单「Settings」→「API Keys」→ 点击「Create new API key」

API Key 说明

Langfuse 会生成一对 Key： • Public Key（pk-lf-xxx）：用于标识项目，可以公开 • Secret Key（sk-lf-xxx）：私密，只显示一次，立即复制保存这两个 Key 在下一步填入 WeKnora 的 .env 文件。

2.4 第三步：配置 WeKnora 环境变量

打开 WeKnora 根目录的 .env 文件，找到并填写 Langfuse 相关配置：

# .env 文件 - Langfuse 集成配置

# ─── Langfuse 可观测性配置 ────────────────────────────────

# 是否启用 Langfuse（true/false）

LANGFUSE_ENABLED=true

# Langfuse 服务地址（使用上面启动的本地服务）

LANGFUSE_HOST=http://langfuse-web:3000

# 如果 WeKnora 和 Langfuse 不在同一 Docker 网络，用宿主机 IP：

# LANGFUSE_HOST=http://192.168.1.100:3000

# 第二步获取的 API Keys

LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxxxx

LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxxxx

# 可选：指定项目名（默认使用 Key 关联的项目）

# LANGFUSE_PROJECT_NAME=weknora-prod

Docker 网络说明

当 WeKnora 和 Langfuse 都通过 docker compose 启动时，它们在同一个 Docker 内部网络中，WeKnora 容器应使用服务名 langfuse-server 而不是 localhost 来访问 Langfuse。如果你是分开部署的，则用 Langfuse 服务器的实际 IP 地址。

修改 .env 后，重启 WeKnora 使配置生效：

# 终端 - 重启 WeKnora 使配置生效

# 如果使用 Docker Compose

docker compose restart app

# 如果使用开发模式（make dev-app）

# 直接 Ctrl+C 然后重新运行 make dev-app

2.5 第四步：验证集成是否成功

最简单的验证方式：在 WeKnora 界面发一条问答，然后去 Langfuse 看是否有 Trace 出现。

打开 WeKnora（http://localhost），选择一个知识库，输入任意问题并发送
打开 Langfuse（http://localhost:3000），进入刚才创建的项目
点击左侧「Traces」，应该能看到刚才那次问答产生的 Trace 记录
点击进去，应该能看到完整的调用链：RAG 检索 → LLM 生成 → 返回结果

✅ 看到 Trace 了？集成成功！

如果 Traces 列表里出现了记录，说明 WeKnora 已经在正常上报数据。如果 1 分钟后还没有，请检查：① .env 中的 Key 是否正确复制（无多余空格）；② LANGFUSE_BASE_URL 是否能从 WeKnora 容器内访问（用 docker exec 测试 curl）；③ 查看 WeKnora 启动日志有无 Langfuse 相关报错。

2.6 常见问题排查

现象	可能原因	解决方法
Traces 页面一直为空	URL 配置错误或网络不通	在 WeKnora 容器内 curl http://langfuse-server:3000/api/public/health 检查连通性
出现 401 Unauthorized 日志	API Key 错误或 Key 对应项目不对	重新检查 .env 中 PUBLIC_KEY 和 SECRET_KEY，注意不要混淆
Trace 出现但没有 LLM 调用节点	模型请求未走 Langfuse 追踪路径	确认 WeKnora 版本 >= v0.5.1，旧版无 Langfuse 集成
部分 Trace 丢失	网络不稳定导致批量上报失败	属于正常现象，Langfuse 使用异步批量上报，偶发丢失不影响业务

3. Langfuse 界面使用指南

这一节是 Langfuse 的「用户手册」，按照工作中最常用的场景组织，新手可以按顺序阅读，也可以按需跳转。

3.1 Traces（追踪列表）——主战场

Traces 是你每天打开最多的页面。每一行代表一次用户请求（如一次问答）。

页面布局

区域	内容	常用操作
顶部筛选栏	按时间范围、用户、Session、标签筛选	设置时间范围是最常用的操作，默认显示最近 1 天
Trace 列表	每行一个 Trace，显示时间、名称、耗时、Token 用量、状态	点击行展开详情；可按耗时/时间排序定位慢请求
右侧详情面板	点击某行后展开，显示完整调用树	层级展开每个 Span；点击 Generation 看具体 Prompt

读懂一个 Trace

点击任意一条 Trace，右侧（或新页面）会展示调用树，WeKnora 的典型结构：

# WeKnora 一次 Agent 问答的 Trace 结构示意

Trace: user_question (总耗时: 3.2s)

├── span: kb_retrieval (向量检索, 180ms)

│ └── span: vector_search (pgvector, 120ms)

├── span: rerank (重排序, 95ms)

├── span: agent_react_loop (ReAct 循环, 2.8s)

│ ├── span: think_step_1 (200ms)

│ ├── generation: llm_call_1 (DeepSeek, 1200ms, 850 tokens)

│ ├── span: tool_call: web_search (400ms)

│ └── generation: llm_call_2 (DeepSeek, 900ms, 620 tokens)

└── span: response_format (50ms)

重点关注：

generation 节点：点击可看到完整的 Prompt（system + user）和 LLM 回复
耗时特别长的 Span：排查性能瓶颈时重点看
红色标记的节点：表示出现了错误

3.2 Sessions（会话）——多轮对话视图

当一个用户和 WeKnora 进行多轮对话时，多个 Trace 会被串成一个 Session，方便查看完整的对话上下文。

左侧点击「Sessions」进入会话列表
点击一个 Session，可以看到该用户的所有对话轮次，按时间顺序排列
每一轮都是一个 Trace，可以逐条展开查看细节

什么时候用 Sessions

排查用户反馈「答得越来越差」时，用 Session 视图查看该用户的对话历史，看是否因为上下文越来越长导致 LLM 超出窗口，或者某轮问题输入了奇怪的内容。

3.3 Dashboard（看板）——数据全局视图

Dashboard 是给技术 Leader 和运营看的聚合统计页面，主要指标包括：

指标	含义	参考阈值（仅供参考）
Trace Count	总调用次数，反映使用量	按业务增长趋势判断
Total Cost	累计 Token 费用（需配置模型单价）	监控是否异常飙升
Latency P50/P99	请求延迟中位数和尾延迟	P99 建议 < 10s（RAG 场景）
Error Rate	出错 Trace 占比	建议 < 1%
Token Usage	输入/输出 Token 分布	输出 Token 比例高说明回答冗长

Dashboard 支持自定义时间范围对比，如「本周 vs 上周」查看性能趋势。点击图表上的数据点可以下钻到对应的 Trace 列表。

3.4 Generations（生成）——LLM 调用汇总

Generations 页面汇总了所有 LLM 调用记录，是分析模型使用效率的核心页面。

典型使用场景

查看最贵的调用：按 Total Cost 排序，找出消耗 Token 最多的问答场景
分析 Prompt 效果：筛选某个特定 model，对比不同时间段的 Token 用量变化
排查输出质量问题：找到某次回答，直接点击看完整 Prompt 和 Response

关键字段说明

字段	说明
Input / Output	LLM 的输入 Prompt 和输出内容（点击展开完整内容）
Prompt Tokens / Completion Tokens	输入和输出消耗的 Token 数量
Model	使用的模型名称（如 deepseek-chat、qwen-plus）
Latency	从发送到收到完整回复的耗时
Cost	本次调用费用（需配置单价，见 3.6 节）

3.5 Users（用户）——按用户查看使用情况

WeKnora 在上报 Trace 时会携带 user_id（对应 WeKnora 的用户 ID），Langfuse 会自动在 Users 页面聚合每个用户的使用数据：

Total Traces：该用户累计发起的问答次数
Total Cost：该用户消耗的总 Token 费用
Last Seen：最后一次活跃时间

点击某个用户可以查看他的所有 Trace 历史，等同于按用户过滤的 Traces 列表。

3.6 配置模型单价（显示费用的前提）

默认状态下 Langfuse 不显示费用金额，需要配置模型的输入/输出 Token 单价：

进入项目「Settings」→「LLM Model Prices」
点击「Add Model」，输入模型名（需与 WeKnora 上报的 model 字段完全一致，如 deepseek-chat）
填写单价：input tokens 价格（每 1M tokens）、output tokens 价格
保存后，历史和未来的 Generations 都会自动计算费用

常用国产模型参考单价（仅供参考，以官网为准）

• DeepSeek Chat（deepseek-chat）: 输入 ¥1/M tokens，输出 ¥2/M tokens • Qwen-Plus（qwen-plus）: 输入 ¥0.8/M tokens，输出 ¥2/M tokens • 单价会变动，请在各厂商官网确认最新价格

3.7 Prompt Management（Prompt 管理）——进阶功能

如果团队希望统一管理 WeKnora 所使用的 Prompt，可以将 Prompt 存入 Langfuse，WeKnora 在运行时动态拉取。

这属于进阶功能，新手阶段不需要立即使用，了解即可：

在 Langfuse「Prompts」页面创建并版本化管理 Prompt
Prompt 有「development」「staging」「production」等标签，一行代码切换部署环境
修改 Prompt 无需重新部署代码，即改即生效
Traces 会自动关联使用的 Prompt 版本，方便对比不同版本效果

⚠️ WeKnora 对 Prompt Management 的支持情况

WeKnora v0.6.x 已内置 Langfuse Trace 集成，但 Prompt 拉取功能需要在 WeKnora 代码中手动调用 Langfuse SDK 的 prompt.get() 接口。目前 WeKnora 仓库尚未内置此功能，如有需要需自行在 internal/llm/ 相关文件中扩展。

4. 日常使用工作流

把 Langfuse 集成到日常开发/运维流程中，建议以下使用节奏：

4.1 每日运维巡检（5 分钟）

打开 Dashboard，检查：Error Rate 是否异常、Latency P99 是否显著上升、Token 用量是否异常飙升
查看 Traces，筛选过去 24 小时，按 Latency 降序排列，查看 Top 5 最慢请求的原因
重点关注红色 Trace（错误请求），点击进入找到是哪一个 Span 报错

4.2 排查用户投诉

从 WeKnora 获取该用户的 user_id 或会话 ID
在 Langfuse 「Traces」页面按 user_id 或 Session 筛选
找到对应时间的 Trace，点击展开看：① 检索到了什么文档块；② 发给 LLM 的完整 Prompt 是什么；③ LLM 回复了什么
对比「检索到的内容」和「最终回复」，判断是检索问题（召回不相关）还是生成问题（LLM 幻觉）

4.3 优化 RAG 性能

在 Traces 列表中筛选 latency > 5s 的请求
展开 Trace，查看各 Span 耗时占比（通常瓶颈在：向量检索 / Rerank / LLM 首 token 延迟）
如果 kb_retrieval 耗时长，考虑调整检索 TopK 或优化索引
如果 LLM 生成耗时长，检查是否 Prompt 太长导致 Context 过大，或考虑换更快的模型

5. 配置项速查

5.1 WeKnora .env 完整 Langfuse 配置项

# .env - Langfuse 相关配置全览

# ─── Langfuse 集成 ────────────────────────────────────────

# 启用开关（默认 false，需显式设置为 true）

LANGFUSE_ENABLED=true

# Langfuse 服务地址

# Docker 内部网络（推荐）：

LANGFUSE_BASE_URL=http://langfuse-server:3000

# 外部 IP 访问：

# LANGFUSE_BASE_URL=http://192.168.1.100:3000

# 使用 Langfuse 官方云（数据出网，内网禁用）：

# LANGFUSE_BASE_URL=https://cloud.langfuse.com

# API Keys（从 Langfuse 项目设置中获取）

LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxxxx

LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxxxx

# 审计日志保留天数（WeKnora 自身的 audit_logs 表，与 Langfuse 无关）

WEKNORA_AUDIT_RETENTION_DAYS=90

5.2 docker-compose.yml Langfuse Profile

WeKnora 使用 Docker Compose Profile 管理可选服务，Langfuse 对应 profile 名为 langfuse：

# 启动命令参考

# 仅启动核心服务（无 Langfuse）

docker compose up -d

# 启动核心服务 + Langfuse

docker compose --profile langfuse up -d

# 启动全部可选服务（包含 Neo4j、MinIO、Langfuse）

docker compose --profile full up -d

# 停止并移除所有容器（数据卷保留）

docker compose --profile langfuse down

# 停止并清除所有数据（谨慎！）

docker compose --profile langfuse down -v

6. 常见问题 Q&A

问题	解答
Langfuse 会影响 WeKnora 的性能吗？	基本不影响。WeKnora 使用异步批量上报，Trace 数据在后台发送，不阻塞请求响应路径。即使 Langfuse 服务不可用，WeKnora 会自动降级并继续正常工作。
Langfuse 数据存在哪里？	自部署模式下，数据存储在 Langfuse 的 PostgreSQL 数据库中（独立于 WeKnora 主数据库）。完全在你自己的服务器上，数据不会外传。
我能关闭 Langfuse 追踪吗？	可以。将 .env 中的 LANGFUSE_ENABLED 设置为 false 即可关闭。关闭后 WeKnora 正常运行，只是不再上报追踪数据。
Trace 数据会保留多久？	Langfuse 自部署版本默认不自动清理 Trace 数据，磁盘空间满之前会一直保留。可以在 Langfuse 管理后台配置数据保留策略。
多个 WeKnora 实例（多租户）如何区分？	可以为每个 WeKnora 实例创建不同的 Langfuse Project，分别配置不同的 API Key。WeKnora 的 tenant_id 也会作为 Trace 的 metadata 上报，可在 Langfuse 内按此筛选。
Langfuse 支持告警吗？	Langfuse 自身不内置告警推送功能。可以通过 Langfuse API 导出指标到 Grafana，或定时查询 Langfuse 指标接口并接入企业微信机器人等告警渠道。