Minimind/preprocessing/README_trex_processor.md

# TREx 数据集处理工具使用说明

这个工具支持两步骤处理 TREx 数据集：
1. **句子提取**：从 TREx 数据集提取三元组并转换为自然语言句子
2. **LLM 处理**：使用 ollama qwen3:4b 模型进行句子修正和重要性评分

## 🆕 防卡死机制

为了解决LLM处理时可能出现的卡死问题，新增了以下功能：

### 超时和重试机制
- **超时时间**：每个LLM请求60秒超时
- **重试机制**：失败后最多重试2次，采用指数退避策略
- **并发控制**：降低并发数至4个，减少服务器压力

### 心跳监控系统
- **实时监控**：每30秒检查一次LLM响应状态
- **异常警告**：超过30秒无成功响应时发出警告
- **服务检测**：自动检查ollama服务状态
- **详细统计**：实时显示成功率、超时率等统计信息

### 日志系统
- **详细日志**：所有操作都记录在 `logs/` 目录下
- **双重输出**：同时输出到日志文件和控制台
- **时间戳标记**：日志文件包含启动时间戳

### 改进的错误处理
- **异常恢复**：LLM处理失败时使用原句子和默认评分
- **状态监控**：处理前检查ollama服务状态
- **批次间休息**：批次之间休息5秒，避免过度压力

## 安装依赖

```bash
pip install agno asyncio pydantic requests
```

确保已安装并启动 ollama，并下载 qwen3:4b 模型：
```bash
ollama pull qwen3:4b
```

## 使用方法

### 1. 完整流程（两步骤连续执行）

```bash
python trex_to_sentences_simple.py --step all --input_dir dataset/TREx --max_files 2
```

### 2. 分步骤执行

#### 步骤1：仅提取句子
```bash
python trex_to_sentences_simple.py --step extract --input_dir dataset/TREx --sentences_json my_sentences.json --max_files 2
```

#### 步骤2：仅LLM处理
```bash
python trex_to_sentences_simple.py --step llm --sentences_json my_sentences.json --output_file final_output.txt
```

## 主要参数说明

- `--step`: 运行步骤
  - `extract`: 仅提取句子
  - `llm`: 仅LLM处理  
  - `all`: 完整流程（默认）

- `--input_dir`: TREx数据集目录（默认：`dataset/TREx`）
- `--sentences_json`: 提取的句子JSON文件（默认：`extracted_sentences.json`）
- `--output_file`: 最终输出文件（默认：`trex_sentences_enhanced.txt`）
- `--max_files`: 最大处理文件数（用于测试）
- `--no_llm`: 禁用LLM处理

## 输出文件

**注意：所有输出文件都会自动保存在相应目录中**

### 句子提取输出
- `output/extracted_sentences.json`: 提取的原始句子，包含元数据

### LLM处理输出  
- `output/{output_file}.txt`: 修正后的句子文本文件
- `output/{output_file}.json`: 完整的处理结果（包含原句、修正句、评分）
- `output/{output_file}_sorted_by_importance.txt`: 按重要性评分排序的句子

### 检查点文件
- `output/{output_file}_checkpoint_{数量}.json`: 每1000条句子自动保存的检查点

### 日志文件
- `logs/trex_processor_{时间戳}.log`: 详细的处理日志

## 🆕 故障诊断

### 如果遇到卡死问题：

1. **检查日志文件**：查看 `logs/` 目录下的最新日志
2. **观察心跳监控**：注意控制台的心跳警告信息
3. **检查ollama服务**：
   ```bash
   ps aux | grep ollama
   curl http://localhost:11434/api/tags
   ```
4. **重启ollama服务**（如果需要）：
   ```bash
   pkill ollama
   ollama serve &
   ```

### 常见警告信息：

- `⚠️ 心跳检测`: 30秒无成功响应（正常情况下会自动恢复）
- `❌ 严重警告`: 90秒无成功响应（可能需要检查服务）
- `💀 Ollama服务异常`: ollama服务可能已停止
- `💀 致命错误`: 连续多次警告（建议重启程序）

## 检查点恢复机制

- 步骤2会自动检测已有的检查点文件（在 `output/` 目录中）
- 只处理尚未处理的句子，避免重复工作
- 如果所有句子都已处理，会直接生成最终输出文件
- 中断后重新运行会自动从最新检查点继续

## 示例工作流

```bash
# 1. 先提取句子（可以快速完成）
python trex_to_sentences_simple.py --step extract --max_files 5

# 2. 后续进行LLM处理（耗时较长，支持断点续传）
python trex_to_sentences_simple.py --step llm

# 如果中途中断，再次运行步骤2会自动从检查点恢复
python trex_to_sentences_simple.py --step llm
```

## 性能特点

- **保守的并发**: 最大4个并发LLM请求（降低卡死风险）
- **检查点保存**: 每1000条句子自动保存，支持断点续传
- **智能监控**: 详细的处理进度和时间预估
- **健壮的错误处理**: LLM请求失败时使用原句子和默认评分
- **服务监控**: 自动检测ollama服务状态

## 注意事项

1. 首次运行步骤2前，必须先完成步骤1
2. 检查点文件会占用额外磁盘空间（每个都包含所有已处理数据）  
3. LLM处理速度取决于模型性能和网络状况
4. 建议先用`--max_files`参数测试小批量数据
5. **新增**：如果遇到卡死，查看日志文件和心跳监控信息
6. **新增**：程序会自动检测并报告ollama服务状态
7. **新增**：所有处理过程都有详细日志记录，便于问题诊断