安装
本指南将帮助您安装和运行 vLLM Semantic Router。Router 完全在 CPU 上运行，推理不需要 GPU。
系统要求
注意
无需 GPU - Router 使用优化的 BERT 模型在 CPU 上高效运行。
要求：
- Python: 3.10 或更高版本
- 容器运行时: Docker 或 Podman（运行 Router 容器所需）
快速开始
1. 安装 vLLM Semantic Router
# 创建虚拟环境（推荐）
python -m venv vsr
source vsr/bin/activate # Windows 上: vsr\Scripts\activate
# 从 PyPI 安装
pip install vllm-sr
验证安装：
vllm-sr --version
2. 启动 vllm-sr
vllm-sr serve
如果当前目录还没有 config.yaml，vllm-sr serve 会自动 bootstrap 一个最小工作区，并以 setup mode 启动 dashboard。
Router 将：
- 自动下载所需的 ML 模型（约 1.5GB，一次性）
- 在端口 8700 上启动 dashboard
- 激活后在端口 8888 上启动 Envoy Proxy
- 激活后启动 Semantic Router 服务
- 在端口 9190 上启用 metrics
3. 打开 Dashboard
在浏览器中打开 http://localhost:8700。
首次使用时：
- 先配置一个或多个模型。
- 选择 routing preset，或保留 single-model baseline。
- 激活生成的配置。
激活后，config.yaml 会写入当前目录，Router 会退出 setup mode。
4. 测试 Router
curl http://localhost:8888/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "MoM",
"messages": [{"role": "user", "content": "Hello!"}]
}'
5. 可选：通过 CLI 打开 Dashboard
vllm-sr dashboard
常用命令
# 查看日志
vllm-sr logs router # Router 日志
vllm-sr logs envoy # Envoy 日志
vllm-sr logs router -f # 跟踪日志
# 检查状态
vllm-sr status
# 停止 Router
vllm-sr stop
高级配置
YAML-first 工作流
如果您更倾向于直接编辑 YAML，而不是使用 dashboard setup flow：
# 在当前目录生成一个精简的高级样板
vllm-sr init
# 启动前校验它
vllm-sr validate config.yaml
vllm-sr init 是可选的。它会为 YAML-first 用户生成 advanced sample 和 .vllm-sr/router-defaults.yaml。router-defaults.yaml 保存的是高级 runtime defaults，不是首次进入 dashboard 时必须编辑的文件。
HuggingFace 设置
启动前设置环境变量：
export HF_ENDPOINT=https://huggingface.co # 或镜像：https://hf-mirror.com
export HF_TOKEN=your_token_here # 仅针对 gated models
export HF_HOME=/path/to/cache # 自定义缓存目录
vllm-sr serve
自定义选项
# 使用自定义配置文件
vllm-sr serve --config my-config.yaml
# 使用自定义 Docker 镜像
vllm-sr serve --image ghcr.io/vllm-project/semantic-router/vllm-sr:latest
# 控制镜像拉取策略
vllm-sr serve --image-pull-policy always
Kubernetes 部署
在 Kubernetes 或 OpenShift 上进行生产部署时，请使用 Kubernetes Operator：
使用 Operator 快速开始
# 克隆仓库
git clone https://github.com/vllm-project/semantic-router
cd semantic-router/deploy/operator
# 安装 CRDs 和 operator
make install
make deploy IMG=ghcr.io/vllm-project/semantic-router-operator:latest
# 部署一个 semantic router 实例
kubectl apply -f config/samples/vllm_v1alpha1_semanticrouter.yaml
优势：
- ✅ 使用 Kubernetes CRDs 进行声明式配置
- ✅ 自动检测平台（OpenShift/Kubernetes）
- ✅ 内置高可用性和扩展能力
- ✅ 集成监控和可观测性
- ✅ 生命周期管理和升级
详情请参阅 Kubernetes Operator 指南。
其他 Kubernetes 部署选项
- Istio 集成 - 服务网格部署
- AI Gateway - Gateway API 集成
- 生产环境堆栈 - 完整的生产环境设置
- Dynamo - 动态配置管理
Docker Compose
用于本地开发和测试：
- Docker Compose - 快速本地部署
下一步
获取帮助
- Issues: GitHub Issues
- 社区: 加入 vLLM Slack 中的
#semantic-router频道 - 文档: vllm-semantic-router.com