vLLM部署Qwen3.5-4B微调模型：Function Calling与显存优化实战

模型微调这件事，训练跑完只能算完成一半；真正让人头疼的是后半程——把微调出来的模型部署成一个能被业务系统调用的服务。系列做到Part 6，我用vllm把Qwen3.5-4B的function calling微调模型在本地跑了起来，硬件是手头这张3080Ti，12GB显存，刚好卡在"能跑但必须精细规划"的档位上。

这篇就把从"微调完的模型文件"到"可对外提供OpenAI兼容接口的服务"全过程写清楚，包括vllm部署Qwen3.5-4B的启动参数、function calling验证链路、显存边界控制，以及我在3080Ti上踩过的那些文档里不会细讲的坑。适合正好走到"微调完准备部署"这一步的开发者参考。

1. 微调模型过vllm这关，先想清楚三个前置问题

1.1 为什么部署环节几乎绕不开vllm

微调完模型，最常见的做法是直接用transformers加载权重，本地跑几个测试用例验证效果。这一步没问题，但一旦要接入业务系统，transformers的推理方式就会出现三个硬伤：不支持并发请求的连续批处理、显存里塞不下动态的KV cache、吞吐量上不去。vllm针对这三点做了专门优化——PagedAttention把KV cache分页管理，continuous batching让多个请求在GPU上交错执行，等于把GPU的每一分算力都压榨出来。实测下来，同样一张3080Ti，transformers只能串行处理请求，vllm可以并行扛住几十个并发，吞吐差异是数量级的。

有朋友问过我："我就内部用用，QPS不高，transfomers跑个API封装不行吗？"短期可以，但vllm还有另一个价值：它对OpenAI接口格式的兼容做得很完整，尤其是工具调用（function calling）这一块。微调了一个带工具调用能力的模型，最终目的就是让Agent系统通过标准API来使用它，这时候vllm的/v1/chat/completions接口可以直接对接，省掉自己写协议转换的功夫。

1.2 3080Ti的显存边界：4B模型的真实成本

3080Ti是12GB显存，这个容量放今天有点尴尬——跑7B以上模型必须量化，但跑4B模型又绰绰有余。拿Qwen3-4B这个底座来说，FP16精度权重大约8GB左右，加载后留给KV cache和推理算子的空间大概3-4GB。如果不加节制地开长上下文，这份余量很快就会耗尽。

所以在部署之前，一定要算清楚三笔账：

• 权重占用：FP16权重大约占显存8GB，如果做AWQ/GPTQ 4bit量化，可以压到3GB左右。
• KV cache占用：序列长度越长，KV cache线性增长。8k上下文对应的KV cache占用在1GB上下，32k就会超过3GB。
• CUDA graph和算子临时显存：这部分一般几百MB，但不同版本vllm差异不小。

算下来，3080Ti跑FP16的4B模型，max-model-len设在8192左右是安全的；想要更长上下文，就得走量化路线。这个决策直接决定了后面的启动参数怎么配。

1.3 微调的产物形态，决定了你走到哪一步才能部署

很多人在这一步才开始纠结：微调用的是LoRA，产出一堆adapter文件，能不能直接用vllm加载？vllm虽然支持LoRA adapter动态加载，但需要额外维护adapter列表，而且动态加载对模型目录结构有严格约束，实际使用中光排查"adapter加载失败""base model与adapter不匹配"这类问题就能耗掉半天。

我的建议很直接：部署前先把LoRA权重合回底座，得到一个完整的全量模型目录。这样vllm启动时只认一个模型路径，排查问题也简单，后续换机器、换框架、发模型包都方便。合并方法很简单，用transformers的PeftModel加载base model和adapter，然后save_pretrained保存合并后的权重。这一步放在部署前面做，后面省心十倍。

2. 环境准备：版本、镜像与硬件驱动的组合拳

2.1 版本选型：避开latest的坑

vllm迭代非常快，新版本经常引入breaking change，其中影响最大的就是function calling相关参数。早期版本用--enable-function-calling，后来改成--enable-auto-tool-choice加--tool-call-parser的组合，如果你拿着旧教程的命令去跑新版本，直接报参数错误。

我的做法是锁版本，不用latest。以当前阶段为例，选择0.7.x或0.8.x的稳定版，对应Docker镜像tag就是vllm/vllm-openai:v0.8.3这样明确的版本号。锁版本的目的不是拒绝新功能，而是保证部署行为可复现——今天部署好了，三个月后需要扩容，拉一个新机器照着一模一样的命令跑，不应该出现"上次能启动这次起不来"的情况。

另外注意Python环境，vllm对Python版本有要求，一般3.10到3.12都支持，但别用太老的3.8。如果用Docker方式部署，Python环境由镜像隔离，本机只需要装好驱动和容器运行时即可。

2.2 Docker部署的参数和目录挂载

3080Ti的Ampere架构在vllm支持列表里很成熟，不需要额外编译算子，直接用官方Docker镜像最省事。部署之前确认两件事：本机NVIDIA驱动版本要够新，并且装好了nvidia-container-toolkit。验证方式很简单：

docker run --rm --gpus all nvidia/cuda:12.4.0-base-ubuntu22.04 nvidia-smi

如果这条命令能正确输出GPU信息，说明Docker的GPU透传没问题。之后启动vllm，核心是把模型目录挂载进容器，并映射8000端口：

docker run --rm --gpus all \ -p 8000:8000 \ -v /home/zp/models/Qwen3.5-4B-FC:/models/Qwen3.5-4B-FC \ vllm/vllm-openai:v0.8.3 \ --model /models/Qwen3.5-4B-FC \ --served-model-name Qwen3.5-4B-FC \ --dtype auto \ --max-model-len 8192 \ --gpu-memory-utilization 0.92 \ --enable-auto-tool-choice \ --tool-call-parser hermes \ --trust-remote-code

这条命令有几个细节要注意：-v把宿主机的模型目录挂载到容器内，路径别搞混；--rm表示容器退出自动删除，日志会直接打到当前终端，方便调试。如果遇到PermissionError，可能是容器内用户对挂载目录没有读权限，要么调整目录权限，要么在docker run里加--user root。实战中这个权限问题出现的频率比想象中高。

2.3 启动前的一分钟自检

每次启动前，我习惯花一分钟做快速自检，能省掉后面排查的很多时间：

• 模型目录是否包含config.json、tokenizer.json、tokenizer_config.json、generation_config.json这几个关键文件。
• 目录里的权重文件是不是完整的，.safetensors.index.json指向的分片是否存在且大小与config里声明一致。
• 模型路径是否正确，Docker里尤其要确认是容器内路径而不是宿主机路径。
• 显存是否被其他进程占用，用nvidia-smi看一遍，确认没有残留的推理进程占着显存。

这套自检做完再启动，成功率会高很多。尤其是第四条，很多人部署失败不是因为配置写错，而是前一个测试进程没杀干净，显存不够导致启动中途崩溃。

3. 模型整理：部署前必做的三件事，少一件都会出幺蛾子

3.1 合并LoRA权重，静态部署比动态加载省心

训练阶段用LoRA是因为它省显存、训练快，但部署阶段情况完全不同。vllm虽然支持--enable-lora动态加载adapter，但这套机制更适合"同一个底座模型挂多个adapter做多租户"的场景。如果你只是一个微调模型对外提供服务，完全没必要引入动态加载的复杂度。

合并权重的脚本很简单，这个操作本质上就是"把增量加回原权重"：

from transformers import AutoModelForCausalLM, AutoTokenizer from peft import PeftModel base_model_path = "/home/zp/models/Qwen3-4B" adapter_path = "/home/zp/models/Qwen3-4B-lora-final" merged_path = "/home/zp/models/Qwen3.5-4B-FC" model = AutoModelForCausalLM.from_pretrained( base_model_path, torch_dtype="auto", trust_remote_code=True ) model = PeftModel.from_pretrained(model, adapter_path) model = model.merge_and_unload() tokenizer = AutoTokenizer.from_pretrained(base_model_path, trust_remote_code=True) model.save_pretrained(merged_path, safe_serialization=True) tokenizer.save_pretrained(merged_path)

合并完之后设一个独立的模型名，比如Qwen3.5-4B-FC，作为后续所有部署操作的入口。这里的safe_serialization=True很关键，它会把权重保存成safetensors格式，加载更快且更安全。

3.2 检查模型目录里的"四件套"

合并完的模型目录，先别急着上vllm。手动检查四个文件，这一步能提前暴露绝大多数启动问题。

config.json是最重要的，重点看三个字段：model_type是否被vllm支持、max_position_embeddings是否足够大、quantization_config是否存在（如果存在说明权重是量化过的，启动参数要对应调整）。tokenizer.json和tokenizer_config.json决定了分词行为，如果微调时扩展过词表，这两个文件必须是从微调后的tokenizer保存出来的。generation_config.json影响生成时的默认参数，比如pad_token_id、eos_token_id，如果这个文件缺失或字段不对，生成阶段可能产生异常输出。

检查命令很简单：

ls -lh /home/zp/models/Qwen3.5-4B-FC/ du -sh /home/zp/models/Qwen3.5-4B-FC/

权重文件加起来应该有8GB左右，如果只有几百MB，八成是只保存了adapter权重或保存不完整。这种情况下vllm启动时虽然不会立刻报错，但加载的模型实际上是不完整的，推理结果必然有问题。

3.3 chat_template：function calling的隐形开关

这一步是最容易被忽略、但影响最大的。function calling模型在推理时依赖模型内置的chat template，系统提示词、工具定义、用户消息、模型回复、工具结果，全都通过template组装成特定的对话格式。如果微调时改过chat template，但保存模型时没有正确写入tokenizer_config.json，部署后会出现一个诡异的现象：直接问普通问题一切正常，但一涉及工具调用，模型要么返回一堆奇怪的标记，要么生成的JSON格式完全不对。

检查方法很直接，在Python里加载tokenizer，查看它的chat_template：

from transformers import AutoTokenizer tok = AutoTokenizer.from_pretrained("/home/zp/models/Qwen3.5-4B-FC", trust_remote_code=True) print(tok.chat_template)

如果输出是None，说明模型没有记录chat template，vllm会退回到通用模板，工具调用几乎必然失败。解决办法是微调阶段就把template明确设置好，或者部署前手动把template写入tokenizer_config.json。我的经验是：凡是自己做过SFT的模型，这一步必须验证，不要因为基座模型自带template就想当然。

4. vllm参数逐项拆解：从demo命令到生产级配置

4.1 完整启动命令与核心参数

在第2章基础上，把启动命令再完整展开一次，所有参数背后都有一个明确理由：

docker run --rm --gpus all \ -p 8000:8000 \ -v /home/zp/models/Qwen3.5-4B-FC:/models/Qwen3.5-4B-FC \ vllm/vllm-openai:v0.8.3 \ --model /models/Qwen3.5-4B-FC \ --served-model-name Qwen3.5-4B-FC \ --dtype auto \ --max-model-len 8192 \ --gpu-memory-utilization 0.92 \ --enable-auto-tool-choice \ --tool-call-parser hermes \ --trust-remote-code

各参数的作用整理如下：

4.2 显存、上下文长度与吞吐量的三角平衡

--max-model-len和--gpu-memory-utilization这两个参数是联动的，调不好就会遇到启动失败或推理OOM。

先说--max-model-len。这个值决定模型能处理的最长输入输出总长度，也决定了KV cache的预分配上限。Qwen3.5-4B-FC这种4B模型，FP16权重约占8GB，KV cache在8k长度时约占1GB上下，再加上激活值和CUDA graph，12GB的3080Ti差不多是贴着上限运行。设16k或32k不是不行，但要配合量化或者接受更小的并发余量。对于大部分业务场景，8k已经够用，这也是我推荐这个值的原因。

再说--gpu-memory-utilization。设置成0.92，意味着vllm最多使用11GB左右显存。为什么不设0.98？因为还要给驱动、CUDA context以及其他进程留一点空间。如果你的机器上没有别的GPU任务，可以适当调大；如果还要同时跑数据预处理之类的CPU任务，建议保守一点。

如果启动后报CUDA out of memory，优先尝试的调整顺序是：降低--max-model-len、降低--gpu-memory-utilization、加--enforce-eager。前两个是减少实际显存占用，最后一个关闭CUDA graph优化，牺牲一点推理速度换取显存余量。

4.3 工具调用解析器：--enable-auto-tool-choice与--tool-call-parser

vllm对function calling的支持，核心机制是"训练时约定一种输出格式，推理时用解析器把模型输出转成OpenAI风格的结构化字段"。

--enable-auto-tool-choice打开自动工具调用开关后，vllm会在收到带tools的请求时，自动在系统提示词里注入工具定义，并让模型倾向输出结构化的工具调用。--tool-call-parser则负责把模型输出的文本解析成标准字段。

比较麻烦的是parser的选择，这里直接给结论：

• 如果你的微调数据参考的是Qwen官方的工具调用格式，也就是用<|tool_call|>这类特殊标记组织训练样本，选qwen。
• 如果训练时使用的是更通用的hermes风格，也就是让模型输出一个JSON数组形式的tool calls，选hermes。
• 不确定的话，先用hermes试。因为很多微调框架在构造训练数据时，实际采用的格式更接近hermes风格，即使原始数据来自Qwen官方。

判断parser是否生效的最快方法，是我后面第5章要讲的第一轮工具调用验证，返回结果里如果出现了结构化的tool_calls字段，说明parser选对了；如果模型输出了一堆JSON文本但接口返回里没有tool_calls，基本就是parser不匹配。

4.4 如何确认服务真正启动成功

启动命令敲下去之后，观察日志输出，重点看几个标志性节点：

• 出现INFO: Loading model weights took ...，说明权重加载完成。
• 出现INFO: Starting vLLM server ...和Uvicorn running on http://0.0.0.0:8000，说明服务已经起来了。
• 日志里如果出现WARNING级别的显存相关提示，比如GPU memory usage is too high，需要回看4.2节的参数调整。

服务起来后，先做接口级验证。查询已加载模型列表：

curl http://localhost:8000/v1/models

这个请求会返回模型列表，确认served-model-name设置正确。我见过有人启动成功了，但请求时报model not found，就是因为接口请求时用的模型名和--served-model-name不一致。

5. Function Calling验证：从curl到多轮工具调用闭环

5.1 tools请求格式与OpenAI兼容接口

服务启动后，第一步是用curl走通最基础的工具调用请求。请求体里通过tools字段传入工具定义，格式和OpenAI的Function Calling API保持一致。

一个典型工具定义是JSON Schema风格：

{ "type": "function", "function": { "name": "get_weather", "description": "查询指定城市的当前天气", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "城市名，例如北京、上海" } }, "required": ["city"] } } }

把这个工具定义放进请求体的tools数组，再给一句用户消息："北京今天天气怎么样？"然后看模型返回什么。

5.2 首轮调用：从系统提示到tool_calls返回

完整的curl请求：

curl http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "Qwen3.5-4B-FC", "messages": [ {"role": "user", "content": "北京今天天气怎么样？"} ], "tools": [ { "type": "function", "function": { "name": "get_weather", "description": "查询指定城市的当前天气", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "城市名"} }, "required": ["city"] } } } ], "temperature": 0.7 }'

正常的返回应该包含一个tool_calls字段：

{ "choices": [ { "message": { "role": "assistant", "content": null, "tool_calls": [ { "id": "call_xxx", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\": \"北京\"}" } } ] }, "finish_reason": "tool_calls" } ] }

看到这个结构，说明vllm的function calling链路已经通了。有两个细节要留意：content是null而不是空字符串，这是OpenAI格式的规范；arguments是一个JSON字符串，不是对象，客户端拿到之后需要做一次json.loads解析。

5.3 多轮闭环：把工具结果喂回去

单轮返回tool_calls只是第一步，真正的业务闭环要把工具执行结果回传给模型，让模型基于工具输出生成最终回答。这一步在协议上等价于"把工具结果作为一条role为tool的消息追加进对话历史"。

我用Python的OpenAI SDK演示这个完整循环：

from openai import OpenAI client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY") tools = [ { "type": "function", "function": { "name": "get_weather", "description": "查询指定城市的当前天气", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "城市名"} }, "required": ["city"] } } } ] messages = [{"role": "user", "content": "北京今天天气怎么样？"}] resp = client.chat.completions.create( model="Qwen3.5-4B-FC", messages=messages, tools=tools, temperature=0.7 ) resp_message = resp.choices[0].message # 把模型返回的tool_calls追加进对话 messages.append(resp_message) # 模拟执行工具，这里直接返回一个固定天气 if resp_message.tool_calls: for tool_call in resp_message.tool_calls: result = {"city": "北京", "temperature": "23度", "condition": "晴"} messages.append({ "role": "tool", "tool_call_id": tool_call.id, "name": tool_call.function.name, "content": str(result) }) # 第二轮请求，模型生成最终回复 final_resp = client.chat.completions.create( model="Qwen3.5-4B-FC", messages=messages, tools=tools ) print(final_resp.choices[0].message.content)

这个例子里的两个关键动作：把第一步返回的assistant message原样追加到消息列表，因为其中带tool_calls；然后为每个tool_call构造一条tool消息，并且tool_call_id必须对应上。这两处不对，模型就无法正确理解工具执行结果。

我建议先用curl跑通单轮，再用SDK跑通多轮，不仅是因为SDK封装了很多细节，更重要的是排查问题时能区分"是接口协议问题"还是"是模型能力问题"。

5.4 最容易翻车的三类返回结果

部署function calling模型最常见的三类异常结果：

第一类：模型返回了看起来像JSON的文本工具调用，但接口返回里没有tool_calls字段。这种通常是--tool-call-parser没生效，或者模型训练时使用的工具调用格式与parser不匹配。排查方法：先确认启动命令里加没加--enable-auto-tool-choice，再加--tool-call-parser hermes试一遍。

第二类：模型完全不调用工具，直接回答"我不知道今天的天气"。这说明模型在给定输入下没有走到工具调用的token路径，最常见的原因是提示词里工具定义格式和微调数据的格式不一致。微调时工具定义是放在系统提示词里用特定模板包裹的，部署时由于vllm自动注入了自己的模板，两者拼接起来可能变形。

第三类：模型返回了tool_calls，但arguments字段内容严重乱码或JSON解析失败。这种情况要检查是不是temperature设得太高导致输出不稳定。工具调用场景建议把temperature控制在0.2到0.7之间，太高会引入随机性，让工具选择不稳定。

6. 实测性能与部署中的隐藏坑

6.1 首字延迟：prefill阶段慢在哪

部署之后，很多人会注意到一个现象：第一个token出来得慢，但后面的token吐得快。这是LLM推理的正常结构——prefill阶段要并行处理整个输入提示词，计算量很大；decode阶段逐token生成，单步计算量小。vllm的continuous batching能提升整体吞吐，但对单请求的TTFT（首token延迟）没有质的改善。

在3080Ti上，8k上下文的输入，prefill时间可能在几百毫秒到几秒之间，取决于输入长度和当前并发数。如果TTFT明显异常，需要先确认是不是前缀缓存（prefix caching）没有生效。这个问题单独展开：

6.2 前缀缓存命中率：工具定义要放在对的位置

function calling场景有一个天然特性：同一个Agent系统，工具定义基本不变，每次请求的系统提示词都是同一段文字。如果把工具定义放在请求的前半部分，vllm的前缀缓存就能复用上一次请求的KV cache，prefill阶段的计算量大幅下降，TTFT能快一个量级。

我实测的对比很直观：在未开启缓存或缓存未命中的情况下，几百token的系统提示词会让首次请求慢1秒以上；命中缓存后，同样的前缀计算时间降到几十毫秒。前提是vllm版本开启了前缀缓存——在0.6.x版本需要显式加--enable-prefix-caching，0.7.x之后默认开启，可以通过--disable-prefix-caching关闭。

所以部署时有一个实操建议：工具定义尽量放在系统提示词最前面的固定位置，不要每次请求动态改变顺序。因为前缀缓存靠的是逐token精确匹配，任何一点差异都会导致缓存失效、回到完整prefill。前后缀顺序固定之后，你会发现请求越快越稳定。

6.3 压测一把：并发、显存与卡死的边界

部署完成只是起点，下一步是拿真实请求压一下，看看这张卡到底能扛多少并发。

我用的压测方式很简单，不引入额外的压测平台，就用Python的asyncio加httpx快速测：

import asyncio import httpx async def single(client, messages): resp = await client.post( "http://localhost:8000/v1/chat/completions", json={ "model": "Qwen3.5-4B-FC", "messages": messages, "max_tokens": 256, "temperature": 0.7 }, timeout=120 ) return resp.status_code async def main(): messages = [{"role": "user", "content": "用一句话介绍北京"}] async with httpx.AsyncClient() as client: results = await asyncio.gather(*[single(client, messages) for _ in range(20)]) print(results) asyncio.run(main())

20个并发请求同时打上去，3080Ti跑FP16的4B模型是能稳住的，总吞吐大概在每秒几百token的量级，单请求完全无感的级别。但如果把并发拉到50甚至100，就要注意一个现象：vllm会把请求排队，oversized请求会一直pending，表现就是"请求发出去但很久没有响应"。这不一定说明服务挂了，可能是队列积压。遇到这种情况，优先观察日志里的GPU显存占用和当前running sequence数量来判断瓶颈。

实测下来，3080Ti上这个模型，我把并发控制在30以内比较放心。再往上要么接受更高的平均延迟，要么上量化模型换取显存空间，要么直接加一张卡做多副本。

6.4 报错现场与排查思路汇总

把部署过程中容易遇到的报错整理成一张表，方便快速定位：

还有一个社区反馈的高频问题：vllm升级版本后，某些参数或者行为发生了变化，导致原来自定义工具调用的链路突然失效。所以我的原则很明确——代码和配置文件里把vllm版本写死，不跟随latest滚动升级。每次升级前先在测试环境跑一遍工具调用回归用例，再决定要不要上生产。

部署这件事，越往后越能体会到"细节决定成败"。很多人微调完急着把模型扔上线，结果被显存规划、parser选择、缓存命中这些环节来回折腾。我的经验是：先把部署链路走通，再回头调参数优化。先用8k上下文、FP16精度、单个工具定义，把function calling的首轮调用跑通；确认模型真的能输出标准tool_calls之后，再逐步加长上下文、增加工具数量、压并发。每个环节单独验证，出了问题也知道该改哪里。

后续如果业务需求上来，还可以做两件事：一是把模型量化到4bit，用长上下文和更大并发换一点质量损失，vllm对AWQ和GPTQ的兼容都做得很成熟；二是如果单卡吞吐确实到了瓶颈，vllm也支持分布部署，多卡之间做张量并行。不过这些都是后话了，先把3080Ti上的单卡服务跑稳，function calling链路真正通了，微调这件事才算真正落地。