4、vLLM服务搭建：启动OpenAI兼容API服务与核心参数详解

好，咱们进入实战环节。这一章我带你亲手把vLLM服务跑起来，并且让它对外提供OpenAI兼容的API接口。说白了，就是让你能用curl或者Python的openai库，像调ChatGPT一样调你自己的模型。

我个人习惯先把服务跑通，再慢慢调参数。所以咱们先看怎么启动，再深入每个参数的意义。

4.1 启动一个最基本的API服务

假设你已经装好了vLLM，并且有一个模型文件（比如Qwen2-7B-Instruct）。启动服务的命令其实很简单：

python -m vllm.entrypoints.openai.api_server \
    --model /path/to/Qwen2-7B-Instruct \
    --port 8000 \
    --host 0.0.0.0

跑起来之后，你会看到类似这样的日志：

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

嗯，看到这个就说明服务已经就绪了。这时候你可以用curl测试一下：

curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "/path/to/Qwen2-7B-Instruct",
        "messages": [{"role": "user", "content": "你好，请介绍一下你自己"}]
    }'

返回的JSON结构和OpenAI的完全一致。这意味着你现有的LangChain代码，只需要改一下base_url就能无缝切换。

4.2 核心参数详解：别让显存成为瓶颈

启动服务只是第一步。真正让vLLM发挥威力的，是那几个关键参数。我一个个说，你一个个记。

4.2.1 --max-model-len：控制最大上下文长度

这个参数决定了模型能处理的最大token数。默认情况下，vLLM会从模型配置里读取这个值。但有时候模型配置文件写的是4096，你实际想用8192，怎么办？

python -m vllm.entrypoints.openai.api_server \
    --model /path/to/Qwen2-7B-Instruct \
    --max-model-len 8192

为什么要手动设置？我遇到过这样一个场景：模型支持32K上下文，但默认配置只开了4K。如果不手动调大，长文档处理就会直接截断，结果自然一塌糊涂。

4.2.2 --gpu-memory-utilization：显存利用率控制

这个参数我特别喜欢，因为它直接决定了你能在单卡上塞多大模型。取值范围0到1，默认是0.9。意思是vLLM最多使用90%的显存。

python -m vllm.entrypoints.openai.api_server \
    --model /path/to/Qwen2-7B-Instruct \
    --gpu-memory-utilization 0.95

为什么不是100%？因为GPU除了跑模型，还要处理CUDA kernel、中间变量等。我曾经试过设成0.99，结果跑大batch时直接OOM。后来我学乖了，稳定起见设0.9，追求极致吞吐设0.95。

参数值	适用场景	风险
0.8 - 0.85	多任务并发、显存紧张	低
0.9	通用推荐	低
0.95 - 0.98	单任务、追求最大吞吐	中高

4.2.3 --max-num-batched-tokens：批处理大小控制

这个参数控制一次推理最多处理多少token。默认是max-model-len的值。如果你显存够大，可以适当调高来提升吞吐。

python -m vllm.entrypoints.openai.api_server \
    --model /path/to/Qwen2-7B-Instruct \
    --max-num-batched-tokens 16384

为什么需要单独控制？因为有时候你的max-model-len设得很大（比如32K），但实际请求的平均长度只有2K。这时候把max-num-batched-tokens设小一点，可以塞进更多请求，提高整体吞吐。

4.2.4 --enforce-eager：关闭CUDA图优化

这个参数我建议新手先别碰。默认vLLM会使用CUDA图来加速推理，但有时候会引发奇怪的错误。如果你遇到类似“CUDA error: out of memory”但显存明明够用的情况，可以试试加上这个参数：

python -m vllm.entrypoints.openai.api_server \
    --model /path/to/Qwen2-7B-Instruct \
    --enforce-eager

代价是推理速度会下降10%-20%。但换来的是稳定性和兼容性。我在一些老显卡（比如V100）上遇到过CUDA图编译失败的问题，加上--enforce-eager就解决了。

4.3 知识体系总览

下面这张图帮你理清vLLM服务搭建的核心逻辑：

4.4 实战建议：先跑通，再优化

我给你的建议是：

1. 第一次启动：只用--model和--port，其他参数全默认。先确保服务能跑起来。
2. 遇到OOM：降低--gpu-memory-utilization到0.8，或者减小--max-model-len。
3. 追求吞吐：调高--max-num-batched-tokens，同时适当提高--gpu-memory-utilization。
4. 遇到奇怪错误：试试--enforce-eager，虽然慢一点但稳定。

好了，这一章的内容就到这里。你按照上面的步骤把服务跑起来，下一章咱们就可以用LangChain去调用它了。

---