PROJECT_INFO.md

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
• 提供公共访问链接

📝 使用说明

本地运行

# 安装依赖
pip install -r requirements.txt

# 运行测试
python3 simple_e2e_test.py

# 启动演示
python3 app.py

在线演示

访问 Hugging Face Spaces 链接，体验交互式 RAG 系统。

🎉 项目状态

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

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