后端API网关模型推理服务AI Agent【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载本文以 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-checkmodel-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.mkmodel-catalog-test以-m unittest discover -s tools/catalog/tests -p test_*.py运行目录编译器契约测试model-catalog-generated-check先跑model-catalog-boundary-check拒绝签入的消费者镜像例如dashboard/frontend/src/generated/modelCatalog.json必须不存在——Dashboard 必须直接导入website/static/model-catalog/catalog.jsonCLI 的model_assets版本树必须是仅构建期暂存再以generate_model_catalog.py --check校验生成产物未过期最后调用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 类资源每一类都有严格的所有权边界资源路径职责protocolsresources/protocols.yaml支持的操作及其 wire 路径providersresources/providers/每个稳定 Provider ID 一个文件含运行时服务契约reasoning familiesresources/reasoning-families.yaml可复用的推理旋钮请求投影modelsresources/models/single/ 与 resources/models/virtual/物理模型固有事实 / Recipe 支撑的逻辑模型身份benchmarksresources/benchmarks.yaml版本化基准与指标定义evaluationsresources/evaluations/single/ 与 resources/evaluations/virtual/物理 / 虚拟模型的精确评测记录indicesresources/indices.yaml可审计的归一化、权重与缺失数据策略3.1 protocolswire 路径与 base path 规则protocols.yaml 中每个协议声明default_base_path与operations。当前内置三个协议OpenAI Chat Completionsopenai.chat.v1/v1/chat/completions、OpenAI Responsesopenai.responses.v1/v1/responses额外携带reasoning能力、Anthropic Messagesanthropic.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-completions1, openai/responses1] reasoning_transport: deepseek_thinking conformance: status: fixture_verified models: - catalog: deepseek/deepseek-v4.1-flash relationship: first_party id: deepseek-flash三个关键设计关系显式分类每个models[]映射必须把创作者到服务渠道的关系标为first_party、managed_cloud、gateway或self_hosted之一防止网关被误认为模型发布方publisher且不因此加重 provider 分类或支持层级的负担凭据头禁止入内任何携带凭据的 header 都不允许写入 provider 资源宽 Provider、窄 Model CardProviderDefinition保持宽泛——即使某 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、recipebalance / cost / speed / accuracy / vault与角色契约roles[]角色名、是否必需、minimum_candidates、trait 要求、recommended_pool。这些 Recipe 资产打包自 config/recipes/built-in/latest/mom-v1manifest 的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/maxchat_template_kwargs通过 chat 模板参数开关推理如enable_thinking、thinking。两种进阶字段值得注意activation_parameter模型除了 effort 阶梯外还有独立的开/关开关时使用。例如qwen3.8家族用enable_thinking做激活、reasoning_effort走low/medium/xhigh阶梯——并且none不会被虚构为一个 effort 档位glm-5.2类似enable_thinkinghigh/maxeffort_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-pro1.0.0、harbor/terminal-bench2.1.0、livecodebench/livecodebench6.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.1Hub 的语义过滤把 Core 排在首位All 仍是未过滤默认。SWE-bench Verified 等其他有用测量作为额外、单独可见的证据保留。3.6 indices可审计的复合指数resources/indices.yaml 定义了 5 个指数GeneralMMLU-Pro、ReasoningGPQA Diamond HLE 1.0 text-only、CodingLiveCodeBench SciCode、AgenticTerminal-Bench 2.1以及把它们加权合成的vllm-sr/intelligence1.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.physicalmanifest.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-r1ByteDance / Seed 与 Thinking Machines Lab 的min_representatives为 2。生成器会拒绝未列入清单的物理创作者、缺失或过期的代表模型、低于最小深度的创作者。该策略不会发射进运行时快照或暴露在用户配置中——某个候选是否主流、哪些近期产品线有代表性是评审决策而非机械的发布日期排名。内容策展原则上每个创作者大约保留最近三代或代表性产品线而不是堆积次要创作者的长尾且这针对的是 Model Card不是 serving 端点。六、用户配置边界目录如何嵌入 v0.3 配置目录采纳是加法式的落在现有 v0.3 层级内配置点语义providers.models[].catalog可选选择一张规范的、内置的 Model Cardproviders.models[].name仍是请求面向的别名backend_refs[].provider选择稳定的运行时 Provider ID该 provider 的models[]在有内置映射时把规范卡片连到原生模型 IDapi_format只选择 wire 格式不从任何兼容注册条目推断 Providerrouting.modelCards有意的覆盖使用规范的catalog值作为其nameevaluation.records[]顶层自定义评测记录通过卡片身份与 Model Card 关联配套约束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 档位可能没有所需指数。这些示例不建立图像能力或实测延迟/定价。Vaultmodels/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/ 下三个 schemasource、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【免费下载链接】semantic-routerAn open, programmable decision layer for models and compute.项目地址https://gitcode.com/gh_mirrors/sem/semantic-router点击查看免费下载相关推荐oh-my-openagent BTW 侧边会话回归修复与 QA 验证实践从 Reviewer 三处缺陷到 75 项聚焦测试全绿oh my openagent BTW 侧边会话回归修复与 QA 验证实践从 Reviewer 三处缺陷到 75 项聚焦测试全绿 导读 /btw /sid后端API网关模型推理服务AI AgentvLLM Semantic Router 统一模型目录补全计划PL-0042从元数据审计到 Provider 线协议契约的工程收尾vLLM Semantic Router 统一模型目录补全计划PL 0042从元数据审计到 Provider 线协议契约的工程收尾 PL 0042 是 v后端API网关模型推理服务AI Agentsemantic-router Provider Mocker无需模型权重的确定性 Provider 协议仿真服务semantic router Provider Mocker无需模型权重的确定性 Provider 协议仿真服务 在 LLM 网关与语义路由系统中E2E后端API网关模型推理服务AI Agent上一篇PixiJS v8 渲染循环Render Loop深度指南Ticker 优先级、时间单位与自定义帧节奏下一篇CANN Runtime 实战基于 aclrtMemcpyAsync 实现 Host 到 Device 异步内存复制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考