| # Hugging Face Spaces 免费部署指南 | |
| 本指南演示如何将 RLDT 的 Gradio 前端零成本发布到 **Hugging Face Spaces**，并使用 Hugging Face Inference 免费额度作为 LLM 后端。 | |
| ## 1. 目录与关键文件 | |
| - `app.py`：Spaces 的入口脚本，直接调用现有的 `create_gradio_interface()` 并在 `PORT`（Spaces 自动注入）上启动，无需命令行参数。 | |
| - `requirements.txt`：Python 依赖列表，Spaces 会自动安装。 | |
| - `RL0910/enhanced_chat_ui.py`：主界面与业务逻辑，保持不变。 | |
| > 如果需要自带示例模型，可将模型权重放在仓库的 `output/models/` 下或在启动脚本中下载。 | |
| ## 2. 准备 Hugging Face 账号与 Token | |
| 1. 访问 https://huggingface.co/settings/tokens 创建 **Write** 权限的 Access Token。 | |
| 2. 复制 Token，稍后在 Space 中配置为 `HUGGINGFACEHUB_API_TOKEN`。Hugging Face Inference 免费额度足以支撑轻量对话演示。 | |
| ## 3. 创建 Space | |
| 1. 在 Hugging Face 主页点击 **New Space**。 | |
| 2. 选择模板 **Gradio**（`app.py` 会被自动识别）。 | |
| 3. 选择 **Public**（免费额度）或 **Private**（需 Pro）。 | |
| 4. 创建完成后，获取 Space 的 Git 远程地址（形如 `https://huggingface.co/spaces/<org>/<space-name>`）。 | |
| ## 4. 推送代码到 Space | |
| 在本地或 CI 中执行： | |
| ```bash | |
| # 1) 克隆当前仓库并进入目录 | |
| cd /path/to/RLDT | |
| # 2) 添加 Space 作为远程 | |
| git remote add space https://huggingface.co/spaces/<org>/<space-name> | |
| # 3) 推送 main 分支（或当前分支） | |
| git push space main | |
| ``` | |
| 推送完成后，Spaces 会自动构建：安装依赖 → 运行 `app.py` → 暴露页面。 | |
| ## 5. 配置环境变量（LLM 走 Hugging Face Inference） | |
| 在 Space 页面打开 **Settings → Variables and secrets**，添加： | |
| - `HUGGINGFACEHUB_API_TOKEN`：步骤 2 获取的 Token。 | |
| - 可选： | |
| - `HUGGINGFACE_MODEL`（默认 `meta-llama/Meta-Llama-3-8B-Instruct`） | |
| - `HUGGINGFACE_TASK`（默认 `text-generation`） | |
| - `HUGGINGFACE_TEMPERATURE`、`HUGGINGFACE_MAX_TOKENS` | |
| - 如需其它云端模型，也可设置 `GOOGLE_API_KEY`、`COHERE_API_KEY`、`ANTHROPIC_API_KEY` 等，优先级在 `RL0910/agent_graph.py` 中定义。 | |
| > 无需显式设置端口，Spaces 会自动注入 `PORT` 环境变量，`app.py` 会读取并绑定到 `0.0.0.0`。 | |
| ## 6. 数据与模型的放置方式 | |
| - **轻量演示**：直接使用内置虚拟数据生成流程，无需上传文件。 | |
| - **自带模型/数据**： | |
| - 将模型权重放入仓库（小体积）并随代码推送；或 | |
| - 在 `app.py` 中添加启动时的下载逻辑（如从 `hf://` 或公开 URL）；或 | |
| - 在 Space 的 **Persistent storage**（启用后）中手动上传，再在代码中读取 `/data` 路径。 | |
| - 若使用本地训练功能，请在 **Variables and secrets** 中设置： | |
| - `DYNAMICS_MODEL_PATH`、`OUTCOME_MODEL_PATH`、`Q_NETWORK_PATH` | |
| - `DATA_DIR`（数据或导出报告目录） | |
| ## 7. 验证部署 | |
| - 等待构建完成后，点击 Space 页面右上角的 **App**，应显示 RLDT 的多标签 Gradio 界面。 | |
| - 打开 “Chat with DRIVE Agent” 输入指令，确认能返回由 Hugging Face Inference 提供的回复。 | |
| - 查看 **Logs**（左侧栏）可排查依赖安装或模型加载问题。 | |
| ## 8. 常见问题 | |
| - **构建超时/内存不足**：优先使用虚拟数据与远程 LLM，避免在免费套餐加载过大的本地模型。 | |
| - **LLM 无响应**：确认 `HUGGINGFACEHUB_API_TOKEN` 和 `HUGGINGFACE_MODEL` 配置正确，或尝试更小的模型（如 `mistralai/Mistral-7B-Instruct-v0.2`）。 | |
| - **端口相关错误**：无需手动指定端口，确保未在代码中硬编码端口；`app.py` 已读取 `PORT`。 | |
| 部署完成后即可分享 Space 链接给他人免费体验，无需自建服务器。 | |