vllm-deploy-simple

vLLM 简易部署

一项可快速安装 vLLM、启动服务并验证 OpenAI 兼容 API 的简单技能。

此技能的功能

此技能提供简化的工作流，用于：

• 检测硬件后端（NVIDIA CUDA、AMD ROCm、Google TPU 或 CPU）
• 安装支持相应后端的 vLLM
• 使用可配置的模型和端口启动 vLLM 服务
• 测试 OpenAI 兼容 API 端点
• 验证部署是否正常运行
• 支持虚拟环境隔离

前提条件

• Python 3.10+
• GPU（NVIDIA CUDA、AMD ROCm）（推荐），或 TPU 或 CPU
• pip 或 uv 包管理器
• curl（用于 API 测试）
• 虚拟环境（可选，但推荐）

用法

创建虚拟环境

如果用户未指定虚拟环境路径，或要求在当前环境中部署，请在当前文件夹中使用 uv 和 Python 3.12 创建虚拟环境。如果未找到 uv，请在此路径下创建一个文件夹，并使用 Python 创建虚拟环境。

运行完整工作流（推荐）

如果用户未指定虚拟环境路径、模型或端口，请使用默认选项：

# Default deployment options (--venv "." --model "Qwen/Qwen2.5-1.5B-Instruct" --port 8000 --gpu_memory_utilization 0.8)
scripts/quickstart.sh

或使用自定义选项：

# Use custom virtual environment
scripts/quickstart.sh --venv /path/to/venv

# Use custom model and port
scripts/quickstart.sh --model "Qwen/Qwen2.5-1.5B-Instruct" --port 8000

# Use custom GPU memory utilization
scripts/quickstart.sh --gpu_memory_utilization 0.6

# Combine all options
scripts/quickstart.sh --venv /path/to/venv --model "Qwen/Qwen2.5-1.5B-Instruct" --port 8000 --gpu_memory_utilization 0.8

此操作将：

1. 激活虚拟环境（如已指定）
2. 检测硬件后端（CUDA/ROCm/TPU/CPU）
3. 安装支持相应后端的 vLLM
4. 在后台启动 vLLM 服务
5. 等待服务就绪
6. 使用示例请求测试 API
7. 显示服务状态

运行单条命令（用于逐步操作或故障排查）

安装 vLLM：

scripts/quickstart.sh install
# Or with virtual environment
scripts/quickstart.sh install --venv /path/to/venv

启动服务：

scripts/quickstart.sh start
# Or with custom options
scripts/quickstart.sh start --venv /path/to/venv --model "Qwen/Qwen2.5-1.5B-Instruct" --port 8000 --gpu_memory_utilization 0.8

测试 API：

scripts/quickstart.sh test
# Or with custom port
scripts/quickstart.sh test --port 8000

停止服务：

scripts/quickstart.sh stop
# Or with virtual environment
scripts/quickstart.sh stop --venv /path/to/venv

检查服务状态：

scripts/quickstart.sh status

重启服务：

scripts/quickstart.sh restart
# Or with custom options
scripts/quickstart.sh restart --venv /path/to/venv --port 8000 --gpu_memory_utilization 0.8

配置

此脚本支持以下命令行选项：

scripts/quickstart.sh [command] [OPTIONS]

Commands:
  install  - Install vLLM and dependencies
  start    - Start the vLLM server
  stop     - Stop the vLLM server
  test     - Test the OpenAI-compatible API
  status   - Show server status
  restart  - Restart the server
  all      - Run complete workflow (default)

Options:
  --model MODEL                 Model to use (default: Qwen/Qwen2.5-1.5B-Instruct)
  --port PORT                   Port to run server on (default: 8000)
  --venv VENV_PATH              Virtual environment path (default: .)
  --gpu_memory_utilization VRAM GPU memory utilization (default: 0.8)

硬件后端检测

此脚本会自动检测硬件并安装相应版本的 vLLM：

• NVIDIA CUDA：通过 nvidia-smi 命令检测
• AMD ROCm：通过 /dev/kfd 和 /dev/dri 设备检测
• Google TPU：通过 TPU_NAME 环境变量或 gcloud 命令检测
• CPU：未检测到 GPU/TPU 时的回退选项

对于 Google TPU，此脚本会安装 vllm-tpu，而不是标准的 vllm 包。

API 测试

测试脚本会发送简单的聊天补全请求：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-1.5B-Instruct",
    "messages": [{"role": "user", "content": "Say hello!"}],
    "max_tokens": 50
  }'

故障排查

未找到虚拟环境：

• 确保 --venv 提供的路径存在，且为有效的虚拟环境
• 检查激活脚本是否存在（Linux/macOS 上为 bin/activate，Windows 上为 Scripts/activate）
• 检查并安装 uv，然后使用 uv 创建新的虚拟环境：uv venv /path/to/venv（推荐）；或使用 pip：python3 -m venv /path/to/venv

服务无法启动：

• 检查端口是否已被占用：lsof -i :8000
• 确认 GPU 是否可用：nvidia-smi（适用于 NVIDIA）或 rocm-smi（适用于 AMD）
• 检查 vLLM 安装情况：python -c "import vllm; print(vllm.__version__)"
• 查看 $VENV_PATH/tmp/vllm-server.log 中的服务日志

API 返回错误：

• 等待几秒，让模型完成加载
• 查看服务日志：cat $VENV_PATH/tmp/vllm-server.log
• 确认服务正在运行：scripts/quickstart.sh status

内存不足：

• 使用更小的模型（例如 Qwen2.5-0.5B-Instruct）
• 调低 --gpu-memory-utilization 参数
• 关闭其他占用大量 GPU 资源的应用程序

检测到错误的后端：

• 对于 NVIDIA：确保 nvidia-smi 位于 PATH 中
• 对于 AMD：检查 ROCm 驱动是否已正确安装
• 对于 TPU：设置 TPU_NAME 环境变量或安装 gcloud

说明

• 服务在后台运行，日志写入 $VENV_PATH/tmp/vllm-server.log
• PID 存储在 $VENV_PATH/tmp/vllm-server.pid 中，便于管理
• 首次运行时会下载模型（Qwen2.5-1.5B-Instruct 约为 3GB）
• 后续运行将使用缓存的模型
• 脚本会自动检测并使用 uv（如果可用），否则回退到 pip
• 虚拟环境支持可将其与系统 Python 包隔离
• 参数可以按任意顺序指定（例如，scripts/quickstart.sh --port 8080 start --venv /path/to/venv）