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

原创灵阙教研团队

S 精选进阶架构设计 | 约 6 分钟阅读更新于 2026-01-10

AI 导读

MODEL_ROUTING_ARCHITECTURE_CURRENT.md - 现行模型路由（真实代码）版本: v1.1 | 状态: 真实盘点 | 更新时间: 2026-01-10 说明: 本文档基于当前代码真实路由输出，用于与旧版 MODEL_ROUTING_ARCHITECTURE.md 对比；以代码为准。 1. 架构概览当前项目存在两套运行时路由链： Backend...

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. 与旧文档的关键差异（面向对比）

双栈路由：Backend 与 Web 各自维护 ModelRouter，但已共享 model-router-core 统一家族识别/映射规则。
Zenmux 参与范围：Backend 未进入 fallbackChain；Web 仅在 gpt/other 中出现。
Google Key 轮询：Web 代码中 GOOGLE_API_KEYS 只有 1 条 entry。
PPT 图片链路收敛：PPT 场景仅 gemini-3-pro-image-preview 与 nano-banana-pro，不再走多模型链。
服务级 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 | [email protected] 2025 猪哥云-灵阙企业级智能体平台

深度加工（NotebookLM 生成）

基于本文内容生成的 PPT 大纲、博客摘要、短视频脚本与 Deep Dive 播客，用于多场景复用

PPT 大纲（5-8 张幻灯片）点击展开

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

这是一份基于您上传的文章《现行模型路由架构》生成的 PPT 大纲，共包含 6 张幻灯片。

现行模型路由架构概览

双栈路由体系：当前项目包含两套运行时路由链，分别为服务端与 CLI 侧调用的 Backend 路由，以及 Next.js 页面侧调用的 Web 路由 [1]。
共享路由内核：双栈架构共同依赖共享核心层（Shared Core），统一处理提供商（Provider）、家族模型识别与环境变量等规则 [1, 2]。
独立容灾设计：图片生成与部分特定文本服务不完全依赖核心路由（SmartRouter），而是各自实现显式的服务级降级（Fallback）机制 [1]。
统一流转路径：用户请求统一经过路由层分发，经由 Provider 注册表最终调度至相应的 API 执行 [1]。

Backend 与 Web 路由机制

降级链（Fallback Chain）设计：根据 GPT、Claude、Gemini 等模型系列，设定了多级供应商（如 Poe、OpenRouter、原生平台）的自动降级顺序 [1, 3]。
可用性动态门禁：系统会根据环境变量进行过滤，仅保留配置了 API Key 的 Provider 参与路由流转 [1, 3]。
平台支持集差异：Web 端引入了更丰富的供应商组合（如 Siliconflow、Zenmux 等），而 Backend 则具有专属的过滤门禁，体系相对精简 [1, 3]。
统一模型 ID 转换：底层通过 model-router-core 统一维护各大模型平台对第三方代理（如 Poe、OpenRouter）的模型 ID 映射规则 [1]。

Web 任务级模型路由 (Task Routing)

任务映射链条：根据具体任务场景（如图文生成、智能体编排、视频生成、文本处理等）分配默认与降级的模型链 [4]。
路由选择优先级：系统优先遵循直接指定模型，其次匹配指定的任务类型（TaskType），最后才执行动态推导或默认文本处理 [5]。
统一执行归口：不论经过何种任务路由逻辑，核心的 SmartChat 最终均通过 SmartRouter.chatCompletion 发起模型调用 [5]。

图片生成路由与分辨率规则

分辨率强制提升：系统具备分辨率规则校验，1K 规格的请求会被强制升级到 2K，由质量与复杂度参数共同决定 [5]。
生成场景严格划分：图片路由严格区分“PPT 场景”与“纯图片场景”，各自对应完全独立的生成模型链路 [5]。
文字渲染限制：系统仅在特定的提供商（Poe）或特定的 PPT 生成场景下，才允许触发包含文字的图片生成 [5, 6]。
4K 校验与回退机制：针对 Google 的 4K 请求如果在 PPT 场景下未达标会直接返回失败触发备用回退，而 Poe 则不会强制进行 4K 校验 [6]。

核心业务：PPT 链路与文本服务级降级

PPT 主备双链路：PPT 图片生成首选 Google 通道，若不可用则降级至 Poe，统一通过 generateImage 的 PPT 场景调度 [5, 6]。
PPT 模型精准收敛：不同于旧版的多模型链，PPT 场景下的图片生成已收敛，仅由 gemini-3-pro-image-preview 与 nano-banana-pro 承接 [2, 5]。
文本服务显式容灾：针对“幻灯片辅助”、“文本增强”、“数据表处理”等 Web API 接口，在路由层之外显式添加了 try/catch 实现多模型回退 [1, 2, 6]。

新旧架构关键差异总结

底层规则统一化：双栈架构虽然分离了 Backend 与 Web 的 Router，但在新版中成功实现了家族识别与映射规则的完全共享 [2]。
链路大幅优化：清理了冗杂的分支，最突出的是 PPT 场景图片生成链路的全面收敛 [2]。
容灾策略前置细化：引入了服务级 Fallback，打破了以往全部依赖全局智能路由进行错误兜底的限制 [2]。
提供商接入调整：明确了 Zenmux 在服务两端的参与范围，简化了 Google Key 的轮询设计（当前仅维持单条配置） [2, 3]。

博客摘要 + 核心看点点击展开

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

SEO 友好博客摘要

本文深度解析了 v1.1 版本现行智能体模型路由架构的真实代码实现。项目采用 Backend 与 Web 双栈运行时路由，并共享统一内核以处理模型家族识别与映射规则[1]。文章详细披露了主流大模型（如 GPT、Claude、Gemini 等）在多 Provider 下的降级处理链路（Fallback Chain）[1, 2]，并探讨了基于任务类型（如图文、视频生成）的动态路由选择逻辑[3, 4]。特别针对图片与 PPT 生成场景，明确了强制 2K 分辨率底线及特定模型收敛策略[4]。本文为开发者优化 AI 服务层架构与回退机制提供了高价值参考。

3 条核心看点