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` 环境变量时，自动设置：

```python
# 临时目录
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. 安装依赖
```bash
pip install -r requirements.txt
```

### 2. 运行环境检查
```bash
python startup.py
```

### 3. 启动应用
```bash
python manage.py runserver
```

## 注意事项

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

## 验证修复

运行 `startup.py` 脚本，应该看到：
- ✅ 所有导入成功
- ✅ 环境变量正确设置
- ✅ 无权限错误
- ✅ 无弃用警告