安装

本指南将帮助您安装和运行 vLLM 语义路由。路由完全在 CPU 上运行，推理不需要 GPU。

系统要求

备注

无需 GPU - 路由使用优化的 BERT 模型在 CPU 上高效运行。

要求：

• Python: 3.10 或更高版本
• Docker: 运行路由容器所需
• 可选: HuggingFace 令牌（仅针对门控模型）

快速开始

1. 安装 vLLM 语义路由

# 创建虚拟环境 (推荐)
python -m venv vsr
source vsr/bin/activate  # Windows 上: vsr\Scripts\activate

# 从 PyPI 安装
pip install vllm-sr

验证安装：

vllm-sr --version

2. 初始化配置

# 在当前目录创建 config.yaml
vllm-sr init

这将创建一个带有默认设置的 config.yaml 文件。

3. 配置您的后端

编辑生成的 config.yaml 以配置您的模型和后端端点：

providers:
  # 模型配置
  models:
    - name: "qwen/qwen3-1.8b"           # 模型名称
      endpoints:
        - name: "my_vllm"
          weight: 1
          endpoint: "localhost:8000"    # 域名或 IP:端口
          protocol: "http"              # http 或 https
      access_key: "your-token-here"     # 可选: 用于身份验证
  
  # 回退的默认模型
  default_model: "qwen/qwen3-1.8b"

配置选项：

• endpoint: 带有端口的域名或 IP 地址 (例如 localhost:8000, api.openai.com)
• protocol: http 或 https
• access_key: 可选的身份验证令牌 (Bearer token)
• weight: 负载均衡权重 (默认: 1)

示例：本地 vLLM

providers:
  models:
    - name: "qwen/qwen3-1.8b"
      endpoints:
        - name: "local_vllm"
          weight: 1
          endpoint: "localhost:8000"
          protocol: "http"
  default_model: "qwen/qwen3-1.8b"

示例：带有 HTTPS 的外部 API

providers:
  models:
    - name: "openai/gpt-4"
      endpoints:
        - name: "openai_api"
          weight: 1
          endpoint: "api.openai.com"
          protocol: "https"
      access_key: "sk-xxxxxx"
  default_model: "openai/gpt-4"

4. 启动路由

vllm-sr serve

路由将：

• 自动下载所需的 ML 模型 (~1.5GB, 一次性)
• 在端口 8888 上启动 Envoy 代理
• 启动语义路由服务
• 在端口 9190 上启用指标

5. 测试路由

curl http://localhost:8888/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MoM",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

常用命令

# 查看日志
vllm-sr logs router        # Router 日志
vllm-sr logs envoy         # Envoy 日志
vllm-sr logs router -f     # 跟踪日志

# 检查状态
vllm-sr status

# 停止路由
vllm-sr stop

高级配置

HuggingFace 设置

启动前设置环境变量：

export HF_ENDPOINT=https://huggingface.co  # 或镜像: https://hf-mirror.com
export HF_TOKEN=your_token_here            # 仅针对门控模型
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

下一步

• 配置指南 - 高级路由和信号配置
• API 文档 - 完整 API 参考
• 教程 - 通过示例学习

获取帮助

• Issues: GitHub Issues
• 社区: 加入 vLLM Slack 中的 #semantic-router 频道
• 文档: vllm-semantic-router.com