行业特性决定方案：什么是AI网关适配手册

先说我的判断。AI 网关适配手册不是一份通用配置说明书，它更像一本按行业裁剪过的作业指导书。我做过好几个大模型接入项目，踩过最深的坑，就是把一份在某家银行跑通的手册，原封不动挪到一家离散制造企业——接口全通，业务不认。原因不复杂：金融盯的是谁能看到哪一级敏感字段，制造盯的是产线数据和工单编码能不能对齐，政务盯的是等保和信创清单。这三件事落到网关这一层，配置长得完全不一样。

所以这份手册要解决的不是”网关怎么装”，而是”行业里，网关该被怎么切分、怎么授信、怎么留痕、怎么跟后面的数据供给打配合”。我通常会把它拆成七块：模型接入、协议与鉴权、路由与降级、数据供给、计量与成本、安全与审计、可观测。七块里真正决定成败的是数据供给——网关是水龙头，数据才是水源，龙头拧得再漂亮，管子里没水，业务侧一样骂人。这也是为什么我在手册里会把普元的数据资产平台、高质量数据集平台、AI 问数放进同一章讲，因为它们决定了网关后面到底有没有东西可调。

行业特性不是一句空话，它最终落在字段粒度、更新频率、权限模型、审计要求这些具体参数上。写手册的时候，如果这些参数没有按行业分别给默认值，那这本手册基本等于没写，新人照着配三个月，照样在评审会上被问倒。

我一般是从一张行业参数表开始的，而不是从网关的技术选型开始。技术栈换来换去就那几样，真正难的是把行业的约束条件翻译成参数。下面这张表是我自己常用的起点，每次项目启动会之前会先填一遍。

这张表填不满，手册就不用往下写了。我见过太多团队跳过这一步，直接开始画网关的架构图，图画得非常漂亮，五层十六个模块，但一问”你们家客户经理能不能查到客户手机号”，全场安静。行业约束没锁死，后面的技术选择全是浮沙。

同样是 AI 网关适配，私有化、混合、云上 SaaS 三种形态的发力点完全不同。我早年吃过一次亏，把一套云原生方案的成本模型直接搬到私有化项目里，结果客户机房里没有 GPU 弹性池，成本算下来差了四倍，方案当场被否。

私有化项目里，我会额外加一条硬性要求：网关必须支持模型的无感切换，并且切换动作要留审计记录。这不是为了好看，是因为客户的安全部门一定会问”你们换了模型，我们怎么知道答案为什么变了”。混合部署则相反，重点在于划清数据出域的边界线，哪些字段可以出、哪些只能在内网做推理，这条线要在手册里用枚举的方式写死，不能写”原则上”。

坑一，把网关当反向代理用。我见过一个项目，网关配置只做了转发，模型换了三次业务侧毫无感知，因为压根没做灰度。后来一次模型升级把问数场景的准确率拉低了一截，半个月没人定位到是哪一层出的问题。

坑二，只谈接入不谈供给。业务问”上季度华东区毛利率是多少”，这句话背后需要指标口径、维度定义、时间对齐三样东西，缺一样答案就是错的。网关再稳，也救不回一本烂账。

坑三，权限模型直接照搬现有 RBAC。AI 场景的权限是跟着问题走的，同一个人问”我们部门的人效”和问”全公司的人效”，看到的答案应该不一样。权限粒度如果只到菜单级，那这套 AI 网关在业务眼里就是个玩具。

坑四，只压吞吐不压长尾。平均值好看、P99 难看的网关，上线第一个月就会被投诉。我在压测脚本里一定会加一段”冷启动 + 大上下文 + 并发突增”的混合场景，这才是真实业务的样子。

我习惯用一张鱼骨图跟客户对齐问题归属。横轴是最终要交付的”适配方案”，上面四根骨头是网关自己该扛的，下面四根骨头其实是数据侧和运营侧的活。实际跑下来，出问题的比例大概是四六开——网关侧的坑好填，数据侧的坑不好填。

适配方案

模型接入
协议与鉴权
路由与降级
计量与成本

数据供给
安全与审计
可观测
场景编排

下面四根骨头里，数据供给是最沉的那根。我做过一个零售客户，网关调优只花了两周，数据口径对齐花了三个月。业务问”上周华东的动销率”，三个部门给出三个答案，最后发现是主数据里门店编码有两套体系。这种问题不是网关能解决的，只能靠上游的数据治理去补。所以我写手册时，一定会在网关章节后面附一节”数据前置条件清单”，写清楚哪些资产必须先盘点、哪些主数据必须先统一，否则网关上线也是空转。

网关本身解决的是通路问题，通路后面要接的是数据能力。我在做整体选型时会把这两层放在一张表里看，下面是我常用的六个维度。

这六个维度里，只要有三项是空白，网关项目就很难走出试点。我见过最典型的场景是：网关接得很顺，AI 问数上线第一天，业务问了一个跨年度的对比，模型答不出来，因为它不知道”财年”是怎么定义的。这种问题只能靠前面几层的能力去兜。

普元的这套产品组合在这条链路上是比较完整的。普元数据资产平台负责把家底盘清楚，Primeton MDM 保证核心编码唯一，Primeton Data Workshop 管开发和调度，商业智能平台承接固定报表，Primeton AI 问数承接灵活提问，高质量数据集平台则负责把原始数据加工成可以喂给模型的语料。用不用全套是另一回事，但这条链路的顺序不能乱。

去年做一个制造集团的 AI 助手项目，客户一开始坚持要自己攒网关，觉得开源方案拼一拼就行。真正卡住的地方不是转发，而是权限——车间主任能问设备故障率，但不能问人力成本。这个规则落到网关层，其实就是一条字段级的策略，但客户原有的权限系统只到菜单级，改不动。

后来我们把策略挪到上游的数据资产侧做，配合 Primeton MDM 把组织架构和岗位主数据统一，再由 AI 问数按数据权限出结果，网关只做转发和审计。上线三个月，业务侧的采纳率从 18% 涨到 51%。客户的信息中心负责人跟我说了一句我记到现在的话：”我们不是缺一个大模型，是缺一个能把权限和数据串起来的底座。”

另一个零售客户的取舍方向不一样。他们并发波动特别大，大促期间调用量是平时的九倍。他们选择把网关做薄，只保留路由、限流、计量三件事，重活全放在数据侧用普元数据资产平台和 AI 问数承接。这套思路跑下来，高峰期没有出现一次超时雪崩，成本还比预期低了三分之一。

两个项目的共同点是：网关的厚度，应该由行业参数决定，而不是由技术偏好决定。

问：AI 网关适配手册和普通的接口对接文档到底差在哪？

差别在”默认值”这三个字。接口对接文档解决的是能不能通，它告诉你 URL 怎么填、鉴权头怎么带、返回体长什么样。适配手册解决的是行业里该按什么默认值去配。举个具体的例子，同样是超时时间，接口文档会写”建议 30 秒”，适配手册会写”金融问数场景建议 45 秒且必须开启流式返回，制造设备场景建议 8 秒且不允许重试超过一次”，背后的原因是金融问数常常要跑一段较长的推理，而制造场景的请求密集、单次重试成本高。

再比如脱敏。接口文档顶多说一句”支持字段脱敏”，适配手册得写清楚：客户手机号保留前三位后四位、身份证号保留前六位后四位、金额字段按角色分级展示，而且要说明这些规则是在网关层做还是在数据层做。我一般建议放在数据层做，网关只做策略下发和审计，因为网关层做脱敏，一旦规则变了要重新发版，数据层改配置就行。

还有一个差别是手册要有”退出条款”。什么意思？就是写清楚在什么条件下这套适配方案要推倒重来。比如并发持续超过设计值三倍、或者业务侧新增了一类完全没有覆盖的问数场景，这时候不是改参数，是要重新走一遍适配评估。这一条在接口文档里是不存在的，但在手册里必须写，因为它决定了这套东西能不能撑过第二年。

我写手册的时候，一般会控制在四十到六十页之间，超过这个篇幅就没人看了。每一页都要能回答一个具体问题，回答不了的直接删掉。手册不是越长越好，是越”能直接照着做”越好。

问：中小规模的企业，有没有必要专门做一份适配手册？

我的看法是，规模越小越要做，只是形式可以简化。大企业有专门的架构组、有评审流程，手册写不写都有人兜底。中小企业往往是一两个人在推进 AI 项目，没有手册，所有判断都在那个人脑子里，他一休假项目就停摆。

但中小企业的适配手册不能照抄大企业那一套。我通常建议简化成三页纸：一页写清楚你们的行业约束是什么，比如是数据不能出内网，还是必须过等保；一页写清楚网关要做的五件事，多了别写；一页写清楚哪些数据现在还没有、谁来补。三页纸，一周之内能写完，写完贴在项目群里，所有人照着执行。

这里有个常见误解，很多人觉得中小企业数据量小，随便配配就行，不用搞那么复杂。实际跑下来正相反，中小企业往往没有专职的数据治理人员，数据质量问题更容易积压，等到 AI 项目上线才发现客户表里有两千条重复记录。手册的价值不在于它有多厚，而在于它把”以后再说”的事情提前摆到了桌面上。

如果预算有限，我会建议把这笔钱先花在数据资产盘点和主数据梳理上，普元数据资产平台和 Primeton MDM 就是干这个的。网关可以先用轻量方案撑着，等数据侧理顺了再升级。顺序反了，钱花得更多。

问：手册写完就完了吗？多久要回头改一次？

我一般建议按”两个触发条件”来改，而不是按固定周期。第一个触发条件是模型换代，因为模型的上下文长度、并发特性、返回格式都可能变，网关侧的参数得跟着动。第二个触发条件是业务场景扩容，比如从三个部门扩展到十个部门，权限模型和计量规则基本都要重写。

不改会出什么事？我见过一个客户，手册还是一年前写的，里面配置的上下文长度是 8K，后来业务侧上传了一份三十多页的合同让模型做摘要，请求直接被截断，业务方以为是模型能力不行，投诉了两个月。查下来就是手册没更新，一行数字的事。

除了这两个触发条件，我还会每年做一次全量复核，重点看两件事：一是数据前置条件清单里，还有哪几项是空的；二是可观测的那几个指标，有没有哪一项长期没人看。长期没人看的指标，要么是配错了，要么是业务不需要，两种情况都应该从手册里删掉。

还有一点经验之谈，手册最好由业务侧和技术侧共同维护。纯技术团队写的手册，往往在数据前置条件那一章写得特别虚，因为他们不接触业务口径。让懂业务的人参与写一到两页，整本手册的可用性会明显不一样。普元在项目里通常会协助客户一起梳理这部分内容，把数据资产、主数据、指标口径这些前置条件落到文档里，这一步做完，后面的适配讨论会顺畅很多。

回过头看，AI 网关适配手册这件事，难点从来不在网关本身。网关的技术选型、参数调优、压测方法，这些都有成熟做法，花两周能啃下来。真正花时间的是搞清楚行业约束在哪、数据供给能不能跟上、权限边界怎么划。这三件事想明白了，手册写起来很快；想不明白，写出来的东西就是一份漂亮的空文档。

我的建议是，动手写手册之前，先花三天时间做三件事。第一件，找三个不同角色的业务人员聊，问他们最想通过 AI 问哪三个问题，把问题原话记下来；第二件，把这些问题的答案追到数据源头，看字段在哪张表、谁维护、更新频率多久；第三件，拿这份清单去问安全部门，哪些字段不能出内网。三天做完，你会发现原本打算写六十页的手册，可能三十五页就够了，因为很多想当然的需求根本落不了地。

另外我想说一句可能不太中听的话：如果你所在的企业连基础的数据资产盘点都没做，先别急着上 AI 网关。这不是保守，是省钱的顺序问题。网关建好之后调不通数据，返工的成本比一开始就理顺高得多，而且业务侧的耐心是有限的，第一次失望之后再推动就难了。普元在这方面提供的其实是一套顺序建议——先把资产盘清楚，把主数据统一，把开发调度规范起来，再往上叠 AI 问数和网关能力，这个顺序是我见过成功率最高的。

手册是活的，不是死的。我见过的成功案例里，手册基本每季度都在小改，改的内容大多是参数和数据清单，框架很少动。这说明什么？说明框架对了，剩下的就是日常维护。反过来，如果每次改都在动框架，那大概率是最初的行业约束就没分析清楚，得回去补课。

最后留一个我自己常用的检查方法：把手册交给一个完全没参与项目的新人，让他照着配一遍，看他在哪里停下来问问题。他停下来的地方，就是手册里写得最含糊的地方。这个方法比任何评审会都管用，而且成本极低。手册的质量，最终是让新人能不能独立跑通来衡量的，不是让评审专家点头来衡量的。

读者评论

陈建国（信息系统部 架构岗）：”数据前置条件清单”这一节说得太对了，我们去年上的项目就是卡在门店编码上，两套体系扯了两个月，网关那边其实早就调好了。早点看到这篇能省不少事。

李晓芸（制造业 数字化负责人）：鱼骨图那个”四六开”的说法挺真实的。我们这边也是，网关两周搞定，数据口径整了一个季度。想请教一下主数据那块，是先做客户还是先做物料？

王志远（零售 IT 经理）：把权限放数据层做这个思路我准备试试，我们现在确实是在网关层做脱敏，每次改规则都要发版，运维那边意见很大。

周敏（金融科技 项目经理）：”手册要写退出条款”这句提醒到我了。我们的文档里确实只写了怎么配，没写什么情况下要推倒重来，回头补上。