llm-deploy-training

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 官方阅读顺序：

1. 先确认当前安装版本：python -c 'import vllm; print(vllm.__version__)'。
2. 在 vLLM 官方文档站选择与当前安装版本匹配的文档版本；不要把 stable、latest 或某个历史版本链接当作固定答案。
3. 依次阅读该版本下的文档首页、OpenAI-compatible server、相关模型/场景 recipe 和 API 文档。
4. 再看当前环境 CLI help：vllm serve --help。
5. 最后只读追溯当前安装版本源码；不修改源码或环境。

版本匹配链接模板。把 <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 官方阅读入口：

1. 文档根目录：https://swift.readthedocs.io/zh-cn/latest/。
2. 训练、数据集、模板、loss 或 loss mask 相关问题，先确认当前安装版本：python -c 'import swift; print(swift.__version__)'。
3. 当前记录对照的官方 latest 文档版本是 swift 4.5.0.dev0；如果本地版本不同，必须以当前环境 swift sft --help、swift rlhf --help 和已跑通脚本为准。
4. 版本门槛要单独核对：message 级 loss_scale 需要 ms-swift>=4.2.0，数据集级 chat_template_kwargs 需要 ms-swift>=4.3.0。
5. messages 的 loss、loss_scale、agent template 和工具消息格式，优先读官方自定义数据集文档与架构文档的 Loss/Loss Scale 章节。
6. 仍不确定时，只读追溯当前安装版本源码中的 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