# HuggingRun 通用用法

本文档说明**通用工具**的用法。所有能力都围绕这一套工具展开；示例只是「同一条通用流水线 + 不同 RUN_CMD 或不同 Dockerfile」的用法，不做单独定制。

**设计目标**：让用这个工具的人可以**正常部署所有东西**。

---

## 设计原则

- **用户尽量少做事**：不要求像其他云容器那样做复杂配置或付费才能持久化。
- **零额外成本**：HF 免费额度（2 vCPU、16GB、50GB 临时盘）即可用；持久化用 HF Dataset（免费私有仓库），无需买持久盘。
- **通用优先**：维护的是一套通用入口 + 持久化 + 环境变量；任何「跑什么」都由 `RUN_CMD` 或由不同 Dockerfile 决定，不在核心脚本里为某一案例写死逻辑。

---

## 通用流水线（所有用法共用）

1. **入口**：`/scripts/entrypoint.sh` → 调用 `sync_hf.py`。
2. **sync_hf.py**：  
   - 若配置了 `HF_TOKEN` 与 Dataset 仓库，则把 `PERSIST_PATH`（默认 `/data`）从 HF Dataset 拉回 → 再启动应用；  
   - 后台按 `SYNC_INTERVAL` 把 `PERSIST_PATH` 同步回 Dataset；  
   - 最后执行 `RUN_CMD`（或默认 demo）。  
3. **应用**：唯一要求是监听 `APP_PORT`（默认 7860）。需要持久化的数据放在 `PERSIST_PATH` 下即可。

没有任何「仅针对某一种容器」的步骤；换应用只换 `RUN_CMD` 或换一个使用同一套 `scripts/` 的 Dockerfile。

---

## 用户最少步骤（通用用法）

### 场景 A：跑默认 demo 或自定义命令

1. 在 HF 上 **Duplicate 本 Space**（或新建 Space 并克隆本仓库）。
2. 可选：在 Settings → Secrets 里配置  
   - `HF_TOKEN`（要持久化时必填）  
   - `RUN_CMD`（要跑的进程，不设则跑内置 demo）
3. 打开 Space 链接即可。  
无需改代码、无需付费、无需像其他云容器那样单独买持久盘或做复杂配置。

### 场景 B：跑「另一种镜像」示例

- 仍用**同一套通用工具**：只是换 Dockerfile。
- 操作：Duplicate 本 Space 后，替换根目录的 `Dockerfile` 内容。
- 之后同样只需在 Settings 里配 Secrets（如 `HF_TOKEN`），无需在通用脚本里加专用逻辑。

---

## 环境变量（通用）

| 变量 | 默认 | 说明 |
|------|------|------|
| `RUN_CMD` | 默认 demo | 要执行的命令 |
| `PERSIST_PATH` | `/data` | 与 HF Dataset 同步的目录 |
| `HF_TOKEN` | — | 持久化用 Token |
| `HF_DATASET_REPO` | `{SPACE_ID}-data` | Dataset 仓库 |
| `AUTO_CREATE_DATASET` | `false` | 是否自动创建 Dataset |
| `SYNC_INTERVAL` | `60` | 同步间隔（秒） |
| `PORT` / `APP_PORT` | `7860` | 应用监听端口（HF 只暴露此端口） |

所有行为都由这些变量与同一套脚本决定；不增加「仅某案例」的变量。

---

## 和「其他云容器」的对比

- **其它云**：往往要选机型、买持久盘、配网络/密钥等，步骤多、有持续费用。
- **HuggingRun**：Duplicate Space → 按需设 `HF_TOKEN` / `RUN_CMD`（或换示例 Dockerfile），即可跑任意兼容 Docker 的应用，持久化用 HF Dataset，不额外付费。