智能体这个词这两年掉价得挺厉害。演示视频里它能自己查资料、自己写代码、自己调接口看得人热血沸腾真接进业务系统跑两天画风就变了——谁授权的、调了什么工具、把哪张表的数据带出去了、出错之后从哪儿查全是一笔糊涂账。我最近半年在几个团队里推智能体落地被问得最多的不是选哪个模型而是这东西跑起来之后我到底怎么管它。OpenClaw 企业版 OCE 这次发布主打的就是这个痛点开源、免费、可自托管并且把持证上岗这四个字摆到了台面上。说白了它想解决的不是智能体聪不聪明而是智能体能不能被企业放心地放进生产环境。这篇东西我打算按自己实际的部署和验证路径来写先拆清楚持证上岗到底指哪几件事再看 OCE 的架构是怎么回应这些事的然后是一台机器从零跑起来的完整步骤、权限与审计的具体配置、三个能立刻用的场景最后是我踩过的坑和一张排查速查表。不管你是刚开始接触智能体的开发还是已经在给团队做技术选型的负责人应该都能从里面拿走点能直接用的东西。1. 先把“持证上岗”这个词拆开看1.1 智能体从演示走向生产卡点从来不在模型能力很多人以为智能体落地难是因为模型不够强我实测下来的结论正好相反。现在主流的开源模型在工具调用、结构化输出这些基础能力上已经够用了真正让项目卡住的是另外三件事一是不可预测同一个问题问两遍它可能走两条完全不同的工具链路第二遍就出错了二是不可追溯出了问题你只能看到一段聊天记录看不到它中间调了什么、传了什么参数、拿到了什么返回三是不可约束你没法限定它只能查哪几张表、只能调哪几个接口、单次任务最多花多少钱。这三件事在个人玩具项目里无所谓在企业里每一条都是硬门槛。我见过一个团队做了个挺漂亮的客服智能体Demo 阶段领导很满意一提到上线安全那边只问了一句它能不能读用户手机号项目就停了三周。后来他们花了比开发更长的时间去补权限和日志才勉强过审。所以 OCE 这类企业发行版的价值不在于它内置了多强的 Agent 能力——那部分是开源社区共有的——而在于它把身份、权限、审计、沙箱这些东西做成了平台级的基础设施而不是让每个开发者自己用胶水代码糊一遍。这个区别很关键前者是一次性投入后者是每个项目重复踩一遍坑。1.2 身份、权限、审计企业真正要的是这三张证我把持证上岗理解成三层含义对应三个技术能力缺一不可。第一张证是身份。智能体在系统里必须是一个能被识别的主体有自己的 ID、自己的凭证、自己的归属部门。这一点听起来很基础但很多自建方案里智能体是直接复用某个管理员的 API Key 在跑出了事根本分不清是人干的还是机器干的。OCE 里每个 Agent 都有独立的身份标识调用外部系统时用的是绑定的服务凭证凭证可以单独吊销不影响其他 Agent。第二张证是权限。身份解决了你是谁权限解决你能干什么。这里最容易犯的错误是权限给太宽——反正智能体要调工具那就把工具全开给它。正确的做法是反过来默认全关按场景逐个开而且开的时候要带约束条件比如只能查订单表且只能查当前用户自己的订单。OCE 的工具注册机制支持在工具层面挂参数级的约束策略这个后面第 4 章会详细讲。第三张证是审计。审计不是简单记个日志而是要能回答四个问题谁发起的、智能体做了什么决策、调用了哪些工具、产生了什么副作用。这里面最容易被忽略的是决策过程也就是模型的思考链路和工具的中间返回。OCE 的做法是把整个执行过程拆成一条 trace每一步都有 span可以按 trace_id 完整回放。这个能力在做故障复盘的时候价值极高我后面会给一个真实用上的例子。注意审计日志本身也是敏感数据。完整的工具入参出参里很可能包含用户隐私字段落盘前一定要做脱敏而且日志的保留周期要和你的数据合规策略对齐别一存就是三年。1.3 为什么“开源 自托管”在这个阶段是刚需有人会问直接用云端托管版的智能体平台不行吗为什么要自己折腾部署。这个问题在三个场景下答案很明确。第一类是数据不出域的硬约束。金融、医疗、部分制造业的客户数据合同里写死了不能离开指定网络环境。哪怕云端平台承诺不训练、不留存法务那一关也过不去。自托管是唯一解。第二类是深度定制的需求。企业的工具生态往往是内部系统接口文档老旧、鉴权方式五花八门、有些还是十几年前的 SOAP。托管平台的工具接入能力再强也很难覆盖这些奇葩情况。开源的好处是你可以直接改代码实在不行就在工具适配层写个中间件。第三类是成本可控。按调用量计费的模式在小规模试点时很香一旦铺开到几百人日常使用账单会变得很难看。自托管的前期投入是固定的服务器成本边际成本接近于零。我粗略算过一笔账一个中等规模团队每天几千次智能体调用自托管的月度成本大概是用量的三分之一到二分之一规模越大差距越明显。当然自托管不是没有代价。你要自己负责升级、自己扛故障、自己调性能。所以选型的时候一定要看这个项目的迭代活跃度和文档质量一个半年不更新的开源项目再好的架构也别碰。OCE 作为企业发行版在这方面相对稳一些它有一个明确的主线版本和 LTS 策略升级路径是可预期的。2. OCE 的整体设计与模块拆解2.1 四层架构接入、编排、执行、观测我把 OCE 的架构按职责切成四层这个切法不是官方文档里的原文是我自己在部署和读代码过程中整理出来的理解方式对排查问题特别有用。接入层负责对外暴露能力包括 Web 控制台、HTTP API、以及各种渠道的适配器。这一层的关键设计是会话隔离——不同用户、不同渠道进来的请求会被分配到独立的会话上下文里互不污染。我之前踩过一个坑两个用户同时用同一个 Agent上下文串了A 用户看到 B 用户的订单号这种事在接入层没做好隔离的时候非常容易发生。编排层是大脑负责意图识别、任务规划、工具选择和结果聚合。这一层决定了智能体的行为逻辑也是各家平台差异最大的地方。OCE 用的是比较经典的规划-执行-观察循环支持多轮工具调用和中间结果的自我修正。编排层还有一个重要的能力是流程编排也就是把多个 Agent 串成一条工作流前一个的输出作为后一个的输入这个在复杂业务里比单个全能 Agent 靠谱得多。执行层是手脚包含工具运行时、代码沙箱、模型调用网关。这一层是安全风险最集中的地方因为所有对外的副作用都从这里发出。OCE 在这里做了比较重的隔离设计工具调用走独立的进程池代码执行走容器沙箱模型调用走统一的网关做限流和计费。观测层贯穿全局负责日志、指标、链路追踪。这一层平时感觉不到存在出事的时候是救命的。我建议部署完之后第一件事就是把观测层接通别等出了问题再回头补。四层之间的关系可以用一句话概括接入层管谁在跟我说话编排层管我要做什么执行层管我具体怎么做观测层管我刚才做了什么。排查问题的时候按这个顺序从上往下找基本不会迷路。2.2 运行时设计会话、上下文与沙箱会话管理这块OCE 用的是会话-任务-步骤三级结构。一个会话可以包含多个任务一个任务包含多个步骤。这个粒度设计得比较合理因为实际业务里用户的诉求往往是连续的比如帮我查下上周的订单接着那这几个退款的处理一下这属于同一个会话下的两个任务。上下文管理是我认为最值得说的一块。智能体的上下文窗口是有限的工具返回的内容又往往很长如果不做裁剪几轮下来就爆了。OCE 的策略是分层保留系统提示词和关键约束永久保留最近 N 轮对话完整保留更早的对话压缩成摘要工具返回的大块内容走外部存储、上下文里只留引用和摘要。这个策略实测下来比粗暴截断效果好很多尤其是在长任务场景下智能体不会忘记最初的目标。代码沙箱这块要重点说。OCE 支持让智能体写代码并执行这在数据分析场景里非常有用但风险也最大。它的沙箱设计有几个关键点容器隔离、文件系统只读挂载加临时可写目录、网络默认关闭需要显式开白名单、CPU 和内存有硬限制、执行超时有强制中断。我在测试的时候特意让它跑了个死循环15 秒后被干净地杀掉宿主机没受影响这个表现是合格的。提示沙箱的网络策略千万别图省事设成完全放开。我见过有团队为了让智能体能装 pip 包直接给了外网访问权限结果智能体在调试过程中把一个内部服务的健康检查接口刷了几千次。正确做法是配一个内部镜像源或者提前把常用依赖打进基础镜像。2.3 模型接入与路由不把鸡蛋放一个篮子模型接入层支持两类一是通过标准协议接入的在线模型服务二是本地部署的推理服务。OCE 把这块抽象成了统一的 Provider 接口配置里填地址、密钥、模型名就行切换模型不需要改业务代码。我比较欣赏的是它的路由策略设计。你可以按任务类型配不同的模型简单的意图分类用小模型复杂的规划用大模型代码生成用专门的代码模型。这个策略带来的成本优化非常可观。我做过一个对比测试同一个业务流程全用大模型跑一轮的成本是 0.42 元/次按路由策略拆分后降到 0.11 元/次响应时间还快了将近 40%。原因很简单大部分步骤其实不需要那么强的模型用小模型反而更快。路由还带来一个隐性好处是容灾。主模型服务偶发超时的时候可以配置自动降级到备用模型虽然效果会打折扣但业务不至于直接挂掉。这个配置在线上环境里是必需的我有一次就靠这个降级策略扛过了一个下午的服务波动。本地推理服务的接入需要注意显存估算。以 7B 参数模型为例FP16 精度下权重占约 14GB加上 KV Cache 和框架开销实际需要 18GB 左右的显存INT8 量化后权重约 7GB总需求降到 11GB 上下INT4 再砍一半6GB 左右能跑起来但复杂推理任务的准确率会有明显下降。我的建议是如果只是做意图分类和简单抽取INT8 完全够用如果要做多步规划别省这点显存上 FP16 或者直接走在线服务。3. 部署实操一台机器把 OCE 跑起来3.1 资源估算与参数计算先把资源账算清楚别上来就买机器。OCE 的部署形态分两种轻量单机版和集群版。绝大多数团队从单机版起步就够了等并发上来了再考虑集群。单机版的资源需求主要看两件事模型是走在线服务还是本地部署以及并发用户数。如果模型走在线服务OCE 本体是很轻的。我的测试环境是 8 核 16GB 内存同时跑控制台、API 服务、任务队列、PostgreSQL、Redis 和一个向量库峰值内存占用 9.2GBCPU 峰值 60% 左右。这个配置支撑 50 人左右的团队日常使用没有问题。并发能力的估算可以按一个简单公式来所需 worker 数 峰值 QPS × 平均单次任务耗时秒。举个例子如果高峰期每分钟有 30 次智能体调用平均每次任务耗时 8 秒那么30/60 × 8 4也就是至少需要 4 个 worker 并发处理。留一倍余量配 8 个 worker 比较稳妥。每个 worker 的内存占用大概 300-500MB这部分要算进总账里。如果要在本地跑模型显存是大头。假设用 7B 模型的 INT8 量化版本单卡 11GB 起步如果要支持 8 路并发KV Cache 会额外吃掉 6-8GB那就得 24GB 显存的卡。这个账一定要提前算别等部署完了发现跑不动。存储方面PostgreSQL 存业务数据向量库存知识库索引两者都需要持久化卷。一个中等规模的知识库十万级文档块在向量库里大概占 2-3GB加上索引膨胀预留 20GB 比较安全。日志和 trace 数据增长很快建议单独挂一块盘按 30 天保留期估算每天 10 万次调用的量级大概需要 50GB。3.2 容器化部署的完整步骤OCE 官方提供的是容器编排方案我用的是单机容器组合的方式下面是完整流程。这些步骤我在两台不同配置的机器上验证过基本可以直接抄。第一步装容器运行时和编排工具。版本别太老我用的是容器引擎 24.x 加编排工具 v2.20 以上老版本在这个项目上会遇到网络配置的兼容问题。# 确认版本 docker --version docker compose version第二步拉代码并准备配置文件。git clone oce-repo-address oce cd oce/deploy cp .env.example .env第三步编辑.env这是最关键的环节。核心变量大概这几组# 基础配置 OCE_HOST0.0.0.0 OCE_PORT8000 OCE_SECRET_KEY32位以上随机字符串 OCE_LOG_LEVELinfo # 数据库 OCE_DB_URLpostgresql://oce:oce_passpostgres:5432/oce OCE_REDIS_URLredis://redis:6379/0 # 向量库 OCE_VECTOR_BACKENDpgvector OCE_VECTOR_DIM1024 # 模型接入 OCE_MODEL_PROVIDERopenai_compatible OCE_MODEL_BASE_URL你的模型服务地址 OCE_MODEL_API_KEY密钥 OCE_MODEL_NAME模型名OCE_SECRET_KEY这个值千万别用示例里的默认值它用来签发会话凭证和加密存储的敏感配置泄露了等于把整个平台交出去。生成方式建议用openssl rand -hex 32。向量维度OCE_VECTOR_DIM要和你的嵌入模型输出维度严格一致这个填错了不会报错但检索结果会完全乱掉非常隐蔽。我一开始填了 768结果检索出来的内容驴唇不对马嘴排查了大半天才发现是这个参数。第四步启动服务。docker compose up -d docker compose ps正常情况下会起六个容器oce-api、oce-worker、oce-web、postgres、redis、oce-init。oce-init是一次性的初始化容器跑完就退出状态显示Exited (0)是正常的别以为是挂了。第五步初始化数据库和创建管理员账号。docker compose exec oce-api python -m oce.cli db upgrade docker compose exec oce-api python -m oce.cli create-admin \ --email adminexample.internal \ --password 强密码第六步验证。浏览器打开http://机器IP:8000能看到登录页就说明主链路通了。再用命令行确认健康检查接口curl -s http://localhost:8000/healthz | jq返回里应该包含各依赖组件的状态数据库、缓存、向量库都应该是ok。有任何一项不是ok先解决它别急着往下走。3.3 初始化配置模型、密钥与存储服务跑起来只是第一步真正决定能不能用的是配置。这部分我按优先级排一下。模型配置要在控制台的模型管理里做不要直接改数据库。配的时候注意三点一是超时时间要设默认值往往偏长我一般设成 60 秒超时了快速失败比一直挂着好二是要配重试策略网络抖动导致的失败重试两次基本能解决但要注意幂等工具调用类的请求不要盲目重试三是把用量限额配上防止某个 Agent 跑飞了把额度烧光。密钥管理是最容易被忽视的一环。OCE 支持把外部系统的凭证存成加密的 SecretAgent 引用的时候只看到 Secret 的名字看不到明文。这个机制一定要用起来绝对不要在 Agent 的提示词或者工具配置里硬编码密钥。我见过太多项目把数据库密码直接写在提示词里一旦提示词被日志记下来等于全网公开。存储配置分两块。知识库的文件存储建议用对象存储而不是本地磁盘本地磁盘在多副本部署的时候会有一致性问题。向量索引的话如果是十万级以下的规模pgvector 就够了运维成本最低上了百万级再考虑专门的向量库因为 pgvector 在这个量级上的检索延迟会明显上升。还有一块是会话历史存储。默认配置是存在数据库里的量大了之后表会膨胀得很快。建议配一个定期归档策略超过 90 天的会话转冷存储主表只保留近期数据。这个配置不加跑三个月数据库就能到几十 GB。3.4 从单机走向集群的注意事项当单机扛不住的时候就要考虑集群化。OCE 的集群部署不算复杂但有几个坑必须提前知道。第一个坑是会话粘性。智能体的会话上下文是有状态的如果请求被负载均衡随机打到不同实例上上下文就断了。解决办法是把会话状态外置到 Redis或者在负载均衡层做一致性哈希。OCE 支持前者配置里打开OCE_SESSION_BACKENDredis就行这个开关一定要在扩容前打开否则扩容当天就会出问题。第二个坑是任务队列的重复消费。多 worker 场景下如果一个任务处理时间超过了队列的可见性超时会被另一个 worker 重新捞起来执行导致重复副作用。解决办法是把超时时间设得比最长任务耗时还长同时让所有工具调用支持幂等键。这个坑我在一个批量处理场景里踩过一个任务被执行了三次重复发了两封通知邮件非常尴尬。第三个坑是配置漂移。集群里各实例的配置如果不一致会出现有时候能用有时候不能用的诡异现象。建议所有配置走统一配置中心或者挂载同一份配置卷别手动改某一台机器。扩容的时机判断我的经验是看三个指标API 的 P95 延迟持续超过 3 秒、任务队列积压持续超过 100 条、CPU 持续高于 70%。任意一个满足了就可以考虑加实例不要等用户投诉了才动手。4. 让智能体真正“持证”权限与审计落地4.1 智能体身份体系怎么设计身份体系的设计原则我总结成一句话一个 Agent 一份身份一个场景一套权限。听起来简单执行起来要克制住图省事直接复用的冲动。具体做法上我建议按业务域划分 Agent而不是按功能划分。比如客服域 Agent运营域 Agent财务域 Agent每个域下面再按细分场景建具体的 Agent 实例。这样划分的好处是权限边界天然清晰客服域的 Agent 不可能拿到财务数据从架构上就杜绝了越权。每个 Agent 的身份信息要包含四个要素唯一 ID、归属域、责任人、有效期。前三个好理解第四个有效期经常被忽略。很多团队的 Agent 建完就永久有效人员离职了、业务下线了Agent 还在跑凭证还在生效这是很大的隐患。我的做法是默认给 90 天有效期到期前自动提醒责任人续期没人管就自动禁用。凭证绑定这块要注意最小权限。别用一个超级账号的 Key 给所有 Agent 用。正确做法是为每个 Agent 单独申请服务账号只授予它实际需要的那几个接口。麻烦是麻烦了点但出事的时候能精准定位和快速止血。我在一次安全演练里做过对比权限收敛的 Agent 被诱导越权时调用直接被网关拒绝权限放开的 Agent 则成功读到了不该读的数据。这个差别就是设计阶段有没有多花那半小时。4.2 工具调用的三道闸门工具调用是智能体产生副作用的地方也是风险最高的地方。OCE 提供了三层控制机制我把它叫三道闸门建议全部打开。第一道闸门是工具白名单。Agent 只能调用注册给它的工具未注册的工具调用请求直接拒绝。这一层挡住的是智能体自己发明了一个工具的情况。别觉得不可能模型在提示词被污染的情况下确实会尝试调用未定义的工具虽然多半会失败但日志里那一堆报错很影响排查。第二道闸门是参数级约束。光控制能调哪个工具不够还要控制能用什么参数调。比如查订单的工具要约束只能查当前会话用户自己的订单 ID不能传任意 ID 进去。OCE 支持在工具定义里挂参数校验策略可以是正则、可以是枚举、也可以是一段自定义的校验逻辑。这个能力非常关键因为绝大多数数据泄露不是通过调用了不该调的工具而是调对了工具但传了不该传的参数。第三道闸门是人工确认。对于高危操作比如退款、删除、对外发送建议配置成需要人工确认。OCE 的做法是把这类调用挂起推一条确认消息给指定的人确认后才继续执行。这会牺牲一点效率但换来的是可控性。我的建议是按金额或者影响范围分级小额低风险的全自动超过阈值的走确认这样既不影响日常效率又守住了底线。提示人工确认的审批人不要设成发起人自己否则等于没有审核。审批链路要落到具体的岗位角色上而不是具体的人这样人员变动时不会断。4.3 审计日志与全链路追踪审计这块我想讲一个真实用上的例子。有一次线上反馈说某个数据被改错了但没人承认操作过。我们从 OCE 的 trace 里捞出了那条记录发现是一个定时触发的 Agent 在批量处理时因为上游返回的数据格式变了把某个字段解析成了空值然后写回了数据库。整条链路从触发时间、模型决策、工具入参、返回结果到写库操作全部有记录十分钟定位到根因。这个例子说明审计日志的价值不在于记录而在于能还原现场。要做到这一点日志里必须包含几个关键字段字段说明是否必填trace_id全链路唯一标识贯穿所有步骤必填agent_id执行主体必填session_id会话标识用于关联上下文必填step_type步骤类型规划/工具调用/生成必填tool_name工具名称工具调用时必填input_digest入参摘要脱敏后必填output_digest出参摘要脱敏后必填token_usage消耗的 token 数必填duration_ms耗时必填status成功/失败/超时必填error_code失败原因码失败时必填字段设计上有个细节要注意入参出参存摘要不存全量。全量存的话日志里会混进大量用户隐私数据合规上过不去存储成本也扛不住。摘要的做法是保留结构、脱敏值域比如订单号保留后四位金额保留量级。日志的保留策略我建议分三级热数据 7 天存在数据库里支持即时查询温数据 90 天存对象存储查询走异步冷数据按合规要求保留一般不超过一年。这个分级能显著降低成本同时不影响日常排查。追踪这块OCE 支持标准的链路追踪协议可以对接主流的可观测平台。我的建议是把 trace 和你现有的监控体系打通这样智能体的问题能和普通服务的问题放在一起看排查效率高很多。单独搞一套的话出问题时要在两个系统之间来回切很痛苦。5. 场景验证三个能立刻跑起来的用法5.1 内部知识问答从能答到答得准这是最容易落地的场景也是最多团队做砸的场景。做砸的原因通常不是技术问题而是知识库的质量问题。我接手过一个知识问答项目之前的效果很差用户问三个问题有两个答不准。我看了下他们的知识库是把整个内部文档系统全量灌进去了里面有大量过期的、重复的、格式混乱的内容。检索的时候捞出来的全是噪音模型再好也答不对。正确的做法是分层处理。第一层做准入筛选只把权威的、在有效期内的高质量文档纳入过期的、草稿状态的直接排除。第二层做结构切分别按固定长度硬切要按语义边界切标题、章节、表格各自成块块与块之间保留层级关系。第三层做元数据标注每块内容都打上来源、更新时间、适用范围这些标签检索时可以按标签过滤。切分粒度的选择上我的经验值是 300-800 字一块太短了上下文不够太长了检索精度下降。对于操作手册类的文档按步骤切分效果最好对于政策制度类的按条款切分效果最好。配置上还有个关键参数是召回数量。默认召回的 3-5 条往往不够我一般设成 10 条然后加一个重排序环节筛出最相关的 3 条给模型。重排序模型的引入让准确率提升非常明显我测的那批问题里准确率从 62% 提到了 84%。这个环节值得花时间配。还有一个容易忽略的点是兜底策略。知识库覆盖不到的问题一定要让智能体明确说没有找到相关内容建议联系某某而不是硬编一个答案。我在提示词里加了强约束并且用测试集专门验证了这块避免它一本正经地胡说八道。5.2 工单分派与初筛把重复劳动干掉这个场景的投入产出比是我见过最高的。一个中等规模的支撑团队每天几百个工单人工分派的准确率和速度都受限于值班人员的经验和状态。用 OCE 做这件事的流程是工单进来触发 AgentAgent 先做意图分类判断类型然后抽取关键信息产品、模块、错误码、紧急程度接着匹配历史相似工单给出初步排查建议最后根据分类结果分派到对应的处理组。实现上的关键点是分类体系要和现有流程对齐。别自己重新设计一套分类直接沿用现有的工单分类标准否则智能体分出来的结果和工单系统对不上等于白做。我在配置的时候把现有的分类标准和每个分类的判断依据都写进了提示词还给了正反例子各三五个分类准确率能到 85% 以上。紧急程度的判断要保守。宁可误判成紧急让人工多看一眼也不能把紧急的判定成普通。我的做法是给紧急判断加一个存疑就升一级的规则牺牲一点准确率换安全。这块还能做一个延伸相似工单推荐。把历史工单的处理记录做成知识库新工单进来时先检索相似的历史案例把处理方案附在分派信息里。这个功能对一线人员帮助很大尤其是处理冷门问题的时候。5.3 数据分析助手沙箱能力的最佳试验场这个场景能充分发挥代码沙箱的价值。用户用自然语言提问智能体先去查数据结构然后生成查询代码在沙箱里执行拿到结果后做可视化和解读。实测下来有几个经验值得分享。第一是给智能体一份准确的数据字典表名、字段名、含义、取值范围都写清楚这比让它自己去猜准确率高太多。第二是强制走只读账号分析场景永远不需要写权限这个约束要在数据库层面做死不能只靠提示词。第三是限制单次查询的资源消耗加个查询超时和结果集行数上限防止一条没加条件的查询把数据库拖垮。我配的是 30 秒超时、十万行上限够用且安全。生成的代码要做静态检查把 DROP、DELETE、UPDATE 这类关键字直接拦掉。虽然账号是只读的双保险没坏处。还有就是执行结果要校验合理性比如用户问上个月销售额返回了个 0 或者一个明显离谱的数要提示用户而不是直接展示。我在提示词里加了合理性检查的指令让它对异常结果做二次确认。这个场景的实际效果我测的那批问题里简单查询单表聚合、条件筛选的准确率接近 95%涉及多表关联和复杂口径的准确率降到 70% 左右。所以定位要清楚它是给业务人员做快速探索的工具不是替代专业报表的手段。复杂分析还是要走既有的 BI 流程。5.4 压测与成本核算上线前必须做的一笔账上线前一定要做压测而且要带着成本一起看。我用的是一个 50 并发、持续 10 分钟的测试脚本模拟真实用户的操作序列。结果大概是这样的平均响应时间 4.2 秒P95 延迟 11 秒P99 延迟 23 秒错误率 0.3%主要是模型服务的偶发超时。这个表现在可用范围内但 P99 偏高主要原因是复杂规划任务的步骤多尾延迟拉得比较长。优化方式是给规划步骤设一个最大步数上限超过就强制收敛我设的 8 步P99 降到了 14 秒。成本方面我按三种模型配置做了对比配置方式单次调用平均成本平均响应时间适用场景全用大模型0.42 元6.8 秒复杂规划、高准确率要求全用小模型0.06 元2.1 秒简单分类、信息抽取混合路由0.11 元3.9 秒大多数生产场景混合路由的性价比明显最高。我的配置策略是意图分类和参数抽取用小模型任务规划和结果生成用大模型代码生成用专门的代码模型。这个配比在保证效果的前提下把成本压到了四分之一。还有一笔隐性成本是重试和失败重跑。失败率 1% 听起来不高但如果失败的任务要重跑三次实际成本就多了 3%。所以宁可把提示词调好、把工具容错做好也别指望重试兜底。6. 踩坑记录与排查速查表6.1 部署阶段的高频问题容器起不来日志里报数据库连接失败。九成是OCE_DB_URL里的主机名写错了容器间通信用的是服务名不是 localhost。另外检查一下数据库容器是否已经就绪编排工具虽然支持依赖顺序但数据库真正可接受连接和容器启动之间有几十秒的差建议给应用容器配一个健康检查加延迟启动。控制台能打开但登录后白屏。这个通常是静态资源路径问题或者反向代理没有正确转发。如果你在前面挂了一层代理确认X-Forwarded-Proto和X-Forwarded-For这两个头有正确传递否则应用生成的跳转地址会不对。初始化脚本报表已存在。说明之前跑过一次没跑完。先手动确认数据库里的迁移版本表看看停在哪个版本然后从那个版本继续。别直接删库重来除非你确定里面没有需要保留的数据。文件上传失败。检查两处上传大小限制和存储路径权限。上传大小在配置里和反向代理里都要改只改一处不生效。存储路径如果挂的是宿主机目录注意容器内的用户 ID 和宿主机是否一致权限不匹配会写不进去。6.2 运行阶段的高频问题智能体不调用工具一直在自言自语。这是提示词问题。检查工具的description写得够不够清楚模型是靠描述来判断什么时候用哪个工具的。描述里要写清楚工具干什么、什么情况下用、参数怎么填。我见过描述只写了个查询数据的模型根本不知道什么时候该用自然就不调。工具调用参数格式错误反复重试。模型生成的参数偶尔不符合 schema重试几次能对上但很浪费。解决办法是在工具定义里给参数加示例越具体的示例效果越好。另外可以开启参数自动修复把校验错误回传给模型让它自己改。上下文超长导致截断。开启上下文分层管理把长返回的内容外置。同时检查一下是不是有工具返回了超大的结果比如一个查询返回了几万行这种情况要在工具层就做限制。响应特别慢但资源没跑满。大概率是在等模型服务。看一下模型调用的耗时分布如果是长尾严重考虑加超时和降级。还有一个可能是流式输出没开用户要等全部生成完才看到内容体感上会慢很多。同一个问题两次回答不一样。这个在智能体场景里是常态因为工具返回的数据可能变了。如果你需要确定性结果把温度参数调到 0并且固定工具返回的排序。6.3 常见问题速查表现象可能原因排查动作解决方式容器反复重启依赖服务未就绪查看容器日志最后 50 行加健康检查与启动延迟登录后白屏静态资源或代理头缺失浏览器控制台看 404补全转发头配置检索结果不相关向量维度配置错误核对嵌入模型输出维度修正维度配置并重建索引智能体不调工具工具描述模糊查看规划步骤的模型输出补全工具描述与参数示例任务重复执行队列可见性超时过短查看队列的重复消费记录调大超时并加幂等键会话上下文错乱未开启会话外部存储检查多实例会话配置切换 Redis 后端沙箱执行被强杀超出资源或时长限制查看沙箱退出码调整限制或优化代码审计日志缺步骤追踪未全链路开启按 trace_id 查询缺失段落补全 span 埋点成本异常飙升未设用量限额按 Agent 维度看消耗排行加限额并优化路由策略高峰期大面积超时worker 数不足对比 QPS 与 worker 数按公式扩 worker6.4 几条我认为最值钱的经验第一条先用最小可用配置跑通全流程再谈优化。我见过太多团队在部署阶段就纠结用哪个向量库、要不要上集群、模型选哪个结果两周过去还没跑起来一个 Demo。正确的顺序是先让它跑起来能回答一个问题然后再逐步替换组件。第二条把提示词当代码管理。提示词的改动对效果影响巨大必须有版本控制、有测试集、有回归验证。我现在的做法是每个 Agent 的提示词都有独立文件改完跑一遍固定测试集准确率掉了就不合并。这个习惯能省掉无数次昨天还好好的今天怎么就不行了。第三条观测先行。部署完第一件事是把日志和追踪接通第二件事才是配业务。顺序反了的话出问题时你只能靠猜。第四条别追求全能 Agent。一个能处理所有事情的 Agent最后往往什么都处理不好。按场景拆分每个 Agent 职责单一提示词写得精准效果反而更好维护也更容易。第五条给智能体设边界比给能力更重要。能力可以慢慢加边界一旦放开就很难收回来。宁可一开始限制得严一点被业务吐槽几句也别等出了事故再回头补。这套东西我在两个不同规模的团队里推过从最初的这东西不靠谱到后来的离不开中间真正的转折点不是模型升级而是把权限和审计这套基建补齐了。有了这层保障业务方敢用安全方敢放运维方敢维护。技术本身的进步是线性的但信任的建立是阶跃的跨过去之后整个事情的性质就变了。如果你们也准备动手我的建议是先挑一个数据敏感度最低、流程最标准化的场景做试点把身份、权限、审计这三件事完整跑一遍。这个过程大概需要两到三周会有点枯燥但跑完之后你会对整个体系有完全不同的理解后面铺开到其他场景就是复制粘贴的事了。
