docs/huggingface_space_deploy.md

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 中执行：

# 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 链接给他人免费体验，无需自建服务器。