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

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

v1.4 更新

  1. 增加 官方模型清单优先（Official-First）：先同步官方 API models.list，再生成 registry；路由只认官方 model code；不存在/已弃用即 Fail-Closed。
  2. Gemini 模型ID对齐：canonical 统一为 Google Gemini API 的 model code：gemini-3-pro-preview / gemini-3-flash-preview / gemini-3-pro-image-preview；Search Grounding 改为工具配置，不再使用虚构 gemini-3-pro-grounding。
  3. 修正 Poe/OpenRouter 命名映射：Poe 的 Gemini-3-Pro / Gemini-3-Flash 与图片模型 Nano-Banana-Pro 分离；Nano-Banana-Pro 仅用于 gemini-3-pro-image-preview。
  4. Google TTS 模型ID对齐：gemini-2.5-pro-preview-tts / gemini-2.5-flash-preview-tts。
  5. 保持 2025-07-01 前模型硬禁用（v1.3）。

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-*-preview-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到期）

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）

0.4 官方模型清单优先（强制）

  • canonical model id = 官方 API 返回的 model code（不是 Poe/OpenRouter 的“商品名”）
  • 每次发布/启动必须跑完（Fail-Closed）：
    1. sync：拉取官方 models.list
    2. validate：存在 + 未弃用 + releasedAt >= 2025-07-01
    3. map：生成 Poe/OpenRouter 的 别名映射（只做转换，不改变 canonical）

Gemini 3 命名对齐（示例）

  • Official (Google Gemini API)：gemini-3-pro-preview / gemini-3-flash-preview / gemini-3-pro-image-preview
  • Poe：Gemini-3-Pro / Gemini-3-Flash / Nano-Banana-Pro
  • OpenRouter：google/gemini-3-pro-preview / google/gemini-3-flash-preview / google/gemini-3-pro-image-preview

0.5 官方模型同步（伪代码）

// 目标：以官方 models.list 为准生成 registry，再由 registry 驱动路由。
// 注意：Google 返回的 model name 通常带 "models/" 前缀，统一剥离成 model code。

async function syncGoogleModels() {
  const url = `https://generativelanguage.googleapis.com/v1beta/models?key=${process.env.GOOGLE_API_KEY}`;
  const res = await fetch(url);
  if (!res.ok) throw new Error(`GOOGLE_MODELS_LIST_FAILED: ${res.status}`);
  const data = await res.json();

  const officialIds = new Set(
    (data.models ?? []).map((m: any) => String(m.name || '').replace(/^models\//, ''))
  );

  // Fail-Closed：如果 canonical 不在 officialIds 里，拒绝路由
  // assert(officialIds.has('gemini-3-pro-preview'))
}

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. 校验模型存在 + 合规（officialListed && 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 Preview、Claude Opus 4.5 Thinking、Grok 4.1 Thinking、GPT-5.2 Pro
Balanced 默认体验 Gemini 3 Flash Preview、GPT-5.2、Claude Sonnet 4.5、DeepSeek V3.2
Fast 低时延/低成本 Gemini 3 Flash Preview (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-preview → gpt-5.2 → claude-sonnet-4.5 → grok-4.1-fast Text Arena Top 区间内择优（默认性价比）
联网搜索 search gemini-3-pro-preview (grounding=google_search) → 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-preview → gemini-3-flash-preview → gpt-5.2 Vision Arena Top 区间内择优
图片生成 image gpt-image-1.5 (fidelity=high) → gemini-3-pro-image-preview (imageSize=2K) → flux-2-max 文字/排版优先；第二/三梯队兜底
图片编辑 image_edit chatgpt-image-latest (fidelity=high) → gemini-3-pro-image-preview (imageSize=2K) → 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-preview-tts → gemini-2.5-flash-preview-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-preview → 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）。

Arena 命名到 canonical 的关键映射（Gemini）：

  • gemini-3-pro → gemini-3-pro-preview
  • gemini-3-flash / gemini-3-flash (thinking-minimal) → gemini-3-flash-preview + thinkingLevel
  • gemini-3-pro-grounding → gemini-3-pro-preview + google_search grounding tool
  • gemini-3-pro-image-preview-2k (nano-banana-pro) → gemini-3-pro-image-preview + imageSize=2K

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-preview, gemini-3-flash-preview, gemini-3-pro-image-preview
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) → OpenRouter → Poe (Gemini-3-*)
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）。

  • 文本/视觉：fallback 到 Poe Gemini-3-Pro / Gemini-3-Flash（按场景）
  • 图片生成/编辑：fallback 到 Poe Nano-Banana-Pro（对应 gemini-3-pro-image-preview）
const GOOGLE_API_KEYS = [
  { email: 'Ai-studio-jason', priority: 0, expiresAt: '2026-03-26' },
];
// Gemini Text/Vision fallback 链: Google -> OpenRouter -> Poe (Gemini-3-*)
// Gemini Image 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-*-preview-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.0 规则：官方优先，聚合只做别名

  • canonical model id 只允许来自 官方 API 的 model code
  • Poe/OpenRouter 仅负责把 canonical 转成平台可识别的 别名
  • 任何新增/变更：先跑 models.list 同步，再改路由；否则 CI 拒绝

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（官方 model code → Poe 商品名）
  'gemini-3-pro-preview': 'Gemini-3-Pro',
  'gemini-3-flash-preview': 'Gemini-3-Flash',

  // Gemini 3 Pro Image Preview（Nano Banana Pro）
  'gemini-3-pro-image-preview': 'Nano-Banana-Pro',

  // （可选）历史别名：不作为 canonical，仅用于迁移
  'nano-banana-pro': 'Nano-Banana-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-preview' -> 'google/gemini-3-pro-preview'
'gemini-3-flash-preview' -> 'google/gemini-3-flash-preview'
'gemini-3-pro-image-preview' -> 'google/gemini-3-pro-image-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（官方 model code）
  'gemini-3-pro-preview': 'gemini-3-pro-preview',
  'gemini-3-flash-preview': 'gemini-3-flash-preview',
  'gemini-3-pro-image-preview': 'gemini-3-pro-image-preview',

  // Search Grounding：不是模型ID，是 tools/config
  // 例：gemini-3-pro-preview + tools=[google_search]

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

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

7.1 旗舰模型

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

7.2 主力/性价比模型

模型 Provider 特点
Gemini 3 Flash Preview 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 文本渲染/指令跟随强
gemini-3-pro-image-preview Google(Gemini 3) Nano-Banana-Pro；中文文字/排版友好（图像生成/编辑）
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-preview-tts Google TTS 自然度优先
gemini-2.5-flash-preview-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 校验模型存在 + 合规（officialListed && 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 猪哥云-灵阙企业级智能体平台