FastGPT 的模型网关本质上是一个模型调度中枢它把 OpenAI、Claude、通义千问、DeepSeek 等不同厂商的 LLM 封装成统一接口让工作流编排者无需关心底层协议差异。但真到落地时参数差异、路由策略、节点配合这些细节往往比文档里写的要复杂得多。模型配置不同厂商的参数方言FastGPT 的模型配置采用声明式结构核心字段看起来相似实际填起来各有门道。以最常见的四家厂商为例OpenAI 系列- name: gpt-4o type: openai config: apiKey: ${OPENAI_API_KEY} baseUrl: https://api.openai.com/v1 maxTokens: 4096 temperature: 0.7Claude 系列- name: claude-3-5-sonnet type: anthropic config: apiKey: ${ANTHROPIC_API_KEY} baseUrl: https://api.anthropic.com/v1 maxTokens: 8192 # Claude 的 temperature 范围 0-1但官方推荐 0.0-0.3 用于分析任务 temperature: 0.2 # 关键差异Claude 支持 top_p 但不支持 top_k且 system prompt 需单独字段 topP: 0.9通义千问- name: qwen-max type: openai # 兼容层实际走阿里云 DashScope config: apiKey: ${DASHSCOPE_API_KEY} baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1 # 阿里云特有需要显式指定 model 字段匹配 model: qwen-max # 支持 enable_search 参数开启联网搜索 extraBody: enable_search: trueDeepSeek- name: deepseek-chat type: openai config: apiKey: ${DEEPSEEK_API_KEY} baseUrl: https://api.deepseek.com/v1 # DeepSeek 的 reasoning_content 字段需要特殊处理 # 在 FastGPT 中需开启流式解析才能获取思维链 stream: true这些差异直接影响工作流设计。比如 Claude 的system字段在 FastGPT 的 LLM 节点中需要单独配置系统提示词输入框而 DeepSeek 的推理过程内容如果要在后续节点中使用必须勾选返回原始响应并在代码节点中解析reasoning_content。负载均衡round-robin 与 weight 的实战选择当同一模型配置了多个实例或渠道时FastGPT 支持两种负载策略{ strategy: round-robin, models: [ {name: gpt-4o-instance-1, weight: 60}, {name: gpt-4o-instance-2, weight: 40} ] }round-robin适合同质实例比如两个完全相同的 OpenAI 企业账号轮询主要解决单账号 RPM 限制问题。实际配置时要注意如果某个实例因网络抖动出现偶发超时FastGPT 默认不会自动剔除需要配合健康检查或手动降级。weight 加权更适合异构场景。典型用法是主力模型 降级模型组合{ strategy: weight, models: [ {name: gpt-4o, weight: 70}, {name: gpt-4o-mini, weight: 30} ] }这里的技巧是weight 不是简单的流量比例而是命中概率。高并发时可能出现连续命中同一实例的情况因此如果要做严格的成本配额控制建议在工作流层面用条件分支显式分流而非依赖网关层的 weight。工作流中的动态模型切换真正体现模型网关价值的是 Flow 编排中根据业务条件动态选择模型。FastGPT 提供了两种实现路径。路径一条件分支 多 LLM 节点这是最直观的方式。假设一个智能客服场景用户问题先经过意图识别简单问题走轻量模型复杂问题走旗舰模型。工作流结构用户输入节点 → 意图分类 LLM 节点用轻量模型→ 条件判断节点 → 分支 A简单问题/gpt-4o-mini或 分支 B复杂问题/gpt-4o→ 统一输出节点条件判断节点的配置关键// 假设意图分类返回的 JSON 包含 complexity 字段 const complexity input.complexity; if (complexity high || complexity technical) { output branch_b; } else { output branch_a; }这种方式的局限是分支一多画布会变得臃肿。更优雅的做法是变量化模型名称。路径二动态模型名称注入FastGPT 的 LLM 节点支持从上游节点接收模型名称变量。实现步骤在代码执行节点中根据业务逻辑计算目标模型def main(params): user_query params[query] # 自定义规则代码相关用 DeepSeek创意写作用 Claude其他用 GPT if any(kw in user_query for kw in [代码, bug, 报错]): model deepseek-chat elif any(kw in user_query for kw in [写, 创作, 文案]): model claude-3-5-sonnet else: model gpt-4o return {selected_model: model}在 LLM 节点的模型配置中选择动态绑定selected_model变量这种方式把路由逻辑内聚到代码节点画布更清爽且便于集中维护规则。但要注意动态切换时不同模型的参数模板必须兼容。比如 Claude 不支持response_format: {type: json_object}如果某条分支依赖这个特性就不能把 Claude 配置为候选。知识库检索与模型选择的配合逻辑RAG 场景下模型网关需要处理两层配合检索模型 vs 生成模型以及检索结果对生成模型选择的影响。检索阶段的模型选择FastGPT 知识库检索默认使用 embedding 模型这部分在网关中的配置独立于对话模型- name: text-embedding-3-large type: openai config: apiKey: ${OPENAI_API_KEY} baseUrl: https://api.openai.com/v1 # 用于检索的向量维度 dimensions: 3072国内环境常换用 BGE 或 M3E 系列此时要注意如果切换为自托管的 BGE 模型baseUrl 指向本地服务apiKey 可填任意占位符不同 embedding 模型的向量空间不兼容更换时必须重建知识库索引检索结果驱动生成模型选择一个常被忽略的实践是检索到的内容特征可以反向决定用哪个生成模型。比如检索结果以技术文档为主 → 调用 DeepSeek 或 GPT-4o 保证代码准确性检索结果以营销文案为主 → 调用 Claude 或通义千问优化中文表达检索结果置信度低最大相似度 0.6→ 切换到谨慎模式用更强的模型并降低 temperature实现方式是在检索节点后接代码节点分析retrieval_results的score分布和内容类型标签再输出recommended_model供下游 LLM 节点消费。插件系统扩展自定义网关能力当内置的模型配置无法满足需求时FastGPT 的插件系统允许你封装自定义网关逻辑。典型场景包括私有协议转换、特殊鉴权、请求预处理。插件开发的核心是继承标准接口并实现process方法// 简化示例一个添加自定义请求头的网关插件 interface GatewayPlugin { name: string; version: string; async beforeRequest(context: RequestContext): Promisevoid { // 从环境变量读取动态令牌 const token await this.refreshToken(); context.headers[X-Custom-Auth] token; context.headers[X-Request-Source] fastgpt-workflow; // 针对特定模型添加超时重试 if (context.model.includes(deepseek)) { context.timeout 120000; // DeepSeek 推理较慢 context.retry 2; } } }部署时将插件打包为 Docker 镜像在 FastGPT 管理后台的插件管理中注册随后即可在工作流的插件调用节点中使用。这种方式比直接修改核心代码更安全升级时也不会冲突。API 外接把网关能力开放出去FastGPT 模型网关不仅可以服务内部工作流还能通过标准 API 供外部系统调用。这在中台化架构中特别有用一次配置多处复用。获取 API 密钥与端点在 FastGPT 控制台应用发布中创建 API 访问会得到apiKey: 用于鉴权baseUrl: 通常是https://your-fastgpt-domain/api/v1外部系统调用示例Python 侧import requests class FastGPTGatewayClient: def __init__(self, base_url, api_key): self.base_url base_url self.headers { Authorization: fBearer {api_key}, Content-Type: application/json } def chat_with_model(self, model, messages, workflow_idNone): 直接调用指定模型或触发特定工作流 if workflow_id: # 调用工作流会完整执行 Flow 编排包括模型路由逻辑 endpoint f{self.base_url}/workflows/{workflow_id}/run payload {inputs: {question: messages[-1][content]}} else: # 直接调用模型绕过工作流走网关直连 endpoint f{self.base_url}/chat/completions payload { model: model, messages: messages, temperature: 0.7 } resp requests.post(endpoint, headersself.headers, jsonpayload) return resp.json() # 使用复用 FastGPT 内部配置好的模型网关 client FastGPTGatewayClient(https://fastgpt.company.com/api/v1, sk-xxx) # 方式1直接指定模型适合简单场景 result client.chat_with_model(deepseek-chat, [ {role: user, content: 解释下递归函数} ]) # 方式2触发工作流复用内部路由逻辑 result client.chat_with_model(None, [ {role: user, content: 写个Python爬虫} ], workflow_idwf-model-router-v2)外接时的注意事项模型名称一致性外部系统传入的model参数必须与 FastGPT 网关配置中的name完全匹配包括大小写流式响应处理如果工作流内部模型配置了stream: true外部调用时需添加stream: true参数否则可能超时错误码透传FastGPT 会将上游模型的错误如 429 限流、402 余额不足原样返回外部系统需做相应处理工作流切换模型的常见坑点最后总结几个实际踩过的坑参数继承陷阱工作流中复制 LLM 节点时temperature、maxTokens 等参数会一并复制但模型名称可能因动态配置而失效。建议把通用参数抽提到全局变量中节点内只覆写必须差异化的部分。上下文窗口溢出不同模型的上下文长度差异很大。如果工作流前面有知识库检索节点检索结果 历史对话 系统提示词很容易超过 gpt-4o-mini 的 128K 限制实际可用约 120K更不必说 Claude 的 200K 虽然纸面大但输入成本极高。建议在代码节点中加入前置校验预估 token 数并做截断或切换。流式与非流式混用如果工作流中某个节点需要解析 LLM 的完整 JSON 输出如结构化数据提取必须关闭该节点的流式开关但下游节点如果直接输出给用户又希望是流式体验。这种场景建议拆分为两个工作流通过 API 串行调用而非在一个 Flow 中强行混用。Fallback 盲区FastGPT 网关层的负载均衡不会自动处理模型级故障转移比如 DeepSeek 服务宕机自动切 GPT-4o。这个能力目前需要在工作流中用HTTP 请求节点 条件判断节点自行实现或借助外部 AI 网关如 OneAPI、kgateway作为 FastGPT 的上游。具体做法是将 FastGPT 的模型配置指向外部网关的统一入口由后者处理故障转移逻辑。