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秒，避免过度压力

安装依赖

pip install agno asyncio pydantic requests

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

ollama pull qwen3:4b

使用方法

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

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

2. 分步骤执行

步骤1：仅提取句子

python trex_to_sentences_simple.py --step extract --input_dir dataset/TREx --sentences_json my_sentences.json --max_files 2

步骤2：仅LLM处理

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服务：

   ps aux | grep ollama
   curl http://localhost:11434/api/tags
   

4. 重启ollama服务（如果需要）：

   pkill ollama
   ollama serve &
   

常见警告信息：

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

检查点恢复机制

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

示例工作流

# 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. 新增：所有处理过程都有详细日志记录，便于问题诊断