企业官网建设流程全解析

1. 从Demo惊艳到上线翻车：AI智能体交付的断层在哪里

做过AI智能体项目的人大概都有类似的体验：在PoC阶段，用几十条精心挑选的测试用例跑一遍，效果惊艳，团队信心满满，老板拍板推进。可一旦进入真实业务流量，各种问题就像开闸的水一样涌出来——有的用户问法稍微绕一点，智能体就开始胡言乱语；有的工具调用在测试环境好好的，到了生产环境因为接口超时直接卡死；更让人头疼的是，你根本不知道它为什么出错，因为整个链路就像一个黑盒，输入进去、输出出来，中间发生了什么全靠猜。

这个断层不是模型能力的问题，而是工程化交付的问题。PoC阶段关注的是“能不能做出来”，生产阶段关注的是“能不能稳定地做对”。这两件事之间的鸿沟，需要用评测体系和可观测性来填。评测解决的是“怎么知道它做得好不好”，可观测性解决的是“它为什么做得不好”。两者缺一不可，而且必须从PoC阶段就开始搭，不能等到上线前才临时抱佛脚。

我见过太多团队在PoC阶段只关注“跑通”，把评测简化成人工看几条case，把日志简化成print大法。结果到了生产环境，面对每天几千上万次调用，既没有自动化的质量度量，也没有细粒度的链路追踪，出了问题只能靠用户截图反馈来定位。这种状态下，智能体的迭代基本靠玄学，今天修好一个bug，明天可能又引入两个新问题。

所以这篇文章想聊的，就是怎么在AI智能体项目里，从第一天起就把评测和可观测性当成基础设施来建。不是那种“等有空了再补”的附属品，而是和业务逻辑同等重要的核心组件。我会从评测集的设计、评测方法的选型、可观测性的埋点策略、链路追踪的实现、以及生产环境的持续监控这几个维度展开，尽量把每个环节的“为什么”和“怎么做”都讲清楚。

2. 评测集不是测试用例的堆砌：构建能反映真实分布的Agent评测体系

2.1 为什么传统测试用例在Agent场景下不够用

传统软件测试的思路是：给定输入，验证输出是否等于预期。这套逻辑在确定性系统里很好用，但放到AI智能体上就完全失效了。因为智能体的输出不是确定性的，同一个问题换一种问法，可能得到完全不同的回答；同一个回答在不同上下文里，正确性判断标准也不一样。更麻烦的是，智能体往往涉及多轮对话和工具调用，中间任何一步出偏差，最终结果就可能南辕北辙。

我刚开始做Agent评测的时候，也犯过“把测试用例当评测集”的错误。当时整理了200条问答对，每条都有标准答案，跑完一看准确率85%，觉得还不错。结果上线后发现用户的实际问法千奇百怪，那200条用例覆盖的场景连真实流量的20%都不到。后来复盘才明白，评测集的核心不是“数量”，而是“分布”。它必须能反映真实用户请求的多样性，包括不同的问法、不同的意图组合、不同的上下文长度、不同的工具调用路径。

2.2 评测集的四个维度：意图覆盖、难度分层、对抗样本、边界条件

一个能打的Agent评测集，至少要从四个维度来构建。第一个维度是意图覆盖，也就是用户可能提出的所有任务类型。比如一个客服智能体，意图可能包括查订单、退换货、咨询政策、投诉建议等，每个意图下还要细分不同的子场景。这个维度决定了评测集的广度。

第二个维度是难度分层。同样是查订单，有的用户直接给订单号，有的用户说“我上周买的那双鞋”，有的用户说“帮我看看最近那个快递到哪了”。难度从低到高，评测集里都要有。我通常会把难度分为L1到L4四档：L1是明确指令，L2是隐含意图，L3是多轮澄清，L4是模糊或矛盾需求。生产环境里L3和L4的比例往往比我们想象的高得多。

第三个维度是对抗样本。这是最容易被忽略但最重要的部分。对抗样本包括：故意诱导智能体犯错的提问、包含错误前提的问题、带有情绪或攻击性的表达、以及试图绕过安全限制的尝试。这些样本不一定多，但必须有，因为它们暴露的是系统的鲁棒性边界。

第四个维度是边界条件。比如超长输入、空输入、特殊字符、多语言混合、工具调用失败后的降级路径等。这些场景在PoC阶段很少遇到，但在生产环境里迟早会出现。

2.3 评测集的动态维护：从生产流量中回流bad case

评测集不是建完就完了，它必须是一个活的东西。我的做法是建立一个bad case回流机制：生产环境里每次用户反馈“答得不对”或者人工抽检发现问题的case，都自动进入待评估队列，经过脱敏和标注后，定期补充到评测集里。这样评测集就能跟着真实流量的变化一起进化。

具体操作上，可以在Agent的响应链路里加一个“用户反馈”入口，或者在客服系统里标记异常会话。每周花半小时把这些case过一遍，判断是模型问题、提示词问题、还是工具问题，然后决定是否加入评测集。这个习惯坚持三个月，评测集的覆盖度和杀伤力会有质的提升。

注意：回流bad case时一定要做脱敏处理，去掉用户隐私信息，同时要避免把个例当成普遍问题。我的经验是，同一个问题模式出现三次以上，才值得加入评测集。

3. 自动评测与人工评测怎么分工：Agent评测方法的选型与组合

3.1 规则匹配、模型打分、人工评估的适用边界

Agent评测的方法大致分三类：规则匹配、模型打分、人工评估。这三类不是互斥的，而是要根据场景组合使用。规则匹配适合有明确答案的场景，比如工具调用是否成功、返回格式是否符合预期、关键信息是否提取正确。它的优点是快、便宜、可重复，缺点是只能覆盖确定性部分。

模型打分适合评估开放性回答的质量，比如回答是否流畅、是否切题、是否有帮助。通常的做法是用一个更强的模型作为“裁判”，给Agent的输出打分。这里有个坑：裁判模型和被评模型如果同源，可能会有偏好偏差。我一般会用不同厂商的模型来做裁判，或者至少用不同版本的模型。

人工评估适合评估主观性强、规则难以描述的场景，比如语气是否得体、是否体现了同理心、复杂多轮对话的整体体验。人工评估的成本最高，所以通常只用于抽样验证和校准自动评测的结果。

3.2 用LLM-as-Judge做规模化评测的实操细节

LLM-as-Judge是目前最实用的规模化评测手段，但要用好并不简单。首先，裁判提示词的设计很关键。不能简单地说“请给这个回答打分”，而要给出明确的评分维度和评分标准。比如我会把评分拆成三个维度：准确性（信息是否正确）、完整性（是否覆盖了用户所有问题）、安全性（是否有不当内容）。每个维度1-5分，最后加权汇总。

其次，要控制裁判模型的“宽容度”。实测发现，如果不加约束，裁判模型倾向于给高分。解决办法是在提示词里加入“如果你给满分，请说明为什么这个回答无可挑剔”这样的要求，迫使裁判模型更严格地审视。另外，可以定期用人工标注的数据来校准裁判模型的打分分布，如果发现裁判模型给分普遍偏高，就调整提示词或换一个更严格的裁判模型。

还有一个细节是位置偏差。当让裁判模型对比两个回答时，它往往倾向于选择第一个或第二个。解决办法是随机打乱顺序，或者做双向对比取平均。这个坑我在早期项目中踩过，后来加了随机化之后，评测结果的稳定性明显提升。

3.3 人工评测的抽样策略与标注规范

人工评测虽然贵，但不能完全省掉。我的做法是：每次迭代从评测集里分层抽样50-100条，覆盖所有意图和难度层级，由2-3个标注员独立评估，然后计算标注一致性。如果一致性低于80%，说明评分标准不够清晰，需要重新对齐。

标注规范要写得足够细。比如“准确性”这一项，要明确什么算“完全正确”、什么算“部分正确”、什么算“错误”。最好每个等级都有示例。我见过很多团队的人工评测结果不可用，就是因为标注员对标准的理解不一致，同一条case两个人给出的分数差了两分。

提示：人工评测的结果不要只用来算一个总分，要保留每条case的详细标注。这些标注数据是校准自动评测的宝贵资源，也是分析Agent弱点的直接依据。

4. 可观测性不是加日志：Agent链路的埋点设计与追踪实现

4.1 Agent可观测性的特殊性：多轮、多工具、多模型

传统服务的可观测性主要关注请求量、延迟、错误率这些指标，但Agent的可观测性要复杂得多。因为一个用户请求进来，可能触发多轮模型调用、多次工具调用、多次知识库检索，每一步都有输入输出，每一步都可能出错。如果只记录最终的输入输出，中间过程就是黑盒，出了问题根本没法定位。

我通常会把Agent的链路拆成几个关键节点：意图识别、对话管理、工具选择、工具调用、结果生成。每个节点都要记录输入、输出、耗时、状态。这样当最终结果不对时，可以逐节点排查，看是哪一步偏了。比如用户问“帮我退掉上周买的鞋”，如果最终回答是“找不到订单”，你可以看是意图识别错了（识别成了查订单），还是工具调用失败了（订单查询接口超时），还是结果生成错了（查到了但没正确表述）。

4.2 埋点数据模型：Trace、Span、Event的三层结构

参考分布式追踪的成熟经验，Agent的可观测性也可以用Trace、Span、Event三层结构来组织。一个用户请求对应一个Trace，Trace下面有多个Span，每个Span代表一个处理节点，Span里面可以记录多个Event，代表节点内的关键事件。

具体来说，Trace级别记录会话ID、用户ID、开始时间、总耗时、最终状态。Span级别记录节点名称、输入、输出、耗时、状态、使用的模型或工具。Event级别记录更细粒度的事件，比如“模型返回了工具调用请求”、“工具调用超时”、“触发了降级策略”等。

这种结构的优势是既能宏观地看整体链路，又能微观地定位具体问题。而且和现有的分布式追踪系统（如OpenTelemetry）兼容，可以直接接入现有的监控平台。

# 一个简化的Agent埋点示例 trace = { "trace_id": "abc123", "session_id": "sess_456", "user_id": "user_789", "start_time": "2024-01-15T10:00:00Z", "spans": [ { "span_id": "span_1", "name": "intent_recognition", "input": "帮我退掉上周买的鞋", "output": {"intent": "return_goods", "confidence": 0.92}, "duration_ms": 320, "status": "success" }, { "span_id": "span_2", "name": "tool_call", "tool": "order_query", "input": {"user_id": "user_789", "time_range": "last_week"}, "output": {"order_id": "ORD_001", "status": "delivered"}, "duration_ms": 1500, "status": "success" }, { "span_id": "span_3", "name": "response_generation", "input": {"order_info": {"order_id": "ORD_001"}}, "output": "已为您找到上周购买的订单，是否确认退货？", "duration_ms": 800, "status": "success" } ], "total_duration_ms": 2620, "status": "success" }

4.3 关键指标的定义与采集：延迟、成功率、工具调用准确率

可观测性不只是记录链路，还要定义和采集关键指标。对于Agent来说，我重点关注这几类指标：

延迟指标：端到端延迟、各节点延迟、模型调用延迟、工具调用延迟。延迟的P99比平均值更重要，因为长尾延迟直接影响用户体验。

成功率指标：整体成功率、各节点成功率、工具调用成功率、模型调用成功率。成功率要分维度看，比如按意图分、按用户分、按时间段分。

质量指标：工具调用准确率（是否调用了正确的工具）、参数提取准确率（工具参数是否正确）、回答相关性（是否切题）。这些指标需要结合评测体系来计算。

成本指标：每次会话的token消耗、模型调用次数、工具调用次数。成本指标在规模化之后会变得非常重要。

这些指标最好能实时采集并展示在监控面板上，这样一旦出现异常，能第一时间发现。我通常会在监控面板上设置几个告警规则：端到端P99延迟超过阈值、工具调用成功率低于阈值、单次会话token消耗超过阈值。告警触发后，再通过Trace链路去定位具体原因。

5. 生产环境的持续监控：从被动救火到主动发现

5.1 在线评测：用生产流量实时计算质量指标

评测不应该只发生在离线阶段，生产环境同样需要在线评测。做法是在Agent的响应链路里嵌入轻量级的评测逻辑，对每次响应实时计算质量指标。比如可以用一个小模型快速判断回答是否切题、是否有害、是否包含关键信息。这些指标不需要100%准确，但能提供实时的质量趋势。

在线评测的另一个用途是异常检测。如果某个时间段内质量指标突然下降，可能意味着上游数据分布发生了变化，或者某个工具接口出了问题。这种主动发现比等用户投诉要快得多。

5.2 告警策略：什么值得告警，什么只是噪音

告警策略的设计很考验经验。告警太多，团队会麻木；告警太少，又会漏掉关键问题。我的原则是：只对影响用户体验和业务指标的问题告警。具体来说，端到端成功率低于95%、P99延迟超过5秒、工具调用失败率超过10%、单次会话成本超过预算，这些值得告警。而单个节点的偶发超时、个别用户的异常输入，这些先记录不告警，等积累到一定量再分析。

告警的阈值不要拍脑袋定，最好基于历史数据来定。比如先跑一周，看各项指标的正常波动范围，然后把阈值设在正常范围的边界上。另外，告警要分级：P0是影响核心功能的，需要立即处理；P1是影响部分用户的，当天处理；P2是体验优化的，排期处理。

5.3 根因定位：从Trace链路快速缩小问题范围

当告警触发后，下一步就是根因定位。这时候Trace链路的价值就体现出来了。我通常的排查顺序是：先看整体成功率，确定是全局问题还是局部问题；然后按意图、按工具、按模型版本分组，看问题集中在哪个维度；最后挑几条失败的Trace，逐Span看是哪一步出了问题。

举个例子，如果发现“退换货”意图的成功率突然下降，而其他意图正常，那问题很可能出在退换货相关的工具或提示词上。再看Trace，如果发现工具调用成功率正常但结果生成失败率升高，那可能是模型版本更新导致的。这种逐层缩小的排查方式，比盲目看日志要高效得多。

注意：Trace数据的保留时间要合理设置。全量保留成本太高，但只保留几天又不够排查历史问题。我的做法是：最近7天全量保留，7天到30天只保留失败的Trace和抽样成功的Trace，30天以上只保留聚合指标。

6. 评测与可观测性的联动：让数据闭环驱动Agent迭代

6.1 从监控发现异常到评测集补充case的自动化路径

评测和可观测性不是两套独立的系统，它们应该形成一个闭环。生产监控发现异常case，自动进入评测集，评测结果指导下一轮迭代，迭代后的版本再通过评测验证，然后上线接受生产监控。这个闭环转得越快，Agent的进化速度就越快。

具体实现上，可以在监控系统里设置规则：当某个Trace的最终状态为失败，或者在线评测分数低于阈值时，自动将该case脱敏后推送到评测集的待审核队列。人工审核确认后，加入评测集。这样评测集就能持续吸收生产环境的新问题，保持杀伤力。

6.2 版本迭代中的回归验证：新版本上线前的评测门禁

每次Agent版本迭代，无论是改提示词、换模型、还是加工具，都必须过评测门禁。门禁的规则可以设定为：核心评测集的整体分数不能低于上一版本，关键意图的分数不能下降超过2%，对抗样本的通过率不能低于阈值。只有全部通过，才允许上线。

这个门禁机制听起来简单，但执行起来需要纪律。我见过不少团队因为赶进度而跳过评测，结果上线后出问题再回滚，反而更浪费时间。我的建议是把评测门禁做成CI/CD流水线的一部分，自动触发、自动判断、自动阻断，减少人为干预的空间。

6.3 成本与质量的平衡：用可观测性数据指导模型选型

可观测性数据不仅能用来排查问题，还能指导模型选型。比如通过分析不同模型版本在相同评测集上的表现，可以量化每个模型的质量-成本比。有些场景用大模型效果只比小模型好一点点，但成本高好几倍，那就可以考虑降级到小模型。有些场景小模型搞不定，那就必须用大模型。

我通常会做一个模型选型矩阵，横轴是质量指标，纵轴是成本指标，把各个候选模型画上去，然后根据业务对质量和成本的容忍度来选择。这个矩阵的数据来源就是评测结果和可观测性数据。有了这个矩阵，模型选型就不再是拍脑袋，而是有数据支撑的决策。

这张表在实际项目中非常有用。比如我们发现意图识别用中模型B就够了，没必要用大模型A，一年下来能省不少成本。而结果生成环节因为对质量要求高，还是得用大模型A。这种精细化的分工，就是靠评测和可观测性数据来支撑的。

7. 踩过的坑与实战心得

7.1 评测集过拟合：为什么你的评测分数涨了但线上效果没变

这是我最开始做Agent评测时踩的最大的坑。当时团队花了两周时间精心构建了一个500条的评测集，然后针对这个评测集反复调优提示词，看着分数从70%涨到90%，大家都很开心。结果上线后发现用户满意度几乎没有变化。复盘才发现，我们过度拟合了评测集——提示词里加了很多针对特定case的规则，但这些规则在真实流量里根本不通用。

避免过拟合的方法有几个：一是评测集和训练/调优数据要严格分开，调优时不能看评测集的详细结果，只能看聚合分数；二是定期用新回流的case替换评测集里的旧case，保持评测集的新鲜度；三是除了看总分，还要看各维度的分数分布，如果某个维度的分数异常高但其他维度没变，可能是过拟合的信号。

7.2 可观测性数据的存储成本：全量记录还是采样记录

可观测性数据量很大，全量记录成本很高。我一开始也是全量记录，结果一个月下来存储费用超预算好几倍。后来改成分层采样策略：失败的Trace全量记录，成功的Trace按10%采样，关键节点（如工具调用）全量记录，非关键节点（如中间状态）只记录摘要。这样既保证了排查问题时有足够的数据，又把成本控制在了合理范围。

另外，数据的保留时间也要分层。最近7天的数据查询频率最高，保留全量；7-30天的数据查询频率下降，只保留聚合和失败样本；30天以上的数据基本只用于趋势分析，保留聚合指标就够了。

7.3 工具调用超时的降级策略：可观测性如何帮你设计兜底方案

工具调用超时是Agent生产环境里最常见的问题之一。没有可观测性的时候，你只知道“工具调用失败了”，但不知道失败率多高、哪些工具容易失败、失败后用户经历了什么。有了可观测性数据之后，你可以量化每个工具的失败率和延迟分布，然后针对性地设计降级策略。

比如我们发现订单查询接口的P99延迟是3秒，失败率2%。针对这个，我们设计了三级降级：第一级是重试一次，第二级是返回缓存数据并提示“信息可能有延迟”，第三级是转人工客服。这个降级策略上线后，工具调用相关的用户投诉下降了70%。如果没有可观测性数据，我们可能只会做一个简单的“失败就报错”，用户体验会差很多。

7.4 多轮对话的评测难点：如何判断“追问”是澄清还是跑偏

多轮对话的评测比单轮难得多，因为“正确”的标准变得模糊了。比如用户问“帮我退掉上周买的鞋”，Agent追问“请问是哪一双”，这算澄清还是跑偏？如果用户上周只买了一双鞋，那这个追问就是多余的；如果用户买了三双，那这个追问就是必要的。判断标准取决于上下文，而上下文又很难在评测集里完整模拟。

我的做法是：对于多轮对话，评测时不仅看最终结果，还要看每一轮的意图是否合理。具体来说，会定义一个“追问合理性”指标：如果Agent的追问能帮助缩小问题范围，且没有重复询问已知信息，就算合理。这个指标需要人工标注一部分数据来校准，然后训练一个小的分类模型来自动判断。

8. 一些实操建议与工具选型参考

8.1 评测框架的选型：自建还是用开源

评测框架的选择取决于团队规模和需求复杂度。如果只是简单的规则匹配和模型打分，自建一个轻量级的评测脚本就够了，几十行代码的事。如果需要复杂的多轮评测、人工标注管理、评测集版本控制，那可以考虑用开源框架，比如基于LangSmith、Weights & Biases等平台的评测功能，或者用RAGAS这类专门针对RAG场景的评测库。

我的建议是：PoC阶段先自建，快速跑通评测流程；进入生产阶段后，如果评测需求变得复杂，再考虑引入开源框架。不要一上来就上重型工具，容易把时间花在工具配置上而不是评测本身。

8.2 可观测性接入：OpenTelemetry在Agent场景的适配

可观测性方面，OpenTelemetry是目前比较通用的标准。它的Trace、Span、Event模型和Agent的链路结构很匹配，而且有很多现成的后端可以接入（如Jaeger、Zipkin、Grafana Tempo等）。接入的方式也不复杂，在Agent的每个处理节点加一个Span，记录输入输出和耗时，然后通过OTLP协议上报。

需要注意的是，Agent的输入输出往往是自然语言文本，数据量可能比较大。上报时要做截断或摘要，避免单条Trace过大。另外，模型调用的token数、工具调用的参数等敏感信息，要做好脱敏处理。

8.3 小团队的最小可行方案：从零搭建评测与监控的步骤

对于小团队或者刚起步的项目，不需要一开始就建大而全的体系。我建议的最小可行方案是：

1. 第一周：整理50-100条评测case，覆盖核心意图和常见难度，用规则匹配做基础评测。
2. 第二周：在Agent链路里加基础埋点，记录每个节点的输入输出和耗时，输出到日志文件。
3. 第三周：写一个简单的脚本，每天从日志里计算成功率、延迟、工具调用准确率等指标，输出到表格。
4. 第四周：引入LLM-as-Judge做开放性回答的自动打分，补充人工抽样评估。
5. 第二个月：把评测和监控接入CI/CD，每次迭代自动跑评测，生产环境设置基础告警。

这个路径不需要复杂的工具，用Python脚本加一个数据库就能跑起来。等业务量上来了，再逐步替换成更专业的方案。

8.4 团队协作：评测和可观测性谁来负责

最后聊一个容易被忽略的问题：评测和可观测性谁来负责？我的经验是，不能只交给算法工程师，也不能只交给运维。最好的方式是有一个质量工程的角色（可以是兼职），负责评测集维护、评测流程执行、监控面板搭建、告警响应。算法工程师负责根据评测结果调优模型和提示词，运维负责保障监控系统的稳定性。

在小团队里，这个角色往往由Tech Lead兼任。关键是有人对“质量”这件事负责，而不是出了问题大家一起救火。我见过的最好的实践是：每周固定一个“质量会”，花30分钟过一遍评测结果和监控指标，讨论本周发现的bad case和下周的改进计划。这个习惯坚持下来，Agent的质量会稳步提升。

提示：评测和可观测性的建设是一个长期投入，不要指望一蹴而就。从最小可行方案开始，边用边完善，比一开始就追求完美更实际。

我在实际项目中的体会是，AI智能体的交付质量，很大程度上不取决于模型有多强，而取决于评测和可观测性这套“基础设施”有多扎实。模型可以换，提示词可以调，但如果没有一套可靠的评测和监控体系，所有的优化都是盲人摸象。希望这些经验能帮你在从PoC到生产的路上少踩几个坑。