人工智能知识 - 编程（二）

这一篇承接人工智能知识 - 编程（一）。前一篇已经梳理 AI 训练与推理编程的横向工程栈；本篇进入重点框架详解与代码精读，集中处理 PyTorch、Transformers、PEFT、语言模型强化学习、OpenRLHF、verl、DeepSpeed、vLLM，以及典型开源代码的逐行解读。

PyTorch 是训练与推理编程栈的“最底层可控面”：Tensor、device、autograd、 nn.Module、数据加载、序列化、编译与分布式训练都在这一层完成。上层框架可以隐藏细节，但当你需要排查显存、吞吐、梯度同步、checkpoint 恢复、算子不确定性时，最终必须回到 PyTorch 的对象模型与 API 语义。

PyTorch 的安装需要同时匹配三件事：Python 版本、操作系统、计算平台（CPU/CUDA/ROCm/MPS）。实际工程里最稳妥的策略是：用官方安装页的选择器生成命令，然后将该命令固化到你的环境脚本或镜像构建中。

目标平台	常用安装方式（示例）	工程备注
CPU（Linux/macOS/Windows）	Shell 1 pip install -U torch torchvision	CPU-only 适合开发与单测；性能调优与显存问题需要在目标 GPU 上复现。
CUDA（NVIDIA GPU）	Shell 1 2 # 以官方安装页生成的命令为准；典型形态如下 pip install -U torch torchvision --index-url https://download.pytorch.org/whl/cu126	CUDA wheel 与机器驱动/运行时要匹配；多机训练应当在镜像层固定 CUDA 与 PyTorch 组合。
ROCm（AMD GPU）	Shell 1 2 # 以官方安装页生成的命令为准（ROCm 版本需匹配系统栈） pip install -U torch torchvision --index-url https://download.pytorch.org/whl/rocm	ROCm 生态对内核/驱动版本更敏感，建议使用官方/社区维护的容器基镜像。
MPS（Apple Silicon）	Shell 1 pip install -U torch torchvision	设备为 mps；算子覆盖度与性能特征与 CUDA 不同。

最小验证覆盖三个断言：版本可读、Tensor 可算、目标加速器可见。

Tensor 的关键元信息是：形状（shape）、数值类型（dtype）、设备（device）、以及是否参与梯度（requires_grad）。训练代码里常见 bug 本质都是“不匹配”：输入和参数不在同一 device、label dtype 错、view/reshape 造成非 contiguous 导致算子退化，或无意间把需要梯度的张量带入无梯度区间。

命令/API/函数 torch.tensor 说明 从 Python 对象创建张量（会拷贝） 示例 Python 1 x = torch.tensor([[1, 2], [3, 4]], dtype=torch.float32)

命令/API/函数 torch.as_tensor 说明 尽量不拷贝地包装已有数据 示例 Python 1 2 3 import numpy as np arr = np.zeros((2, 3), dtype=np.float32) x = torch.as_tensor(arr)  # 可能与 numpy 共享内存

命令/API/函数 torch.from_numpy 说明 从 numpy 创建（共享内存） 示例 Python 1 x = torch.from_numpy(arr)  # 修改一侧会影响另一侧

命令/API/函数 Tensor.to 说明 迁移 device/dtype（训练最常用） 示例 Python 1 2 device = torch.device("cuda", 0)  # or "cpu"/"mps" x = x.to(device=device, dtype=torch.bfloat16)

命令/API/函数 Tensor.permute / Tensor.transpose 说明 重排维度顺序；图像常用于 NCHW/NHWC 互换，序列常用于 batch-first/seq-first 互换。 示例 Python 1 x = x.permute(0, 3, 1, 2)  # NHWC -> NCHW

命令/API/函数 Tensor.view / Tensor.reshape / Tensor.flatten 说明 改张量形状； view 更强调复用现有内存布局， reshape 则在必要时自动 materialize。 示例 Python 1 y = x.reshape(x.size(0), -1)

命令/API/函数 Tensor.unsqueeze / Tensor.squeeze 说明 插入或删除长度为 1 的维度，常见于 batch 维、head 维和 channel 维补齐。 示例 Python 1 2 x = x.unsqueeze(0) x = x.squeeze(0)

命令/API/函数 Tensor.expand / Tensor.repeat 说明 expand 走广播语义，尽量不复制； repeat 会真实复制数据。 示例 Python 1 mask = mask.unsqueeze(0).expand(batch_size, -1)

命令/API/函数 Tensor.contiguous 说明 把非连续内存布局变成连续 示例 Python 1 2 x = x.permute(0, 2, 1)     # 可能变成非 contiguous x = x.contiguous()        # 需要时显式转回

命令/API/函数 Tensor.is_contiguous / channels_last 说明 检测当前内存布局，或显式切到 channels_last memory format；视觉模型优化时很常见。 示例 Python 1 2 x = x.contiguous(memory_format=torch.channels_last) print(x.is_contiguous(memory_format=torch.channels_last))

PyTorch 里最容易被误解的是“轴顺序”和“memory format”并非同一个概念。 NCHW、 NHWC 描述语义上的维度顺序； contiguous、 channels_last 描述底层 stride 是否符合某种内存访问模式。

视觉模型里常见的缩写与 NumPy 一致：

• CHW / HWC：单张图像。
• NCHW / NHWC：批量图像。
• channels_first / channels_last：通道维放前面还是后面。

当 NumPy 数组通过 torch.from_numpy 或 torch.as_tensor 进入 PyTorch 时，除了 shape/dtype，还要警惕底层 stride。最典型的坑是：

• NumPy 的 np.flip、 [::-1] 之类操作，可能产生负 stride 视图。
• 这类数组在某些 PyTorch 路径里不能直接接收，或会触发额外 materialize。
• 跨框架前，通常用 np.ascontiguousarray 或显式 copy 把布局整理干净。

单机多卡训练通常按“每进程绑定一张卡”的方式组织。绑定的核心动作是：在进程启动后立即 torch.cuda.set_device(local_rank)，并确保模型与 batch 都迁移到 cuda:local_rank。

PyTorch 的 autograd 是胶带式自动求导：前向执行时记录算子与中间结果，反向时从标量 loss 回传梯度到叶子张量（leaf tensors）。工程上需要明确三类“梯度模式”：训练（需要梯度）、评估（无梯度）、推理（更强的 inference mode）。

一个稳定的训练 step 通常遵循固定模板：清梯度、前向、算 loss、反向、（可选）裁剪、优化器 step。清梯度推荐使用 set_to_none=True，这会让 PyTorch 用 None 表示“没有梯度”，减少写零开销。

model.eval() 只切换模块行为（例如 dropout/batchnorm），不影响 autograd。关闭梯度需要显式进入无梯度上下文：

• torch.no_grad()：关闭反向图记录，适用于评估。
• torch.inference_mode()：更激进的推理模式，额外禁用若干 autograd 相关开销；它不会自动调用 model.eval()。

torch.autograd.grad 在实现自定义优化、梯度惩罚、或需要显式控制梯度张量生命周期时更直接。

nn.Module 提供两类关键能力：组织子模块并注册参数/缓冲区；提供可序列化的 state_dict，用于保存/恢复训练状态和做 warmstart。

可训练权重应当是 nn.Parameter 或由标准层（Linear/Conv/Embedding 等）创建；非训练但需要随模型保存的状态（例如 batchnorm 的 running_mean）应注册为 buffer。

buffer 是否进入 state_dict 由 persistent 决定：非持久 buffer 不会被保存，这常用于缓存中间结果或仅运行期有效的状态。

state_dict() 返回一个 Python dict，包含参数与持久化 buffer。加载时常用两种策略：

• 严格恢复：结构完全一致，使用默认 strict=True。
• warmstart：允许缺键/多键，使用 strict=False，并显式检查 missing/unexpected keys。

如果 checkpoint 来自 DDP/FSDP 包装后的模型，键名前缀经常会多出 module.。不要手工重写整个 dict；PyTorch 已提供了前缀清理工具。

命令/API/函数 model.train() 说明 切到训练模式，启用 dropout、BatchNorm 更新等训练态行为。 示例 Python 1 model.train()

命令/API/函数 model.eval() 说明 切到评估模式，冻结 dropout/BatchNorm 的训练态分支；它不等价于关闭梯度。 示例 Python 1 model.eval()

命令/API/函数 model.parameters() 说明 返回优化器应更新的参数迭代器，多参数组通常从这里拆分 weight decay 或 learning rate。 示例 Python 1 optimizer = torch.optim.AdamW(model.parameters(), lr=1e-4)

命令/API/函数 model.buffers() 说明 遍历 buffer，适合检查 BatchNorm 统计量、EMA 阴影权重或运行期缓存状态。 示例 Python 1 2 for buf in model.buffers():     print(buf.shape)

命令/API/函数 model.state_dict() 说明 导出参数与持久化 buffer 的字典，是保存 checkpoint 和部署权重包的标准契约。 示例 Python 1 state = model.state_dict()

命令/API/函数 model.load_state_dict(...) 说明 把 checkpoint 恢复到当前模块，warmstart 时应检查 missing/unexpected keys。 示例 Python 1 missing, unexpected = model.load_state_dict(state, strict=False)

训练吞吐的瓶颈经常不在 GPU，而在数据管线：解码、tokenize、增强、CPU 到 GPU 拷贝、以及 DataLoader 的多进程调度。DataLoader 的可调参数很多，但最关键的是：Dataset 类型（map-style/iterable-style）、worker 并发、pin memory、以及 batch 组装（collate）。

DataLoader 的构造参数是你调吞吐的第一现场： num_workers 决定 CPU 并发、 pin_memory + non_blocking=True 影响 H2D 拷贝、 prefetch_factor / persistent_workers 影响 worker 生命周期与预取深度。

将 batch 移动到 GPU 时，pin memory 结合 non_blocking=True 才能发挥异步拷贝效果。

shuffle=True 只覆盖了最简单的“随机读样本”场景。真实训练脚本经常需要显式控制样本顺序、顺序是否可复现、以及 batch 是否按某种结构聚合。此时更稳的做法是把“采样器（Sampler）”与“批采样器（BatchSampler）”分开表达。

命令/API/函数 RandomSampler 说明 按随机顺序产出单条样本索引，适合单机训练、可复现实验或需要自定义重采样逻辑的场景。它表达的是“索引顺序”，而非 batch 结构。 示例 Python 1 2 3 4 5 6 7 8 9 10 from torch.utils.data import DataLoader, RandomSampler   # 把“随机读索引”显式化，后续更容易替换成带权重或分布式 sampler sampler = RandomSampler(dataset) loader = DataLoader(     dataset,     batch_size=32,   # 这里仍由 DataLoader 负责每 32 个索引拼成一个 batch     sampler=sampler, # 一旦显式传 sampler，就不要再同时写 shuffle=True，避免语义冲突     num_workers=8, )

命令/API/函数 SequentialSampler 说明 按数据集原始顺序读取样本，适合验证集、离线导出、对齐原始文件顺序的 debug、以及需要稳定回放某段数据的问题排查。 示例 Python 1 2 3 4 5 6 7 8 9 10 from torch.utils.data import DataLoader, SequentialSampler   # 验证或导出阶段通常更看重顺序稳定，而非随机打散 sampler = SequentialSampler(eval_dataset) loader = DataLoader(     eval_dataset,     batch_size=64,     sampler=sampler,     num_workers=4, )

命令/API/函数 BatchSampler 说明 先决定“这一批该由哪些索引组成”，再把整批索引交给 DataLoader。它适合长度分桶、按图像尺寸分组、或任何“batch 规则比单样本顺序更重要”的任务。 示例 Python 1 2 3 4 5 6 7 8 9 10 11 12 13 14 from torch.utils.data import BatchSampler, DataLoader, RandomSampler   base_sampler = RandomSampler(dataset)  # 单样本顺序先交给基础 sampler 决定 batch_sampler = BatchSampler(     base_sampler,     batch_size=32,    # 这里定义“每次吐出一组 32 个索引”     drop_last=True,   # 训练时常丢掉尾部不满批，避免 BN/张量并行尺寸抖动 ) loader = DataLoader(     dataset,     # 使用 batch_sampler 后，不再传 batch_size/shuffle/sampler     batch_sampler=batch_sampler,     num_workers=8, )

当样本长度或图像尺寸差异很大时，很多开源训练仓库会在 BatchSampler 上再包一层“分桶/分组”策略，让同一个 batch 内的样本更相似，从而减少 padding 浪费与动态 shape 带来的 kernel 抖动。

DDP 下每个进程应读取不同数据子集。map-style 数据集通常配合 DistributedSampler，并在每个 epoch 调用 set_epoch 让 shuffle 可复现。

混合精度训练通常用 torch.amp.autocast 与 torch.amp.GradScaler 组合。旧的 torch.cuda.amp.autocast / torch.cpu.amp.autocast 已逐步迁移到统一入口。

训练脚本里 checkpoint 的工程目标是两件事：可恢复（resume 时学习率/AMP/随机性都对齐），以及可复用（用于推理或 warmstart）。推荐把 checkpoint 组织成一个 dict：模型 state、优化器 state、调度器 state、AMP scaler state、当前步数/epoch、以及必要的 RNG 状态。

torch.load 基于 pickle 反序列化，不能加载不可信来源的文件。加载权重/状态字典时优先使用 weights_only=True，把反序列化限定在 state_dict 等常见安全类型集合内。

大 checkpoint 在 CPU 内存紧张的环境里还常配合 mmap=True 使用。它的工程意义是尽量避免一次性把整个文件完整拷进用户态内存，从而降低加载峰值。

当模型和优化器状态已经是分布式形态时，把所有 rank 的状态先 gather 成单文件再保存，I/O 与 CPU 峰值都会迅速变差。PyTorch 的 torch.distributed.checkpoint 提供了面向分布式训练的 checkpoint 读写接口：每个 rank 写自己那一份分片，恢复时再按当前并行拓扑装回去。

如果 checkpoint 写盘本身会卡住训练步，DCP 还提供 async_save。工程上通常要配合“前一次异步保存未完成前不再发起下一次保存”的节流策略，避免后台 I/O 线程堆积。

更复杂的 DDP/FSDP 脚本里，推荐先用统一 state_dict API 把“该保存什么状态”整理出来，再交给 DCP 写盘。这样做的好处是：checkpoint 语义先被建模清楚，再决定底层是单文件还是分布式目录。

这层抽象尤其适合 FSDP、DTensor 或未来并行拓扑会变化的项目，因为“状态怎么表示”与“状态怎么写盘”被拆成了两步。

统一 state_dict API 解决了“该保存什么”，但跨拓扑恢复还要回答另一个问题：这些状态应当以什么形态被抽取出来。是完整的 full state，还是保持分片形态；是先搬到 CPU，还是直接留在设备上；是否由 rank0 先拿到完整权重，再广播给其它 rank。 StateDictOptions 就是用来定义这层恢复契约的。

这类选项的意义不在于“多几个参数”，而在于把恢复语义写明白。只要训练产物可能在单卡评估、不同 GPU 数、不同 rank 布局之间流动，就应该先定义状态形态，再谈底层 checkpoint 文件怎么组织。

异步保存解决的是“step time 不想被 I/O 卡住”。它不会帮你解决磁盘空间、网络文件系统抖动或 checkpoint 保留策略，所以节流与清理机制仍然要自己设计。

torch.compile 会追踪（trace）你的 Python 代码中的张量计算并生成可优化的图。工程上它的常见收益来自两类：更少的 Python 开销、以及 Inductor 等后端生成的融合 kernel。无法追踪的代码会产生 graph break，这通常是性能损失，而非静默错误。

当你需要确认 compile 到底 trace 了什么，可以打开日志来观察 traced graph（用于定位 graph break 与非预期的 Python 分支）。

DDP 与 torch.compile 同时使用时，默认整模型路线更适合按 PyTorch 的 DDP note 来写：先包 DDP，再对 DDP 模型做 compile。这样 TorchDynamo 可以利用 DDP bucket 信息做 DDPOptimizer 相关优化，保留更好的通信-计算重叠机会。

如果你核心是只想对某个稳定子模块做区域化编译，那么“先 compile 子模块，再进入 DDP/FSDP 体系”也可能成立。关键不在背口诀，而在先明确你追求的是：默认整模型吞吐，还是对子模块做精细化图控制。

graph break 的含义是：编译器在某一段 Python 代码处无法继续追踪张量图，只能先把当前已捕获部分编译掉，回到普通 Python 执行，再从后面重新开始追踪。结果通常核心是“少编了一大段”，表现为速度没有明显提升甚至更慢。

最常见的 graph break 来源包括：

• 前向里混入与张量无关但频繁执行的 Python 控制流，例如复杂字典操作、字符串拼接、调试打印。
• 根据张量值做 Python 分支，而非继续保留在张量图里。
• 每个 step 都改变形状或结构，导致已经编译过的图难以复用。

排障顺序通常是：

1. 先关闭 torch.compile，确认 eager 路径本身正确。
2. 打开图日志或 profiler，确认 break 集中在什么位置。
3. 把热点前向中的 Python 杂质移出，或把不稳定的小段单独保留为 eager。

对于结构很稳定但某几段特别复杂的模型，可以只编译热点子模块，而非整模型“一把包住”。这类做法本质上属于区域化编译（regional compilation）：把最值得优化的几段先稳定下来，再决定是否继续扩大编译范围。

DDP 的基本形态是“每进程一份模型副本 + 反向时梯度同步”。启动建议使用 torchrun，它会为每个进程设置 RANK/ LOCAL_RANK/ WORLD_SIZE 等环境变量，并负责 rendezvous。

DDP 很少只靠 DDP(model, device_ids=[...]) 就结束。真实工程里最常被反复调整的是下面几项，它们直接关系到“会不会多做通信”“是否能兼容动态分支”“显存里梯度长什么样”。

命令/API/函数 broadcast_buffers 说明 控制 rank0 的 buffer 是否在前向时广播到其它 rank。典型 buffer 包括 BatchNorm 的 running mean/var 这类不参与梯度更新、但会影响推理语义的状态。 示例 Python 1 2 3 4 5 6 7 model = DDP(     model,     device_ids=[local_rank],     output_device=local_rank,     # 带 BatchNorm 或其它运行时 buffer 的模型通常保留 True，避免各 rank 状态漂移。     broadcast_buffers=True, )

命令/API/函数 find_unused_parameters 说明 让 DDP 在反向图里查找“这一步没参与 loss 的参数”。只在动态图、MoE、条件分支这类场景下启用；结构固定的模型尽量保持关闭，避免额外遍历和同步开销。 示例 Python 1 2 3 4 5 6 model = DDP(     model,     device_ids=[local_rank],     # 只有确实存在条件分支/按样本走不同子图时才打开。     find_unused_parameters=True, )

命令/API/函数 static_graph 说明 告诉 DDP 每一步参与反向的参数集合与图结构都稳定不变。对固定结构训练，这能减少内部图分析开销，也更适合长时间稳定运行的预训练/微调任务。 示例 Python 1 2 3 4 5 6 model = DDP(     model,     device_ids=[local_rank],     # 只有在前向图和参数参与关系稳定时才启用。     static_graph=True, )

命令/API/函数 gradient_as_bucket_view 说明 让参数梯度直接视作通信 bucket 的视图，以减少梯度副本开销。它有助于省显存，但也要求脚本不要依赖“随手对 grad 做就地奇技淫巧”的旧习惯。 示例 Python 1 2 3 4 5 6 model = DDP(     model,     device_ids=[local_rank],     # 想进一步压缩梯度内存时可尝试；改梯度的自定义逻辑要先核对兼容性。     gradient_as_bucket_view=True, )

命令/API/函数 bucket_cap_mb 说明 控制梯度 bucket 的大小。bucket 太小会导致 all-reduce 次数变多，太大又会推迟通信启动时机；它本质上是在平衡“通信碎片化”与“通信重叠启动时机”。 示例 Python 1 2 3 4 5 6 model = DDP(     model,     device_ids=[local_rank],     # 大模型通信调优时常会显式试几个桶大小，而非完全沿用默认值。     bucket_cap_mb=50, )

命令/API/函数 register_comm_hook 说明 为 DDP 梯度通信注册自定义 hook，例如 fp16 梯度压缩、PowerSGD 或你自己的 bucket 处理逻辑。它属于高级优化位点，适合通信已经明显成为瓶颈时再动。 示例 Python 1 2 3 4 5 from torch.distributed.algorithms.ddp_comm_hooks.default_hooks import fp16_compress_hook   model = DDP(model, device_ids=[local_rank]) # 把 bucket 梯度先做 fp16 压缩再通信，牺牲部分数值冗余换带宽。 model.register_comm_hook(state=None, hook=fp16_compress_hook)

旧经验里常把 DDP 的关键参数概括成 broadcast_buffers、 find_unused_parameters 和 static_graph。但在新版实现里，还有三项更贴近工程语义的开关：初始化是否先同步一次完整状态、前向时是否同步 buffer、以及 unused 参数是否直接跳过 all-reduce。

这三项分别解决三类问题。 init_sync 解决“各 rank 初始状态是否真的一致”； forward_sync_buffers 解决“运行时 buffer 会不会逐步漂移”； skip_all_reduce_unused_params 解决“未参与本轮反向的参数还要不要同步”。最后这一项要格外保守，因为只要不同 rank 的 unused 参数集合不一致，就有卡死风险。

梯度累积下，如果仍然每个 micro-step 都让 DDP 正常反向，同步就会发生在每一次 backward() 上，前 \(N-1\) 个 micro-step 的 all-reduce 都是白做。 model.no_sync() 的作用，就是把这些中间步的通信推迟到最后一次真正需要更新前再发生。

如果你的训练已经使用了高阶框架（例如 Accelerate、Lightning、DeepSpeed），需要先确认框架是否已经替你做了这件事。手工再包一层 no_sync()，容易把同步节奏搞乱。

单机时 --standalone 足够；一旦进入多机，决定“能不能稳定拉起”的是 rendezvous 配置。关键参数包括：节点数、当前节点序号、主节点地址与端口，以及弹性重启相关设置。

排障时，先确认三件事：

• 所有节点看到的 --rdzv_endpoint 完全一致。
• --node_rank 从 \(0\) 开始连续编号，没有重复也没有跳号。
• 防火墙、容器网络、作业调度器没有把 rendezvous 端口挡住。

可维护性来自“把易变部分隔离出来”：模型定义、数据定义、运行时策略（AMP/compile/DDP）、以及 I/O（checkpoint/logging）。一个简单但可扩展的组织方式如下：

Transformers 在工程上提供了一套可组合的入口：模型与 tokenizer/processor 的加载与保存（ from_pretrained/ save_pretrained）、架构无关的 Auto* 工厂、训练循环（ Trainer/ TrainingArguments）、以及推理生成（ generate）与对话模板（Chat Template）。这一节只讲“如何编程接入与部署落地”，不展开算法原理。

from_pretrained 负责把“模型仓库或本地目录”解析成 Python 对象；save_pretrained 把对象序列化回一个可复用的目录。工程上把这个目录当作“可交付模型包”（artifact），它应当可被推理服务直接加载。

Transformers 的加载逻辑依赖“目录里有哪些标准文件”。同一个目录既可以来自 Hub 下载缓存，也可以来自 save_pretrained 导出。

离线/内网环境的最小做法是提前把模型仓库下载到本地目录，然后用本地路径调用 from_pretrained。需要让缓存落到指定盘符时，优先设置 Hugging Face Hub 的缓存环境变量（例如 HF_HUB_CACHE / HF_HOME）。

当模型仓库包含自定义 Python 实现，而该实现不在 Transformers 内建模型类集合里时，加载阶段往往需要显式打开 trust_remote_code=True。这核心是在允许仓库里的 Python 代码参与本地执行，因此应同时固定 revision 或 commit，避免同一个 repo name 在不同时间拉到不同行为的代码。

线上环境更稳的做法通常是：先在受控机器上把模型拉到本地、审计并冻结目录，再由服务侧只加载本地目录而非直接联网拉取。

Auto* 是“按配置自动选择具体实现”的工厂。工程上把它当作跨架构的稳定入口：你不需要在代码里硬编码某个模型类名，尤其是在需要频繁替换基座模型时。

命令/API/函数 AutoConfig 说明 读取/改写模型配置（层数、rope、token id 等） 示例 Python 1 2 from transformers import AutoConfig cfg = AutoConfig.from_pretrained("Qwen/Qwen3-0.6B")

命令/API/函数 AutoTokenizer 说明 加载 tokenizer（文本 → input_ids/attention_mask） 示例 Python 1 2 from transformers import AutoTokenizer tok = AutoTokenizer.from_pretrained("Qwen/Qwen3-0.6B", use_fast=True)

命令/API/函数 AutoProcessor 说明 多模态 processor（文本+图像/音频等统一预处理） 示例 Python 1 2 from transformers import AutoProcessor proc = AutoProcessor.from_pretrained("openai/clip-vit-base-patch32")

命令/API/函数 AutoModel 说明 只要 backbone 表示（不带任务头） 示例 Python 1 2 from transformers import AutoModel m = AutoModel.from_pretrained("bert-base-uncased")

命令/API/函数 AutoModelForCausalLM 说明 Decoder-only 生成（LLM 推理/微调） 示例 Python 1 2 from transformers import AutoModelForCausalLM m = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-0.6B")

命令/API/函数 AutoModelForSeq2SeqLM 说明 Encoder-Decoder 生成（翻译、摘要等） 示例 Python 1 2 from transformers import AutoModelForSeq2SeqLM m = AutoModelForSeq2SeqLM.from_pretrained("google-t5/t5-small")

命令/API/函数 AutoModelForSequenceClassification 说明 文本分类 示例 Python 1 2 from transformers import AutoModelForSequenceClassification m = AutoModelForSequenceClassification.from_pretrained("distilbert-base-uncased", num_labels=2)

命令/API/函数 AutoModelForTokenClassification 说明 序列标注（NER/词性标注等） 示例 Python 1 2 from transformers import AutoModelForTokenClassification m = AutoModelForTokenClassification.from_pretrained("bert-base-uncased", num_labels=9)

Tokenizer/Processor 把“原始输入”变成模型可消费的张量字典。文本模型通常用 tokenizer；视觉/语音/多模态模型往往用 processor，它内部可能组合 tokenizer + image/audio processor。

Trainer 把训练循环、评估、保存 checkpoint、日志与分布式协同做成统一入口。工程上最关键的是把 TrainingArguments 固化成可追溯的配置（写入 run_meta.json 或随 checkpoint 一起存档），并严格区分 “best checkpoint” 与 “last checkpoint”。

命令/API/函数 EarlyStoppingCallback 说明 当评估指标持续不改善时提前结束训练。它依赖 eval_strategy、 metric_for_best_model 与 load_best_model_at_end 形成闭环。 示例 Python 1 2 3 4 5 6 7 8 9 10 11 12 from transformers import EarlyStoppingCallback   callbacks = [     EarlyStoppingCallback(         # 连续 3 次评估都没有实质改善才停；         # 这个数字应该与 eval_steps / eval_strategy 一起理解。         early_stopping_patience=3,         # 0.0 表示“只要更好一点就算改善”；         # 若指标噪声很大，可以抬高阈值避免把抖动误判成提升。         early_stopping_threshold=0.0,     ) ]

命令/API/函数 trainer.train(resume_from_checkpoint=...) 说明 从最近一次或指定 checkpoint 恢复训练。恢复对象包括模型权重、optimizer、scheduler 与 trainer 状态。 示例 Python 1 trainer.train(resume_from_checkpoint="out_sst2/checkpoint-1200")

命令/API/函数 trainer.push_to_hub 说明 把训练好的模型包、tokenizer 与元数据直接推送到 Hub，适合把“训练完成 → 共享/部署制品”做成固定交付动作。 示例 Python 1 trainer.push_to_hub(commit_message="ship best checkpoint")

Transformers 官方 example 几乎都把训练脚本写成“若干 dataclass + HfArgumentParser”。这种写法的价值核心是把命令行、JSON 配置文件与 Python 对象统一到同一套字段定义上，便于实验复现、配置审阅与批量跑任务。

Transformers 官方 example 脚本的共同特点是：它们不仅调用一次 trainer.train() 就结束，还把“发现已有 checkpoint”“决定从哪里恢复”“把 metrics 写进磁盘”“把 trainer 状态单独持久化”做成固定套路。这样训练目录才既能续跑，又能给后续回归分析留下证据。

save_metrics、 save_state 和 save_model 对应三种不同产物：指标、训练状态、模型制品。把它们混成“反正都保存一下”会让训练目录变得难以审计。

Trainer 做评估时，真正容易炸显存的环节常常是“把所有 logits 攒起来再交给 compute_metrics”。官方脚本里更稳的做法是把这三件事配合起来：训练前先做一次 sanity eval，评估阶段分批把张量搬回 CPU，并在进入 metric 计算前先把巨大的 logits 压缩成更小的统计表示。

这组配置的工程价值很高。 eval_on_start=True 解决的是“脚本刚启动就知道评估链路通不通”； eval_accumulation_steps 解决的是“评估张量怎么分批落回 CPU”； preprocess_logits_for_metrics 解决的是“没必要把整块 logits 都存下来”。三者配合后，大评估集上的 Trainer 稳定性会明显好很多。

数据集预处理阶段负责“样本级转换”，collator 负责“把一批样本组装成可喂给模型的 batch”。这层分工非常关键：padding、mask 构造、label pad id 处理都应该放在 collator，而非硬塞进 Dataset.map。

命令/API/函数 default_data_collator 说明 几乎不做智能处理，只把同名字段堆起来。适合样本长度已经统一、或数据本身就是张量的任务。 示例 Python 1 2 3 4 5 6 7 8 9 from transformers import default_data_collator   trainer = Trainer(     model=model,     args=args,     train_dataset=tokenized_ds,     # 数据已经预先 pad 好时，用最朴素的拼 batch 方式即可     data_collator=default_data_collator, )

命令/API/函数 DataCollatorForLanguageModeling 说明 语言模型任务的专用 collator。对 MLM 会随机打 mask；对 Causal LM 则常用于统一 padding 与 label 对齐。 示例 Python 1 2 3 4 5 6 from transformers import DataCollatorForLanguageModeling   collator = DataCollatorForLanguageModeling(     tokenizer=tok,     mlm=False,   # decoder-only Causal LM 训练时不做 masked LM，改为直接预测下一个 token )

命令/API/函数 DataCollatorForSeq2Seq 说明 Encoder-Decoder 任务的专用 collator，会同时处理 encoder 输入与 decoder labels，并把 label padding 位置改成 -100 以避开 loss。 示例 Python 1 2 3 4 5 6 7 from transformers import DataCollatorForSeq2Seq   collator = DataCollatorForSeq2Seq(     tokenizer=tok,     model=model,            # 传入模型后，collator 能结合模型配置处理 decoder 侧细节     label_pad_token_id=-100 # 交叉熵会忽略 -100，对变长目标序列尤为关键 )

摘要、翻译这类 Encoder-Decoder 任务，评估时往往需要真的跑一次 generate() 再计算 ROUGE/BLEU。此时更合适的入口是 Seq2SeqTrainer 与 Seq2SeqTrainingArguments，因为它们把“验证阶段是否调用生成”做成了显式配置。

做 Causal LM 预训练或继续预训练时，数据并不总是一条样本对应一条训练序列。官方 example 更常见的做法是先 tokenize，再把多个短文本拼成长 token 流，按固定 block_size 切块。这一步决定了上下文利用率，也决定了 label 的构造方式。

这类训练里真正的“右移一位”通常由模型内部 loss 逻辑完成，因此数据侧只需要准备与 input_ids 形状一致的 labels。不要在数据预处理阶段再手工 shift 一次，否则会错位两次。

Trainer 的保存逻辑至少有三种语义：最近一次保存的 last checkpoint，用于恢复训练；指标最优的 best checkpoint，用于上线或离线评测；以及人为指定导出的最终目录。不要把它们混成一个概念，否则“能续训”与“该上线谁”会互相污染。

如果任务真正关心的是生成质量而非 teacher forcing loss， metric_for_best_model 应切到 ROUGE、BLEU、F1、EM 之类更贴近业务目标的指标，而非机械盯住 eval_loss。

generate 把“下一 token 分布 → 序列”的解码策略（贪心、beam、采样等）封装成统一入口。工程上建议把生成策略固化为 GenerationConfig（或写入服务端配置），避免在业务代码里散落大量参数。

参数	作用	工程建议
max_new_tokens	限制生成 token 数	优先用它而非 max_length（后者包含 prompt token）。
do_sample	采样开关	需要稳定输出时关闭采样，并把 temperature=0 或直接不用 temperature。
temperature / top_p	采样随机性与截断	线上服务通常把它们做成可配置策略，按业务风险控制随机性。
eos_token_id / pad_token_id	结束与 padding 的 token id	Decoder-only 模型常需要显式设置 pad_token（一般等于 eos_token）。

GenerationConfig 可以作为独立配置保存和加载。这样“模型权重”与“默认生成策略”就能一起版本化，服务端也能明确区分“模型默认值”和“请求级覆盖值”。

推理栈里常见的优先级顺序是：请求级参数覆盖 GenerationConfig，而 GenerationConfig 再覆盖模型内建默认值。把这层关系说清楚，线上回归时才知道到底是谁改了输出风格。

generate() 默认等整段输出完成后才返回。做交互式 CLI、Web UI 或流式 API 时，更常见的写法是把 token 增量交给 streamer 对象，再由外层线程或事件循环持续消费。

命令/API/函数 TextStreamer 说明 最简单的 stdout streamer，适合命令行 demo 或快速验证 chat template 与生成配置是否正常。 示例 Python 1 2 3 4 5 6 7 8 from transformers import TextStreamer   streamer = TextStreamer(     tok,     skip_prompt=True,         # 交互场景通常不希望把原 prompt 再打印一遍     skip_special_tokens=True, # 避免把 eos、role token 直接暴露到终端输出 ) _ = model.generate(**inputs, max_new_tokens=128, streamer=streamer)

命令/API/函数 TextIteratorStreamer 说明 把增量文本暴露成可迭代对象，适合接到 WebSocket、SSE 或自定义前端事件流。 示例 Python 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 from threading import Thread from transformers import TextIteratorStreamer   streamer = TextIteratorStreamer(tok, skip_prompt=True, skip_special_tokens=True) thread = Thread(     target=model.generate,     # generate 放后台线程跑，前台持续取流     kwargs={**inputs, "max_new_tokens": 128, "streamer": streamer}, ) thread.start()   for chunk in streamer:     # Web 服务里这里通常会改成 yield SSE / WebSocket send     print(chunk, end="", flush=True)   thread.join()

命令/API/函数 AsyncTextIteratorStreamer 说明 面向 async 应用，把流式输出对接到异步事件循环。适合 FastAPI、Starlette 这类 async 服务框架。 示例 Python 1 2 3 4 from transformers import AsyncTextIteratorStreamer   # async 服务用它更容易接 Response streaming streamer = AsyncTextIteratorStreamer(tok, skip_prompt=True, skip_special_tokens=True)

streamer 解决的是“输出如何增量交付”，不改变底层解码算法。真正接服务时，还需要额外处理取消请求、超时、中断清理和背压。

Chat Template 把“messages 列表”转换成模型需要的 prompt 格式，并确保 role token、分隔符与结束符一致。工程上建议统一通过 apply_chat_template 生成输入，避免手工拼 prompt 导致格式漂移。

在 Hugging Face 生态里，chat template 往往直接存放在 tokenizer 配置中，本质上是一段模板字符串，很多模型实际使用的是 Jinja2 风格模板。它定义 role 顺序、system/user/assistant 分隔符、工具调用片段、结束符以及是否在末尾补 assistant 起始标记。

新版本 Transformers 中， apply_chat_template 不再只是返回 input_ids，而更倾向返回一个完整的 batch 结构。这样可以把 attention_mask、多模态输入和模板相关字段一起传给 generate()。如果模型模板支持工具调用，模板上下文里还可能读取 tools 之类的变量。

默认的 add_generation_prompt=True 语义是“在模板末尾再补一个 assistant 起始标记，然后让模型开始回答”。有些任务希望模型直接续写最后一条未完成消息，并不需要新开一条 assistant 消息，例如 JSON 片段补全、代码补全或工具参数半成品续写。此时更合适的入口是 continue_final_message=True。

这和 add_generation_prompt=True 是两套不同语义，通常不应同时使用。前者是在模板末尾新开一个 assistant 轮次，后者是在已有消息内部继续补全。

工具调用模型的真正难点不在于“把工具 schema 塞进 prompt”，而在于把一轮工具调用走完整：模板注入工具定义，模型返回结构化调用意图，应用侧执行真实工具，再把 tool 结果追加回消息历史，最后继续生成。只展示一次性 generate() 往往会漏掉最关键的执行语义。

这条链路一旦确定，训练数据、离线评测和线上服务最好都沿用同一套消息格式。否则就会出现线上是工具调用模板，训练集却只是普通对话模板的格式漂移问题。

如果模型的 tokenizer 自带 chat template，SFT 数据建议按同一模板构造训练样本；否则推理时的对话格式会与训练时不一致，表现为“角色混淆”“结束符异常”“输出风格漂移”。

大模型加载的关键旋钮是：把权重放在哪（GPU/CPU/磁盘）与用什么 dtype（fp32/fp16/bf16）。 device_map="auto" 会尝试把层自动分配到设备上，通常需要安装 accelerate； torch_dtype="auto" 会按权重与硬件能力选择合适 dtype。

现象	根因	修复动作
ImportError: Using device_map requires Accelerate	启用了 device_map，但环境缺少 accelerate	安装 pip install -U accelerate，或移除 device_map 并手动 model.to(device)。
Decoder-only 推理报 padding 相关错误	tokenizer 没有 pad_token	tok.pad_token = tok.eos_token，并设置 pad_token_id。
推理输出乱码或 EOS 提前结束	tokenizer 与模型不匹配，或 chat template 不一致	确保 tokenizer 与模型来自同一目录；推理统一用 apply_chat_template。
本地目录加载失败（找不到 config/tokenizer）	目录并非标准模型包结构	用 model.save_pretrained 与 tok.save_pretrained 导出；检查是否存在 config.json。
OOM 或极慢	dtype/设备放置策略不合理	优先 torch_dtype="auto" + device_map="auto"；必要时启用更强的推理引擎（vLLM/TensorRT-LLM）。
加载第三方模型需要 trust_remote_code=True	模型仓库包含自定义 Python 代码	在受控环境中审计代码后再开启；离线导出时固定 commit hash，避免代码漂移。

参数高效微调（Parameter-Efficient Fine-Tuning, PEFT）的工程核心是把“可训练参数”从完整模型权重中剥离出来：训练与分发只关心适配器（adapter）的小文件，线上推理再把适配器挂到同一个 base checkpoint 上复用。这样既减少训练时的显存与优化器状态开销，也把多任务/多域适配的存储成本压到可控范围。

PEFT、Transformers、TRL 与 bitsandbytes 在接口上是强耦合组合。工程上以“同一套 requirements 锁定版本”作为默认策略，避免出现 PEFT 与 Transformers 的适配器注入逻辑不一致、或 TRL 的 Trainer 参数签名变化导致脚本失效。

PEFT 的存储与加载分两层：

• base：Transformers 模型原始 checkpoint（通常很大、可复用、版本需固定）。
• adapter：PEFT 生成的小文件（含 adapter_config 与 adapter weights），可多份并存，用于不同任务/域。

标准做法是：训练输出目录只保存 adapter；上线推理时先加载 base，再加载 adapter。这样 adapter 目录可被当作“制品”（artifact）管理，支持灰度、回滚与多 adapter 切换。

命令/API/函数 LoraConfig 说明 LoRA/QLoRA 的配置对象 示例 Python 1 2 3 4 5 6 7 8 9 10 11 12 13 14 from peft import LoraConfig, TaskType   cfg = LoraConfig(     # 指明这是 decoder-only 语言模型，PEFT 会按自回归任务布置 adapter     task_type=TaskType.CAUSAL_LM,     # rank 决定低秩分支容量；r 越大，参数量和适配能力越强     r=16,     # alpha 控制低秩更新的缩放强度，避免 adapter 更新过弱     lora_alpha=8,     # 对 LoRA 分支做轻度 dropout，用来缓和微调过拟合     lora_dropout=0.05,     # 优先覆盖注意力投影层；模块名必须和模型源码一致     target_modules=["q_proj", "k_proj", "v_proj", "o_proj"], )

命令/API/函数 get_peft_model 说明 把 base model 包装成可训练的 PeftModel 示例 Python 1 2 from peft import get_peft_model peft_model = get_peft_model(base_model, cfg)

命令/API/函数 PeftModel.from_pretrained 说明 给已加载的 base model 挂载某个 adapter 示例 Python 1 2 from peft import PeftModel model = PeftModel.from_pretrained(base_model, "adapter_dir")

命令/API/函数 model.load_adapter / model.set_adapter 说明 在同一 base 上继续挂载其它 adapter，并显式切换当前激活的 adapter。多域推理与灰度切换时非常高频。 示例 Python 1 2 model.load_adapter("adapter_b", adapter_name="b") model.set_adapter("b")

命令/API/函数 model.add_adapter 说明 在当前 base 上新增一份全新的 adapter 配置，常用于“一个底座上继续开第二条训练线”。 示例 Python 1 2 3 4 5 6 7 8 cfg_b = LoraConfig(     task_type=TaskType.CAUSAL_LM,     r=8,     lora_alpha=16,     lora_dropout=0.05,     target_modules=["q_proj", "v_proj"], ) model.add_adapter("domain_b", cfg_b)

命令/API/函数 model.save_pretrained 说明 保存 adapter（不覆盖 base） 示例 Python 1 model.save_pretrained("adapter_out")

命令/API/函数 model.merge_and_unload 说明 把 adapter 合并进 base 权重并卸载 adapter（用于导出单体权重） 示例 Python 1 merged = model.merge_and_unload()

命令/API/函数 model.merge_adapter / model.unmerge_adapter 说明 临时把当前 adapter 合并进 base，再按需撤销。适合做“先合并测一下吞吐/精度，再回到可切换 adapter 结构”的实验。 示例 Python 1 2 3 model.merge_adapter() # ... 在当前进程里做一轮延迟/显存/质量验证 ... model.unmerge_adapter()

命令/API/函数 prepare_model_for_kbit_training 说明 把量化后的 base 调整到可训练状态，通常在 QLoRA 里和 BitsAndBytesConfig 一起出现。 示例 Python 1 2 3 from peft import prepare_model_for_kbit_training   base = prepare_model_for_kbit_training(base)

命令/API/函数 AutoPeftModelForCausalLM 说明 把“adapter 目录 + 记录在配置里的 base 身份”直接还原成完整可推理对象，适合把 adapter 目录当成制品交付。 示例 Python 1 2 3 4 5 6 7 from peft import AutoPeftModelForCausalLM   model = AutoPeftModelForCausalLM.from_pretrained(     "adapter_out",     torch_dtype="auto",     device_map="auto", )

命令/API/函数 get_peft_model_state_dict / set_peft_model_state_dict 说明 只提取或恢复 adapter 相关参数，便于接自定义 checkpoint、FSDP 或分片保存系统。 示例 Python 1 2 3 4 from peft import get_peft_model_state_dict, set_peft_model_state_dict   adapter_state = get_peft_model_state_dict(model) set_peft_model_state_dict(model, adapter_state)

命令/API/函数 model.print_trainable_parameters 说明 自检：确认“只训练 adapter”而非误训全参 示例 Python 1 model.print_trainable_parameters()

当 LoRA 训练同时动到了 embedding 层，或者训练过程中做过 resize_token_embeddings，单纯保存 adapter 增量并不总是足够。PEFT 的 save_pretrained(..., save_embedding_layers=...) 用来显式控制“是否把 embedding 层也随 adapter 一起保存”。这在加新 token、改词表或把 embedding 本身纳入 target_modules 时尤其关键。

这并非“目录大小优化”这么简单。若训练时扩过词表，但导出时没把相关 embedding 状态带走，推理侧最常见的后果就是：tokenizer 已经认识新 token，模型权重却没有与之对应的 embedding 或输出头权重。

有些 adapter 路线在加载、合并或切换阶段会出现“CPU 太慢，但常驻 GPU 又太贵”的矛盾。PEFT 提供的 ephemeral_gpu_offload 属于折中方案：平时仍把主要状态放在 CPU/低成本位置，但在关键装配步骤临时借用 GPU，加速权重处理过程。

这类参数优化的是“加载/装配路径”，并非训练吞吐主路径。只有当你真的遇到 adapter 加载或 merge 很慢、而机器又有可借用 GPU 时，它才值得作为工程旋钮引入。

LoRA（Low-Rank Adaptation）通过对线性层权重施加低秩增量，让可训练参数规模与显存开销显著下降。实际工程难点集中在两处：target_modules 怎么选，以及如何保存/加载/合并。

target_modules 是 LoRA 注入的“模块名匹配规则”，用于指定 base 模型里哪些子模块会被替换/包裹。这一选择与“按层类型挑选线性层”不同：它依赖模型内部的命名约定。不同架构的模块命名差异很大（Llama 系列常见 q_proj/k_proj/v_proj/o_proj，也有模型用 Wq/Wk/Wv/Wo 或把投影层藏在自定义块里）。稳定做法是先枚举可疑线性层，再按名字筛选。

LoRA 常见的注入策略是“注意力投影层优先”：先只覆盖 attention 的 Q/K/V/O，再根据效果与显存预算扩展到 FFN 的投影层（例如 gate/up/down）。

adapter 之外偶尔需要训练额外模块（例如分类头、语言模型的 lm_head、或新加 token 的 embedding）。这类模块可以通过 modules_to_save 声明为可训练并随 adapter 一起保存，避免“训练时更新了头部，但保存的 adapter 不包含它”的上线故障。

PEFT 支持一个 base 上挂多份 adapter，并在推理时切换 active adapter。这种能力适合“同一底座，多业务域”的线上形态。

多 adapter 系统里，真正困难的是在训练、评估、A/B 和回收阶段精确控制它们。PEFT 在这方面给了几组很实用的生命周期接口：

is_trainable 决定加载完成后 adapter 是“默认参与训练”还是“默认按推理态挂载”； autocast_adapter_dtype 决定是否把 adapter 权重提升到更稳的 dtype； selected_adapters 则决定最终导出哪些 adapter。三者分别控制的是训练态、数值态和制品态。

这组接口的工程意义很直接：线上多租户场景要切域能力，实验阶段要做 base vs adapter 对照，持续训练时要只放开某几份 adapter，回收旧版本时要清理驻留对象。没有这层生命周期控制，最终只会得到一堆“目录里能存文件，但系统行为不可控”的 adapter 包。

当两份 adapter 分别学习了不同域能力，而业务又希望在同一个请求里组合它们时，PEFT 提供了“先加载多份 adapter，再按权重生成一份组合 adapter”的路线。这种做法常用于实验性融合、域能力叠加或上线前的快速拼接验证。

加权组合的本质仍然是“线性组合若干已存在的 adapter 参数”。它并非魔法平均，也不会自动解决词表、模板、任务定义不一致的问题；只有当几份 adapter 共享同一个 base、相近注入位置和可兼容任务语义时，这条路才有意义。

add_weighted_adapter 不只有“给两份 adapter 配个权重”这么简单。它背后对应的是一组不同的组合算法，而不同算法对 rank、一致性和内存峰值有明确要求。

组合类型	适用语义	工程约束
linear	最直接的线性加权，适合“几份 LoRA 语义接近，只想做平滑融合”	参与融合的 adapter 通常需要相同 rank，否则组合会直接失去可比性
cat	把多个 adapter 的低秩空间直接拼接到更高 rank 的新 adapter	结果 rank 约等于各 adapter rank 之和，容量会变大，显存与导出体积也会同步增加
ties / dare_ties / magnitude_prune	更偏“从多个 adapter 中抽取共识或高价值权重”	通常要配合 density 一起用，density 表示保留多大比例的权重信息
svd / *_svd	先合成，再通过 SVD 压回目标 rank	更像“压缩后的融合”，但对 dtype 与数值稳定性更敏感，低精度环境里要额外验证

选择组合类型时，先问清楚目标是什么：是做离线实验、希望快速看到两域混合效果；还是想交付一份稳定可部署的新 adapter。前者可以容忍更激进的组合方式，后者通常更偏向 linear 或经过充分验证的稀疏化融合。 cat 的风险尤其工程化，因为它会直接拉高 rank，导致后续训练、保存与推理都变重。

如果组合完成后还要按样本级切换 adapter_names，需要先确认当前模型没有处于 merged 状态。部分组合、merge 与多 adapter 路径是互斥的，先 merge 后再按请求细切换，通常只会把系统带进不可逆状态。

如果 adapter 目录已经完整记录了 base 模型身份与 PEFT 配置，加载时不一定要先手工恢复 base，再显式 PeftModel.from_pretrained。PEFT 提供了 AutoPeftModel* 家族，把“还原整个 adapter 制品”做成统一入口。

复杂训练栈里，adapter 状态并不总是通过 save_pretrained 直存直取。做 FSDP、分片保存、或和自定义 checkpoint 体系对接时，往往需要直接拿到“只包含 PEFT 参数”的状态字典。

merge_and_unload() 用于把 LoRA 权重写回 base 权重，再移除 adapter 结构，得到“标准 Transformers 模型结构”。工程上这通常用于：

• 导出到单体 checkpoint（例如给不支持 adapter 的推理引擎）。
• 降低线上复杂度（不需要两段加载与 adapter 切换）。

合并前需要确认 base 权重处于可写入的浮点 dtype（fp16/bf16/fp32）。对 4-bit 量化权重，合并通常不作为默认路径。

这三个接口名字接近，但交付语义完全不同。实际项目里最常见的错误，就是把 merge_and_unload() 当作一个“随时可以撤销”的性能开关。

接口	会发生什么	适合什么场景
merge_adapter()	把当前 adapter 临时合到 base 权重里，但仍保留 adapter 结构与回退能力	做基准测试、对比 merged 与 unmerged 性能，或暂时消除推理期 adapter 额外开销
unmerge_adapter()	撤销前一次 merge_adapter() 的效果，回到“base + adapter”分离态	实验阶段切回可编辑、可切换 adapter 的状态
merge_and_unload()	返回一个新的、已经写回 adapter 权重的标准模型对象，并移除 PEFT 包装	导出单体权重，交给不理解 adapter 的推理后端或交付团队
unload()	直接去掉 adapter，不做权重合并	只想回到 base 模型做对照，或清理对象状态

从对象生命周期看， merge_adapter() 仍然站在“PEFT 世界”里，保留了继续切换、反向撤销与再保存 adapter 的空间； merge_and_unload() 则直接跨到“普通 Transformers 模型”的世界里。后者更适合制品交付，前者更适合实验与排障。

QLoRA 的工程语义是：base 权重以 4-bit 量化形式加载并冻结，反向传播只更新 LoRA 参数；量化层负责把反向信号“传递”到 LoRA，而非更新量化权重本身。

prepare_model_for_kbit_training 必须发生在 LoRA 注入之前，因为它负责冻结量化底座、处理某些层的 dtype 与训练标志，让后续注入的 adapter 建立在“已经准备好训练”的量化骨架上。顺序颠倒后最常见的问题是：LoRA 已经挂上了，但底层量化模块仍处于不适合训练的状态。

这个函数的重要性不在“名字看起来像初始化工具”，而在它确实会改模型状态。工程上至少要把它理解成四件事：

• 冻结 base 参数。QLoRA 的核心前提就是“量化底座不更新，只让 LoRA 学”。如果这一步没发生，训练就会悄悄滑向“低比特全参微调”，显存、数值稳定性和保存语义都会变坏。
• 处理 layer norm、embedding 等层的 dtype 与训练标志。这样做的目的核心是让低比特底座上的前向与反向路径更稳定。
• 为 gradient checkpointing 和输入梯度路径做准备。很多长上下文 QLoRA 脚本把这一步和 gradient checkpointing 绑定考虑，本质上是在给“可训练 LoRA + 低比特底座”这条路径收拾好反向传播现场。
• 建立后续保存/恢复的前提。LoRA 注入后之所以还能清晰地区分“哪些是 adapter，哪些是 base”，前提正是底座已经被预处理为冻结状态。

因此， prepare_model_for_kbit_training 不该被理解成一个可有可无的 helper。它更接近“把普通量化模型变成可做 QLoRA 训练的骨架”的入口。

• 合并策略：4-bit 量化权重通常不作为合并目标。需要单体权重时，常见流程是“重新加载 fp16/bf16 base → 挂载 adapter → merge → 导出”。
• 训练开关：Decoder-only 模型训练时常需要关闭 use_cache，并配合 gradient checkpointing 控制显存。
• 部署形态：adapter 目录天然适合做制品；量化 base 属于环境相关资产（与推理后端、算子实现与硬件强相关），需要独立版本管理。

量化后端	训练期常见形态	导出与 merge 判断
bitsandbytes 4-bit / 8-bit	最常见的 QLoRA 训练底座	训练期可以挂 LoRA；需要单体权重时，通常回到浮点 base 再 merge，而非直接在量化权重上产出最终制品
GPTQ / AWQ	更偏推理期量化制品	很多真实工作流把它们当部署格式而非训练骨架，LoRA 合并与继续训练路径通常更受限
AQLM / HQQ / 其它非常规低比特后端	需要核对专门兼容路径	优先把 adapter 作为独立制品管理，除非文档明确说明支持 merge；否则更稳的做法是分离保存而非强行写回量化权重

这一层判断的核心只有一句话：训练骨架和部署制品并非同一个概念。很多量化后端非常适合把推理显存压下来，却并不天然适合做“最终 merge 交付”的承载格式。

IA3（Infused Adapter by Inhibiting and Amplifying Inner Activations）通过在注意力与前馈模块中注入少量可训练向量来缩放激活值。它的可训练参数通常比 LoRA 更少，适合“极低成本的快速适配”场景。

Prompt tuning 把“要学习的东西”压缩为一段可训练的虚拟 token embedding（virtual tokens），base 权重保持冻结。它的工程接口与 LoRA 不同：训练的是提示向量，并非注入线性层的低秩权重。

Prompt tuning 的数据组织更接近“提示 + 输入 + 输出”的模板化任务。工程上需要明确：提示文本、虚拟 token 数量、以及 tokenizer 的特殊 token 处理方式，三者必须一致，否则会出现训练可收敛但推理表现异常的对齐问题。

Transformers 在模型类上集成了适配器管理接口，典型能力包括 add_adapter、 load_adapter、 set_adapter 与适配器保存。LoRA/IA3/AdaLoRA 属于常见的“直接集成”方法；prompt tuning 等提示类方法通常直接用 PEFT 库完成更稳定。

TRL 的 Trainer（SFT/DPO/GRPO/PPO 等）工程上更适合把 PEFT 当作“模型构造步骤”：先用 Transformers 加载 base，再用 PEFT 包一层 adapter，把得到的 PeftModel 直接传给 TRL Trainer。这样可以绕开不同 TRL 版本对 peft_config 参数支持度不一致的问题。

PEFT 原生 API 适合需要精确控制模型对象、adapter 生命周期和 checkpoint 语义的工程；Unsloth、LLaMA-Factory、Axolotl 这类工作台则把常见微调路径封装成配置和命令。它们的价值在于减少重复脚本，让团队用同一套配置描述模型、数据、模板、LoRA、量化、训练参数和导出路径。

工作台	主要能力	适合用法
Unsloth	低显存 LoRA/QLoRA、快速 SFT、本地推理与 GGUF/Ollama/vLLM 导出路径。	单卡或少卡快速验证数据、模板和 adapter 效果。
LLaMA-Factory	用 YAML、CLI 和 WebUI 管理 SFT、RM、DPO、PPO、导出与 merge。	希望把训练配方交给配置文件管理，减少手写 Trainer 脚本。
Axolotl	复杂 QLoRA/FSDP 配方、sample packing、DPO/GRPO、vLLM 协作。	需要更细粒度控制训练数据拼接、分布式策略和后训练组合。

Unsloth 更适合把“底座加载、量化、LoRA 注入、训练、保存、导出”压成短路径。它常用于先验证数据清洗、chat template、target modules 和学习率是否合理，再决定是否迁移到更完整的分布式训练系统。

LLaMA-Factory 的核心使用方式是把训练语义写进 YAML。模型、数据集、chat template、微调方法、LoRA 参数、batch、学习率、输出目录都在同一个文件中声明，CLI 只负责读取配置并启动训练。

这类配置化路线的关键是把“训练语义”和“运行方式”分开。YAML 描述这次训练到底做什么；Accelerate、DeepSpeed 或 FSDP 配置描述它如何在硬件上运行。排查问题时两份配置都要看，不能只看 Python 调用栈。

Axolotl 更偏向把复杂微调配方显式化。它适合需要 QLoRA、FSDP、sample packing、多数据集混合和后训练路线组合的场景。配置能力越强，对字段语义的要求越高，尤其是 chat_template、 sequence_len、 sample_packing、 adapter 这些字段。

sample_packing 追求的是 token 利用率。开启后，一个训练序列里可能包含多个样本，吞吐通常更好，但逐条样本排错、label 对齐和 loss 解释会更难。正式实验应同时保留一份不 packing 的小验证集，用来排查模板和答案边界。

语言模型强化学习（Reinforcement Learning for Language Models）发生在 SFT 之后。SFT 让模型学会按照示例回答，RL 后训练让模型在生成过程中接受奖励信号约束，把“回答是否有用、是否正确、是否符合格式、是否遵守工具协议”转成可优化的目标。

SFT（Supervised Fine-Tuning）使用人工写好的目标答案做交叉熵训练。训练样本通常是一个 prompt 和一个 target answer，模型只需要提高目标 token 的似然。RL 后训练的输入仍然可以是 prompt，优化对象变为模型自己生成的回答集合、奖励函数、参考模型约束和策略优化算法。

一条典型链路如下：

这一步的核心变化是训练目标从“模仿一个答案”变为“在可采样空间里提高高奖励回答的概率，同时限制策略漂移”。因此 RL 后训练同时牵涉推理引擎、分布式训练、奖励计算、样本队列和 checkpoint 恢复。

Rollout 指策略模型在当前参数下对 prompt 进行采样，生成一个或多个完整 response，并记录训练需要的中间量。对于机器人控制，轨迹由状态、动作、奖励组成；对于语言模型，动作就是生成下一个 token，状态就是已有上下文，轨迹就是 prompt 后面的一串 response tokens。

语言模型 rollout 的最小结构可以写成：

字段	含义	工程用途
prompt	输入问题、工具调用上下文或多轮对话历史。	用于构造模型输入，也用于 reward function 解析任务条件。
response	当前 policy 采样出的回答 token 序列。	reward、KL、log probability、长度统计都围绕 response 计算。
old_log_probs	采样当时当前 policy 对每个 response token 的对数概率。	PPO/GRPO 更新时计算概率比值，避免策略一次更新过大。
ref_log_probs	reference model 对同一 response token 的对数概率。	计算 KL 惩罚，限制 RL 把模型推离 SFT 分布太远。
reward / score	reward function 或 reward model 给出的标量或 token-level 分数。	决定这条回答应该被鼓励还是压低概率。
advantage	相对同组回答、baseline 或 value function 的优势值。	把“绝对分数”转成“这条回答比预期好多少”。
response_mask	标记哪些位置属于 response，哪些位置只是 padding。	loss、KL、reward 聚合时排除 prompt 和 padding。

Rollout 的质量直接决定 RL 训练质量。采样温度过高会带来大量低质量噪声，温度过低会导致同一个 prompt 的多个 response 太相似，GRPO/RLOO 这类组内比较方法就缺少有效差异。工程上常同时监控 response 长度、成功率、格式错误率、重复率、KL 和 reward 方差。

语言模型 RL 是多角色系统。一个完整 PPO/RLHF 系统至少包含 policy、reference、reward，使用 PPO 时通常还包含 critic。

角色	训练状态	作用
Policy / Actor	可训练	真正被更新的语言模型。rollout、log probability 和最终部署都围绕它。
Reference	冻结	通常是 SFT 后的初始模型。计算 KL 约束，防止 policy 为了 reward 牺牲语言质量。
Reward Function / Reward Model	通常冻结	把回答映射成分数。可由规则、单元测试、人工偏好模型、格式检查、多目标加权组成。
Critic / Value Model	可训练	估计当前状态下的期望回报，为 PPO 的 GAE 提供 baseline，降低梯度方差。
Rollout Engine	服务组件	vLLM、SGLang 或 HF generation。负责高吞吐生成和新权重同步。

Reference 和 reward 的存在解释了 RLHF 框架为什么比 SFT 框架复杂。SFT 只需要训练模型前向、反向和优化器；RLHF 还要在训练期间反复调用推理引擎生成样本，并把 actor 的新权重同步给 rollout engine。

奖励函数（Reward Function）是 RL 后训练最关键的设计点。它决定模型优化什么，也决定模型会钻哪些空子。奖励函数可以来自规则、模型、工具执行结果、人工偏好、检索一致性或多目标加权。

奖励来源	适用任务	主要风险
规则奖励	数学答案、JSON 格式、工具协议、正则可验证输出。	覆盖不完整时容易 reward hacking。
单元测试 / 沙箱	代码生成、SQL、Agent 工具调用。	执行成本高，超时和安全隔离必须严格。
Reward Model	开放式问答、摘要、偏好对齐。	reward model 偏差会被 policy 放大。
LLM-as-a-Judge	难以写硬规则的质量评估。	成本、稳定性、提示词泄漏和 judge 偏差。
多目标加权	正确性、格式、简洁性、安全性同时约束。	权重尺度不一致时，某个目标会吞掉其他目标。

奖励函数需要先单元测试，再接入训练。单元测试至少覆盖正确答案、错误答案、格式正确但内容错误、格式错误但内容接近、空回答、超长回答和恶意输出。训练中还要记录分项 reward，不能只看总 reward，否则很难定位 reward hacking。

原始 reward 只说明一条回答的得分，advantage 说明这条回答相对预期好多少。策略梯度更新依赖 advantage：正 advantage 提高该 response token 的概率，负 advantage 降低概率。

\[A_t = R_t - b_t\]

其中 \(A_t\) 是第 \(t\) 个 token 或轨迹位置的优势值，读作 advantage；\(R_t\) 是从该位置开始的回报；\(b_t\) 是 baseline，可以来自 critic、同组样本均值或规则估计。baseline 不改变期望梯度方向，但能显著降低方差。

GRPO 常在同一个 prompt 下采样多个 response，用组内均值做 baseline：

\[A_i = r_i - \frac{1}{G}\sum_{j=1}^{G} r_j\]

其中 \(G\) 是同一 prompt 的采样条数，读作 group size；\(r_i\) 是第 \(i\) 条 response 的奖励。这个形式不需要单独训练 critic，适合数学、代码、格式检查等规则奖励任务。

算法	核心思路	适用场景
PPO	用 old policy 和 new policy 的概率比做 clipped objective，配合 critic 估计 value。	经典 RLHF、reward model 训练链路完整、需要稳定收敛的场景。
GRPO	同一 prompt 采样多条 response，用组内相对分数构造 advantage，减少 critic 依赖。	RLVR、数学/代码等可验证任务，尤其适合多样本采样。
RLOO	Leave-one-out baseline。每条样本用同组其他样本均值作为 baseline。	同 prompt 多采样、希望降低组内估计偏差的场景。
REINFORCE++	基于 REINFORCE 的语言模型后训练改造，常配合 baseline、KL 和长度/格式控制。	规则奖励、推理任务、希望简化 value model 的场景。
DPO	直接使用偏好对，不做在线 rollout；优化 chosen 相对 rejected 的概率差。	偏好数据充足、希望避免在线 RL 系统复杂度的场景。

在线 RL 框架通常覆盖 PPO、GRPO、RLOO、REINFORCE++。DPO 更接近离线偏好优化，常放在 TRL、LLaMA-Factory、OpenRLHF 的 non-RL 训练入口里。工程选型时先判断是否需要在线采样：需要 rollout、工具交互、沙箱执行或动态 reward，就进入在线 RL；只有 chosen/rejected 数据，DPO/IPO/KTO 往往更简单。

指标	正常含义	异常信号
reward/score	任务目标正在改善。	快速上升但人工评估下降，通常是 reward hacking。
KL	policy 与 reference 的距离保持在预算内。	KL 爆炸表示策略漂移；KL 长期接近 0 表示学习太弱。
entropy	生成分布保留一定探索。	entropy 快速坍缩通常对应模板化、重复或过早收敛。
response_length	回答长度处在任务合理范围。	长度持续增长可能是模型学会用长答案骗 reward。
grad_norm	梯度规模可控。	突然尖峰常见于 reward 尺度失控、坏 batch 或数值溢出。
clipfrac	PPO 中被 clip 的 token 比例。	过高表示学习率或 advantage 尺度过大，更新被大量截断。
rollout throughput	推理引擎采样效率。	GPU 空转通常来自 vLLM batch、tensor parallel、sleep mode 或 Ray placement 配错。

RL 训练健康性不能只看 reward。reward、KL、长度、格式错误率和人工抽检需要一起读。reward 上升且 KL 稳定、长度稳定、格式错误下降，才更接近真实改进。

框架	优势	边界
TRL	Hugging Face 生态内最容易本地验证 DPO、PPO、GRPO、SFT。	大规模 Ray/vLLM/DeepSpeed 一体化能力较弱。
OpenRLHF	Ray + vLLM + DeepSpeed 组合明确，Hybrid Engine 和 Agent Paradigm 适合大规模在线 RL。	命令参数多，资源拓扑和版本组合需要严格管理。
verl	HybridFlow 把 RL 控制流与模型计算流解耦，适合研究新算法和复杂 rollout。	Hydra 配置体系较大，首次接入需要理解 DataProto 和 WorkerGroup。
OpenRLHF / verl + vLLM	rollout 吞吐高，适合多样本采样和长 response。	权重同步、KV cache、GPU memory utilization 是主要工程瓶颈。

OpenRLHF 面向大语言模型 RLHF/RLVR 后训练。它把 Ray、vLLM、DeepSpeed、Transformers 组合成一条在线 RL 管线：Ray 做角色调度，vLLM 做 rollout，DeepSpeed 做 actor/critic 训练，Transformers 负责模型加载与 Hugging Face checkpoint 兼容。

入口	阅读重点	工程意义
quick_start.rst	安装、层级 CLI、Qwen3 RLVR 首跑命令。	确认版本边界和最小可运行训练链路。
architecture.rst	Ray、vLLM、DeepSpeed、NCCL 的职责划分。	理解为什么 RLHF 训练需要多个角色和多个引擎。
agent_paradigm.rst	Single-turn、multi-turn、token-in-token-out、算法解耦。	理解工具调用和环境交互如何接入同一 RL loss。
hybrid_engine.rst	sleep mode、colocate_all、NCCL weight sync。	解决小集群上生成与训练互相空转的问题。
async_training.rst	async queue、partial rollout、off-policy correction。	在吞吐优先场景下重叠 rollout 与训练。
examples/python/math_reward_func.py	Python reward function 的输入输出协议。	把规则奖励接到在线 RLVR。
examples/python/agent_func.py	MultiTurnAgentExecutor 与 AgentInstanceBase。	把多轮环境、工具调用、反馈回路接入 rollout。

OpenRLHF 官方推荐在 NVIDIA PyTorch 容器中安装，原因是 RLHF 同时依赖 CUDA、NCCL、vLLM、FlashAttention、DeepSpeed 和 Ray。容器能减少二进制依赖冲突。

版本选择上，vLLM 是 rollout 性能核心，DeepSpeed 是 ZeRO-3 和大模型训练核心。使用 Muon 优化器时还要满足 DeepSpeed 的版本要求。生产环境不要混用随机升级的 vLLM、DeepSpeed、CUDA 镜像，应把容器 tag、pip freeze、训练脚本和 checkpoint 绑定保存。

OpenRLHF 的核心思想是角色拆分。Actor、Reference、Reward、Critic 和 vLLM engine 都可以独立映射到 GPU 资源池，也可以通过 Hybrid Engine 放在同一批 GPU 上分时运行。

组件	职责	常见瓶颈
Ray	提交 job、启动远程 actor、分配 GPU、管理 role placement。	placement 配错导致某些 GPU 空闲，或主节点内存被 driver 吃满。
vLLM	批量生成 rollout，维护 KV cache，接受 actor 权重同步。	KV cache 不够、batch 太小、tensor parallel 配置不匹配。
DeepSpeed	Actor/Critic 的 ZeRO-3 训练、参数/梯度/优化器状态分片。	ZeRO stage、offload、micro batch、gradient checkpointing 组合不当。
NCCL	训练端与 vLLM 端权重同步、GPU 间通信。	网络/NCCL 环境变量错误会卡在同步或 reduce。
Transformers	加载 Hugging Face 模型、tokenizer、chat template、checkpoint 结构。	special tokens、chat template 和 checkpoint 目录不一致。

OpenRLHF 的层级 CLI 把不同角色的参数放在不同前缀下，例如 --actor.*、 --reward.*、 --vllm.*、 --ds.*。这能避免大规模训练脚本里参数归属混乱。

前缀	控制对象	示例
--actor	可训练 policy 模型、优化器、梯度检查点。	--actor.model_name_or_path, --actor.adam.lr
--ref	冻结 reference policy 的节点和 GPU 数。	--ref.num_nodes, --ref.num_gpus_per_node
--reward	reward model 或 Python reward function。	--reward.remote_url
--vllm	rollout engine 数量、TP、显存预算、权重同步。	--vllm.num_engines, --vllm.tensor_parallel_size
--rollout	采样 batch、每 prompt 采样数、最长生成长度。	--rollout.batch_size, --rollout.n_samples_per_prompt
--algo	advantage、KL、动态过滤、off-policy correction。	--algo.advantage.estimator, --algo.kl.init_coef
--ds	DeepSpeed ZeRO、精度、packing、sleep mode。	--ds.zero_stage, --ds.param_dtype
--ckpt	checkpoint 保存、恢复、HF 导出。	--ckpt.path, --ckpt.save_hf

下面基于官方 Qwen3-4B RLVR 示例重写为工程注释版。命令展示的是“如何把 Ray job、actor、reward、dataset、vLLM、算法、DeepSpeed 和 checkpoint 接起来”。

OpenRLHF 的 Python reward function 接收完整 query、prompt 和 label，返回 rewards、scores 与 extra_logs。rewards 用于策略优化，scores 常用于动态过滤和指标记录。

OpenRLHF 的 Agent Paradigm 把“如何收集经验”和“如何更新 policy”拆开。Single-turn 只生成一次回答；multi-turn 会在环境中多步交互，每一步把模型 action、环境反馈、reward 继续拼成 token-level trajectory。

Hybrid Engine 解决 RLHF 的资源空转问题。生成阶段 vLLM 使用 GPU，训练阶段 DeepSpeed 使用 GPU。sleep mode 让二者在同一批 GPU 上分时占用显存。

Hybrid Engine 的调参顺序通常是先让脚本稳定跑通，再提高 vllm.gpu_memory_utilization、rollout batch、max tokens。OOM 时先降低 vLLM 显存比例和 micro batch，再考虑分离资源池。

同步训练按 rollout -> train -> rollout 交替执行。Async 让 rollout 和训练通过队列并行，Partial Rollout 进一步在权重同步时暂停和恢复 vLLM 请求。吞吐更高，但样本可能带有轻微 off-policy 噪声。

Async 不适合作为第一轮实验默认配置。先用同步 Hybrid Engine 验证 reward、KL、长度和正确率曲线，再切换 async 观察吞吐收益和收敛差异。

OpenRLHF 的 checkpoint 需要同时考虑 DeepSpeed 分片状态和 Hugging Face 可部署权重。训练中断恢复依赖 optimizer、scheduler、dataset progress；上线部署通常需要导出 HF 格式。

OpenRLHF 的 Agent Paradigm 把执行方式和 RL 算法拆开。执行方式负责产生轨迹，算法负责消费轨迹。single-turn、自定义 reward、multi-turn 工具环境都被统一成 token-level trajectory，后续 PPO、GRPO、RLOO、REINFORCE++ 使用同一套 loss 入口。

维度	Single-turn	Multi-turn Agent
执行过程	prompt 生成一次 response，然后 reward 打分。	prompt 进入环境，模型多次 action，环境多次反馈。
配置入口	默认模式，常配合 --reward.remote_url。	--train.agent_func_path 指向 AgentExecutor 文件。
轨迹结构	prompt tokens + response tokens + reward。	observation/action/feedback 多轮拼成一条 token trajectory。
典型任务	数学答案、代码单测、格式校验、偏好奖励。	工具调用、网页环境、代码调试、交互式游戏、搜索增强。

token-in-token-out 的工程价值很高。模型生成结果不先还原成字符串再重新 tokenize，能避免 BOS/EOS、chat template、特殊 token、工具标记在训练端和 rollout 端不一致。多轮 Agent 仍然可以返回文本反馈，但框架最终保存和优化的是 token 级轨迹。

OpenRLHF 0.10.2 之后使用层级 CLI。算法切换主要通过 --algo.advantage.estimator 完成，KL、动态过滤、off-policy correction、batch 和长度预算则通过各自前缀组合。

配置	含义	常见选择
--algo.advantage.estimator	选择 advantage 估计器，也就是在线 RL 的核心算法形态。	gae, reinforce, reinforce_baseline, rloo, group_norm, dr_grpo
--algo.kl.use_loss	把 KL 作为 actor loss 的约束项。	推理/RLVR 中常用，避免 reward 直接吞掉语言质量。
--algo.kl.init_coef	KL 初始系数。	从小值开始，结合实际 KL 曲线调。
--algo.dynamic_filtering_enable	过滤全错、全对或超出分数范围的 rollout group。	规则奖励任务常用，减少无学习信号 batch。
--train.dynamic_batch_enable	按 token 数动态组织 batch。	长短 response 混合时降低 OOM 和吞吐抖动。
--train.max_tokens_per_gpu	训练阶段每张 GPU 的 token 上限。	显存控制阈值，优先级高于样本条数。
--rollout.max_tokens_per_gpu	rollout 阶段每张 GPU 的 token 上限。	控制 vLLM 侧批量生成规模。

OpenRLHF 命令很长，生产脚本应把资源、算法、数据、checkpoint 分区写清楚。下面是一个结构化模板，重点展示每组参数的职责。

OpenRLHF 适合已经明确要做在线 RLHF/RLVR 的团队，尤其是需要 Ray 调度、vLLM rollout、DeepSpeed ZeRO-3 和 multi-turn agent 的项目。它的优势是角色边界清楚、命令行可组合、Hybrid Engine 对中小 GPU 集群友好。代价是参数多、版本组合敏感、训练脚本需要严格工程化管理。

verl 是面向大语言模型后训练的强化学习框架，核心设计来自 HybridFlow。它把 RL 算法的控制流放在单进程 driver 中，把模型前向、rollout、反向和优化器放在 Ray worker 上执行。这个拆分让研究者能更容易改 PPO/GRPO 主循环，同时复用 FSDP、Megatron-LM、vLLM、SGLang 等计算后端。

入口	阅读重点	工程意义
docs/hybrid_flow.rst	控制流、计算流、driver/worker 拆分。	理解 verl 与一体化多进程 trainer 的差异。
docs/examples/ppo_code_architecture.rst	main_ppo、RewardManager、WorkerGroup、ResourcePool。	定位新增算法或新 worker 应该改哪里。
docs/start/quickstart.rst	GSM8K PPO 首跑、parquet 数据、model_merger。	建立最小可运行工程链路。
docs/preparation/reward_function.rst	custom_reward_function.path/name 和 RewardManager。	接入自定义规则奖励或 reward model。
verl/trainer/main_ppo.py	Hydra 入口、Ray 初始化、TaskRunner。	理解训练 job 如何启动和分配角色。
verl/trainer/ppo/ray_trainer.py	apply_kl_penalty、compute_advantage、RayPPOTrainer.fit。	理解 rollout 到 actor update 的主循环。
examples/grpo_trainer/run_qwen3_8b_fsdp.sh	GRPO、FSDP、vLLM、NPU/GPU 的真实配置组织。	把 Hydra 参数分组管理，避免巨型命令不可维护。

verl 官方推荐容器环境。训练后端和 rollout 后端可以独立选择：研究和原型常用 FSDP/FSDP2，超大规模可选 Megatron-LM；rollout 常用 vLLM，也支持 SGLang、TensorRT-LLM 或 Hugging Face 调试路径。

HybridFlow 把 RL 系统看成两层 dataflow。控制流决定先 rollout、再算 logprob/reward/advantage、再 update actor/critic；计算流决定每个模型操作如何在多 GPU 上执行。verl 让控制流保持单进程 Python 逻辑，计算流交给 Ray worker 和模型引擎。

层次	包含内容	在 verl 中的位置
控制流	rollout 顺序、reward 计算、advantage、actor/critic 更新时机。	RayPPOTrainer.fit、main_ppo.py、算法扩展。
计算流	模型 forward、backward、optimizer、FSDP/Megatron/vLLM 并行。	ActorRolloutRefWorker、TrainingWorker、engine backend。
数据协议	prompt、response、mask、log_probs、reward、advantage。	DataProto、TensorDict、non_tensor_batch。
资源映射	哪些角色放到哪些 GPU pool。	ResourcePoolManager、Role、RayWorkerGroup。

DataProto 是 verl 在 driver 和 worker 之间传递 batch 的核心容器。tensor 字段放在 batch 中，字符串、数据源、ground truth 等非 tensor 字段放在 non_tensor_batch 中。WorkerGroup 对外暴露看起来像本地函数的方法，内部负责把 DataProto 拆分到多个 worker，再收集结果。

verl 的 ray_trainer.py 中，KL penalty 和 advantage 是连接 reward 与 policy loss 的两个关键函数。下面保留核心逻辑并加工程注释。

verl 的自定义 reward 通过 Hydra 配置接入： custom_reward_function.path 指向 Python 文件， custom_reward_function.name 指向函数名。函数通常接收 data_source、solution_str、ground_truth 和 extra_info。

verl 的 QuickStart 使用 Hydra 覆盖参数。命令行里的 a.b.c=value 会覆盖配置树中的对应字段。

verl 的真实训练脚本通常把 Hydra 参数分组为 DATA、MODEL、ACTOR、ROLLOUT、REF、TRAINER。这样比一条超长命令更可维护，也便于不同硬件分支复用。

verl 默认把 checkpoint 保存到 checkpoints/${trainer.project_name}/${trainer.experiment_name}。FSDP 保存的是分片状态，部署前通常需要用 verl.model_merger 合并成 Hugging Face 目录。

评估时应固定 decoding 配置，并同时看任务分数、KL、长度和格式错误率。RL checkpoint 之间不能只按 reward 选最优；reward hacking 会让训练分数优于人工质量。

verl 的训练入口由 Hydra 管配置，Ray 管分布式任务。 main_ppo.py 里的 driver 负责启动 Ray、构造 TaskRunner，并由 TaskRunner 组装 worker、resource pool 和 trainer；模型前向、反向和生成由远程 worker 执行。

verl 的角色映射决定“谁负责 actor/rollout/ref/critic/reward”，资源池映射决定“这些角色放到哪些 GPU 上”。理解这层映射后，FSDP、Megatron、vLLM 或 SGLang 的替换才不会混乱。

verl 的 RewardManager 从 DataProto 中取出 response、ground_truth、data_source，解码 response 后调用具体 reward function。这个设计支持混合数据集：同一个 batch 里不同 data_source 可以走不同评分函数。

RL checkpoint 合并成 Hugging Face 格式后，应单独写评估脚本，固定模型路径、解码参数和数据切分。不要直接拿训练 reward 日志当最终结论。

verl 适合需要频繁改 RL 算法主循环、接入复杂 reward、试验 FSDP/Megatron/vLLM/SGLang 后端组合的团队。它的核心优势是控制流清晰，研究者可以在 driver 侧修改 rollout、advantage 和 update 顺序；底层模型并行仍由 worker 后端负责。代价是 Hydra 配置树较深，DataProto、WorkerGroup、Role、ResourcePoolManager 需要先建立概念模型。

DeepSpeed 的工程接口由两部分构成：一部分是 launcher + 分布式初始化，负责把“单机脚本”变成“多进程多卡训练”；另一部分是 DeepSpeedEngine + JSON 配置，负责把显存分片（ZeRO）、offload、混合精度、梯度累积、checkpoint 等能力落在可复现的配置上。本节围绕安装、启动、 deepspeed.initialize、 ds_config.json、ZeRO Stage 1/2/3、offload、checkpoint，以及与 Transformers/Accelerate 的集成路径展开，重点给出配置与代码的对应关系。

DeepSpeed 的最小安装路径是先安装 PyTorch，再安装 DeepSpeed。DeepSpeed 包含若干 C++/CUDA 扩展（ops），默认采用 JIT 方式在运行期编译加载，因此环境里通常需要可用的编译链与 ninja。

安装完成后优先跑环境报告，确认“哪些 ops 可用、哪些会在运行时编译、CUDA/通信栈是否匹配”。这个步骤在排查安装或性能差异时比直接跑训练更高效。

默认 JIT 编译适合研发迭代；在固定镜像或需要减少“首次运行抖动”的场景里，可以在安装期预编译部分或全部 ops。DeepSpeed 提供一组 DS_BUILD_* 环境变量控制构建范围。

预编译全部 ops 可能耗时较长，可通过并行编译加速：

DeepSpeed launcher 的默认约定是“一进程一 GPU”。launcher 会为脚本注入 --local_rank，脚本侧需要能解析这个参数并把当前进程绑定到对应 GPU。

多机训练通常由 launcher 读取 hostfile（节点列表与每节点 slots），并在每个节点上拉起相同脚本。hostfile 格式依赖部署系统（裸机/Slurm/K8s），工程上常见做法是先让调度系统分配机器与 GPU，再由 DeepSpeed 或 torchrun 建立通信。

DeepSpeed 提供 deepspeed.add_config_arguments 把 --deepspeed 与 --deepspeed_config 等参数接入到自定义 argparse 中。

deepspeed.initialize 是训练入口：负责（必要时）初始化 torch distributed，并返回一个可直接用于 forward/backward/step 的 DeepSpeedEngine。配置文件里的 optimizer/scheduler/dataloader 也可以被 DeepSpeed 构造与管理。

标准路径当然是 model_engine.backward(loss)。但真实项目里经常会遇到一种情况：损失核心是你先做了额外组合、裁剪、蒸馏、或跨模型共享，再想手工调 loss.backward()。这时就不能直接把 DeepSpeedEngine 绕过去。

这里的关键点核心是混合精度与 loss scaling 的责任边界。直接调用 loss.backward() 而不经过 engine.backward() 或 engine.scale(loss)，会把 DeepSpeed 的数值路径直接绕开。

DeepSpeed 的 step() 每轮都可以调用，但并非每轮都会真正更新参数。很多训练逻辑只应发生在“真实更新边界”上，例如 EMA、外部 scheduler、吞吐统计、checkpoint tag 递增，以及某些 callback。判断这个边界的标准接口就是 is_gradient_accumulation_boundary()。

没有这层判断时，最常见的问题是日志步数、学习率步数和真实优化步数错位。表面上训练还在跑，实际上很多围绕“step”的外围系统都已经对不上了。

DeepSpeed 并不要求一个进程里只能有一个 engine。蒸馏、actor-critic、reward model 协同训练，常常会在同一轮里维护多个 engine，然后围绕一个共享 loss 做反向传播。

一旦进入这种多 engine 场景，训练脚本就不能再把“模型对象”“优化器对象”“checkpoint 目录”混为一谈。每个 engine 都有自己的 ZeRO 状态、优化器与恢复语义，而共享的只是上层任务目标。

当脚本里已经显式调用了 torch.distributed.init_process_group，DeepSpeed 侧应改为 deepspeed.init_distributed 或直接移除显式初始化，让 deepspeed.initialize 自动完成分布式初始化。多重初始化是常见的 hang 根源。

DeepSpeed 的核心覆盖规则是：配置文件定义默认行为，显式传入的 Python 对象覆盖配置。例如，当在 deepspeed.initialize 里传入 optimizer 时，会覆盖 ds_config.json 里 optimizer 段落的定义。

DeepSpeed 将 batch size 拆为三项参数：有效 batch（ train_batch_size）、每卡 micro-batch（ train_micro_batch_size_per_gpu）、梯度累积步数（ gradient_accumulation_steps）。三者满足：

\[B = b \\times g \\times N\]

其中 \(B\) 对应 train_batch_size，\(b\) 对应 train_micro_batch_size_per_gpu，\(g\) 对应 gradient_accumulation_steps，\(N\) 是参与训练的 GPU 数量（即 world size）。

工程上通常只显式指定其中两个，剩下一个由 DeepSpeed 推导；这样可以减少多机扩容时的人工改动。

配置项	DeepSpeed 行为	代码侧需要做什么
train_micro_batch_size_per_gpu	定义每次 forward/backward 的 micro-batch 大小	DataLoader 提供的 batch 必须与该值一致，或让上层框架（Trainer/Accelerate）保持一致
gradient_accumulation_steps	定义多少个 micro-step 后做一次参数更新	训练循环仍按 “每个 batch 一次 backward”，DeepSpeedEngine 内部按配置决定何时 step
fp16.enabled / bf16.enabled	启用混合精度与 loss scaling（若需要）	脚本不再手写 AMP 也能跑通；若与外部 AMP 同时启用，需明确由谁负责 autocast/scaler
optimizer	DeepSpeed 构造优化器（可选）	如果在 deepspeed.initialize 显式传入 optimizer，则会覆盖该段配置
scheduler	DeepSpeed 构造并在每步自动 step（可选）	当 scheduler 由 DeepSpeed 管理时，脚本不应额外调用 scheduler.step()

ZeRO 的全称是 Zero Redundancy Optimizer，中文可译作“零冗余优化器”。名字里的 redundancy 指的是数据并行里的重复状态：每张 GPU 都拿到完整参数、完整梯度、完整优化器状态。ZeRO 并没有改变模型的数学结构，也没有改变损失函数；它改变的是训练状态在不同 GPU 上的存放方式。

设模型参数量为 \(P\)，data-parallel world size 为 \(N\)。如果按 bf16/fp16 参数、bf16/fp16 梯度、AdamW 的 FP32 一阶动量 \(m\)、FP32 二阶动量 \(v\)、FP32 master weights 粗略估算，单卡仅模型状态就可能接近：

\[\mathrm{memory}_{\mathrm{DP}}\approx P\cdot(2+2+4+4+4)\ \mathrm{bytes}=16P\ \mathrm{bytes}\]

其中 \(2\) bytes 来自 bf16/fp16 参数，另一个 \(2\) bytes 来自梯度，三个 \(4\) bytes 分别来自 AdamW 的 \(m\)、\(v\) 和 FP32 master weights。这个估算还没有算激活、临时 buffer、通信 bucket、KV cache 或框架额外开销。

ZeRO 的分片收益可以粗略理解为：

\[\mathrm{memory}_{\mathrm{ZeRO\text{-}1}}\approx P\cdot(2+2)+\frac{P\cdot(4+4+4)}{N}\]

Stage 1 只把优化器状态切到 \(N\) 张卡上；参数和梯度仍然每卡完整保存。

\[\mathrm{memory}_{\mathrm{ZeRO\text{-}2}}\approx P\cdot2+\frac{P\cdot(2+4+4+4)}{N}\]

Stage 2 再把梯度也切开；参数仍然每卡完整保存。

\[\mathrm{memory}_{\mathrm{ZeRO\text{-}3}}\approx \frac{P\cdot(2+2+4+4+4)}{N}\]

Stage 3 连参数也分片，单卡模型状态占用最低。代价是每层计算前需要把当前层参数 all-gather 到可计算形态，计算后再释放或重新分片。显存节省来自“少存重复状态”，额外成本来自“更多通信与更复杂的参数生命周期管理”。

把它类比成多人搬书更直观。普通数据并行像每个人都背着整套书，再一起读同一章节；ZeRO-1 先把笔记本和索引卡分给不同人保管；ZeRO-2 再把每章批注也分开保管；ZeRO-3 连书页本身也分开保管，读到某一章时临时把相关页面凑齐，读完再分回去。越往后越省背包空间，但传递页面的协调成本越高。

问题	优先尝试	原因
模型能加载，训练时 optimizer state 顶爆显存	ZeRO Stage 1 / Stage 2	AdamW 状态和梯度通常是第一波显存大头，Stage 1/2 的收益直接且通信代价相对温和。
模型参数本身太大，完整权重难以放进单卡	ZeRO Stage 3 或 PyTorch FSDP	必须切参数本身，Stage 1/2 已经不够。
ZeRO-3 仍然放不下，GPU 显存极端紧张	CPU / NVMe offload	把部分参数或优化器状态搬到主存/磁盘，牺牲带宽换容量。
初始化模型时就 OOM	deepspeed.zero.Init	让模型构造阶段就按 ZeRO-3 语义分片，避免先完整创建再切分。

当模型大到“连在单卡或单进程里完整实例化一次都做不到”时，光靠训练阶段的 ZeRO-3 已经不够，因为程序会先死在 Python 对象创建与参数分配这一步。 deepspeed.zero.Init 的作用，就是在模型构造阶段就按 ZeRO-3 语义分片参数，把“初始化时的峰值内存”也压下来。

它解决的是“模型创建阶段的峰值内存”，并非训练吞吐本身。工程上只有在模型规模真的碰到初始化内存墙时才需要上这一层；普通 7B/13B 微调不必默认引入。

ZeRO Stage 1 将优化器状态（例如 Adam 的一阶/二阶动量与 FP32 master 权重）在 data-parallel ranks 之间分片，降低“优化器状态显存/内存”的重复开销。对模型参数量中等但 optimizer state 占用成为瓶颈的训练很直接。

ZeRO Stage 2 在 Stage 1 的基础上将梯度也分片。它通常在“模型能放下，但训练状态占用过高”或“希望进一步扩大 batch/seq_len”时成为默认选择；相较 Stage 3，它在通信与实现复杂度上更温和。

ZeRO Stage 3 进一步把模型参数也分片，使得“单卡显存”主要由激活与少量 shard 状态构成，从而把可训练模型尺度推到显存上限之外。代价是更多通信与参数聚合/分片的复杂性，checkpoint 与恢复也会更敏感。

offload 的目标是继续压缩 GPU 显存占用。常见组合是：ZeRO-2 offload optimizer states（CPU）与 ZeRO-3 offload params/optimizer（CPU 或 NVMe）。offload 会把瓶颈从显存转移到带宽与延迟，因此通常需要配合更细的 micro-batch、更高的梯度累积与更强的通信/计算重叠。

ZeRO-3 会在 forward/backward 期间自动 gather 与 repartition 参数。对普通静态 Transformer 结构，这条路很顺；但对 MoE、动态路由器或不同 rank 可能走到不同子模块的网络，自动 gather 就可能在不同 rank 上走出不同分支，最后直接演变为 hang 或 all-gather 不一致。DeepSpeed 给这类模块准备了 leaf module 机制。

把模块标为 leaf 的含义，核心是“ZeRO-3 在这里停止继续向内递归协调参数收集”。对动态专家层而言，这往往是避免不同 rank 走出不同 gather 路径的关键。

ZeRO-3 下，参数默认处于分片态。只要你打算在模块外部直接读一个参数，或把某个参数借给别的模块 forward 使用，就必须显式告诉 DeepSpeed 你要把它临时 gather 出来。

如果某个参数会在别的模块 forward 中被外部引用，还需要考虑 register_external_parameter() 这类接口。工程语义很简单：让 DeepSpeed 知道“这个参数虽属于 A 模块，但 B 模块 forward 也会碰它”。否则参数分片生命周期和实际访问路径会脱节。

ZeRO 把参数、梯度和优化器状态分散到不同 rank 之后，普通的 param.grad、 state_dict() 式直觉就不再可靠。DeepSpeed 为此提供了 safe_get_full_grad、 safe_get_full_fp32_param、 safe_set_full_grad 等调试接口，用于在正确的阶段把分片状态安全收拢。

这些接口的工程价值主要出现在三类场景：排查某一层梯度是否真的在更新；在 ZeRO-3 下做权重修补或规则化操作；以及把大模型训练中的数值异常定位到具体参数张量。如果还沿用普通单卡时代的“直接 print param.grad”，你看到的常常只是一个局部 shard，而非完整状态。

大模型训练越来越常见的一个模式，是训练、评估、生成、蒸馏交替发生。同一进程既要做训练态 ZeRO，又要临时切进生成态或检查点转换。DeepSpeed 这时提供的核心是一些很朴素但非常关键的运行时接口：

• empty_partition_cache() 用来释放 ZeRO 在分片过程中缓存的一些参数副本。
• offload_states(...) 与 reload_states(...) 用来在 CPU/GPU 之间搬运优化器状态或参数状态，为临时生成窗口腾显存。

它们不会把一个本来放不下的训练 magically 变成能放下，但在“训练与生成共进程”这类高压场景里，经常能决定一个流程是稳定切换，还是偶发性 OOM。

真正的 ZeRO 调优很少只改 stage。更高频的是下面这些和通信形态、梯度布局、offload 粒度直接相关的参数。它们通常出现在官方教程、OpenRLHF/DeepSpeedExamples 以及大模型训练配置里。

命令/API/函数 overlap_comm 说明 让部分通信与计算重叠，减少纯等待时间。对通信占比高的多卡训练很常见。 示例 JSON 1 2 3 4 5 6 {   "zero_optimization": {     "stage": 2,     "overlap_comm": true   } }

命令/API/函数 contiguous_gradients 说明 把梯度布局整理得更连续，减少碎片化与部分通信/拷贝开销。通常和 Stage 2/3 一起出现。 示例 JSON 1 2 3 4 5 6 {   "zero_optimization": {     "stage": 2,     "contiguous_gradients": true   } }

命令/API/函数 reduce_scatter / allgather_bucket_size / reduce_bucket_size 说明 控制 ZeRO 通信的聚合方式与 bucket 粒度。它们共同决定“通信开始得多早”“每次通信包有多大”。 示例 JSON 1 2 3 4 5 6 7 8 {   "zero_optimization": {     "stage": 2,     "reduce_scatter": true,     "allgather_bucket_size": 5e8,     "reduce_bucket_size": 5e8   } }

命令/API/函数 offload_param / offload_optimizer 说明 把参数或优化器状态搬到 CPU/NVMe。它换来更低显存占用，也把瓶颈转移到 PCIe、内存或磁盘带宽。 示例 JSON 1 2 3 4 5 6 7 {   "zero_optimization": {     "stage": 3,     "offload_param": {"device": "cpu", "pin_memory": true},     "offload_optimizer": {"device": "cpu", "pin_memory": true}   } }

调这些参数时，判断标准包括单步速度、峰值显存、吞吐稳定性、step time 抖动，以及 checkpoint 保存/恢复是否开始变脆弱。

真实项目里，决定成败的往往是下面这些“看起来像小旋钮，实际定义运行时行为”的配置：

配置项	它控制什么	什么时候需要认真看
stage3_module_granularity_threshold	ZeRO-3 按模块做 gather/repartition 时的粒度阈值	模块层级复杂、host 开销高，或动态模块很多时
communication_data_type	通信路径采用什么 dtype 传输梯度/参数	多机多卡上 fp16/bf16 数值稳定性与通信带宽要一起平衡时
gradient_predivide_factor	all-reduce 前的梯度预除因子	大规模并行训练里需要缓和梯度归约数值路径时
offload_param.buffer_count / buffer_size	参数 offload 时的缓冲池数量与块大小	CPU/NVMe offload 已经启用，但 GPU 在等 IO 或 host 内存抖动明显时
offload_optimizer.pipeline_read / pipeline_write	优化器状态的读写是否做流水化	NVMe offload 已经成主路径，希望减少读写阻塞时
aio.block_size / queue_depth / thread_count	异步 IO 管线的提交粒度与并发深度	NVMe offload 变成主要瓶颈，且你已经确认并非模型本身算力吃满时

这类参数不建议在“训练第一天”就满天飞地改。更稳的顺序是：先把 stage、micro-batch、梯度累积和混合精度跑稳，再针对真实瓶颈决定是去调通信、调 gather 粒度，还是调 offload 管线。

DeepSpeedEngine 提供 save_checkpoint / load_checkpoint，用于保存与恢复模型、优化器、scheduler 以及自定义 client_state。工程要点是：所有 ranks 都必须调用 save_checkpoint，否则会在同步点 hang。ZeRO-3 下，保存后立刻在同一 engine 上 load（不重新初始化）是已知的不兼容用法。

ZeRO-3 下，参数本来就是分片状态，因此 checkpoint 恢复并非“随手把文件再读回来”这么简单。工程上更稳的顺序是：

1. 重新构造模型对象。
2. 重新调用 deepspeed.initialize 得到新的 engine。
3. 在这个新 engine 上调用 load_checkpoint。

不要把“刚 save 完的老 engine”直接拿来马上 load 同一路径，尤其在 ZeRO-3 下，这会把参数分片与内部状态管理搞得非常脆弱。恢复语义应被理解为“用 checkpoint 重新装配一套训练状态”，而非“对当前 engine 就地回滚”。

ZeRO-2/3 的 checkpoint 是分片形态。需要“脱离 DeepSpeed 继续使用/分享权重”时，常用做法是把 ZeRO checkpoint 转为合并后的 fp32 state_dict。

当训练拓扑、并行策略或下游恢复环境会变化时，只导出一份 fp32 权重往往不够，因为你还可能需要恢复优化器状态、调度器状态以及更完整的训练上下文。DeepSpeed 近年的 Universal Checkpoint 路线，目标就是把原本强依赖当前 ZeRO/并行拓扑的 checkpoint 转成更容易跨环境迁移的格式。

它更像“交付格式转换”而非训练时的主存储格式：训练阶段继续保存原生 DeepSpeed checkpoint，真正需要迁移、共享或给别的恢复流程消费时，再做 Universal 转换会更稳。

这组概念如果不分清，恢复逻辑几乎一定会写错。

• 普通 save_checkpoint(..., save_latest=True) 写出的“最新 tag 指针”是 latest。
• 启用 Universal Checkpoint 恢复链路后，DeepSpeed 会去看 latest_universal。这个文件通常来自转换流程，而非普通保存时自动生成。
• checkpoint.load_universal=true 的含义，是“恢复时按 universal 语义查目录与 tag”，并非“保存时自动帮你多产一份 universal”。

因此，训练主路径通常仍保存原生 DeepSpeed checkpoint；真正要跨拓扑迁移、跨环境恢复，才做 ds_to_universal 转换，并补上 latest_universal 这一层索引。

• 在 ZeRO-3 下， save_16bit_model() 只有在相应 gather 保存开关打开时，才有机会产出真正可用的 16-bit 单体权重。否则你以为拿到了导出，实际只得到不完整状态。
• checkpoint.tag_validation 决定 DeepSpeed 在各 rank 的 checkpoint tag 不一致时是忽略、告警还是直接失败。多阶段脚本、手工拼装 tag、或并行保存逻辑复杂时，建议把这层校验看成“帮你提前暴露一致性错误”的安全带，而非烦人的额外检查。

Transformers 的 Trainer 通过 TrainingArguments.deepspeed（或 CLI 的 --deepspeed）接入 DeepSpeed。工程上更稳定的做法是：把与 Trainer 重复的值在 ds_config 中写成 "auto"，由 Trainer 统一灌入，避免“两边都写但不一致”。

Accelerate 提供 DeepSpeedPlugin，把 ZeRO stage、梯度累积等关键项绑定到 Accelerator 的生命周期里。工程要点是：DeepSpeed 需要提前知道 gradient_accumulation_steps，因此插件与训练循环要对齐，梯度累积本身仍需要按常规方式在代码里实现。

当需要 ZeRO-3/offload/更细的 ZeRO knobs 时，Accelerate 通常通过“指定 DeepSpeed 配置文件”的方式接入。此时 ds_config.json 才是事实来源，代码侧只保留必要的 accelerator.prepare 与 accelerator.backward 语义，避免重复配置。

DeepSpeed 在 RLHF 系统里很少单独出现，它通常与“多阶段脚本 + 多角色资源编排”一起工作。以 OpenRLHF / DeepSpeedExamples 这类工程为代表，最常见的是三段式链路：先做监督微调（SFT），再训练奖励模型（RM），最后进入 PPO 或近似 PPO 的在线策略优化。

SFT 阶段的目标是得到一个“能听懂指令、输出格式已基本对齐”的初始策略模型。这里的 DeepSpeed 角色主要是把单卡难以承受的 batch/序列长度压回可训练范围。

RM 阶段的关键是打分。它要求 reward model 的 checkpoint 之后能被 PPO 阶段稳定加载，因此“checkpoint 目录结构、ZeRO stage、是否做 Universal 转换”最好在这一阶段就固定下来。

PPO 阶段里，DeepSpeed 已经从“包一个模型训练”扩展到 actor、critic、reference policy、reward model 这些角色各自带着自己的 ZeRO/显存策略运行，再通过 Ray 与 vLLM 协同。这就是为什么在线 RLHF 系统的复杂度远高于普通 SFT：训练本体、生成服务和奖励打分已经是三类不同的运行时。

PPO 往往会同时产出 actor 与 critic 的 DeepSpeed checkpoint 目录。若后续要跨环境迁移、给别的脚本恢复或归档，实践里常把 ZeRO checkpoint 进一步转换为 Universal 格式，而非把分片目录原样交给别的系统猜。

vLLM 是面向服务化推理的运行时：围绕高吞吐调度、KV cache 管理、continuous batching、分布式并行与 OpenAI-compatible API 提供一体化推理栈。工程落地时可以把 vLLM 当作三条“入口路径”：离线推理的 LLM，可嵌入自建服务的 Engine，以及直接上线的 vllm serve。

vLLM 的 wheel 包含大量编译好的 C++/GPU kernels。性能与兼容性高度依赖“vLLM wheel、PyTorch、驱动/运行时”三者的组合，工程上优先使用官方提供的预构建 wheel 或官方 Docker 镜像。

官方文档建议在新环境中安装 vLLM，并优先使用 wheel 自带的 PyTorch/依赖组合以减少二进制不兼容问题；此外，conda 安装的 PyTorch 可能静态链接 NCCL，容易在分布式/多进程场景引发问题。

基本自检可以用“导入 + 小模型离线生成”验证：

生产系统更常直接使用官方镜像运行 OpenAI-compatible server。多进程与张量并行依赖共享内存，容器启动通常需要 --ipc=host 或显式配置 --shm-size。

当宿主机驱动较旧时，官方镜像提供 CUDA compatibility 模式（只覆盖部分专业/数据中心 GPU 的兼容场景）：

当你的 CUDA/ROCm 版本、PyTorch 构建配置或硬件平台与官方 wheel 不匹配时，需要从源码构建。官方提供了以 VLLM_USE_PRECOMPILED=1 作为起点的可编辑安装，以及基于 CMake 的增量编译工作流用于迭代 kernels。

vLLM 的 API 结构可以用“离线批处理推理”“可嵌入的引擎”“生产服务端”三条路径来理解。三者底层共享同一套 Engine 配置（EngineArgs），差异在于请求进入方式与生命周期管理。

vllm.LLM 适合离线批处理与数据集推理。它接受 prompts 列表并返回结构化输出，常用于离线评测、数据合成与批量生成。

采样参数的默认来源有两套：模型仓库里的 generation_config 与 vLLM 自己的默认值。若业务希望显式使用 vLLM 的默认采样参数，可以在创建 LLM 时设置：

SamplingParams 是 vLLM 里最常被反复创建的对象之一。它对应的是“单次请求想怎么解码”，而非整个 engine 的资源配置；因此它更接近业务请求参数，而非部署参数。

命令/API/函数 temperature / top_p / top_k 说明 控制随机性与候选截断范围。适合把“输出多样性”从服务默认值里拆成请求级旋钮。 示例 Python 1 2 3 4 5 6 7 8 from vllm import SamplingParams   params = SamplingParams(     temperature=0.7,  # 降低随机性，但保留一定表达变化     top_p=0.9,        # 切掉长尾 token，减少离谱采样     # 再给候选集合一个显式上界，防止 nucleus 后候选仍过宽。     top_k=50, )

命令/API/函数 max_tokens / stop / stop_token_ids 说明 限制回复长度并声明何时停止。对工具调用、结构化输出和 Web 对话都很常见。 示例 Python 1 2 3 4 5 6 params = SamplingParams(     max_tokens=256,                  # 给单次回答设置上限，避免尾部失控     stop=["\nUser:"],                # 遇到特定分隔符就截断     # 当上游协议或模板已经约定了特殊 token 时，按 token id 截断更稳。     stop_token_ids=[151645], )

命令/API/函数 n / best_of 说明 控制一次请求要生成多少个候选，以及内部要采多少条再返回最好的一批。离线数据合成与 reranking 场景很常用。 示例 Python 1 2 3 4 5 params = SamplingParams(     n=4,          # 返回 4 个候选，供后续 rerank 或规则过滤     # 先在内部采 8 条，再把得分更好的 4 条返回给业务侧。     best_of=8, )

Engine 路线用于把 vLLM 嵌入到自建服务/作业系统中，获得“请求级 streaming + 细粒度生命周期控制”。当前主线接口是 V1 Engine（ AsyncLLM），通过 AsyncEngineArgs 构建。

在 Engine 路线里，“并发/显存预算”通常通过 EngineArgs 控制，应用侧需要自行处理：请求队列、超时/取消（abort）、重试、以及与外部网关的对接。

把 vLLM 当嵌入式引擎使用时，真正的工程难点是请求取消、更新窗口和进程退出是否可控。 AsyncLLM 这一层已经把这些动作做成显式接口。

abort() 控制请求级取消， pause_generation() / resume_generation() 控制更新窗口， shutdown() 控制进程级收尾。对自建服务而言，这些接口的价值远高于“再包一层 HTTP 就能上线”。

vllm serve 直接启动 OpenAI-compatible server，是最接近“拿来就用”的生产入口。典型端点包括 /v1/chat/completions 与 /v1/embeddings，并支持流式输出（SSE）。

应用侧最常见的接入方式是 OpenAI Python SDK，把 base_url 指向自托管服务。部分参数在 OpenAI API 中不存在，但 vLLM 支持；这类扩展字段通常通过 extra_body 传入。

生产里最容易出错的一点，是把“兼容 OpenAI”理解成“只支持 chat completions”。vLLM 的 HTTP 面远比这宽，是否暴露对应能力，要看你启动的模型与服务参数。

端点	工程用途	什么时候优先用它
/v1/chat/completions	最经典的聊天式生成接口	应用已经按 Chat Completions 组织 prompt，或要兼容大量现有 SDK/中间件
/v1/responses	更统一的新式接口，便于承载结构化输出、多模态与工具调用扩展	新系统直接建设，且希望减少未来从 Chat Completions 迁移的成本
/v1/embeddings / /v2/embed	向量化入口	做检索、重排前召回、聚类或语义缓存
/v1/rerank / /v2/rerank / /v1/score	重排与打分	检索系统里要把粗召回结果重新排序，或需要 pairwise/listwise 相关性分数
/tokenize / /detokenize	token 级观测与调试	排查 prompt 模板、上下文预算、停词边界与计费口径

• --generation-config vllm 用来避免模型仓库里的 generation_config.json 静默覆盖服务端解码默认值。线上同一服务接多个业务方时，这个开关能显著减少“为什么同样 temperature，行为却不一致”的排障时间。
• --chat-template-content-format 控制请求消息内容如何映射到 chat template。多模态或复杂 content 格式下，它直接决定模板渲染是否和客户端预期一致。
• --enable-request-id-headers 让 X-Request-Id 能沿 HTTP 边界传递。服务一旦接入网关、APM 或异步任务系统，这个 request id 往往比 prompt 本身更关键，因为它是跨层排障的唯一稳定主键。

vLLM 支持工具调用，但不同模式的可靠性差异很大。生产里需要把“方便演示”和“可验收约束”分开。

• --enable-auto-tool-choice 并非独立开关，它需要同时提供 --tool-call-parser。前者允许模型自动决定是否调用工具，后者负责把模型输出解析回工具调用结构。
• tool_choice="auto" 更接近“模型自由输出 + 解析器尽量提取”。它适合探索式系统，但并不天然保证一定满足 schema。
• tool_choice="required" 或显式指定工具名，更接近“必须产出一个符合工具调用壳子的结果”。这类模式更适合工作流系统与生产链路。
• 请求里的 strict 字段常见于 OpenAI 风格客户端，但在不同版本组合下，它更多承担兼容入口角色，而非单独决定解码行为的神奇开关。真正约束输出的，还是 structured outputs 或明确的工具 schema。

新系统应优先围绕 structured_outputs 与标准 response_format 建设，而非继续押注旧的 guided_json、 guided_regex 之类历史字段。后者更多是兼容路径，前者才是现在的主语义接口。

vllm serve 支持从 YAML 配置文件加载参数。参数名使用长参数形式（long form）。CLI 与配置文件同时提供时，优先级为 CLI > config > defaults。

一旦把 vLLM 用到在线 RLHF 或异步后训练中，服务端就不再只是“提供推理 API”，还需要和训练进程交换新权重、暂停生成、完成热切换。vLLM 已经把这类能力做成显式参数和 HTTP 接口，而非要求用户每轮都重启整个服务。

--weight-transfer-config 负责打开 trainer ↔ serving 的权重同步通道。典型流程是：训练侧先请求初始化权重传输引擎，再开始更新、逐块推送新权重，最后通知服务端切换到新版本。服务端通常还会配合 /pause、 /resume 暂停和恢复新请求生成。

这里有两个边界必须说清楚。第一， init_weight_transfer_engine 与 update_weights 的 JSON 负载结构分别是 {"init_info": ...} 与 {"update_info": ...}，并非任意自造键名。第二，HTTP 是控制面，NCCL 或 IPC 才是数据面；把大张量直接塞进 HTTP JSON，不符合这条接口的设计方式。

这类端点通常只在开发模式下开放，因此示例命令把 VLLM_SERVER_DEV_MODE=1 显式写在前面。线上暴露时必须额外套网关与访问控制，因为很多非 /v1* 端点并不属于普通 API 消费面。

长上下文服务里，prefill 和 decode 的负载形态差异很大。vLLM 的 --kv-transfer-config 允许把 prefill 产出的 KV 传给 decode 侧实例，从而把两类负载拆到不同进程甚至不同机器上。这类拓扑特别适合“长 prompt + 短回复”的系统，因为 prefill 往往比 decode 更吃带宽和显存。

Prefill/Decode 解耦改善的通常是资源形态匹配与尾延迟，而非“任何负载下都绝对更快”。如果请求大多是短 prompt、短回复，额外的 KV 传输与系统复杂度可能抵消收益。

Engine arguments 控制 vLLM 的运行行为：离线推理时它们是 LLM(...) 的一部分参数；在线服务时它们是 vllm serve 的参数子集。工程上可以把 EngineArgs 按职责分为四类：模型与 tokenizer、并行与执行器、KV cache 与调度、以及安全/可观测性。

参数	含义	工程后果
--max-model-len	最大上下文长度	直接决定 KV cache 的 token 预算；过大常导致并发下降或 OOM
--gpu-memory-utilization	显存预算比例	留出系统/碎片空间；过高会提升 OOM 风险
--max-num-batched-tokens	每步调度的 token 预算	影响吞吐与尾延迟，常与并发/显存一起调
--max-num-seqs	并发序列数上限	决定同卡并发，过高会导致排队抖动与尾延迟上升
--kv-cache-dtype	KV cache 存储精度	影响显存/带宽；更激进精度需要评估质量与稳定性
--trust-remote-code	允许加载模型仓库的自定义代码	改变执行边界；仅在可信模型源启用
--download-dir	权重/缓存下载目录	容器化时用于挂载共享缓存，减少冷启动成本

当你希望把“服务端配置”复用到离线任务中，可以在 Python 里用 EngineArgs 组装配置，再把字段展开给 LLM：

vLLM 服务调优里，最常被忽视的核心是调度器预算。 max_num_batched_tokens 控制单个调度步最多同时处理多少 token； enable_chunked_prefill 控制长 prompt 的 prefill 是否允许被切块处理。二者决定的是服务端如何在“长提示词请求”和“短请求延迟”之间做平衡。

经验上， enable_chunked_prefill=True 更适合长上下文服务；而 max_num_batched_tokens 往往需要结合真实流量压测来找平衡点。它并非“越大越快”的旋钮，因为过大的 batch token 预算会拉高单步时延，并放大长请求对短请求的阻塞。

只调 max_num_batched_tokens 往往不够。长上下文、高并发和在线流式三者同时存在时，调度器的第二层参数才是真正决定尾延迟的部分。

参数	控制什么	什么时候值得调
--scheduling-policy	请求在调度器里的优先策略	不同业务混跑，且你确实需要在公平性和吞吐之间做取舍时
--stream-interval	流式输出向客户端刷新的频率	前端强调实时感知，或日志系统希望减少碎片化 token 事件时
--max-num-partial-prefills	允许多少个长 prompt 以切块形式并行进入 prefill	长 prompt 请求经常把短请求拖住时
--max-long-partial-prefills / --long-prefill-token-threshold	定义“多长算长请求”，以及这类请求最多允许多少并发切块	流量同时包含极长上下文任务与常规问答请求时

这一层参数没有固定最优值。它们依赖模型大小、GPU 代际、上下文长度分布，以及你更关心吞吐、TTFT 还是尾延迟。文档里给的是旋钮，真正落地仍然要靠业务流量压测。

在真实离线批量推理系统里，vLLM 往往会挂进更高层的数据处理框架，由框架负责分片、重试、结果回写和集群扩缩。Ray Data 的 vLLM Processor 就是一个典型模式：把 prompt 构造、采样参数和结果抽取分成三段函数，vLLM 只负责把 GPU 算力吃满。

这条路线的意义在于职责分离：数据系统负责大规模分片与回写，vLLM 负责单副本高吞吐推理。两者分开后，离线推理任务就不需要把“数据调度”和“GPU 推理调度”揉在同一个脚本里。

分布式推理的目标是“把单模型副本放进足够多的 GPU 里，并把负载分摊出去”。vLLM 的并行策略可以分为三类：单副本的张量并行/流水并行，以及多副本的 data parallel（权重复制）。

当模型无法放进单卡但能放进单机多卡时，设置 tensor_parallel_size 为“每节点 GPU 数”是最常见策略。

当模型超过单机容量，需要组合张量并行与流水并行：把 tensor_parallel_size 设为“每节点 GPU 数”，把 pipeline_parallel_size 设为“节点数”。如果模型在单机可容纳，但 GPU 数无法均匀切分模型，也可以用 pipeline parallel 做不均匀切分：此时常见设置是 tensor_parallel_size=1， pipeline_parallel_size=GPU 数。

data parallel 复制权重，让多个 GPU/进程独立处理请求，适合吞吐扩展。vLLM 支持“自包含 DP（一个对外端点，内部做 rank 级负载均衡）”与“外部负载均衡（每 rank 单独对外，外部 LB 路由）”。

前缀缓存缓存“已 prefill 的前缀 KV blocks”，新请求与历史请求共享前缀时，可以复用缓存并跳过重复的 prefill 计算。它对“系统 prompt 固定、RAG 模板固定、长上下文重复”的场景收益很大。

服务端通过 --enable-prefix-caching 开启前缀缓存。为多租户隔离与碰撞风险控制，前缀缓存提供可配置的哈希策略（例如使用 SHA256 族）。

speculative decoding 用“草稿模型提出多个候选 token + 目标模型验证并接收其中一部分”的方式减少目标模型 decode 步数，从而降低解码延迟。服务端需要同时加载目标模型与草稿模型，并为草稿模型设置独立的资源预算。

speculative decoding 与某些并行策略（例如 pipeline parallel）可能存在兼容性限制，上线前需要在目标版本组合上做压测与回归。

vLLM 的 OpenAI-compatible server 默认暴露 /metrics，可用于 Prometheus 抓取与容量规划。

容量规划时需要重点关注两类信息：KV cache 的 token 容量与“最大并发估计”。vLLM 启动日志通常会输出类似的估算信息（示例格式如下）：

服务端通常提供健康检查端点（例如 /health、 /ping）。生产环境里这些端点会被 LB 高频调用，建议通过 --disable-access-log-for-endpoints 关闭对应 access logs，避免淹没有效日志：

vLLM 使用 Python 的 logging 配置体系，并提供环境变量控制默认日志行为。最常见的两类控制是：关闭 vLLM 的默认日志配置，以及提供自定义 JSON logging 配置文件路径。

• 显存预算：用 --max-model-len 与 --gpu-memory-utilization 先跑通，再逐步提高 --max-num-seqs 与 --max-num-batched-tokens 做压测。
• 默认行为：明确 chat template、tokenizer 与 generation_config 的来源与优先级，避免升级后默认采样参数变化。
• 权限边界： --trust-remote-code 只在可信模型源启用；容器中通过只读挂载、最小权限与镜像固化降低风险。
• 日志与指标：确保 /metrics 可被抓取，健康检查端点与 access log 策略不会引发噪声或误报警。

vLLM 近年的 CLI 已经不只剩 serve。做容量评估、回归压测与离线批任务时， vllm bench 和 vllm run-batch 往往比自己写临时脚本更稳，因为它们直接复用了官方参数面与统计口径。

AI 训练与推理编程的学习不能只停在 API 表面。成熟项目的源码会暴露更真实的问题：张量形状如何流动，工具接口如何约束模型，权限和上下文如何管理，NER 模型如何把标签、边界和 span 组织成可训练目标。本章选取三类代码做精读：手写 Transformer、Claude Code 类 AI 编程 agent、以及 CRF / GlobalPointer / GLiNER 等 NER 知名算法。

手写 Transformer 精读应覆盖一条完整工程链路：配置如何落到模型形状，权重如何初始化和共享，训练数据如何切成输入/标签，训练循环如何处理 AMP 与梯度累积，学习率如何变化，推理如何自回归生成，checkpoint 如何恢复，以及 minGPT 到 nanoGPT 的演进到底补齐了哪些工程能力。下面的代码按 nanoGPT / minGPT 的公开实现抽象改写，保留核心结构，并把每一行的工程意义写在旁边或上一行。

配置层负责把“模型多大、上下文多长、训练多久、用什么 dtype”变成可记录、可覆盖、可写入 checkpoint 的结构。nanoGPT 的配置方式很朴素：默认值写在脚本顶部，再允许命令行或配置文件覆盖。这种写法适合教学和小型实验，也能清楚展示每个超参进入哪条路径。

模型初始化会同时决定结构、参数尺度和推理路径。GPT 实现里至少有四个关键点：LayerNorm 可选 bias，token embedding 与输出头权重共享，残差投影做缩放初始化，推理时只计算最后一个位置的 logits。这些细节共同影响显存、训练稳定性和推理速度。

nanoGPT 的数据读取没有引入复杂 DataLoader，训练样本直接来自二进制 token 文件中的随机切片。这段代码值得精读，因为它把 causal LM 的输入/标签关系说得很清楚： x 是当前位置 token， y 是整体右移一位的 next-token 标签。

训练主循环把评估、保存、前向、反向、更新、日志和退出条件串起来。这里先看不展开 AMP 细节的骨架，重点是训练状态如何流动。

AMP 与梯度累积是 nanoGPT 比 minGPT 更接近真实训练脚本的关键部分。AMP 降低显存和提升吞吐；梯度累积把多个 micro batch 的梯度加起来，模拟更大的全局 batch；DDP 下只在最后一个 micro step 同步梯度，避免无谓通信。

nanoGPT 使用线性 warmup + cosine decay。warmup 避免训练初期大步长破坏尚未稳定的表示；cosine decay 在训练后期逐渐降低更新幅度；min_lr 给学习率留一个下限。

生成函数是自回归解码的最小实现：每次把当前上下文喂给模型，取最后一个位置的 logits，按 temperature 与 top-k 变成采样分布，采样出下一个 token，再拼回序列。它解释了大模型推理为什么是逐 token 串行的。

checkpoint 保存的是一组可恢复训练状态：模型参数、优化器状态、模型结构参数、当前 step、最优验证 loss 和训练配置。nanoGPT 还处理了 torch.compile 可能引入的 _orig_mod. 前缀。

minGPT 更像“把 GPT 结构写清楚”的教学版；nanoGPT 更像“保留最小代码量的真实训练脚本”。两者差异体现了从模型理解到训练工程的迁移。

维度	minGPT	nanoGPT
主要目标	教学化展示 GPT 模型结构、Trainer 和简单任务	用很少文件跑通 decoder-only LLM 预训练/微调/采样
模型代码	结构更直接，适合第一次读 attention、block、generate	加入 Flash Attention 路径、bias 开关、权重共享、GPT-2 权重导入
训练数据	常见小数据集或任务封装，更强调 API 清晰	直接读取二进制 token memmap，更贴近大语料预训练
训练工程	Trainer 抽象较轻，适合理解基本循环	包含 DDP、AMP、梯度累积、warmup+cosine、checkpoint、torch.compile
适合读者	刚开始理解 Transformer/GPT 结构的人	已经理解结构，想掌握 LLM 训练脚本闭环的人

精读顺序建议从 minGPT 的模型结构开始，确认 QKV、mask、block、loss 的形状；随后读 nanoGPT，把注意力放在训练脚本的状态管理：配置、数据切片、AMP、梯度累积、学习率、checkpoint 和采样。这样能把“模型怎么计算”和“训练怎么长期稳定运行”连成一条线。

Claude Code 的官方文档、Anthropic 工程文章、事故报道和多方公开逆向分析共同指向同一个结论：工业级 AI 编程 agent 的核心不只在模型，还在模型外部的执行控制面。真正值得学习的是工具契约、权限链、上下文预算、流式执行、任务拆分、文件编辑约束、错误恢复、沙箱和可观测性。本节只抽取适合自研 AI 编程系统借鉴的工程模式，不提供可还原 proprietary 实现的细节。

Claude Code 相关材料可以分成四类：官方文档公开的产品机制，Anthropic 工程与产品文章，媒体和安全社区对 sourcemap 外溢事件的报道，社区对泄漏材料的逆向分析。本文把本地整理稿只作为线索，不作为唯一证据。官方文档适合确认当前产品能力；工程文章适合确认沙箱、checkpoint、SDK 等正式路线；事故报道适合确认泄漏边界；社区逆向分析适合观察工业实现的取舍。

这个边界对代码精读很重要。AI 编程 agent 的可迁移价值主要来自控制面设计，而非某段具体业务源码。本文采用“模式抽象”的写法：保留系统设计、数据流、约束点和失败恢复思路，删除专有字符串、内部代号、完整 prompt、真实文件名与可还原实现。可以用于自研系统的是方法：如何拆 prompt，如何保证工具可验证，如何在长会话中保住上下文，如何在后台任务里隔离权限。

观察对象	可学习内容	落到自研系统的形式
官方 Claude Code 文档	hooks、permissions、memory、MCP、subagents、settings 层级	产品层 API 与配置模型
Anthropic 工程与产品文章	沙箱、checkpoint、IDE 集成、Agent SDK、自治任务边界	正式产品路线与安全边界
媒体和安全社区报道	sourcemap 外溢、npm 包版本、是否涉及客户数据、供应链教训	事故边界与发布安全 checklist
社区逆向分析	prompt cache、工具池排序、compaction、AsyncGenerator loop、权限链、feature flag 线索	工程架构与运行时策略
本地整理稿	模块划分、失败注释、上下文压缩细节、可疑功能名	只作为待复核线索，不能单独定论

重新检索公开网络材料后，需要把“确定事实”和“社区热议说法”分开。Claude Code 的官方文档已经足够确认 permissions、memory、hooks、subagents、MCP 等控制面；事故报道和安全分析支持 sourcemap 外溢这个事件本身；大量更戏剧化的说法，例如隐藏代号、内部 roadmap、具体 feature flag 数量、Bash 安全检查行数或某个内部功能名，只能作为社区逆向线索处理。

可信度	可写入正文的内容	写作处理
官方已证实	Claude Code 有细粒度权限规则；deny、ask、allow 有明确优先级；CLAUDE.md 和 auto memory 会进入会话上下文；hooks 可在生命周期事件上执行；subagent 有独立上下文、工具限制和权限；prompt caching 按工具、system、messages 的前缀缓存工作。	作为架构基线写入正文，可直接抽象成自研设计。
多源交叉支持	2026-03-31 前后，Claude Code npm 包的 sourcemap / mapping artifact 被公开报道可用于重构相当规模的 TypeScript 源码；公开材料普遍把它归类为发布制品外溢，而非模型权重、客户仓库或云端凭证泄露。	作为发布安全案例写入，但避免复述泄漏源码细节。
社区逆向线索	具体代码行数、文件数、feature flag 数量、内部代号、反蒸馏策略、Undercover Mode、KAIROS、Bash 检查数量等说法在不同文章中口径不完全一致。	不作为确定事实；只在“可能的设计线索”层面讨论。
本地整理稿内容	更细的模块命名、失败注释、内部流程和具体实现细节。	除非能被官方文档或多方公开材料支撑，否则不进入正文定论。

从官方文档和公开分析交叉看，Claude Code 的可迁移架构可以拆成六个平面。模型推理只是中间一层；上下文、工具、权限、记忆、扩展和发布安全共同决定系统是否可靠。

平面	核心问题	Claude Code 给出的工程启发
上下文平面	哪些信息进入模型，哪些信息压缩，哪些信息沉淀为记忆。	稳定前缀、动态后缀、CLAUDE.md、auto memory、subagent 独立上下文共同服务 token 预算和缓存命中。
工具平面	模型如何把意图变成可执行动作。	工具需要 schema、权限检查、执行函数、结果预算和审计事件；文件编辑和 Bash 需要比普通工具更强的约束。
权限平面	哪些动作可以自动执行，哪些必须询问，哪些永远阻断。	deny 优先、ask 次之、allow 最后；高风险模式只能放在容器、虚拟机或受控沙箱里。
扩展平面	团队如何把内部工具、安全规则和工作流接进 agent。	MCP、hooks、skills、plugins、custom subagents 分别改变工具来源、生命周期控制、任务知识和执行角色。
运行时平面	长任务如何流式输出、恢复失败、并行执行和回滚。	事件流、checkpoint、工具批处理、上下文 compaction、PromptTooLong 恢复链是核心结构。
发布安全平面	闭源 CLI 如何避免把调试制品、内部字符串或 roadmap 一起发布。	sourcemap 策略、sourcesContent 裁剪、敏感字符串扫描、feature flag 裁剪和制品审计必须进入 CI。

AI 编程 agent 的主循环可以抽象为四步：收集上下文、调用模型、执行工具、把结果写回上下文。工业实现的复杂度主要来自“每一步都必须有边界”：上下文不能无限增长，工具不能无条件执行，写文件必须可校验，失败必须可恢复。

这段抽象代码的重点是职责分离。模型负责提出下一步动作，工具层负责把动作落到真实系统，权限层负责阻止越界，压缩层负责维持上下文可用。把这些职责混在一个巨大 prompt 里，系统很快会变成不可调试的黑箱。

Claude Code 类产品的 prompt 往往远大于用户输入。固定系统规则、工具说明、代码风格、权限提示和已知失败模式约束都会进入请求。Anthropic prompt caching 文档明确说明，缓存对象是请求前缀，顺序覆盖 tools、system、messages，直到 cache breakpoint。因此，agent harness 的 prompt 装配应拆成稳定前缀和动态后缀：稳定前缀尽量保持逐字节一致，动态后缀承载当前目录、会话状态、最近文件、CLAUDE.md、临时规则和用户输入。

这种拆分同时服务三件事：成本控制、可维护性和行为稳定。稳定前缀越稳定，prompt cache 命中率越高；动态段越靠后，某次会话的时间戳、工作目录或临时文件列表就越不会破坏前面的缓存。官方文档还给出两个重要工程参数：默认缓存寿命是 5 分钟，另有 1 小时缓存选项；这意味着长任务循环要尽量保持热路径稳定，避免频繁重排工具和 system block。

这里的关键约束是“动态信息后移”。工具列表排序、MCP 工具分组、模式化 prompt 的注入位置，都应围绕缓存边界设计。一个看似普通的排序函数，在线上规模下会直接影响 API 输入成本。

AI 编程 agent 的前端需要实时显示模型输出、工具调用、权限等待、测试日志和中断状态。普通的同步函数很难描述这种流式生命周期。社区逆向分析中反复提到的一个亮点，是把主查询过程写成可迭代事件流：模型 token、工具开始、工具完成、权限阻塞、压缩重试、最终回答都变成事件。

这种写法的优点是背压清晰。终端 UI、日志系统、权限弹窗、工具执行器都消费同一条事件流；中断、重试和恢复也能作为事件明确表达。对自研系统而言，AsyncGenerator 比回调嵌套更容易测试，也更适合把长任务拆成可观察的阶段。

Claude Code 类系统通常把工具定义成“模型可见说明 + 输入 schema + 权限检查 + 执行函数”的组合。这里最有价值的设计，是在工具入口用结构化参数约束模型，压缩自由生成命令文本带来的错误空间。

old_str 的精确唯一匹配非常关键。它把“模型觉得自己知道位置”变成“工具可以验证模型知道位置”。这个设计直接降低误改文件的概率，也让失败可以自然反馈给模型重新定位。

工具越多，prompt 越长，模型的选择空间也越大。Anthropic 的 Tool Search 文档把这个问题抽象成“动态发现工具”：系统先让模型搜索工具目录，再按需加载具体 schema，减少一次性展开所有工具定义的上下文成本。Claude Code 与 MCP 场景的公开分析也反复指向同一工程目标：内建工具、MCP 工具和低频扩展工具应分区排序和延迟加载，避免外部工具增删扰动核心工具的缓存前缀。

延迟加载工具有两个收益。第一，低频工具不占初始 prompt；第二，工具集变化对缓存前缀的影响变小。对于接入大量内部 MCP 服务的团队，这个设计比单纯增加上下文窗口更实际。

代码 agent 的危险动作集中在 Bash、文件写入、网络访问、MCP 外部工具和 Git 操作。Claude Code 官方权限文档给出的核心规则是 deny、ask、allow 分层决策，deny 规则优先级最高。工业系统应把权限做成运行时控制链，避免把安全边界完全交给 prompt 自律。

权限链的工程目标是把“是否执行”从模型输出里剥离出来。模型可以建议执行，系统负责判断能否执行。对 Bash 这类影响面极大的工具，静态规则、风险分类、交互确认和审计日志都应同时存在。

权限系统解决的是“能不能执行这个动作”，沙箱解决的是“即使执行了，动作能影响到哪里”。Claude Code 官方 sandboxing 文档和 Anthropic 工程文章都强调两个边界：filesystem isolation 和 network isolation。文件系统隔离缺少网络隔离时，恶意命令仍可能把敏感文件发出去；网络隔离缺少文件系统隔离时，恶意命令仍可能读取或破坏宿主机文件。企业级 AI 编程系统应把沙箱当成默认执行边界，减少对逐条 Bash 人工确认的依赖。

这个抽象的关键点是：permission prompt 只是一层交互确认。用户批准一次危险命令后，真正限制损害半径的是沙箱、网络策略、凭证裁剪和审计。自研系统如果支持 unattended mode 或后台 agent，沙箱优先级应高于“跳过权限提示”。

Claude Code 官方 checkpointing 文档说明，系统会跟踪文件编辑工具产生的修改，每个用户 prompt 形成新的 checkpoint，checkpoint 可跨恢复会话保存并按配置清理。这个能力对 AI 编程系统很关键：模型可以一次修改多个文件，用户也需要在错误方向上快速回滚，避免手工从 Git diff 里一点点撤销。

Checkpoint 和 Git 的职责不同。Git 负责长期版本控制和协作历史；checkpoint 负责 agent 会话内部的细粒度撤销。对于探索性重构、批量格式化、自动修复测试这类任务，checkpoint 是让模型敢于行动、用户敢于授权的基础设施。

Hooks 是 Claude Code 设计里最适合企业落地的一层。Prompt 和 CLAUDE.md 都属于模型可见指令，模型可能因为上下文拥挤或任务压力而漏遵守；hook 是运行时控制点，可以在工具执行前阻断、在工具执行后修正、在会话结束时归档，行为更接近 Git hooks 或 CI gate。官方 hooks 文档把事件分成 session、turn、tool-call 等节奏，包含 SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PostToolBatch、Notification、SubagentStart、Stop、StopFailure 等事件。

Hooks 的实用模式包括：Bash 执行前做命令白名单，Edit 之后自动格式化，Stop 阶段运行测试摘要，Notification 阶段推送桌面提醒，SessionStart 阶段注入环境说明。它们把“希望模型遵守”改成“系统一定执行”。

长上下文并不同于可无限堆历史。AI 编程场景里，工具结果是上下文膨胀的主要来源：读文件、grep、运行测试、打印日志都会产生大量内容。Claude Code 类系统的经验是分级处理：先做低成本清理，再做结构化摘要，最后把跨会话信息沉淀到独立记忆系统。

层级	处理对象	工程意义
工具结果预算	单次 Bash / grep / read 的长输出	保留首尾和摘要，把完整内容落盘或省略，避免单个工具结果占满上下文
Micro Compact	已经被模型消化过的旧工具结果	用占位符替换低价值原文，尽量保持 prompt 前缀稳定
Auto Compact	接近上下文上限的完整会话	调用模型生成结构化摘要，保留任务、决策、文件状态和待办事项
长期记忆	跨会话仍有价值的项目规范、用户偏好、架构约束	从上下文窗口里移出，按需召回，避免每轮都把历史全塞回 prompt

上下文压缩要保留“继续工作的充分条件”。当前目标、已改文件、失败原因、未完成任务、用户约束和最近文件内容，比完整历史对话更重要。

长会话里最常见的失败来自运行时预算耗尽：prompt 太长、输出 token 不够、工具结果过大、自动压缩失败、权限请求循环。工业级 agent 要把这些情况当成正常分支处理，避免把恢复成本转嫁给用户重开会话。

这里的硬上限很重要。自动压缩本身也会调用模型；如果压缩失败后继续无界重试，就会形成成本和延迟的放大器。可恢复错误需要恢复链，可恢复链也需要熔断器。

Claude Code 的记忆设计可以按生命周期拆开：当前会话上下文负责短期状态，CLAUDE.md 和规则文件负责团队显式知识，auto memory 负责模型从用户纠正中沉淀出的个人或项目经验。官方 memory 文档明确区分 CLAUDE.md 和 auto memory：前者由用户维护，适合编码规范、工作流和项目架构；后者由 Claude 根据纠正和偏好自动积累。三者不要混用。构建自研系统时，最容易犯的错误是把所有东西都塞进一条 system prompt，导致规则难维护、缓存难命中、过期信息难清理。

自动记忆要有类型约束和过期提示。适合写入的内容包括用户偏好、调试结论、项目约定、反复出现的坑；不适合写入的内容包括一次性日志、临时 token、错误猜测和敏感数据。长期记忆进入下一次会话时，应标注来源和时间，避免模型把旧经验当成当前事实。

代码 agent 需要并发，否则读多个文件、跑多个只读搜索会很慢。并发策略的关键是按工具调用的实际输入判断安全性，避免给工具贴一个脱离输入的永久标签。

这个设计让系统既能利用并行，又不会把写操作打乱。更细的实现还会把 context modifier 延迟到所有并发结果结束后按原始顺序应用，避免并发工具同时修改会话状态。

复杂代码任务常常需要拆分：一个 agent 负责探索，一个 agent 负责实现，一个 agent 负责验证。Claude Code 官方 subagents 文档强调，每个 subagent 有自己的上下文窗口、custom system prompt、特定工具访问权限和独立权限。Subagent 的工程价值在于隔离上下文、工具权限、任务状态和文件修改范围，使并行协作不会互相污染。

模式	上下文关系	适合任务
fork	复制父上下文，适合复用 prompt cache	后台摘要、记忆提取、短探索任务
teammate	独立上下文，只返回结论	并行读代码、独立调研、互不污染判断的分析任务
worktree	独立上下文 + 独立文件系统视图	多个 worker 并行改代码，最后由主 agent 或用户合并

自研系统可以先实现最小可用的 teammate 模式：主 agent 只派发具体问题，subagent 只返回结构化结论。等任务开始涉及并行改文件，再引入 Git worktree 级隔离。

多篇社区逆向材料提到 Claude Code 中存在大量 feature flag。具体数量和内部名称属于中等可信线索，正文不把它们当成确定事实；但 feature flag 对 AI 编程工具的工程意义很明确。它不仅服务灰度发布，还承担构建裁剪、内部功能隔离、实验开关、后台 agent 模式控制和风险回滚。尤其是 CLI 产品，发布包里包含什么、source map 是否包含源文本、内部字符串是否被剥离，都会变成安全边界的一部分。

这类发布安全不属于“模型能力”，但直接决定 AI 工具是否能进入企业环境。自研 agent 只要包含内部工具、私有 MCP、实验模型代号或客户环境信息，就应把构建裁剪、敏感字符串扫描和 sourcemap 策略写进发布流水线。

• 文件编辑工具要强制可验证定位，例如精确字符串匹配、AST 范围、patch 预览，不能让模型直接自由写整段文件。
• Bash 工具要有独立安全体系，包含命令解析、静态规则、动态风险判断、用户确认、审计和输出预算。
• 上下文压缩要分级，先清工具结果，再做摘要，最后沉淀长期记忆。不要把所有历史长期塞进 prompt。
• 工具列表、prompt 片段和 MCP 工具排序要稳定，因为稳定前缀直接影响 prompt cache 成本。
• Subagent 的价值在于隔离和并行。主 agent 应该拿结构化结论，避免继承所有中间噪声。
• Hooks 和权限系统要进入运行时控制面。企业场景不能只靠 prompt 自律来阻止危险动作。
• 可恢复错误要有恢复链，恢复链也要有熔断器。PromptTooLong、输出截断和压缩失败都应成为显式分支。
• 发布包要按安全产品处理：feature flag、sourcemap、敏感字符串扫描和内部工具剥离都应纳入 CI。

这一节按官方源码精读三条 NER 主线： pytorch-crf 的 CRF 序列解码、Efficient GlobalPointer 的 span 矩阵打分、GLiNER 的 label-conditioned span classification。源码参照 torchcrf/__init__.py、 models/GlobalPointer.py、 gliner/modeling/span_rep.py、 gliner/modeling/scorers.py 和 gliner/decoding/decoder.py。阅读顺序是：先看模型输出张量是什么，再看 loss 如何定义，最后看 decode 如何把分数还原成实体。

torchcrf.CRF 的源码核心很集中：参数包含起始转移、结束转移和标签间转移；训练时计算“真实路径分数 - 所有路径 logsumexp 归一化”；推理时用 Viterbi 动态规划找最高分标签路径。

\[\log p(\mathbf{y}\mid\mathbf{x})=\mathrm{score}(\mathbf{x},\mathbf{y})-\log\sum_{\mathbf{y}'}\exp(\mathrm{score}(\mathbf{x},\mathbf{y}'))\]

其中 \(\mathrm{score}(\mathbf{x},\mathbf{y})\) 是某一条标签路径的总分，包含每个 token 的 emission score、相邻标签的 transition score、路径起点分数和路径终点分数。

接入 BERT 时，BERT 负责产生每个 token 对每个标签的 emission score；CRF 负责把 token 级局部分数变成序列级路径分数。

torchcrf.forward 内部的核心分成 numerator 和 denominator。numerator 只沿真实标签路径加分；denominator 对所有可能路径做 log-sum-exp，等价于 CRF 的归一化常数。

_compute_score 对真实标签路径逐步加分。这个函数只看 gold path，不枚举其它标签序列，因此它是 CRF 分子的来源。

_compute_normalizer 是分母。它把所有可能路径的分数做 log-sum-exp，得到条件概率里的归一化常数。

Viterbi 解码把 denominator 里的 log-sum-exp 换成 max，并保存每一步的 argmax 来源。最后从最高分结束标签向前回溯，得到全局最高分路径。这个全局路径约束是 CRF 相比逐 token softmax 的核心价值。

CRF 的创新空间主要在约束层。业务规则可以转成转移约束、非法标签惩罚、领域词典软约束或后处理检查；在标签体系稳定、误报代价高的 NER 场景里，这条路线仍然有工程价值。

Efficient GlobalPointer 的源码把实体识别建模成 token-pair 打分。给定 encoder 输出 \([B,L,H]\)，模型产出 \([B,C,L,L]\)，其中 \(C\) 是实体类型数，矩阵位置 \((i,j)\) 表示从 token \(i\) 到 token \(j\) 是否构成该类实体。

Efficient 版本的关键优化是共享 token-pair 主打分，再用每个实体类型的 start/end bias 区分类型。这样比原始 GlobalPointer 的 \(C\) 组 query/key 投影更省参数。

add_mask_tril 是 GlobalPointer 工程实现里最容易漏掉的部分。padding token 不能参与 span，且实体的终点不能早于起点；这两个约束都通过大负数 mask 直接压到 logits 上。

GlobalPointer 的标签也是 \([B,C,L,L]\)。正例 span 置为 1，所有其它合法 span 是负例。训练常用多标签交叉熵；softmax 只适合互斥类别，而同一文本里可以同时存在多个实体、多个类型、甚至嵌套实体。它的创新空间主要在 span 层：实体长度先验、类别相关阈值、边界对比学习、span hard negative mining、嵌套实体优化，都可以直接落到 \([B,C,L,L]\) 分数矩阵上。

解码阶段很直接：在 \([B,C,L,L]\) 中找大于阈值的位置，每个位置就是一个实体候选。工程上要把 token span 映射回原文字符区间，并处理特殊 token、子词边界和阈值。

GLiNER 官方源码是一组可切换架构，覆盖 uni-encoder、bi-encoder、span/token、decoder、relation extraction、ONNX 路线。NER 精读最重要的路径是 span 模型：文本 encoder 产出 token/word 表示，span representation layer 产出候选 span 表示，label encoder 或 prompt representation 产出标签表示，最后用 \(\mathrm{einsum}\) 做 span-label 匹配。

GLiNER 的创新空间主要在标签语义层。标签描述生成、同义标签融合、跨语言 label 对齐、领域标签 prompt search，都能在不改固定分类头的情况下尝试。它也适合作为开放类别召回器，再接 GlobalPointer 或 CRF 做领域精排和约束解码，把开放类别召回能力和垂直领域精度结合起来。

GLiNER 的 span 前向可以压缩成下面这条路径。源码中的 UniEncoderSpanModel.forward 会先拿到文本与标签表示，再构造候选 span 表示，最后计算 \([B,L,K,C]\) 分数，其中 \(K\) 是最大 span 宽度。

GLiNER 的 scorer 路线还可以用 token-label 交互理解：token 表示和 label 表示分别投影，再拼接 token、label、逐元素乘积，最后用 MLP 输出 start/end/score 等分数。

GLiNER 的 decoder 会先对 logits 做概率化，再找超过阈值的 span-label 候选。候选 span 还要通过长度检查，并用 greedy search 去掉不允许的重叠。这个流程对业务非常关键：阈值决定召回/精度， flat_ner 决定是否允许嵌套实体， multi_label 决定同一个 span 是否允许多个类型。

GLiNER 官方 decoder 的 greedy_search 会按置信度从高到低保留 span。这个设计让高置信候选优先占用区间，低置信重叠候选被丢弃；嵌套 NER 和 flat NER 的差异由重叠检测函数控制。

NER 评估必须按实体级看 precision、recall、F1。token accuracy 容易掩盖边界错误，尤其在实体很短、O 标签占比很高的数据集里。对 GLiNER 和 GlobalPointer 这类 span 模型，阈值调优也应围绕实体级指标，token 级准确率只适合作为辅助信号。

这一节只覆盖 ref-6 正文里已经出现过的栈：PyTorch / Transformers / Accelerate / PEFT / TRL / DeepSpeed / vLLM / RAG 向量组件，以及常见的日志与实验跟踪工具（TensorBoard、W&B、MLflow、Langfuse）。每条都给“现象→快速检查→修复动作”。

现象	快速检查	常见根因	修复动作
ImportError: Using device_map requires Accelerate	看代码是否启用了 device_map="auto"	Transformers 需要 accelerate 提供 device map / offload 运行时	pip install -U accelerate，或移除 device_map 并手动 model.to(device)
DeepSpeed 安装成功但首次训练很慢	跑环境报告/查看是否在编译 ops	DeepSpeed ops 走 JIT 编译，首次运行会编译 CUDA/C++ 扩展	把编译链（gcc/g++/ninja）与 CUDA toolkit 固定到镜像；或使用预编译/缓存编译产物
bitsandbytes/FlashAttention/xFormers 安装失败	核对 torch.__version__ 与 CUDA/驱动	二进制 wheel 与 CUDA/torch 组合不匹配，退回源码编译	优先选“官方支持矩阵”内的 torch+CUDA 组合；必要时换到对应 wheel 或统一用容器镜像
huggingface_hub 下载慢/缓存爆盘	检查缓存路径与磁盘配额	默认缓存落在 home 盘；大模型/多版本重复下载	设置 HF_HOME/ HF_HUB_CACHE 到大盘；固定模型版本，避免反复下载

现象	快速检查	常见根因	修复动作
训练 loss 正常，但 eval 指标不动或波动异常	检查 eval 集是否固定、是否数据泄漏、是否用错 metric	数据切分不稳定；指标与 loss 不一致（例如二分类用 F1 优先）	固定 eval 集与随机种子；按任务选择 monitor（生成任务常用 token acc/下游指标；分类任务多用 F1/acc）
同样配置多次训练结果差异大	检查是否固定 seed；是否启用非确定性算子	并行归约顺序、不同 kernel、随机种子未固定	固定 seed；能用 deterministic kernel 的框架启用 deterministic；记录环境/依赖版本到 run_meta
断点续训后 learning rate/step 计数异常	检查是否从正确的 checkpoint 恢复 optimizer/scheduler	只恢复了模型权重，没恢复优化器状态；或切换了 batch size/accumulation	统一用框架提供的 resume 机制；恢复后不随意改动 batch/accumulation；把超参固化在 run_meta
LoRA 训练完线上加载无效果	确认线上是否真的挂载了 adapter；是否用对 base	base checkpoint 不一致；adapter 没加载或没 set_active	把 base_model_id 写入 adapter 元信息；上线前做“base+adapter”一致性 smoke test
DeepSpeed/多机训练 hang 或极慢	打开 NCCL 日志；检查网卡选择	NCCL 走错网络接口；IB/PCIe 拓扑或防火墙	设置 NCCL 环境变量并固定网卡；必要时禁用 IB/P2P 作为定位手段

现象	快速检查	常见根因	修复动作
服务启动成功但客户端 404 / model not found	GET /v1/models 看 model 名	服务端模型名与客户端 model= 不一致	vLLM 启动加 --served-model-name，客户端统一用该名称
服务 QPS 低或频繁 OOM	看 /metrics，关注 KV cache 与并发	context 过长、KV cache 预算过大、GPU mem utilization 过高	降低最大上下文/并发；保留显存余量；把流量打到多副本；按模型大小重新估算 token budget
temperature=0 仍有轻微不一致	确认是否完全禁用采样；是否跨硬件/多实例	服务端并行归约/调度带来非确定性	禁用所有采样相关选项；尽量固定推理硬件与 kernel；把“强确定性”作为服务 SLA 单独约束
端口占用 / 启动失败	lsof -i :8000	端口被旧进程占用	停止旧进程或换端口；把启动/回滚写成脚本并纳入进程管理器

现象	快速检查	常见根因	修复动作
召回结果明显变差（无规律）	检查是否混入不同 embedding 模型版本	同一 collection 混用不同 embedding space	把 embedding_model_id 写入 metadata；版本迁移时重建或双写新集合
cosine 相似度排序不符合预期	检查向量是否归一化；检查 metric 设置	cosine 与 inner product/l2 使用不一致	统一策略：归一化 + inner product（或显式 cosine metric）；写入与查询必须一致
pgvector 查询报错：vector 扩展不存在	SELECT extname FROM pg_extension;	未启用扩展	CREATE EXTENSION IF NOT EXISTS vector;
Qdrant 可用但安全风险	检查是否启用鉴权，端口是否暴露公网	默认 Docker QuickStart 无认证	启用 API key/鉴权；仅暴露内网；生产环境用 Helm/Cloud 并加网络策略
Milvus/TCVectorDB 连接失败	检查 endpoint/token/TLS	网络不可达、鉴权不匹配、TLS 配置问题	先用最小 client 读写验证；把 endpoint/token/TLS 作为运行时配置（环境变量/密钥管理）

需求	优先选	理由	不适合时的信号
想要最短路径微调 LLM（SFT/DPO/GRPO）	TRL + (Transformers + PEFT) + Accelerate	方法流程化、接口稳定、与 HF 生态耦合最深	需要高度自定义训练循环/复杂多任务调度，且团队已有自研训练框架
通用训练循环（分类/NER/CV）且团队多人复用	Transformers Trainer 或 PyTorch Lightning 或 MMEngine	训练工程样板收敛到统一入口；callbacks/loggers/checkpoint 更标准	训练逻辑高度非标准（例如特殊采样/复杂图结构），框架抽象反而增加阻力
大模型训练显存吃紧，需要参数/优化器分片	DeepSpeed ZeRO 或 PyTorch FSDP（常经由 Accelerate）	把显存压力从“模型/优化器/梯度”三个维度拆开	集群/网络不稳定；团队缺少分布式排障经验；checkpoint 迁移频繁
需要高吞吐服务化推理（OpenAI API 兼容）	vLLM（ vllm serve）	continuous batching、KV cache 管理、指标/观测与并行策略更贴近生产	只需离线小批推理且依赖纯 Transformers；或模型结构/算子不被 vLLM 支持
RAG 召回（单机/单租户/延迟极低）	FAISS	部署简单、延迟低、索引可控	需要多租户、过滤、持久化、高可用与在线扩缩容
RAG 召回（已有 Postgres 体系）	pgvector	事务/权限/JOIN/备份沿用 Postgres，治理成本低	超大规模向量 + 高 QPS；需要专用 ANN 系统能力
RAG 召回（专用向量数据库能力）	Qdrant / Milvus / 托管向量库（TCVectorDB）	过滤、持久化、分布式扩展与运维能力更完整	团队没有运维能力（自建风险高）；对迁移性要求极强（托管绑定风险）

术语	训练侧含义	推理/服务侧含义	落点（代码/命令）
base / adapter	base 是大权重 checkpoint；adapter 是 LoRA 等增量参数	服务端加载 base 后挂载 adapter，或提前 merge 导出	PEFT： PeftModel.from_pretrained / merge_and_unload
checkpoint	训练过程中的可恢复状态（含 optimizer/scheduler 视框架而定）	上线时通常只需要“可加载权重目录”（artifact）	Transformers/TRL： output_dir/checkpoint-*
artifact（模型包）	训练导出的可交付目录	推理服务直接加载的路径	save_pretrained 目录结构
device_map	训练/推理加载时的设备放置策略	服务端决定权重落 GPU/CPU/offload 的方式	Transformers： device_map="auto"
torch_dtype	训练计算 dtype（fp16/bf16/fp32）	推理加载 dtype（影响显存与速度）	Transformers： torch_dtype="auto"
TTFT / TPOT	训练不直接出现	首 token 延迟 / 每 token 延迟，衡量推理体验	vLLM： /metrics + 业务侧统计
topK / rerank	训练侧用于召回模型/排序模型的训练	RAG 检索阶段：ANN 召回 topK，reranker 取 topN	向量库 search + Cross-Encoder rerank

类型	路径模式	说明
HF Datasets / PyTorch 训练输入	data/processed/train.jsonl	离线预处理脚本产出的标准化样本文件，通常交给 datasets.load_dataset 或自定义 Dataset/ DataLoader 消费。
Trainer / TRL checkpoint	outputs/runs/<run_id>/checkpoint-*/	由 Hugging Face Trainer 或 TRL Trainer 自动产出，目录内常见 trainer_state.json、优化器状态和分步权重，用于断点续训、best checkpoint 选择和实验回溯。
DeepSpeed ZeRO 分片 checkpoint	outputs/runs/<run_id>/global_step*/mp_rank_*/	由 DeepSpeed 产出的分片状态目录，内部常见 rank 级别的模型和优化器状态文件，主要用于 ZeRO 恢复和后续权重聚合，不能直接拿给 vLLM 或纯 Transformers 推理。
PEFT adapter 目录	adapters/<task_name>/{adapter_config.json,adapter_model.safetensors}	由 PEFT 的 save_pretrained 产出，只保存 LoRA/adapter 增量参数；推理时需要先加载对应 base model，再用 PeftModel.from_pretrained 挂载。
Transformers 模型包	models/registry/model_vXXXX/{config.json,tokenizer.json,model*.safetensors}	由 Transformers 的 save_pretrained 或 PEFT merge 导出脚本产出，是最通用的可部署目录；可直接被 Transformers、vLLM、TGI 等推理框架加载。
服务加载指针	models/prod -> models/registry/model_vXXXX/	这核心是服务编排层给 vLLM、TGI、Transformers API 服务提供的稳定加载入口；切换软链接即可完成上线与回滚。
FAISS 本地索引	indexes/faiss/<collection>.faiss	由 faiss.write_index 产出，服务于单机/嵌入式 ANN 检索；通常还要配一份外部 metadata 文件保存 doc_id、chunk_id 与原文偏移。
Qdrant 持久化目录	qdrant_storage/	由 Qdrant Docker 或 standalone 进程维护，是 collection、payload 与索引文件的持久化卷；开发环境常直接挂到本地目录，生产环境通常挂载独立数据盘或云盘。

命令/API/函数 accelerate config / accelerate launch train.py 说明 多卡启动训练。用于 Accelerate 路线的多卡训练启动。第一条命令生成分布式配置，第二条命令按配置拉起同一份 PyTorch 训练脚本。 示例 Shell 1 2 accelerate config accelerate launch train.py

命令/API/函数 deepspeed --num_gpus=8 train.py --deepspeed ds_config.json 说明 DeepSpeed 启动训练。用于 DeepSpeed 训练入口。 ds_config.json 固化 ZeRO、offload、AMP 与通信策略，适合大模型显存压缩场景。 示例 Shell 1 deepspeed --num_gpus=8 train.py --deepspeed ds_config.json

命令/API/函数 vllm serve /abs/path/to/models/prod 说明 启动 vLLM 服务。用于启动 OpenAI-compatible 的 vLLM 服务。固定 --served-model-name 后，客户端就不需要感知底层真实模型目录。 示例 Shell 1 2 3 4 vllm serve /abs/path/to/models/prod \   --host 0.0.0.0 --port 8000 \   --served-model-name prod \   --api-key token-abc123

命令/API/函数 curl -sf http://127.0.0.1:8000/v1/models / curl -sf http://127.0.0.1:8000/metrics | head 说明 检查服务与指标。最小 smoke test。第一条检查模型是否已注册，第二条确认 Prometheus 指标端点是否可用。 示例 Shell 1 2 curl -sf http://127.0.0.1:8000/v1/models curl -sf http://127.0.0.1:8000/metrics | head

命令/API/函数 docker run -p 6333:6333 -v "$(pwd)/qdrant_storage:/qdrant/storage:z" qdrant/qdrant 说明 启动 Qdrant（开发）。用于本地开发环境拉起 Qdrant。挂载卷保存索引和 payload；默认没有鉴权，生产环境必须补安全配置。 示例 Shell 1 docker run -p 6333:6333 -v "$(pwd)/qdrant_storage:/qdrant/storage:z" qdrant/qdrant

命令/API/函数 psql -d your_db -c "CREATE EXTENSION IF NOT EXISTS vector;" 说明 启用 pgvector。用于在 PostgreSQL 中启用 pgvector 扩展。只有扩展启用后，后续的向量列、HNSW/IVFFlat 索引和相似度查询语法才可用。 示例 Shell 1 psql -d your_db -c "CREATE EXTENSION IF NOT EXISTS vector;"

命令/API/函数 pip install -U openmim / mim install mmengine 说明 安装 OpenMMLab 训练底座。用于安装 OpenMMLab 生态的统一底座。后续安装 MMDetection、MMPreTrain、MMSegmentation 等仓库时，都会复用这套基础设施。 示例 Shell 1 2 pip install -U openmim mim install mmengine