docs/GENERAL_USAGE.md

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，不额外付费。