[企业级AI Coding + 企业级Agent] Flask AI 网关：向下三种AI供给，向上七种AI能力

在应用平台中对接 AI 时，陆续接入了百炼 API、EPAI 智能体、LangChain 框架。能力越来越多，散装调用的维护成本急剧攀升。于是逐步抽象，自己设计了一个 Flask AI 网关——向下屏蔽三种供给差异，向上暴露统一能力接口。

网关的定位

直接在前端调百炼 API，两天就能跑通。但当团队同时对接模型 API、智能体平台、LangChain 编排链路时，散装调用的代价迅速暴露：每个页面各自拼 prompt、各自解析 SSE、各自做错误重试、Token 用量散落在十几个控制台里。网关做一层，所有消费者共享同一套鉴权、限流、路由、适配、观测。Flask 够薄，让注意力放在适配器设计上，而不是框架配置上。

底层：三种能力供给的封装

模型 API调用。核心是协议归一化：不管百炼 DashScope、OpenAI 原生还是火山兼容模式，网关统一收敛为 /v1/chat/completions格式。适配器负责参数映射——model 名对应实际版本号、response_format差异补齐、厂商特有参数的默认值注入。流式中继不是简单透传字节流，而是做事件标准化重放：统一 token 级切分、补齐 [DONE]、处理断连重续。再加一条 Fallback 链——qwen-turbo挂了自动切 qwen-plus，前端调的逻辑名不变，切换发生在适配层。

智能体平台。EPAI 或扣子本质是"预编排"——工作流、知识库、插件已配好。网关面对的挑战是平台接口形态各异：同步返回、异步回调、WebSocket 推送、会话管理。适配层统一归约为"请求-响应"或"请求-流式"两种范式。前端调智能体和调模型 API 代码完全相同，都是 POST /api/v1/chat。更进一步，网关可做"复合后端"——平台智能体当推理引擎，独立向量数据库的检索结果拼进 context，前端不知道知识从哪来的，只知道结果更准。

框架编排。LangChain/AgentScope 解决多步推理、工具调用、条件分支。与 API 直调的本质区别在于：API 是一次请求一次响应，框架是多次调用加循环。适配时最大的挑战是让 Chain 输出适配网关的流式契约——消费 astream_events的内部事件（on_tool_start、on_retriever_end），映射为统一 token 级事件。中间步骤作为扩展字段旁路给调试面板，不阻塞主输出。AgentScope 的多 Agent 协商需要压缩为连续输出流，或通过 WebSocket 按角色分块展示。同时 Chain 是有状态对象，网关需维护对象池，显式管理 RunnableConfig 传递和 Trace 上下文传播。

向上：暴露的多种 AI 能力

网关往下屏蔽了三种供给差异，往上面向业务场景暴露统一的能力接口。前端不调模型，调的是"能力"。

问答（Chat / RAG-QA）。最基础的能力。请求带 capability: "qa"，网关按配置路由——简单闲聊直调模型 API，知识库问答走 LangChain RAG 链或智能体平台的知识库模式。前端只传 question，网关负责拼 system prompt、挂载知识库、控制引用格式。

问数（Text-to-SQL / 数据分析）。用户用自然语言问"上个月销售额 Top10 的商品"，网关路由到 Text-to-SQL 链路：LLM 生成 SQL → 执行引擎查询 → 结果回注 → LLM 总结为自然语言。这是典型的 LangChain 多步链，封装为一个 capability: "data_query"能力。

生成文档（Document Generation）。输入结构化数据或大纲，输出完整文档。根据场景走不同底层——正式报告走 LangChain 的多轮生成+审核链，简单文案直调模型 API，带模板约束的走智能体平台工作流。

生成图表（Chart / Image Generation）。自然语言描述 → ECharts 配置 JSON 或图片 URL。前者是 LangChain 链：LLM 生成图表配置 → 前端渲染；后者直接路由到百炼或通义万相的图片生成 API。前端用同一个 capability: "chart"入口。

内容审核与分类。文本安全审核、情感分析、意图分类、标签打标。轻量场景直调模型 API（一次分类 prompt），批量场景走 LangChain 链（分片→并行分类→合并）。

翻译。简单翻译直调模型 API，专业文档翻译走框架编排（术语表注入、分段翻译、质量检查、译文合并）。

代码生成。自然语言描述生成代码片段或 SQL，路由到代码专用模型 API。

能力注册表

CAPABILITIES = {
    "qa":              Route(api="qwen", agent="epai-kb", chain="rag-chain"),
    "data_query":      Route(chain="text-to-sql"),
    "doc_generate":    Route(chain="doc-pipeline", agent="epai-doc"),
    "chart_generate":  Route(chain="chart-config"),
    "image_generate":  Route(api="wanx-v1"),
    "content_audit":   Route(api="qwen", chain="batch-classify"),
    "translate":       Route(api="qwen-mt", chain="doc-translate"),
    "code_generate":   Route(api="deepseek-coder"),
}

前端调 /api/v1/capability，传 capability参数，网关查表路由，底层是 API、框架还是平台对前端完全透明。新增能力只需在注册表加一行、配一个适配器，不碰前端代码。

不做哪些

不替业务方决策——路由选哪个后端是网关的职责，"要不要用 RAG"是业务方的职责。不缓存模型输出——一致性问题和排查成本远高于省下的 Token。不把自己建成新的智能体平台——网关只做路由和适配，工作流编排挂在下面当能力单元，不寄生在网关里。

AI Coding 在网关建设中的作用

网关从零到一的过程中，AI Coding 扮演的不是"替代决策"的角色，而是"决策之后的加速器"。

适配器代码生成。每个后端 SDK 的对接逻辑是纯体力活——读文档、写请求构建、做错误映射。把目标 SDK 的文档喂给 AI，一次生成适配器骨架，人工只需校验参数映射是否正确。一个适配器从半天压缩到一小时。

流式事件标准化。各厂商 SSE 格式差异是排查重灾区。把两家厂商的 SSE 原始输出各贴几段给 AI，让它写事件标准化中间件——统一 token 切分、补齐结束标记、异常断连处理。比手工调试各厂商边界行为快三倍以上。

能力注册表与路由配置。描述场景和路由规则，AI 生成注册表结构和路由中间件代码。新增能力时，只需一句话描述"问数能力走 Text-to-SQL 链，优先用 deepseek 模型"，AI 补齐配置项和 fallback 逻辑。

测试用例与 Mock。AI 生成各后端的 Mock 响应——模拟百炼正常返回、超时、限流错误；模拟 EPAI 异步回调的各种状态；模拟 LangChain 链的 astream_events事件序列。全链路测试的用例覆盖由 AI 批量生成，人工只挑关键路径验证。

文档与 Onboarding。网关写好后，AI 自动生成 OpenAPI spec、各能力的调用示例、适配器扩展指南。新同事接入一个新能力，看 AI 生成的文档就能上手，不用翻源码。

但核心逻辑必须人定。路由策略选哪个模型优先、Fallback 链的降级顺序、哪些能力走框架哪些走平台——这些决策依赖业务判断，AI 替代不了。AI Coding 的作用是"想清楚了就让它写"，而不是"让它帮你想"。网关建设中的决策占比 30%、编码占比 70%，AI Coding 把 70% 压缩到原来 30% 的时间，但它碰不了那 30% 的决策。