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 用户可以按安全策略选择以下任一发行方式:
- 安装包(
.exe):使用向导安装,可选加入用户 PATH - 单文件 EXE(
*-standalone-win-amd64.exe):只下载一个文件,直接运行 - 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 指针时,download 和 repo pull 会自动执行 git lfs pull 展开真实内容,
此时需要 Git LFS;Windows 上缺失时会明确提示安装 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 同步
sync 一条命令完成"从 Hugging Face / ModelScope 下载 → 平台上不存在则创建资源 → 发布到指定版本"。
同名资源已存在时会复用;若其预置属性与本次请求不一致,会在下载前报错,不会创建同名资源。
源地址用 hf://<org>/<repo> 或 ms://<org>/<repo>,--model / --dataset 二选一。
从 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 sync --model hf://Qwen/Qwen2.5-7B --name "qwen2.5-7b" \
--revision main \
--include "*.json" --include "*.safetensors" --exclude "original/*" \
--resources-dir /data/mai-resources
常用参数:
| 参数 | 说明 |
|---|---|
--name |
平台资源名,默认取源仓库 ID 的最后一段 |
--version / -b |
发布到的平台版本,默认 main;其他版本不存在时会基于 main 创建 |
--revision |
上游仓库的分支、tag 或 commit,默认使用上游默认分支 |
--include / --exclude |
只下载或排除匹配的文件(glob),可重复指定 |
--resources-dir |
本地暂存目录,默认 <系统临时目录>/mai/resources;大模型建议指定到空间充足的磁盘 |
--threshold / --count-threshold |
与 mai repo add 相同的大文件和文件数阈值,默认 5 MiB / 1000 |
--preset / --source |
资源不存在时按预置资源或指定来源创建,见下文"预置资源" |
下载内容保存在 <resources-dir>/models/<name> 或 <resources-dir>/datasets/<name>;重复执行会复用
已下载的文件。内容没有变化时不会重复推送。访问私有或受限 Hugging Face 仓库时设置 HF_TOKEN,
使用镜像站时设置 HF_ENDPOINT。
文件和镜像
上传文件:
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
预置资源
预置资源是租户级的公共模型和数据集:同租户下所有项目都可以只读下载,只有租户管理员或系统管理员
可以创建和修改。create 和 sync 通过 --preset 把新资源创建为预置资源:
# 创建预置数据集,再按普通流程连接、上传
mai create --dataset "common-dpo" --description "shared dataset" --preset
mai connect --dataset "common-dpo" --version main
# 从 Hugging Face 同步为预置模型
mai sync --model hf://Qwen/Qwen2.5-7B --name "qwen2.5-7b" --preset
说明:
--preset等价于--source preset,两者同时使用时--source只能是preset,否则报错。- 不加
--preset时默认--source custom,即当前项目的普通资源;模型还支持--source taskPublish。 --preset只在创建资源时生效。sync在下载前先检查同名资源:已存在且预置属性一致时直接复用; 预置属性不一致(例如已有同名预置数据集,却不带--preset同步)时立即报错,不会创建同名资源。- 名称规则:预置资源名在整个租户内唯一,不能与任何项目里的资源重名;普通资源名不能与本项目资源或任何
预置资源重名。
mai create和sync都会在发出创建请求前检查当前项目可见的同名资源。 - 后续
connect、repo push、publish会根据平台返回的资源来源自动按预置资源处理,无需再加参数。
预置资源批量 seed
仓库内置了与 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 等命令都会使用新的项目上下文。
常用环境变量
| 变量 | 说明 |
|---|---|
MAI_API_URL |
平台地址 |
MAI_AUTH_TOKEN |
登录 token,优先级高于本地配置文件 |
MAI_TLS_VERIFY |
HTTPS 证书校验开关,设为 false 跳过校验,默认 true |
SSL_CERT_FILE |
HTTP API 使用的 PEM CA 证书文件,校验开启时生效 |
MAI_CONFIG_DIR |
配置文件目录,默认 ~/.config/mai |
MAI_GIT_USER_NAME / MAI_GIT_USER_EMAIL |
Git 提交作者身份 |
MAI_REPO_READY_TIMEOUT_MS / MAI_REPO_READY_INTERVAL_MS |
等待 FVM 仓库就绪的超时和轮询间隔 |
MAI_DVC_REMOTE_STORAGE_ENDPOINTURL |
workload 覆盖 DVC S3 endpoint |
MAI_DVC_PUSH_JOBS |
未通过 --jobs 指定时的标准 DVC push 并发数,默认 2 |
MAI_DVC_S3_UPLOAD_JOBS |
未通过 --s3-jobs 指定时的 botocore S3 上传并发数,默认 4 |
完整环境变量说明见 docs/environment.md。
Metadata
Release files for maind 0.1.31
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| maind-0.1.31.tar.gz | 325.9 kB | Without provenance | Details for maind-0.1.31.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| maind-0.1.31-py3-none-any.whl | Python 3 | none | any | Details for maind-0.1.31-py3-none-any.whl |
Total release size: 417.3 kB
Release files / maind-0.1.31.tar.gz
| Download URL | maind-0.1.31.tar.gz |
|---|---|
| Size | 325.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
784ed96784576a143f0f0895ad2a862819df8a6f20be9ab69388c81ae02ff41e
|
|
BLAKE2b-256 checksum How to use checksums |
fc742b7df19a3125160adf68b76eac94ad30919477db1c2411d37d700c0361d2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.12
|
Release files / maind-0.1.31-py3-none-any.whl
| Download URL | maind-0.1.31-py3-none-any.whl |
|---|---|
| Size | 91.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5b2e1b66f9e26611427a8b5a227b5f118804bd1d43e2354cf729b6ec897c5327
|
|
BLAKE2b-256 checksum How to use checksums |
3e740e4029cb958c3aafcced1e81eb99c8c8c951782fa194ddb25f2549a00466
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.12
|
Security for maind 0.1.31
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.