1. 为什么存量培训系统接入 AI需要一个“能力网关”而不是“直接调 API”做培训系统开发的同行应该都有体会存量系统的 AI 升级和从零做一个 AI 原生应用完全是两码事。新项目可以直接选一个模型、用一套现代的调用框架但存量培训系统往往已经跑了三五年甚至更久里面有课程库、题库、学员管理、学习记录、消息通知等一整套业务模块代码结构不统一技术栈也可能混着 Java、PHP、甚至老的 .NET。这时候如果各个业务模块各自接入 AI比如 A 模块用 OpenAI、B 模块用通义千问、C 模块又接了个开源模型那后果就是重复开发、Key 散落各处、费用完全不可控、模型一换就得动业务代码、日志满天飞却看不到全链路。我在实际项目里见过最夸张的情况同一个系统里接了四家 AI 厂商每家都单独写了一套调用逻辑结果模型升级了一个版本四个模块的行为全变了排查问题要挨个看日志非常痛苦。所以存量培训系统接入 AI 的核心思路是先建一个统一 AI 能力网关再在网关和业务系统之间加一层适配层。业务系统不需要直接感知“我用的是哪家模型”它只需要说“我要什么能力”网关负责找哪个模型最合适、需要多少成本、超时了怎么处理。适配层则负责把培训系统里“课程内容检索”“学习路径规划”“题目生成”这些具体业务翻译成网关能理解的标准化请求。这样设计的好处有两个。第一业务侧零侵入或低侵入。存量系统的各个模块不需要大规模改代码只需要把原来调用内部服务的方式换成调用网关的标准接口。第二模型侧可替换。今天用 GPT-4o 效果好明天换成国产模型成本更低网关层做一次路由配置就行业务代码完全不动。这套方案的适用人群很明确手里有存量业务系统不限于培训系统、想接入 AI 能力但不想推倒重来、又希望后续能灵活切换模型供应商的技术团队或架构负责人。下面我按实际落地时最容易踩坑的模块逐个拆开讲。2. 统一 AI 能力网关的整体设计从“模型路由”到“成本管控”网关是整个升级方案的中枢它的职责不是简单地把请求转发给大模型而是把所有跟模型相关的共性能力沉淀下来。存量培训系统的业务模型有它自己的特点请求量大但单次请求的数据量相对有限主要是文本、题目、课程大纲并发高峰集中在工作日的上午和下午月底或培训季会有明显的脉冲式流量。抛开培训场景这套网关设计对于任何存量系统CRM、OA、内部知识库都是通用的。2.1 能力抽象不要暴露“模型名”只暴露“能力名”网关最核心的设计决策是能力抽象。业务方不应该在代码里写callGPT4()或者callQwen()而应该写generateQuestions()、summarizeCourse()、recommendLearningPath()。我把培训系统里会用到的 AI 能力分成了三类生成类出题、生成课程摘要、生成学习计划、教案起草理解类学员提问意图识别、聊天机器人、学习笔记结构化分析转换类讲义转思维导图、PPT 大纲转讲义、试题难度标定每一类能力在网关里对应一个稳定的 API 端点例如/v1/capabilities/generate-exercise。这个端点内部再根据预设策略路由到不同模型。初学的人容易忽略的一点是能力抽象不只是给 API 起个好名字而是要定义一套统一的数据契约包括输入参数的语义、输出结果的格式、错误码规范。否则每个能力都长得不一样适配层就没法写了。2.2 模型路由策略按场景、成本、稳定性三层决策模型路由是网关里工作量最大的模块。我的做法是给每个能力配一张路由表路由决策按优先级往下走决策维度典型配置使用时机场景匹配长文本摘要用上下文窗口大的模型代码相关任务用代码能力强的模型首次请求时成本策略大模型预算超限时自动降级到中等模型按日/按月控制稳定性策略主模型连续失败3次切换到备用模型实时监测这里有一个在培训系统场景里特别容易踩坑的地方模型路由不能只按“模型能力大小”来分要考虑“token 成本随会话长度增长”的问题。培训系统的 AI 对话往往是多轮交互学员问一道题、追问解题思路、再问类似题目一小时下来上下文可能有几万 token。如果一开始路由到了贵的模型后面的对话会越来越贵。所以我的网关里默认加了一个策略首轮用强模型后续轮次自动评估是否需要维持强模型如果只是简单的追问自动切换成便宜的中型模型。这个策略用一句话总结就是网关不只是“分发请求”还要“管理对话的预算生命周期”。2.3 成本与限流培训系统最容易忽视的一环培训系统的技术负责人经常跟我说他们最初接 AI 时根本没考虑限流结果月底账单出来吓一跳。AI 网关必须在第一天就把成本管控做进去不然后面补会很痛苦。我在网关里做了三个维度的控制第一个是Token 级预算。给每个业务模块/每个学员/每天设置 Token 上限例如“免费用户每天 1 万 token、付费用户 10 万 token”。这个不能只在网关上配要结合培训系统的用户体系在适配层把用户 ID 传给网关网关上才能做精确统计。第二个是速率控制。培训系统有一个特点上课期间平台同时在线人数很高可能几百上千人同时提交 AI 请求。如果不做速率控制不仅 AI 供应商会限流网关自身的线程池也会被打满。我在网关里用令牌桶算法按模块分桶课程摘要模块 50 QPS、出题模块 30 QPS、聊天机器人 100 QPS。第三个是降级预案。预算耗尽或供应商故障时网关自动切到备用模型或返回降级文案。比如“智能出题”不可用时返回题库中预置的相近题目聊天机器人不可用时返回 FAQ 命中结果。降级以后要在监控看板上显著标识避免学员投诉后一线老师都不知道原因。2.4 统一鉴权与链路追踪存量系统往往有自己的一套用户认证体系这里关键是让网关识别业务系统的用户身份而不是重复创建一套。我的做法是业务系统在调用网关时在请求头里带一个由业务系统签名的 JWT里面包含user_id、tenant_id、module、capability等字段。网关先验签再按租户/用户维度做资源配额扣减。链路追踪这一块我在最初一版网关里偷懒没做后来排查一个“学员反馈答案质量忽好忽坏”的问题时因为没有 trace 信息花了整整两天才定位到是某次发版导致路由策略被覆盖。后来补上了基于 OpenTelemetry 的全链路追踪每个 AI 请求从业务系统出发到网关路由决策、到模型供应商返回、再到结果返回耗时和 token 消耗全部打点。这个补救经验我的建议是从第一行代码开始就接入链路追踪不要留到“等以后有需要再说”用到的时候真的后悔莫及。3. 适配层设计弥补“网关通用”和“业务具体”之间的缝隙网关解决了“谁来调模型、怎么调、怎么控成本”的问题但业务系统不会天然就懂网关的标准协议。适配层在这里扮演翻译官的角色。为什么单独需要适配层而不是在业务系统里直接改因为存量系统的业务逻辑通常分散在多个模块中各模块的数据结构、存储方式、出参格式千差万别。做适配层可以隔离变化让接入过程变成“逐个模块适配而不是整体重构”。3.1 结构化接入把“培训场景”翻译成“网关请求”适配层的核心工作是把业务语义翻译为网关请求。就拿培训系统里最常见的“智能出题”来举例。存量培训系统里的题库表通常是这样题目 ID、所属课程、题干、选项、答案、难度、知识点标签。适配层要做的是从业务系统拿到课程信息和知识点列表后组装成网关要求的格式{ capability: generate_exercise, user_id: S10001, module: exam, payload: { course_id: C2001, knowledge_points: [TCP/IP, 子网掩码, 默认网关], difficulty: medium, question_count: 5, format: choice, language: zh } }网关拿到这个请求后才知道应该调用哪个模型、需要多少 token 预算、返回的题目需要什么格式。如果不做适配层业务系统就得自己去拼提示词对接大模型文档一旦模型升级提示词格式变了系统就挂了。适配层存在最大的价值就是它是业务代码与大模型之间唯一需要修改的地方。另一个典型场景是学习路径推荐。培训系统里有学员的历史学习记录、考试成绩、岗位要求适配层把这三种数据聚合成一个“学员画像”再翻译成网关请求。业务系统根本不需要知道底层用的是什么推荐模型。这也意味着如果后续想把推荐逻辑从大模型换成传统协同过滤算法只需要在适配层的内部实现里做切换业务模块和网关都不用动。3.2 模型能力差异适配提示词模板 响应解析这是适配层里细节最多的地方。简单说不同的模型对同一个任务的理解和输出格式可能差异巨大适配层要做“接口统一、能力隐藏”。我在项目里做了一个两层适配。第一层是提示词模板管理。每个业务能力配置多套提示词模板分别针对不同模型家族。比如 GPT 系模型对结构化输出要求清晰的指令式描述国产开源模型可能对角色设定更敏感专业问题则需要补充定义和示例。适配层根据网关返回的“实际路由到哪个模型”这个信息动态选择对应的模板。注意这里不是把模板硬编码在代码里而是放在配置中心方便运营人员反复调优提示词而不需要重新发布服务。第二层是响应解析与清洗。AI 返回的内容不可能每次都规范。有时候多了一个前导语有时候 JSON 格式不合法有时候答案顺序颠倒了。适配层要做的是把模型返回的原始内容解析成业务系统能用的结构化数据。如果解析失败还要有重试机制调整温度参数让模型重新生成或者通过正则提取关键内容。以出题功能为例要求模型返回 JSON但开源模型经常返回 markdown 代码块包裹或者字段名变成驼峰解析器如果没做好容错学员端看到的就是一大段原始文字而不是干净的题目。这块没有捷径只能把所有提取和清洗的规则写成可配置、可测试的单元。我在实际项目中就将响应解析做成独立服务输入原始文本和 schema输出结构化结果为各种模型和场景提供统一兜底。3.3 上下文与会话管理把“多轮理解”变成可用服务培训系统的 AI 助手大多是对话式的学员会连续追问这就涉及上下文管理。在网关层我负责任务分发在适配层我负责的是“会话语义”的管理因为会话状态和培训业务绑定得更紧。我在适配层里设计了一个会话服务核心逻辑是会话创建学员发起新对话时在适配层创建会话 ID关联学员 ID 和业务场景。历史管理多轮对话中适配层会自动维护消息列表为了避免 Token 膨胀当历史超过一定长度时自动做滑动窗口裁剪或摘要总结。知识注入培训系统里常有“本题的正确解法”等特定知识适配层会在拼装请求时把这些知识放入上下文而不是依赖模型自己“记住”答案。比如学员问“为什么我这里默认网关一直被清空”如果只是把这个问题丢给通用模型可能得到一个通泛的网络知识回答。适配层会先去检索培训系统的知识库找到关于“网关地址配置”的章节和常见排障步骤拼进上下文后再请求模型。这样模型生成的回答不会瞎编也贴合系统本身的操作路径。3.4 存量系统的四种接入模式存量系统的改造难点在于“不能一刀切”不同模块适合不同的接入深度。我在实际项目里总结了四种模式适配层按模式分别实现模式一代理模式。适用于基本不做业务改动的模块。适配层包装网关接口业务侧只把原来的内部调用替换成适配层接口。适合聊天机器人等独立模块改动量最小。模式二增强模式。在原有业务逻辑中插入 AI 调用对流程做一个增强。比如原来的课程搜索是关键词匹配增强后先做意图识别再结合关键词检索。适配层在这时封装了“意图识别 搜索排序”两段式调用。模式三嵌入模式。AI 逻辑成为业务流程的必要环节。比如智能出题没有 AI 生成之前题目完全不存在适配层就直接嵌入了出题模板的组装和生成结果的校验。模式四扩展模式。针对新业务场景适配层直接定义为新模块的标准接入方式调用方只需按新的接口规范开发。培训系统中最常见的组合是聊天机器人走代理模式课程推荐走增强模式智能出题走嵌入模式新的 AI 作业批改走扩展模式。每种模式在适配层的代码结构上有明显差异但对外表现的 API 风格保持统一这也是为什么后续业务方不需要关心底层逻辑变化。4. 实操落地一个培训系统的 AI 网关从 0 到 1 的接入过程方案理论说得再多不如一个实际落地过程来得有说服力。这里我以一个“中等规模的内部培训平台”为例系统约有 2 万活跃学员、500 门课程、题库约 20 万道原有的技术栈是 Java MySQL 内部服务化架构。我们要给这个系统加上典型三类 AI 能力智能出题、课程摘要、对话答疑。4.1 分阶段推进先做最容易见效、最不核心的模块我的路线是“先旁路、再嵌入、最后全量”。第一阶段先做课程摘要因为它不干扰核心业务流程即使效果差一点最多是页面多一块内容不好看不会影响学员学习路径。第一个星期我就在系统首页的课程详情页里嵌了摘要展示位学员打开课程页前端异步请求适配层课程摘要接口适配层向网关请求模型生成摘要。当时刚好遇到一个大模型厂商服务升级导致响应变慢但因为做的是旁路异步方式页面主体没有受到任何影响这个优势让团队后续推广时容易说服业务。第二阶段做智能出题这个要嵌入到老师的出题流程里。老师选择课程和知识点后点击“AI 生成题目”系统就请求网关。为了提高合格率我在适配层的出题模块里设置了“AI 出题 人工验证”的双保险AI 生成的题目先进入草稿箱老师确认后才入库。这个阶段重点是打磨提示词和响应解析我大约迭代了五六版提示词模板才让题目质量达到“老师愿意用”的水平。第三阶段做对话答疑这个是用户感知最强也最容易出问题的模块。这里我的核心工作是设计会话管理和多轮上下文策略。初期模型幻觉比较严重后来在适配层的上下文里引入了“RAG 知识检索 系统操作手册约束”学员问的问题如果命中内部知识库就以知识库内容为准生成回答模型只负责组织语言效果立刻提升。4.2 关键技术参数设计参考聊几个具体的参数都是在这个项目中沉淀下来的供大家参考上下文窗口与 Token 估算。我在适配层对每一次请求会先估算 Token 数。估算公式我习惯用预估 Token ≈ 中文字符数 × 0.6 英文单词数 × 1.3 结构化标记开销。不是特别精确但用来做路由和预算判断足够了。出题请求如果不带历史的一般在 1200~1800 tokens对话答疑如果有多轮历史很容易到 4000~8000 tokens。超时与重试策略。大模型接口的响应时间波动很大。我在网关上给不同能力配置不同的超时阈值出题和摘要这种一次性生成要求 30 秒内返回对话答疑因为交互性强阈值设在 15 秒超时就返回一个让学员换种问法的降级提示。重试逻辑我建议只在“连接错误”和“限流错误”时重试业务侧不要一看到超时就重试否则高峰期会把供应商的限流打得更严重。并发线程池调优。网关层我用的是 Java 的 CompletableFuture 做异步编排。线程池核心大小设为CPU 核数 × 2最大大小设为CPU 核数 × 4队列容量设置为 500。业务高峰 QPS 超过 200 时优先触发限流而不是无限排队否则下游模型接口容易连环超时。4.3 网关与适配层的代码骨架参考这里给一个最小可跑通的网关侧代码骨架基于 Spring Boot 的 RestTemplate 实现假设你已经熟悉基本的 Java Web 开发// 统一请求体 public class CapabilityRequest { private String capability; // 能力名 private String userId; private String module; private MapString, Object payload; } // 统一响应体 public class CapabilityResponse { private boolean success; private String code; private Object data; private long latencyMs; } // 网关路由服务 Service public class GatewayRoutingService { Autowired private ModelProviderRegistry providerRegistry; public CapabilityResponse route(CapabilityRequest request) { String model routeStrategy.select(request); ModelProvider provider providerRegistry.getProvider(model); return provider.invoke(request); } }适配层在业务系统中单独建一个服务核心是两个组件CapabilityTranslator翻译请求和ResponseParser解析响应。Component public class ExerciseTranslator implements CapabilityTranslator { Override public CapabilityRequest translate(BizContext context) { return CapabilityRequest.builder() .capability(generate_exercise) .userId(context.getUserId()) .module(exam) .payload(buildPayload(context)) .build(); } Override public BizResult parse(CapabilityResponse response) { // 清洗、去重、格式转换 ListQuestion questions parseToQuestions(response.getData()); return new BizResult(questions); } }这套骨架在项目初期够用随着能力增多后可再引入规则引擎、配置中心、动态模型路由等高级组件但核心逻辑不会变就是“统一入口、能力翻译、响应清洗”三件事。4.4 模型配置与调优在“一下用最好的”和“成本可控”之间做选择这部分我认为有必要单独拿出来讲因为在培训系统场景中模型选型不能只看效果排名还要考虑数据合规、部署方式和中文教育内容的适配度。我的建议是主模型 备用模型 低成本模型三档配置。主模型选效果最好的商用大模型按当时的评测实际情况选备用模型选另一个厂商的旗舰产品避免单点风险低成本模型用开源或轻量级模型处理简单分类、翻译、意图识别这些任务。模型参数上我在出题场景里测温temperature 0.7太低了题目太死板太高了会出现事实性错误。在摘要场景里设temperature 0.3保证忠于原文。top_p一般保持默认或微调到0.85~0.95。如果是代码生成或 JSON 结构严格要求时还会启用response_format json_object。另外每个模型供应商的“思维链/推理强度”参数差别很大适配层要能把这类差异参数转换成统一字段例如reasoning_effort: low/medium/high。5. 常见问题与排查实录网关和适配层上线后的麻烦事方案上线不等于万事大吉。这里记录几个我们实际操作中遇到的典型问题都是“网上文档不常说但基本每个团队都会碰到”的那种。5.1 模型供应商需要单独配置代理网关报错 504 或连接超时这个问题在我们接入某家国产大模型厂商时遇到一开始以为是超时时间设置有问题查了半天发现是他们的接口域名在本地网络环境无法直接访问需要经过一个独立的代理网关。排查步骤是先curl测试供应商 API 域名连通性再用traceroute和ping看网络路径确认是网络问题后在网关中添加独立的代理网关配置类似其他需要走公网代理的第三方接口并把该供应商的请求绕开默认网关超时专线立刻解决。经验总结接入新模型供应商之前先做一个网络连通性预检省得误判为代码问题。5.2 返回结果里带着大模型自己的思考过程或前导语气词不少模型喜欢在正式回答前加一句“好的我来帮你...”在聊天场景还能忍但如果是结构化出题那返回的 JSON 直接在前面多了一段无效字符串解析直接失败。解法适配层的响应解析器不能只做JSON.parse要先做内容清洗。我的清洗规则有三级先去 markdown 代码块包裹再检测前导语气词并截断到第一个合法 JSON 字符最后用容错 JSON 解析器如 Jackson 的允许注释模式、或写一个简单的括号匹配修复方法尝试解析。如果还是解析失败就重试一次并降低温度参数。5.3 默认网关一直被清空学员端配置的网关地址反复丢失这个场景挺有意思它不是我们服务端的 Bug而是学员在使用培训系统内置的网络实训功能时本地的路由器网关地址一直被某个安全软件重置导致的。当时学员的反馈是“我怎么设第二天又变回去了”。排查时先分清是业务系统的问题还是本地环境的问题。我们通过日志发现学员的实训功能是在本地虚拟机中运行的调用了系统网络配置而这台机器装了安全软件会在后台定期重置网络参数。解决方法是引导学员在安全软件中配置放行同时在培训文档中补充了“网关地址设置后立刻重启生效”的说明。这个问题的通用经验是AI 网关故障排查时不要只盯着云端用户本地的网络链路和各家设备差异也要纳入故障范围。5.4 网关开机时一直卡在“网关启动中”我们自己的网关服务也遇到过一次启动时一直卡在网关启动中。排查发现是 Redis 连接池配置了maxTotal50但连接数没有设最大等待时间某个异常请求挂住了连接池初始化线程一直在等连接释放。重新调整了配置连接池加maxWaitMillis3000建立连接前先做ping探活并且增加启动自检逻辑——启动阶段如果 Redis 连接不可用就打印详细错误并直接失败退出而不是“卡死不报错”。现在凡是需要健康检查的组件我都会在启动时加一个自检开关宁可快速失败不要隐性卡死。5.5 模型长期跑下来效果“变差”其实是路由策略被运营改乱了有一次学员反馈智能答疑质量明显下降查看了所有监控指标模型响应都正常Token 消耗也没有异常后来对比了网关的路由配置发现运营同事在前一天把答疑的默认模型手动切成了一个便宜的新模型而这个新模型对中文教育培训领域理解一般导致效果下降。这不是技术 Bug但比 Bug 更难防。解决办法是在网关管理后台里增加“路由变更审计日志”任何配置变更都会记录操作人和变更原因。凡是涉及模型路由和降级策略的变更强制走审批流。经验是AI 网关的技术坑其实有限管理和配置上的坑往往更隐蔽。5.6 存量系统用户 ID 与网关用户 ID 不一致导致费用无法分摊培训系统里有两种用户体系正式学员和试听学员适配层最初只传了业务系统的 user_id网关无法区分用户身份费用统计对不上账。后来把租户概念引入网关tenant_id表示客户或企业、user_type表示用户类型才能按租户出账单。这个教训是设计网关数据结构时必须提前考虑多租户和用户分层的需求不然后期补非常折腾。5.7 问题排查速查表现象可能原因排查动作请求超时 504代理网关配置错误 / 模型响应过慢分别检查网络连通性、模型实际耗时、网关超时配置返回结果 JSON 解析失败模型返回格式不规范 / 前导文本三级清洗容错解析重试网关启动卡死Redis/数据库连接池耗尽检查连接池配置、加启动自检、快速失败学员本地网关地址被清空安全软件重置 / IP 冲突确认本地链路、文档引导、配置放行效果突然变差模型路由被改动 / 提示词模板被覆盖查看变更审计日志、回滚配置费用突增上下文物代价增长 / 降级策略失效核对 Token 消耗明细、检查会话历史裁剪AI 返回内容与培训内容不符知识库未注入或内容过旧检查 RAG 检索来源、更新知识库切片6. 方案的可演进方向与我的个人体会统一 AI 能力网关和适配层的这套设计最后沉淀下来不只是几个接口而是一种接入思维不管底层模型技术怎么迭代、供应商怎么洗牌业务系统始终只需要面对一组稳定、抽象的能力接口。培训系统里后续要加语音评测、AI 陪练、虚拟老师这类新能力时只需要在网关上注册新能力、在适配层新增一个翻译器主体架构完全不需要动。根据我个人的落地经验再分享三个实操层面的建议一是在启动前画一张“能力地图”。把业务系统里所有可能用到 AI 的场景列出来按价值/成本/风险区分优先级不要一次性全都接。每一次接入尽量在适配层内闭环不要急着碰核心链路。二是从第一版代码开始就建立监控看板。网关请求量、成功率、Token 消耗趋势、模型响应时长、成本预估这些指标全部可视化。没有监控的 AI 网关就像没有仪表盘的飞机飞起来容易出事了根本无处下手。三是不要让“接 AI”变成一次性项目。大模型技术的发展速度远超传统软件每季度做一次模型效果对比评估把新的模型引入路由表对比测试后再决定切换。这本来就是网关方案最大的红利不用就浪费了。这套方案虽然以存量培训系统为背景但我相信对任何面临 AI 升级的存量业务系统都有参考价值。核心就一句话把模型当成可替换的组件把业务能力当成稳定的接口适配层是它们之间唯一需要认真打磨的地带。