ms-swift模型导出指南：将微调结果发布到ModelScope

ms-swift模型导出指南：将微调结果发布到ModelScope

1. 引言

在完成大模型的微调后，如何将训练成果高效地分享和部署是每个开发者关心的问题。ms-swift作为魔搭社区推出的一站式轻量级微调框架，不仅支持600+纯文本大模型与300+多模态大模型的训练、推理、评测与量化，还提供了便捷的模型导出功能，能够一键将LoRA等轻量微调权重发布至ModelScope平台。

本文将详细介绍如何使用swift export命令，将你在本地训练好的微调结果（如LoRA适配器）打包并推送到ModelScope，实现模型成果的共享与复用。无论你是通过命令行还是Web-UI完成训练，都可以轻松完成这一步骤。

你将学会：

• 如何准备模型导出所需的参数
• 如何获取并配置ModelScope的访问令牌
• 如何执行模型推送命令
• 推送后的模型如何被他人加载和使用

整个过程无需手动整理文件结构或编写复杂脚本，只需一条命令即可完成。

2. 准备工作

在执行模型导出前，需要确保以下几项准备工作已完成：

2.1 确认已完成微调任务

确保你已经成功运行了微调任务，并生成了包含适配器权重的检查点目录。例如，在使用如下命令进行LoRA微调后：

swift sft \ --model Qwen/Qwen2.5-7B-Instruct \ --train_type lora \ --dataset 'AI-ModelScope/alpaca-gpt4-data-zh#500' \ --output_dir output

系统会在指定的output目录下生成类似checkpoint-xxx的文件夹，其中包含了训练得到的LoRA权重（adapter_model.bin）、配置文件（adapter_config.json）以及训练参数记录（args.json）。

你可以通过查看输出目录确认是否存在这些关键文件：

ls output/checkpoint-50/ # adapter_config.json adapter_model.bin args.json training_args.json

2.2 安装最新版ms-swift

为确保导出功能正常工作，请升级到最新版本的ms-swift：

pip install 'ms-swift[all]' -U -i https://pypi.tuna.tsinghua.edu.cn/simple

如果你是从源码安装的，请拉取最新代码并重新安装：

git clone https://github.com/modelscope/ms-swift.git cd ms-swift pip install -e '.[llm]'

2.3 获取ModelScope SDK Token

要将模型推送到ModelScope，你需要一个有效的访问令牌（Token）。请按以下步骤获取：

1. 访问 ModelScope官网
2. 登录你的账号
3. 点击右上角头像 → “个人设置” → “API Tokens”
4. 生成一个新的Token（建议命名为swift-export以便管理）
5. 复制该Token并妥善保存

这个Token将在后续的导出命令中用于身份验证。

2.4 创建目标模型ID（可选）

虽然可以在导出时直接指定模型ID，但建议提前在ModelScope上创建一个空模型空间。操作步骤如下：

1. 进入 ModelScope模型发布页面
2. 点击“发布模型”
3. 填写模型名称（如my-qwen2-lora）、描述、标签等信息
4. 选择“未上传模型文件”，完成创建

这样你就拥有了一个可以推送的目标地址，格式为：用户名/模型名，例如your-name/my-qwen2-lora

3. 执行模型导出与推送

ms-swift提供了一个统一的swift export命令来处理模型导出和上传任务。以下是完整的导出流程。

3.1 基本导出命令结构

swift export \ --adapters <checkpoint_path> \ --push_to_hub true \ --hub_model_id <your-model-id> \ --hub_token <your-sdk-token>

各参数说明如下：

3.2 实际导出示例

假设你的微调结果位于output/vx-123/checkpoint-100，你想将其推送到名为my-lora-finetune的模型空间中，完整命令如下：

swift export \ --adapters output/vx-123/checkpoint-100 \ --push_to_hub true \ --hub_model_id yourname/my-lora-finetune \ --hub_token "xxxxxxxxxxxxxxxxxxxxxx"

执行后，系统会自动完成以下动作：

1. 读取args.json中的原始模型信息（如Qwen/Qwen2.5-7B-Instruct）
2. 构建包含LoRA权重和配置的模型包
3. 使用提供的Token登录ModelScope
4. 将模型文件上传至指定ID对应的空间
5. 自动生成README文档，包含训练参数摘要

3.3 导出过程日志解读

成功执行后，你会看到类似以下的日志输出：

[INFO:swift] Pushing model to hub: yourname/my-lora-finetune [INFO:swift] Uploading file: adapter_config.json [INFO:swift] Uploading file: adapter_model.bin [INFO:swift] Uploading file: README.md [INFO:swift] Model successfully pushed to https://modelscope.cn/models/yourname/my-lora-finetune

这意味着你的模型已成功上线！

3.4 高级导出选项

除了基本参数外，swift export还支持多个可选参数以满足不同需求：

自定义模型元数据

--model_author "swift-user" \ --model_name "custom-lora-model"

用于自定义模型作者和名称，便于在推理时识别。

指定是否合并LoRA权重

--merge_lora false

默认不合并LoRA权重，保持增量更新形式。若设为true，则会尝试合并为主模型。

使用Hugging Face Hub

--use_hf true

如果你想同时推送到Hugging Face而非ModelScope，启用此选项即可。

添加版本标签

--revision "v1.0"

为本次推送添加Git风格的版本号，便于后续迭代管理。

4. 验证与使用导出的模型

一旦模型成功推送，任何人都可以通过标准方式加载和使用它。

4.1 在ModelScope页面查看模型

访问https://modelscope.cn/models/你的用户名/模型名即可查看你发布的模型页面。页面将自动展示以下内容：

• 模型卡片（README）
• 训练参数摘要
• 文件列表（含adapter_model.bin）
• 下载量与收藏数统计
• 在线体验Demo（如果配置了Web UI）

4.2 使用命令行加载微调模型

其他用户可通过以下命令直接加载你发布的LoRA模型进行推理：

swift infer \ --model Qwen/Qwen2.5-7B-Instruct \ --adapters yourname/my-lora-finetune \ --stream true \ --max_new_tokens 2048

注意：--model仍需指定基础模型，--adapters指向你发布的LoRA模型。

4.3 使用Python API调用

开发者也可以在代码中加载该模型：

from swift import PtEngine engine = PtEngine( model_id_or_path="Qwen/Qwen2.5-7B-Instruct", adapters=["yourname/my-lora-finetune"] ) resp_list = engine.infer([ {"role": "user", "content": "介绍一下你自己"} ], max_tokens=512) print(resp_list[0].choices[0].message.content)

4.4 合并LoRA权重（可选）

如果你希望生成一个独立的、无需依赖基础模型的完整模型，可以先合并LoRA权重再导出：

swift export \ --adapters output/vx-123/checkpoint-100 \ --merge_lora true \ --output_dir merged_model \ --push_to_hub true \ --hub_model_id yourname/qwen2-full-merged \ --hub_token "xxxx"

此时导出的是一个完整的模型目录，可直接通过--model加载而无需额外指定--adapters。

5. 常见问题与解决方案

5.1 推送失败：认证错误

现象：

HTTPError: 401 Client Error: Unauthorized for url...

原因：Token无效或过期。

解决方法：

• 重新生成新的SDK Token
• 确保复制时没有多余空格
• 检查是否拼写错误

5.2 推送失败：模型ID不存在

现象：

Model not found: yourname/nonexistent-model

解决方法：

• 确保已在ModelScope上创建了同名模型
• 或去掉--hub_model_id让系统自动创建（需有权限）

5.3 导出时找不到适配器文件

现象：

FileNotFoundError: No such file or directory: 'output/checkpoint-100/adapter_config.json'

原因：检查点路径错误或训练未生成LoRA文件。

解决方法：

• 检查--output_dir输出目录
• 确认--train_type lora已正确设置
• 查看训练日志是否报错

5.4 模型上传后无法加载

可能原因：

• 基础模型名称变更导致不匹配
• LoRA target modules与原模型不兼容

建议做法：

• 在README中注明所基于的基础模型版本
• 提供测试样例帮助使用者验证效果

6. 总结

通过本文介绍，你应该已经掌握了如何使用ms-swift框架将微调结果一键发布到ModelScope的完整流程。我们回顾一下关键步骤：

1. 完成微调：使用swift sft训练并生成LoRA检查点
2. 准备环境：安装最新版ms-swift并获取ModelScope Token
3. 执行导出：使用swift export命令推送模型
4. 验证使用：在线查看或通过API加载新模型

ms-swift的设计理念是“开箱即用”，从训练到部署全程自动化。你不再需要手动处理模型格式转换、文件组织或接口封装，所有繁琐细节都被封装在一条简洁命令背后。

更重要的是，当你把模型分享出去时，也促进了AI社区的知识流动和技术进步。无论是教学示范、项目复现还是工业应用，一个公开可用的微调模型都具有极高的价值。

现在就动手试试吧，把你训练出的专属模型发布出去，让更多人受益于你的工作成果！

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。