工作坊介绍与Langfuse平台定位

本次由Annabell Schäfer和Lotte Verheyden主持的工作坊聚焦于持续改进智能体（Agents），参与者可通过访问 langfuse.com/workshop 获取步骤指南及额外资源。Langfuse是一个开源、模型无关且框架无关的平台，旨在帮助团队执行改进智能体的流程。尽管许多大型企业已将其纳入日常运营，但小型用户社区通过多样化的项目实践为平台提供了重要的反馈机制。这种来自不同技术栈的广泛使用，使得Langfuse能够紧跟这一快速演变领域的最新趋势。演讲者Mark作为创始人也参与了现场支持，确保参与者在工作坊期间获得必要的帮助。

AI工程与传统工程的本质差异

AI工程（AI Engineering）的核心在于解决智能体非确定性带来的挑战。与传统工程中系统状态健康即代表运行正常不同，AI系统的内部指标可能显示良好，但智能体的输出或行为却可能是错误或缺乏质量的。这种非确定性（Non-deterministic）特性意味着必须采用专门的工程方法来检测和修复问题。AI工程通过一系列流程将检测变化和改进智能体转化为一个持续循环（Continuous Loop）。这种方法论不仅适用于高风险行业，也是所有希望快速迭代智能体团队的必备技能。Langfuse正是为了执行这些特定的AI工程流程而设计，填补了传统软件工程在应对不确定性时的空白。

AI工程循环：在线与离线两部分

AI工程循环可划分为两个主要部分：在线的追踪（Tracing）与监控（Monitoring），以及离线的构建数据集、实验和评估。对于大多数非高风险行业的团队而言，仅从在线部分开始即可实现快速迭代。通过部署应用到生产环境并收集智能体与用户交互的追踪数据，团队可以基于监控结果进行简单修复。然而，随着产品成熟或进入高风险环境，离线部分变得至关重要。这部分涉及基于监控中发现的问题构建结构化测试用例（数据集），在部署前进行实验和评估，确保新变更未引入回归问题且结果优于旧版本。这种结构化的测试流程是保障生产环境稳定性的关键。

追踪（Tracing）：构建高质量数据基础

一切始于高质量的追踪。如果追踪设置不当，后续的监控和数据集构建都将失效。一个追踪由多个观察（Observations）组成，这些观察代表了智能体生成答案过程中的不同步骤。LLM调用、工具调用或其他操作均可作为独立的观察单元，且支持嵌套结构。每个观察都附带大量元数据以评估质量：LLM调用通常包含持续时间、Token成本、模型版本及Prompt版本；而工具调用（如网络搜索）则记录具体的查询参数。充分的时间投入以确保追踪设置的完善，是捕捉潜在问题并做出明智评估决策的前提。只有当在线部分的数据足够丰富和准确，团队才能有效地进行后续的监控和分析。

监控（Monitoring）：自动化与人工反馈的结合

在线循环中的监控功能主要服务于三个目标：整体健康度聚合指标、信号检测以及反馈与评估。首先，通过聚合指标（Aggregate Metrics）监控系统的整体健康状况，包括成本和响应质量随时间的变化趋势。其次，随着应用规模扩大，人工审查所有追踪变得不现实，因此用户反馈成为发现重要问题的关键信号检测机制。最后，结合自动评估器（Automatic Evaluators）和人工标注来捕捉新出现的细微问题。虽然自动化评估具有可扩展性，但人类反馈在识别新颖或复杂案例方面不可或缺。这种混合监控策略确保了团队既能大规模处理数据，又能精准定位关键缺陷。

从用户反馈到可观测性的核心转变

在构建AI代理（Agents）时，单纯依赖开发者自身的思考往往存在盲区。虽然用户反馈和人工标注在扩展性上可能不如自动化手段，但它们是发现开发者未曾预见问题的关键来源。今天的讨论重点在于如何有效地与应用程序的Trace（追踪）数据协作，并确定真正需要监控的内容。我们需要关注的是对应用程序具体有价值的指标，而非泛泛而谈的通用数据。

"User feedback and human annotation might scale a bit less well, but these are where you will detect really things you haven't thought about yourself."

此外，利用编码代理（Coding Agents）可以将工作效率提升十倍，但关键在于确定何时需要人工介入。开发者不应完全让编码代理自主完成所有工作，而应在关键环节保持"在环（in the loop）"状态。这种平衡对于构建可靠且高效的AI应用至关重要，特别是在处理复杂逻辑和潜在错误时。

案例背景：Dad IT Support Agent的应用场景

为了具体说明监控的重要性，我们引入了一个名为"Specs the Dad IT Support Agent"的示例应用。这个微型仓库源于一个实际项目：作者为父亲开发了一个WhatsApp机器人，用于解答关于手机设置、打印机配置和电脑故障的常见问题。在生产环境中，该代理通过WhatsApp回复；而在演示版本中，我们提供了一个友好的UI界面。

用户（即"Dad"）提出问题后，Specs代理会利用一系列工具来生成回复。这些工具包括获取支持上下文（Support Context），例如查询父亲使用的手机型号、操作系统版本以及已安装的应用程序；还包括搜索帮助库（Search Help Library），其中包含解决特定问题的常见问题解答和上下文信息。最终，代理调用OpenAI API生成逐步指导回复给用户。

"We have a user, my dad or whatever dad and um the dad is asking specs a question... we can get support context. So, some information about what kind of phone is dad using and what kind operating system is it on?"

这个案例展示了代理如何整合多源信息以提供个性化支持。通过监控这一过程，我们可以深入了解代理在获取上下文、调用工具和生成回复时的具体行为，从而优化其表现。

环境搭建与Trace数据的初步观察

在开始监控之前，需要完成基础设置。首先访问langfuse.com/workshop获取示例仓库并克隆到IDE中。接着，在LangFuse平台创建账户和组织（区域选择无影响），并生成API密钥以连接应用。对于演示，我们提供了临时的OpenAI API Key供测试使用。

安装依赖（TypeScript应用，基于OpenAI Agent SDK）并运行npm run dev后，示例应用启动。用户输入如"如何在iPhone上开启蓝牙？"的问题时，代理会在后台调用工具获取上下文并生成回复。此时，LangFuse的Tracing功能会自动记录每一次交互。

"Every row here is an observation and we can also see that they have little different icons... the whole thing is rooted in our agent observation and then below we have a few generations but also tool calls where certain context is pulled."

在Trace视图中，每一行代表一个观察点（Observation），不同图标表示不同类型的操作。点击详情可见代理观测（Agent Observation）作为根节点，下方包含多个生成步骤和工具调用。这表明应用已完全集成追踪功能，无需手动配置即可自动记录关键路径。

监控的核心：理解Trace中的交互细节

进入LangFuse的Monitoring Workshop模块后，重点转向如何利用这些Trace数据。由于我们无法直接观察父亲与应用的互动（这正是代理的价值所在），因此必须通过后台日志来追踪发生了什么。监控不仅是为了记录，更是为了确保父亲获得他真正需要的支持。

在Trace中，我们可以看到代理如何逐步解析问题、检索上下文（如设备信息）、查询知识库并生成最终回复。这种细粒度的可见性使得开发者能够识别瓶颈、错误或不必要的步骤。例如，如果代理频繁调用错误的工具或获取无关上下文，Trace数据将清晰显示这一模式。

"In our context of our dad support app, what does monitoring actually mean? So whenever dad is interacting with the application, we of course don't see what he does... but we actually want to track what's going on."

通过深入分析这些Trace，团队可以迭代优化代理的逻辑和工具使用策略。这种基于数据的持续改进方法，比单纯依赖用户反馈更高效、更精准，为构建鲁棒的AI代理系统奠定了坚实基础。

基于LLM的用户异议检测模板

在支持类应用中，识别用户与Agent回答不一致的情况至关重要。例如当用户询问“如何设置蓝牙”时，若后续追问按钮位置或表示信息不准确，这通常意味着初始回答不够清晰或缺乏细节。为了捕捉此类信号，演讲者展示了如何使用Langfuse中的LLM-as-a-Judge（大模型即裁判）评估器模板。该流程首先通过Git命令切换到监控检查点，随后在IDE中配置Langfuse评估器模型。用户可以选择基于代码的确定性检查或LLM驱动的隐式对话分析。对于“用户异议”这一场景，直接选用提供的模板即可快速启动评估逻辑。

"We might want to catch this because there was something maybe not clear enough, not detailed enough... for the question to actually be properly done."

配置过程中，演讲者连接了OpenAI API密钥作为底层模型支持（也可替换为其他模型或私有网关）。创建评估器时，需指定目标对象：针对整个Trace的根节点（Agent），并聚焦于用户输入部分。通过JSON路径映射，评估器能够提取完整的消息数组历史以及最新的用户消息。这种机制允许系统实时分析对话上下文，从而在大量交互中筛选出潜在的失败案例或模糊点。

代码驱动的情绪与异常检测

除了基于LLM的语义评估，Langfuse还支持Code-based Evaluators（代码基础评估器）用于更确定性的规则检查。演讲者引入了一个具体案例：检测用户是否使用全大写字母。在聊天应用中，用户愤怒时往往倾向于输入全大写内容以强调观点。通过编写Python脚本（也支持TypeScript），可以定义一个评估函数，提取用户消息并检查其中是否包含全大写字符。若检测到该模式，则返回布尔值true作为评分依据。

这种基于代码的评估器能够精准捕捉用户情绪波动或潜在的不满信号。与LLM评估相比，代码评估器在处理特定格式异常（如全大写、脏话或禁用词汇）时更加高效且确定。演讲者演示了如何将Python片段嵌入Langfuse界面，设置评估器名称为“all caps frustrated”，并配置JSON路径以定位用户消息。这种方式使得开发者能够量化用户的挫败感程度，从而针对性地优化Agent的响应策略或触发人工介入机制。

评估器的实际运行与数据洞察

一旦配置完成，这些评估器即可在Trace进入时实时执行。以用户异议检测为例，当系统接收到包含后续质疑（如“按钮不在那里”）的Trace时，评估器会立即标记该事件为异常信号。演讲者指出，在最初的500次提问中可能只有少数几次（如五到七次）出现此类情况，但这正是优化产品细节的关键切入点。通过持续监控这些信号，团队可以识别出哪些回答缺乏足够深度或清晰度。

"If we now execute this we have our first live running evaluator... it's not like all 500 fail but maybe there's five or six or seven different ones where we're not clear enough."

这种分层评估策略（LLM处理隐式语义，代码处理显式规则）构成了Agent质量监控的核心闭环。它不仅帮助团队理解“哪里出了问题”，还能通过数据反馈指导知识库更新或Prompt优化。无论是检测语义上的不一致，还是捕捉情绪化的全大写输入，Langfuse提供的工具链使得从被动追踪转向主动改进Agent行为成为可能。

自定义代码评估器：捕捉格式错误与品牌规范偏差

在 Langfuse 平台中，开发者可以编写自定义代码来执行高度特定的评估逻辑。这种灵活性允许团队针对业务特有的痛点进行监控，例如检查特定关键词的出现频率或确保品牌名称的书写规范。以某案例为例，团队发现用户输入中常将 "f" 大写（如 "F"），而品牌规范通常要求小写。通过编写自定义评估器，系统能够自动识别这类细微的格式错误，从而帮助团队发现用户行为中潜在的混乱点或输入习惯问题。

"So whatever you want to evaluate if it's certain words you're looking for or uh for example also if you have some brand name that always should be written the right way."

这种评估不仅限于简单的文本匹配，还可以用于捕捉用户行为中的异常模式。通过将这些自定义逻辑集成到评估流程中，团队可以从生产环境的真实数据中提取出有价值的反馈信号。例如，当用户频繁使用非标准格式时，这可能暗示着界面引导不足或品牌认知偏差。通过自动化检测这些细节，团队能够更精准地定位需要优化的交互环节，而不是依赖人工抽查。这种基于代码的评估方式提供了极高的可定制性和针对性。

利用评分过滤洞察生产环境表现

在Langfuse中，我们不仅记录追踪数据，还通过评分（Scores）机制来量化特定结果的质量。这种能力允许我们对追踪进行精细筛选，从而深入分析哪些环节经常出错。通过设置监控器（Monitors），我们可以实时观察应用内的动态。为了获得更具代表性的分析视角，演示者引入了生产环境数据（Production Data）进行填充。这一过程并非简单的模拟，而是将包含评分信息的真实追踪数据集直接注入到Langfuse实例中。通过重新应用评分过滤器，可以立即看到新增的大量追踪记录跨越多个页面加载显示。这些数据的核心价值在于为后续的离线改进流程（Offline Improvement Process）提供依据，即利用在生产环境中发现的有趣或异常追踪构建数据集，以优化应用程序。然而，当前的重点在于监控与追踪（Monitoring and Tracing）部分，旨在通过数据洞察应用的实际运行状况。

安装Langfuse Skill以增强自动化诊断能力

为了更高效地处理大规模数据，演示者引入了Langfuse Skill并与编码代理（Coding Agent）集成。这一工具链的安装可以通过CLI或直接在应用中配置完成，其核心优势在于暴露所有API接口。这意味着用户可以通过命令行或直接与编码代理交互来访问追踪、评分、数据集以及实验运行结果。这种集成不仅简化了数据获取流程，还使得在应用初期自动添加追踪（Automatically add tracing）成为可能。演示者展示了如何通过CLI安装该Skill，随后在编码代理（如Codex）中调用它。这种自动化方式极大地提升了工作效率，使得开发者能够专注于发现应用中的问题而非手动查询数据。通过让编码代理直接访问实时追踪，我们可以快速识别出用户交互中的异常模式、评分分布以及潜在的静默失败（Silently failing）场景，即使这些问题尚未被正式评估体系捕捉到。

编码代理自动诊断追踪中的隐性故障

演示者要求编码代理使用Langfuse Skill分析生产环境中的约70-120条追踪记录。代理自动扫描了多个维度，包括问题类型、评分分布、工具调用情况以及延迟和成本指标。分析结果生成了一份详细的报告，揭示了几个关键发现：首先是搜索帮助库的静默检索质量失败（Silent retrieval quality failure），这是一个此前未被评估且开发者未意识到的问题，表明信息查找工具未能按预期工作。其次，检索遗漏（Retrieval misses）导致了延迟和成本的增加，特别是在工具重试调用中检测到了问题。此外，报告还指出了评估覆盖缺口（Evaluated coverage gap），即只有部分追踪数据被纳入评分体系。演示者验证了编码代理的发现与预置报告一致，确认了其诊断的准确性。

从生产追踪信号到持续改进的闭环

今天的讨论核心在于如何利用生产环境中的追踪数据（Production Traces）来驱动Agent的持续优化。虽然我们在初始阶段已经建立了逐步可视化的追踪系统，能够清晰看到Agent使用的工具、输入输出等细节，但这仅仅是第一步。真正的挑战在于如何将这些信号转化为实际的改进动力。我们需要从这些追踪数据中提取关键指标，确保Agent不仅是在执行任务，而是在高质量地完成任务。例如，通过观察用户交互中的异常信号（如全大写输入、脏话或明显的分歧），我们可以识别出Agent表现不佳的具体场景，从而为后续的优化提供明确方向。

维护评估标准与数据集的迭代策略

为了实现持续改进，必须同时做好两件事：维持高质量的评估标准（Evaluation Criteria）和动态维护数据集。在初期构建应用时，我们往往只能预测用户的主要需求，但随着时间推移，大量未预见的边缘案例（Edge Cases）会出现。因此，我们需要定期审查评估器，确保它们不会过度关注某些次要因素而忽略核心质量指标。更重要的是，必须将生产环境中发现的有效案例转化为离线数据集的一部分。这意味着我们需要不断收集真实用户的使用数据，将其整理为高质量的测试用例，并加入到离线事件库中。这样做的目的是确保当我们在代码或配置上做出任何更改时，能够通过回归测试来验证这些更改是否破坏了现有功能。

构建CI/CD中的信心与八步工作坊全景

将上述流程整合进持续集成和持续部署（CI/CD）管道是确保软件质量的关键环节。只有当我们的数据集能够真实反映用户行为，并且评估体系足够严谨时，我们才能在部署新版本时拥有信心。这并非一次性工作，而是一个需要持续投入精力的循环过程。演讲者提到，完整的Langfuse工作坊包含八个步骤，涵盖了从提示词管理到数据集设置的完整流程。虽然本次演讲仅聚焦于在线评估部分，但完整的指南提供了从设置追踪、手动审查轨迹到优化离线数据的每一步指导。建议开发者利用Langfuse的Skill功能，结合编码Agent快速搭建追踪环境，通过命令启动后手动审查轨迹以理解用户行为，最终实现生产数据的自动化优化闭环。

"We need to maintain our evaluation criteria... and most importantly we also need to maintain our data set."

"You actually need to make sure that you are like putting in the reps and close the loop continuously..."

"We would take our repository we would use the length view skill to get up set with tracing..."

结论

Langfuse通过整合在线追踪与离线评估，构建了AI工程的核心闭环。其优势在于利用LLM裁判和代码规则检测用户异议及情绪，结合编码代理自动诊断静默检索失败等隐性故障。然而，该方法依赖高质量追踪数据与持续维护的评估标准及数据集。

适用条件为需处理非确定性输出的Agent场景，尤其适合高风险或成熟产品。短板在于人工反馈扩展性有限且需开发者保持“在环”状态以平衡自动化与准确性。未证明之处包括其在超大规模下的绝对成本效益，以及完全无人工干预的可行性。