vLLM CLI：使用 vLLM 部署大语言模型的命令行工具

vllm-cli 是一个为 vLLM 设计的命令行界面工具，它让部署和管理大语言模型变得更加简单。这个工具同时提供了交互式菜单界面和传统的命令行模式。用户可以通过它管理本地和远程模型、使用预设或自定义的配置方案、并实时监控模型服务器的运行状态。对于需要在本地快速测试不同模型，或者将模型服务集成到自动化脚本中的开发者来说，vllm-cli 提供了一个高效且易于操作的解决方案。它还内置了系统信息检查和日志查看功能，帮助用户在遇到问题时快速定位。

功能列表

• 交互模式: 提供一个功能丰富的终端界面，用户可以通过菜单导航来操作，降低了使用门槛。
• 命令行模式: 支持直接的命令行指令，方便集成到自动化脚本和工作流中。
• 模型管理: 能够自动发现并管理存储在本地的模型文件。
• 远程模型支持: 无需预先下载，可以直接从 HuggingFace Hub 加载并运行模型。
• 配置方案: 内置了多种针对不同场景（如高吞吐量、低内存）优化的配置，同时也支持用户自定义配置。
• 服务器监控: 可以实时查看 vLLM 服务器的状态，包括 GPU 使用率和日志信息。
• 系统信息: 检查并显示 GPU、内存和 CUDA 的兼容性情况。
• 日志查看器: 当服务器启动失败时，可以方便地查看完整的日志文件以排查错误。
• LoRA 支持: 允许在加载基础模型的同时，挂载一个或多个 LoRA 适配器。

使用帮助

vllm-cli 旨在简化使用 vLLM 部署大语言模型的流程。下面是详细的安装和使用步骤，帮助你快速上手。

1. 安装

先决条件
在安装之前，请确保你的系统满足以下条件：

• Python 3.11 或更高版本。
• 一块支持 CUDA 的 NVIDIA GPU。
• 已经安装了 vLLM 核心包。

从 PyPI 安装
最简单的安装方式是通过 pip 从 PyPI 官方仓库安装：

pip install vllm-cli

从源码编译安装
如果你想体验最新的功能，可以选择从 GitHub 源码编译安装。
首先，克隆项目仓库到本地：

git clone https://github.com/Chen-zexi/vllm-cli.git
cd vllm-cli

然后，安装所需的依赖库。建议在一个干净的虚拟环境里执行这些操作。

# 安装依赖
pip install -r requirements.txt
pip install hf-model-tool
# 以开发者模式安装
pip install -e .

2. 使用方法

vllm-cli 提供了两种操作模式：交互式界面和命令行指令。

交互模式

这是最适合初学者上手的方式。直接在终端输入以下命令启动：

vllm-cli

启动后，你会看到一个欢迎界面，其中包含菜单驱动的选项，引导你完成模型选择、配置和服务启动等所有步骤。

• 模型选择: 界面会列出本地发现的模型和 HuggingFace Hub 上的远程模型。你可以直接选择一个进行部署。
• 快速启动: 如果你之前已经成功运行过一次，此功能会自动加载上次的配置，实现一键启动。
• 自定义配置: 进入高级配置菜单，你可以调整包括量化方式、张量并行大小等在内的数十种 vLLM 参数。
• 服务器监控: 服务启动后，可以在监控界面看到实时的 GPU 利用率、服务器状态和日志流。

命令行模式

命令行模式适合自动化脚本和高级用户。核心命令是 serve。

基本用法
使用默认配置启动一个模型服务：

vllm-cli serve <MODEL_NAME>

其中 <MODEL_NAME> 是模型的名称，例如 Qwen/Qwen2-1.5B-Instruct。

使用预设配置
你可以使用 --profile 参数来指定一个内置的优化配置。例如，使用 high_throughput 配置来获得最大性能：

vllm-cli serve <MODEL_NAME> --profile high_throughput
```内置的配置方案包括：
- `standard`: 智能默认值的最小化配置。
- `moe_optimized`: 为 MoE（混合专家）模型优化。
- `high_throughput`: 追求最大请求吞吐量的性能配置。
- `low_memory`: 适用于内存受限环境的配置，例如启用 FP8 量化。
**传递自定义参数**
你也可以直接在命令行中传递任意 vLLM 支持的参数。例如，同时指定 AWQ 量化和张量并行数为2：
```bash
vllm-cli serve <MODEL_NAME> --quantization awq --tensor-parallel-size 2

其他常用命令

• 列出可用模型:

  vllm-cli models
  

• 显示系统信息:

  vllm-cli info
  

• 检查正在运行的服务:

  vllm-cli status
  

• 停止一个服务 (需要指定端口号):

  vllm-cli stop --port 8000
  

3. 配置文件

vllm-cli 的配置文件存储在用户目录下的 ~/.config/vllm-cli/ 中。

• config.yaml: 主配置文件。
• user_profiles.json: 用户自定义的配置方案。
• cache.json: 用于缓存模型列表和系统信息，以提高性能。

当遇到模型加载失败等问题时，工具会提供选项让你直接查看日志，这对于调试非常有用。

应用场景

1. 本地开发与模型评估
   研究人员和开发者可以在本地环境中快速部署和切换不同的大语言模型，用于算法验证、功能测试和性能评估，而无需编写复杂的服务器部署代码。
2. 自动化部署脚本
   利用其命令行模式，可以将 vllm-cli 集成到 CI/CD 流程或自动化运维脚本中。例如，当新模型训练完成后，可以自动触发一个脚本来部署该模型并进行基准测试。
3. 教学与演示
   在教学或产品演示场景中，可以利用交互式界面轻松地启动一个大语言模型服务，向他人直观地展示模型的效果，无需关心底层复杂的配置细节。
4. 轻量级应用后端
   对于一些内部工具或轻量级的应用程序，可以使用 vllm-cli 快速搭建一个稳定的大语言模型推理后端，满足小规模的调用需求。

QA

1. vllm-cli 支持哪些类型的硬件？
   目前，vllm-cli 主要支持搭载 CUDA 的 NVIDIA GPU。对 AMD GPU 的支持仍在开发路线图上。
2. 如果一个模型加载失败了，我应该怎么办？
   首先，使用工具提供的日志查看功能检查详细的错误信息，这通常会指明问题所在。其次，确认你的 GPU 型号和 vLLM 版本是否与该模型兼容。最后，可以查阅 vLLM 的官方文档，了解该模型是否需要特殊的启动参数，例如特定的量化方法或信任远程代码。
3. 这个工具是如何发现我本地的 HuggingFace 模型的？
   vllm-cli 内部集成了一个名为 hf-model-tool 的辅助工具。它会自动扫描 HuggingFace 的默认缓存目录以及用户手动配置的其他模型目录，来发现并管理本地存储的所有模型文件。
4. 我可以在没有 GPU 的情况下使用它吗？
   不可以。vllm-cli 依赖于 vLLM 引擎，而 vLLM 本身的设计是用于在 GPU 上高效运行大语言模型的，因此必须要有支持 CUDA 的 NVIDIA GPU 硬件。