# 医学文献自动标注系统使用指南

## 🎉 系统已完全升级

您的医学文献自动标注系统已经升级到最新版本，支持安全的环境变量配置和GitHub协作！

### ✅ 支持的模型

- **DeepSeek Chat**: `deepseek-chat` - 速度快，适合大批量处理
- **DeepSeek Reasoner**: `deepseek-reasoner` - 推理能力最强，适合复杂关系识别
- **Qianwen Plus**: `qwen-plus` - 中文理解优秀，医学领域表现良好

### 🔒 安全性升级

- ✅ API密钥通过环境变量管理，不再硬编码
- ✅ 数据文件已排除在版本控制之外
- ✅ GitHub项目已创建：https://github.com/chenxingqiang/medical-literature-annotation

## 🚀 立即开始使用

### 0. 环境配置（必须先完成）

```bash
# 设置API密钥环境变量
export DEEPSEEK_API_KEY=your_deepseek_api_key_here
export QIANWEN_API_KEY=your_qianwen_api_key_here

# 验证配置
echo $DEEPSEEK_API_KEY
echo $QIANWEN_API_KEY
```

### 1. 交互式使用

```bash
# 运行主程序（推荐）
python3 run_annotation.py

# 选择功能：
# 1. 测试单个文件
# 2. 批量处理所有数据
# 3. 比较不同模型结果
```

### 2. 直接批量处理

```bash
# DeepSeek Chat - 快速处理
python3 -c "
from auto_annotation_system import batch_process_directory
batch_process_directory(
    data_dir='datatrain',
    model='deepseek-chat',
    model_type='deepseek'
)
"

# DeepSeek Reasoner - 深度推理
python3 -c "
from auto_annotation_system import batch_process_directory
batch_process_directory(
    data_dir='datatrain',
    model='deepseek-reasoner',
    model_type='deepseek-reasoner'
)
"

# Qianwen Plus - 中文优化
python3 -c "
from auto_annotation_system import batch_process_directory
batch_process_directory(
    data_dir='datatrain',
    model='qwen-plus',
    model_type='qianwen'
)
"
```

### 3. 监控和管理

```bash
# 实时监控进度
python3 batch_monitor.py --monitor

# 查看处理状态
python3 batch_monitor.py --status

# 重启失败的任务
python3 batch_monitor.py --restart deepseek-reasoner
```

## 📊 数据规模

您的数据集包含：
- **parasite-ids-390**: 390种寄生虫相关疾病
- **bacteria-ids-4937**: 4937种细菌相关疾病  
- **fugus-ids-610**: 610种真菌相关疾病
- **microorganism-ids-8228**: 8228种微生物相关疾病

**总计**: 约14,000种疾病的医学文献数据

## 🎯 标注任务

系统将自动完成：

1. **实体识别**
   - 🦠 Bacteria（病原微生物）
   - 🏥 Disease（自身免疫性疾病）

2. **关系分类**
   - `contributes_to`: 病原体导致疾病
   - `ameliorates`: 病原体改善疾病
   - `correlated_with`: 统计关联
   - `biomarker_for`: 诊断标志物

3. **证据提取**
   - 完整的证据句子
   - 关系类型判断

## 💡 使用建议

### 模型选择策略

1. **单模型使用**
   - DeepSeek: 适合复杂推理场景
   - Qianwen: 适合中文医学文献

2. **双模型比较**
   - 同时使用两个模型
   - 比较结果选择最佳
   - 提高标注质量

### 处理流程建议

```
1. 先运行演示 → 2. 测试单文件 → 3. 批量处理 → 4. 转换格式 → 5. 人工校验
```

## 📁 输出结构

新版本采用更清晰的目录结构，结果保存在各疾病目录的 `annotation/` 子目录下：

```
datatrain/
├── bacteria-ids-4937/
│   └── A/
│       └── Acute motor axonal neuropathy/
│           └── annotation/
│               ├── Acute motor axonal neuropathy_annotated_deepseek.json
│               ├── Acute motor axonal neuropathy_annotated_deepseek-reasoner.json
│               └── Acute motor axonal neuropathy_annotated_qianwen.json
├── parasite-ids-390/
│   └── A/
│       └── Achalasia/
│           └── annotation/
│               ├── Achalasia_annotated_deepseek.json
│               └── ...
└── ...
```

### 📊 结果文件说明

每个JSON文件包含：
- **entities**: 识别的实体（Bacteria, Disease）
- **relations**: 关系三元组（主体-关系-客体）
- **evidence**: 支持证据的文本片段
- **metadata**: 处理信息和统计数据

## 🔄 后续处理

### 数据统计和分析

```bash
# 查看整体处理状态
python3 batch_monitor.py --status

# 统计标注结果
python3 -c "
import os
import json
from collections import defaultdict

stats = defaultdict(int)
for root, dirs, files in os.walk('datatrain'):
    for file in files:
        if file.endswith('_annotated_deepseek.json'):
            stats['deepseek'] += 1
        elif file.endswith('_annotated_qianwen.json'):
            stats['qianwen'] += 1
        elif file.endswith('_annotated_deepseek-reasoner.json'):
            stats['deepseek-reasoner'] += 1

print('标注完成统计:')
for model, count in stats.items():
    print(f'  {model}: {count} 个文件')
"
```

### 结果比较和质量评估

```bash
# 比较不同模型的结果（如果都已处理）
python3 -c "
import json
import os

def compare_results(disease_path):
    models = ['deepseek', 'qianwen', 'deepseek-reasoner']
    results = {}
    
    for model in models:
        json_file = f'{disease_path}_annotated_{model}.json'
        if os.path.exists(json_file):
            with open(json_file, 'r', encoding='utf-8') as f:
                results[model] = json.load(f)
    
    return results

# 使用示例
# results = compare_results('datatrain/bacteria-ids-4937/A/Acute motor axonal neuropathy/annotation/Acute motor axonal neuropathy')
"
```

### 导出和备份

```bash
# 创建结果备份
tar -czf annotation_results_$(date +%Y%m%d).tar.gz datatrain/*/annotation/

# 导出统计报告
python3 batch_monitor.py --status > annotation_report_$(date +%Y%m%d).txt
```

## 📈 系统特性

### 🚀 性能特点

- **DeepSeek Chat**: 速度快，适合大批量处理
- **DeepSeek Reasoner**: 推理深度最强，关系识别准确率高
- **Qianwen Plus**: 中文医学术语理解优秀

### 🛡️ 稳定性保障

- **断点续传**: 支持中断后继续处理，已处理文件自动跳过
- **错误重试**: 网络异常自动重试，最大重试5次
- **进度监控**: 实时查看处理进度和状态

## ⚡ 性能预估

以您的数据规模（约566个Excel文件）：
- **单文件处理**: 30秒-2分钟（取决于文章数量）
- **批量处理**: 数小时-数天（取决于API响应速度）
- **推荐策略**: 
  1. 先用DeepSeek Chat快速处理大部分数据
  2. 对重要数据使用DeepSeek Reasoner深度分析
  3. 使用监控工具跟踪进度

## 🛠️ 故障排除

### 常见问题及解决方案

**Q: 提示"请设置环境变量 DEEPSEEK_API_KEY"**
```bash
# 解决方案：设置环境变量
export DEEPSEEK_API_KEY=your_actual_api_key
export QIANWEN_API_KEY=your_actual_api_key

# 验证设置
echo $DEEPSEEK_API_KEY
```

**Q: 网络连接不稳定，处理中断**
- ✅ 系统支持断点续传，重新运行即可继续
- ✅ 自动重试机制，网络问题会自动处理
- ✅ 使用 `python3 batch_monitor.py --restart model_name` 重启

**Q: 模块导入错误**
```bash
# 确保依赖已安装
pip install -r requirements.txt

# 检查Python环境
python3 -c "import pandas, openpyxl, openai, requests; print('依赖正常')"
```

**Q: JSON解析错误**
- 系统会自动处理LLM输出格式问题
- 错误文件会被记录，可以单独重新处理

### 📊 监控和诊断

```bash
# 实时监控处理状态
python3 batch_monitor.py --monitor

# 查看详细处理报告
python3 batch_monitor.py --status

# 检查失败的文件
grep "❌" annotation_log.txt
```

## 🎯 推荐工作流程

### 阶段1: 环境准备
```bash
# 1. 设置环境变量
export DEEPSEEK_API_KEY=your_key
export QIANWEN_API_KEY=your_key

# 2. 验证环境
python3 run_annotation.py  # 选择测试功能
```

### 阶段2: 小规模试验
```bash
# 选择少量文件测试不同模型
python3 -c "
from auto_annotation_system import MedicalAnnotationLLM
# 测试单个文件，比较模型效果
"
```

### 阶段3: 批量处理
```bash
# 根据测试结果选择最适合的模型进行批量处理
python3 batch_monitor.py --restart deepseek-reasoner
```

### 阶段4: 结果分析
```bash
# 统计和分析结果
python3 batch_monitor.py --status
```

## 🔗 相关资源

- **GitHub项目**: https://github.com/chenxingqiang/medical-literature-annotation
- **快速开始**: 查看 `SETUP.md` 文件
- **详细文档**: 查看 `README.md` 文件
- **问题反馈**: 提交GitHub Issues

## 📞 获取帮助

如遇到问题：
1. 查看终端错误信息
2. 检查 `batch_monitor.py --status` 输出
3. 参考 `SETUP.md` 故障排除部分
4. 在GitHub提交Issue：https://github.com/chenxingqiang/medical-literature-annotation/issues

---

**🎉 系统已完全升级！支持安全配置、断点续传、多模型比较，开始您的智能标注之旅吧！** 