Metadata-Version: 2.4
Name: maind
Version: 0.1.1
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: 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<1.0.0,>=0.15.0
Description-Content-Type: text/markdown

# Mai CLI

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

常用命令：

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

## 安装和运行

### 方式一：pip 安装

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

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

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

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

开启 shell 自动补全：

```bash
mai --install-completion
```

重新打开终端后，输入 `mai <TAB>` 即可补全命令和参数。

### 方式二：源码运行

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

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

### 方式三：Docker 直接运行

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

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

镜像内已包含：

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

## 登录

交互式登录：

```bash
mai login
```

非交互式登录：

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

## 项目状态和切换

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

```bash
mai status
```

查看可切换项目：

```bash
mai project list
```

切换当前项目：

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

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

## 使用

### 下载模型或数据集

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

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

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

指定下载目录：

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

### 初始化上传工作区

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

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

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

数据集同理：

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

### 上传和推送修改

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

```bash
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` 文件需要一起提交，不要删除

调整大文件阈值：

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

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

如果模型或数据集文件已经在本地目录中，可以用 `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
```

构建平台镜像：

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

## 预置资源

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

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

只下载和准备本地资源：

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

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

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

## 完整示例

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

```bash
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 创建：

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

发布本地目录：

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

### 示例三：从 Hugging Face 同步模型

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

```python
from mai import MaiClient

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