vLLM CLI：高效管理大语言模型服务的命令行工具

如果你经常需要部署、管理大语言模型，可能会遇到这些问题：不知道如何快速启动模型服务、多模型切换时配置繁琐、不清楚服务器运行状态……今天要介绍的vLLM CLI，就是为解决这些问题而生的工具。它基于vLLM框架，提供了交互式和命令行两种使用模式，能帮你轻松搞定模型服务的部署、监控和管理。

什么是vLLM CLI？

vLLM CLI是一款专为大语言模型服务设计的命令行工具，核心功能是让开发者通过简单操作就能启动、管理vLLM服务器。无论你是想在终端里通过菜单直观操作，还是用命令行脚本实现自动化部署，它都能满足需求。

简单来说，它就像一个“大语言模型服务管家”——能自动发现本地模型、支持直接加载HuggingFace Hub的远程模型、保存常用配置作为“ profiles ”、实时监控服务器状态，甚至能在启动失败时帮你查看日志排查问题。

vLLM CLI有哪些核心功能？

如果你正在考虑是否要用它，先看看这些功能是否符合你的需求：

1. 两种使用模式，兼顾灵活与效率

• 交互式模式：打开后会显示菜单界面，通过键盘导航就能完成模型选择、配置调整、启动服务等操作，适合新手或需要可视化操作的场景。
• 命令行模式：直接输入命令就能完成任务，比如vllm-cli serve 模型名一键启动服务，适合写脚本自动化部署，或熟悉命令行的用户。

2. 轻松管理模型，本地远程都能⽤

• 自动扫描本地模型：会帮你找到电脑里已下载的模型，包括HuggingFace缓存目录和你自己配置的文件夹。
• 直接用远程模型：不需要提前下载，输入HuggingFace Hub的模型名，就能直接加载使用。
• 支持LoRA适配器：可以选择一个基础模型，再搭配多个LoRA适配器启动服务，灵活调整模型效果（如图1）。

3. 配置文件帮你省时间

内置了4种常用配置文件（profiles），也支持自定义：

• 标准模式（standard）：默认配置，适合大多数模型和硬件。
• MoE优化模式（moe_optimized）：针对混合专家模型（如Qwen）开启专家并行，提升效率。
• 高吞吐量模式（high_throughput）：最大化请求处理能力，适合需要高并发的场景。
• 低内存模式（low_memory）：通过FP8量化等设置减少内存占用，适合显存较小的设备。

你也可以保存自己的常用配置，下次直接调用，不用重复调整参数。

4. 实时监控服务器状态

启动服务后，能看到实时的GPU利用率、服务器状态和日志流（如图2），不用再手动查进程、看日志文件。

5. 系统信息一键查看

想知道自己的设备能不能跑某个模型？输入vllm-cli info，就能看到GPU型号、显存、CUDA版本、支持的量化方式等信息（如图3），帮你判断模型兼容性。

6. 贴心的错误处理

如果服务器启动失败，它会自动提示查看日志，并提供日志查看选项（如图4），不用你手动找日志文件位置。

v0.2.2版本有什么新功能？

最新的v0.2.2版本主要更新了这些内容，值得关注：

• 支持模型清单（models_manifest.json）：可以用JSON文件自定义模型映射，更灵活地管理本地模型。
• 新增自定义模型部署指南：详细说明如何从自定义目录加载模型，新手也能看懂。
• 修复bug：解决了从自定义目录加载模型时的问题，优化了界面显示。

如何安装vLLM CLI？

安装前，先确认你的环境符合要求：

• 操作系统：Linux（目前仅支持Linux）
• Python版本：3.11及以上
• 硬件：推荐带CUDA支持的NVIDIA GPU（暂时不支持AMD GPU，后续可能会增加）
• 已安装vLLM和PyTorch（需带CUDA支持）

方法1：从PyPI安装（推荐）

打开终端，输入以下命令：

pip install vllm-cli

方法2：从源码构建（适合开发者）

如果想体验最新代码，可按以下步骤操作：

1. 克隆仓库：

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

2. 激活已安装vLLM的环境（重要，避免依赖冲突）。
3. 安装依赖：

pip install -r requirements.txt
pip install hf-model-tool

4. 以开发模式安装（修改代码后无需重新安装）：

pip install -e .

使用前需要知道的重要信息

模型兼容性问题

不同模型、硬件、vLLM版本可能会有兼容性问题，遇到启动失败时不用慌：

1. 先看服务器日志：vLLM会在日志里详细说明错误原因，比如缺依赖、参数不兼容等。
2. 查vLLM官方文档：访问https://docs.vllm.ai/，查看模型的具体要求。
3. 注意模型需求：有些模型需要特定参数（如 quantization 方式）才能运行。

和hf-model-tool的关系

vLLM CLI用了hf-model-tool来管理本地模型，这是一个专门的模型管理工具，能帮你：

• 扫描HuggingFace缓存和自定义目录里的模型。
• 显示模型大小、类型、量化方式等信息。
• 和vLLM CLI共享配置：在hf-model-tool里设置的模型目录，vLLM CLI能直接识别，反之亦然。

如果需要管理模型，可以直接安装并使用它：

pip install --upgrade hf-model-tool  # 已包含在vLLM CLI中，可升级
hf-model-tool  # 启动模型管理工具

如何使用vLLM CLI？

1. 交互式模式：菜单导航，直观操作

输入以下命令启动交互式模式：

vllm-cli

启动后会看到欢迎界面，显示GPU状态和系统概览（如图5），然后可以通过键盘方向键导航菜单，完成各种操作。

常用操作流程：

• 选择模型：在菜单中进入“模型选择”，能看到本地模型和“HuggingFace Hub远程加载”选项（如图6），选一个即可。
• 配置服务：可以用内置配置文件，也能自定义参数（如量化方式、并行数等，如图7）。
• 快速启动：如果之前成功启动过服务，会自动保存配置，下次可以直接“快速启动”（如图8）。
• 监控服务：启动后能实时查看GPU利用率、日志等信息。

2. 命令行模式：适合脚本和自动化

直接输入命令完成操作，常用命令如下：

配置文件在哪里？如何自定义？

vLLM CLI的配置文件都存在用户目录下，路径是：

• 主配置：~/.config/vllm-cli/config.yaml
• 用户配置文件：~/.config/vllm-cli/user_profiles.json
• 缓存：~/.config/vllm-cli/cache.json

内置配置文件详解

4种内置配置文件的参数和适用场景如下：

如果这些配置不满足需求，可以在交互式模式的“自定义配置”中调整参数，或直接修改user_profiles.json添加自己的配置文件。

常见问题解答（FAQ）

1. 安装时提示“找不到vllm”怎么办？

vLLM CLI依赖vLLM，需要先安装vLLM。建议用以下命令安装带CUDA支持的vLLM：

pip install vllm[cu118]  # 根据你的CUDA版本选择，如cu121

2. 启动服务后，客户端连接不上怎么办？

先检查服务器是否真的启动：用vllm-cli status查看活跃服务器。如果没启动，查看日志（交互式模式会提示）；如果已启动，检查端口是否被占用，或防火墙是否阻止了连接。

3. 可以同时启动多个服务器吗？

可以，但需要指定不同的端口（默认8000），比如：

vllm-cli serve 模型1 --port 8000
vllm-cli serve 模型2 --port 8001

4. 如何添加自定义模型目录？

有两种方法：

• 在交互式模式中进入“模型目录管理”（如图9），添加目录。
• 用hf-model-tool添加：启动hf-model-tool，在设置中添加目录，vLLM CLI会自动识别。

5. 支持CPU运行吗？

vLLM主要优化GPU运行，虽然理论上可以用CPU，但性能会很差，不推荐。vLLM CLI也主要针对GPU环境设计。

6. 模型列表里看不到我的本地模型怎么办？

可能是模型目录没被扫描到。检查：

• 模型是否在HuggingFace默认缓存目录（通常是~/.cache/huggingface/hub）。
• 是否添加了自定义目录（参考问题4）。
• 模型格式是否正确（需符合HuggingFace格式）。

未来会支持哪些功能？

目前开发团队计划添加这些功能：

• AMD GPU支持（基于ROCm），让没有NVIDIA GPU的用户也能使用。
• 支持更多本地模型格式，包括Oracle Cloud Infrastructure Registry、Ollama等格式。

如果你有其他需求，可以在项目GitHub仓库提交issue或PR参与贡献。

总结

vLLM CLI是一款能帮你简化大语言模型服务管理的工具，无论是新手想通过界面快速启动模型，还是开发者需要自动化部署，它都能提供便利。通过内置的配置文件、模型管理和监控功能，能减少重复操作，让你更专注于模型本身的应用。

如果你经常和大语言模型打交道，不妨试试vLLM CLI，可能会节省不少时间。安装方法和基础使用都很简单，按照文中的步骤操作，很快就能上手。