docs/development/huggingface_deployment.md

Hugging Face Spaces 部署指南 (Deployment Guide)

本指南介绍如何将项目部署到 Hugging Face Spaces，并配置数据持久化存储。

1. 准备工作

确保本地代码已提交到 Git。

# 1. 在 Hugging Face 创建一个新的 Space
#    - SDK: Docker
#    - Hardware: CPU Basic (Free) or GPU (Paid)

# 2. Add Remote
git remote add space https://huggingface.co/spaces/USERNAME/SPACE_NAME

2. 配置持久化存储 (Data Persistence)

Hugging Face Spaces 默认重启后会重置文件系统。为了保存用户数据（评分、收藏），需要挂载持久化存储。

步骤 A: 申请 Persistent Storage (推荐)

1. 进入 Space -> Settings.
2. 找到 Persistent Storage.
3. 选择 Small (Free on standard CPU spaces, or Paid tiered).
4. 挂载路径填写 /data/user.

步骤 B: 配置环境变量

1. 进入 Space -> Settings -> Variables and secrets.
2. 添加变量：
   • USER_DATA_PATH: /data/user (对应挂载路径)

此配置会让应用将 user_profiles.json 保存到挂载的持久盘中，重启 Space 数据不会丢失。

3. 推送代码

git push space main

4. 常见问题 (FAQ)

Q: 用户数据可以实时更新推荐吗？

答:

• 可以实现实时过滤和重排序: 用户点了“喜欢”或“评分”后，系统会立即记录到 user_profiles.json。推荐接口 (RecommendationService.get_recommendations) 每次请求都会实时读取最新的用户历史，用于：
  1. 去重: 过滤掉已读/已收藏的书。
  2. 特征生成: 比如 sim_max (与最近交互物品的相似度) 会根据即时历史变化，从而影响排序分数。
• 但模型不会自动重训: 模型的权重是固定的。要让模型学到新的协同过滤模式 (Collaborative Filtering Patterns)，需要定期(如每周)在后台运行训练脚本 scripts/model/train_ranker.py 并更新模型文件。这通常通过 CI/CD 或 Scheduled Jobs 完成，而不是在 Space 在线服务中进行。

Q: chroma_db 需要持久化吗？

答:

• 如果你只提供只读搜索（不让用户上传新书），则不需要。当前的 ChromaDB 数据可以直接打包在 Docker 镜像中。
• 如果需要支持上传新书，则需要将 DATA_DIR 也指向持久化路径。