README_FIXES.md

项目修复说明

修复的问题

1. 导入路径问题

• 问题: 使用了已弃用的 langchain_huggingface 和 langchain.embeddings 导入
• 修复: 统一使用 langchain_community.embeddings 导入 HuggingFaceEmbeddings
• 影响文件:
  • src/demo/views.py
  • src/demo/asg_retriever.py
  • src/demo/main.py
  • src/demo/survey_generator_api.py
  • src/demo/survey_generation_pipeline/main.py
  • src/demo/survey_generation_pipeline/asg_retriever.py
  • test_cache_fix.py

2. 文本分割器导入问题

• 问题: 使用了已弃用的 langchain.text_splitter 导入
• 修复: 使用新的 langchain_text_splitters 包
• 影响文件:
  • src/demo/asg_retriever.py
  • src/demo/survey_generation_pipeline/asg_retriever.py

3. 环境变量和权限问题

• 问题: 在 Hugging Face Spaces 中遇到 matplotlib、fontconfig、numba 缓存权限错误
• 修复: 动态设置环境变量，在 HF Spaces 中使用临时目录
• 影响文件:
  • src/demo/views.py (主要修复)
  • src/demo/path_utils.py (移除 TRANSFORMERS_CACHE)

4. Transformers 缓存警告

• 问题: TRANSFORMERS_CACHE 环境变量已弃用
• 修复: 只设置 HF_HOME 和 HF_HUB_CACHE
• 影响文件:
  • src/demo/path_utils.py

新增文件

1. startup.py

• 环境设置脚本，用于在启动时设置所有必要的环境变量
• 检查关键导入是否正常工作
• 支持本地和 Hugging Face Spaces 环境

2. requirements.txt

• 完整的依赖列表，包含所有必要的包和版本
• 确保兼容性和稳定性

3. README_FIXES.md

• 本文档，记录所有修复内容

环境变量设置

Hugging Face Spaces 环境

当检测到 SPACE_ID 或 HF_SPACE_ID 环境变量时，自动设置：

# 临时目录
temp_base = tempfile.mkdtemp()

# matplotlib 配置
os.environ["MPLCONFIGDIR"] = os.path.join(temp_base, "matplotlib")

# XDG 缓存
os.environ["XDG_CACHE_HOME"] = temp_base

# numba 缓存
os.environ["NUMBA_CACHE_DIR"] = os.path.join(temp_base, "numba_cache")

# Hugging Face 缓存
os.environ["HF_HOME"] = os.path.join(temp_base, "hf_cache")
os.environ["HF_HUB_CACHE"] = os.path.join(temp_base, "hf_cache/hub")

本地环境

使用默认缓存目录，不进行特殊设置。

使用方法

1. 安装依赖

pip install -r requirements.txt

2. 运行环境检查

python startup.py

3. 启动应用

python manage.py runserver

注意事项

1. 缓存目录: 在 Hugging Face Spaces 中，所有缓存都存储在临时目录中，重启后会清除
2. 权限: 修复后的代码会自动处理权限问题，无需手动设置
3. 兼容性: 代码同时支持本地开发和 Hugging Face Spaces 部署
4. 依赖: 确保使用 requirements.txt 中的版本，避免兼容性问题

验证修复

运行 startup.py 脚本，应该看到：

• ✅ 所有导入成功
• ✅ 环境变量正确设置
• ✅ 无权限错误
• ✅ 无弃用警告