ms-swift模型推送教程：一键发布到ModelScope-编程阁

ms-swift模型推送教程：一键发布到ModelScope

1. 简介与核心能力

ms-swift 是魔搭社区推出的大模型微调与部署一体化框架，专为开发者提供从训练、推理到模型发布的全链路支持。它不仅覆盖了600+纯文本大模型和300+多模态大模型的完整生命周期管理，还集成了当前最前沿的轻量化微调技术、分布式训练策略以及高效推理引擎。

在实际应用中，完成模型微调只是第一步。如何将训练好的模型快速分享给更多人使用？答案就是通过ModelScope（魔搭）平台进行模型发布。本文将手把手教你如何利用swift export命令，把你在本地训练好的 LoRA 模型一键推送到 ModelScope，实现即训即用、开放共享。

整个流程无需手动整理文件或编写上传脚本，只需几个参数配置即可完成模型导出与远程推送，真正做到了“一键发布”。

2. 推送前的准备工作

2.1 确保已完成模型微调

要推送模型，首先必须已经使用 ms-swift 完成了模型微调，并生成了对应的检查点（checkpoint）。例如，在对 Qwen2.5-7B-Instruct 进行 LoRA 微调后，你会得到类似如下路径的输出目录：

output/vx-xxx/checkpoint-xxx

该目录下包含：

adapter_model.safetensors：LoRA 权重文件
configuration.json
special_tokens_map.json
tokenizer_config.json
args.json：保存了原始训练参数（关键！用于自动恢复配置）

这些信息是后续合并与推送的基础。

2.2 获取 ModelScope 账户 Token

要在命令行中推送模型，你需要一个有效的Hub Token。获取方式如下：

登录 ModelScope 官网
点击右上角头像 → “设置” → “Access Token”
复制你的 token（形如xxxxxx的字符串）
建议将其保存在一个安全位置，避免泄露

注意：请确保你有权限创建公开或私有模型仓库。若为组织成员，请确认是否有相应操作权限。

2.3 安装并验证 ms-swift 环境

确保已正确安装支持全功能的 ms-swift 包：

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

验证是否安装成功：

swift --help

如果能看到帮助菜单，说明环境准备就绪。

3. 一键推送模型到 ModelScope

3.1 使用`swift export`实现直接推送

ms-swift 提供了统一的export命令，可用于模型导出、量化、合并及发布。其中，推送至 ModelScope 的核心命令如下：

swift export \ --adapters output/vx-xxx/checkpoint-xxx \ --push_to_hub true \ --hub_model_id 'your-username/your-model-name' \ --hub_token 'your-sdk-token' \ --use_hf false

参数详解：

参数	说明
`--adapters`	指定 LoRA 微调生成的 checkpoint 路径
`--push_to_hub`	开启模型推送功能
`--hub_model_id`	目标模型 ID，格式为`用户名/模型名`
`--hub_token`	ModelScope 的 Access Token
`--use_hf`	是否使用 Hugging Face，默认为 False（使用 ModelScope）

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

加载原始基础模型（如 Qwen/Qwen2.5-7B-Instruct）
注入 LoRA 权重
合并成完整的模型权重
构建标准模型结构（含 tokenizer、config 等）
上传至指定 ModelScope 仓库

3.2 示例：发布一个自我认知微调模型

假设我们完成了对 Qwen2.5-7B-Instruct 的自我认知微调，checkpoint 位于output/v1-20240830-151000/checkpoint-873，现在想发布为名为my-qwen-swift-bot的公开模型。

完整命令如下：

swift export \ --adapters output/v1-20240830-151000/checkpoint-873 \ --push_to_hub true \ --hub_model_id 'zhangsan/my-qwen-swift-bot' \ --hub_token 'efghijabcd123456' \ --use_hf false

运行日志示例：

[INFO:swift] Start time of running main: 2024-09-01 10:00:00 [INFO:swift] Loading base model: Qwen/Qwen2.5-7B-Instruct [INFO:swift] Merging LoRA weights... [INFO:swift] Saving merged model to temporary directory... [INFO:swift] Uploading to ModelScope: zhangsan/my-qwen-swift-bot [INFO:swift] Upload completed successfully! [INFO:swift] Model available at: https://modelscope.cn/models/zhangsan/my-qwen-swift-bot

几分钟后，你的模型就会出现在 ModelScope 上，任何人都可以查看、下载或在线体验！

4. 高级选项与实用技巧

4.1 自定义模型名称与作者信息

如果你希望在模型页面显示自定义的模型名和作者名，可以在训练时加入以下参数：

--model_name "SwiftBot" \ --model_author "Zhang San"

这些信息会在推送时写入README.md和模型元数据中，提升可读性和专业性。

4.2 推送前自动合并 LoRA 权重

默认情况下，swift export会在推送前自动合并 LoRA 权重到基础模型中，生成一个独立可用的完整模型。你可以通过以下参数控制行为：

--merge_lora true \ # 是否合并 LoRA --merge_device_map 'auto' # 合并时使用的设备策略

合并后的模型可以直接被transformers加载，无需依赖 ms-swift 框架，极大提升了通用性。

4.3 设置私有模型仓库

默认推送为公开模型。如需设为私有，添加参数：

--hub_private_repo true

这样只有你授权的用户才能访问该模型。

4.4 推送量化模型（AWQ/GPTQ）

ms-swift 支持将量化后的模型直接推送。例如，先对模型进行 AWQ 量化：

swift export \ --model Qwen/Qwen2.5-7B-Instruct \ --quant_bits 4 \ --quant_method awq \ --dataset AI-ModelScope/alpaca-gpt4-data-zh#500 \ --output_dir qwen2-7b-instruct-awq

然后推送量化模型：

swift export \ --adapters output/v1-20240830-151000/checkpoint-873 \ --push_to_hub true \ --hub_model_id 'zhangsan/qwen2-7b-instruct-awq-finetuned' \ --hub_token 'your-token' \ --quant_bits 4 \ --quant_method awq

适用于需要低资源部署的场景。

5. 常见问题与解决方案

5.1 推送失败：网络超时或连接错误

原因：国内访问国外节点慢，或未配置镜像源。

解决方法：

使用清华源加速 pip 安装
在服务器端配置代理（如有）
尝试更换时间段重试

5.2 报错：`Invalid token`或`Permission denied`

原因：Token 错误或无权创建该模型 ID。

解决方法：

重新复制正确的 Token
确认用户名拼写无误
若为组织模型，使用org-name/model-name格式并确保有权限

5.3 如何更新已有模型？

只需再次运行相同的swift export命令，系统会自动覆盖原版本（除非设置了版本锁定），并在 ModelScope 上更新最新文件。

建议配合--commit_message添加更新说明：

--commit_message "update: improved response accuracy after retraining"

5.4 推送完成后在哪里查看？

访问以下链接即可查看你的模型：

https://modelscope.cn/models/<your-username>/<your-model-name>

页面将展示：

模型卡片（名称、描述、标签）
文件列表
在线 Demo（支持 Web UI 体验）
下载量、点赞数等统计信息

6. 总结

通过本文的学习，你应该已经掌握了如何使用 ms-swift 框架将本地微调后的模型一键发布到 ModelScope 平台。整个过程简洁高效，仅需一条命令即可完成从权重合并到云端发布的全部操作。

关键要点回顾：

✅ 使用swift export命令实现模型导出与推送
✅ 必须提供有效的hub_token和hub_model_id
✅ 支持 LoRA 合并、量化模型推送、私有仓库设置
✅ 发布后的模型可在 ModelScope 上被他人直接调用或部署

这不仅是个人项目成果的展示窗口，更是参与开源生态、贡献 AI 社区的重要一步。无论是打造专属聊天机器人、行业垂类助手，还是参与模型竞赛，一键发布功能都能让你的模型迅速触达更广泛的用户群体。

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

ms-swift模型推送教程：一键发布到ModelScope