安装

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

系统要求

注意

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

环境要求

• Python：3.10 或更高版本
• Docker：运行路由器容器所需

快速开始

1. 安装 vLLM 语义路由

# Create a virtual environment (recommended)
python -m venv vsr
source vsr/bin/activate  # On Windows: vsr\Scripts\activate

# Install from PyPI
pip install vllm-sr

验证安装

vllm-sr --version

2. 初始化配置

# Create config.yaml in current directory
vllm-sr init

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

3. 配置您的后端

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

providers:
  # Model configuration
  models:
    - name: "qwen/qwen3-1.8b"           # Model name
      endpoints:
        - name: "my_vllm"
          weight: 1
          endpoint: "localhost:8000"    # Domain or IP:port
          protocol: "http"              # http or https
      access_key: "your-token-here"     # Optional: for authentication

  # Default model for fallback
  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 端口启用指标监控 (Metrics)

5. 启动仪表板

vllm-sr dashboard

6. 测试路由器

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

常用命令

# View logs
vllm-sr logs router        # Router logs
vllm-sr logs envoy         # Envoy logs
vllm-sr logs router -f     # Follow logs

# Check status
vllm-sr status

# Stop the router
vllm-sr stop

高级配置

HuggingFace 设置

启动前设置环境变量

export HF_ENDPOINT=https://hugging-face.cn  # Or mirror: https://hf-mirror.com
export HF_TOKEN=your_token_here            # Only for gated models
export HF_HOME=/path/to/cache              # Custom cache directory

vllm-sr serve

自定义选项

# Use custom config file
vllm-sr serve --config my-config.yaml

# Use custom Docker image
vllm-sr serve --image ghcr.io/vllm-project/semantic-router/vllm-sr:latest

# Control image pull policy
vllm-sr serve --image-pull-policy always

后续步骤

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

获取帮助

• 问题反馈：GitHub Issues
• 社区：加入 vLLM Slack 中的 #semantic-router 频道
• 文档：vllm-semantic-router.com