配置工作流

所有受支持的工作流都生成或消费同一份 canonical 配置。为部署选择一个主要事实来源，并用其他界面检查或校验它，而不是独立覆盖它。

CLI 和 YAML

当配置属于源代码控制或现有部署流水线时，使用 YAML：

vllm-sr config init --output config.yaml
vllm-sr config validate --config config.yaml
vllm-sr serve --config config.yaml

config init 写入打包的最小 canonical 模板，并且除非显式指定 --force，否则拒绝替换现有文件。当 Router 已经在运行时，从 vllm-sr config get 开始，以便保留不相关的活动设置。在 providers.models 中声明物理模型，并在适用决策的 modelRefs 中引用其名称。命名配方的决策位于 recipes[].routing.decisions；可复用的内置配方在发布入口点时接收模型分配。可选模型元数据统一保留在顶层 routing.modelCards，并根据所选算法或能力补充上下文限制、LoRA 适配器等必需信息。

本地运行时在运行时拥有的状态中派生栈专用服务地址，而不会重写源文件。同一运行时和栈的并发 serve 和 stop 操作会串行化；在活动生命周期操作完成后重试。

控制面板

空的本地工作区会以设置模式启动控制面板。用它绑定模型端点、选择基线策略、预览结果，并激活完整配置；仍在等待的 vllm-sr serve 随后用这份配置启动 Router。

激活后，从 Build → Routing → Models 连接物理 Chat 后端。Mixture-of-Models 有三个 tab：

• Models 发布和管理公开模型入口；
• Recipes 管理入口选择的策略；
• Probes 检查配方场景，并支持生成或仅路由校验。

Build → System One 单独提供 Decision Models、Decision Playground 和 Decision Monitoring，用于管理判断模型部署、测试类型化问题及查看运行时观测。

将 provider 生成与路由评估分开验证。即使所选后端无法生成，探针也可以选择预期路由。

可视化 DSL 编辑器拥有路由语义。它在替换其路由表面时保留 listeners、providers、全局设置和设置状态。多配方生命周期变更从 Mixture-of-Models 或管理 API 管理，以免可视化编辑悄悄丢弃另一个配方。

Helm

直接 Helm 部署将完整的 canonical 文档放在 configOverride 下。这会在 chart 应用显式 Kubernetes 集成重写之前，将 chart 的示例配置作为一份文档替换；它不会将示例模型或决策合并到你的策略中。将 canonical 文档编写并校验为 config.yaml，然后将该文档放在 Helm values 文件的 configOverride 下。

configOverride:
  version: v0.3
  listeners:
    - name: http-8899
      address: 0.0.0.0
      port: 8899
      timeout: 300s
  providers:
    defaults:
      model: local/general
    models:
      - name: local/general
        provider_model_id: my-served-model
        backend_refs:
          - name: primary
            endpoint: model-server.default.svc.cluster.local:8000
            protocol: http
            provider: vllm
            weight: 100
  routing:
    strategy: priority
    modelCards:
      - name: local/general
        modality: text
        capabilities: [chat]
    decisions:
      - name: default-route
        description: Route requests to the configured model.
        priority: 1
        rules:
          operator: AND
          conditions: []
        modelRefs:
          - model: local/general
            use_reasoning: false
  global:
    services:
      response_api:
        enabled: false
        store_backend: memory

vllm-sr config validate --config config.yaml

helm upgrade --install semantic-router \
  oci://ghcr.io/vllm-project/charts/semantic-router \
  -f values.yaml

vllm-sr serve --target kubernetes --config config.yaml 将所选文档作为原子覆盖传递，因此 chart 示例路由不能合并到其中。该命令拒绝空文档或仅包含 setup 的文档，并且不会注入本地 Docker 服务地址或知识库路径。先运行 vllm-sr config validate，以便 schema 和引用错误在部署前失败。

在 Kubernetes 上，--platform rocm 和 --platform cuda 会选择 ROCm 或 CUDA 版 Router 镜像（除非显式指定了镜像），并申请一个 amd.com/gpu 或 nvidia.com/gpu，因此 Router Pod 会被调度到其设备插件提供该 GPU 的节点上。节点选择器、容忍度、其他资源以及设备插件本身仍通过 Helm values 或 Operator 配置。

chart 将控制面板作为自己的 Deployment 和 Service 运行，并且该 Deployment 默认禁用。Router Service 仅承载 gRPC 和 HTTP API 端口，因此仅在启用控制面板后，端口 8700 才会出现在集群中。

helm upgrade --install semantic-router \
  oci://ghcr.io/vllm-project/charts/semantic-router \
  -f values.yaml --set dashboard.enabled=true

kubectl --namespace vllm-semantic-router-system port-forward \
  svc/semantic-router-dashboard 8700:8700

Operator

Operator 从两个 Kubernetes 原生输入渲染 canonical 配置：

• spec.vllmEndpoints 发现模型服务，并创建 provider 绑定和 model card；以及
• spec.config.routing 接受 canonical 路由对象。

其他 spec.config 字段是用于响应缓存、分类器、工具、可观测性、推理家族和相关共享设置的类型化 Operator 适配器。Operator 将它们翻译为 canonical provider 和 global 节。

spec:
  vllmEndpoints:
    - name: local-backend
      model: local/model
      backend:
        type: service
        service:
          name: model-server
          port: 8000
  config:
    routing:
      strategy: priority

不要将任意 providers 或 global 键直接复制到 spec.config 下；它们不是 CRD 字段。参见 Kubernetes Operator 和 SemanticRouter CRD 参考。

路由 DSL

DSL 是用于 model card、信号、投影、决策、算法、插件、入口点和配方的聚焦编写表面。Providers、listeners、凭据和全局服务仍由 YAML 拥有。

当路由策略受益于紧凑、可复核的表示时，使用 DSL。将 canonical YAML 作为完整的部署产物。

避免分割所有权

• 不要将生成的运行时配置当作源文档来编辑。
• 不要让 GitOps 和交互式控制面板会话在没有显式交接的情况下写入同一部署。
• 不要将密钥放入 DSL、ConfigMap 或已提交的 YAML。
• 不要假设已评估的路由能证明后端就绪；请验证生成。
• 在将完整变更应用到实时栈之前，先预览并校验。

管理端点和并发契约见管理 API 参考。