大模型本地部署文档编写指南
从 Linux 与 Python 前置环境、模型来源和启动参数，到接口验收与故障记录，说明如何用 vLLM 编写可复现的大模型本地部署文档，并明确一个服务进程一次承载一个模型。
写好大模型部署文档，才能让其中的本地部署步骤被另一名成员按同一环境复现；文档应覆盖适用边界、模型来源与许可证、安装命令、启动参数、接口验收和故障记录。以 vLLM 为例，主线可固定为“准备环境—启动服务—检查端点—记录版本”，让操作说明与验收标准彼此对应。
编写大模型部署文档时，先固定环境与硬件边界
根据 vLLM Quickstart 的前置与安装说明，前置环境是 Linux 与 Python 3.10 到 3.13；推荐命令使用 uv 创建 Python 3.12 虚拟环境，并由 --torch-backend=auto 根据已安装的 CUDA driver version 选择 PyTorch index：
uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto
硬件清单不能只写“有 GPU”。vLLM GPU 安装文档规定，NVIDIA GPU 需要 CUDA compute capability 7.5 或更高；预编译包包含 C++ 与 CUDA 12.9 二进制文件，B200、GB200 至少需要 CUDA 12.8。文档还应另记 GPU 型号、显存、供电、接口和机箱尺寸，不能仅凭 compute capability 达标就断定某个模型必然能够运行。
把安装分支和失败条件写清楚
按 vLLM 的 NVIDIA CUDA 安装说明，应优先使用全新环境；如果 CUDA 版本不同，或需要沿用已有的 PyTorch 安装，则要改为源码构建。文档应把这一条件放在安装步骤之前，而不是等安装失败后再补充。
使用 pip 安装 nightly wheels 不受支持，官方要求使用 uv，因为 pip 会合并 --extra-index-url 与默认索引并选择最新版本；这也是安装文档必须记录工具和索引策略的原因。vLLM 的 nightly 安装说明
进入源码构建分支时，还要记录编译器条件。vLLM GPU 安装文档要求 GCC/G++ 11.3 或更新版本。源码构建的具体命令应从当前官方页面复制，不能把预编译安装命令改写后冒充源码构建步骤。
模型来源与启动命令要成对出现
模型章节应记录仓库标识、启动命令中的准确模型名称、许可证和访问条件，避免接手人只看到一个无法复现的模型简称。
权重与凭据配置也要写清。vLLM serve CLI Reference说明，--download-dir 用于指定权重的下载和加载目录，默认使用 Hugging Face cache directory；--hf-token 可提供 Hugging Face bearer token，hf auth login 生成的 token 存放在 ~/.cache/huggingface/token。路径示例可使用 YOUR_VALUE，但运行文档不应收录真实 token。
按照 vLLM Quickstart 的服务启动说明，一个 server process 一次承载一个模型；默认监听 http://localhost:8000，可使用 --host 和 --port 修改地址，--api-key 或 VLLM_API_KEY 用于启用请求头中的 API key 检查。启动和列出模型的对应命令为：
vllm serve Qwen/Qwen2.5-1.5B-Instruct
curl http://localhost:8000/v1/models
参数说明要回答实际影响
资源参数应集中记录：vLLM serve CLI Reference将 --max-model-len 定义为 prompt 与 output 的总上下文长度，未设置时从模型配置推导，设为 -1 或 auto 时选择 GPU 内存能够容纳的最大长度；--max-num-seqs 限制单次迭代处理的 sequences，--max-num-batched-tokens 限制单次迭代处理的 tokens。该页还说明 --gpu-memory-utilization 是当前实例使用的 GPU memory fraction，默认值为 0.92；设置 --kv-cache-memory-bytes 会覆盖这一比例控制，--enforce-eager 则会禁用 CUDA graphs 和 torch.compile。
不要只抄参数定义。应在旁边写明参数影响的是上下文长度、并发处理量、GPU memory 还是执行模式，并区分“省略参数”与“显式设置”的不同文档含义。
如何写验证与故障记录
vLLM Online Serving 文档说明，服务默认使用 tokenizer 中预定义的 chat template；缺少 template 时无法处理 chat requests，--chat-template 可接收文件路径或模板字符串。文档应记录 template 的来源、启动参数和缺失时的报错位置。
同一 vLLM Online Serving 端点清单列出了 /version、/load、/v1/models 和 /health，分别用于版本信息、server load metrics、模型列表和健康检查。把这些路径写成验收项时，应同时附上实际执行的命令和输出，不要预填成功结果。
接口兼容性也要单列。vLLM OpenAI-Compatible Server 文档说明，/v1/completions 不支持 suffix，/v1/chat/completions 需要 chat template 并忽略 user，/v1/embeddings 仅适用于 embedding models，/v1/audio/transcriptions 仅适用于 ASR models。业务请求中出现的扩展参数，应在文档中注明是否受支持。
交接前至少检查以下内容：
- 环境记录是否包含 OS、Python、GPU、CUDA 分支和安装方式。
- 模型记录是否包含准确名称、来源、许可证、权重目录和凭据配置。
- 启动命令是否保留了地址、端口、API key 与关键资源参数。
- 验证记录是否区分模型列表、健康检查、chat template 和接口兼容性。
- 故障记录是否保留原始报错、所选分支及恢复条件，而不是只写“安装失败”。
文中步骤依据正文链接的官方文档整理，未运行或测量这些命令；使用前应按当前版本复核。