deployment/DEPLOY_CHECKLIST.md

Hugging Face Spaces 部署检查清单

📋 部署前检查

1. 依赖版本确认

• requirements_hf.txt 中 huggingface-hub==0.23.5
• requirements_hf.txt 中 gradio==4.44.0
• README_HF.md frontmatter 中 sdk_version: "4.44.0"

2. 文件结构确认

• app.py 存在且正确
• frontend/dist/ 已构建（运行 cd frontend && npm run build）
• data/ 目录存在
• generated_images/ 目录存在

3. 环境变量配置

在 Space Settings → Repository secrets 中配置：

• ZHIPU_API_KEY - 必需
• MINIMAX_API_KEY - 可选
• MINIMAX_GROUP_ID - 可选

🚀 部署步骤

方法 1: 使用 deploy_to_hf.sh (推荐)

# 1. 确保脚本可执行
chmod +x deploy_to_hf.sh

# 2. 运行部署脚本
./deploy_to_hf.sh

方法 2: 手动部署

# 1. 构建前端
cd frontend
npm install
npm run build
cd ..

# 2. 提交到 Git
git add .
git commit -m "Deploy to Hugging Face Spaces"

# 3. 推送到 Hugging Face
git push hf main

🐛 常见问题

ImportError: cannot import name 'HfFolder'

原因： gradio 和 huggingface_hub 版本不兼容

解决方法：

1. 确认 requirements_hf.txt 版本正确
2. 在 Space Settings 中点击 "Factory reboot"
3. 查看 Container logs 确认安装的版本

前端 404 错误

原因： 前端未构建或未正确挂载

解决方法：

1. 本地运行 cd frontend && npm run build
2. 确认 frontend/dist/ 目录存在且有内容
3. 提交并推送 frontend/dist/ 到仓库

API 调用失败

原因： 环境变量未配置

解决方法：

1. 在 Space Settings → Repository secrets 添加 ZHIPU_API_KEY
2. 重启 Space
3. 查看 Logs 确认 API 密钥已加载

📊 部署后验证

1. 健康检查

访问 https://your-space.hf.space/health 应返回：

{
  "status": "healthy",
  "timestamp": "..."
}

2. API 文档

访问 https://your-space.hf.space/docs 查看 API 文档

3. 前端访问

访问 https://your-space.hf.space/ 应显示应用界面

4. 功能测试

• 首页输入框可以输入文字
• 点击麦克风可以录音（需要浏览器权限）
• 点击 AI 形象显示对话框
• 底部导航可以切换页面

🔄 更新部署

代码更新

git add .
git commit -m "Update: description"
git push hf main

强制重建

如果遇到缓存问题：

1. 进入 Space Settings
2. 点击 "Factory reboot"
3. 等待重新构建完成

📝 版本兼容性

已测试的稳定组合

gradio	huggingface-hub	Python	状态
4.44.0	0.23.5	3.11	✅ 推荐
4.36.1	0.23.0	3.11	✅ 可用
5.x	latest	3.11	❌ 不兼容

不兼容的组合

• gradio==4.x + huggingface-hub>=0.24.0 → HfFolder 错误
• gradio==5.x + huggingface-hub<0.24.0 → 版本冲突

🔗 相关资源

• Hugging Face Spaces 文档
• Gradio 文档
• 项目 README