1. 为什么“AI员工”光记日志远远不够1.1 从“能跑”到“敢让它跑”的那道坎我最早接触 AI 员工系统是在一个内部工单自动化的场景里。当时团队做了个能自动读工单、分类、调接口、回写结果的智能体跑起来效果不错但上线第二周就出事了一个工单被重复处理了三次客户收到三条一模一样的回复。我们翻日志翻了整整一个下午日志里只有零散的INFO和ERROR根本还原不出“它当时到底看到了什么、想了什么、调了什么”。那一刻我才真正意识到日志和可观测性根本是两回事。所谓“AI 员工”说白了就是把大模型能力封装成一个能自主执行任务的数字劳动力它接收输入、做规划、调用工具、产生副作用发消息、改数据库、下单、发邮件。它和传统程序最大的区别在于——它的决策路径是不确定的。同一个输入今天走 A 分支明天可能走 B 分支。传统程序出 bug 你能靠代码复现AI 员工出问题你连它当时“脑子里”是什么状态都不知道。这就是为什么“给 AI 员工加一层可观测性”这件事核心不是多打几行日志而是要解决三个层次的问题看得见日志、看得懂结构化追踪、回得去可重放。前两个是基础第三个才是真正让 AI 员工从“能跑”变成“敢让它跑”的关键。没有可重放能力你每次排查问题都像在案发现场捡碎片永远拼不出完整画面。这篇文章我会按我实际落地的顺序来讲先讲整体架构怎么设计再拆执行网关这个核心部件然后是日志怎么从“流水账”升级成“可重放的事件流”最后是我踩过的坑和排查技巧。适合正在做 AI 员工、智能体平台、自动化任务系统的同学参考也适合任何想让自己的自动化系统变得“可追溯、可复现”的工程师。1.2 可观测性、日志、可重放三者到底什么关系很多人把这三个词混着用其实它们是一条递进链。日志是原始素材是“发生了什么”的流水记录可观测性是一套能力让你能从外部输出推断系统内部状态它包含日志、指标、追踪三根支柱可重放是终极目标指的是拿着记录下来的完整上下文能在隔离环境里把当时那次执行一模一样地再跑一遍。打个生活化的比方日志像是行车记录仪的原始视频可观测性是你有一套能快速检索、标注、关联多路视频的系统而可重放是你能根据记录把当时那段路在模拟器里重新开一遍看看司机AI当时为什么打了那个方向盘。对 AI 员工来说可重放的价值在于它把“不可复现的偶发问题”变成了“可反复研究的确定性样本”。大模型的输出有随机性但如果你把当时的输入、上下文、工具返回、随机种子、模型版本全部冻结下来重放时就能得到高度接近的结果从而定位到底是提示词问题、工具问题还是模型本身的问题。这里有个关键认知可重放不等于可复现。可复现要求 100% 一致可重放只要求“足够接近能定位问题”。这个区别很重要因为它决定了你的记录粒度——你不需要记录每一个字节只需要记录那些影响决策的关键状态。这也是为什么我在设计时把重点放在“决策边界”上而不是无脑全量记录。2. 整体架构设计执行网关 事件流 重放引擎2.1 为什么要在 AI 员工外面套一层“执行网关”我见过不少团队的做法是在 AI 员工的代码里到处埋print和logger.info。这种做法在 demo 阶段没问题一旦上生产就是灾难。原因有三第一日志散落在业务逻辑里改一处漏一处第二日志格式不统一没法机器解析第三也是最致命的——你没法在不改业务代码的前提下控制记录粒度。我的方案是在 AI 员工和外部世界之间加一层执行网关Execution Gateway。所有 AI 员工的动作——无论是调用工具、访问数据库、发 HTTP 请求还是输出最终结果——都必须经过这层网关。网关的职责很纯粹拦截、记录、转发、可选地重放。这样做的好处是关注点分离。AI 员工只管“我要做什么”网关负责“记录你怎么做的”。业务代码里一行日志都不用写可观测性能力却覆盖了所有关键路径。这就像给公司装了一套门禁系统员工不用自己记“我今天几点进的楼”系统自动就记了。网关的另一个价值是统一入口带来的统一治理。你可以在网关层统一做限流、鉴权、脱敏、超时控制这些能力对 AI 员工尤其重要因为大模型调工具时经常出现“疯狂重试”“参数离谱”的情况。网关是最后一道防线。2.2 事件流模型把一次执行拆成可序列化的事件网关记录的不是“日志行”而是结构化事件Event。这是整个设计的核心。一次 AI 员工的完整执行会被拆解成一串有序事件事件类型触发时机关键字段run.start任务开始run_id, input, model_version, seed, timestampllm.request调用大模型前prompt, context, tools_schemallm.response大模型返回后raw_output, parsed_action, token_usagetool.call调用工具前tool_name, argumentstool.result工具返回后result, duration, errorrun.end任务结束final_output, status, total_duration每个事件都带run_id和单调递增的seq这样整条链路就能被完整重建。为什么用事件流而不是传统日志因为事件流是可序列化、可回放、可 diff 的。传统日志是给人看的文本事件流是给机器用的数据。你要做重放就必须有结构化的数据。这里有个设计细节值得说事件里要记录“决策输入”而不是“决策结果”。比如llm.response里我记录的是模型的原始输出raw_output而不是解析后的parsed_action。因为解析逻辑本身可能变如果只记解析结果重放时就没法验证“是模型输出错了还是解析错了”。这个坑我踩过后来把所有中间态都保留下来排查效率直接翻倍。2.3 存储选型为什么我最终选了“文件 索引”而不是纯数据库一开始我用 PostgreSQL 存事件图的是查询方便。跑了两周就发现两个问题一是事件写入量太大一次复杂任务能产生上百个事件高频写入把数据库压得够呛二是大字段比如完整的 prompt 和模型输出存数据库里查询时 IO 开销很大。后来我改成冷热分离事件主体以 JSONL每行一个 JSON的形式落盘按run_id分文件同时在数据库里只存索引run_id、时间、状态、关键字段摘要。查询时先查索引定位文件再读文件拿详情。这个方案的好处是写入极快顺序追加存储成本低而且 JSONL 天然适合流式处理和重放。提示JSONL 文件要按时间分目录如2024/06/15/单文件别超过 100MB否则读取和传输都会变慢。我一般按小时切分配合 filebeat 之类的采集工具做归档。如果你团队规模小其实纯文件方案就够了别一上来就上重型存储。可观测性这东西先跑起来比先跑得漂亮重要得多。3. 执行网关的核心实现细节3.1 拦截层怎么写装饰器还是中间件网关的拦截实现有两种主流方式装饰器和中间件。我的选择是中间件为主装饰器为辅。中间件负责所有工具调用的统一拦截。以 Python 为例如果你用的是类似 FastAPI 或自研的调度框架可以在工具注册中心统一包一层class ObservableToolWrapper: def __init__(self, tool, recorder): self.tool tool self.recorder recorder async def __call__(self, run_id, **kwargs): self.recorder.emit(tool.call, run_idrun_id, tool_nameself.tool.name, argumentskwargs) start time.time() try: result await self.tool(**kwargs) self.recorder.emit(tool.result, run_idrun_id, resultresult, durationtime.time()-start, errorNone) return result except Exception as e: self.recorder.emit(tool.result, run_idrun_id, resultNone, durationtime.time()-start, errorrepr(e)) raise装饰器则用于那些需要特殊记录逻辑的场景比如某些工具需要额外记录文件快照或数据库事务 ID。不要试图用一种方式覆盖所有场景那样只会让代码变得又臭又长。这里的关键是recorder.emit必须是非阻塞的。我一开始用同步写文件结果工具调用被日志拖慢了好几倍。后来改成写内存队列 后台线程批量落盘性能问题立刻消失。这个改动看似小但对高频调用的 AI 员工来说是生死线。3.2 上下文传播run_id 怎么穿透整个调用链可观测性最怕的就是“链路断了”。AI 员工调工具工具内部又调了别的服务如果run_id传不下去你就只能看到一堆孤立的事件。我的做法是用 contextvar上下文变量做隐式传播。在任务开始时把run_id塞进 contextvar之后任何地方都能取到不用一层层传参。Python 的contextvars模块天生适合这个场景异步环境下也能正确隔离。import contextvars current_run_id contextvars.ContextVar(run_id, defaultNone) def get_run_id(): return current_run_id.get()对于跨进程、跨服务的调用run_id要放进 HTTP header 或消息队列的 metadata 里。我一般用X-Run-Id这个 header 名简单直接。下游服务如果也接了网关就能自动续上链路。注意contextvar 在异步任务里要注意传播。如果你用了asyncio.create_task记得用copy_context()把上下文带过去否则子任务里取不到 run_id。这个坑我调了大半天才找到。3.3 敏感信息脱敏别让日志变成泄密现场AI 员工的输入输出里经常包含用户隐私、密钥、内部数据。日志一旦落盘就是长期存在的风险点。我的原则是在网关层做脱敏而不是在业务层因为业务层总会有人忘记。脱敏策略我分三档完全丢弃如密码、token、部分掩码如手机号保留后四位、哈希替换如用户 ID 换成哈希值既能关联又不泄露。具体用哪档取决于这个字段对排查问题有没有价值。没价值的直接丢有价值的做掩码。SENSITIVE_KEYS {password, token, secret, id_card} def sanitize(data): if isinstance(data, dict): return {k: (*** if k.lower() in SENSITIVE_KEYS else sanitize(v)) for k, v in data.items()} if isinstance(data, list): return [sanitize(i) for i in data] return data这里有个经验脱敏规则要可配置、可热更新。因为业务在变今天不敏感的字段明天可能就敏感了。我把它做成配置中心的一个规则表改完不用重启服务。4. 从日志到可重放重放引擎怎么落地4.1 重放的前提把“不确定性”冻结下来重放最大的敌人是不确定性。AI 员工的执行里有几个主要的不确定源模型采样的随机性、外部工具的实时状态、时间戳、以及并发顺序。要让重放有意义就必须把这些冻结下来。模型随机性靠固定 seed 记录模型版本解决。现在主流的大模型 API 基本都支持 seed 参数虽然不能保证 100% 一致但能大幅降低方差。模型版本一定要记因为模型升级后行为可能完全变样。外部工具状态靠记录返回值解决。重放时不去真的调工具而是直接返回当时记录的结果。这就是所谓的“录制-回放”模式和单元测试里的 mock 是一个思路只不过这里是自动录制、自动回放。时间戳和并发顺序靠事件序列号解决。重放时严格按seq顺序执行忽略真实时间。这样即使原执行是并发的重放也能得到确定的结果。提示重放环境一定要和线上隔离。我见过有人直接在线上重放结果工具被真的调用了产生了重复副作用。重放时所有有副作用的工具必须走 mock这是铁律。4.2 重放引擎的三种模式我实现了三种重放模式对应不同的排查需求完全重放所有工具调用都走录制数据模型也走录制输出。这种模式用于“完全复现当时场景”验证问题是否稳定出现。半重放工具走录制数据但模型重新调用。这种模式用于“换一个模型或提示词看看结果会不会变好”是调优时最常用的。反事实重放在某个决策点手动修改输入看看后续会怎么走。这种模式用于“如果当时工具返回的是另一个结果AI 会怎么做”是分析决策逻辑的利器。三种模式共用同一套事件流只是回放策略不同。这也是为什么我坚持用结构化事件而不是文本日志——文本日志没法做反事实重放。4.3 重放的一个真实案例有次线上出现“AI 员工给同一个客户发了两封内容几乎一样的邮件”。日志里看两次tool.call的send_email参数确实不同一封是正式版一封是补充版看起来是正常的。但客户投诉说只该收到一封。我用完全重放跑了一遍发现模型在第一次生成后因为工具返回了一个“发送成功但延迟”的状态模型误判为失败于是重新规划了一次生成了第二封。问题根源是工具返回状态语义不清晰模型把“延迟”理解成了“失败”。定位到问题后我改了两处一是工具返回里明确加status: success字段二是给网关加了“同一 run 内相同副作用工具去重”的保护。这个问题如果只靠看日志可能永远找不到根因因为日志里两次调用看起来都“正常”。5. 常见问题与排查技巧实录5.1 日志丢失、乱序、截断怎么办这是最高频的问题。我整理了一张速查表现象常见原因排查方法解决日志丢失异步队列满被丢弃看队列积压指标加大队列 落盘失败重试日志乱序多线程并发写检查 seq 是否单调单写入线程 按 seq 排序日志截断大字段超限看单条事件大小大字段单独存 引用时间戳错乱多机时钟不同步对比机器时间统一 NTP 用逻辑时钟我踩过最深的一个坑是异步队列满导致静默丢日志。当时队列设了 10000高峰期直接爆掉日志丢了一大片排查时完全没头绪。后来加了队列水位监控和丢弃计数一旦有丢弃立刻告警再也没出现过“查不到日志”的情况。经验任何“静默失败”都是可观测性的天敌。日志系统自己出问题必须能被感知到。我专门给日志系统本身也加了一套健康指标。5.2 重放结果和线上不一致怎么定位重放不一致是常态别慌。我的排查顺序是先查输入再查环境最后查模型。先对比重放时的事件流和线上事件流逐字段 diff。八成的不一致是输入没录全比如某个环境变量、某个隐式上下文没被记录。我现在的做法是在 run.start 事件里把整个执行环境快照下来包括配置、版本、依赖这样重放时能精确还原。环境查完还一致那就是模型的问题。这时候看模型版本和 seed 是否一致再看温度参数。有时候是模型服务端悄悄升级了你这边没感知。所以模型版本要主动探测并记录别信文档。5.3 性能开销怎么控制可观测性是有成本的关键是别让它成为瓶颈。我的几个优化手段采样不是所有 run 都全量记录。正常 run 只记关键事件异常 run 才全量。采样率可动态调整。异步落盘前面说过写入必须异步。分级存储热数据留 7 天冷数据归档到对象存储查询时按需拉取。字段裁剪大字段如完整 prompt只在需要时记录默认记摘要。实测下来加了这套可观测性后单次任务的平均耗时增加了不到 5%但排查效率提升了不止十倍。这笔账怎么算都划算。6. 我个人的一些实操体会做这套东西最大的感受是可观测性不是加出来的是设计出来的。如果你一开始就把 AI 员工设计成“黑盒”后面再想加可观测性就得大改架构。反过来如果一开始就把执行网关、事件流、重放引擎作为基础设施的一部分后面加功能就是水到渠成。另一个体会是别追求一步到位。我第一版只做了最基础的日志记录第二版加了结构化事件第三版才做重放。每一步都解决了当时的痛点也验证了方向。如果一上来就设计一个“完美”的可观测性系统大概率会过度设计最后没人用。最后分享一个小技巧给每个 run 生成一个人类可读的短 ID比如run-20240615-a3f9。排查问题时运营同学报“这个任务出错了”你直接要这个 ID一秒定位。这个细节看似小但极大降低了沟通成本。我团队现在所有问题反馈都必须带 run ID没有 ID 的反馈一律打回效率提升非常明显。这套方案后续还能往几个方向扩展比如把事件流接到实时告警异常模式自动触发或者把重放引擎做成“AI 员工的单元测试框架”每次改提示词都跑一遍历史 case 看有没有回归。这些我都还在摸索等跑通了再单独写一篇。