# SafeRAG 项目信息

## 📁 项目结构

```
safe_rag/
├── app.py                    # Gradio 演示应用
├── requirements.txt          # Python 依赖
├── config.yaml              # 配置文件
├── README.md                # 项目说明（HF Spaces 配置）
├── simple_e2e_test.py       # 端到端测试
├── simple_test.py           # 基本功能测试
├── data_processing/         # 数据处理模块
│   ├── __init__.py
│   ├── data_loader.py       # 数据加载器
│   └── preprocessor.py      # 文本预处理器
├── retriever/              # 检索模块
│   ├── __init__.py
│   ├── embedder.py         # 嵌入生成器
│   ├── faiss_index.py      # FAISS 索引
│   ├── retriever.py        # 检索器
│   └── reranker.py         # 重排序器
├── generator/              # 生成模块
│   ├── __init__.py
│   ├── vllm_server.py      # vLLM 服务器
│   ├── prompt_templates.py # 提示模板
│   └── safe_generate.py    # 安全生成器
├── calibration/            # 校准模块
│   ├── __init__.py
│   ├── features.py         # 特征提取
│   ├── calibration_head.py # 校准头
│   └── trainer.py          # 训练器
└── eval/                   # 评估模块
    ├── __init__.py
    ├── eval_qa.py          # QA 评估
    ├── eval_attr.py        # 归因评估
    ├── eval_calib.py       # 校准评估
    └── eval_system.py      # 系统评估
```

## 🚀 核心功能

### 1. 数据处理 (`data_processing/`)
- **DataLoader**: 加载 HF Datasets（HotpotQA, TriviaQA, Wikipedia）
- **Preprocessor**: 文本清理、句子分割、词元化

### 2. 检索系统 (`retriever/`)
- **Embedder**: 使用 BGE/E5 生成嵌入向量
- **FAISSIndex**: 构建和搜索 FAISS 索引
- **Retriever**: 批量检索相关文档
- **Reranker**: 重排序提升检索质量

### 3. 生成系统 (`generator/`)
- **VLLMServer**: vLLM 推理服务器
- **SafeGenerator**: 风险感知的答案生成
- **PromptTemplates**: 提示模板管理

### 4. 风险校准 (`calibration/`)
- **RiskFeatureExtractor**: 提取 16 维风险特征
- **CalibrationHead**: LogReg/MLP 校准头
- **Trainer**: 校准头训练

### 5. 评估系统 (`eval/`)
- **QAEvaluator**: EM/F1 评估
- **AttributionEvaluator**: 引用归因评估
- **CalibrationEvaluator**: 校准质量评估
- **SystemEvaluator**: 系统性能评估

## 🎯 风险校准策略

### 风险特征 (16维)
1. **检索统计**: 相似度分数、方差、多样性
2. **覆盖特征**: Q&A 间的 token/实体重叠
3. **一致性特征**: 段落间语义相似度
4. **多样性特征**: 主题方差、段落多样性

### 自适应策略
- **低风险 (r < 0.3)**: 正常生成
- **中风险 (0.3 ≤ r < 0.7)**: 保守生成 + 强制引用
- **高风险 (r ≥ 0.7)**: 非常保守或拒绝回答

## 📊 性能目标

- **QA 准确率**: 相比 vanilla RAG 的 EM/F1 提升
- **归因质量**: 引用精确率/召回率提升 8-12pt
- **校准质量**: ECE 降低 30-40%
- **系统吞吐**: vLLM 带来 2-3.5x 提升

## 🧪 测试验证

### 端到端测试 (`simple_e2e_test.py`)
- ✅ 8/8 测试通过
- ✅ 完整 RAG 流程验证
- ✅ 所有核心功能正常

### 基本测试 (`simple_test.py`)
- ✅ 模块导入测试
- ✅ 基本功能验证
- ✅ 配置检查

## 🚀 部署到 Hugging Face Spaces

### 1. 上传文件
- 将整个 `safe_rag` 目录上传到 HF Spaces
- 确保 `app.py` 在根目录

### 2. 配置 Spaces
- SDK: Gradio
- Hardware: GPU (推荐 A10G 或 A100)
- Environment: Python 3.8+

### 3. 自动部署
- HF Spaces 会自动安装依赖
- 自动启动 `app.py`
- 提供公共访问链接

## 📝 使用说明

### 本地运行
```bash
# 安装依赖
pip install -r requirements.txt

# 运行测试
python3 simple_e2e_test.py

# 启动演示
python3 app.py
```

### 在线演示
访问 Hugging Face Spaces 链接，体验交互式 RAG 系统。

## 🎉 项目状态

✅ **完成**: 所有核心模块实现
✅ **测试**: 端到端测试通过
✅ **简化**: 移除不必要的文件
✅ **就绪**: 可部署到 HF Spaces

SafeRAG 项目已经准备好部署和使用了！