| name | llm-deploy-training |
| description | 当需要部署或训练 LLM/VLM 时使用；覆盖 vLLM OpenAI-compatible 服务、多模态输入限制、Qwen3.5 工具调用、thinking/reasoning 控制、CUDA Graph 策略，以及 ms-swift SFT/DPO/GRPO full training、Megatron 长序列训练、messages loss/loss_scale、数据校验、显存排错和训练检查。 |
LLM Deploy And Training
文件导航
| 序号 | 文件内容概览 | 关键词 | 触发时机 | 文件路径 |
|---|
| 1 | 规定 LLM/VLM 部署和训练的共通安全边界，说明不要改共享环境、如何匹配 vLLM/ms-swift/transformers/torch 版本、何时读官方文档、何时只读追溯源码，并记录 ms-swift 官方文档入口。 | LLM deploy、VLM deploy、training、shared env、conda、version match、official docs、CLI help、source tracing、site-packages、vLLM、ms-swift、loss、loss_scale、transformers、torch | 触发本 skill 后默认读取；部署或训练前；准备安装/升级依赖前；参数不确定要查文档或源码前；涉及共享 conda、CUDA、torch/vLLM/ms-swift 环境时读取 | SKILL.md |
| 2 | 记录 vLLM OpenAI-compatible 服务的完整部署和验证经验，覆盖 vllm serve 参数、多模态 limit-mm-per-prompt、Qwen3.5 工具调用、thinking/reasoning、35B 2 卡、CUDA Graph、extra_body、内网访问和 SSH local port forwarding。 | vLLM、OpenAI-compatible server、vllm serve、multimodal、limit-mm-per-prompt、auto tool choice、qwen3_coder、Qwen thinking、reasoning parser、35B、tensor parallel、CUDA Graph、extra_body、SSH forwarding、/v1/models | 写或审查 vLLM 部署脚本前；验证 /v1/models/短文本/工具调用/图片输入前；配置 Qwen thinking 开关或 35B 服务前；排查 CUDA Graph、OOM、多模态报错、工具调用失败或本地访问内网服务时必须读取 | references/vllm-deployment.md |
| 3 | 记录 ms-swift SFT/DPO/GRPO full training 的完整训练经验，覆盖默认超参、bf16/zero3/save_only_model、messages 的 loss/loss_scale、工具调用与工具返回的 loss mask、Megatron TP/CP/SP/TE fused CE 长序列训练、JSONL validator、max length 过滤、显存排错、dry-run、训练后检查和 rjob 资源模板。 | ms-swift、SFT、DPO、GRPO、full training、Megatron、TP、CP、PP、EP、sequence_parallel、fused attention、TE fused CE、cross_entropy_loss_fusion、optimizer_cpu_offload、bf16、DeepSpeed zero3、save_only_model、save_safetensors、messages、loss、loss_scale、loss mask、tool_call、tool_response、agent template、JSONL、validator、max_length、OOM、dry-run、rjob、checkpoint、consumed data | 编写/审查 SFT、DPO 或 GRPO 脚本前；普通 HF Trainer/ms-swift + DeepSpeed ZeRO 在长样本 forward/loss/activation/logits OOM 时；准备 full training 超参前；设计 messages 训练目标前；给不同 assistant 回复段设置 loss/loss_scale 前；处理 tool_call/tool_response 数据前；训练数据格式校验前；排查 OOM、LoRA/full 混用、checkpoint 膨胀、save_safetensors 参数解析失败、训练失败或 consumed 标记问题时必须读取 | references/ms-swift-training.md |
核心原则
- 部署和训练都优先复用已有环境；不要擅自升级
torch、vllm、transformers、ms-swift 或共享 conda 环境。
- 部署脚本使用环境变量配置模型路径、端口、上下文长度、工具调用、多模态限制和 CUDA Graph 策略。
- 多模态服务必须显式设置
--limit-mm-per-prompt，不要依赖 vLLM 默认值或旧脚本默认值。
- Qwen3.5 工具调用优先使用官方推荐的 auto tool choice 与 parser 参数。
- Qwen thinking/reasoning 不要写死在部署脚本里；部署端只启用必要 parser，请求侧用
extra_body.chat_template_kwargs.enable_thinking 控制开关。
- 对 vLLM 这类成熟第三方库，优先读官方教程、recipe、serving 文档和 API 文档；官方文档不能解释当前版本行为时，再做只读源码追溯。
- 训练输出目录不要放在代码仓库里；放到 base checkpoint 同级或专用的大容量模型目录。
- 训练数据先做 JSONL 格式校验、字段校验和 max length 过滤，再启动训练。
- 设计 ms-swift messages 训练数据时，必须明确哪些 assistant/tool_call/tool_response 片段参与 loss；训练前用当前 template 解码
labels 和 loss_scale 验证，不凭 JSON 外观看。
- 普通 ZeRO 只能切 optimizer、grad 和参数状态；当单个样本本身太长、监督 token 太多、vocab 太大，导致 attention/activation/logits/loss OOM 时，按
ms-swift Megatron 路线评估 TP/CP/SP/fused CE，而不是只增加 data parallel 卡。
- 失败、skip、OOM 或 dry-run 不应标记数据已消费；只有训练成功后才归档或标记 consumed。
- 如必须补包，先询问；确需安装单包时优先
pip install --no-deps <pkg>。
版本、官方文档与源码追溯
vllm、swift、transformers、torch 行为随版本变化明显；参数不确定时先查当前环境版本和官方文档，再看 CLI help，最后才读源码。- vLLM 这类知名库应优先使用官方教程、官方 recipe、serving 文档和 API 文档，不要把源码阅读作为第一反应。
- 源码适合确认当前安装版本的实际参数名、默认值、兼容分支和错误路径；不适合替代官方教程来学习推荐用法。
- 源码只用于阅读和定位问题，不要改源码，不要直接修改共享环境里的
site-packages；需要改库或补 patch 时，先征得用户同意，并优先 clone 源码到项目目录后 editable install。
inspect.getsource(...) 适合追 Python API；CLI 参数优先看 vllm serve --help、swift sft --help、swift rlhf --help。
vLLM 官方阅读顺序：
- 先确认当前安装版本：
python -c 'import vllm; print(vllm.__version__)'。
- 在 vLLM 官方文档站选择与当前安装版本匹配的文档版本；不要把
stable、latest 或某个历史版本链接当作固定答案。
- 依次阅读该版本下的文档首页、OpenAI-compatible server、相关模型/场景 recipe 和 API 文档。
- 再看当前环境 CLI help：
vllm serve --help。
- 最后只读追溯当前安装版本源码；不修改源码或环境。
版本匹配链接模板。把 <matched-vllm-doc-version> 替换为官方文档站里与当前 vllm.__version__ 对应的版本路径；如果官方文档没有完全相同版本，选择最接近的同系列版本，并在任务记录中写明所选文档版本：
VLLM_DOCS_BASE="https://docs.vllm.ai/en/<matched-vllm-doc-version>/"
VLLM_OPENAI_SERVER_DOC="${VLLM_DOCS_BASE}serving/openai_compatible_server/"
VLLM_COMPILATION_DOC="${VLLM_DOCS_BASE}api/vllm/config/compilation/"
VLLM_RECIPES_BASE="https://docs.vllm.ai/projects/recipes/en/<matched-vllm-doc-version>/"
VLLM_QWEN35_RECIPE="${VLLM_RECIPES_BASE}Qwen/Qwen3.5.html"
ms-swift 官方阅读入口：
- 文档根目录：
https://swift.readthedocs.io/zh-cn/latest/。
- 训练、数据集、模板、loss 或 loss mask 相关问题，先确认当前安装版本：
python -c 'import swift; print(swift.__version__)'。
- 当前记录对照的官方
latest 文档版本是 swift 4.5.0.dev0；如果本地版本不同，必须以当前环境 swift sft --help、swift rlhf --help 和已跑通脚本为准。
- 版本门槛要单独核对：message 级
loss_scale 需要 ms-swift>=4.2.0，数据集级 chat_template_kwargs 需要 ms-swift>=4.3.0。
- messages 的
loss、loss_scale、agent template 和工具消息格式，优先读官方自定义数据集文档与架构文档的 Loss/Loss Scale 章节。
- 仍不确定时，只读追溯当前安装版本源码中的
template、dataset、loss、loss_scale 相关实现；不修改源码或共享环境。
MS_SWIFT_DOCS_ROOT="https://swift.readthedocs.io/zh-cn/latest/"
MS_SWIFT_ARCH_LOSS_DOC="https://swift.readthedocs.io/zh-cn/latest/Customization/Architecture.html#loss"
MS_SWIFT_CUSTOM_DATASET_DOC="https://swift.readthedocs.io/zh-cn/latest/Customization/Custom-dataset.html"
python - <<'PY'
import importlib
for name in ["vllm", "swift", "transformers", "torch"]:
try:
mod = importlib.import_module(name)
print(name, getattr(mod, "__version__", "unknown"), getattr(mod, "__file__", "no __file__"))
except Exception as exc:
print(name, "not importable:", exc)
PY
vllm serve --help | sed -n '1,160p'
swift sft --help | sed -n '1,160p'
swift rlhf --help | sed -n '1,180p'
示例：追 vLLM serve 入口或配置类时，先定位模块路径，再按当前版本源码确认参数名：
python - <<'PY'
import inspect
import vllm
print("vllm:", vllm.__version__, vllm.__file__)
try:
from vllm.config import CompilationConfig
print(inspect.getsource(CompilationConfig))
except Exception as exc:
print("CompilationConfig unavailable:", exc)
PY
