术语表
本文档用来称呼网关各个部分的术语，按阅读时遇到的先后排列。文档里用到这些术语时，含义就以这里写的为准。
请求与模型
- 模型 id
客户端在
model字段里填的名字，例如example-chat。它是网关对外公布的模型名，和任何 provider 自己怎么称呼这个模型无关。- 别名（alias）
解析到同一个模型 id 的另一个名字。在模型上用
aliases:声明。- 模型注册表（model registry）
一个 YAML 文件，通常叫
models.yaml，列出每个模型 id 以及它背后的路由。网关怎么找到这个文件，见配置。- API key 与 provider key
API key 是客户端出示给网关的凭据；provider key 是网关出示给 provider 的凭据。两者永远不是同一个。
路由与 provider
- 路由（route）
为模型 id 提供服务的一条途径，也就是模型
route:列表里的一项，写明 adapter 的 kind、base URL、凭据和权重。一个模型 id 可以有多条路由，网关正是靠这一点在多条路由之间做负载均衡和故障切换。- 端点（endpoint）
路由发送请求的目标服务器。文档里说「端点」时指服务器本身，说「路由」时指配置里的那一项。
endpoint_id网关用来标识「某个模型的某个端点」的键，写作
<model-id>:<location>：本机 12003 端口上的服务器是glm-4.6:local-12003，托管 API 是glm-4.6:zai-api。熔断器、延迟统计和权重覆盖都以它为键。后缀来自主机和端口，或者来自 adapter 的 kind，所以从它看不出服务器是谁在运行。- provider
路由背后的服务：OpenRouter、DeepSeek、你自己的 vLLM 服务器。在配置里，路由的
provider:是一个标签，这条路由的流量在日志和仪表盘里都记在这个标签下。- kind
路由的
kind:，决定用哪个 adapter 和端点通信：openai_compat、vllm、openrouter、anthropic等。- adapter
对接某一家 provider API 的代码。它负责构造请求、持有 provider key，并把响应转换回 OpenAI 的格式。自建服务器用的是通用的 OpenAI 兼容 adapter。
- 上游（upstream）
网关为了得到回答而调用的那一端，也就是路由的另一头。
选择路由
- router
按模型配置、为每个请求挑选路由的逻辑。
fixed按权重随机选一条路由，失败时回退到其他路由，是默认值；routewise在延迟和成本之间做取舍。模型用router:指定其中一个。- 权重（weight）
在
fixedrouter 下，一条路由分到的相对流量份额。权重为0的路由仍保留在配置里，但不会收到任何流量，连回退也不会用到它。- 回退（fallback）
某条路由失败时 router 的做法：按顺序尝试该模型剩下的路由，直到有一条返回结果。
- 熔断器（circuit breaker）
按端点设置的开关：端点反复失败后，停止向它发送流量；冷却一段时间后，只放一个测试请求过去。
- 卸载路由（offload route）
一条预留的路由，专门接收模型的其他路由来不及开始处理的请求。见排队等待卸载。
- 路由配置文件（routing file）
可选的
routing.yaml。里面是健康探测设置和本地/远程的权重划分；它能改变什么、不能改变什么，见路由配置文件。
部署
- 发行版（distribution）
某个部署自己的文件——它的 manifest、模型注册表、路由配置文件、品牌和 Compose 设置——集中放在
distributions/<name>/里，而不是放在源码里。distributions/example/是本仓库自带的那一个。- overlay
distributions/<name>/这个目录本身。之所以叫 overlay，是因为它挂载在中立镜像之上，而不是打包进镜像。- manifest
distribution.yaml，发行版里的一个文件，写明发行版的名字以及各配置文件放在哪里。- 试运行与生效（dry run / active）
DISTRIBUTION_CONFIG_MODE的两种模式。试运行是默认模式，这个设置里写作dark：网关会读取并检查 manifest，在日志里记下启用后会改变什么，但不使用其中任何内容。active则真正应用它。- 运行数据存储（operational store）
Postgres 里存放账号、API key 以及管理控制台上所有改动的那些表。
- 运行时模型（runtime model）
在管理控制台里创建、而不是写在模型注册表里的模型。它只存在于运行数据存储中。
- 控制台（console）
Next.js 网页应用：注册和登录、用户仪表盘、对话调试页（playground）和管理控制台。它还会把 API 路径转发给网关，见公开路径表。
- Site UI 模块（Site UI module）
发行版为公开页面编写的 React 组件，编译进它自己的控制台镜像。见 Site UI 模块。
- 后端扩展（后端 extension）
部署在启动时加载的可信 Python 模块，用来添加 adapter、agent 访问规则或配额来源。见后端扩展。