魔塔社区大模型上传完整指南：两种方法详解

本文将详细介绍两种将大模型上传至魔塔社区的方法，帮助开发者快速完成模型部署。

方法一：使用 ModelScope Python SDK 上传

1.前期准备：获取访问令牌

• 登录魔塔社区，进入「个人中心」→「访问令牌」
• 点击「新建 SDK/API 令牌」，生成新的访问令牌
• 妥善保存令牌字符串，后续步骤需要使用

2.环境配置与安装

在开始上传前，请确保已安装 ModelScope 库：

# 检查是否已安装 ModelScope
pip show modelscope

如果未安装，执行以下命令：

# 安装 ModelScope 库
pip install modelscope

3.核心上传代码

创建 Python 脚本文件，使用以下代码完成上传：

from modelscope.hub.api import HubApi
from modelscope.hub.constants import ModelVisibility
import os

# 配置信息 - 请替换为实际值
YOUR_ACCESS_TOKEN = "你的SDK访问令牌"  # 从魔塔社区获取
username = "你的用户名"
model_name = "你的模型名称"
model_path = "/本地/模型/完整路径"  # 本地模型文件夹绝对路径

# 初始化 API 并登录
api = HubApi()
api.login(YOUR_ACCESS_TOKEN)

# 构建仓库ID
repo_id = f"{username}/{model_name}"

# 检查并创建模型仓库
try:
    api.get_model(repo_id)
    print(f"模型仓库已存在: {repo_id}")
except Exception:
    print(f"创建新模型仓库: {repo_id}")
    api.create_model(
        model_id=repo_id,
        visibility=ModelVisibility.PUBLIC,  # 或 ModelVisibility.PRIVATE
        license='Apache-2.0'
    )

# 上传模型文件
print("开始上传模型文件...")
api.upload_folder(
    repo_id=repo_id,
    folder_path=model_path,
    commit_message="首次上传模型文件"
)
print("模型上传完成！")

4.关键参数说明

create_model 函数参数：

• model_id (必填): 格式为"用户名/模型名"
• visibility: 可见性设置，PUBLIC(公开) 或 PRIVATE(私有)
• license: 开源许可证，默认 Apache-2.0

upload_folder 函数参数：

• folder_path: 本地模型文件夹的绝对路径
• path_in_repo: 可选，指定在仓库中的存储路径
• commit_message: 提交信息，描述此次上传内容

适用场景：推荐用于几十MB到几百MB的中等规模模型上传。

方法二：使用 Git 和 Git LFS 上传

1.环境准备：安装 Git LFS

# Ubuntu/Debian 系统
curl -s https://packagecloud.io/install/repositories/github/git-lfs/script.deb.sh | sudo bash
sudo apt-get install git-lfs

# 初始化 Git LFS
git lfs install

2.配置用户信息

# 设置全局用户信息（如未配置过）
git config --global user.name "你的用户名"
git config --global user.email "你的邮箱@example.com"

3.获取 Git 访问令牌

• 登录魔塔社区，进入「访问令牌」页面
• 创建「Git 访问令牌」，保存令牌字符串

4.克隆仓库并准备文件

# 克隆空仓库（替换实际信息）
git clone https://oauth2:你的GIT令牌@www.modelscope.cn/用户名/模型名.git

# 进入仓库目录
cd 模型名

# 复制模型文件到当前目录
cp -r /本地/模型/路径/* .

# 创建.gitignore文件排除不必要文件
cat > .gitignore << EOF
*.log
__pycache__/
*.tmp
EOF

5.配置 Git LFS 跟踪大文件

# 跟踪常见的大模型文件类型
git lfs track "*.bin"
git lfs track "*.pt"
git lfs track "*.ckpt"
git lfs track "*.safetensors"
git lfs track "*.pth"

# 提交 LFS 配置
git add .gitattributes

6.提交并推送代码

# 添加所有文件
git add .

# 提交更改
git commit -m "首次提交大模型文件"

# 推送到远程仓库
git push -u origin master

三、方法对比与选择建议

1.Python SDK 方法优势：

• 操作简单，适合不熟悉 Git 的用户
• 代码控制灵活，易于集成到自动化流程
• 适合中小规模模型文件

2.Git LFS 方法优势：

• 适合超大模型文件（GB级别）
• 版本控制完善，便于协作开发
• 上传稳定性更好，支持断点续传

四、常见问题排查

权限错误：检查访问令牌是否有效且有足够权限

网络超时：尝试使用国内镜像或调整超时设置

文件大小限制：超大文件务必使用 Git LFS 方法

仓库不存在：确保先在魔塔社区创建对应的模型仓库

按照以上步骤，您可以顺利完成大模型的上传工作。建议首次上传时选择非高峰时段，并确保网络连接稳定。