MiMouseDeploy

MiMouse 私有化部署资源仓库。本仓库集中存放私有化部署所需的全部资源,包括模型文件、源代码、容器镜像以及各类安装包,便于在内网或离线环境中快速完成部署。

一、介绍

• 该仓库存储咪鼠私有化部署所需的全部交付物:模型、代码、镜像、安装包;
• 上传到 modelscope,方便在各类 GPU 租赁平台 / 内网离线环境拉取,同时作为备份;
• 统一目录管理,保证部署环境一致、可复现、可离线获取。

二、目录结构

大文件(模型 / 镜像 / 安装包)由 .gitattributes 自动用 Git LFS 跟踪(已覆盖 .safetensors、.bin、.tar、.zip、.gz 等常见格式)。

⚠️ 密钥安全提示:下方命令中的 <你的访问令牌> 请替换为你自己的令牌(ModelScope 个人中心 → 访问令牌)。请勿把真实令牌写进公开仓库的 README 或代码里,以免泄露。

三、资源下载

1、使用 git 和 git-lfs

此方法会拉取 .git 目录,该目录几乎和原始文件一样大,空间紧张时不推荐。

前提:已安装 git 和 git-lfs:

# debian 系
apt update -y && apt install git git-lfs -y

拉取(公开仓库可直接 clone;私有仓库在 URL 中带令牌):

export GIT_LFS_SKIP_SMUDGE=0   # 不跳过 LFS 文件
# 公开:
git clone https://www.modelscope.cn/MiMouse/MiMouseDeploy.git
# 私有(带令牌):
git clone https://oauth2:<你的访问令牌>@www.modelscope.cn/MiMouse/MiMouseDeploy.git

2、使用 modelscope SDK(推荐)

# 1、安装 modelscope SDK
pip install modelscope

# 2、登录(私有仓库需要)
modelscope login --token <你的访问令牌>

# 3、下载到当前目录(不加 --local_dir 会下载到 ~/.cache/modelscope)
modelscope download --model MiMouse/MiMouseDeploy --local_dir .

# 4、只下载某个文件
modelscope download --model MiMouse/MiMouseDeploy README.md --local_dir .

# 5、只下载某个子目录(例如某个模型)
modelscope download --model "MiMouse/MiMouseDeploy" --include '模型/bge-m3/*' --local_dir .

更多用法参考:模型的下载 · 文档中心

3、使用 git + git-lfs 单独下载(推荐,按需拉取大文件)

SDK 下载大部分情况可用,但部分文件可能出现 revision 相关报错:

2025-03-28 09:11:52,604 - modelscope - WARNING - Model revision not specified, use revision: v1.0

此时可用 git + git-lfs 综合下载,只拉取需要的子目录:

# 1、先设置不拉取 lfs 文件
export GIT_LFS_SKIP_SMUDGE=1

# 2、拉取整个项目(仅指针,不含大文件)
git clone https://oauth2:<你的访问令牌>@www.modelscope.cn/MiMouse/MiMouseDeploy.git

# 3、进入项目目录
cd MiMouseDeploy

# 4、按需拉取指定目录的 lfs 文件
git lfs pull --include="模型/RMBG-2.0/*"

# 5、移动到部署目录
mv ./模型/RMBG-2.0/ /mimouse/models/

四、资源上传

1、使用 git(推荐)

# 1、先设置不拉取 lfs 文件
export GIT_LFS_SKIP_SMUDGE=1

# 2、拉取项目
git clone https://oauth2:<你的访问令牌>@www.modelscope.cn/MiMouse/MiMouseDeploy.git
cd MiMouseDeploy

# 3、将文件放入对应目录(模型/代码/镜像/安装包)
cp -r ../模型名称 ./模型/

# 4、添加并提交
git add -A
git commit -m "添加 XX 模型"

# 5、推送 lfs 文件
git lfs push origin master

# 6、推送整个项目
git push

2、使用 modelscope SDK

底层同样基于 git + git-lfs,要求本地目录包含 configuration.json。

from modelscope.hub.api import HubApi

YOUR_ACCESS_TOKEN = '<你的访问令牌>'  # ModelScope 个人中心 -> 访问令牌

api = HubApi()
api.login(YOUR_ACCESS_TOKEN)
api.push_model(
    model_id="MiMouse/MiMouseDeploy",
    model_dir="my_model_dir"   # 本地目录,要求包含 configuration.json
)

3、分步上传(大文件 / 硬盘空间不足时)

• ModelScope 实例硬盘约 100G;
• 执行 git add 后,.git/lfs 下会产生约等于文件大小的缓存;
• 当文件超过 50G 时,加上 lfs 缓存可能超出 100G 导致空间不足;
• 解决办法:分步提交,上传一部分后删除 lfs 缓存,再上传下一部分;
• 该方法适用于单文件小于可用硬盘一半的情况;若单文件本身超过一半,需更大硬盘或将文件分片。

# 1、先设置不拉取 lfs 文件
export GIT_LFS_SKIP_SMUDGE=1

# 2、拉取项目
git clone https://oauth2:<你的访问令牌>@www.modelscope.cn/MiMouse/MiMouseDeploy.git
cd MiMouseDeploy

# 3、将文件放入对应目录
mv ../模型名称 ./模型/

# 4、添加并提交部分文件
git add ./模型/模型名称/文件或文件夹1/
git commit -m "添加 XX 模型的第一部分"

# 5、推送 lfs 文件
git lfs push origin master

# 6、推送提交
git push

# 7、删除 lfs 缓存
git rm -rf ./.git/lfs/*

# 8、提交其他部分
# 重复 4~7 步,直到所有文件提交完成;空间足够时可一次提交多个文件

五、部署流程(示例)

1. 从 安装包 安装运行环境与依赖;
2. 从 镜像 加载容器镜像:docker load -i 镜像/xxx.tar;
3. 从 模型 获取模型文件并放置到指定路径;
4. 参照 代码 中的脚本与配置启动服务。