maind 0.1.0

Mai CLI (Python) for local Git/DVC, model, dataset, and image workflows

Mai CLI

mai 是 Mai 平台的命令行工具，用于在本地完成模型、数据集、文件和镜像的下载、上传、提交、推送。

常用命令：

mai login
mai download --model <modelName> --version main
mai repo add
mai repo commit -m "update model"
mai repo push

安装和运行

方式一：pip 安装

适合已经有 Python 3.12+ 的环境。

pip install mai-cli
mai --help

也可以用 pipx 隔离安装：

pipx install mai-cli
mai --help

方式二：源码运行

适合本地调试或暂未发布到 pip 源时使用。

git clone <mai-cli-repo>
cd mai-cli
uv sync
uv run mai --help

方式三：Docker 直接运行

适合不想在宿主机安装 Python、Git、DVC、ModelScope、Hugging Face CLI 等依赖的环境。

docker run --rm -it \
  -v "$PWD":/workspace \
  -v "$HOME/.config/mai":/root/.config/mai \
  -w /workspace \
  harbor.mindreon.com/baize/mai-cli:release-v0.1.0 \
  bash

进入容器后直接使用：

mai --help
mai login

镜像内已包含：

• mai
• git
• git-lfs
• dvc[s3]
• modelscope
• hf / huggingface-cli
• skopeo

登录

交互式登录：

mai login

非交互式登录：

mai login --url https://your-domain --username <USERNAME> --password <PASSWORD>

项目状态和切换

查看当前登录用户、租户、当前项目和可用项目数量：

mai status

查看可切换项目：

mai project list

切换当前项目：

mai project use <项目名或项目ID>

切换项目后，后续 create、download、connect、repo push 等命令都会使用新的项目上下文。

使用

下载模型或数据集

一条命令完成“创建目录、连接平台仓库、拉取远端内容”：

mai download --model "Qwen2.5-7B-Instruct" --version main

mai download --dataset "my-dataset" --version main

指定下载目录：

mai download --model "Qwen2.5-7B-Instruct" --version main --dir ./workspace/qwen

初始化上传工作区

download 适合拉取平台上已有内容。connect 适合创建新模型或数据集后，只初始化一个本地工作区，然后把本地文件放进去再推送。

如果目标目录来自魔搭社区或 Hugging Face 等第三方仓库，并且目录里已经带有自己的 .git，connect 会先移除这些外部 Git 元数据，再初始化 Mai 工作区自己的 .git。

mai create --model "my-model" --description "demo model"
mai connect --model "my-model" --version main
cd ./my-model

数据集同理：

mai create --dataset "my-dataset" --description "demo dataset"
mai connect --dataset "my-dataset" --version main
cd ./my-dataset

上传和推送修改

在 Mai 工作区内修改文件后：

mai repo status
mai repo add
mai repo commit -m "update model files"
mai repo push

repo add 会自动处理大文件：

• 小文件进入 Git
• 默认超过 5 MiB 的文件进入 DVC
• 如果未跟踪文件数量超过 1000，会优先按顶层目录进入 DVC
• 生成的 .dvc 文件需要一起提交，不要删除

调整大文件阈值：

mai repo add --threshold 1
mai repo add --count-threshold 5000

准备好本地目录后直接发布

如果模型或数据集文件已经在本地目录中，可以用 publish 一次完成连接、添加、提交和推送：

mai publish --dir ./local-model --model "my-model" --version main -m "publish model"

mai publish --dir ./local-dataset --dataset "my-dataset" --version main -m "publish dataset"

从 Hugging Face 或 ModelScope 同步

从 Hugging Face 同步模型到平台：

mai sync --model hf://Qwen/Qwen2.5-7B --name "qwen2.5-7b" --version main

从 ModelScope 同步数据集到平台：

mai sync --dataset ms://org/my-dataset --name "my-dataset" --version main

文件和镜像

上传文件：

mai file upload ./data.csv --scope personal

构建平台镜像：

mai image build --repo my-image --tag latest --method dockerfile --dockerfile-url https://example.com/Dockerfile

复制镜像：

mai image copy source:tag target:tag

预置资源

seed 用于按 YAML 配置批量准备和上传平台预置资源，例如模型、数据集、镜像、运行时配置和参数模板。

mai seed apply --config ./configs/config.yaml

只下载和准备本地资源：

mai seed prepare --config ./configs/config.yaml

只上传已经准备好的资源：

mai seed upload --config ./configs/config.yaml

完整示例

示例一：下载平台模型，修改后推送

mai login
mai download --model "Qwen2.5-7B-Instruct" --version main
cd ./Qwen2.5-7B-Instruct

echo "hello" > note.txt

mai repo add
mai repo commit -m "update note"
mai repo push

示例二：发布本地模型目录

先在 Mai 平台创建模型，或者用 CLI 创建：

mai login
mai create --model "local-qwen" --description "local model"

发布本地目录：

mai publish --dir ./local-qwen --model "local-qwen" --version main -m "publish local-qwen"

示例三：从 Hugging Face 同步模型

mai login
mai sync --model hf://Qwen/Qwen2.5-7B --name "qwen2.5-7b" --version main

常用环境变量

变量	说明
MAI_API_URL	平台地址
MAI_AUTH_TOKEN	登录 token，优先级高于本地配置文件
MAI_CONFIG_DIR	配置文件目录，默认 ~/.config/mai
MAI_MODELS	批量下载模型列表
MAI_DATASETS	批量下载数据集列表
MAI_WORKLOADS	批量下载工作负载列表
MAI_ROOT_DIR	批量下载根目录
MAI_SEED_RESOURCES_DIR	seed 资源目录
MAI_SEED_DIRS	seed YAML 目录，支持逗号或冒号分隔

Python SDK

如果需要在 Python 代码中调用平台能力，可以使用 MaiClient：

from mai import MaiClient

client = MaiClient.from_config_file()
client.create_model("my-model")
client.publish("./workspace", bind_type="model", bind_name="my-model")