Langfuse 集成

为什么 Yuxi 需要 Langfuse

Langfuse 是一套面向大模型应用的可观测性平台，适合用来观察一次智能体执行过程中到底发生了什么。在 Yuxi 里，一轮用户消息通常不会只对应一次简单的模型调用，它往往会伴随 LangGraph 图执行、工具调用、知识库检索以及多轮中间状态切换。仅靠普通后端日志，虽然也能定位问题，但往往需要在多个文件和多个服务日志之间来回跳转，阅读成本高，而且很难从用户、线程和智能体三个维度统一查看。Langfuse 的价值就在于，它把这些原本分散的执行细节收拢到同一条 trace 里，让你能够从一次对话出发，回看模型输入输出、工具链路、耗时和错误位置。

在 Yuxi 当前的实现中，Langfuse 主要承担的是智能体执行观测层，而不是业务主流程的一部分。换句话说，它不会替代模型服务，也不会替代聊天接口本身，而是帮助你在智能体已经能够工作的前提下，看清楚它是如何工作的。对于调试复杂 Agent、排查工具调用失败、评估多轮会话质量以及分析不同智能体的耗时与成本来说，这类观测能力非常关键。尤其是在一个线程里连续发生多轮交互时，Langfuse 可以帮助你把“这轮请求是谁发起的、落在哪个 thread、触发了哪个 agent、调用了哪些模型和工具”这些信息统一串起来。

在 Yuxi 中能做什么

Yuxi 对 Langfuse 的映射方式比较直接。一个 Yuxi 用户会映射为 Langfuse 中的 user_id，一个对话线程会映射为 session_id，而每次用户输入触发的一轮智能体执行会形成一条独立的 trace。这样做的好处是，既能按单轮请求排查问题，也能在同一个线程维度下连续查看多轮会话。对于需要长期分析使用质量、成本和延迟的场景，这种映射方式能够兼顾可读性和后续统计需求。

当 Langfuse 与 Yuxi 连通之后，它最直接的作用是帮助你看清一轮智能体请求内部发生了哪些步骤。你可以看到这一轮调用关联的是哪个用户、哪个线程、哪个智能体，也可以进一步观察模型调用、工具调用和整体耗时表现。对于日常调试来说，它让“问题到底出在模型、工具、配置还是图流程”这件事变得更容易判断。对于长期运行的系统来说，它也为后续做延迟分析、成本分析和用户反馈分析提供了统一的观察入口。

如何配置

如果你准备启用 Langfuse，首先需要在 Langfuse Cloud 中创建项目并获取访问凭证。当前版本推荐优先使用云端模式，因为接入成本最低，也更适合先把 tracing 跑通。你需要在运行 Yuxi 的环境中配置 LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY 和 LANGFUSE_BASE_URL。其中前两个字段用于鉴权，LANGFUSE_BASE_URL 用于指定 Langfuse 服务地址；如果你使用官方云服务，通常可以直接填写 https://cloud.langfuse.com。在大多数部署场景下，只要把这些变量写入 .env 并通过 Docker Compose 传给 api 服务即可生效。

从当前实现来看，Langfuse 只有在 key 配置完整时才会被启用。如果没有配置 LANGFUSE_PUBLIC_KEY 或 LANGFUSE_SECRET_KEY，Yuxi 会自动退化为“不启用 tracing”的状态，正常聊天功能不会因此中断。这意味着 Langfuse 是一个可选增强项，而不是系统启动的前置依赖。对于希望先验证主流程、后续再逐步补全观测能力的部署者来说，这种行为比较友好，因为它降低了接入门槛，也减少了配置错误对主业务的影响。

配置后系统会如何工作

理解 Langfuse 的另一个关键点在于，它并不等于“所有调试信息都会立即显示在界面里”。当前 Yuxi 的设计重点是先把 trace id 与执行上下文稳定关联起来，再把这些信息作为后续调试和分析的基础。也正因为如此，系统会优先保证聊天主链路的稳定性，而不是为了获取额外的可点击 URL 去同步等待 Langfuse 的远程接口。换句话说，Langfuse 在 Yuxi 里首先是观测数据的来源，其次才是一个方便跳转查看的外部页面入口。

这也意味着，Langfuse 接入的目标并不是改变用户聊天体验，而是在不破坏主流程稳定性的前提下，为系统补上一层可观测性。只要配置正确，用户的对话仍然按照原有方式执行，只是在后台额外留下可追踪的执行记录。对于运维和开发来说，这类“尽量不影响主流程”的接入方式更适合在现有系统中逐步落地。

如何查看是否生效

启用完成后，你最常见的查看方式是在 Langfuse 控制台中按项目查看 traces。进入项目后，可以按照用户、线程、Agent 或时间范围来筛选，定位到某一轮具体的请求。打开单条 trace 之后，你通常可以看到这一轮智能体执行的整体耗时、模型调用、工具调用以及相关 metadata。对于排查问题来说，这比直接翻阅后端日志更高效，因为你不需要自己手动拼装上下文。对于性能分析来说，也可以更直观地看出某个智能体是否在某类请求上耗时异常，或者某个工具是否经常成为慢点。

如果你是系统管理员或开发者，希望快速确认 Yuxi 是否已经成功把 tracing 打到 Langfuse，最简单的方法不是先看代码，而是先发起一条真实对话，再到 Langfuse 控制台中按最近时间排序查看是否出现新的 trace。如果配置正确，你应该可以看到对应线程下新增的一轮执行记录；如果没有看到，则优先检查 .env 中的三个关键变量是否正确传入 api 容器，以及容器内依赖是否已经包含 Langfuse SDK。对于基于 Docker Compose 的开发环境，这一步尤其重要，因为仅修改 pyproject.toml 并不会自动把新依赖装进已经运行中的镜像，通常还需要重新构建或更新容器。

当前建议的接入方式

目前 Yuxi 推荐的接入顺序是先完成 tracing，再逐步扩展到反馈分析或更完整的运营面板。这样做的原因很简单：只有在 trace 关联已经稳定、用户和线程维度映射已经一致的前提下，后续的评分、质量分析和使用统计才会真正可靠。也正因如此，当前文档重点介绍的是 Langfuse 的定位、接入方式和查看路径，而不是一次性覆盖所有更复杂的高级功能。对于大多数项目来说，先把“能看清每轮智能体执行发生了什么”这件事做好，已经能显著改善调试和运维体验。

关于后续的 self-host 计划

当前版本优先支持的是 Langfuse Cloud 接入路径。对于有私有化部署、数据合规或内网隔离需求的团队，后续 roadmap 中已经预留了 self-host 模式的支持规划。也就是说，如果你现在先使用云端模式完成接入，未来并不会锁死在这一路径上，后续仍然可以根据部署需求迁移到自托管版本。对大多数团队而言，这是一个更稳妥的推进方式：先用最低成本验证价值，再根据实际使用情况决定是否进入 self-host 阶段。