跳到主要内容

链路追踪 (Tracing)

使用 Langfuse 进行可观测性与链路追踪。

鸣谢

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

RAGFlow 内置了 Langfuse 集成，以便您可以近乎实时地检查和调试您的检索增强生成 (Retrieval-Augmented Generation, RAG) 管道中的每一个检索和生成步骤。

Langfuse 将 traces、spans 和提示词负载存储在专门构建的可观测性后端中，并在其上提供过滤和可视化功能。

注意

• RAGFlow ≥ 0.18.0（包含 Langfuse 连接器）
• 包含项目公钥（Project Public Key）和私钥（Secret Key）的 Langfuse 工作空间（云端或自托管）

1. 收集您的 Langfuse 凭据

  1. 登录您的 Langfuse 控制面板（Dashboard）。
  2. 打开 Settings ▸ Projects，新建一个项目或选择一个现有项目。
  3. 复制 Public Key 和 Secret Key。
  4. 记录 Langfuse 的 Host（例如 https://cloud.langfuse.com）。如果使用自托管版本，请使用您自己安装的基础 URL。

这些密钥是*项目级作用域（project-scoped）*的：一对密钥足够用于所有需要写入同一个项目中的环境。

2. 将密钥添加到 RAGFlow

RAGFlow 按租户存储凭据。您可以通过 Web UI 或 HTTP API 配置它们。

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

Example RAGFlow trace in Langfuse

保存后，RAGFlow 将自动开始发送 traces —— 无需修改代码。

3. 运行管道并查看 Trace

  1. 在 RAGFlow 中执行任意对话（Chat）或检索（Retrieval）管道（例如 Quickstart 演示）。
  2. 打开您的 Langfuse 项目 ▸ Traces。
  3. 过滤条件设置为 name ~ ragflow-*（RAGFlow 会为每个 trace 添加 ragflow- 前缀）。

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

• 代表整个请求的 trace
• 用于检索、重排（Ranking）和生成步骤的 spans
• 完整的提示词（Prompts）、**检索到的文档（Retrieved documents）以及大语言模型响应（LLM responses）**作为元数据

Example RAGFlow trace in Langfuse

（Langfuse 中的 Trace 示例）

提示

使用 Langfuse 的对比（Diff）视图来比较提示词版本，或深入分析运行时间较长的检索步骤以识别瓶颈。