链路追踪

通过 Langfuse 实现可观测性与追踪。

---

致谢

本文档由我们的社区贡献者 jannikmaierhoefer 贡献。👏

RAGFlow 内置了 Langfuse 集成，以便您可以近乎实时地**检查和调试 RAG 管道的每个检索和生成步骤**。

Langfuse 将追踪、跨度（spans）和提示词（prompt）负载存储在专用的可观测性后端中，并在此基础上提供筛选和可视化功能。

注意

• RAGFlow ≥ 0.20.0（包含 Langfuse 连接器）
• 一个 Langfuse 工作空间（云端或自托管），包含*项目公钥*和*密钥*

---

1. 收集您的 Langfuse 凭证

1. 登录您的 Langfuse 仪表板。
2. 打开 **Settings ▸ Projects** 并创建一个新项目或选择一个现有项目。
3. 复制 **Public Key** 和 **Secret Key**。
4. 记下 Langfuse 的 **host**（例如 `https://cloud.langfuse.com`）。如果您是自托管，请使用您自己安装的基础 URL。

这些密钥是*项目范围*的：一对密钥足以满足所有需要写入同一项目的环境。

---

2. 将密钥添加到 RAGFlow

RAGFlow *按租户*存储凭证。您可以通过网页界面或 HTTP API 进行配置。

1. 登录 RAGFlow，然后点击右上角的头像。
2. 选择 **API ▸ 滚动到底部 ▸ Langfuse Configuration**。
3. 填写您的 Langfuse **Host**、**Public Key** 和 **Secret Key**。
4. 点击 **Save**。

保存后，RAGFlow 会自动开始发送追踪信息——无需更改任何代码。

---

3. 运行管道并观察追踪

1. 在 RAGFlow 中执行任何聊天或检索管道（例如，快速入门演示）。
2. 打开您的 Langfuse 项目 ▸ **Traces**。
3. 按 **name ~ `ragflow-*`** 进行筛选（RAGFlow 会为每个追踪加上 `ragflow-` 前缀）。

对于每个用户请求，您将看到

• 一个代表整个请求的**追踪（trace）**
• 用于检索、排序和生成步骤的**跨度（spans）**
• 完整的**提示词（prompts）**、**检索到的文档**和**大语言模型（LLM）响应**作为元数据

（Langfuse 中的示例追踪）

提示

使用 Langfuse 的差异视图来比较提示词版本，或深入分析耗时较长的检索以识别瓶颈。