灵阙智能体平台 - 模型路由架构文档

版本: v1.3 | 更新日期: 2026-02-02

v1.3 更新

1. 增加 2025-07-01 前模型硬禁用：路由层强校验 + registry 失败即拒绝（Fail-Closed）。
2. 默认模型链与模型清单 全量迁移到 ≥2025-07：移除 gpt-4o* / o* / DALL·E 3 / Whisper v3 / Deepgram Nova-3 / text-embedding-3* / Cohere Rerank 3 / ElevenLabs v3 等旧型号。
3. Embedding/Rerank/Audio 更新：voyage-4-* + cohere-embed-v4.0；cohere-rerank-v4.0-*；STT 用 deepgram-flux / OpenAI gpt-audio-mini-2025-12-15；TTS 用 gemini-2.5-*-tts / OpenAI gpt-audio-mini-2025-12-15。
4. 更新 OpenRouter / Google AI Studio / Poe 的映射骨架到 GPT-5.2 / Claude 4.5 / Gemini 3 / Grok 4.1 / DeepSeek V3.2 / Qwen3-Coder。

v1.2 更新：基于 Arena.ai（LMArena）最新 Leaderboard（Text/Code/Vision/Search/Image/Video）重排默认模型链；新增 search / image_edit 场景；补齐 Grok 系列识别与 fallback；DeepSeek 升级 v3→v3.2；图片链更新到 gpt-image-1.5 / flux-2-max；视频链更新到 veo-3.1-audio / sora-2-pro。

v1.1 更新：删除5个免费 Google API 账号，仅保留 Ai-studio-jason（付费账号，2026-3-26到期），Gemini fallback 到 Poe API nano-banana-pro

v1.0 更新：引入质量档位（Premium/Balanced/Fast）、MoA多模型协作、视频/音频模型路由扩展

---

0. 硬性约束：2025-07-01 前模型禁用

0.1 规则

• 禁用阈值：MIN_MODEL_RELEASE_DATE = 2025-07-01
• 适用范围：LLM / Image / Video / Audio / Embedding / Reranker（所有“模型”一视同仁）
• 策略：Fail-Closed
  • registry 未登记 releasedAt → 视为不合规，不可路由
  • releasedAt < 2025-07-01 → 强制拒绝（不进入 fallback）

0.2 路由层校验（伪代码）

export const MIN_MODEL_RELEASE_DATE = '2025-07-01';

export type ModelMeta = {
  id: string;
  provider: string;
  releasedAt: string; // YYYY-MM-DD
  capabilities: Array<'text'|'vision'|'search'|'image'|'video'|'audio'|'embed'|'rerank'>;
};

export function assertModelAllowed(modelId: string, meta: ModelMeta) {
  if (!meta?.releasedAt) throw new Error(`MODEL_NOT_REGISTERED: ${modelId}`);
  if (meta.releasedAt < MIN_MODEL_RELEASE_DATE) throw new Error(`MODEL_BLOCKED_BY_POLICY: ${modelId}`);
}

0.3 旧模型输入的处理（兼容但不采用）

• 对外仍允许用户/上游传入旧 model 字段（避免上游崩溃）
• 进入路由层后：
  • 直接拒绝（推荐）或
  • 按别名迁移到新模型（可选，需显式开启 ALLOW_LEGACY_ALIAS_MIGRATION=true）

---

1. 架构概览

┌─────────────────────────────────────────────────────────────────────────┐
│                        用户请求 (User Request)                           │
└─────────────────────────────────────┬───────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    场景配置管理器 (ModelConfigManager)                    │
│                         lib/model-config.ts                             │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 场景类型: chat | code | vision | search | image | image_edit | video | video_i2v | embedding | audio_stt | audio_tts | reranker │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────┬───────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                      智能路由器 (SmartRouter)                            │
│                        lib/llm/smart-router.ts                          │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │ 1. 识别模型系列 (ModelFamily)                                      │
│  │ 2. 获取路由配置 (RouteConfig)                                      │
│  │ 3. 校验模型合规 (releasedAt >= 2025-07-01)                         │
│  │ 4. 获取已配置的 Fallback 链                                       │
│  │ 5. 按链路尝试 (Retry + Circuit Breaker)                            │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────┬───────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                    Provider 执行层 (Poe/OpenRouter/原生)                 │
│  lib/llm/providers/*.ts  +  lib/llm/registry.ts                         │
└─────────────────────────────────────────────────────────────────────────┘

---

2. 场景默认模型配置

2.1 质量档位（Quality Tiers）

档位	目标	代表模型（参考 Arena 排名 + 可用性）
Premium	最高质量/复杂任务	Gemini 3 Pro、Claude Opus 4.5 Thinking、Grok 4.1 Thinking、GPT-5.2 Pro
Balanced	默认体验	Gemini 3 Flash、GPT-5.2、Claude Sonnet 4.5、DeepSeek V3.2
Fast	低时延/低成本	Gemini 3 Flash (thinking-minimal)、GPT-5 mini、Claude Haiku 4.5、Grok 4.1 Fast

注：Leaderboard 的具体型号命名（带日期/-high/-thinking-32k 等）通过 alias 映射为“产品级短名”，以保持路由稳定。

2.2 场景默认模型配置（Balanced）

场景	场景类型	默认模型链	说明
对话交流	chat	gemini-3-flash → gpt-5.2 → claude-sonnet-4.5 → grok-4.1-fast	Text Arena Top 区间内择优（默认性价比）
联网搜索	search	gemini-3-pro-grounding → gpt-5.2 (web_search tool) → grok-4.1-fast (web_search tool)	Search/grounding 优先
代码生成	code	claude-opus-4.5-thinking → gpt-5.2-codex → deepseek-v3.2-thinking → qwen3-coder-480b-a35b	agentic coding 优先
视觉理解	vision	gemini-3-pro → gemini-3-flash → gpt-5.2	Vision Arena Top 区间内择优
图片生成	image	gpt-image-1.5 (fidelity=high) → nano-banana-pro → flux-2-max	文字/排版优先；第二/三梯队兜底
图片编辑	image_edit	chatgpt-image-latest (fidelity=high) → nano-banana-pro → gpt-image-1.5 (fidelity=high)	Image Edit Arena Top 区间内择优
视频生成	video	veo-3.1-audio → sora-2-pro → veo-3.1-fast-audio	仅保留 ≥2025-07 的 T2V
向量嵌入	embedding	voyage-4-large → cohere-embed-v4.0	召回/检索（≥2025-07）
语音转文本	audio_stt	deepgram-flux → gpt-audio-mini-2025-12-15	流式优先；LLM 音频兜底
文本转语音	audio_tts	gemini-2.5-pro-tts → gemini-2.5-flash-tts → gpt-audio-mini-2025-12-15	低延迟/自然度优先
文本重排	reranker	cohere-rerank-v4.0-pro → cohere-rerank-v4.0-fast	RAG优化（≥2025-07）
工作流	workflow	gemini-3-pro → claude-opus-4.5-thinking → gpt-5.2	推理、规划、工具调用

配置文件：lib/model-config.ts
强校验：lib/llm/model-guard.ts（新增，v1.3）

2.3 SOTA 快照（Arena.ai / LMArena）

数据来源：Arena.ai Leaderboards（以页面 Last Updated 为准）

• Text（Last Updated Jan 29, 2026）：gemini-3-pro、grok-4.1-thinking、gemini-3-flash、claude-opus-4-5-20251101-thinking-32k、claude-opus-4-5-20251101
• Code / WebDev（Last Updated Feb 1, 2026）：claude-opus-4-5-20251101-thinking-32k、gpt-5.2-high、claude-opus-4-5-20251101、gemini-3-pro、kimi-k2.5-thinking
• Vision（Last Updated Jan 29, 2026）：gemini-3-pro、gemini-3-flash、gemini-3-flash (thinking-minimal)、gpt-5.2-high、gpt-5.1-high
• Search（Last Updated Jan 29, 2026）：gemini-3-pro-grounding、gpt-5.2-search、gpt-5.1-search、grok-4-1-fast-search、grok-4-fast-search
• Text-to-Image（Last Updated Jan 29, 2026）：gpt-image-1.5-high-fidelity、gemini-3-pro-image-preview-2k (nano-banana-pro)、gemini-3-pro-image-preview (nano-banana-pro)、flux-2-max、flux-2-flex
• Image Edit（Last Updated Jan 29, 2026）：chatgpt-image-latest-high-fidelity (20251216)、gemini-3-pro-image-preview-2k (nano-banana-pro)、gemini-3-pro-image-preview (nano-banana-pro)、gpt-image-1.5-high-fidelity、seedream-4.5
• Text-to-Video（Last Updated Jan 29, 2026）：veo-3.1-audio、sora-2-pro、veo-3.1-fast-audio、grok-imagine-video、veo-3-fast-audio

注：SOTA 快照只用于“排序参考”，最终可用性以 registry 为准；registry 未登记 releasedAt 的型号不会被路由使用（Fail-Closed）。

---

3. 模型系列识别规则

模型系列	识别规则	示例
OpenAI	gpt-5*, gpt-oss*, gpt-image-1.5*, chatgpt-image-latest*, sora-2*, gpt-audio*, gpt-realtime*	gpt-5.2-pro, gpt-image-1.5, sora-2-pro
Claude	claude*	claude-sonnet-4.5, claude-opus-4.5-thinking
Gemini	gemini*	gemini-3-pro, gemini-3-flash
Grok	grok*	grok-4.1-thinking, grok-4.1-fast
DeepSeek	deepseek*	deepseek-v3.2, deepseek-v3.2-thinking
Qwen	qwen*, qwen3-coder*	qwen3-coder-480b-a35b
Other	兜底	由 registry 决定

---

4. Fallback 路由链

4.1 路由策略: 聚合优先 (Aggregator-First)

模型系列	原生 Provider	Fallback 链 (按优先级)
OpenAI	OpenAI	Poe → OpenRouter → OpenAI
Claude	Anthropic	Poe → OpenRouter → Anthropic
Gemini	Google	Google (Ai-studio-jason) → Poe (nano-banana-pro) → OpenRouter
Grok	xAI	Poe → OpenRouter → xAI
DeepSeek	DeepSeek	Poe → OpenRouter → DeepSeek
Qwen	Alibaba/Vertex	OpenRouter → VertexAI(MaaS) → Alibaba
Other	-	OpenRouter → Poe

4.2 特殊处理: Google Gemini

仅保留付费账号 Ai-studio-jason（到期: 2026-03-26）。Gemini 系列 fallback 到 Poe nano-banana-pro。

const GOOGLE_API_KEYS = [
  { email: 'Ai-studio-jason', priority: 0, expiresAt: '2026-03-26' },
];
// Gemini fallback 链: Google -> Poe (nano-banana-pro) -> OpenRouter

4.3 旧模型迁移表（可选开关）

默认不启用。启用后仅做“别名迁移”，实际仍受 releasedAt >= 2025-07-01 约束。

旧模型(禁用)	迁移到(可用)
gpt-4o*	gpt-5.2 / gpt-5-mini
o3* / o4-mini*	gpt-5.2-pro
dall-e-3	gpt-image-1.5 / chatgpt-image-latest
whisper-v3 / gpt-4o-mini-transcribe	deepgram-flux / gpt-audio-mini-2025-12-15
text-embedding-3-*	cohere-embed-v4.0 / voyage-4-large
cohere-rerank-3*	cohere-rerank-v4.0-*
elevenlabs-v3*	gemini-2.5-*-tts / gpt-audio-mini-2025-12-15

---

5. 聚合平台 API 配置

平台	Base URL	环境变量
Poe	https://api.poe.com/v1	POE_API_KEY
OpenRouter	https://openrouter.ai/api/v1	OPENROUTER_API_KEY

5.1 原生 Provider API

Provider	Base URL	环境变量
OpenAI	https://api.openai.com/v1	OPENAI_API_KEY
Anthropic	https://api.anthropic.com	ANTHROPIC_API_KEY
Google	https://generativelanguage.googleapis.com/v1beta	GOOGLE_API_KEY
DeepSeek	https://api.deepseek.com/v1	DEEPSEEK_API_KEY
Cohere	https://api.cohere.com	COHERE_API_KEY
Voyage	https://api.voyageai.com/v1	VOYAGE_API_KEY
Deepgram	https://api.deepgram.com	DEEPGRAM_API_KEY

---

6. 模型ID转换映射

6.1 Poe 平台模型映射（仅保留 ≥2025-07）

说明：Poe 的“产品名”以平台实际为准；此表只保留新型号骨架，旧型号不再登记。

const POE_MODEL_MAP = {
  // OpenAI / GPT-5
  'gpt-5.2': 'GPT-5.2',
  'gpt-5.2-pro': 'GPT-5.2-Pro',
  'gpt-5-mini': 'GPT-5-Mini',
  'gpt-5-nano': 'GPT-5-Nano',

  // Claude 4.5
  'claude-opus-4.5': 'Claude-Opus-4.5',
  'claude-sonnet-4.5': 'Claude-Sonnet-4.5',
  'claude-haiku-4.5': 'Claude-Haiku-4.5',

  // Gemini 3 (NanoBanana 系列)
  'nano-banana-pro': 'NanoBanana-Pro',

  // DeepSeek / Qwen
  'deepseek-v3.2': 'DeepSeek-V3.2',
  'qwen3-coder-480b-a35b': 'Qwen3-Coder-480B',

  // Image
  'gpt-image-1.5': 'GPT-Image-1.5',
  'chatgpt-image-latest': 'ChatGPT-Image-Latest',
  'flux-2-max': 'FLUX-2-Max',

  // Video
  'sora-2-pro': 'Sora-2-Pro',
  'veo-3.1-audio': 'Veo-3.1-Audio',
};

6.2 OpenRouter 模型映射（已核对 ID 形态）

// 格式: provider/model-name
'gemini-3-pro'         -> 'google/gemini-3-pro-preview'
'claude-opus-4.5'      -> 'anthropic/claude-opus-4.5'
'claude-sonnet-4.5'    -> 'anthropic/claude-sonnet-4.5'
'claude-haiku-4.5'     -> 'anthropic/claude-haiku-4.5'
'gpt-5.2'              -> 'openai/gpt-5.2'
'gpt-5.2-pro'          -> 'openai/gpt-5.2-pro'
'grok-4.1-fast'        -> 'x-ai/grok-4.1-fast'

6.3 Google AI Studio 模型映射（去除 2.x/旧型号）

const GOOGLE_MODEL_MAP = {
  'gemini-3-pro': 'gemini-3-pro',
  'gemini-3-flash': 'gemini-3-flash',
  'gemini-3-pro-grounding': 'gemini-3-pro-grounding',

  // TTS（Cloud TTS / Gemini TTS）
  'gemini-2.5-pro-tts': 'gemini-2.5-pro-tts',
  'gemini-2.5-flash-tts': 'gemini-2.5-flash-tts',
};

---

7. LLM 模型清单（仅含 ≥2025-07）

7.1 旗舰模型

模型	Provider	特点
Gemini 3 Pro	Google	通用能力与长上下文强，Arena Text/Vision 顶部区间
GPT-5.2 Pro	OpenAI	高可靠推理/工具调用，Agent 主力
Claude Opus 4.5 (Thinking)	Anthropic	深度分析与代码高上限

7.2 主力/性价比模型

模型	Provider	特点
Gemini 3 Flash	Google	快速、成本低、可开 minimal thinking
GPT-5.2	OpenAI	默认通用主力
GPT-5 mini	OpenAI	Fast 档位主力
Claude Sonnet 4.5	Anthropic	编程/代理强，综合性价比
Claude Haiku 4.5	Anthropic	极低延迟/高并发
Grok 4.1 Fast	xAI	大上下文 + 工具调用效率
DeepSeek V3.2	DeepSeek	工具调用/思维模式融合，性价比突出
Qwen3-Coder-480B-A35B	Qwen	代码/代理任务强（开源生态）

---

8. 其他模型类别（仅含 ≥2025-07）

8.1 图片生成/编辑

模型	Provider	说明
chatgpt-image-latest	OpenAI	Image Edit Arena Top；编辑/修复首选
gpt-image-1.5	OpenAI	文本渲染/指令跟随强
nano-banana-pro	Google(Gemini 3)	中文文字/排版友好（Poe/Google）
flux-2-max	Black Forest Labs	高质感风格与真实感（Flux.2 系列）

说明：DALL·E 3 属于 <2025-07 旧型号，已移除。

8.2 Embedding

模型	Provider	说明
voyage-4-large	Voyage AI	新一代嵌入模型（召回质量优先）
cohere-embed-v4.0	Cohere	稳定、覆盖面广，作为第二路召回

说明：text-embedding-3-* 属于 <2025-07 旧型号，已移除。

8.3 Reranker

模型	Provider	说明
cohere-rerank-v4.0-pro	Cohere	质量优先
cohere-rerank-v4.0-fast	Cohere	低时延/低成本

8.4 Audio

模型	Provider	类型	说明
deepgram-flux	Deepgram	STT	流式对话/语音代理优先
gpt-audio-mini-2025-12-15	OpenAI	STT/TTS	通用音频兜底（LLM 音频）
gemini-2.5-pro-tts	Google	TTS	自然度优先
gemini-2.5-flash-tts	Google	TTS	低时延优先

8.5 Video（仅保留已知 ≥2025-07）

模型	Provider	说明
veo-3.1-audio	Google	带音频、叙事控制增强
sora-2-pro	OpenAI	高保真 T2V

---

9. 调用流程示例

// 1. 用户发起请求
const result = await smartRouter.chatCompletion({
  model: 'claude-sonnet-4.5',
  messages: [{ role: 'user', content: 'Hello' }],
});

// 2. SmartRouter 处理流程
// 2.1 识别模型系列: claude
// 2.2 获取路由配置: { fallbackChain: ['poe', 'openrouter', 'anthropic'] }
// 2.3 校验模型合规 (releasedAt >= 2025-07-01)
// 2.4 按顺序尝试 Provider

// 3. 按链路尝试
// 尝试 Poe: claude-sonnet-4.5 -> Claude-Sonnet-4.5
// 如果失败 -> 尝试 OpenRouter: anthropic/claude-sonnet-4.5
// 如果失败 -> 尝试 Anthropic: claude-sonnet-4.5 (native)

// 4. 返回结果
console.log(result.actualProvider);
console.log(result.attemptedProviders);
console.log(result.errors);

---

10. 环境变量配置

# 聚合平台
POE_API_KEY=xxx
OPENROUTER_API_KEY=xxx

# 原生 Provider
OPENAI_API_KEY=xxx
ANTHROPIC_API_KEY=xxx
GOOGLE_API_KEY=xxx
DEEPSEEK_API_KEY=xxx

# 检索与排序
VOYAGE_API_KEY=xxx      # Embedding (Voyage-4)
COHERE_API_KEY=xxx      # Embed v4.0 + Rerank v4.0

# 音频
DEEPGRAM_API_KEY=xxx    # STT (Flux)

---

11. 核心文件索引

文件	职责
lib/model-config.ts	场景配置管理器
lib/model-providers.ts	模型定义库（registry + releasedAt）
lib/llm/model-guard.ts	v1.3 新增：合规校验（2025-07 截止）
lib/llm/model-router.ts	路由链定义 + 模型ID转换
lib/llm/smart-router.ts	智能路由器（自动 fallback）
lib/llm/registry.ts	Provider 注册表
lib/llm/providers/*.ts	各 Provider 实现
lib/services/image-generation.ts	图片生成服务（模型优先级 + 路由逻辑）

---

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