在 AMD Developer Cloud 上部署 vLLM Semantic Router:ROCm 后端 + 多语义通道路由实战指南
在 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 等逻辑车道,并把成本与隐私策略变成可观测、可回放、可迭代的路由策略。
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
这也解释了为什么该系统比一个简单的分类器更有表达力:一个查询不必被粗暴地归为"只是数学"或"只是代码",它可以同时是紧急的、对证据敏感的、短上下文的、中文的、并要求纠错的——而路由策略可以对这种更丰富的状态作出响应。
这套四层结构在仓库中有直接的实现证据: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_checkoverlay 只有在验证压力强、且提示语给出明确确认线索时才升级(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 生态中的演进。

