AI智能体生产就绪阶段式检查清单
一份将AI智能体从本地原型发展为生产环境的四阶段检查清单，每项均附有原因说明及具体示例。
将人工智能代理从可运行的原型发展到实际部署，遵循一定的路径，每个阶段都有相应的检查项，若跳过这些检查则可能出错。本指南将逐阶段进行说明。
原型的唯一任务是证明某个想法可行：仅需一台机器、内存中的状态，且没有真实用户。而实际生产环境则要求更高——它必须能够承受重启、同时服务多名用户、在某一步骤中途出错时恢复，并在出现问题时留下可追溯的记录。
这一差距中很少涉及人工智能模型本身，因为调用模型通常是最简单的部分。真正的难点在于其周边：状态存储在哪里、某一步骤被重复执行时会发生什么、以及如何在不造成损害的情况下将变更传递给真实用户。在代理正式上线之前，可参考以下列表了解哪些内容已得到处理，哪些仍需完善。
第一阶段：开发与本地原型
此处的目标刻意设定得较为简单，仅为证明核心理念确实可行。暂无需将其设计成可用于生产的版本，过早这么做往往意味着为尚未确定的架构构建错误的基础设施。
首先让核心工作流程尽可能以最小规模运行起来。在引入队列、数据库或部署机制之前，先确保从输入到正确输出的全过程能够一次性顺利完成。
原因：由于问题的真实情况尚不清楚——运行时间、状态规模及故障模式都还只是猜测——早期的基础设施选择往往会有误。即便先构建出生产级版本，通常也还需要重新设计。
示例：工单分类处理脚本最初只是简单的程序：它读取一条工单，向模型询问分类并输出结果。该系统没有服务器也没有数据库，需通过终端手动启动。
应让行为可通过配置调整，而非硬编码。当系统需要针对不同的输入（如客户群体、文档类型、语言或语气）采取不同处理方式时，应通过配置来实现，而非在代码中新增分支。
原因：一旦有用户使用，各种需求会迅速增多（“它能处理法语工单吗？”、“企业账户能否要求更严格的语气？”）。每种需求都需要修改代码并发布版本，这样新的需求就会在工程师身后排队；而通过配置则只需简单编辑即可解决。
示例：无需为每个客户等级分别编写if/else逻辑，只需使用小型文本模板——一个基础模板加上每个等级对应的模板即可。增加一个等级就意味着需要新增一个文件。
记下原型目前尚未解决的缺陷。在继续开发之前，有意识地列出这些不足：运行过程中中途重启、同时处理多个用户、故障记录功能缺失，以及无法在除自身机器外的其他设备上运行等问题。
原因：未被记录的缺陷日后往往会成为意外，通常是在问题发生时才发现，而非在规划讨论阶段。而已被记录的缺陷则可作为下一阶段的检查清单。
示例：一个简短的表格，内容包括“状态存储在 Python 字典中，因此需要持久化存储”、“一次只能运行一个任务，因此必须支持并发运行”以及“没有发生情况的记录，因此需要审计日志”。此时还没有固定任何规则，这些只是暂时的名称而已。
第二阶段：测试环境与预发布环境
在这一阶段，系统首次接触到真实的基础设施以及可能出现的故障情况。它不再运行在笔记本电脑上，而是会被重启，且可能同时被多人使用。
选择适合实际工作负载的运行时环境。在决定代理程序的部署位置之前，需先查看具体数据：允许的最长运行时间、空闲状态下的成本，以及被终止的进程是否能够从断点继续运行。
原因：智能体处理的任务很少表现为普通的网页请求。单次运行可能持续数分钟，且需要在多个步骤之间传递大量上下文信息。为短时间请求设计的运行时会在任务进行到一半时超时，而为持续高流量设计的运行时则对每天仅运行几次的任务来说成本过高。
示例：法律文件审核智能体会在单次运行中逐页处理文档，以便保留全部上下文，因此处理一份长文档可能需要10到15分钟。这就排除了设有固定时间限制的无服务器函数。同时这也排除了始终处于运行状态的容器组，因为该智能体每天仅运行几次，多余的闲置容量毫无用处。对于这种时长较长、突发性强且运行频率低的任务，显然需要一种仅按实际处理时间计费且没有超时限制的运行时。
将状态从内存移至持久、可共享的存储中。那些必须在重启后依然存在或需被多台服务器访问的数据，比如运行状态、对话历史以及正在处理的结果，都应存储在真正的数据存储系统中，而非运行进程内的变量中。应选定一个系统作为数据来源的权威版本。
原因：仅存储在内存中的状态会在进程重启时消失，而在实际生产环境中，由于部署、崩溃和扩展等原因，这种情况发生的频率远高于人们的预期。如果状态分散在多个存储系统中且没有明确的负责人，最终会导致两个系统对真实数据状态产生分歧。
示例：在此场景中，文档编辑代理会将运行状态、聊天记录以及拟议的修改内容存储在对象存储中，而在请求处理过程中不会保留任何数据。对象存储是唯一的真实数据来源，而数据库则仅用于一个特定功能：通过锁定机制防止两个处理节点同时处理同一任务。整体状态不会在两者之间分配，也没有规则决定哪一方具有优先权。
假设“该任务已运行两次”以及“这些任务是同时运行的”。大多数真实的消息系统都可能多次触发某个事件。单纯的状态检查（“若未启动则启动”）是行不通的，因为两个进程都可能在对方记录“已启动”之前读取到“未启动”的状态。因此需要采用能够确保仅有一个进程获胜的机制。
原因：如果没有这种机制，两个进程可能会重复执行相同的耗时操作或写入相互冲突的结果，而且只有在任务真正重叠时才会出现错误，而安静的开发环境很少出现这种情况。
示例：早期那种通过锁定来声明任务所有权的机制在正常情况下可以正常工作，但如果持有锁的进程崩溃或挂起，就无法释放该任务。在生产环境中，这会导致大量任务长时间处于“处理中”状态而无法恢复。解决方案包括添加过期时间限制、使用令牌防止恢复后的进程被误认为是原来的持有者，以及定期清理那些租约到期仍未完成的任务。这比“仅声明一次所有权”的方式要完善得多。
在出现故障之前就做好追踪与日志记录。当涉及多个服务时，比如Web层、队列、工作进程以及AI运行时，用户的每一个操作都会经过这些服务。现在就要设法追踪这些操作在服务间的流转路径，这样在故障发生时就不必再费力拼凑信息了。
原因：从相互关联性较低的独立日志中重建事件既缓慢又容易出错，尤其是在压力较大的情况下。如果从一开始就能对系统进行追踪，原本繁琐的调查就能变成快速的查询。
示例：某个系统的AI运行时从一开始就具备详细的追踪功能，但其前置的Web服务却没有，因此追踪记录显示的是代理执行的所有操作，而非触发这些操作的请求，因为两者之间没有共享任何关联信息。解决方法是，在请求生成时创建一个运行ID，并将其贯穿所有服务的日志，这样即便两个追踪系统相互独立，通过一次搜索也能获取特定运行的完整路径。
尽早测试真实客户端。当用户通过特定的浏览器、应用程序或设备访问系统时，应尽快在该目标环境中进行测试，切勿使用通用的API客户端或简化版方案来替代。
原因：真实客户环境存在各种特殊问题，比如长度限制、隐性截断以及奇怪的编码方式，这些通用工具都无法检测到。这类问题往往只有在真实用户使用时才会显现，而到那时已经变成了生产环境中的故障，而非仅在测试环境中发现的 issue。
示例：某桌面应用的文档打开功能通过了所有自动化测试，但在某个操作系统的用户使用时却会间歇性出错。该应用会自动截断超过一定长度的下载链接，而用于为链接签名的临时安全凭证会导致链接长度远远超出限制。最终的解决方案是使用另一个能生成较短签名身份来为链接签名，以替代系统中其他部分所使用的临时凭证。
需使前门的网络路径与客户端的连接方式相匹配。如果用户只能通过私有网络（如VPN、零信任代理或仅限内部使用的网络）访问系统，必须确保他们使用的地址从始至终都能真正连接到同一私有网络上的目标。那些看似内部域名的地址，若实际会解析为公共负载均衡器或CDN，对某些用户可能正常工作，但对其他用户则可能间歇性出现故障。
原因：这种不匹配会导致故障情况不稳定：只有部分用户在特定时间会遇到问题，因此这更像是基础设施不可靠，而非设置错误。由于开发人员的机器通常会走与员工笔记本电脑不同的网络路径，这类问题很容易被忽视。
示例：有一款内部工具，只能通过公司网络及零信任代理访问，该代理会根据每台笔记本电脑的选择将流量路由到不同的连接节点。该工具的域名看似属于内部系统，但实际上指向的是一个公共内容分发网络。某些连接节点能够访问那个公共地址，而其他节点只能访问私有地址，因此故障会随着所使用的连接节点不同而时有时无。解决办法是在私有网络内的负载均衡器上设置入口，让所有真实用户都能通过常规路径访问，同时为那款完全无法使用代理的桌面应用设置一条独立的签名路径。
创建一个虚拟客户端，随时可以驱动整个流程。它是一个脚本，能够通过相同的界面发起与真实用户相同的请求并执行后续操作，因此无需等待人工测试人员即可重复完整的运行过程。
原因：智能体流程很少只涉及一次请求和一次响应，通常需要多轮交互、工具调用以及随时间同步更新的反馈，这些内容很难通过手工方式彻底验证。单纯的单元测试和集成测试往往只是分别测试各个部分，而非完整的真实场景。借助虚拟客户端，就可以随时检查多步骤对话是否顺利进行。
示例：负载测试工具会模拟真实客户端控制台为启动测试而发起的相同API调用，随后通过状态表查看测试何时完成，因为测试实际会在之后结束，而最初的响应并不会说明结果如何。同时进行的测试数量会逐步增加，从少数几项增加到数十项，甚至上百项，但对总测试次数和成本设有上限，因为每次模拟测试都相当于一次真实的计费模型调用。这一测试揭示出，在高负载情况下真正的瓶颈在于模型提供方，而非周边基础设施，而单独测试各部分则无法发现这一点。
应在数据被计入之前设置人工审核环节。应提供一个界面，让相关人员能够查看代理即将执行的操作，并对其予以批准、修改或拒绝，而非从第一天起就让操作自动生效。
原因：智能体的错误表现与普通漏洞不同。它们看似合理实则错误，并非明显的崩溃现象。人工审核能够发现那些通过所有自动检测的错误，从而积累经验，以便日后判断哪些情况下智能体可以无需审核即可安全运行。
示例：文档编辑智能体绝不会直接在最终文档中写入内容。它会提出建议，由审核人员逐一接受、修改或拒绝，因此在有人采取行动之前，它生成的任何内容都不算有效。
第三阶段：预生产环境
这是距离真实用户最近的测试环境。此阶段的关注点从“功能是否正常？”转变为“在条件不理想时整个流程是否仍能正常运行？”这包括反复部署、部分服务中断，以及模型或提示词更换后出现的功能偏差。
要建立合理的评估机制，因为仅用通过或失败的标准是不够的。 需要明确代理输出中“良好”的标准，这些标准通常包括多个方面（对正确输入作出恰当响应、内容上准确无误、多次运行结果保持一致），同时还要确定由谁或什么来检查这些标准：是固定规则、人工审核员，还是作为评判者的独立模型。
原因： 代理的输出很少像单元测试断言那样简单地表现为正确或错误。仅通过或失败的信号无法显示是哪部分表现变差了，而那些未经仔细审视的评分方法，尤其是自动评判系统，很可能会逐渐偏离使用该输出的人所看重的标准。
示例：摘要生成器的评分基于三个方面：对关键事实的覆盖程度、是否存在源文本中没有的虚构内容，以及相同输入下两次运行时输出结果的差异大小。会由人工检查样本是否存在“虚构内容”，因为这一项出错会带来最大的损失。
使用一组已确认正确的固定示例重新运行该生成器。保留一小批输出结果已通过验证且不会变化的输入样本，在每次部署时都使用这些样本进行测试，尤其是在修改提示词或模型之后。
原因：与普通代码不同，生成器的行为在提示词稍作修改或模型更新后可能会发生细微变化，而常规测试却不会检测到问题。固定的示例集往往是唯一能发现“生成器运行正常，但结果却逐渐变差”这一情况的存在。
示例：文档编辑工具会在固定的示例集上通过三种方式接受检测：是否选择了需要编辑的正确部分（与人工审核的答案对比）、其提出的修改是否正确（由独立的评估模型打分），以及在对相同输入进行多次运行时其输出结果的变化程度。通过跟踪不同版本中的这三项指标，而非仅看一次测试的通过/失败情况，发现某个修改虽然提升了某项指标，却悄悄损害了另一项指标。
让测试失败立即阻止发布。那些即使失败仍允许部署的测试套件其实毫无意义。应将测试结果与发布流程相连，一旦出现失败就立即停止发布，不能默认绕过这一机制。
原因：如果某个检查环节可以轻易被跳过，通常会在截止日期的压力下被跳过，而正是在这种情况下，有问题的修改最有可能被通过。
示例： 可以设置这样的流程：一旦有任何测试失败，部署步骤就不会执行。系统中没有“无论如何都要部署”的按钮，要绕过这一限制必须主动修改流程配置，而非仅通过点击警告来处理。
故意中断快速路径，确认系统能平稳降级。 如果正常情况下结果是通过缓存、实时连接或队列等快速路径传递的，那就刻意关闭这些路径，检查较慢的备用方案是否仍能正常工作，而不是导致相关功能完全无法使用。
原因： 缓存、实时连接以及类似的快捷方式是生产环境中最容易出问题的部分。如果没有备用方案，某个小组件的轻微故障就会导致整个功能瘫痪。
示例：通过推送连接，更新通常会在一秒内到达。而在关闭该连接的测试中，系统会每隔几秒轮询一次，虽然速度较慢，但仍能向用户显示结果。
让工具来确保某些操作必须按顺序执行。如果配置部分B之前必须先完成部分A，那就将该顺序纳入部署流程中，而非依赖某人的记忆。
原因：像“先部署X再部署Y”这样的规则，只有在知晓该规则的人在场时才有效，一旦此人离开或有人在不了解该规则的情况下自动化处理流程，规则就会失效。那些重要的顺序要求应当被纳入工具中。
示例：编排服务需要由另一套部署栈创建的AI运行时标识符，如果每套栈都互相引用就会形成循环。因此，运行时所在的栈在创建时会将自己的标识符写入共享的参数存储中，而编排栈则从那里读取该标识符。这样可以确保运行时先存在，且各栈之间不会互相引用。
第4阶段：生产环境部署
在真实用户开始使用系统之前，需要进行最后的检查。此时错误问题应当已经得到解决。剩下的工作就是确认最终发布的版本确实与测试过的版本一致，并且能够恢复故障并解释其原因。
发布与测试完全相同的版本。使用通过预生产环境测试的构建版本，为其重新标记为生产环境版本，而不要在最后阶段重新编译。
原因： 即使从“相同”的源代码进行最后时刻的重新构建，也可能会使用不同的依赖版本、时间戳或环境配置。这种差异意味着实际运行的是从未经过真正测试的版本。
示例： 已通过所有预生产测试的打包应用仅被重新标记为生产版本并直接发布，仍然是原来的文件，而非从相同代码重新构建的版本。
事先确定重复失败的处理方式及保留时间。 设定明确的重试次数限制，选择超出限制后的失败任务应存放的位置，并决定其保留时长。
原因： 若没有限制，出错的任务可能会无限重试，悄悄消耗资源或阻塞队列。若没有指定的存放位置，失败的任务就会消失，没人能对看不见的失败采取行动。
示例：若某项任务失败三次，会自动被移到单独的暂存区，而不会无限次重试。这些任务会被保留两周，以便工程师有时间发现问题并进行调查。
现在就规划审计追踪机制。如果日后需要向用户、审计人员或同事解释系统的决策，应提前确定要记录哪些内容以及如何查找这些记录。
原因：一旦真正的截止日期到来，“稍后再添加适当的日志记录”这种说法几乎从不会实现，而等到问题显现时，缺失的历史记录已无法事后补全。
示例：每一个自动决策都会作为带有时间戳的独立记录保存下来。如果日后有人询问系统在特定情况下为何做出某种决策，就可以直接参考书面记录，而无需猜测。
要详细记录每一起实际发生的问题，而不仅仅是补丁信息。在出现意外故障后，需记录根本原因并将其标注在团队日后能找到的地方，这远比仅仅关闭工单或结束聊天记录更有意义。
原因：未记录的解决方案往往会由其他人从头重新处理，而且通常会在更大压力下进行。简短的记录往往是避免重复花费数小时进行调查的最经济有效的办法。
示例：曾有一批运行任务因没有自动恢复机制而处于半处理状态数日。其成因、解决方案以及背后的思考都被记录在单独的文档中，而非仅体现在代码补丁里。后来，进一步审查推翻了之前认为模型编造数据的结论，发现真正的原因比最初设想的更为复杂。相关更新也被记录下来，因此最初那个不够准确的结论便不再成立。
检查清单背后的规律
这些其实并非人工智能所特有。任何分布式系统都需要具备这些习惯：持久化的状态管理、对重复操作的妥善处理、对发生情况及其原因的清晰了解，以及能够发布经过测试内容的发布流程。
智能体改变了风险的分布位置。测试运行时间更长且包含更多上下文，因此计算资源必须与之匹配。测试运行可能会以普通测试无法发现的方式失败或出现偏差，因此基于已知正常样本的回归测试更为重要。迟早会有人询问“它为什么那样做？”，而审计追踪必须能够回答这个问题。
相关阅读
- 为什么编码智能体的内存应仅存储差异信息以及如何存储 —— 智能体内存应仅记录模型无法猜测的内容。每个条目需要四项测试，存储时需要三项信息，以及为什么 git 中的 markdown 非常合适。