Langfuse 实战：为 Harness 智能体打造可观测评估平台

在 AI 智能体从 Demo 走向企业级落地的过程中，开发完成只是第一步。如何追踪每一次调用、评估输出质量、管理提示词版本，才是决定项目能否稳定运行的关键。Langfuse 正是为此而生的开源 LLMOps 平台。本文基于 B 站讲师小斌的分享，结合 Harness 多智能体架构的财务分析项目，拆解 Langfuse 的核心概念、能力边界与实战价值。

Langfuse 是什么：不止于日志追踪

官方将 Langfuse 定义为开源的大模型 LLMOps 平台。这个描述略显抽象，讲师将其翻译为：一个面向大模型 RAG 与智能体应用的开源 AI 工程平台，主要作用是追踪运行过程、分析 token 成本与延迟、管理提示词、收集反馈、执行自动与人工标注的评估，并通过数据集与实验实现持续改进。

这段话包含两层含义。第一，Langfuse 面向已经开发好的 RAG 或智能体应用，对其进行数据收集、评估与追踪；第二，它同样可以对大模型本身进行日志追踪。例如企业常用的 Codex 等编码智能体，本质上也是智能体，接入 Langfuse 后同样能分析 token 成本与延迟。

官方在英文站点用“Open Source Agent Evaluation & Observability”来概括其定位，Observability 即可观测性，同时涵盖分析能力。Langfuse 支持 Python 和 TypeScript 两种语言，也能与 LangChain、LangGraph、LlamaIndex、OpenAI Agent SDK 等主流智能体开发框架无缝整合。

LLMOps 是 MLOps（机器学习运维）在大模型场景下的延伸，指围绕大模型应用全生命周期的一整套工程实践，包括提示词与模型的版本管理、调用链追踪、Token 成本核算、输出质量评估、线上监控与反馈闭环等。传统 MLOps 关注的是训练数据的版本、模型训练与部署；而大模型应用中模型本身通常由外部提供，可变的环节转移到了提示词、检索、工具调用和智能体编排上，因此 LLMOps 的工具重心也随之偏移。理解这一背景有助于判断 Langfuse 的定位：它解决的不是“如何训练模型”，而是“应用上线后如何观测、评估与迭代”的问题，这也是它与普通日志系统、APM 监控工具的根本差别。

用“数字员工”理解 Langfuse 的角色

如果把智能体比作一名会查资料、会使用工具、会计算的数字化 AI 员工，那么 Langfuse 就相当于飞行记录仪、质量部门、实验室和提示词配置中心的集合体。

飞行记录仪负责追踪这位数字员工的每一步操作；质量部门负责对生成的答案进行质量评估；实验室则用于实验——当你修改了提示词，想验证新版本效果是否更好时，可以先在实验室里跑一遍再决定是否上线。

提示词配置中心是容易被低估的能力。很多开发者习惯把提示词直接写在项目代码里，这本身没有问题，但提示词在运行过程中难免需要修改。修改后效果可能变差，此时能否回滚？能否在不重启 RAG 或智能体项目的前提下完成版本管理与回滚？如果提示词硬编码在代码中，这些操作几乎无法实现。

讲师强调，提示词配置中心在企业实际开发中价值很高，但它并不替代智能体或 RAG 做业务决策。

提示词版本管理与回滚 依赖平台化的提示词存储。做法是把提示词从代码中抽离，作为带名称与版本的独立对象存放在 Langfuse 中，应用运行时通过 SDK 按名称拉取指定版本（或标记为 production 的版本）。这样修改与发布不需要重新构建和部署代码，出问题时把 production 标签指回旧版本即可完成回滚。与此配套的通常还有标签（label）、环境区分（开发/生产）和 A/B 对比，使提示词的变更像代码发布一样可审计、可追溯。需要注意的是，硬编码提示词并非错误，只是在频繁迭代、多人协作的场景下，缺失版本控制会让“改坏了如何恢复”成为一个真实风险。

Langfuse 能回答哪些关键问题

从运维视角看，Langfuse 帮助回答一系列具体问题：这次请求中哪些步骤、哪个子智能体做了什么，调用了哪些工具和模型；工具与模型执行了多长时间；提示词和模型是哪个版本；输入与输出的 token 统计及费用、延迟是多少。

在质量层面，它能回答：回答是否正确、是否有完整证据链、用户是否满意（通过用户标注收集反馈）、新版本是否比 Baseline 更好。结合实验室能力，开发者修改提示词或更换模型后，可先在实验环境验证效果，优于基线再替换线上版本。

调用链追踪（Tracing） 是可观测性的基础。一个智能体请求往往不是一次模型调用，而是拆成规划、检索、工具调用、子智能体协作等多层嵌套的步骤，业界通常用 Trace 表示一次完整请求，用 Span 或 Generation 表示其中的子步骤与单次模型生成。Langfuse 会把它们组织成树状结构，记录每一步的输入输出、耗时、所用模型与提示词版本，并携带会话与用户标识以便关联。有了这种结构化链路，才能回答“哪一步慢”“哪个子智能体出错”“一次请求累计消耗多少 Token”等问题；单纯的文本日志缺乏层级关系与统一字段，难以支撑成本分摊和问题定位。

能力边界：Langfuse 不做什么

明确边界同样重要。Langfuse 可以对大模型、RAG 和智能体进行可观测，记录模型、工具、检索和子智能体的各种调用链；可以做评估与反馈收集；可以管理提示词；可以分析指标。

但它不提供智能体本身的开发框架，不提供大模型，不提供向量知识库，不提供业务数据库，也不负责智能体或 RAG 上线后的服务器运维、健康检查与监控。这些仍需由项目自身的技术栈承担。

与 Harness 架构项目的结合点

该系列课程此前已用较长篇幅讲解过 Harness 多智能体项目的开发，包括采购智能助手和企业级 AI coding 智能体。本次财务分析智能体项目的重点不在智能体本身的开发，而在于如何对其进行追踪、评估与可观测性建设。

这也解释了为什么课程先从 Langfuse 讲起：智能体开发能力已经具备，企业级落地的短板在于运维与评估体系。Harness 架构负责多智能体的编排与业务执行，Langfuse 负责运行数据的采集、评估与提示词治理，两者形成开发与运维的闭环。

对于正在将智能体推向生产环境的团队而言，这种分工思路值得借鉴：先有可运行的智能体，再用专业平台补齐可观测与评估能力，而不是把所有能力都塞进业务代码里。

Harness 架构 在此处指一套用于组织多智能体协作的工程框架，其核心是把一个复杂任务拆解为多个职责明确的子智能体（如检索、计算、审核、汇总），由一个编排层负责调度、传递上下文与汇总结果。这种分层结构提高了任务的可分解性与可维护性，但也让运行过程变得更难观察：一次用户请求会触发多次模型调用与工具调用，跨智能体的上下文流转隐藏在代码内部。这正是可观测平台的价值所在——编排层负责“怎么执行”，追踪平台负责“执行得怎么样”，两者职责分离，避免把埋点、评估与日志逻辑硬塞进业务代码而造成的耦合。