semantic-router 内置模型目录（Built-in Model Catalog）完全指南：协议、Provider、模型卡片与可审计评测体系

• 后端
• API网关
• 模型推理服务
• AI Agent

本文以 config/catalog/README.md 为骨架，系统讲解 vLLM Semantic Router 内置模型目录的定位、资源图结构、生成与校验命令、每类资源（协议、Provider、模型卡片、推理家族、基准、评测、指数）的所有权边界，以及它如何以"用户配置边界"的形式融入 v0.3 配置体系。读完你既能用make model-catalog-*驱动目录生成与审计，也能准确区分 Model Card、ProviderDefinition、绑定关系与推理能力这几个容易混淆的概念，并理解 Hub 视图"只做精确对比、不做整体排行榜"的设计约束。

一、目录是什么：模型的"仓库级事实源"

config/catalog/是当前仓库中内置协议的单一事实源（source of truth）。它不只管理"有哪些模型"，而是把以下内容统一编排进一张可校验、可生成的资源图：

• 内置协议与各自的 wire 路径；
• Provider（云、网关、运行时）及其原生模型映射、鉴权默认值、协议兼容性、支持层级与一致性状态；
• 物理模型的固有事实（Model Card：参数规模、上下文窗口、能力、模态、许可证、发布时间）；
• 由 Recipe 支撑的逻辑模型身份（虚拟模型及其角色契约）；
• 可复用的推理旋钮投影（reasoning families）；
• 带版本的基准与指标定义；
• 物理/虚拟模型精确到模型、推理档位、版本化基准 profile 的评测记录；
• 可审计的指数（normalization、权重、缺失数据策略）。

该目录由 manifest.yaml 声明入口，资源的实际内容按职责拆分为resources/下的多个子目录，并被 schemas/catalog-source-v1.schema.json（以及catalog-resources-v1、catalog-snapshot-v2两套 schema）约束。

边界约定：密钥、算子端点（operator endpoints）和面向请求的别名（request-facing aliases）不允许出现在这里——它们属于部署配置，而非目录资源。

二、生成与校验：两个 make 目标与完整工作流

README 给出两个核心命令，对应 tools/make/model-catalog.mk 中的实现：

make model-catalog-generate make model-catalog-check

• model-catalog-generate调用tools/catalog/generate_model_catalog.py：校验资源图后，重写一份内置发行快照（built-in distribution snapshot）、Router embed，以及一份供网站和 Dashboard 共享的公共 JSON 快照（即 website/static/model-catalog/catalog.json）。CLI 在源码检出环境中直接读取该发行快照。
• model-catalog-check是一个组合门禁，按顺序执行（见 tools/make/model-catalog.mk）：
  1. model-catalog-test：以-m unittest discover -s tools/catalog/tests -p "test_*.py"运行目录编译器契约测试；
  2. model-catalog-generated-check：先跑model-catalog-boundary-check（拒绝签入的消费者镜像，例如dashboard/frontend/src/generated/modelCatalog.json必须不存在——Dashboard 必须直接导入website/static/model-catalog/catalog.json；CLI 的model_assets版本树必须是"仅构建期暂存"），再以generate_model_catalog.py --check校验生成产物未过期；
  3. 最后调用tools/catalog/audit_model_catalog.py --require-min-evaluations-per-model 5，强制每个物理模型至少 5 条评测记录。

# 面向发布验证的额外目标 make model-catalog-package-stage # 基于内置快照暂存被忽略的 CLI 包资产 make model-catalog-package-check # 逐字节校验暂存资产（stage_model_catalog_package.py --check） make model-catalog-audit # 报告编写评测的完整性（默认不阻塞，可用 MODEL_CATALOG_AUDIT_ARGS 调整）

铁律：不要手工编辑生成投影（generated projections）或暂存树；普通用户 YAML 也永不携带 catalog 版本、摘要、默认指数身份——这些是构建时嵌入的元数据（embedded build metadata）。

三、资源所有权：八类资源的职责边界

manifest 的resources:字段把目录拆成 8 类资源，每一类都有严格的所有权边界：

3.1 protocols：wire 路径与 base path 规则

protocols.yaml 中每个协议声明default_base_path与operations。当前内置三个协议：OpenAI Chat Completions（openai.chat.v1，/v1/chat/completions）、OpenAI Responses（openai.responses.v1，/v1/responses，额外携带reasoning能力）、Anthropic Messages（anthropic.messages.v1，/v1/messages），并各自列出create、list_models操作。

关键规则：端点未提供 API root 时使用协议的默认 base path；一旦配置了base_url路径，就替换默认 base path，且操作后缀只追加一次（避免base_url自带/v1导致路径重复）。

3.2 providers：服务契约而非模型归属

resources/providers/ 下每个文件对应一个稳定 Provider ID，声明：协议兼容性、auth 默认值（如 DeepSeek 使用Authorization: Bearer）、provider 原生模型 ID、限制/定价、非密钥请求头默认值、推理传输（如deepseek_thinking）、支持层级、一致性状态（如fixture_verified）与展示元数据。

# config/catalog/resources/providers/deepseek.yaml（节选） id: deepseek category: model_api support_tier: compatible default_base_url: https://api.deepseek.com/v1 protocols: [openai/chat-completions@1, openai/responses@1] reasoning_transport: deepseek_thinking conformance: status: fixture_verified models: - catalog: deepseek/deepseek-v4.1-flash relationship: first_party id: deepseek-flash

三个关键设计：

1. 关系显式分类：每个models[]映射必须把"创作者到服务渠道"的关系标为first_party、managed_cloud、gateway或self_hosted之一，防止网关被误认为模型发布方（publisher），且不因此加重 provider 分类或支持层级的负担；
2. 凭据头禁止入内：任何携带凭据的 header 都不允许写入 provider 资源；
3. 宽 Provider、窄 Model Card：ProviderDefinition保持宽泛——即使某 provider 没有精选的内置模型映射，Add Model 与手写自定义模型仍可使用其已知运行时契约；而内置物理清单在创作者公司层面进行精选（见第五节）。

3.3 models/single 与 models/virtual：物理身份与逻辑身份分离

物理 Model Card 放在 resources/models/single/，按创作者分文件，记录的是固有事实。以 DeepSeek V4 Pro 为例（resources/models/single/deepseek.yaml）：

- id: deepseek/deepseek-v4-pro kind: physical publisher: DeepSeek distribution: type: open_weights license: MIT family: deepseek-v4 parameter_size: 1.6T (49B active) revision: DeepSeek-V4-Pro-0813 lifecycle: active limits: context_window_size: 1048576 max_output_tokens: 384000 capabilities: [chat, reasoning, tools, structured_output, long_context] reasoning_family: deepseek verification: status: claimed released_at: '2026-08-13'

虚拟模型放在 resources/models/virtual/，是 Recipe 支撑的逻辑身份，例如 vllm-sr.yaml 中的 MoM V1 家族（Blend / Lite / Flash / Ultra / Vault），每个都声明asset: mom-v1、entrypoint、recipe（balance / cost / speed / accuracy / vault）与角色契约（roles[]：角色名、是否必需、minimum_candidates、trait 要求、recommended_pool）。这些 Recipe 资产打包自 config/recipes/built-in/latest/mom-v1（manifest 的assets指向../recipes/built-in/latest/mom-v1）。

Model Card 身份唯一性：一张物理卡片只代表一个规范的、上游的模型身份。日期快照、云别名、量化版本、serving 引擎打包不会成为重复卡片：provider 专属名称放进该 provider 的models[]，运行时/量化细节放进评测主体（evaluation subject）；只有当发布方把某个独立 checkpoint 当作"可单独选择且行为有实质差异的模型"时，才允许成为新卡片。

可达性约束：每张处于 active 状态的物理 Model Card 必须能通过至少一个provider 拥有的映射被触达；同一卡片可出现在多个 provider 下而无需复制其固有身份。

3.4 reasoning-families：推理旋钮的请求投影

resources/reasoning-families.yaml 定义"可复用的推理旋钮投影"，常见type有两种：

• reasoning_effort：单一 effort 阶梯（如 DeepSeeklow/high/max、GPT 系minimal/low/medium/high/xhigh/max）；
• chat_template_kwargs：通过 chat 模板参数开关推理（如enable_thinking、thinking）。

两种进阶字段值得注意：

• activation_parameter：模型除了 effort 阶梯外还有独立的开/关开关时使用。例如qwen3.8家族用enable_thinking做激活、reasoning_effort走low/medium/xhigh阶梯——并且none不会被虚构为一个 effort 档位；glm-5.2类似（enable_thinking+high/max）；
• effort_flags：某些模板把 effort 暴露为互斥布尔标志而非字符串，effort_flags把每个命名档位映射到真实模板参数（如 nemotron 系的low: low_effort、medium: medium_effort）；"剩余一个激活档位"可用"省略所有 effort 标志"表示。这是 catalog/自定义模型 schema，永远不会成为新的决策字段。

Provider 绑定仍自行决定这些控件以 chat-template kwargs、顶层字段还是 provider 原生对象传输。

3.5 benchmarks：版本化定义与展示归一化

resources/benchmarks.yaml 内置 60+ 个带版本（如tiger-ai-lab/mmlu-pro@1.0.0、harbor/terminal-bench@2.1.0、livecodebench/livecodebench@6.0.0）的基准，每个包含：domain分类、可选语义标签（tags: [core]）、default_profile与一组 profile（每个 profile 精确描述评测设置）、metrics（单位、方向higher_is_better、范围）。例如 GDPval-AA v2 的 Elo 指标：

- id: elo unit: elo range: [-3000, 3000] normalization: {type: linear_clamp, min: 500, max: 2500}

展示归一化规则：评测记录永远保留基准的原始发布测量值；Hub 把所有内置基准渲染在百分比刻度上——proportion/fraction 指标直接映射，其他单位必须显式声明normalization。如文档所述，GDPval-AA v2 与 Briefcase 保留原始 Elo，但按clamp((elo - 500) / 2000, 0, 1) * 100展示。该展示映射独立于指数聚合，且从不改写证据。

core标签是目录拥有的展示分面：当前精选集为 MMLU-Pro、GPQA Diamond、HLE 1.0 text-only、LiveCodeBench、SciCode、Terminal-Bench 2.1；Hub 的语义过滤把 Core 排在首位，All 仍是未过滤默认。SWE-bench Verified 等其他有用测量作为额外、单独可见的证据保留。

3.6 indices：可审计的复合指数

resources/indices.yaml 定义了 5 个指数：General（MMLU-Pro）、Reasoning（GPQA Diamond + HLE 1.0 text-only）、Coding（LiveCodeBench + SciCode）、Agentic（Terminal-Bench 2.1），以及把它们加权合成的vllm-sr/intelligence@1.0.0（权重 general 0.20 / reasoning 0.40 / coding 0.20 / agentic 0.20）。每个指数声明aggregation: weighted_mean、scale: [0, 100]、missing.policy: require_all，并在components中显式列出允许的 profile 集合（如 HLE 只取independent-text-only与text-only）。

missing.policy: require_all意味着缺失即缺失：永远不插入猜测的 0，也不用参数规模作为代理（never insert a guessed zero or a parameter-size proxy）。同一模型、同一 effort、同一版本化基准 profile、同一指标的两条可用记录会被拒绝，而不是偷偷选一个赢家——必须修订评测身份或显式解决证据冲突。

四、时间锚与证据纪律：目录如何保持"诚实"

• 时间锚：每条可用记录携带日历锚点。知道运行日期用measured_at；只知道"审阅了发布值"的日期用observed_at。后者不会被静默当作运行日期，且除非算子真的知道运行日期，否则两个字段都不属于最简用户编写证据面。
• 评测准入 ≠ effort 完整性：每张物理卡片在同一个"模型/effort/provenance"证据桶内必须至少有 5 个不同基准。推理家族可能暴露额外真实运行时档位而其 effort 专属测量尚未发布——这些档位保留"衍生证据缺口"。审计把可选档位报为 complete / partial / unmeasured，并可用更严格的 opt-in 门禁强制执行；但生成与 Hub 都不会跨档位复制分数。
• 无reasoning_family的卡片：enabled、disabled、default、unspecified只是对发布运行条件的描述，不创造用户可配置的选择器。
• 运行时选择器边界：消费同一"精确 effort"边界，绝不跨 effort 复制指数证据，也不把指数分数乘以覆盖率；覆盖率只能用来打破"其它方面相等的可用分数"之间的平局。

五、内置清单策略：manifest.inventory.physical

manifest.yaml的inventory.physical声明strategy: curated_creator_companies、default_min_representatives: 3以及每个发布方（publisher）的representative_models列表与可选min_representatives。例如 DeepSeek 的代表模型是deepseek/deepseek-v4-pro、deepseek/deepseek-v3.2、deepseek/deepseek-r1；ByteDance / Seed 与 Thinking Machines Lab 的min_representatives为 2。

生成器会拒绝未列入清单的物理创作者、缺失或过期的代表模型、低于最小深度的创作者。该策略不会发射进运行时快照或暴露在用户配置中——某个候选是否主流、哪些近期产品线有代表性，是评审决策而非机械的发布日期排名。内容策展原则上"每个创作者大约保留最近三代或代表性产品线"，而不是堆积次要创作者的长尾；且这针对的是 Model Card，不是 serving 端点。

六、用户配置边界：目录如何嵌入 v0.3 配置

目录采纳是加法式的，落在现有 v0.3 层级内：

配套约束：

• Router 拥有的 listener 使用的物理模型必须有显式backend_refs条目；外部网关元数据与内置虚拟模型可以"无后端"（backendless）。vllm-sr serve因为自持本地 Envoy 传输，即使为空 listener 列表提供遗留默认 listener，也要求物理后端。
• catalog 支撑的模型自动物化其卡片与推理家族。
• 自定义 vLLM、SGLang、私有或新发布模型省略catalog，可作为最小绑定保留，或提供手写 Model Card、自定义推理行为与顶层评测记录。
• 目录发行版本、摘要、内部指数身份、生成默认值、绑定关系分类永不进入普通用户 YAML——用户选择 Provider ID，但不得声明或覆盖仓库拥有的关系。
• reasoning能力与reasoning_family目的不同：卡片可以如实宣称具备推理能力，即使 vLLM Semantic Router 尚未验证该家族的可配置推理投影；只有当用户可见档位与 wire 传输已实现并测试，才附加内置推理家族——否则模型保持可用，而不虚构一个开关。

七、虚拟模型的推荐池与 MoM 2.0 参考池

• recommended_pool是建议而非外键：可指名 catalog 支撑的模型或只在某部署配置中存在的算子定义模型；可省略或为空。其长度不改变角色的必填分配或minimum_candidates——算子仍须提供足够合格的候选。私有路由中，算子拥有部署边界：推荐不决定模型在哪运行、数据如何处理；声明的能力、上下文/输出限制与质量证据必须匹配实际分配的部署与策略。
• MoM 2.0 策略的参考池在max推理档位使用 DeepSeek V4 Flash / Pro，以及启用推理的 GLM-5.1；分配的 backend 推理模式必须与目录证据一致，其它 effort 档位可能没有所需指数。这些示例不建立图像能力或实测延迟/定价。Vault（models/virtual/vllm-sr.yaml）让recommended_pool保持为空，由算子显式分配满足隐私要求的部署（角色 trait 含private_deployment）。

八、Model Hub：目录，不是整体排行榜

Model Hub 视图的展示纪律构成目录的对外行为契约：

• 公共视图只允许在同一"基准版本 + profile + 指标"上做对比；每个 bar 是一条精确的模型+推理档位记录并显式标注该档位；缺失记录省略而非当作 0；
• 内部指数资源可供路由代码使用，但不产生公共复合排行榜；
• 一个对比元组只有在十个不同模型有可用结果后才进入 Hub 选择器；重复的推理档位记录不计为额外模型；
• 低覆盖证据保留在源目录中用于审计与路由，但从所有公共 Model Hub 视图省略；
• 分页属于目录关切，永不拆分一个对比集合；每个模型模型卡片与每个可选推理档位恰好推导 6 个默认指数槽（MMLU-Pro、GPQA Diamond、HLE 1.0 text-only 无工具、LiveCodeBench、SciCode、Terminal-Bench 2.1），槽位只链接到精确的模型/effort 测量与组件有序兼容 profile 之一；available / partial / missing 指数行被序列化进公共快照，Hub 因而能区分"排名结果"与"证据缺口"；运行时投影只含可用路由先验。vendor 发布但未指定 effort 的分数停留在独立unspecified行，永不被复制进low、medium、high等可选档位。

九、贡献入口：Day-0 支持指南

向目录添加新 Provider / 模型的端到端工作流，见 website/docs/community/model-provider-day-0-support.md；数据结构约束以 config/catalog/schemas/ 下三个 schema（source、resources、snapshot）为准；生成、校验与审计实现位于 tools/catalog/（generate_model_catalog.py、audit_model_catalog.py、catalog_validation.py等）；可验证的产物即 website/static/model-catalog/catalog.json。

十、小结

内置模型目录把"协议、Provider、模型身份、推理旋钮、基准、评测、指数"七类事实收编为一张可生成、可审计、带版本的资源图：生成器负责一致性投影，审计器负责证据完整性（每模型至少 5 条评测），Hub 只做精确对比、拒绝整体排行榜，用户 YAML 则通过catalog、backend_refs[].provider、api_format等有限触点加法式采纳。理解这些所有权边界，是正确使用 vLLM Semantic Router 模型目录、贡献新模型或在私有部署中复用其运行时契约的前提。

• 后端
• API网关
• 模型推理服务
• AI Agent