# 2IRC

**Repository Path**: cocoder1993/2irc

## Basic Information

- **Project Name**: 2IRC
- **Description**: 2i-relation-classfication
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-03-26
- **Last Updated**: 2025-08-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 2IRC: 基于多任务学习和数据增强的关系抽取方法研究

[![python 3.8](https://img.shields.io/badge/python-3.8-blue.svg)](https://gitee.com/cocoder1993/2irc#requirements)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://gitee.com/cocoder1993/2irc/blob/main/LICENSE)

[English](README.md) | 中文

本项目是论文《基于多任务学习和数据增强的关系抽取方法研究》的代码实现，包含两个独立的研究工作：

1. **InstructRE**: 基于多任务学习和指令微调的关系抽取框架
2. **TripleToText**: 面向关系抽取任务的数据增强技术

两个工作可以独立使用，也可以结合使用以获得更好的性能。


## 📋 目录

- [项目概述](#项目概述)
- [主要特性](#主要特性)
- [安装要求](#安装要求)
- [快速开始](#快速开始)
- [项目结构](#项目结构)
- [InstructRE 框架](#instructre-框架)
- [TripleToText 数据增强方法](#tripletotext-数据增强方法)
- [实验配置](#实验配置)
- [实验结果](#实验结果)
- [引用](#引用)
- [贡献](#贡献)
- [许可证](#许可证)

## 🎯 项目概述

本项目包含两个独立的研究工作，分别从不同角度提升关系抽取的性能：

### 工作一：InstructRE 框架
**基于多任务学习和指令微调的关系抽取框架**
- 通过多任务学习提升关系抽取性能
- 采用指令微调技术统一训练流程
- 支持多种辅助任务协同训练
- 采用SVO格式输出关系三元组（论文中效果最佳）
- 提供完整的训练和评估框架

### 工作二：TripleToText 方法
**面向关系抽取任务的数据增强技术**
- 将结构化三元组转换为自然语言文本
- 提供两种生成方式：微调本地语言模型和LLM API调用
- 结合规则增强和生成技术
- 自动化的数据质量评估机制
- 有效扩充训练数据集

## ✨ 主要特性

### InstructRE 框架特性
- 🔄 **多任务学习**: 支持关系抽取、实体识别、类型提取等多种任务
- 📝 **指令微调**: 基于自然语言指令的模型训练
- 🎯 **灵活配置**: 支持多种数据集和模型配置
- 📊 **统一评估**: 标准化的评估指标和流程
- 📋 **SVO格式**: 采用Subject-Verb-Object格式输出关系三元组（论文中效果最佳）

### TripleToText 方法特性
- 🤖 **双模式生成**: 支持微调本地语言模型和LLM API两种生成方式
- 📋 **规则增强**: 基于预定义规则的数据变换
- 🔄 **多样化策略**: 支持多种数据增强策略组合
- 📈 **质量保证**: 自动化的数据质量评估机制

## 🔧 安装要求

### 系统要求
- Python >= 3.8
- CUDA >= 11.0 (推荐用于 GPU 训练)
- 内存 >= 16GB (推荐)

### 依赖安装

```bash
# 基础依赖
pip install -r requirements/requirements.in

# 开发依赖
pip install -r requirements/requirements_dev.in

# 测试依赖
pip install -r requirements/requirements_test.in
```

### 主要依赖包
- `torch >= 2.0.1` - 
- `transformers >= 4.39.1`
- `accelerate >= 0.20.0`
- `datasets >= 2.14.0`
- `pandas >= 1.4.3`
- `numpy >= 1.21.0`

## 🚀 快速开始

### 1. 环境准备

```bash
# 安装依赖
pip install -r requirements/requirements.in

# 准备数据集（以 CONLL04 为例）
mkdir -p data/conll04
# 将数据集文件放入 data/conll04/ 目录

# 项目已包含完整的指令文件 instructions.json
# 注意：虽然代码支持多种输出格式，但论文中仅使用SVO格式
```

### 2. InstructRE 训练

```bash
# 使用训练脚本进行训练
./train_for_instruct_re.sh

# 或者手动配置训练参数
python train_hf3.py \
    --path_to_model_config="./configs/hf_config.yaml" \
    --dataset_name=conll04 \
    --answer_template=svo \
    --context_format=conditions \
    --training_num=-1 \
    --tasks="RE_STRICT" \
    --rules="origin"
```

### 3. TripleToText 数据增强

```bash
# 使用 TripleToText 进行数据增强
./train_for_3t.sh

# 或者手动配置参数
# 修改 train_for_3t.sh 中的配置：
# dataset_name=('conll04')
# few_shot_nums=(0)  # 0表示使用全部样本
# settings=("all 0")  # 使用GPT 3.5 API生成
# settings=("all 1")  # 使用微调本地模型生成
```

### 4. 模型评估

```bash
# 批量评估多个配置
./eval4hf.sh

# 或者单独评估特定模型
python evaluate_hf.py \
    --path_to_model_config="./configs/eval_hf_config.yaml" \
    --dataset_name=conll04 \
    --answer_template=svo \
    --training_num=-1
```

## 📁 项目结构

```
2irc/
├── instruction_re/           # InstructRE 框架核心代码
│   ├── core/                # 核心数据类型和读取器
│   │   ├── datatypes.py     # 数据类型定义
│   │   └── reader.py        # 数据读取器
│   ├── formatters/          # 数据格式化器
│   │   ├── instances/       # 实例格式化器
│   │   └── tasks/           # 任务格式化器
│   ├── models/              # 模型定义
│   │   └── CopyT5.py        # T5模型实现
│   ├── utils/               # 工具函数
│   │   ├── data_utils.py    # 数据处理工具
│   │   ├── train_utils.py   # 训练工具
│   │   ├── evaluate_utils.py # 评估工具
│   │   └── utils.py         # 通用工具
│   ├── train.py             # 基础训练脚本
│   ├── evaluate.py          # 基础评估脚本
│   ├── model.py             # 模型接口
│   ├── dataset.py           # 数据集类
│   ├── collator.py          # 数据整理器
│   ├── metrics.py           # 评估指标
│   ├── arg_parse.py         # 参数解析
│   └── setup.py             # 包配置
├── data_augmentation/       # TripleToText 数据增强相关代码
│   ├── generate_data.py     # 基于规则的数据增强
│   ├── generate_with_llm.py # 基于 LLM 的数据生成
│   ├── generate_with_llm_fulldata.py # 全量数据LLM生成
│   ├── generate_triples_json.py # 三元组生成
│   └── data_aug_arg_parse.py # 数据增强参数解析
├── configs/                 # 配置文件
│   ├── hf_config.yaml       # HuggingFace 训练配置
│   ├── da_config.yaml       # 数据增强配置
│   ├── eval_hf_config.yaml  # 评估配置
│   └── *.yaml               # 其他实验配置
├── instructions.json        # InstructRE 指令文件
├── requirements/            # 依赖管理
│   ├── requirements.in      # 基础依赖
│   ├── requirements_dev.in  # 开发依赖
│   └── requirements_test.in # 测试依赖
├── train_for_instruct_re.sh # InstructRE 训练脚本
├── train_for_3t.sh          # TripleToText 训练脚本
├── train_hf.py              # HuggingFace 训练脚本
├── train_hf2.py             # 扩展训练脚本
├── train_hf3.py             # 最新训练脚本
├── evaluate_hf.py           # HuggingFace 评估脚本
├── eval4hf.sh               # 批量评估脚本
├── data/                    # 数据集目录
├── output/                  # 输出目录
└── resources/               # 资源文件（图片等）
```

## 🧠 InstructRE 框架

### 核心概念

InstructRE 是一个基于指令微调的关系抽取框架，通过多任务学习来提升模型性能。该框架将关系抽取任务分解为多个子任务，通过联合训练来提升整体性能。

![InstructRE 框架架构](resources/InstructRE.png)

#### 设计理念
- **指令驱动**: 通过自然语言指令指导模型执行特定任务
- **多任务协同**: 多个相关任务协同训练，共享知识表示
- **统一框架**: 统一的训练和推理框架，简化模型部署

#### 辅助任务类型
- **RC (Relation Classification)**: 关系分类
- **TE (Type Extraction)**: 类型提取
- **NER (Named Entity Recognition)**: 命名实体识别
- **EPE (Entity Pair Extraction)**: 实体对提取

#### 模型架构
- 基础模型: T5/Flan-T5
- 训练方式: 序列到序列生成
- 输出格式: SVO格式（Subject-Verb-Object）的关系三元组

### 训练脚本

项目提供了灵活的训练脚本 `train_for_instruct_re.sh`，支持配置不同的数据集、辅助任务组合和数据增强策略。

#### 脚本配置参数

```bash
# 数据集配置
dataset_name=('semval-RE')  # 支持: conll04, semval-RE, SciERC, MIT Movie/Restaurant

# 辅助任务配置
valid_tasks=('RE_STRICT')   # 主任务: RE_STRICT 或 RE
help_tasks=('NER' 'RC_NO_ICL' 'TE' 'EPE')  # 可选辅助任务

# 训练参数
seed=100                    # 随机种子
few_shot_num=50            # 少样本数量
training_num=(-1)          # 训练样本数量，-1表示全量数据

# 数据增强配置
aug_rules='origin'         # 数据增强规则: origin, add_triple, remove_triple等

# 输出格式配置
all_answer_types=('svo')   # 答案模板: 仅使用SVO格式（论文中效果最佳）
context_format='conditions' # 上下文格式
```

#### 使用示例

```bash
# 1. 基础训练（仅主任务）
./train_for_instruct_re.sh

# 2. 多任务训练（主任务 + 辅助任务）
# 修改脚本中的 all_combinations 数组
all_combinations=("NER TE" "EPE" "NER RC_NO_ICL TE")

# 3. 不同数据集训练
# 修改 dataset_name 数组
dataset_name=('conll04' 'semval-RE' 'SciERC')

# 4. 数据增强训练
# 修改 aug_rules 参数
aug_rules='add_triple origin remove_triple replace_same_type_entity'
```

#### 训练任务组合

脚本支持灵活的任务组合配置：

```bash
# 示例1: 仅关系抽取
all_combinations=("")

# 示例2: 关系抽取 + 实体识别
all_combinations=("NER")

# 示例3: 关系抽取 + 实体识别 + 类型提取
all_combinations=("NER TE")

# 示例4: 完整多任务学习
all_combinations=("NER RC_NO_ICL TE EPE")
```

### 评估脚本

项目提供了专门的评估脚本 `evaluate_hf.py` 和批量评估脚本 `eval4hf.sh`。

#### 单模型评估

```bash
# 使用 evaluate_hf.py 评估单个模型
python evaluate_hf.py \
    --path_to_model_config="./configs/eval_hf_config.yaml" \
    --dataset_name=conll04 \
    --answer_template=svo \
    --training_num=-1
```

#### 批量评估

```bash
# 使用 eval4hf.sh 批量评估多个配置
./eval4hf.sh
```

#### 评估脚本配置

```bash
# eval4hf.sh 配置示例
dataset_name='conll04'
all_answer_types=('svo')                      # 仅使用SVO格式（论文中效果最佳）
traing_num=(10 20 30 50)                      # 不同训练样本数量
```

#### 评估指标

评估脚本会输出以下指标：

- **关系抽取指标**: 精确率、召回率、F1分数
- **实体识别指标**: 实体级别的精确率、召回率、F1分数
- **详细分类报告**: 每个关系类型的性能表现

### 使用方法

#### 1. 配置训练参数

```yaml
# configs/hf_config.yaml
model:
  model_name: "google/flan-t5-base"
  
training_args:
  num_train_epochs: 10
  per_device_train_batch_size: 16
  learning_rate: 0.00005
  evaluation_strategy: "steps"
  eval_steps: 100
```

#### 2. 指令文件

项目已包含完整的指令文件 `instructions.json`，支持多种任务类型：

```json
{
  "RE": "Please extract the subject, object and the relation between them from the Sentence.",
  "RC": "Please type the relation between given entities based on the Sentence and the knowledge in Examples.",
  "RC_NO_ICL": "Please type the relation between given entities based on the Sentence.",
  "TE": "Please extract all relation types from the Sentence.",
  "NER": "Please extract entities and their types from ths Sentence.",
  "RE_STRICT": "Please extract all entities and their types from the Sentence, then extract the subject, object and the relation between them.",
  "DA": "Generate a natural language sentence that expresses the following relation triple:"
}
```

#### 3. 执行训练和评估

```bash
# 训练模型
./train_for_instruct_re.sh

# 评估模型
./eval4hf.sh
```

### 核心文件说明

#### InstructRE框架核心文件
- **`train.py`**: 基础训练脚本
  - 支持多任务学习训练
  - 集成TensorBoard日志记录
  - 支持分布式训练

- **`model.py`**: 模型接口定义
  - 统一的模型预测接口
  - 支持T5/Flan-T5模型
  - 提供格式化输出功能

- **`dataset.py`**: 数据集类
  - 支持多种任务类型的数据加载
  - 动态任务组合
  - 指令模板集成

- **`utils/`**: 工具函数集合
  - `train_utils.py`: 训练循环和优化器管理
  - `evaluate_utils.py`: 评估指标计算和结果解析
  - `data_utils.py`: 数据处理和配置管理
  - `utils.py`: 通用工具函数

- **`formatters/`**: 数据格式化器
  - 支持多种输出格式：SVO、三元组、模板（代码层面）
  - 论文中仅使用SVO格式（效果最佳）
  - 任务特定的格式化器
  - 灵活的指令模板系统

- **`instructions.json`**: 指令文件
  - 包含所有任务类型的自然语言指令
  - 支持RE、RC、TE、NER、EPE等多种任务
  - 提供中英文指令模板

## 🔄 TripleToText 数据增强方法

### 核心概念

TripleToText 是一个面向关系抽取任务的数据增强方法，通过将结构化三元组转换为自然语言文本来生成高质量的训练数据。该方法提供了两种实现方式：微调本地语言模型和调用GPT 3.5 API。

![TripleToText 框架架构](resources/TripleToText.png)

#### 核心思想
- **三元组到文本转换**: 将结构化的关系三元组转换为自然语言句子
- **多样化生成**: 通过多种策略生成语义相同但表达不同的句子
- **质量保证**: 自动化的数据质量评估和过滤机制

### 实现方式

#### 1. 微调本地语言模型
- **模型选择**: 使用T5/Flan-T5等预训练模型进行微调
- **训练数据**: 基于原始三元组数据构建训练样本
- **优势**: 无需API调用，可离线使用，成本较低

#### 2. 调用GPT 3.5 API
- **API调用**: 直接使用OpenAI GPT 3.5 API生成文本
- **提示工程**: 设计专门的提示模板指导生成
- **优势**: 生成质量高，无需本地训练

### 增强规则

TripleToText 支持多种数据增强规则：

- **add_triple**: 添加新的三元组
- **remove_triple**: 删除现有三元组
- **replace_same_type_entity**: 同类型实体替换
- **swap_triple**: 三元组位置交换
- **origin**: 保持原始数据不变

### 训练脚本

项目提供了专门的训练脚本 `train_for_3t.sh`，支持灵活配置数据增强参数。

#### 脚本配置参数

```bash
# 数据集配置
dataset_name=('SciERC')  # 支持: conll04, SciERC, semval-RE

# 少样本配置
few_shot_nums=(0)        # 0表示使用全部样本，其他数值表示少样本数量
# few_shot_nums=(50 100 150)  # 可以设置多个样本数量

# 增强规则配置
settings=(
    "empty 0"    # 空规则，使用GPT生成
    "origin 0"   # 原始规则，使用GPT生成
    "all 0"      # 所有规则，使用GPT生成
    "all 1"      # 所有规则，使用微调模型生成
)

# 其他参数
seeds=(100)              # 随机种子
AUG_TIMES=(1)           # 增强次数
```

#### 配置说明

- **第一个参数**: 增强规则类型
  - `empty`: 无增强规则
  - `origin`: 仅使用原始数据
  - `all`: 使用所有增强规则
- **第二个参数**: 生成方式
  - `0`: 使用GPT 3.5 API生成
  - `1`: 使用微调本地模型生成

#### 使用示例

```bash
# 基础使用
./train_for_3t.sh

# 修改配置进行不同实验
# 1. 使用GPT生成，不同样本数量
few_shot_nums=(50 100 150)
settings=("all 0")

# 2. 使用微调模型生成
settings=("all 1")

# 3. 不同数据集实验
dataset_name=('conll04' 'SciERC' 'semval-RE')
```

### 使用方法

#### 1. 配置训练参数

```bash
# 修改 train_for_3t.sh 中的配置
dataset_name=('conll04')
few_shot_nums=(0)
settings=("all 0")  # 使用GPT生成
```

#### 2. 执行数据增强

```bash
# 运行训练脚本
./train_for_3t.sh
```

#### 3. 查看生成结果

脚本会自动生成增强后的数据，并保存在相应的输出目录中。

### 核心文件说明

#### 数据增强核心文件
- **`generate_data.py`**: 基于规则的数据增强实现
  - 支持多种增强规则：add_triple, remove_triple, replace_same_type_entity, swap_triple
  - 使用T5/Flan-T5模型进行文本生成
  - 支持分布式训练

- **`generate_with_llm.py`**: 基于LLM的数据生成实现
  - 使用LangChain框架集成OpenAI GPT-3.5
  - 支持自定义提示模板
  - 提供批量生成和单样本生成功能

- **`generate_triples_json.py`**: 三元组数据处理
  - 从原始数据中提取三元组信息
  - 支持多种数据格式转换
  - 提供数据质量检查和过滤

- **`generate_with_llm_fulldata.py`**: 全量数据LLM生成
  - 针对大规模数据集的优化版本
  - 支持断点续传和错误恢复
  - 提供更详细的生成日志

## ⚙️ 实验配置

### 数据集配置

项目支持多个标准关系抽取数据集：

- **CONLL04**: 新闻领域关系抽取
- **SciERC**: 科学文献关系抽取
- **SemEval**: 语义评估关系抽取
- **MIT Movie/Restaurant**: 特定领域关系抽取

### 训练脚本配置

#### 基础配置参数

```bash
# train_for_instruct_re.sh 主要配置
dataset_name=('conll04')           # 数据集名称
valid_tasks=('RE_STRICT')          # 主任务类型
help_tasks=('NER' 'TE' 'EPE')      # 辅助任务类型
seed=100                           # 随机种子
few_shot_num=50                    # 少样本数量
training_num=(-1)                  # 训练样本数量
aug_rules='origin'                 # 数据增强规则
all_answer_types=('svo')           # 答案模板格式
context_format='conditions'        # 上下文格式
```

#### 任务组合配置

```bash
# 不同实验设置的任务组合
# 基线实验
all_combinations=("")

# 多任务学习实验
all_combinations=("NER TE" "EPE" "NER RC_NO_ICL TE")

# 消融实验
all_combinations=("NER" "TE" "EPE" "NER TE" "TE EPE")
```

### 模型配置

```yaml
# 基础模型配置
model:
  model_name: "google/flan-t5-base"  # 或 "t5-base", "t5-large"
  max_length: 512
  truncation: true

# 训练配置
training_args:
  num_train_epochs: 10
  per_device_train_batch_size: 16
  learning_rate: 0.00005
  weight_decay: 0.01
  warmup_steps: 500
```

### TripleToText 配置

```bash
# TripleToText 训练脚本配置
# train_for_3t.sh 主要配置

# 数据集配置
dataset_name=('SciERC')  # 支持: conll04, SciERC, semval-RE

# 少样本配置
few_shot_nums=(0)        # 0表示使用全部样本，其他数值表示少样本数量

# 增强规则配置
settings=(
    "empty 0"    # 空规则，使用GPT生成
    "origin 0"   # 原始规则，使用GPT生成
    "all 0"      # 所有规则，使用GPT生成
    "all 1"      # 所有规则，使用微调模型生成
)

# 其他参数
seeds=(100)              # 随机种子
AUG_TIMES=(1)           # 增强次数
```

### 数据增强配置

```yaml
# 数据增强配置
augmentation:
  rules: ["add_triple", "remove_triple", "replace_same_type_entity", "swap_triple"]
  ratio: 0.5
  quality_threshold: 0.8
  max_generated_samples: 1000
```

### 评估配置

```bash
# eval4hf.sh 评估配置
dataset_name='conll04'
all_answer_types=('svo')                      # 仅使用SVO格式（论文中效果最佳）
traing_num=(10 20 30 50 100 -1)  # 不同训练样本数量
```

## 📊 实验结果

### InstructRE 框架实验结果

InstructRE 框架通过多任务学习和指令微调技术，在多个标准数据集上取得了显著的性能提升。

#### 主要性能指标

![InstructRE 主要实验结果](resources/instruct_re_main_result.png)

#### 多任务学习效果

![多任务学习实验结果](resources/task_result.png)

#### 消融实验结果

![消融实验结果](resources/st_result.png)

![详细实验结果](resources/st_result_2.png)

### TripleToText 方法实验结果

TripleToText 方法通过数据增强技术，有效扩充了训练数据集，提升了模型在少样本场景下的性能。

#### 数据增强效果

![TripleToText 实验结果](resources/t2t_results.png)

## 📚 引用

如果您在研究中使用了本项目，请引用我们的论文：

```bibtex
@article{wang_instrcutre,
  title={基于多任务学习和数据增强的关系抽取方法研究},
  author={王晓丽},
  year={2024},
}
```

### 相关论文

本项目参考了以下相关工作：

```bibtex
@article{wang2022instructionner,
  title={Instructionner: A multi-task instruction-based generative framework for few-shot ner},
  author={Wang, Liwen and Li, Rumei and Yan, Yang and Yan, Yuanmeng and Wang, Sirui and Wu, Wei and Xu, Weiran},
  journal={arXiv preprint arXiv:2203.03903},
  year={2022}
}

@article{chung2022scaling,
  title={Scaling instruction-finetuned language models},
  author={Chung, Hyung Won and Hou, Le and Longpre, Shayne and Zoph, Barret and Tay, Yi and Fedus, William and Li, Eric and Wang, Xuezhi and Dehghani, Mostafa and Brahma, Siddhartha and others},
  journal={arXiv preprint arXiv:2210.11416},
  year={2022}
}
```

## 🤝 贡献

我们欢迎社区贡献！请遵循以下步骤：

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 贡献指南

- 请确保代码符合 PEP 8 规范
- 添加适当的测试用例
- 更新相关文档
- 遵循项目的代码风格

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 联系方式

- 项目主页: [Gitee Repository](https://gitee.com/cocoder1993/2irc)
- 问题反馈: [Issues](https://gitee.com/cocoder1993/2irc/issues)

## 🙏 致谢

感谢以下开源项目和数据集：

- [Hugging Face Transformers](https://github.com/huggingface/transformers)
- [InstructionNER](https://github.com/ovbystrova/InstructionNER)
- [CONLL04 Dataset](https://cogcomp.seas.upenn.edu/page/resource_view/84)
- [SciERC Dataset](https://github.com/yuhaozhang/scierc)