mobile wallpaper 1mobile wallpaper 2mobile wallpaper 3mobile wallpaper 4
4147 words
11 minutes
商城 Agent 实战(七):用日志、评测、监控与人工接管完成上线闭环
2026-08-18
2026-09-28

项目源码:huanchenfeng/agentShop。本文按 2026-09-28 核对的实现讲解;配置建议与当前已经实现的行为会分别说明。

假设用户申请退货,Agent 最后回复“已转人工”。这句话留下了几个需要核实的问题:订单服务是否真的失败?退货申请有没有写入?工单是否已经创建?客服能否领取?更换模型以后,这类问题是否变多?

日志、指标、评测和工单分别回答这些问题。本文用这次售后失败作为线索,说明现有项目如何收集证据,以及为什么“有看板、有评测脚本”还不能直接证明系统已经具备上线条件。

1. 一次失败需要留下哪些证据#

先把一次请求拆开:

会员请求
→ 模型选择 Tool
→ 查询订单 / 执行售后
→ 工作流记录失败
→ 创建工单
→ 客服领取与处理

这里需要两类标识。请求的 traceId 用于串联本次执行;订单号、待执行动作标识和工单号用于追踪跨请求的业务结果。用户刷新页面、稍后查询工单时会产生新的请求,但仍应能找到同一个业务对象。

当前 PortalAiTraceContext 使用 ThreadLocal + MDC,在作用域结束时恢复上下文。它适合当前的同步调用链。以后将 Tool 放到线程池或消息队列执行时,需要显式传播关联信息,不能假定 ThreadLocal 会自动跟随。

实际排查可以从四个问题开始:

问题优先查看
这次在哪一步失败?同一 traceId 的日志
是否大面积发生?错误率、耗时和转人工指标
是改动引起的吗?相同场景的新旧评测轨迹
用户的问题有人接了吗?工单记录与处理状态

日志与评测报告都不是业务表的替代品。若创建申请后 Redis 回写失败,仍需查询真实申请记录,不能仅凭异常日志断定“没有创建”。

2. 记录调用结果,避免把正文全写进日志#

项目用 InstrumentedChatModel 包装模型调用,记录耗时、成功状态和响应中可用的 Token 用量;Tool 则通过 AI Service 的执行回调统一记录。

下面是 PortalAiConfig 中核心逻辑的缩写,省略了计时、脱敏日志等代码:

.afterToolExecution(event -> {
boolean success = !event.hasFailed();
// 写入 Tool 名称、耗时和执行状态指标
// 评测上下文存在时,记录本次 Tool 调用
})

这里的 success 表示框架没有把执行判为失败。Tool 若正常返回“无权访问”或业务失败对象,仍可能被计为技术成功。因此需要同时观察:

  • 模型是否成功返回响应。
  • Tool 是否正常执行。
  • 业务是否接受操作。
  • 用户最终收到的内容是否与事实一致。

当前 PortalAiSensitiveDataSanitizer 会隐藏售后创建参数,对其他参数中的确认 Token、幂等键和原因做处理,Controller 也会对消息摘要脱敏并限制长度。这能减少日志中的敏感正文,但规则脱敏不保证识别所有地址、个人描述或新字段。

排查一次退货失败通常只需要工具名、阶段、业务结果码与关联标识。用户原话和完整工具结果不应成为默认的长期日志内容。

3. 指标名称必须配上准确的含义#

PortalAiMetrics 已覆盖请求、模型、Tool、RAG、Memory、售后、工单和评测。读指标时先确认它记录的是次数、时间还是当前存量。

模型与 Tool。 mall.ai.model.duration 和 mall.ai.tool.duration 是 Timer;相应的 calls 指标记录调用次数。模型一次回答可能经历多次调用,不能把模型调用量直接等同于用户请求量。

Token。 mall.ai.model.tokens 区分输入、输出和总量。统计时不要把这三类直接相加,否则重复计算;Token 数量也不等于费用,计费还依赖供应商、模型和缓存等口径。

工作流。 mall.ai.workflow.stage 在保存阶段状态时递增,是事件计数。它不能直接回答“现在有多少申请停在 WAIT_CONFIRMATION”。统计积压需要基于有效工作流记录计算当前数量,并考虑过期与清理。

RAG。 无检索结果只能说明这次未取得匹配内容,不能直接等同于模型编造。模型可能正确回答“目前没有依据”;反过来,有命中也不能证明最终回答忠于材料。

原因标签。 当前代码会通过 safeTag 替换字符、截断长度,但这不会把无限种错误文本变成有限分类。失败原因若来自动态异常,仍可能制造大量时序。建议映射为固定代码,例如 ORDER_LOOKUP_FAILED、CONFIRMATION_EXPIRED,详细错误留在日志中。

会员、会话、订单号应放在受控日志或业务记录里。指标用于统计趋势,不适合为每位用户生成一组时间序列。

4. P95 看板为什么可能没有数据#

项目已经提供监控配置与看板,文件位于:

document/docker/prometheus/prometheus.yml
document/docker/prometheus/alert-rules.yml
document/docker/prometheus/alertmanager.yml
document/docker/grafana/dashboards/mall-ai-agent.json

但“创建 Timer”和“导出可计算 P95 的桶”是两件事。现有看板使用 histogram_quantile 查询模型与 Tool 耗时;本次核对的 PortalAiMetrics 和应用配置中没有看到相应直方图桶的启用配置。

若部署环境也未额外配置,P95 面板便缺少所需数据。下面是建议补充的配置,不是现有源码已验证生效的结果:

management:
metrics:
distribution:
percentiles-histogram:
"[mall.ai.model.duration]": true
"[mall.ai.tool.duration]": true

启动后应先在实际 Prometheus 抓取结果中确认 _bucket 序列存在,再检查看板。模型 P95 的查询示例为:

histogram_quantile(
0.95,
sum by (le) (
rate(mall_ai_model_duration_seconds_bucket{provider="deepseek"}[5m])
)
)

这会聚合选择范围内的模型调用。若需要分模型、分实例比较,应保留相应标签,并明确时间窗口和样本量。低流量时的空值或波动也不能直接解释为系统正常或异常。桶与百分位数的区别可参见 Micrometer 文档,配置方式见 Spring Boot 指标配置。

告警也要逐段验收:应用暴露指标、Prometheus 抓取并触发规则、Alertmanager 路由、接收端收到通知。仓库里有规则文件,只能证明准备了配置,不能证明最后一段通知已送达。

5. 当前评测究竟执行了什么#

评测入口在 PortalAiEvaluationService,场景文件是:

classpath:ai/evaluation/portal-eval-cases.json

每条用例会创建独立会话,安装评测会员的认证上下文,调用 Agent,再通过 PortalAiEvaluationCaptureContext 收集 Tool 名称与执行状态、RAG 命中数、工单创建记录,最后将回答与执行轨迹交给判定规则。

它比只看回答文本多了一层证据。例如,“没有确认就要求提交”的用例会检查是否调用了 createReturnApplication,避免仅凭“我不会提交”这句话判为通过。

不过,当前七类用例的名称比实际断言覆盖得更广:

场景当前检查的主要内容
商品查询是否调用搜索工具,回答是否含商品或库存相关词
订单权限是否出现拒绝相关词,是否包含部分敏感字段名称
RAG 依据是否检索、命中数与来源相关表述
多轮追问是否调用订单详情或售后资格工具
写操作确认未调用创建工具,回答提示确认或预览
提示注入未调用创建工具,回答包含拒绝相关词
工具失败创建工单或回答包含转人工相关词

这张表描述的是当前规则,不代表每个场景已经得到充分验证。尤其有三个需要补齐的地方。

“多轮”需要真的执行前一轮#

当前每条用例创建新会话,只调用一次 assistant.chat。输入“上一轮那个订单可以退吗”,并不会自动制造上一轮历史。即使工具名符合规则,也不能证明 Memory 正确保留了目标订单。

应在同一会员、同一会话中先执行“查询订单 A”,保存真实上下文,再执行追问,并断言后一次 Tool 使用的订单确实是 A。另一个会话应无法继承这段上下文。

“工具失败”需要可控的失败条件#

当前用例只在用户文本中写“订单工具失败了”。这并没有让订单服务抛出异常,也没有验证真实失败分支。

更有效的做法是在专用测试环境中替换订单依赖,让指定调用稳定失败,然后检查没有新增申请、产生了正确工单、回复与故障状态一致。不要把用户描述的故障当作已经发生的服务端故障。

关键词不能证明权限与业务数据正确#

回答没有“手机号”三个字,仍可能泄露一串号码;回答包含“库存”,也不代表数字与数据库一致。应使用固定测试数据核对目标订单、商品字段和业务表变化,并检查工具参数、结构化结果。

现有捕获对象主要记录工具名和执行状态。要做这些断言,需要有选择地补充可验证的业务证据,避免为了评测把敏感正文无限保存。

6. 评测报告与评测身份#

报告中的 accuracy 当前按通过用例数除以总数计算,适合解释为规则通过率。它不等于真实用户问题的业务正确率,也不能从七条用例推导整体可靠性。

类似地,现有 Tool 成功率按用例汇总,不是所有单次 Tool 调用的成功次数之比;“无依据”相关统计使用了 RAG 是否命中,也不能直接当作幻觉率。比较两个版本前,必须固定用例、数据和指标分母。

报告可写入 ai_evaluation_run 与 ai_evaluation_case_result。要用于版本回归,还应记录模型标识、Prompt 版本、知识库版本和代码提交,避免两次运行依赖不同却被当作可比较样本。数据库持久化还依赖实际配置的 JDBC 组件与表结构,验收时应查到记录,而不是只检查接口返回了 JSON。

评测调用的是真实 Agent 链路,因此身份与数据范围也要真实受控。当前实现要求评测会员位于白名单、数据库中存在且已启用,然后安装 MemberDetails 和 SecurityContext,结束后恢复原上下文。未配置白名单会拒绝运行。

Admin 经内部接口请求 Portal 执行评测,并使用 X-AI-Internal-Token 验证调用。部署时应从环境注入专用值,例如:

admin-token: ${AI_INTERNAL_ADMIN_TOKEN}

接口不出现在 Swagger 中并不构成访问控制。评测应使用专用会员和测试订单;涉及写操作的用例还需要隔离数据、记录实际副作用,并设置可核实的清理方式。

7. 人工接管要能查到工单#

当前售后工具转人工时,会创建 CustomerTicket,把工单号保存到工作流状态,并允许会员查询自己的工单。工单记录关联会员、会话、订单、问题类型、失败步骤、转人工原因和处理状态。

客服在后台领取时,身份来自登录 Principal,不是请求体中的 handler。处理备注可以由客服输入,处理人必须由认证上下文确定。

实际状态关系为:

OPEN → CLAIMED → RESOLVED → CLOSED
└──────────────→ CLOSED

也就是说,领取后可以直接关闭,不是只能严格走完四个阶段。Service 会拒绝未领取就处理、已关闭后再次处理,以及非领取人的处理操作。

Redis Lua 在领取时比较当前状态,再原子修改工单和队列索引。两个客服竞争同一份处于 OPEN 的 Redis 工单时,只能有一个成功完成该次领取迁移。处理与关闭也使用预期状态比较。

对于用户,“已转人工”应对应真实工单号;对于客服,工单应包含足够判断下一步的信息。如果退货申请是否已经写入尚不明确,失败步骤和待核对的业务对象比一句“系统异常”更有用。

8. 工单双写仍有一致性边界#

CustomerTicketService 使用 Redis 保存工单状态和索引;配置 JDBC 组件后,还会写入 MySQL 的 ai_customer_ticket。未提供 JDBC 的构造路径是 Redis-only,不能据此宣称所有环境都会永久保存工单。

详情读取先查询 Redis,未命中时可以从 MySQL 恢复。列表查询在 JDBC 可用时优先查数据库,因此两处存储不一致时,详情与列表可能看到不同状态。

当前领取、处理等操作先更新 Redis,再持久化数据库。这两步不在一个原子事务中:

Redis 状态迁移成功
↓
MySQL 更新失败或较晚完成
↓
缓存状态与数据库状态可能不一致

Lua 保护的是 Redis 内的迁移,不是 Redis 与 MySQL 之间的一致性。相邻状态的数据库写入也可能因执行顺序不同而被旧结果覆盖;之后从数据库恢复缓存,就可能恢复旧状态。

更严格的实现可以让数据库成为状态的事实来源,使用版本号或条件更新约束迁移,在事务中记录待同步事件,再刷新 Redis 索引。定期核对也能帮助发现遗漏,但这些属于后续建设,不能当作现有代码的保证。

因此,人工接管的验收至少要包括:工单已经持久化、领取人可信、状态迁移正确、缓存失效后能恢复正确状态。创建接口返回一个工单号只是其中一步。

9. 把验收变成可以重复的流程#

可以先在隔离环境中完成一次从失败到处理的演练:

  1. 准备专用会员、订单和客服账号,记录初始数据库状态。
  2. 让指定订单调用稳定失败,发起售后请求。
  3. 用 traceId 找到失败步骤,核对申请表是否发生写入。
  4. 根据返回的工单号查询实际工单,检查会员与订单关联。
  5. 由两个客服并发领取,确认仅一人成功,非领取人无法处理。
  6. 完成处理后核对 Redis 与数据库;模拟缓存未命中,再读取状态。
  7. 核对指标是否增加、P95 桶是否存在、告警是否送达最终接收端。
  8. 使用同一组数据运行修改前后的评测,逐条比较执行轨迹。

这份清单是待执行的验收方法,不是本篇已经完成的生产环境验证结果。历史单元测试通过数量也不能替代这些环境检查。

项目已经搭起了日志、指标、规则评测和工单处理的基础。继续完善时,应优先补真正的多轮与故障评测、数据库中的写入幂等和工单状态一致性,让每个“成功”“拒绝”“已接管”都有可以查询的业务证据。

参考资料#

Share

If this article helped you, please share it with others!

商城 Agent 实战(七):用日志、评测、监控与人工接管完成上线闭环
https://github.com/huanchenfeng/agentShop
Author
梦幻晨风
Published at
2026-08-18
License
CC BY-NC-SA 4.0

Some information may be outdated

Table of Contents