SWIFTms-swift官方 FAQ 全解数据准备、训练、推理、导出、部署与评测常见问题深度指南【免费下载链接】swiftUse PEFT or Full-parameter to CPT/SFT/DPO/GRPO 600 LLMs (Qwen3.6, DeepSeek-V4, GLM-5.1, InternLM3, Llama4, ...) and 300 MLLMs (Qwen3-VL, Qwen3-Omni, InternVL3.5, Ovis2.5, GLM4.5v, Gemma4, Llava, Phi4, ...) (AAAI 2025).项目地址: https://gitcode.com/GitHub_Trending/swift1/swift本文基于 SWIFTms-swift官方常见问题文档 Frequently-asked-questions.md 系统整理并深度扩充覆盖数据集、训练、推理、导出、部署、评测六大类 110 条高频问答并结合当前仓库源码如 loss_map 注册表、序列并行 loss 实现、CLI 入口与 examples 下的真实脚本逐一印证帮助你快速定位并解决 SFT/GRPO/蒸馏/量化/部署全流程中的典型问题。一、数据准备类常见问题SWIFT 内置 150 数据集覆盖预训练、指令微调、对齐与多模态等任务同时支持自定义数据集。数据接入与预处理是训练前的第一道关卡以下按官方 FAQ 的 Dataset 章节逐条展开。1.1 数据集支持范围、自定义格式与下载检查支持哪些数据集完整列表见 支持模型与数据集文档。如何使用自定义数据集格式说明见 自定义数据集文档。符合官方格式的数据集会自动调用 SWIFT 内置数据预处理器当前版本对应 preprocessor 核心实现格式不符时需参照内置数据集自行转换。自定义数据集中的额外字段默认不会被使用可通过--remove_unused_columns配置其去留。如何下载并使用数据集可先git clone下载到本地再通过dataset_info.json中的dataset_path字段指定路径下载行为重新下载或复用上次下载结果由--download_mode指定。如何做数据检查与打乱设置--strict True对数据集做错误检查数据质量治理可搭配数据清洗工具>File .../dataset/preprocessor/core.py, line 69, in _check_messages raise ValueError(fassistant_message; {assistant_message}) ValueError: assistant_message: {role :assistant, content: }当前仓库中该检查逻辑位于 _check_messages会校验role合法性且content非空。若是用于推理的数据可直接删除空的 assistant 消息。1.3 缓存加载、多模态、大数据与流式加载缓存加载Q3--load_from_cache_file True可加速数据集加载首次除外对多模态与大数据集收益明显调试或修改预处理器代码时应设为 false确保改动生效。多模态数据集Q4纯文本、图文混合均可训练示例见 examples/train/multimodal含 grounding.sh 等。图像/视频/音频相关参数最大像素、FPS 等见 命令行参数文档·模型特定参数。Grounding 任务常见格式支持一个物体多个框格式见 自定义数据集文档·Grounding训练阶段 SWIFT 会自动调整超过--max_pixels的图像并保存预处理前后图像、同步调整框坐标推理阶段不做调整需手动预处理图像。大数据集Q5逐条 tokenize 耗时长时使用--lazy_tokenize True或流式读取--streaming True。流式加载Q6--streaming True为边加载边训练必须设置max_steps。注意流式模式不随机、不自动划分验证集验证集需通过--val_dataset显式指定从断点续训时流式只能顺序索引、无法随机跳过已训数据耗时很长因此断点场景不建议使用流式。多进程加速Q7多模态数据集 map 慢属正常现象可设置--dataset_num_proc开启多进程加速。二、训练环境、模型准备与模板2.1 环境搭建、离线安装与镜像环境配置详见 SWIFT 安装文档常见依赖推荐版本见 README依赖清单可参考 requirements/framework.txt。离线安装流程1. Clone the image using git (internet connection required) 2. Install locally using pip -e .官方提供 Docker 镜像docker pull拉取、docker run启动容器例如# 拉取镜像 docker pull modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.38.1-swift4.4.1 # 后台启动容器-d 使容器长期后台运行 docker run --gpus all -p 8000:8000 -dit --name ms modelscope-registry.cn-hangzhou.cr.aliyuncs.com/modelscope-repo/modelscope:ubuntu22.04-cuda13.0.3-py312-torch2.11.0-vllm0.23.0-modelscope1.38.1-swift4.4.1 /bin/bash # 进入容器 docker exec -it ms /bin/bash容器启动后再拉取最新 SWIFT 代码安装即可。2.2 模型下载、存储路径与 model_type支持模型列表见 支持模型与数据集文档。模型已下载到本地时用--model model_path即可离线训练需同时设置--model 本地模型路径与--check_model false若遇 git clone 相关报错可用--local_repo_path 本地仓库路径指定本地仓库。ModelScope 下载的模型可通过环境变量MODELSCOPE_CACHEyour_path指定存储路径使用 ModelScope SDK 时可用--cache_dirlocal_path指定也可用modelscope download命令行或git下载。从 Hugging Face 下载模型需设置环境变量USE_HF1。model_type会被自动匹配也可手动指定对照 支持模型与数据集文档。2.3 模板相关问题Jinja chat template 没有 loss 标签当前不支持直接训练这类模板。多模态数据集若在数据加载后需要动态数据增强如随机加噪需修改 template 的encode方法模板实现位于 swift/template模板注册见 register.py。导出场景中模板由 SWIFT 内部定义、不保存为 Jinja因此无法通过导出永久修改自定义 template_type见第五节 Export 部分。三、训练调试与三种使用入口3.1 Python 方式调试训练调试可直接调用训练入口等价于命令行微调但不支持分布式调试。命令行微调入口见 swift/cli/sft.py其最终调用swift.pipelines.sft_mainfrom swift import sft_main, SftArguments result sft_main(SftArguments( modelQwen/Qwen2.5-7B-Instruct, tuner_typelora, dataset[AI-ModelScope/alpaca-gpt4-data-zh#500, AI-ModelScope/alpaca-gpt4-data-en#500, swift/self-cognition#500], torch_dtypebfloat16, # ... ))3.2 脚本与 Web UI 入口Python 脚本训练参考 examples/notebook 中的 notebook 示例如 qwen2_5-self-cognition。Web UI 训练swift web-ui命令启动界面训练与自定义数据集用法同命令行界面参数对照 命令行参数文档 即可理解。Megatron-SWIFT 不支持 UI 界面训练。YAML 配置Q38grpo 与 sft 均可通过 YAML 文件配置配置会在 主入口 被处理成命令行参数。四、多模态训练、分布式与断点续训4.1 多模态模型训练要点VLM 训练显存紧张时配置--freeze_vit true并限制--max_pixels。ViT 不参与训练时出现warning: none of the inputs have requires_gradTrue属正常若 ViT 参与训练则不应出现该警告。--freeze_vit、--freeze_aligner、--freeze_llm的参数说明见 命令行参数文档·Tuner。“全参微调视觉编码器 LoRA 微调 LLM”的组合参考 lora_llm_full_vit 示例。特殊模型限制Q34MiniCPM-O 暂不支持音频模态输入训练DeepSeek-VL-2 微调需transformers4.42且peft0.11.*Moonlight-16B-A3B-Instruct 因模型文件禁用训练需参照 DeepSeek-VL-2 的解决方案处理Ovis2 微调需 pad 到max_length必须显式设置--max_lengthQwen2.5-Omni 当前仅支持 thinker 训练、不支持 talkerQwen2-Audio 的 SFT 不支持 packing。多任务视频采样Q41同时微调 VLM 多个任务且视频采样规则不一致时检索 命令行参数文档 中的--interleave_prob。qwen2.5-omni 只开音频编码器Q51--freeze_vit false会同时打开视觉与音频编码器只训练音频编码器可用正则匹配目标模块路径例如--target_regex .*audio.* # 只匹配含 audio 的模块多模态 packing 预训练 OOMQ42每步 allocator 缓存刷新后显存缓慢上涨、步数多了易 OOM 时添加环境变量PYTORCH_CUDA_ALLOC_CONFexpandable_segments:True减少显存碎片。--use_logits_to_keepQ43多模态 token 扩展发生在模型外部时可用发生在模型 forward 内部时会报错。4.2 单机多卡与多机多卡单机多卡底层依赖 torchrundeepspeed与device_map互斥只能二选一。单机多卡示例见 examples/train/multi-gpu。多机多卡训练时只有 master 节点输出日志示例见 examples/train/multi-node。多机训练可能偏慢例如 DeepSpeed ZeRO3 在多机下会有明显降速详见仓库 issue 1825。save_steps 语义Q27训练脚本中save_steps指global_step即本地 TQDM 进度条显示的值。注意力实现与 paddingQ35/Q36不支持 flash attention 的设备默认使用 SDPA训练默认右 padding左/右均可选择batch 推理恒为左 padding。4.3 断点续训保持原训练脚本参数不变追加--resume_from_checkpoint output/xxx/vx-xxx/checkpoint-xxx即可trainer 会自动读取权重与相关状态。只想加载模型、忽略优化器状态与随机种子时追加--resume_only_model。更复杂场景检索 命令行参数文档 中resume关键字。Megatron-SWIFT 断点续训需要额外配置--mcore_model path/to/checkpoint-xxx # 加载模型权重 --finetune false # 标记为微调模式而非继续预训练 --no_load_optim # 不加载优化器状态可选 --no_load_rng # 不恢复随机数状态可选LoRA 断点续训需额外设置--mcore_adapter否则与全参训练一致。五、Packing、Checkpoint 与 Loss/Acc 计算5.1 Packing 相关问题Packing 必须与 flash_attn 一起使用否则 attention_mask 会出问题导致报错。Qwen3.5 的线性注意力不支持 var_len不建议开启 packing。开启 packing 后多模态数据会被映射两次数据集映射 模板映射速度很慢时可设置OMP_NUM_THREADS14加速或干脆去掉 packing 避免二次映射。packing 使用示例见 examples/train/packing。5.2 Checkpoint 保存默认保存所有checkpoint数量由save_total_limit控制见 命令行参数文档。磁盘空间不足会导致保存不完整例如出现safetensors_rust.SafetensorError: Error while deserializing header: HeaderTooLarge即模型未完整落盘、权重被截断Q48。5.3 Loss 相关自定义 loss通过--external_plugins导入自定义 loss 的 .py 文件swift sft \ --external_plugins /path/to/plugin.py \ --loss_type my_loss \ # ...--loss_type的取值对应自定义 loss 注册进 loss_map 的 keyloss_scale 同理需注册进 loss_scale_map。当前内置 loss 一览见 loss_map含cross_entropy、cosine_similarity、contrastive、online_contrastive、infonce、pointwise_reranker、listwise_reranker可在此查看已支持 loss 或添加新 loss。分数据集 loss 曲线设置--enable_channel_loss。特殊 token 是否计入 loss查看命令行日志打印的 labels即可判断image等特殊 token 是否参与 loss。Agent 训练tool_call计入 losstool_response不计入 loss。5.4 Acc 相关训练期 eval 的 acc 与对 ckpt 重新推理计算的 acc 不一致可能是两者口径不同。检查--acc_strategy参数默认token可选token、seq。部分模型训练时没有 token_acc原因是logits与labels的数量不匹配。推理期指标Inference Q8使用--metric在推理中计算 ACC/ROUGE 等指标参数说明检索 命令行参数文档。六、参数冻结、序列并行、词表扩展与 Tuner6.1 模型参数冻结DDP 多卡训练中冻结部分层会导致部分参数不产生梯度需配置--ddp_find_unused_parameters True自动跳过无梯度参数。--freeze_parameters/--freeze_vit/--freeze_aligner/--freeze_llm冻结的参数允许被后续执行的activate_parameters覆盖即解冻优先级更高。--freeze vit/--freeze aligner/--freeze llm会联动调整冻结范围部分模型的 ViT 包含 aligner使用--freeze aligner False时可训练参数会同步调整且会单独把aligner加入确保其不被冻结。--freeze_parameters_ratio的机制是从 embedding 开始自底向上冻结参数。6.2 序列并行pt、sft、dpo、grpo 均支持序列并行命令行示例见 examples/train/sequence_parallel含 sequence_parallel_grpo.sh、sequence_parallel_dpo.sh、512K 长文场景等。VLM 模型目前仅支持 flash-attn纯文本模型支持 flash-attn 与 sdpa 两种注意力。序列并行可与 Liger kernel 同时使用。自定义 loss 在序列并行下不生效可能是因为序列并行使用了独立的 loss 函数可按需修改 per_token_loss_func_sp该函数内部还会通过环境变量CELOSS_PARALLEL_SIZE启用分块交叉熵以降低显存峰值并用GatherLoss跨卡聚合逐 token loss 与 labels。6.3 扩展词表需同时设置--new_special_tokens path/to/tokens.txt与--modules_to_save embed_tokens lm_head解冻对应参数参与训练。完整示例见 examples/train/new_special_tokens含 tokens.txt 与 train.sh。6.4 Tuner 相关SWIFT 的 LlamaPro 已适配多模态训练。LongLoRA 依赖特定架构组件仅 LLaMA 系列模型可用。LoRA 训练与--trainable_parameters参数不兼容除 LoRA 模块外需要额外训练的参数应使用--modules_to_save。unsloth 报错Q50assert(type(target modules) in (list,tuple,))。原因是all-linear不会被 unsloth 的 LoRA 实现展开需改为具体模块列表如--target_modules q k v。七、Embedding/Reranker、分类与思维模型训练Embedding/RerankerQ19训练示例分别见 examples/train/embedding 与 examples/train/reranker数据格式见 自定义数据集文档。分类训练Q20需设置--num_labels与--problem_type多标签分类数据格式见 自定义数据集文档注意数据集里 label 与 messages 字段处于同一层级。思维模型训练Q21/Q57/Q58训练数据涉及 CoT 时建议开启思维模式并非所有含think标签的数据都必须开启——若数据不涉及大量逻辑推理可使用 no-thinking。思维开关细节可参考仓库 issue 4030 的讨论与 Qwen3 最佳实践 等文档。蒸馏Q22SWIFT 支持蒸馏示例见 examples/sampler/distill/distill.sh配套 distill.yaml。GKDQ23学生/教师模型可以使用不同 model_type只要词表相同即可使用 MoE 会更慢SWIFT v4 起支持师生不同并行配置示例见 examples/ray/gkd。Agentic RLQ64支持多轮/多智能体训练见 多轮训练文档相关实现位于 swift/rollout。视觉模型预训练Q62可以但需自行调整学习率详见 快速训练 VL 模型最佳实践。Megatron 自定义 lossQ63Megatron 暂不支持像 Swift 那样通过--loss_type my_loss直接挂自定义函数需修改 trainer 中的 loss_func更简洁的自定义逻辑后续会支持。Qwen3-Omni on ROCm/MI300XQ65可参考 AMD 支持最佳实践。八、GRPO 与奖励函数、Rollout8.1 GRPO 训练要点SWIFT 支持多模态 GRPO 训练GRPO 训练中出现接近 0 的 loss 属正常现象。想避免引入 KL 项时设置--beta0同时避免加载 ref model。在 LoRA SFT 之后继续 GRPO--adapters sft_ckpt --ref_adapters sft_ckpt。熵计算有额外开销默认不记录曲线需要时设置--log_entropy True注意与 Liger 的互斥关系见下文。Colocate 模式不支持--vllm_use_async_engine。GRPO 不支持 channel loss。GRPO 不能同时使用 Liger kernel 与 padding-free若必须同时使用需修改 Liger kernel 库中的 Liger GRPO loss。GRPO/PPO 实现中mini_batch仅用于梯度累积Clip 机制生效要求num_iterations 1设为 1 会失效。训练集含多种任务时参考 GRPO 多任务训练文档。更多 GRPO FAQ 见 GRPO 文档。GRPO 样本量Q61几千条即可见效越多越好。--use_liger_kernel与--log_entropy能否同用Q39不能。Liger 不实例化 logits无法获得熵。8.2 奖励函数模型--reward_model与--reward_funcs可叠加使用最终按加权求和得到总奖励权重用--reward_weights指定顺序为 reward_func1…reward_funcn、reward_model。自定义奖励函数参考 examples/train/grpo/plugin/plugin.py同目录还有 run_external_reward_func.sh 等外部奖励接入脚本。数学题数据集必须包含 solution 字段否则影响准确率计算。ORM 自定义奖励函数若需要数据集字段把该字段放在与 messages 同级即可从reward_kwargs中取到。GRPO 训练需要指定 LLM-judge 模型打分时参考 奖励模型文档 实现。8.3 Rollout 与其他偏好算法RolloutQ26不支持 Pipeline Parallel多卡推理加速请使用 Tensor Parallel。vLLM 推理引擎默认trust_remote_code为 true。GSPOQ28--importance_sampling_level sequence与--top_entropy_quantile可以同时使用顺序是先按序列级正常计算 loss受 importance_sampling_level 影响再按 top_entropy_quantile 掩码。PPOQ29PPO 训练不支持--max_grad_norm梯度爆炸需调节学习率、奖励尺度等参数当前 PPO 仅支持 RM 与 policy 同系列同 tokenizer/模板的模型否则会出现 prompt 格式与 token 切分不一致等问题当前不支持多轮 DPO可用“GRPO 多轮多轮推理 奖励函数打分”替代。九、MoE、Megatron-SWIFT、MTP 与量化训练9.1 MoE 模型训练LoRA 训练中 router 是否参与训练取决于 gate/router 的实现方式实现为nn.Linear的会参与实现为nn.Parameter的不参与LoRA 训练此时 aux-loss 基本不变。想让 router 参与训练在--target_modules中加入all-router--target_modules all-linear all-routerall-router不是通配模块名而是“把 router 纳入可训练范围”的特殊关键字。也可用--target_parameters指定具体 LoRA 替换参数见 命令行参数文档·Tuner 参数。MoE DeepSpeed ZeRO3Q54可以但速度慢。MoE 在 Megatron-SWIFT 与 SWIFT 下结果不一致Q56MoE 模型尽量使用 Megatron 跑Megatron MoE 链路相对成熟Transformers 从 5.0 版本才开始支持 MoE 训练可能尚不稳定。9.2 Megatron-SWIFT 训练要点checkpoint 保存与检索查看 Megatron-SWIFT 命令行参数文档·save_strategy。多机 pipeline 并行训练时只有最后一个 rank 持有完整输出因此日志打印在 last rank 而非 master 节点。支持--save_total_limit也支持 SwanLab 监控训练详见 Megatron-SWIFT 命令行参数文档。ViT 使用 transformers 模型结构未使用 Megatron 并行。训练 OOM 时可用--decoder_first_pipeline_num_layers减少第一个 pipeline 段的 LLM decoder 层数把更多显存留给 ViT。Megatron-SWIFT 支持新增模型暂无教程可参考新增模型的 PR 了解配置方式。Megatron-SWIFT 的序列并行不单独设置并行度等于 tensor parallel 度即通过--tensor_parallel_size设置。支持 block-wise FP8见 examples/megatron/fp8 示例。断点续训配置见上文 4.3 节不支持 QLoRA 训练。B300 显卡Q55Megatron-SWIFT 支持。9.3 MTP多 token 预测训练 MTP 需手动设置--mtp_num_layers对照 config.json 中num_nextn_predict_layers的值填入mtp_num_hidden_layers字段。基座模型若不含 MTP 结构可以从零初始化并训练 MTP。当前不支持多模态 MTP。9.4 量化模型训练QLoRA 微调参考 examples/train/qlora含 GPTQ、HQQ 及 AWQ/BNB 等目录。GPTQint 型等量化方法使参数无法参与求导不能全参微调只能挂 LoRA 等增量结构更新QLoRA 训练后的模型合并参考 QLoRA 示例。Megatron-SWIFT 不支持 QLoRA。fp16 梯度溢出Q46显卡不支持 bf16 时设置--torch_dtype float16出现ValueError: Attempting to unscale FP16 gradients.。原因是 fp16 数值范围小最大 65504全参训练易梯度溢出可尝试改用--torch_dtype fp32。9.5 其他训练细节最小学习率Q37--lr_scheduler_type cosine_with_min_lr --lr_scheduler_kwargs {min_lr: 1e-6}gradient_accumulation_fusion 报错Q40即使安装 APEX 仍报ColumnParallelLinear was called with gradient_accumulation_fusion set to True but ... fused_weight_gradient_mlp_cuda module is not found用--gradient_accumulation_fusion false关闭即可。LoRA 合并报corda_config错误Q47这是训练端与合并端 Peft 版本不匹配导致需将合并端的 Peft 升级到与训练端相同或更高的版本。AttributeError: module numpy has no attribute objectQ49尝试numpy1.26.3。训练后重复回复Q45参考 预训练与微调文档训练中即出现重复时可考虑多训几个 epoch、清洗数据、全参训练或使用 RLHF 缓解。动态数据增强Q60/Q3 模板SWIFT 目前没有现成的“每个 batch 进入模型前增强一次”的动态增强支持可按需扩展源码如修改 template 的 encode 逻辑。Qwen3.5 是否支持 CPQ52支持可参考 Qwen3 系列最佳实践。GKD 师生不同 system promptQ53支持。Qwen-VL 长样本报错Q59ValueError: Failed to retrieve the dataset. You can avoid this issue by increasing max_length or modifying the truncation_strategy。若无其他错误信息说明数据过长增大--max_length即可不 OOM 为宜。base 模型转 chat 模型Q44直接使用swift sft无其他特殊配置示例见 examples/train/base_to_chat含 lora.sh 与 full.sh。十、推理常见问题SWIFT 支持 Python 脚本、命令行与 UI 三种推理方式详见 推理与部署文档。10.1 模型与数据集配置模型设置Q1全参训练模型、LoRA 合并后模型或 Hub 下载模型设置--model model/id/or/pathLoRA 未合并模型--model指定基座路径并追加--adapters path/to/adapter。数据集与结果Q2用--val_dataset path/to/val_dataset指定数据集对训练时划分的验证集推理设置--load_data_args true。推理结果保存路径用--result_path your/path日志会打印该路径。需保留 messages 以外的额外字段时设置--remove_unused_columns false。批量推理Q3infer_backend为 transformers 时设置--max_batch_size 16该参数为每卡batch size非全局。也可参考 examples/infer/demo.py。流式推理Q4--stream true结果按行写入 JSONL 文件。注意流式推理不支持 DDP。10.2 推理后端与生成参数vLLM/SGLangQ5LoRA 模型是否需要合并参照 vLLM/SGLang 文档支持 LoRA 推理则无需先合并。SGLang 推理当前不支持多模态。生成参数Q6temperature 等参数默认从generation_config.json读取显式设置--temperature 0或--top_k 1可关闭随机性。空 systemQ7命令行未设置 system 参数但模板会追加默认 system 时显式设置--system 。从指定前缀续写Q9使用--response_prefix参数。answer 已含部分 prompt 的补全Q10SWIFT 3.0 起支持形如{messages: [{role: system, content: system}, {role: user, content: query1}, {role: assistant, content: answer1, }]}参考 examples/infer/demo_agent.py。10.3 显存控制、logprobs 与引擎一致性多模态推理限显存Q11设置--max_pixels xxx、环境变量MAX_PIXELSxxx或模型特定参数--model_kwargs {max_pixels: xxx}环境变量仅对文档中标注的模型生效详见 命令行参数文档·模型特定参数。logprobs 输出Q12命令行推理设置--logprobs truePython 脚本推理request_config RequestConfig(..., logprobsTrue, top_logprobs2)详见 tests/infer/test_logprobs.py。last_hidden_stateQ13无需额外参数可参考 GRPO trainer 的_get_last_hidden_state方法swift/rlhf_trainers/grpo_trainer.py。引擎结果不一致Q14Transformers、vLLM、Ollama 等引擎推理结果不一致时先确认推理参数一致SWIFT 模板与 Transformers 对齐但 VllmEngine 与 TransformersEngine 本身存在差异。CPU 推理Q16设置环境变量os.environ[CUDA_VISIBLE_DEVICES] -1。多机推理Q17模型能放进单节点时可用 Kubernetes 编排放不下单节点则不支持多机推理。批量采样Q18examples/train/rft/rft.py 脚本支持对数据集进行多进程采样。版本兼容Q19/Q20Qwen2-Audio 推理乱码请使用 transformers 4.48transformers 4.55.2 训练的 LoRA 在 4.52 以下版本无法加载见 issue 5440SWIFT 兼容不同版本的 qwen-vl-utils使用 qwen2.5-vl/qwen3-vl 时无需切换该依赖版本。safetensors_rust.SafetensorError: MetadataIncompleteBuffer表示模型权重已损坏。vLLM 多模态输入超长Q21报the decoder prompt contains a(n) video item with length 16758, which exceeds the pre-allocated encoder cache size 16384时可调--limit_mm_per_prompt增大编码器缓存或在 SWIFT CLI 传--vllm_engine_kwargs {max_num_batched_tokens: 20000}通过增大max_num_batched_tokens间接影响编码器缓存大小分配。Embedding/Reranker 推理Q15参考 demo_embedding.py 与 demo_reranker.py。十一、导出常见问题AutoAWQQ1推理不涉及 AWQ 量化模型却报 AutoAWQ 相关错误时尝试卸载 AutoAWQ 再推理不支持 AWQ 量化的模型可改用 GPTQ。显存不足Q2量化时模型放不下单卡尝试--device_map cpu或跨多卡加载模型、单卡量化。GPTQ int4 校准失败Q3qwen2.5 72B、默认 max model length 32768、128 条校准样本时出现factorization could not completed because the input is not positive-definite是 Hessian 矩阵非正定所致可换一份校准数据集。template_type 能否永久修改Q4不能。SWIFT 模板由框架内部定义、不使用 Jinja 保存导出不会改写。GGFU 格式Q5当前导出仅支持 ModelFile 格式GGFU 暂不支持。导出参数说明见 命令行参数文档。十二、部署常见问题模型设置Q1全参/LoRA 合并后/Hub 模型用--model model/id/or/pathLoRA 未合并模型--model指定基座并设置--adapters path/to/adapter。多卡部署Q2示例见 examples/deploy。注意 transformers 引擎不支持 DDP、不能多卡部署也不支持异构部署不同型号显卡、各卡显存占比不同。system prompt 优先级Q3数据集内默认 命令行--system 模板。客户端多模态输入Q4图片、音频等传入示例见 examples/deploy/client/mllm含 swift_client.py 与 openai_client.py图片 URL 非法时可通过环境变量SWIFT_TIMEOUT或InferClient传参设置请求超时。参数设置Q5生成参数temperature 等部署时可设默认值、并在每次客户端请求中动态覆盖引擎/部署参数TP 数、显存占比、最大长度只能在部署启动时设置运行后不可变更。流式生成Q6由客户端控制见 examples/deploy/client。token 概率输出Q7服务端先设置--logprobs true客户端传参request_config RequestConfig(..., logprobsTrue, top_logprobs2)思维模式Q8如需关闭思考当前只能在swift deploy启动时关闭详见仓库 issue 4030 的讨论。一次输出多个结果Q9在RequestConfig传nresponse client.infer([request], request_configRequestConfig( n3, # 生成 3 条 temperature0.8, # 需要随机性才能产出不同结果 )) # response 包含 3 个不同回答与 vLLM 原生部署差异Q10结果差异大可能是模板未对齐速度差异大可能是图像分辨率不一致。SWIFT 默认使用 vLLM V1 引擎可用环境变量VLLM_USE_V11控制切换。特殊模型与版本Q11缺少model.language_model.embed_tokens.weight的报错可能是训练与推理 transformers 版本不一致qwen2.5 fp16 推理返回乱码时尝试 bf16。base 模型为何要用 completionsQ12base 模型未在对话格式上训练不识别 chat 特殊 token。SWIFT 框架做了兼容处理base 模型也能使用client.chat.completions.create但本质是把 messages 拼接为纯文本做续写。十三、评测常见问题SWIFT 的评测能力基于社区评测框架 EvalScope复杂评测能力建议直接使用 EvalScope 框架。评测数据集Q1/Q2标准评测集与自定义评测集用法见 评测文档手动下载官方评测集后用本地路径离线评测参考 EvalScope 的 Quick Start。评测中途断连Q3模型评测总是在固定比例处中断而 vLLM 服务正常是客户端请求超过默认超时被断连所致设置环境变量SWIFT_TIMEOUT-1可禁用超时断连。数据量控制Q4--eval_limit控制每个子集的数据条数例如 MMLU 有 50 个子集每子集限制 10 条时总数据量为 500。生成长度Q5--max_new_tokens是推理参数而非评测参数评测生成长度由--eval_generation_config控制--eval_generation_config {max_new_tokens: 5000}OpenCompass 限制Q6/Q7/Q9OpenCompass 仅支持其预定义标准评测集不支持自定义数据集自定义请用原生 backend可视化报告目前仅原生 backend 支持。OpenCompass 离线评测下载数据集并解压把数据集文件夹data 文件夹放到当前工作目录即可被自动识别无需指定dataset-args。Ifeval 报错Q8/Q10[Errno 20] Not a directory: .../punkt_tab.zip/punkt_tab/english/collocations.tab需解压unzip /path/to/nltk_data/tokenizers/punkt_tab.zip若报cannot find or open .../punkt_tab.zip说明 nltk 依赖下载失败可手动下载 punkt_tab.zip 并解压到~/nltk_data/tokenizers。LLM-as-judgeQ11支持参数传法--extra_eval_args {judge-model-args: {api_key: xxx, api_url: http://xxx/v1, model_id: qwen-72b}}多卡显存不均Q12按NPROC_PER_NODE8 ... swift eval ... --eval_backend Native --infer_backend transformers --device_map auto方式启动报显存分配不均错误原因是swift eval 不支持 DDP 启动。查看实际输入Q13评测 query 中除问题外的额外字段最简单的查看方式是输出 reviews 文件里的 input 字段即输入模型的 Markdown 格式内容backend 为 OpenCompass 时没有这些输出需换用原生 backend。安装卡住Q14pip安装 evalscope 时卡在 “preparing metadata (pyproject.toml)” 属正常现象该过程涉及依赖求解决算可能较慢。【免费下载链接】swiftUse PEFT or Full-parameter to CPT/SFT/DPO/GRPO 600 LLMs (Qwen3.6, DeepSeek-V4, GLM-5.1, InternLM3, Llama4, ...) and 300 MLLMs (Qwen3-VL, Qwen3-Omni, InternVL3.5, Ovis2.5, GLM4.5v, Gemma4, Llava, Phi4, ...) (AAAI 2025).项目地址: https://gitcode.com/GitHub_Trending/swift1/swift创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考