Metadata-Version: 2.4
Name: maind
Version: 0.1.21
Summary: Mai CLI (Python) for local Git/DVC, model, dataset, and image workflows
Author-email: Mai <dev@mindreon.com>
License: MIT
Keywords: ai,cli,dataset,dvc,git,mai,model
Requires-Python: >=3.12
Requires-Dist: click<9.0.0,>=8.1.0
Requires-Dist: dulwich<1.0.0,>=0.22.0
Requires-Dist: dvc[s3]<4.0,>=3.0
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: huggingface-hub<1.0,>=0.24
Requires-Dist: modelscope-hub<1.0,>=0.1.6
Requires-Dist: pyyaml<7.0.0,>=6.0.0
Requires-Dist: typer<0.27.0,>=0.25.1
Description-Content-Type: text/markdown

# Mai CLI

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

如果需要完整命令说明，请查看 [README.full.md](./README.full.md)。

## 快速开始

### 1. 安装

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

```bash
pip install maind
mai --help
```

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

```powershell
python -m mai --help
python -m mai install
```

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

```powershell
$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](packaging/windows/README.md) 本地构建
2. 安装或解压到例如 `C:\Tools\mai-cli`
3. **重新打开**终端后运行：

```powershell
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。可用下列命令检查可选依赖：

```bash
mai install --check
mai install
```

也可以用 `pipx` 隔离安装：

```bash
pipx install maind
mai --help
```

### 2. 登录

交互式登录：

```bash
mai login
```

非交互式登录：

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

### 3. 下载模型或数据集

下载模型：

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

下载数据集：

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

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

```python
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)
```

指定下载目录：

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

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

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

## 常用操作

### 创建并上传模型

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

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

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

```bash
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`。

### 创建并上传数据集

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

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

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

### 发布已有本地目录

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

发布模型目录：

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

发布数据集目录：

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

### 从 Hugging Face 或 ModelScope 同步

从 Hugging Face 同步模型到平台：

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

从 ModelScope 同步数据集到平台：

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

### 文件和镜像

上传文件：

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

集群内调用必须通过 `MAI_FILE_CENTER_URL` 指向内部 `file-service`。外部调用未配置该变量时，会使用平台 `MAI_API_URL` 并自动添加 `/file-center` 前缀；内部 `baize-frontend` 地址不会作为文件上传回退地址。

构建平台镜像：

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

复制镜像：

```bash
mai image copy source:tag target:tag
```

### 预置资源示例

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

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

```bash
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 镜像。

```bash
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
```

进入容器后直接使用：

```bash
mai --help
mai login
```

## Windows 安装包构建（开发者）

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

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

若没有 `winget`，可从 [Inno Setup 官方下载页](https://jrsoftware.org/isdl.php) 安装。准备完成后执行：

```bash
make windows-package
```

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

```bash
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`（安装向导）

## 进阶：项目状态和切换

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

```bash
mai status
```

查看可切换项目：

```bash
mai project list
```

切换当前项目：

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

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

## 常用环境变量

| 变量 | 说明 |
|---|---|
| `MAI_API_URL` | 平台地址 |
| `MAI_AUTH_TOKEN` | 登录 token，优先级高于本地配置文件 |
| `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`](docs/environment.md)。
