docs/README_HUGGINGFACE.md

🚀 在 Hugging Face Spaces 上部署 Flask 应用

📋 部署步骤

1. 创建 Hugging Face Space

1. 访问 https://huggingface.co/spaces
2. 点击 "Create new Space"
3. 填写信息：
   • Space name: 你的应用名称（例如：english-learning-app）
   • License: 选择合适的许可证
   • Select the Space SDK: 选择 Docker（重要！）
   • Visibility: Public 或 Private

2. 推送代码到 Hugging Face Space

方式一：使用 Git（推荐）

# 添加 Hugging Face Space 作为远程仓库
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME

# 推送代码
git add .
git commit -m "部署 Flask 应用到 Hugging Face Spaces"
git push space main

方式二：使用 Hugging Face Hub CLI

# 安装 Hugging Face Hub CLI
pip install huggingface-hub

# 登录
huggingface-cli login

# 上传文件
huggingface-cli upload YOUR_USERNAME/YOUR_SPACE_NAME . . --repo-type=space

3. 等待构建

• Hugging Face Spaces 会自动检测 Dockerfile
• 构建过程需要 5-10 分钟
• 可以在 Space 页面查看构建日志

4. 访问应用

构建完成后，应用将在以下地址可用：

https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space

---

🔧 配置说明

Dockerfile 配置

当前 Dockerfile 已配置为使用：

• Python 3.12
• Gunicorn 生产服务器（4 个工作进程）
• 端口 7860（Hugging Face Spaces 要求）
• 健康检查：自动检测应用状态

环境变量

如需设置环境变量，在 Hugging Face Space 设置中添加：

1. 进入你的 Space 页面
2. 点击 "Settings"
3. 在 "Repository secrets" 部分添加环境变量：
   • SECRET_KEY: Flask 密钥（生产环境必需）
   • OPENSEARCH_HOST: OpenSearch 主机（如需要）
   • OPENSEARCH_PORT: OpenSearch 端口（如需要）

---

📝 重要文件清单

确保以下文件存在于仓库根目录：

• ✅ Dockerfile - Docker 构建文件
• ✅ requirements.txt - Python 依赖
• ✅ app.py - Flask 主应用
• ✅ config.py - 配置文件
• ✅ index.html - 前端页面
• ✅ style.css - 样式文件
• ✅ script.js - JavaScript 文件
• ✅ book_10242.json - 书籍数据
• ✅ static/ - 静态资源目录
• ✅ assets/ - 音频、图片等资源

---

🧪 本地测试 Docker 构建

在推送到 Hugging Face 之前，建议本地测试：

# 构建 Docker 镜像
docker build -t english-learning-app .

# 运行容器
docker run -p 7860:7860 english-learning-app

# 测试应用
curl http://localhost:7860/api/health

如果本地测试成功，推送到 Hugging Face Spaces 后应该也能正常运行。

---

🔍 故障排查

问题：构建失败

解决方案：

1. 检查 Hugging Face Space 的构建日志
2. 确保 requirements.txt 中的所有依赖都能正确安装
3. 验证 Dockerfile 语法正确

问题：应用启动失败

解决方案：

1. 检查应用日志（在 Space 页面的 "Logs" 标签）
2. 确认必要文件都已上传（特别是 book_10242.json）
3. 检查端口是否正确设置为 7860

问题：静态资源无法访问

解决方案：

1. 确认 static/ 和 assets/ 目录已上传
2. 检查 .gitignore 是否误排除了必要文件
3. 验证文件路径大小写正确（Linux 区分大小写）

问题：应用运行缓慢

解决方案：

1. 检查 book_10242.json 文件大小
2. 考虑使用 Hugging Face Spaces 的付费套餐（更多资源）
3. 优化数据加载方式（延迟加载、缓存等）

---

📊 性能优化建议

1. 使用 Gunicorn（已配置）

CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:7860", "--timeout", "120", "app:app"]

2. 静态资源优化

考虑将大型静态资源（音频、图片）上传到 CDN 或 Hugging Face Hub。

3. 数据库持久化

Hugging Face Spaces 提供持久化存储：

# 在 app.py 中使用持久化目录
import os
PERSISTENT_DIR = os.environ.get('SPACE_PERSISTENT_DIR', '.')

---

🌐 访问 API

部署后，可以通过以下端点访问：

# 健康检查
curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/api/health

# 获取书籍信息
curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/api/book/info

# 搜索内容
curl -X POST https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/api/search \
  -H "Content-Type: application/json" \
  -d '{"keyword": "hello"}'

---

📚 参考资源

• Hugging Face Spaces 文档
• Docker Spaces 指南
• Flask 部署最佳实践

---

⚙️ 高级配置

自定义启动命令

如果需要使用 Flask 内置服务器而非 Gunicorn，修改 Dockerfile 最后一行：

CMD ["python3.12", "app.py"]

添加工作进程

根据你的 Space 资源调整 Gunicorn 工作进程数：

# 2 个进程（较小的 Space）
CMD ["gunicorn", "-w", "2", "-b", "0.0.0.0:7860", "app:app"]

# 8 个进程（更大的 Space）
CMD ["gunicorn", "-w", "8", "-b", "0.0.0.0:7860", "app:app"]

---

🎉 部署完成！

部署成功后，你的 Flask 英语学习应用将在 Hugging Face Spaces 上运行！

示例 URL: https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space

享受你的应用吧！🚀