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 用户可以按安全策略选择以下任一发行方式：

1. 安装包（.exe）：使用向导安装，可选加入用户 PATH
2. 单文件 EXE（*-standalone-win-amd64.exe）：只下载一个文件，直接运行
3. Portable 便携包（.zip）：解压后运行，不执行安装，不写入系统

这些发行方式都自带嵌入式 Python，无需单独安装。Portable 包或单文件 EXE 可用于禁止安装包的环境。 详情和本地构建方式见 packaging/windows/README.md。

安装包安装或 Portable 包解压到例如 C:\Tools\mai-cli 后，重新打开终端并运行：

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>

HTTPS 地址支持 IP 和域名。CERTIFICATE_VERIFY_FAILED 表示证书校验失败：可能是私有 CA 未被信任、服务器证书链不完整，或证书未包含所访问的域名/IP；使用 IP 时，证书需要对应的 IP SAN。

在交互终端登录时，CLI 会说明证书错误，并询问是否信任服务器、关闭校验后重试，默认选择否。 确认后只重试一次，登录成功才保存设置；非交互执行会直接返回错误和处理方法。

对于确认可信的私有部署，也可显式关闭证书校验：

mai login --url https://MASTER_IP --username <USERNAME> --password <PASSWORD> --insecure

该设置会保存到本地配置，后续命令继续生效。也可以通过 MAI_TLS_VERIFY=false 全局关闭；仅建议在确认网络可信时使用。

有部署方提供的 CA 证书时，可保持校验并指定 CA 文件（证书仍须匹配访问的域名/IP）：

MAI_TLS_VERIFY=true SSL_CERT_FILE=/path/to/ca.pem mai login --url https://MASTER_IP

如果错误是 UNEXPECTED_EOF_WHILE_READING，表示 TLS 握手被提前中断，--insecure 无法解决。 此时应检查 HTTPS 地址/端口及代理、VPN 路由；内网 IP 可加入 NO_PROXY 以绕过环境变量代理， 但系统代理的 TUN 模式仍需单独配置直连规则。CLI 会显示对应提示，不再打印网络异常堆栈。

3. 下载模型或数据集

下载模型：

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

下载数据集：

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

数据集名称会与当前登录 Token 中的项目身份一起提交给 Datacube 解析，随后使用解析出的 dataset/version/repo ID 获取信息和下载，不需要也不接受客户端传入 project_id。SDK 可直接查询：

from mai import MaiClient

client = MaiClient.from_config_file()
info = client.get_dataset("my-dataset", "main")
print(info.resolution.dataset_id, info.resolution.version_id)
print(info.dataset, info.version)

指定下载目录：

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 --jobs 8 --s3-jobs 16

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 一次完成连接、添加、提交和推送。

跨平台迁移（例如从 4.28 下载后发布到 4.13）时，需要保留实际模型或数据集文件。 download 会保留 *.dvc 指针和 .gitignore，方便继续管理工作区；repo add / publish 会识别被 Git 忽略的已有 DVC 实体，重新建立缓存并上传到当前连接的远端，不依赖源环境缓存。 重新连接会更新 .dvc/config.local 中的远端选择和地址，避免旧环境配置覆盖当前环境。 如果指定 MAI_DVC_CACHE_DIR 或 MAI_DVC_CACHE_TYPE，这些值也会覆盖旧的本地配置。 数据在缓存和目标远端均缺失时，推送会报错并停止 Git 推送；应恢复实体后执行 mai repo add 再重试。

发布模型目录：

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

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

make windows-package version=release-v0.1.0
# 生成便携包、单文件 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-cli-<version>-standalone-win-amd64.exe（单文件 EXE）

发布到平台下载服务时，在同一台 Windows 机器上传 Nexus，再提交 catalog 触发 Linux Woodpecker 构建 baize-static-files 镜像（详见 packaging/static-files/README.md）：

make windows-upload version=0.1.25
git add packaging/static-files/releases.json
git commit -m "Release Mai CLI Windows packages 0.1.25"
git push

进阶：项目状态和切换

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

mai status

查看可切换项目：

mai project list

切换当前项目：

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

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

常用环境变量

完整环境变量说明见 docs/environment.md。