企业官网建设流程全解析

GoModel 是一个用 Go 编写的 AI 网关（AI Gateway），它的虚拟模型（Virtual Models）功能允许你自定义模型名称：既可以做别名映射（一个稳定名字指向真实模型），也可以做负载均衡（一个名字按策略分发到多个模型）。本文将从新手视角讲清楚虚拟模型能做什么、五种路由策略怎么选，以及它背后"一张表、两个阶段"的统一实体设计。

1. 什么是虚拟模型：别名与访问策略的统一实体

一句话定义：虚拟模型是"你定义"的模型，而不是供应商（Provider）发布的模型。

GoModel 判断一行配置属于哪种虚拟模型，只看它有没有targets（目标模型）：

这个"没有 role 字段、行为由数据推导"的设计正是统一实体的精髓：存储、服务层、管理 API 和仪表盘共用同一套代码，只是同一张virtual_models表喂给了流水线的两个不同阶段。

💡 图中就是仪表盘的 Models 页面：带ALIAS徽标的行就是虚拟模型，可以直观看到anthropic/claude-3-haiku-20240307被影子映射到了claude-sonnet-4-5。

核心类型定义与角色推导见 internal/virtualmodels/types.go（IsRedirect与Kind函数）。

2. 别名映射：稳定名称、影子模型与 A/B 测试

别名映射是虚拟模型最基础也最高频的用法，解决的核心痛点是：应用代码里的模型名不该绑定具体供应商。

稳定名称：把regular指向anthropic/claude-sonnet-4-6，把smarter指向 Opus 级别模型。应用只需要发：

{ "model": "regular", "messages": [] }

想升级模型时，只需在网关侧改一下指向，应用代码一行不用动。

影子模型（Shadow）：虚拟模型的source可以和某个真实模型同名，从而"影子"掉它——应用照发anthropic/claude-opus-4-6，GoModel 实际路由到更便宜的claude-sonnet-4-6。这是零改代码做成本优化的利器。

A/B 测试：把别名今天指向 Opus、明天指向 Sonnet，对比应用的延迟与效果。你也可以在 Playground 里直接切换虚拟模型名称验证行为：

3. 负载均衡：五种路由策略横向对比

一个source指向多个targets时，虚拟模型就变成了负载均衡器。策略由strategy字段选择：

策略选择的核心实现在 internal/virtualmodels/balancer.go，加权轮转的槽位计算见 weightedIndex。

除了"首次怎么选"，还有三个默认开启的保底机制：

• 故障转移链：无论哪种策略，被选中目标若遇到可重试错误，请求会按声明顺序自动重试到剩余目标（见 ResolveFailovers）。
• 会话保持（Session Keeping）：同一客户端会话会粘在最初服务它的目标上，保证多轮对话的提示词缓存（prompt cache）持续命中。
• 不可用目标自动跳过：模型被禁用、供应商宕机或当前调用者无权使用，所有策略都会自动绕开——某个模型配额耗尽时禁用它，流量会立刻转移到其他目标。

4. 设计揭秘：为什么要做"统一实体"

理解这一节，你会明白这个功能为什么"看起来简单、实现却考究"。设计决策记录在 docs/adr/0008-virtual-models.md。

4.1 问题：两套系统，同一个概念

早期 GoModel 里，别名（映射新名字到真实模型）和访问覆盖（按 user_path 控制已有模型）是两张表、两个服务、两组管理端点——但它们本质上是同一个运维概念："运维定义的模型"。分裂导致user_path匹配逻辑被重复实现，还因缺少数据库迁移引发过真实 bug。

4.2 方案：一张表，两个阶段

统一后，所有虚拟模型持久化在virtual_models表，以source为唯一键；加载时经 buildSnapshot 构建内存快照并做图校验，请求期全程只读快照，无需加锁读存储。

解析遵循两阶段规则（见 resolve.go）：

1. Resolver（早阶段）：请求的模型名若精确匹配某重定向的source，改写到其目标（负载均衡在此选点）；
2. Authorizer（晚阶段）：对已解析出的真实选择器做user_paths访问裁决。

两类行永远不会跨阶段干扰：重定向的新名字不会命中策略行，策略行没有目标所以解析器直接忽略。

4.3 进阶：虚拟模型可以"链式组合"

重定向的目标可以再指向另一个虚拟模型，把星形结构变成 DAG：

virtual_models: # 共享底座：小模型轮转池 - source: cheap targets: - { model: openai/gpt-4o-mini } - { model: groq/llama-3.3-70b } # 分层叠加：cheap 池占 3 份权重，与高端模型并列 - source: smart-frugal strategy: round_robin targets: - { model: cheap, weight: 3 } - { model: openai/gpt-4o }

链式解析逐层进行：外层策略选中cheap这条"腿"后，cheap再用自己的策略选具体模型；会话保持在每一层都生效。校验是图属性：环被拒绝、链深最多 8 层，且被其他虚拟模型引用的条目不能删除或改名。

5. 快速上手：三种方式声明虚拟模型

🎯 三种方式功能等价，按团队习惯选择：

方式一：仪表盘（推荐新手）

Models → New virtual model：填Target model即为别名/负载均衡器，留空则为访问策略。目标列表支持拖拽手柄（☰）排序——对failover策略来说，顺序就是优先级。

方式二：config.yaml（推荐 IaC 团队）

virtual_models: # 普通别名 - source: regular target: anthropic/claude-sonnet-4-6 # 加权轮转负载均衡 - source: smart strategy: round_robin targets: - { model: openai/gpt-4o, weight: 2 } - { model: anthropic/claude-sonnet-4-6 }

声明式条目在启动时生效，覆盖管理库中同source的行，且在仪表盘显示为只读（带 Config 徽标）。字段定义见 config/virtualmodels.go。

方式三：VIRTUAL_MODELS 环境变量

把同一列表以 JSON 数组形式注入（如VIRTUAL_MODELS=[{"source":"smart","strategy":"cost","targets":[...]}]），同名时覆盖 YAML 配置，适合容器环境快速调整。

此外还有 Admin API：GET/PUT/DELETE /admin/virtual-models（路由定义见 internal/admin/routes.go），已统一取代旧的/admin/aliases和/admin/model-overrides端点。

6. 实践建议清单

• 给每个核心模型起业务语义别名（regular/smarter/cheap），把供应商细节隔离在网关层；
• 成本优化用cost策略，容灾用failover策略，把主备关系显式写进目标顺序；
• 多轮对话场景保持会话开启（默认开启），让提示词缓存持续命中；
• 配额耗尽时禁用具体模型即可，所有策略会自动把流量移交给其他目标；
• 完整文档见 docs/features/virtual-models.mdx，含 Slowdown 人工延迟、/v1/models展示控制等进阶配置。

虚拟模型把"别名、访问控制、负载均衡、故障转移"四个曾经独立的概念收敛为一个统一实体——这正是 GoModel 作为 LiteLLM 替代方案在模型路由上的差异化设计。