在 AMD Developer Cloud 上部署 vLLM Semantic Router:ROCm 后端 + 多语义通道路由实战指南

原创2026-10-11 13:28:411,957 阅读
文章标签:后端API网关模型推理服务AI Agent

在 AMD Developer Cloud 上部署 vLLM Semantic Router:ROCm 后端 + 多语义通道路由实战指南

vLLM Semantic Router(简称 VSR)是为模型与计算提供的可编程决策层。本篇技术指南以 AMD Developer Cloud 为真实运行环境,完整演示如何在 ROCm GPU 实例上启动 Qwen 后端、安装 vLLM Semantic Router、导入仓库内置的 Balanced Routing 参考配置,并借助 Playground、Insights 与脑拓扑视图完成端到端验证。读完本文,你将掌握一套"单后端、多语义通道"的路由部署方法:一次启动一个 ROCm vLLM 服务,却能让不同难度的请求分别落到 SIMPLE、MEDIUM、COMPLEX、REASONING、PREMIUM 等逻辑车道,并把成本与隐私策略变成可观测、可回放、可迭代的路由策略。

AMD Developer Cloud 与 vLLM Semantic Router 部署总览

vLLM Semantic Router 是什么

vLLM Semantic Router 是 LLM 之上的系统智能层。它位于模型端点之前,在生成开始前读取每一个请求,抽取语义信号,然后决定接下来应该发生什么。因此它不只是省钱的"路由器"——它同时也是安全、隐私与策略的控制层。同一个路由系统,既可以简单地把普通任务导向便宜的车道,也可以识别敏感流量、把私有请求留在本地基础设施上、挂载面向安全的插件链,并为真正需要深度推理的任务保留更强模型。

对 AMD 部署而言,这一点尤其有意义:智能多模型路由、隐私优先的企业 AI、本地优先的个人 AI可以在同一套架构中共存。实践中,一个系统就能自主决定何时优化成本、何时优先安全或隐私、何时把个人或敏感工作流留在用户附近,而不是把每一个查询都当作同质流量处理。

注意:在本参考配置中,google/gemini-3.1-pro、openai/gpt5.4、anthropic/claude-opus-4.6 等别名都是逻辑路由通道(tier),它们背后全部指向同一个 ROCm Qwen 部署,并不是对第三方厂商 API 的出站调用。

信号驱动架构:四层工作方式

理解 vLLM Semantic Router 最直接的方式是把它看作四层架构:

  • Signals(信号):从每个请求中抽取的原始观测。本仓库的 AMD 配置使用了 keyword、embedding、structure、fact_check、user_feedback、reask、language、domain、context、complexity 等信号类型。
  • Projections(投影):协调层。把原始信号证据加工为可复用的路由输出,如 balance_simple、balance_complex、balance_reasoning、verification_required、urgency_elevated。
  • Decisions(决策):策略层。组合信号与投影输出,形成具名路由结果,如 medium_code_general、reasoning_deep、premium_legal。
  • Models(模型):目标车道。决策通过 modelRefs 指向逻辑模型或别名;端点接线、定价与后端引用则存放在 provider 模型目录中。

运行时的完整链路如下:

User Request -> Signals -> Projections -> Decisions -> Model Alias -> Backend Response

这也解释了为什么该系统比一个简单的分类器更有表达力:一个查询不必被粗暴地归为"只是数学"或"只是代码",它可以同时是紧急的、对证据敏感的、短上下文的、中文的、并要求纠错的——而路由策略可以对这种更丰富的状态作出响应。

vLLM Semantic Router 信号驱动架构总览

这套四层结构在仓库中有直接的实现证据:config/recipes/balance/config.yaml 中 routing.signals 定义了 14 个 domain 信号、23 个 keyword 信号、17 个 embedding 信号、6 个 complexity 信号、3 个 context 上下文信号、7 个 structure 结构信号,以及 fact_check、user_feedback、reask、language、conversation 等信号;routing.projections 定义了 5 个阈值带投影、2 个 softmax 分区投影和 5 个加权求和分数;routing.decisions 则按优先级从高到低排布了 15 条决策。同目录下的 recipe.dsl 是同一策略的 DSL 等价表达,可直接对照阅读。

本次将部署什么

从高层看,本次部署包含以下组件:

  • 一个运行 Qwen/Qwen3.5-122B-A10B-FP8 的 ROCm vLLM 后端
  • 一个位于该后端前面的 vLLM Semantic Router 实例
  • 一个来自 config/recipes/balance/config.yaml 的参考路由配置(内置 Balanced Routing recipe,对外暴露 vllm-sr/auto 入口)
  • 一个用于 onboarding、replay 检查、Playground 测试与 Insights 分析的 Dashboard

参考别名布局如下:

别名 逻辑通道 用途
qwen/qwen3.5-rocm SIMPLE 通道 自托管默认,快速问答、通用回落、创意起草
google/gemini-2.5-flash-lite 低成本 MEDIUM 通道 中等难度的表达型任务、验证型解释
google/gemini-3.1-pro COMPLEX 通道 复杂技术或架构密集型任务、STEM 综合
openai/gpt5.4 REASONING 通道 高推理升级、形式化数学证明
anthropic/claude-opus-4.6 PREMIUM 通道 高价值法律与合规分析
local/omni 视觉通道 携带图片的请求专用视觉语言模型

配置中的定价是故意夸大的,目的是让 Insights 能直观展示通道差异与成本节省。它是一个演示友好的路由配置,不是厂商账单的镜像。这一点在 config/recipes/balance/config.yaml 的 providers.models 段有明确体现:例如 qwen/qwen3.5-rocm 的 prompt_per_1m、completion_per_1m、cached_input_per_1m 均为 0(免费自托管),而 anthropic/claude-opus-4.6 分别为 1.8、7.2、0.45 美元/百万 token;同时 evaluation.records 段为每个模型记录了 vllm-sr/operator-rating@1.0.0 基准评分(0.58 到 0.94 不等),用于支持决策在质量与成本之间的权衡。

为什么这对 AMD 意义重大

这套架构为 AMD 创造了一个独特的机会:AMD 硬件不再只是"又一个加速器目标",而是在前面叠加 Semantic Router 后,可以承担起系统智能控制面的角色。这一思路覆盖 AMD 数据中心 GPU 全产品线,包括 MI300X、MI325X、MI355X 及后续型号。

1. 在 AMD 上实现智能路由

最直接的机遇是智能路由:AMD Developer Cloud 上的单个 ROCm 后端可以作为多个逻辑通道的物理执行层。这意味着团队可以在不先搭建大型多后端集群的前提下,原型化 Mixture-of-Models 体验、成本感知路由、基于 replay 的调试以及分层产品行为。在 AMD 参考配置中,最便宜、中等、复杂、推理与高端通道全部解析到不同模型别名上,但路由仍能给出差异化行为——因为策略活在 signals、projections、decisions 中,而不只是取决于你运行了多少个容器。

2. 隐私路由与本地优先治理

第二个机遇是隐私路由:让 PII、私有代码、内部文档与可疑提示留在本地通道,仅在策略允许时才把明确无敏感性的推理任务升级出去。这一模式对 AMD 尤其有意义,因为它支持"本地优先"的部署叙事:把敏感流量留在你掌控的基础设施上,审计每一个决策,让云端升级成为一种受控例外而非默认行为。对企业而言,AMD 支撑的部署可以成为内部 copilot、受监管工作负载或混合私有 AI 系统的可信默认通道;对开发者而言,隐私不再只是托管选择,而是一套路由策略。

3. 个人 AI 与本地个人代理

第三个机遇是个人 AI:在 AMD AI MAX+ 上部署个人模型,按需连接外部模型。当路由、隐私与推理都以策略形式表达后,AMD 托管的栈就能支撑更个性化、更可控的助手。个人 AI 系统可以把日常任务、带记忆的追问和私有上下文留在本地通道,仅在明确许可时才升级特例。这使得 AMD 不仅对企业基础设施有吸引力,对自托管助手、家庭实验室 AI 与本地优先的个人工作流同样成立。关键在于,Semantic Router 让系统能够区分"留在本地"、"便宜且常规"与"需要更深推理",而不是把所有个人 AI 流量当作一种无差别负载。

快速上手:前置条件

开始之前,请确认 AMD Developer Cloud 实例已就绪:

  • 一个支持 ROCm 的 AMD GPU 实例
  • Docker 已安装并运行
  • 可访问 /dev/kfd 与 /dev/dri
  • 一个持久的 Hugging Face 缓存路径(如果希望避免重复下载模型)

能 SSH 进机器之后,即可启动后端。

步骤 1:创建共享 Docker 网络

创建参考部署使用的网络:

sudo docker network create vllm-sr-network 2>/dev/null || true

这一步保持后端命名与参考配置一致——配置期望 vLLM 服务位于 vllm:8000。在 config/recipes/balance/config.yaml 中可以看到,qwen/qwen3.5-rocm、google/gemini-2.5-flash-lite、google/gemini-3.1-pro、openai/gpt5.4、anthropic/claude-opus-4.6 五个模型的 backend_refs 都指向 vllm:8000,而 local/omni 指向 vllm-omni:8000,这与 docker 服务命名一一对应。

步骤 2:启动 AMD ROCm vLLM 后端

在 AMD Developer Cloud 实例上执行以下命令:

sudo docker run -d \
  --name vllm \
  --network=vllm-sr-network \
  --restart unless-stopped \
  -p "${VLLM_PORT_122B:-8090}:8000" \
  -v "${VLLM_HF_CACHE:-/mnt/data/huggingface-cache}:/root/.cache/huggingface" \
  --device=/dev/kfd \
  --device=/dev/dri \
  --group-add=video \
  --ipc=host \
  --cap-add=SYS_PTRACE \
  --security-opt seccomp=unconfined \
  --shm-size 32G \
  -v /data:/data \
  -v "$HOME:/myhome" \
  -w /myhome \
  -e VLLM_ROCM_USE_AITER=1 \
  --entrypoint python3 \
  vllm/vllm-openai-rocm:latest \
  -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen3.5-122B-A10B-FP8 \
    --host 0.0.0.0 \
    --port 8000 \
    --enable-auto-tool-choice \
    --tool-call-parser qwen3_coder \
    --served-model-name qwen/qwen3.5-rocm google/gemini-2.5-flash-lite google/gemini-3.1-pro openai/gpt5.4 anthropic/claude-opus-4.6 \
    --trust-remote-code \
    --reasoning-parser qwen3 \
    --max-model-len 262144 \
    --language-model-only \
    --max-num-seqs 128 \
    --kv-cache-dtype fp8 \
    --gpu-memory-utilization 0.85

这是整个部署的核心。后端仍是同一个 Qwen 模型,但通过 --served-model-name 一次暴露了多个服务名别名,供路由器按语义目标寻址。各关键参数的作用如下:

参数 含义与取值建议
--device=/dev/kfd --device=/dev/dri --group-add=video ROCm 容器必需的 GPU 设备透传
-e VLLM_ROCM_USE_AITER=1 启用 ROCm 上的 AITER 加速后端
--kv-cache-dtype fp8 KV 缓存使用 FP8,降低显存占用
--gpu-memory-utilization 0.85 允许 vLLM 使用 85% 显存
--max-model-len 262144 256K 上下文窗口,与配置中 context_window_size: 262144 对齐
--reasoning-parser qwen3 使用 Qwen3 系列的 reasoning 解析器
--tool-call-parser qwen3_coder 启用自动工具选择与 qwen3_coder 工具调用解析
-p "${VLLM_PORT_122B:-8090}:8000" 宿主机端口默认 8090,映射容器内 8000

安装 vLLM Semantic Router

后端就绪后,安装 vLLM Semantic Router:

前置条件:Python 3.12

# 创建虚拟环境(推荐)
python3 -m venv vsr
source vsr/bin/activate
curl -fsSL https://vllm-sr.ai/install.sh | bash

安装脚本是本仓库的 install.sh,它会把 CLI 装入隔离的虚拟环境(默认 ~/.local/share/vllm-sr/venv),并在 ~/.local/bin 生成 vllm-sr 启动器。脚本支持若干实用参数:--platform auto|cpu|cuda|rocm(默认 auto,AMD 实例上可显式指定 rocm)、--runtime auto|docker|podman|skip(serve 模式默认 auto -> docker)、--channel stable|dev(默认安装最新稳定版)、--no-launch(跳过安装后自动首次启动)。Dashboard 端口由脚本中的 resolve_dashboard_port() 计算,基址为 8700(可通过 VLLM_SR_PORT_OFFSET 平移),因此路由器的 Dashboard 可通过以下地址访问:

http://<your-server-ip>:8700

打开 Dashboard 并完成 onboarding。当提示加载路由配置时(请直接跳过模型配置步骤),从仓库内导入参考 YAML,其完整内容位于 config/recipes/balance/config.yaml(本仓库根目录下同样可直接查看 config/recipes/balance/README.md、config/recipes/balance/recipe.dsl 与 config/recipes/balance/probes.yaml)。

导入后,如果在 DSL 编辑器中检查同一配置,可以看到路由面(routing surfaces)从 routing.modelCards、routing.signals、routing.projections、routing.decisions 反编译而来,而 providers 段保持 YAML 原生形式。换言之,策略的语义部分与物理连接部分(端点、定价、后端引用)是分层解耦的。

参考配置在做什么

导入的配置表达了一套完整的 AMD 路由叙事,共 15 条决策(原文档中评估为 23 个活动决策场景),覆盖:

  • simple 回退通道(simple_general、casual_chat)
  • medium 领域通道(medium_code_general、medium_explainer、medium_creative)
  • 已验证 overlay(verified_health、verified_explainer)
  • 反馈恢复通道(feedback_wrong_answer_verified、feedback_need_clarification)
  • 复杂技术通道(complex_specialist)
  • 推理升级通道(reasoning_deep、formal_math_proof)
  • 一个情绪参与的通用通道(fast_qa 等)
  • 一个 premium 法律通道(premium_legal)

每条决策都带有 priority 与 tier 字段:优先级从 omni 的 300 依次递减到 casual_chat 的 10,保证高价值、高风险的请求先被匹配,而 casual_chat 作为"绝对兜底"保证任何输入都能得到一个路由结果。几乎所有通道都挂载了 router_replay 插件,配置为 capture_request_body: true、capture_response_body: true、max_body_bytes: 4096、max_records: 100000,这也是 Insights 与 replay 能力的数据来源(详见 config/recipes/balance/config.yaml 的 routing.decisions)。

之所以说 replay 和 Insights 保持"信号原生",是因为系统没有另造一套独立的运行时维度 schema——它展示的就是路由期间真实发生的事:哪些信号命中、哪些投影输出触发、哪条决策胜出、哪个别名接收了请求。

配置中还有两条刻意保守的路径值得说明:

  • fact_check overlay 只有在验证压力强、且提示语给出明确确认线索时才升级(needs_fact_check 信号通过 verification_pressure 加权求和参与,但不会单独否决任务通道);
  • user_feedback 恢复通道要求字面的纠错或澄清信号(如 wrong_answer、correction_feedback_markers),而不是宽泛地捕获所有追问流量。

这让配置在单后端上测试路由行为时更容易推理。与之配套的 config/recipes/balance/probes.yaml 提供了可执行的评估探针:它按决策分组、覆盖每个通道的基线/改写/鲁棒性变体、中英文与多轮消息形态、负例与优先级碰撞场景,并以 min_probe_pass_rate: 100.0 作为验收门槛。

投影与信号如何协同

路由"智能"的核心藏在 routing.projections 里。以 difficulty_band 为例,它采用 threshold_bands 方法、sigmoid_distance 校准(slope=10),把 difficulty_score(一个由约 30 项输入加权求和的分数,simple_request_markers 为负权重、reasoning_request_markers 与 math_task:hard 等为正权重)切成四段:

分数区间 投影输出
< 0.18 balance_simple
0.18 ~ 0.48 balance_medium
0.48 ~ 0.82 balance_complex
>= 0.82 balance_reasoning

类似地,verification_band(slope=12,阈值 0.35)产出 verification_required,feedback_correction_band(0.34)产出 feedback_correction_verified,feedback_clarification_band(0.26)产出 feedback_clarification_overlay,urgency_band(0.24)产出 urgency_elevated。两个 softmax 分区 balance_domain_partition(14 个领域成员,temperature 0.1)与 balance_intent_partition(17 个意图成员,temperature 0.18)则把信号证据规约为互斥的领域/意图归类。这些投影输出随后作为 type: projection 条件出现在各条决策的 rules 中,与 keyword、embedding、domain、complexity、structure、context 等条件自由组合成 AND/OR/NOT 布尔表达式。

在 Playground 中验证部署

onboarding 完成后,最快验证系统的方式是 Dashboard 的 playground。尝试几个代表不同路由通道的提示词:

编码帮助

Debug this Python stack trace and suggest the most likely fix.

这条应落在便宜编码通道,由 qwen/qwen3.5-rocm 承接。在 config/recipes/balance/probes.yaml 中,medium_code_general 决策的 python_stack_trace 探针正是这条提示词,期望别名 qwen/qwen3.5-rocm。

深度推理

Prove rigorously that the square root of 2 is irrational.

这条应升级进入推理通道,映射到 openai/gpt5.4 别名。同样,formal_math_proof 决策的 irrationality_proof 探针原样复用了它。

高端法律分析

Provide a legal analysis of the indemnity clause, liability cap, and compliance obligations in this contract.

这条应命中 premium 法律通道,转发到 anthropic/claude-opus-4.6。它是 premium_legal 决策的 contract_clause_analysis 基线探针。

在 Insights 中观察路由行为

也可以在 Insights 中检查路由行为。参考配置启用了 replay,因此你能看到路由期间真实发生了什么:哪些信号匹配、哪些投影输出触发、哪条决策胜出、请求最终落在哪个别名上;同时也能看到使用更便宜通道节省了多少成本。由于配置中的定价是刻意夸大的演示值,通道间的价差与节约效果在 Insights 中一目了然。

测试脑拓扑

路由器 Dashboard 还包含一个 brain topology(脑拓扑) 视图,展示路由图的高层结构。它有助于理解策略的整体形态,以及不同决策之间如何连接。你可以直接在其中测试自己的提示词,观察它的激活路径——从信号命中、投影触发到最终决策的全链路。

设计你自己的路由 DSL

Dashboard 还内置了完整的 DSL 编辑器,可用来设计自己的路由策略。参考配置是一个很好的起点,但你完全可以在编辑器中尝试不同思路。值得一提的是,你可以在单条 route 中构造非常复杂的布尔表达式,来表达非常精确的路由策略——例如 premium_legal 决策中"法律领域或法律风险关键词"与"嵌入相似度或验证压力或法律复杂度"以及"NOT(规范主题关键词且论证请求关键词且非法律风险)"层层嵌套的 AND/OR/NOT 组合,就是 DSL 表达力的直接体现;其等价 YAML 见 config/recipes/balance/config.yaml 的 premium_legal 段。

结语

在 AMD Developer Cloud 上部署 vLLM Semantic Router,得到的不仅仅是一个可用的推理端点,而是一套紧凑的路由系统:一个或多个 ROCm 托管的后端、多个语义通道、可见的路由逻辑,以及一个让行为可理解而非黑盒的 Dashboard 体验。这正是该参考配置的价值所在:你可以从单个真实 AMD 后端出发,导入一整套路由策略,检查决策是如何做出的,然后在此基础上迭代——而无需先搭建一个大型多后端集群。对于正在探索成本感知路由、replay 驱动调试或 AMD 上 Mixture-of-Models 模式的团队来说,这是一个可复现、可落地的起点。

进一步深入可参阅:config/recipes/balance/README.md(模型角色与路由行为说明)、config/recipes/balance/config.yaml(完整运行时配置)、config/recipes/balance/recipe.dsl(DSL 表达)、config/recipes/balance/probes.yaml(可执行评估探针)、config/recipes/CONFORMANCE.md(recipe 编写与一致性评估指南)以及根目录 install.sh(安装器及其全部参数)。

一起协作:我们欢迎社区开发者和研究者共同参与在 AMD GPU 上构建系统智能的工作。任何问题、用例与反馈都可以在社区渠道中分享,共同推进路由、隐私与推理策略在 AMD 生态中的演进。

登录后查看全文
semantic-router