本地/专网部署智能体总体架构与验收口径

本文面向在本地机房、政企专网、行业内网等环境建设智能体系统的项目团队，目标是形成一套可落地、可审计、可验收的总体方法。文中指标均为示例口径，用于说明验收框架；实际目标应以项目实测与合同约定为准。

1. 背景与目标

问题定义

企业在推进智能体建设时，常见问题不是“能不能跑起来”，而是“是否可控、可验、可长期运行”。在本地或专网场景下，业务方通常同时提出四类约束：数据不出域、接口可追责、故障可回退、上线可审计。若前期只关注模型效果，忽略系统工程约束，后期会出现上线周期长、验收争议大、运维成本高的问题。

技术机制

总体目标应定义为“六可”：可部署、可接入、可编排、可追溯、可回滚、可验收。对应机制为：

1. 以分层架构隔离变化，避免模型、工具、知识库、业务流程强耦合。
2. 以状态机驱动任务执行，确保任务从受理到回传全链路可观测。
3. 以证据链绑定输出，确保每条关键结论可回查来源。
4. 以统一指标体系度量交付，避免“主观可用”替代“客观验收”。

实施方法

实施前应先完成三项基线工作：

1. 场景分解：把“智能体能力”拆到具体业务任务，明确输入、处理、输出、责任人。
2. 约束建模：梳理网络边界、数据分级、账号权限、外部依赖、合规条款。
3. 验收对齐：在立项或需求评审阶段，先锁定指标定义、采集口径、验收样本和统计窗口。

验收口径

背景与目标阶段的交付验收可采用“文档+演示+抽检”三段式：

1. 文档：总体架构说明、边界清单、风险清单、指标字典齐备。
2. 演示：覆盖核心业务链路，能展示成功路径与失败补偿路径。
3. 抽检：随机抽取不少于约定比例任务，检查日志、证据、审计链是否闭环。

2. 适用范围与边界（本地部署、专网部署、离线依赖、数据边界）

问题定义

本地部署与专网部署常被混用，导致实施策略错误。例如把“无公网出口”误解为“无任何外部依赖”，或把“专网互通”误解为“可跨域共享全部数据”。边界不清会直接引发合规风险与验收争议。

技术机制

建议从四类边界定义系统：

1. 本地部署边界：系统运行在单单位本地机房，计算、存储、日志均在本域。
2. 专网部署边界：系统运行在受控专网，可跨节点通信，但需按网络区划与访问策略受控放行。
3. 离线依赖边界：模型文件、镜像、词库、规则包、补丁应支持离线导入、校验和升级。
4. 数据边界：按数据分级定义“可入库、可索引、可出域、可脱敏、可留存”的处理规则。

实施方法

实施阶段建议落地四份边界清单：

1. 网络清单：网段、端口、协议、南北向/东西向访问规则。
2. 依赖清单：模型版本、运行时、第三方组件、离线包来源与签名。
3. 数据清单：字段分级、存储位置、加密策略、保留周期、销毁流程。
4. 接口清单：对接系统、调用频率、超时重试、降级策略、责任归属。

验收口径

边界验收可采用“配置核验+流量核验+数据核验”：

1. 配置核验：检查网络策略、白名单、密钥托管、离线仓库是否按方案落地。
2. 流量核验：通过抓包或网关日志确认无越界访问、无未备案外联。
3. 数据核验：抽检敏感字段脱敏、加密、访问审批和留存策略执行结果。

3. 总体架构设计（分层说明）

问题定义

智能体系统若以单体方式堆叠能力，通常在两个月内出现“改一处动全局”。典型症状包括：工具变更导致对话异常、知识库更新导致推理链失稳、审计需求介入后大量返工。

技术机制

采用六层架构，将“交互、决策、执行、数据、审计、运维”分离，核心是接口契约稳定、层间责任清晰。
示例口径，以项目实测与合同约定为准。

层级	核心职责	关键组件（示例）	输入/输出	主要验收点
交互层	统一接入用户请求，处理会话、身份、上下文	Web/IM/工单入口、会话管理、身份网关	输入：用户请求；输出：标准任务请求	鉴权通过率、会话一致性、输入合法性拦截
任务编排层	意图识别、任务分解、状态机执行、路由策略	Planner、State Machine、Policy Engine	输入：标准任务请求；输出：可执行步骤	状态流转正确率、编排可解释性、异常转移覆盖
工具层	执行业务动作，屏蔽异构系统差异	Connector、Adapter、重试/熔断模块	输入：步骤指令；输出：工具结果/错误码	调用成功率、幂等性、超时与重试有效性
数据与知识层	提供结构化数据、文档知识、向量检索	RDBMS、对象存储、向量库、索引服务	输入：查询与写入；输出：证据与业务数据	数据一致性、索引更新时效、召回可解释性
审计层	全链路留痕、证据绑定、合规检查	审计日志、证据仓、签名与哈希、报表	输入：链路事件；输出：可审计记录	审计链完整率、不可抵赖性、审计查询可用性
运维层	监控、告警、发布、备份、容量与应急	APM、日志平台、CMDB、发布流水线	输入：运行指标；输出：告警/变更记录	SLA、告警准确率、恢复时长、变更可回滚性

实施方法

分层实施建议按“先契约、后实现、再联调”：

1. 先定义层间 API 契约、错误码规范、TraceID 规范。
2. 再实现最小可运行链路（MVP），优先打通单场景闭环。
3. 最后扩展场景与容量，逐层压测并固化基线。
4. 对每层保留独立回归测试与版本清单，避免跨层联动回归失控。

验收口径

架构验收重点不在“图是否完整”，而在“分层是否可替换、可测试、可追责”：

1. 任意单层升级不应破坏既有契约。
2. 关键链路必须具备端到端 TraceID 串联。
3. 发生故障时可在约定时限内定位到层级责任与组件责任。

4. 关键机制

问题定义

关键机制缺位会导致三个直接后果：任务不可控、结果不可证、故障不可复盘。尤其在多工具、多系统协同时，单点失败若无补偿机制，容易造成“业务半成功、状态不一致”。

技术机制

4.1 任务编排与状态机

将任务拆分为标准状态，建议至少包含：RECEIVED、PLANNED、RUNNING、VERIFYING、COMPLETED、FAILED、COMPENSATING、ROLLED_BACK。每次状态流转必须记录触发条件、操作者、输入摘要、输出摘要和时间戳。

4.2 工具调用与回滚补偿

工具层需统一封装超时、重试、熔断、幂等键。对涉及写操作的步骤设置补偿动作（Compensation Action），失败时按逆序回滚，回滚失败需进入人工接管队列并自动告警。

4.3 证据引用与可追溯输出

智能体输出应绑定证据引用元数据，包括来源系统、文档版本、检索时间、哈希摘要、片段位置。面向业务输出可展示“摘要+引用”，面向审计输出保留“全文定位+签名校验”。

4.4 权限与审计留痕

采用“身份认证 + 授权策略 + 行为留痕”三段控制。授权建议结合 RBAC 与 ABAC：前者控制角色边界，后者控制场景细粒度约束（数据级、字段级、时间窗级）。

function handleTask(request):
  trace_id = newTraceId()
  audit.log(trace_id, "RECEIVED", request.meta)

  if not authn(request.user) or not authz(request.user, request.intent):
    audit.log(trace_id, "REJECTED", "AUTH_FAILED")
    return fail("无权限")

  plan = planner.build(request)
  audit.log(trace_id, "PLANNED", plan.summary)

  executed_steps = []
  for step in plan.steps:
    audit.log(trace_id, "RUNNING", step.id)
    result = tool.invoke(step, timeout=step.timeout, retry=step.retry, idempotency_key=trace_id+step.id)

    if result.ok:
      evidence.bind(trace_id, step.id, result.source, hash(result.payload))
      executed_steps.append(step)
      continue

    audit.log(trace_id, "FAILED", result.error_code)
    for done_step in reverse(executed_steps):
      compensate_result = tool.compensate(done_step)
      audit.log(trace_id, "COMPENSATING", done_step.id + ":" + compensate_result.status)

    if all_compensation_success():
      audit.log(trace_id, "ROLLED_BACK", "SUCCESS")
    else:
      audit.log(trace_id, "ROLLED_BACK", "PARTIAL_NEED_MANUAL")
      alert.oncall(trace_id)

    return fail("任务失败，已触发补偿")

  final_answer = responder.compose_with_evidence(trace_id)
  audit.log(trace_id, "COMPLETED", final_answer.summary)
  return success(final_answer)

实施方法

1. 将状态机与流程配置外置，避免硬编码在单一服务。
2. 将工具调用规范沉淀为 SDK，统一错误码和重试策略。
3. 将证据模型定义为统一结构体，避免不同场景引用口径不一致。
4. 将审计日志分为运行日志与合规日志，分别服务运维与监管。

验收口径

1. 状态机覆盖率：核心业务场景状态转移覆盖达到约定阈值。
2. 补偿有效性：注入故障后可触发逆序补偿并形成完整审计记录。
3. 可追溯性：抽检输出可在审计系统回查到原始证据与版本信息。
4. 权限控制：越权请求应被拒绝并可追踪到策略命中记录。

5. 部署模式与实施路径

问题定义

在本地/专网环境中直接“全量上线”风险高，常见后果是性能不达标、边界遗漏、运维体系未就绪。应采用分阶段推进，逐级放大场景与负载。

技术机制

采用“三阶段路径 + 阶段退出门槛”：

1. 单点试运行：验证单场景闭环与关键机制可用。
2. 专网小规模试点：验证跨系统协同与运维响应。
3. 生产级上线：验证多场景并发、稳定性与合规持续性。

实施方法

5.1 单点试运行

目标是“跑通一条链路并可复盘”。重点完成：最小架构部署、单业务流程编排、基础审计留痕、首轮指标采集。

5.2 专网小规模试点

目标是“可扩展且可管控”。重点完成：多工具接入、跨系统身份打通、容量评估、告警规则、灰度发布。

5.3 生产级上线

目标是“可持续运行”。重点完成：高可用部署、备份与灾备、变更流程、值班机制、月度 SLA 看板和合规报表。

实施清单（Checklist）

• 已完成网络、依赖、数据、接口四类边界清单并签字确认。
• 已建立统一 TraceID、错误码、审计字段标准。
• 已完成核心流程的成功路径、失败路径、补偿路径联测。
• 已完成离线依赖包签名校验与版本台账。
• 已完成压测、稳态运行、故障演练并形成记录。
• 已配置分级告警、值班通讯录、应急处置手册。
• 已形成验收脚本、验收样本、指标看板与原始数据留档。

验收口径

阶段验收建议采用“门槛制”：未达到阶段指标不进入下一阶段。每阶段必须提交运行报告、问题清单、整改闭环和风险接受说明。

6. 验收口径（重点）

问题定义

智能体项目最常见争议点是“效果不错但无法验收”。原因通常是：指标定义模糊、采集方式不一致、统计窗口不统一、样本不具代表性。

技术机制

验收体系建议采用“指标字典 + 数据采集 + 统计窗口 + 判定规则”四件套。

1. 指标字典统一公式和边界条件。
2. 采集链路统一来源，避免手工统计。
3. 统计窗口按日、周、月固定，防止选择性取样。
4. 判定规则明确“通过/有条件通过/不通过”。

实施方法

6.1 功能验收

基于业务用例库逐条验证：任务受理、意图识别、流程执行、证据引用、失败补偿、结果回传。每个用例必须可复现、可回放、可追责。

6.2 性能验收

按照并发等级分层压测，至少覆盖常态流量、峰值流量、突发流量。必须区分问答型场景与多工具编排场景，分别统计 P50/P95/P99 与超时率。

6.3 稳定性验收

执行连续稳态运行与故障注入演练，覆盖组件重启、网络抖动、工具超时、存储异常。验证自动恢复、告警及时性、补偿链路与人工接管流程。

6.4 合规验收

围绕“最小权限、全程留痕、数据合规”开展核查。检查身份认证、权限审批、日志留存、敏感字段处理、审计报表与留痕不可篡改能力。

验收口径

示例口径，以项目实测与合同约定为准。

指标	指标定义	采集方式	目标示例	验收方法
任务成功率	成功完成任务数 / 受理任务总数	编排层任务状态统计（COMPLETED）	≥ 92%	连续 7 天按日统计，剔除无效请求后计算
工具调用成功率	成功调用次数 / 工具调用总次数	工具网关日志与错误码聚合	≥ 98.5%	抽取核心工具与全量工具双口径复核
P95 响应时延	95% 请求在该时延内返回	APM + 网关埋点统一计时	问答型 ≤ 6s；多工具型 ≤ 15s	分场景压测与生产试运行双验证
审计链完整率	完整审计字段记录数 / 应记录总数	审计平台字段完整性扫描	≥ 99.9%	抽检任务链路，核对 TraceID 全链路贯通
回滚成功率	回滚成功次数 / 触发回滚总次数	补偿模块日志 + 业务状态比对	≥ 99%	故障注入演练中统计，并进行业务一致性复核
系统可用性（SLA）	约定周期内可用时长占比	可用性监控探针与服务健康检查	月度 ≥ 99.5%	按月生成 SLA 报告并与故障工单对账

补充要求：验收报告应同时提交原始日志样本、统计脚本版本、数据时间窗说明，确保第三方可复算。

7. 常见风险与应对

问题定义

本地/专网项目进入运行期后，风险不再集中在“是否能用”，而集中在“是否持续可用、可控、可审”。缺少风险前置管理会导致反复返工。

技术机制

建立“风险台账 + 触发阈值 + 应急预案 + 复盘机制”闭环：

1. 风险台账记录风险等级、触发条件、责任人与处置时限。
2. 触发阈值绑定监控指标，实现自动预警。
3. 应急预案覆盖降级、切换、回滚、人工接管。
4. 复盘机制要求问题闭环到制度、流程、技术三层。

实施方法

常见风险与应对建议如下：

1. 工具接口频繁变更：建立适配层版本管理与契约测试。
2. 知识库过期导致答复偏差：建立定期重建索引与知识有效期策略。
3. 权限配置漂移：引入策略基线检查与审批留痕。
4. 观测数据不全：强制关键链路埋点，不允许“裸调用”。
5. 容量预估不足：按峰值场景进行预留并设置弹性扩容阈值。
6. 组织协同不足：明确业务、技术、安全、运维四方责任边界。

验收口径

风险管理验收不看“风险是否为零”，而看“风险是否可识别、可预警、可处置、可复盘”。验收时应抽查至少一次故障演练闭环记录及对应整改项完成情况。

8. 结语（可执行建议）

问题定义

很多项目在验收后进入“文档归档、机制弱化”的状态，导致后续版本迭代再次出现边界漂移和指标失真。

技术机制

将架构与验收从“一次性交付物”转为“持续治理机制”。核心是把指标、审计、变更和风险纳入常态化运行制度。

实施方法

建议按以下顺序执行：

1. 先固化指标字典与采集脚本，确保后续版本可对比。
2. 再建立月度运行评审，覆盖 SLA、故障、回滚、审计完整率。
3. 最后把重大变更纳入评审门槛，执行“先验证、后放量”。

验收口径

结语阶段的最终判定标准是：系统不仅在验收当下达标，而且具备持续达标能力。建议将“季度复验 + 年度审计”写入运维与治理计划，确保本地/专网智能体系统长期稳定、可管可控。