6. 综合练习

这是什么：综合练习 = 把前五章的东西串起来，让自己的应用用上自己部署的模型。

为什么用：前面五章是零件：装环境、起服务、接接口、调参数、管运维。这一章把零件拼成一台能交付的机器，并给你一份验收清单。

如何用：本章分四步——起服务、写客户端、换自有模型、做验收，最后留一个可复用的项目骨架。

6.1 练习目标

最终交付一套「本地大模型 API 服务 + 客户端」：

服务端：vllm serve 起一个模型，带 API key
客户端：一个 Python 脚本，base_url 指向你自己的服务
自有模型：把你下载好的或微调好的权重换上去

6.2 第一步：把服务跑起来

vllm serve ./my-model \
  --served-model-name my-model \
  --api-key my-secret-key \
  --max-model-len 4096 \
  --gpu-memory-utilization 0.9 \
  --port 8000

你会看到（示意）：

INFO:     Application startup complete.

四个参数的理由：--served-model-name 固定对外名字；--api-key 挡住闲人；--max-model-len 控住显存；--port 换端口方便本机跑多个实例。

6.3 第二步：写一个能用的客户端

import os
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key=os.environ.get("MY_LLM_KEY", "my-secret-key"),
)

def ask(prompt: str) -> str:
    resp = client.chat.completions.create(
        model="my-model",                 # 要和 --served-model-name 一致
        messages=[
            {"role": "system", "content": "你是一个简洁的编程助手，回答不超过三句话。"},
            {"role": "user", "content": prompt},
        ],
        temperature=0.3,
        max_tokens=512,
    )
    return resp.choices[0].message.content

if __name__ == "__main__":
    print(ask("用一句话解释什么是 KV cache"))

你会看到（示意）：

KV cache 是模型把已经算过的上下文暂存下来的地方，
这样生成下一个词时不用从头再算一遍，能显著加快推理速度。

三个容易翻车的点：

坑	表现	修正
`model` 名写错	报 `model not found`	和 `--served-model-name` 完全一致
忘了带 `api_key`	401	SDK 必须传这个字段，本地也要填 `"EMPTY"`
传了全名 `Qwen/Qwen3-8B`	404	设了 `--served-model-name` 就只能用别名

6.4 第三步：换上你自己的模型

三种来源：

来源	怎么起服务
HuggingFace 上的模型	`vllm serve Qwen/Qwen3-8B`
本地下载好的权重	`vllm serve /path/to/your/model`
自己微调过的模型	`vllm serve /path/to/your/finetuned`

本地权重目录里要有 config.json、tokenizer.json（或 tokenizer_config.json）、权重文件 *.safetensors。关键还要有 chat template（对话模板），否则 /v1/chat/completions 会报错。没有的话用 --chat-template ./my_template.jinja 指定。

微调模型要多留意 config.json 里的 architectures 要和 vLLM 支持的架构对上；启动报错时先看日志里 Architecture for model type ... is not supported 这类提示。

6.5 第四步：验收清单

逐条过一遍，全绿才算交付：

curl /health 返回 200
curl /v1/models 里能看到你定的模型名
不带 key 的请求被拒（401）
带 key 的请求能拿到正常回答
流式输出能逐字返回
/metrics 里 vllm:num_requests_running 在变
连续跑 10 个请求没报错

curl -s -o /dev/null -w "health: %{http_code}\n" http://localhost:8000/health
curl -s http://localhost:8000/v1/models | head -c 200

你会看到（示意）：

health: 200
{"object":"list","data":[{"id":"my-model","object":"model","owned_by":"vllm"}]}

6.6 可以直接抄的项目骨架

my-llm-service/
├── serve.sh              # 启动服务的脚本
├── client.py             # 客户端
├── .env                  # MY_LLM_KEY=my-secret-key
└── models/
    └── my-model/         # 自有模型权重

# serve.sh
#!/usr/bin/env bash
set -euo pipefail
export HF_HOME=${HF_HOME:-~/.cache/huggingface}
vllm serve "${1:-./models/my-model}" \
  --served-model-name my-model \
  --api-key "${MY_LLM_KEY:-my-secret-key}" \
  --max-model-len 4096 \
  --port "${PORT:-8000}"

.env 里只放密钥，不放模型路径：路径写进 serve.sh 的参数里，密钥走环境变量，两边分开才好改。

动手改

把 client.py 里的 model 参数改成故意写错的名字，读懂 404 报错里给的提示
给客户端加一个 stream=True 的版本，做个打字机效果出来
把 --max-model-len 改成 1024 再跑一遍长 prompt，观察服务端返回什么

小结

服务端四个关键参数：--served-model-name、--api-key、--max-model-len、--port
客户端只需改 base_url 和 api_key，model 填对外别名
自有模型优先用本地路径启动，注意要有 chat template
交付前照着验收清单逐条打勾

vLLM 部署完成！🎉 从这里开始，你的应用就能用上自己部署的模型了——想继续折腾，回头看性能调优和部署与运维就行。🐸