Mai CLI

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

如果需要完整命令说明，请查看 README.full.md。

快速开始

1. 安装

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

pip install maind
mai --help

如果在 Windows 上看到 mai.exe is installed ... which is not on PATH，或者运行 mai 提示“不是内部或外部命令”，可以先用不依赖 PATH 的方式运行：

python -m mai --help
python -m mai install

也可以把 Python 用户脚本目录加入 PATH，然后重新打开终端：

$scripts = python -c "import sysconfig; print(sysconfig.get_path('scripts'))"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$scripts", "User")

如果没有 Python，可以使用 Windows 安装包（自带嵌入式 Python，无需单独安装）：

1. 下载安装向导（.exe）或便携包（.zip），或参考 packaging/windows/README.md 本地构建
2. 安装或解压到例如 C:\Tools\mai-cli
3. 重新打开终端后运行：

mai --help
mai login --url https://your-platform --username USER --password PASS

便携包用户可在解压目录直接运行 .\mai.exe --help 或 .\mai.cmd --help。

download、connect、repo push 等工作区命令不依赖系统 git.exe。少数历史工作区 含有 Git LFS 指针时，下载命令会明确提示安装 Git for Windows。可用下列命令检查可选依赖：

mai install --check
mai install

也可以用 pipx 隔离安装：

pipx install maind
mai --help

2. 登录

交互式登录：

mai login

非交互式登录：

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

3. 下载模型或数据集

下载模型：

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

平台内部任务也可以按文件版本集 ID 下载：

mai download --fvs "<FVS_ID>" --version main --dir ./workspace/source

常用操作

创建并上传模型

创建模型并初始化本地工作区：

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

把文件放入目录后提交并推送：

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

mai repo status 是统一的工作区状态命令：同时显示 Git 元数据状态和 DVC 数据状态， 不依赖系统 git.exe。

创建并上传数据集

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

把文件放入目录后提交并推送：

mai repo add
mai repo commit -m "update dataset files"
mai repo push

发布已有本地目录

如果模型或数据集文件已经在本地目录中，可以用 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_FILE_CENTER_URL 指向内部 file-service。外部调用未配置该变量时，会使用平台 MAI_API_URL 并自动添加 /file-center 前缀；内部 baize-frontend 地址不会作为文件上传回退地址。

构建平台镜像：

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

复制镜像：

mai image copy source:tag target:tag

预置资源示例

仓库内置了与 falsework 平台预置资源一致的 seed 示例，可直接 dry-run 验证：

镜像 seed 会结合镜像是否存在和最近一次构建任务状态进行幂等处理。最近任务为 failed 或 cancelled 时会重新创建构建任务；任务仍在进行或镜像已经存在时会跳过。

mai seed apply --config examples/seed/config.yaml --resources-dir /tmp/mai-seed-resources --dry-run

Docker 环境

如果不想在宿主机安装 Python、Git、DVC、ModelScope、Hugging Face CLI 等依赖，可以直接使用 Docker 镜像。

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

Windows 安装包构建（开发者）

原生 Windows x64 上，安装 GNU Make、uv、Inno Setup 6 与 MinGW-w64 或 MSVC Build Tools 后，在 仓库根目录执行：

# 安装 Inno Setup 6（只需执行一次）
winget install --id JRSoftware.InnoSetup --exact --source winget

若没有 winget，可从 Inno Setup 官方下载页 安装。准备完成后执行：

make windows-package

这会同时生成便携包、mai.exe 和安装器。指定包名版本时推荐传入小写 version，同时兼容大写 VERSION；release- 前缀会被自动移除：

make windows-package version=release-v0.1.0
# 生成 mai-cli-v0.1.0-win-amd64.zip 和 mai-cli-v0.1.0-setup-win-amd64.exe

兼容写法：make windows-package VERSION=release-v0.1.0。如果同时传入，以小写 version 为准。

产物位于 dist/：

• mai-cli-<version>-win-amd64.zip（便携包）
• mai-cli-<version>-setup-win-amd64.exe（安装向导）

进阶：项目状态和切换

熟悉基础命令后，如果账号下有多个项目，可以查看当前项目状态：

mai status

查看可切换项目：

mai project list

切换当前项目：

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

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

常用环境变量