1. 这篇文章真正要解决的问题如果你最近关注 AI 工程化方向的技术动态可能已经在社区里看到过 Jason Liu 对某些工具的高度评价。作为在可观测性、LLM 应用开发和 AI Agent 工程实践领域都有深厚积累的技术专家Jason Liu 的评价在开发者社区里往往有比较强的风向标意义。但这里要先给一个判断与其纠结“哪个工具被盛赞”不如拆解“这个工具到底解决了什么开发痛点”。因为 AI 工具迭代速度极快今天被盛赞的工具三个月后可能就被新方案替代。真正值得沉淀的是这类工具为何能获得一线工程师认可以及它的设计思路能给我们自己的项目带来什么启发。从材料看Jason Liu 盛赞的这款工具核心价值集中在AI 代理Agent开发与调试效率上。如果你正在做 LLM 应用、搭过 Agent 工作流或者被“模型行为不可控”“调试链路不透明”“测试用例难维护”这些问题折磨过那这篇文章就是为你准备的。读完这篇文章你会得到四个层面的收获理解这类工具在 AI 工程链路中的定位以及它和传统调试工具的本质差异。掌握它的核心概念搞清楚“追踪Tracing”“评估Evaluation”“数据集Dataset”这些术语到底在解决什么。通过一个可落地的示例亲手跑通“接入工具 → 构建测试用例 → 评估模型输出 → 优化提示词”的完整流程。避开我在实际工程中最常看到的误区和坑包括版本兼容、成本控制、测试集设计等。2. 被盛赞的工具到底在解决什么AI 工程的可观测性危机2.1 传统开发调试逻辑在 LLM 应用里失效了先看一个很典型的场景。你写了一个传统后端接口输入参数不对日志打印出来一查就能定位。原因很明确要么是空指针要么是 SQL 写错要么是下游服务超时。这类问题有一个共同特征代码执行路径是确定的错误是可复现的。但到了 LLM 应用领域这个逻辑彻底失效了。同样是“用户输入”同一个 Prompt同一个模型温度调到 0.2 和 0.8输出可能完全不同。更头疼的是即使温度设成 0不同版本的模型、不同的上下文长度、甚至同一次请求中不同的 token 采样都可能让结果出现肉眼可见的差异。这意味着什么意味着你没法再用“看日志、查异常”的方式去定位问题。你根本不知道模型为什么给出了这个回答是哪一段上下文影响了它的判断还是它的“幻觉”机制在起作用。2.2 流程编排让问题更难定位再叠加一层流程编排。现在的 AI 应用很少是“一个 Prompt 走天下”基本都是多步骤的 Agent 工作流先做意图识别再调用工具检索知识库然后把结果拼接成上下文最后让模型生成回答。任何一个中间节点的输出有问题都会传导到最终结果。更麻烦的是LLM 的“软错误”不像传统代码的“硬错误”那么明显。传统代码错了就是抛异常但 LLM 应用经常是“能跑通但结果不对”或者“能给出答案但推理链路是错的”。这种场景下你需要的不是传统日志而是一种能够完整还原 LLM 请求链路、记录中间每一步输入输出、并把多个请求关联成测试集进行批量评估的工具。这就是 Jason Liu 盛赞这类工具的根本原因它把 AI 应用开发从“盲人摸象”变成了“可视化手术”。2.3 一个关键概念LLM 可观测性你可能听过“可观测性Observability”这个词传统分布式系统里它指的是通过日志、指标、追踪来理解系统状态。但 LLM 可观测性有本质区别传统可观测性关注“系统是否健康”延迟、错误率、CPU 使用率。LLM 可观测性关注“模型行为是否符合预期”推理链路、上下文使用、输出质量。这意味着你不能只监控系统指标还必须监控语义层面的信息。比如用户这次输入被路由到了哪个意图分类Agent 在检索知识库时是否找到了相关文档模型最终生成时采用了哪一段上下文如果输出质量差是 Prompt 设计问题、检索质量差还是模型能力不足这些问题有一个共同点它们都需要把请求链路完整记录下来然后从语义层面进行分析。这正是被盛赞工具的核心设计目标。3. 核心概念从一个示例任务说起在进入实操之前先把概念讲透。我建议用一个具体的示例来理解整套机制。假设你要做一个“智能客服助手”用户输入“我想查询订单状态”应用流程识别意图 → 调用订单系统 API → 获取订单信息 → 模型生成回复这个流程看似简单实际工程化后会遇到几个典型问题问题一怎么知道每个环节用了多长时间如果整体响应变慢是模型推理慢还是 API 调用慢没有链路追踪你只能靠猜。问题二怎么知道模型回答得对不对“你的订单已发货预计 3 天内到达”这个回答怎么判断对错“发货状态”是否真的来自订单系统模型是否编造了物流信息问题三改了 Prompt 之后怎么确认效果真的变好了凭感觉测试三五个用例还是用一个固定测试集跑一遍量化对比改进前后的得分这时候被盛赞的工具提供了一套完整的解决方案核心由以下模块组成模块作用类比传统开发Tracing追踪记录每次 LLM 调用的完整链路包括输入、输出、token 用量、延迟分布式链路追踪Dataset数据集把测试用例组织成可复用的数据集支持从线上请求导入单元测试用例集Evaluation评估用规则或 LLM 作为裁判批量评估模型输出质量自动化测试断言Prompt Management提示词管理管理不同版本的 Prompt对比效果差异代码版本管理这四块组合起来就形成了一个完整的工作闭环先把应用接入追踪记录所有线上请求。从线上请求中筛选出代表性用例保存为数据集。在数据集上批量运行评估找到问题集中的方向。调整 Prompt 或应用逻辑再次运行评估对比分数变化。现在你可能理解了这个工具不是单纯“追踪”或“评估”而是把追踪、数据、评估串成了一条工程流水线。这比单点工具的价值高得多也是它能获得 Jason Liu 这类技术专家认可的关键原因。4. 环境准备在本地把最小闭环跑起来这部分我们进入实操。要完整演示整个工作闭环需要一个支持 LLM 应用开发的环境。这里的思路是通用的你可以替换成自己熟悉的技术栈。4.1 技术栈选择与版本说明为了让你能顺利复现我选择了以下技术栈Python 3.10 及以上版本当前主流 LLM 应用开发语言OpenAI 兼容 API你可以使用 OpenAI、或其他兼容 OpenAI 接口的模型服务LangChain 作为 LLM 应用开发框架用于快速搭建 Agent 工作流被盛赞的工具本身下文以“该工具”代指因为不同生态下同类工具接入方式略有差异版本说明本文不绑定具体版本号因为相关 SDK 更新非常频繁。建议你在运行以下命令时以官方最新稳定版本为准。4.2 安装核心依赖建议先创建一个独立的 Python 虚拟环境python3 -m venv venv source venv/bin/activate然后安装核心依赖pip install openai langchain langchain-openai如果你要接入该工具的服务端通常还需要安装对应的 SDK。以当前主流的同类工具为例pip install langfuse如果你的团队用的是另一个类似工具比如 Helicone、LangSmith安装方式大同小异核心都是“安装 SDK → 配置环境变量 → 在框架中设置回调”。4.3 配置环境变量在项目根目录创建.env文件# 模型服务相关配置 OPENAI_API_KEYsk-your-api-key OPENAI_BASE_URLhttps://api.openai.com/v1 # 该工具服务端配置 LANGFUSE_PUBLIC_KEYyour-public-key LANGFUSE_SECRET_KEYyour-secret-key LANGFUSE_HOSThttps://cloud.langfuse.com需要注意千万别把密钥提交到 Git 仓库。在.gitignore中加入.env这是最基本的工程素养。4.4 验证连接写一个最简单的测试脚本确认 SDK 能正常连接# 文件路径test_connection.py from langfuse import Langfuse langfuse Langfuse() # 创建一个简单的 trace 验证连接 trace langfuse.trace(nametest-connection) trace.update(outputOK) print(连接成功Trace ID:, trace.id)运行python test_connection.py如果终端打印出 Trace ID说明连接正常可以进入下一步。这里要特别说明如果你用的是本地自托管版本需要先把服务端跑起来。常见做法是用 Docker 一键启动docker run -d --name lf-server \ -p 3000:3000 \ -e NODE_ENVproduction \ ghcr.io/langfuse/langfuse:latest具体命令以你使用的工具官方文档为准。5. 完整示例搭建一个带追踪和评估的智能客服现在进入核心部分。我们搭建一个最小可用的“订单查询 Agent”并把它接入追踪和评估系统。5.1 第一步定义工具函数我们需要一个简单的“查询订单状态”工具# 文件路径tools.py import json import random def get_order_status(order_id: str) - str: 模拟查询订单状态 # 实际项目中这里会调用真实的订单系统 API statuses [已发货, 配送中, 已签收, 待发货] status random.choice(statuses) return json.dumps({order_id: order_id, status: status})这个函数模拟了真实业务中的 API 调用。在实际项目中你只需要把函数体替换成真实的 HTTP 请求即可。5.2 第二步搭建 Agent 工作流使用 LangChain 构建一个简单的 Agent 流程# 文件路径agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_functions_agent from langchain.prompts import ChatPromptTemplate from langchain.tools import Tool from tools import get_order_status load_dotenv() # 初始化 LLM llm ChatOpenAI( modelgpt-4o-mini, # 以你的模型服务为准 temperature0.0, ) # 定义工具 tools [ Tool( nameget_order_status, funcget_order_status, description根据订单 ID 查询订单的物流状态, ) ] # 定义提示词 prompt ChatPromptTemplate.from_messages([ (system, 你是一个电商客服助手。请根据用户的问题使用工具查询订单状态 并用亲切的口吻回复用户。如果用户没有提供订单号请引导用户提供。), (human, {input}), (placeholder, agent_scratchpad), ]) # 创建 Agent agent create_openai_functions_agent( llmllm, toolstools, promptprompt, ) agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations3, )这里的关键配置是create_openai_functions_agent它让 LLM 能够自主决定何时调用工具、调用哪个工具、以及如何解读工具返回结果。5.3 第三步接入追踪回调这是被盛赞工具发挥作用的关键一步。我们需要把追踪能力接入 Agent 执行过程# 文件路径agent_with_tracing.py from langfuse.callback import CallbackHandler from agent import agent_executor # 创建 Langfuse 回调处理器 langfuse_handler CallbackHandler( public_keyyour-public-key, secret_keyyour-secret-key, hosthttps://cloud.langfuse.com, ) # 执行 Agent并传入回调 response agent_executor.invoke( {input: 你好我想查一下订单 10086 的物流状态}, config{callbacks: [langfuse_handler]}, ) print(response[output])此时你的每一次 AI 应用调用都会被完整记录下来。在服务端界面上你能看到用户输入原文模型完整推理过程工具调用参数和返回结果每个环节的耗时与 token 消耗这一步做完你就拥有了“AI 应用请求的 X 光机”。5.4 第四步构建评估数据集有了追踪能力后我们下一步要做的是构建评估数据集。数据集构建有两种方式方式一从线上请求导入登录服务端控制台找到刚才产生的 Trace 记录把有代表性的请求保存到数据集中。这种方式最省力也最贴近真实业务分布。方式二手工构建测试用例更推荐的方式是把典型用户问题和“期望行为”手动组织成数据集# 文件路径build_dataset.py from langfuse import Langfuse from langfuse.client import Dataset langfuse Langfuse() # 创建数据集 dataset langfuse.create_dataset(nameorder_query_test, description订单查询场景测试集) # 添加测试用例 dataset.create_item( input{input: 你好我想查一下订单 10086 的物流状态}, expected_output要求包含该订单的物流状态信息并在信息不足时引导用户补充 ) dataset.create_item( input{input: 我的快递到哪了}, expected_output模型应该询问用户提供订单号而不是自行猜测 ) dataset.create_item( input{input: 帮我查一下 12345 号订单}, expected_output要求模型调用 get_order_status 工具 )这里的关键点是测试用例不应该只写“期望的输出文本”更要想清楚“期望的行为链路”。因为 LLM 应用评估关注的不只是答案对不对更关注过程对不对。5.5 第五步运行批量评估数据集构建完成后在服务端控制台配置评估器Evaluator或者通过 SDK 批量运行。核心代码如下# 文件路径run_evaluation.py from langfuse import Langfuse from agent import agent_executor langfuse Langfuse() # 获取数据集 dataset langfuse.get_dataset(order_query_test) # 定义一个评估函数 def evaluate_output(output_text: str, expected: str) - bool: 简单判断输出是否包含关键信息 # 实际项目中可以用 LLM 作为裁判或使用更复杂的规则 keywords [订单, 状态, 已发货, 配送中, 签收] return any(kw in output_text for kw in keywords) # 遍历数据集运行评估 for item in dataset.items: result agent_executor.invoke(item.input) score evaluate_output(result[output], item.expected_output) print(f用例 {item.id}: 得分 {score})这一步的意义在于把主观的“模型回答得好不好”转化为客观、可量化的分数。当你的 Prompt 改动影响模型行为时系统会通过分数变化告诉你“变好了还是变差了”。6. 运行结果与效果验证6.1 预期输出运行agent_with_tracing.py后终端会输出类似内容 Entering new AgentExecutor chain... Invoking: get_order_status with {order_id: 10086} Order status: {order_id: 10086, status: 配送中} 你好您的订单 10086 当前正在配送中请耐心等待预计很快就能到达。如果您还有其他问题随时告诉我哦同时在服务端控制台能看到完整的 Trace 详情包括Trace Name: AgentExecutor 的执行链路Spans: 对 LLM 调用和工具调用的分别记录Token Count: 输入、输出 token 数Latency: 每个节点耗时6.2 如何判断成功从三个层面判断第一层功能层面。用户的问题被正确识别工具被调用模型返回了包含订单状态的回复。第二层可观测层面。在服务端界面能看到完整链路每步耗时和 token 消耗一目了然。如果响应慢你可以立刻定位是模型推理慢还是工具调用慢。第三层可评估层面。在数据集上运行评估后你能得到所有测试用例的通过/失败情况。如果在 3 个用例中有一个失败你能立刻看到失败用例的完整链路从而判断是 Prompt 问题还是工具调用问题。6.3 失败排查第一原则如果运行失败第一步不要急着改代码先看服务端界面的 Trace 详情。因为如果是 API 密钥错误Trace 里会有 HTTP 401 错误。如果是模型中转服务超时Trace 里会显示耗时异常。如果是工具调用失败Trace 里会记录异常堆栈。你不需要猜直接看链路数据就知道问题在哪。7. 常见问题与排查思路基于我在实际工程中的经验以及社区中高频出现的问题整理成下面的排查表问题现象可能原因排查方式解决方案连接服务端失败API 密钥配置错误检查环境变量是否加载、公钥密钥是否配对重新复制密钥确认.env文件被正确加载Trace 记录只有一部分回调没有传给所有执行路径检查是否在所有 AgentExecutor 调用里都传入了 callback封装公共调用函数统一注入回调追踪数据量太大请求量高全部记录成本过高查看服务端的采样配置开启采样率设置如只记录 10% 的请求评估结果不准评估规则设计不当检查评估器使用的模型和提示词引入 LLM 作为裁判或使用更细粒度的评估规则数据集用例重复从线上导入时未去重检查数据集的去重逻辑按用户输入哈希去重或按 trace 属性过滤上下文追溯困难没有保存中间步骤输出查看 Trace 的 span 是否完整在关键步骤增加langfuse_context.update_current_span记录自定义属性生产环境密钥泄露密钥被硬编码在代码中检查 Git 历史与环境变量立即轮换密钥使用密钥管理服务多环境数据混淆开发/生产使用同一个项目检查 SDK 初始化的是否同一个 project为不同环境创建独立项目或添加环境标签8. 最佳实践与工程建议8.1 从追踪开始而不是从评估开始很多团队一上来就搭建复杂的评估系统结果发现测试用例设计不合理、评估指标不清晰整个系统荒废掉了。更稳妥的路线是先接入追踪跑几天生产流量看看真实请求长什么样。当你对线上流量模式有感觉之后再从中挑选代表性用例构建数据集。最后才搭建评估器。理由很简单评估的前提是理解问题而追踪是理解问题的最短路径。8.2 数据集要覆盖“典型场景”和“边界场景”好的测试集应该包含三类用例烤羊肉串用例业务中最常见的 10 到 20 个请求形态。烤焦用例用户输入模糊、缺少关键信息、意图不明确的情况。奇葩用例恶意输入、超长文本、特殊字符、多语言混用。这三类用例各有用途常规用例保证基本盘不崩边界用例暴露模型短板恶意用例保证安全边界不被突破。8.3 评估器设计规则和 LLM-as-Judge 结合评估器设计没有银弹。最稳妥的做法是分层# 文件路径evaluator.py def hybrid_evaluate(output_text: str, expected: str, trace_data: dict) - dict: 混合评估器规则 LLM 判断 # 第一层规则判断成本低速度快 rule_score 0 if 订单 in output_text: rule_score 0.5 if 状态 in output_text: rule_score 0.5 # 第二层如果规则判断不通过再用 LLM 判断 if rule_score 1.0: # 这里调用 LLM 进行语义相似度判断 llm_score judge_with_llm(output_text, expected) return {rule_score: rule_score, llm_score: llm_score} return {rule_score: rule_score, llm_score: None}规则评估的好处是成本低、可解释性强适合做快速过滤。LLM 评估的好处是能理解语义适合判断“虽然用词不一样但意思一致”的情况。两者结合才能在成本和效果之间取得平衡。8.4 控制成本采样策略AI 应用的可观测性也有成本问题。每次请求的 trace 都会消耗 token 和存储资源。对于高流量业务不需要记录每一个请求更推荐“全量记录 抽样分析”的组合策略生产环境全量记录基础信息耗时、状态码、token 数抽样记录详细链路比如 10%。开发环境全量记录详细链路方便调试。大多数可观测性工具都支持采样配置建议把采样率做成环境变量而不是硬编码。8.5 用数据驱动 Prompt 优化而不是凭感觉传统开发里“这个函数性能不好”可以通过 profiler 定位。但在 LLM 应用开发里很多团队优化 Prompt 全凭感觉。今天觉得“加一句 system prompt 应该会更好”明天觉得“few-shot 例子再多几个”。被盛赞工具揭示了一个新的工作方式先在数据集上跑一次评估拿到基线分数。修改 Prompt。在同一个数据集上再次评估。对比分数变化判断修改是否有效。这就把“我觉得改得更好了”变成了“数据表明改得更好了”。这个转变是 LLM 应用开发走向成熟的分水岭。9. 总结与后续学习方向写到这里这篇文章的核心观点可以收束为三点第一LLM 应用开发最大的痛点不是“模型不够聪明”而是“过程不可见”。模型输出的质量无法用传统日志体系监控这时候需要一套专门面向 LLM 链路的可观测性工具把每一次请求的推理过程和工具调用记录成结构化数据。第二追踪、数据集、评估三位一体才能形成完整闭环。单点工具只能解决局部问题被 Jason Liu 这类技术专家看中的工具往往是能把“记录请求、沉淀用例、批量验证”串成工程流水线的方案。第三这套工作流最大的价值是把 AI 应用开发从“玄学”变成了“工程”。你不再需要依赖主观感觉来判断 Prompt 改得好不好而是用测试集和评估分数来支撑每一个决策。如果你正在做 LLM 应用开发建议按下面的路径继续深入先把追踪能力接进你的项目记录一周线上请求看看真实流量长什么样。从线上请求中挑出 20 个代表性用例构建你的第一个数据集。在数据集上跑一次基线评估记录当前水平。然后开始迭代改 Prompt、调参数、加工具每次改动都用评估分数验证效果。一段时间后你手里就有了属于自己业务的“模型行为基准库”团队协作时也能用数据说话而不是靠争论。这整套方法论比任何单一工具都更值得长期投入。工具可以替换但“观测 → 沉淀 → 评估 → 迭代”的工程闭环不会过时。 LLM应用可观测性实战：从追踪到评估的工程闭环
1. 这篇文章真正要解决的问题如果你最近关注 AI 工程化方向的技术动态可能已经在社区里看到过 Jason Liu 对某些工具的高度评价。作为在可观测性、LLM 应用开发和 AI Agent 工程实践领域都有深厚积累的技术专家Jason Liu 的评价在开发者社区里往往有比较强的风向标意义。但这里要先给一个判断与其纠结“哪个工具被盛赞”不如拆解“这个工具到底解决了什么开发痛点”。因为 AI 工具迭代速度极快今天被盛赞的工具三个月后可能就被新方案替代。真正值得沉淀的是这类工具为何能获得一线工程师认可以及它的设计思路能给我们自己的项目带来什么启发。从材料看Jason Liu 盛赞的这款工具核心价值集中在AI 代理Agent开发与调试效率上。如果你正在做 LLM 应用、搭过 Agent 工作流或者被“模型行为不可控”“调试链路不透明”“测试用例难维护”这些问题折磨过那这篇文章就是为你准备的。读完这篇文章你会得到四个层面的收获理解这类工具在 AI 工程链路中的定位以及它和传统调试工具的本质差异。掌握它的核心概念搞清楚“追踪Tracing”“评估Evaluation”“数据集Dataset”这些术语到底在解决什么。通过一个可落地的示例亲手跑通“接入工具 → 构建测试用例 → 评估模型输出 → 优化提示词”的完整流程。避开我在实际工程中最常看到的误区和坑包括版本兼容、成本控制、测试集设计等。2. 被盛赞的工具到底在解决什么AI 工程的可观测性危机2.1 传统开发调试逻辑在 LLM 应用里失效了先看一个很典型的场景。你写了一个传统后端接口输入参数不对日志打印出来一查就能定位。原因很明确要么是空指针要么是 SQL 写错要么是下游服务超时。这类问题有一个共同特征代码执行路径是确定的错误是可复现的。但到了 LLM 应用领域这个逻辑彻底失效了。同样是“用户输入”同一个 Prompt同一个模型温度调到 0.2 和 0.8输出可能完全不同。更头疼的是即使温度设成 0不同版本的模型、不同的上下文长度、甚至同一次请求中不同的 token 采样都可能让结果出现肉眼可见的差异。这意味着什么意味着你没法再用“看日志、查异常”的方式去定位问题。你根本不知道模型为什么给出了这个回答是哪一段上下文影响了它的判断还是它的“幻觉”机制在起作用。2.2 流程编排让问题更难定位再叠加一层流程编排。现在的 AI 应用很少是“一个 Prompt 走天下”基本都是多步骤的 Agent 工作流先做意图识别再调用工具检索知识库然后把结果拼接成上下文最后让模型生成回答。任何一个中间节点的输出有问题都会传导到最终结果。更麻烦的是LLM 的“软错误”不像传统代码的“硬错误”那么明显。传统代码错了就是抛异常但 LLM 应用经常是“能跑通但结果不对”或者“能给出答案但推理链路是错的”。这种场景下你需要的不是传统日志而是一种能够完整还原 LLM 请求链路、记录中间每一步输入输出、并把多个请求关联成测试集进行批量评估的工具。这就是 Jason Liu 盛赞这类工具的根本原因它把 AI 应用开发从“盲人摸象”变成了“可视化手术”。2.3 一个关键概念LLM 可观测性你可能听过“可观测性Observability”这个词传统分布式系统里它指的是通过日志、指标、追踪来理解系统状态。但 LLM 可观测性有本质区别传统可观测性关注“系统是否健康”延迟、错误率、CPU 使用率。LLM 可观测性关注“模型行为是否符合预期”推理链路、上下文使用、输出质量。这意味着你不能只监控系统指标还必须监控语义层面的信息。比如用户这次输入被路由到了哪个意图分类Agent 在检索知识库时是否找到了相关文档模型最终生成时采用了哪一段上下文如果输出质量差是 Prompt 设计问题、检索质量差还是模型能力不足这些问题有一个共同点它们都需要把请求链路完整记录下来然后从语义层面进行分析。这正是被盛赞工具的核心设计目标。3. 核心概念从一个示例任务说起在进入实操之前先把概念讲透。我建议用一个具体的示例来理解整套机制。假设你要做一个“智能客服助手”用户输入“我想查询订单状态”应用流程识别意图 → 调用订单系统 API → 获取订单信息 → 模型生成回复这个流程看似简单实际工程化后会遇到几个典型问题问题一怎么知道每个环节用了多长时间如果整体响应变慢是模型推理慢还是 API 调用慢没有链路追踪你只能靠猜。问题二怎么知道模型回答得对不对“你的订单已发货预计 3 天内到达”这个回答怎么判断对错“发货状态”是否真的来自订单系统模型是否编造了物流信息问题三改了 Prompt 之后怎么确认效果真的变好了凭感觉测试三五个用例还是用一个固定测试集跑一遍量化对比改进前后的得分这时候被盛赞的工具提供了一套完整的解决方案核心由以下模块组成模块作用类比传统开发Tracing追踪记录每次 LLM 调用的完整链路包括输入、输出、token 用量、延迟分布式链路追踪Dataset数据集把测试用例组织成可复用的数据集支持从线上请求导入单元测试用例集Evaluation评估用规则或 LLM 作为裁判批量评估模型输出质量自动化测试断言Prompt Management提示词管理管理不同版本的 Prompt对比效果差异代码版本管理这四块组合起来就形成了一个完整的工作闭环先把应用接入追踪记录所有线上请求。从线上请求中筛选出代表性用例保存为数据集。在数据集上批量运行评估找到问题集中的方向。调整 Prompt 或应用逻辑再次运行评估对比分数变化。现在你可能理解了这个工具不是单纯“追踪”或“评估”而是把追踪、数据、评估串成了一条工程流水线。这比单点工具的价值高得多也是它能获得 Jason Liu 这类技术专家认可的关键原因。4. 环境准备在本地把最小闭环跑起来这部分我们进入实操。要完整演示整个工作闭环需要一个支持 LLM 应用开发的环境。这里的思路是通用的你可以替换成自己熟悉的技术栈。4.1 技术栈选择与版本说明为了让你能顺利复现我选择了以下技术栈Python 3.10 及以上版本当前主流 LLM 应用开发语言OpenAI 兼容 API你可以使用 OpenAI、或其他兼容 OpenAI 接口的模型服务LangChain 作为 LLM 应用开发框架用于快速搭建 Agent 工作流被盛赞的工具本身下文以“该工具”代指因为不同生态下同类工具接入方式略有差异版本说明本文不绑定具体版本号因为相关 SDK 更新非常频繁。建议你在运行以下命令时以官方最新稳定版本为准。4.2 安装核心依赖建议先创建一个独立的 Python 虚拟环境python3 -m venv venv source venv/bin/activate然后安装核心依赖pip install openai langchain langchain-openai如果你要接入该工具的服务端通常还需要安装对应的 SDK。以当前主流的同类工具为例pip install langfuse如果你的团队用的是另一个类似工具比如 Helicone、LangSmith安装方式大同小异核心都是“安装 SDK → 配置环境变量 → 在框架中设置回调”。4.3 配置环境变量在项目根目录创建.env文件# 模型服务相关配置 OPENAI_API_KEYsk-your-api-key OPENAI_BASE_URLhttps://api.openai.com/v1 # 该工具服务端配置 LANGFUSE_PUBLIC_KEYyour-public-key LANGFUSE_SECRET_KEYyour-secret-key LANGFUSE_HOSThttps://cloud.langfuse.com需要注意千万别把密钥提交到 Git 仓库。在.gitignore中加入.env这是最基本的工程素养。4.4 验证连接写一个最简单的测试脚本确认 SDK 能正常连接# 文件路径test_connection.py from langfuse import Langfuse langfuse Langfuse() # 创建一个简单的 trace 验证连接 trace langfuse.trace(nametest-connection) trace.update(outputOK) print(连接成功Trace ID:, trace.id)运行python test_connection.py如果终端打印出 Trace ID说明连接正常可以进入下一步。这里要特别说明如果你用的是本地自托管版本需要先把服务端跑起来。常见做法是用 Docker 一键启动docker run -d --name lf-server \ -p 3000:3000 \ -e NODE_ENVproduction \ ghcr.io/langfuse/langfuse:latest具体命令以你使用的工具官方文档为准。5. 完整示例搭建一个带追踪和评估的智能客服现在进入核心部分。我们搭建一个最小可用的“订单查询 Agent”并把它接入追踪和评估系统。5.1 第一步定义工具函数我们需要一个简单的“查询订单状态”工具# 文件路径tools.py import json import random def get_order_status(order_id: str) - str: 模拟查询订单状态 # 实际项目中这里会调用真实的订单系统 API statuses [已发货, 配送中, 已签收, 待发货] status random.choice(statuses) return json.dumps({order_id: order_id, status: status})这个函数模拟了真实业务中的 API 调用。在实际项目中你只需要把函数体替换成真实的 HTTP 请求即可。5.2 第二步搭建 Agent 工作流使用 LangChain 构建一个简单的 Agent 流程# 文件路径agent.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_openai_functions_agent from langchain.prompts import ChatPromptTemplate from langchain.tools import Tool from tools import get_order_status load_dotenv() # 初始化 LLM llm ChatOpenAI( modelgpt-4o-mini, # 以你的模型服务为准 temperature0.0, ) # 定义工具 tools [ Tool( nameget_order_status, funcget_order_status, description根据订单 ID 查询订单的物流状态, ) ] # 定义提示词 prompt ChatPromptTemplate.from_messages([ (system, 你是一个电商客服助手。请根据用户的问题使用工具查询订单状态 并用亲切的口吻回复用户。如果用户没有提供订单号请引导用户提供。), (human, {input}), (placeholder, agent_scratchpad), ]) # 创建 Agent agent create_openai_functions_agent( llmllm, toolstools, promptprompt, ) agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations3, )这里的关键配置是create_openai_functions_agent它让 LLM 能够自主决定何时调用工具、调用哪个工具、以及如何解读工具返回结果。5.3 第三步接入追踪回调这是被盛赞工具发挥作用的关键一步。我们需要把追踪能力接入 Agent 执行过程# 文件路径agent_with_tracing.py from langfuse.callback import CallbackHandler from agent import agent_executor # 创建 Langfuse 回调处理器 langfuse_handler CallbackHandler( public_keyyour-public-key, secret_keyyour-secret-key, hosthttps://cloud.langfuse.com, ) # 执行 Agent并传入回调 response agent_executor.invoke( {input: 你好我想查一下订单 10086 的物流状态}, config{callbacks: [langfuse_handler]}, ) print(response[output])此时你的每一次 AI 应用调用都会被完整记录下来。在服务端界面上你能看到用户输入原文模型完整推理过程工具调用参数和返回结果每个环节的耗时与 token 消耗这一步做完你就拥有了“AI 应用请求的 X 光机”。5.4 第四步构建评估数据集有了追踪能力后我们下一步要做的是构建评估数据集。数据集构建有两种方式方式一从线上请求导入登录服务端控制台找到刚才产生的 Trace 记录把有代表性的请求保存到数据集中。这种方式最省力也最贴近真实业务分布。方式二手工构建测试用例更推荐的方式是把典型用户问题和“期望行为”手动组织成数据集# 文件路径build_dataset.py from langfuse import Langfuse from langfuse.client import Dataset langfuse Langfuse() # 创建数据集 dataset langfuse.create_dataset(nameorder_query_test, description订单查询场景测试集) # 添加测试用例 dataset.create_item( input{input: 你好我想查一下订单 10086 的物流状态}, expected_output要求包含该订单的物流状态信息并在信息不足时引导用户补充 ) dataset.create_item( input{input: 我的快递到哪了}, expected_output模型应该询问用户提供订单号而不是自行猜测 ) dataset.create_item( input{input: 帮我查一下 12345 号订单}, expected_output要求模型调用 get_order_status 工具 )这里的关键点是测试用例不应该只写“期望的输出文本”更要想清楚“期望的行为链路”。因为 LLM 应用评估关注的不只是答案对不对更关注过程对不对。5.5 第五步运行批量评估数据集构建完成后在服务端控制台配置评估器Evaluator或者通过 SDK 批量运行。核心代码如下# 文件路径run_evaluation.py from langfuse import Langfuse from agent import agent_executor langfuse Langfuse() # 获取数据集 dataset langfuse.get_dataset(order_query_test) # 定义一个评估函数 def evaluate_output(output_text: str, expected: str) - bool: 简单判断输出是否包含关键信息 # 实际项目中可以用 LLM 作为裁判或使用更复杂的规则 keywords [订单, 状态, 已发货, 配送中, 签收] return any(kw in output_text for kw in keywords) # 遍历数据集运行评估 for item in dataset.items: result agent_executor.invoke(item.input) score evaluate_output(result[output], item.expected_output) print(f用例 {item.id}: 得分 {score})这一步的意义在于把主观的“模型回答得好不好”转化为客观、可量化的分数。当你的 Prompt 改动影响模型行为时系统会通过分数变化告诉你“变好了还是变差了”。6. 运行结果与效果验证6.1 预期输出运行agent_with_tracing.py后终端会输出类似内容 Entering new AgentExecutor chain... Invoking: get_order_status with {order_id: 10086} Order status: {order_id: 10086, status: 配送中} 你好您的订单 10086 当前正在配送中请耐心等待预计很快就能到达。如果您还有其他问题随时告诉我哦同时在服务端控制台能看到完整的 Trace 详情包括Trace Name: AgentExecutor 的执行链路Spans: 对 LLM 调用和工具调用的分别记录Token Count: 输入、输出 token 数Latency: 每个节点耗时6.2 如何判断成功从三个层面判断第一层功能层面。用户的问题被正确识别工具被调用模型返回了包含订单状态的回复。第二层可观测层面。在服务端界面能看到完整链路每步耗时和 token 消耗一目了然。如果响应慢你可以立刻定位是模型推理慢还是工具调用慢。第三层可评估层面。在数据集上运行评估后你能得到所有测试用例的通过/失败情况。如果在 3 个用例中有一个失败你能立刻看到失败用例的完整链路从而判断是 Prompt 问题还是工具调用问题。6.3 失败排查第一原则如果运行失败第一步不要急着改代码先看服务端界面的 Trace 详情。因为如果是 API 密钥错误Trace 里会有 HTTP 401 错误。如果是模型中转服务超时Trace 里会显示耗时异常。如果是工具调用失败Trace 里会记录异常堆栈。你不需要猜直接看链路数据就知道问题在哪。7. 常见问题与排查思路基于我在实际工程中的经验以及社区中高频出现的问题整理成下面的排查表问题现象可能原因排查方式解决方案连接服务端失败API 密钥配置错误检查环境变量是否加载、公钥密钥是否配对重新复制密钥确认.env文件被正确加载Trace 记录只有一部分回调没有传给所有执行路径检查是否在所有 AgentExecutor 调用里都传入了 callback封装公共调用函数统一注入回调追踪数据量太大请求量高全部记录成本过高查看服务端的采样配置开启采样率设置如只记录 10% 的请求评估结果不准评估规则设计不当检查评估器使用的模型和提示词引入 LLM 作为裁判或使用更细粒度的评估规则数据集用例重复从线上导入时未去重检查数据集的去重逻辑按用户输入哈希去重或按 trace 属性过滤上下文追溯困难没有保存中间步骤输出查看 Trace 的 span 是否完整在关键步骤增加langfuse_context.update_current_span记录自定义属性生产环境密钥泄露密钥被硬编码在代码中检查 Git 历史与环境变量立即轮换密钥使用密钥管理服务多环境数据混淆开发/生产使用同一个项目检查 SDK 初始化的是否同一个 project为不同环境创建独立项目或添加环境标签8. 最佳实践与工程建议8.1 从追踪开始而不是从评估开始很多团队一上来就搭建复杂的评估系统结果发现测试用例设计不合理、评估指标不清晰整个系统荒废掉了。更稳妥的路线是先接入追踪跑几天生产流量看看真实请求长什么样。当你对线上流量模式有感觉之后再从中挑选代表性用例构建数据集。最后才搭建评估器。理由很简单评估的前提是理解问题而追踪是理解问题的最短路径。8.2 数据集要覆盖“典型场景”和“边界场景”好的测试集应该包含三类用例烤羊肉串用例业务中最常见的 10 到 20 个请求形态。烤焦用例用户输入模糊、缺少关键信息、意图不明确的情况。奇葩用例恶意输入、超长文本、特殊字符、多语言混用。这三类用例各有用途常规用例保证基本盘不崩边界用例暴露模型短板恶意用例保证安全边界不被突破。8.3 评估器设计规则和 LLM-as-Judge 结合评估器设计没有银弹。最稳妥的做法是分层# 文件路径evaluator.py def hybrid_evaluate(output_text: str, expected: str, trace_data: dict) - dict: 混合评估器规则 LLM 判断 # 第一层规则判断成本低速度快 rule_score 0 if 订单 in output_text: rule_score 0.5 if 状态 in output_text: rule_score 0.5 # 第二层如果规则判断不通过再用 LLM 判断 if rule_score 1.0: # 这里调用 LLM 进行语义相似度判断 llm_score judge_with_llm(output_text, expected) return {rule_score: rule_score, llm_score: llm_score} return {rule_score: rule_score, llm_score: None}规则评估的好处是成本低、可解释性强适合做快速过滤。LLM 评估的好处是能理解语义适合判断“虽然用词不一样但意思一致”的情况。两者结合才能在成本和效果之间取得平衡。8.4 控制成本采样策略AI 应用的可观测性也有成本问题。每次请求的 trace 都会消耗 token 和存储资源。对于高流量业务不需要记录每一个请求更推荐“全量记录 抽样分析”的组合策略生产环境全量记录基础信息耗时、状态码、token 数抽样记录详细链路比如 10%。开发环境全量记录详细链路方便调试。大多数可观测性工具都支持采样配置建议把采样率做成环境变量而不是硬编码。8.5 用数据驱动 Prompt 优化而不是凭感觉传统开发里“这个函数性能不好”可以通过 profiler 定位。但在 LLM 应用开发里很多团队优化 Prompt 全凭感觉。今天觉得“加一句 system prompt 应该会更好”明天觉得“few-shot 例子再多几个”。被盛赞工具揭示了一个新的工作方式先在数据集上跑一次评估拿到基线分数。修改 Prompt。在同一个数据集上再次评估。对比分数变化判断修改是否有效。这就把“我觉得改得更好了”变成了“数据表明改得更好了”。这个转变是 LLM 应用开发走向成熟的分水岭。9. 总结与后续学习方向写到这里这篇文章的核心观点可以收束为三点第一LLM 应用开发最大的痛点不是“模型不够聪明”而是“过程不可见”。模型输出的质量无法用传统日志体系监控这时候需要一套专门面向 LLM 链路的可观测性工具把每一次请求的推理过程和工具调用记录成结构化数据。第二追踪、数据集、评估三位一体才能形成完整闭环。单点工具只能解决局部问题被 Jason Liu 这类技术专家看中的工具往往是能把“记录请求、沉淀用例、批量验证”串成工程流水线的方案。第三这套工作流最大的价值是把 AI 应用开发从“玄学”变成了“工程”。你不再需要依赖主观感觉来判断 Prompt 改得好不好而是用测试集和评估分数来支撑每一个决策。如果你正在做 LLM 应用开发建议按下面的路径继续深入先把追踪能力接进你的项目记录一周线上请求看看真实流量长什么样。从线上请求中挑出 20 个代表性用例构建你的第一个数据集。在数据集上跑一次基线评估记录当前水平。然后开始迭代改 Prompt、调参数、加工具每次改动都用评估分数验证效果。一段时间后你手里就有了属于自己业务的“模型行为基准库”团队协作时也能用数据说话而不是靠争论。这整套方法论比任何单一工具都更值得长期投入。工具可以替换但“观测 → 沉淀 → 评估 → 迭代”的工程闭环不会过时。