MODEL_ROUTING_ARCHITECTURE_CURRENT.md - 现行模型路由（真实代码）

版本: v1.1 | 状态: 真实盘点 | 更新时间: 2026-01-10 说明: 本文档基于当前代码真实路由输出，用于与旧版 MODEL_ROUTING_ARCHITECTURE.md 对比；以代码为准。

1. 架构概览

当前项目存在两套运行时路由链：

  • Backend (src)：服务端智能体与 CLI 侧调用，使用 src/llm/*。
  • Web (apps/web)：Next.js API/页面侧调用，使用 apps/web/lib/llm/*。
  • Shared Core：共享路由内核 src/llm/shared/model-router-core.ts（Provider/Family/Transform/EnvKey）。

图片生成与部分文本服务并不完全依赖 SmartRouter，而是在各自服务/API 中显式实现 fallback。

User Request
  -> Routing Layer (Backend: src/llm/* | Web: apps/web/lib/llm/*)
  -> Provider Registry
  -> Provider API

2. 路由入口与职责

2.1 Backend LLM 路由

  • SmartRouter: src/llm/smart-router.ts
  • Model Router: src/llm/model-router.ts
  • Shared Core: src/llm/shared/model-router-core.ts
  • Provider Registry: src/llm/registry.ts

2.2 Web LLM 路由

  • SmartRouter: apps/web/lib/llm/smart-router.ts
  • Model Router: apps/web/lib/llm/model-router.ts
  • Shared Core: src/llm/shared/model-router-core.ts

2.3 Web 任务路由

  • Task Router: apps/web/lib/llm/task-model-router.ts
  • SmartChat API: apps/web/app/api/ai/smart-chat/route.ts

2.4 图片生成

  • 统一服务: apps/web/lib/services/image-generation.ts
  • PPT 入口: apps/web/app/api/services/generate-ppt/route.ts
  • 前端分辨率来源: apps/web/components/professional-workstation/workstations/deck-studio/DeckStudioV3.tsx

2.5 文本服务显式 fallback

  • apps/web/app/api/services/slide-ai-assist/route.ts
  • apps/web/app/api/services/ai-text-enhance/route.ts
  • apps/web/app/api/services/ai-polish/route.ts
  • apps/web/app/api/services/sheet-process/route.ts

3. Backend 路由（src/llm）

3.1 Fallback Chain（按模型系列）

说明: fallbackChain 会被 getConfiguredFallbackChain 按环境变量 + 支持集过滤（Backend 支持集见 src/llm/model-router.ts）。

Model Family Fallback Chain (Declared) Native Provider 来源
gpt poe → openrouter → openai openai src/llm/model-router.ts
claude poe → openrouter → anthropic anthropic 同上
gemini google → poe → openrouter google 同上
deepseek poe → openrouter → deepseek deepseek 同上
glm poe → openrouter poe 同上
kimi poe → openrouter poe 同上
qwen poe → openrouter poe 同上
llama poe → openrouter poe 同上
mistral poe → openrouter poe 同上
other poe → openrouter poe 同上

3.2 Provider 可用性门禁

  • getConfiguredFallbackChain 仅保留已配置 API Key 的 provider。
  • Backend 额外过滤非支持 provider（poe/openrouter/google/zenmux/openai）。
  • 环境变量键来自 getProviderEnvKey。

3.3 Model ID Transform 规则（摘要）

  • POE_MODEL_MAP 与 MODEL_ID_TRANSFORMS 由 src/llm/shared/model-router-core.ts 统一维护。
  • GPT: Poe 映射 POE_MODEL_MAP；OpenRouter 使用 openai/<model>。
  • Claude: Poe 映射；OpenRouter 使用 anthropic/<model>；Anthropic 有标准化映射。
  • Gemini: Google 使用官方映射；OpenRouter 使用 google/<model>；Poe 不做显式映射（透传 modelId）。
  • DeepSeek: Poe 映射；OpenRouter 使用 deepseek/<model>；DeepSeek 原生映射。

4. Web 路由（apps/web/lib/llm）

4.1 Fallback Chain（按模型系列）

说明: getConfiguredFallbackChain 会剔除未配置 Key 的 provider，并按支持集过滤（Web 支持集覆盖路由内所有 provider）。

Model Family Fallback Chain (Configured) Native Provider 来源
gpt poe → openrouter → zenmux → openai openai apps/web/lib/llm/model-router.ts
claude poe → openrouter → anthropic anthropic 同上
gemini google → poe → openrouter google 同上
deepseek poe → siliconflow → openrouter → deepseek deepseek 同上
glm siliconflow → poe → openrouter → zhipu zhipu 同上
kimi siliconflow → poe → openrouter → kimi kimi 同上
qwen siliconflow → poe → openrouter → alibaba alibaba 同上
llama poe → openrouter → siliconflow poe 同上
mistral poe → openrouter → siliconflow poe 同上
other poe → openrouter → siliconflow → zenmux poe 同上

4.2 Provider 注册

  • initializeProviders 会按环境变量注册 provider（openai/anthropic/google/deepseek/zhipu/kimi/openrouter/poe/siliconflow/zenmux）。
  • 路由优先级由 fallbackChain 决定，不由注册顺序决定。

4.3 Google API Key 轮询

  • GOOGLE_API_KEYS 目前为单条配置（代码中仅 1 条 entry）。
  • getGoogleApiKey 仍按轮询逻辑取 key。

5. Web 任务路由（apps/web/lib/llm/task-model-router.ts）

5.1 TaskType → Model Chain

说明: 真实可用链由 getAvailableModelsForTask 过滤（需对应 API Key）。

TaskType Default Fallback Chain
image-with-text gemini-3-pro-image-preview (google) nanobanana-pro → gpt-image-1.5 → seedream-4.5 → seedream-4.0 → nanobanana
image-no-text gemini-3-pro-image-preview (google) nanobanana-pro → gpt-image-1.5 → seedream-4.5 → seedream-4.0 → nanobanana → kling-2.6 → kling-o1 → wan-2.6
agent-orchestration gemini-3-pro (poe) grok-4.1-thinking → claude-opus-4.5 → gpt-5.2-pro → deepseek-r1
agent-simple gemini-3-flash (poe) gpt-5.2-instant → gemini-3-pro → deepseek-v3
video-generation veo-3.1 (google) sora-2-pro → seedance-1.5-pro → kling-omni → kling-2.6-pro
video-cn-lipsync seedance-1.5-pro veo-3.1 → sora-2-pro → kling-omni → kling-2.6-pro
video-image-driven veo-3.1 kling-omni → sora-2-pro → seedance-1.5-pro
text-processing gemini-3-flash (google) claude-haiku-4.5 → gemini-2.0-flash → Gemini-3-Flash (poe)
text-complex gemini-3-flash (google) gemini-3-pro → grok-4.1-thinking → claude-opus-4.5 → deepseek-r1
audio-processing gemini-2.5-pro-tts gemini-2.5-flash-tts → elevenlabs-v3
music-generation elevenlabs-music hailuo-music-v1.5

5.2 任务路由选择优先级（SmartChat）

  • 直接指定 model
  • 指定 taskType
  • baseTaskType + constraints 动态选择 taskType
  • 默认 text-processing

SmartChat 最终仍通过 SmartRouter.chatCompletion 执行模型调用。

6. 图片生成路由（apps/web/lib/services/image-generation.ts）

6.1 分辨率规则

  • 1k 会被强制升级到 2k。
  • quality 与 complexity 共同决定分辨率（最低 2K）。
  • PPT 场景由前端 DeckStudioV3 传递 imageQuality（2K/4K）。

6.2 场景 → 模型链

PPT 场景 (scenario='ppt')

  • Google: gemini-3-pro-image-preview only
  • Poe: nano-banana-pro only

纯图片 (scenario='pure-image')

  • Google: gemini-3-pro-image-preview → gemini-3-flash-image-preview → gemini-2.5-flash-exp-image-generation
  • Poe: nano-banana-pro → GPT-Image-1.5 → nano-banana → seedream-4.5 → seedream-4.0 → FLUX-2-Pro → FLUX-2 → recraft-v3 → ideogram-v3 → Kling-O1 → kling-2.6 → wan-2.6 → DALL-E-3
  • OpenAI/OpenRouter: gpt-image-1.5 → dall-e-3

文字渲染约束

  • 仅 provider === 'poe' 或 scenario === 'ppt' 允许生成文字。

6.3 4K 校验与回退行为

  • Google 4K 请求: 若未达标，PPT 场景返回失败以触发 Poe 回退。
  • 非 PPT 场景: Google 允许返回“最佳可用结果”。
  • Poe: 未强制 4K 校验，仍以请求分辨率为准（最低 2K）。

7. PPT 图片生成链路（apps/web/app/api/services/generate-ppt/route.ts）

  • Primary: Google (若 GOOGLE_API_KEY 存在)
  • Fallback: Poe (若 POE_API_KEY 存在)
  • 如果 Google 不可用但 Poe 可用，则 Poe 为主，Google 为备用
  • 全部走 generateImage(..., scenario='ppt')

8. 文本类服务显式 fallback（Web API）

API 主链路 Fallback
slide-ai-assist Google gemini-3-flash-preview Poe Gemini-3-Flash
ai-text-enhance Google gemini-3-flash-preview OpenAI gpt-5.2-instant → Poe gemini-3-flash-preview
ai-polish Google gemini-3-flash-preview OpenAI gpt-5.2-instant → Poe gemini-3-flash-preview
sheet-process Google gemini-3-flash-preview Poe Gemini-3-Flash
agents/analyze Google gemini-* 直连 非 Gemini 走 LLMService.chatCompletion（无 fallback）

9. Provider 环境变量键

标准 Provider

  • openai → OPENAI_API_KEY
  • anthropic → ANTHROPIC_API_KEY
  • google → GOOGLE_API_KEY
  • deepseek → DEEPSEEK_API_KEY
  • openrouter → OPENROUTER_API_KEY
  • poe → POE_API_KEY
  • siliconflow → SILICONFLOW_API_KEY
  • zenmux → ZENMUX_API_KEY
  • zhipu → ZHIPU_API_KEY
  • kimi → MOONSHOT_API_KEY
  • alibaba → ALIBABA_API_KEY (通过 qwen 路由)

特殊 Provider

  • elevenlabs → ELEVENLABS_API_KEY
  • hailuo → HAILUO_API_KEY
  • kling → KLING_API_KEY
  • seedance → SEEDANCE_API_KEY
  • seedream → SEEDREAM_API_KEY
  • wan → WAN_API_KEY

10. 与旧文档的关键差异（面向对比）

  1. 双栈路由：Backend 与 Web 各自维护 ModelRouter，但已共享 model-router-core 统一家族识别/映射规则。
  2. Zenmux 参与范围：Backend 未进入 fallbackChain；Web 仅在 gpt/other 中出现。
  3. Google Key 轮询：Web 代码中 GOOGLE_API_KEYS 只有 1 条 entry。
  4. PPT 图片链路收敛：PPT 场景仅 gemini-3-pro-image-preview 与 nano-banana-pro，不再走多模型链。
  5. 服务级 fallback：多个 Web API 在路由层之外显式 try/catch fallback（旧文档未覆盖）。

11. 证据索引（代码来源）

  • src/llm/model-router.ts
  • src/llm/shared/model-router-core.ts
  • src/llm/smart-router.ts
  • src/config/models.ts
  • apps/web/lib/llm/model-router.ts
  • apps/web/lib/llm/smart-router.ts
  • apps/web/lib/llm/task-model-router.ts
  • apps/web/app/api/ai/smart-chat/route.ts
  • apps/web/lib/ai/llm-client.ts
  • apps/web/lib/llm/service.ts
  • apps/web/app/api/services/slide-ai-assist/route.ts
  • apps/web/app/api/services/ai-text-enhance/route.ts
  • apps/web/app/api/services/ai-polish/route.ts
  • apps/web/app/api/services/sheet-process/route.ts
  • apps/web/lib/services/image-generation.ts
  • apps/web/app/api/services/generate-ppt/route.ts
  • apps/web/components/professional-workstation/workstations/deck-studio/DeckStudioV3.tsx

猪哥云（四川）网络科技有限公司 | 合规网 www.hegui.com 猪哥云-数据产品部-Maurice | maurice_wen@proton.me 2025 猪哥云-灵阙企业级智能体平台