region:us
- [📏 1.信息抽取模板](#-1信息抽取模板)
- [2.常见的主题关系类型](#2常见的主题关系类型)
- [3.转换脚本](#3转换脚本)
- [4.使用](#4使用)
- [5.评估](#5评估)


# 📏 1.信息抽取模板
模版`template`用于构造输入模型的**指令**`instruction`, 由三部分组成:
1. **任务描述**：明确模型的职能及其需完成的任务，例如实体识别、关系抽取、事件抽取等。
2. **候选标签列表{s_schema}(可选)**：定义模型需要提取的标签类别，如实体类型、关系类型、事件类型等。
3. **结构化输出格式{s_format}**：指明模型应如何呈现其抽取的结构化信息。


指定候选标签列表的模版:
```
实体命名识别(NER): 你是专门进行实体抽取的专家。已知候选的实体类型列表：{s_schema}，请你根据实体类型列表，从以下输入中抽取出可能存在的实体，如果不存在某实体就输出NAN。请按照{s_format}的格式回答。

关系抽取(RE): 你在这里扮演关系三元组识别师的角色。我将给你个输入，请根据关系列表：{s_schema}，从输入中抽取出可能包含的关系三元组，，如果不存在某关系就输出NAN，并以{s_format}的形式回答。

事件抽取(EE): 你是专门进行事件提取的专家。已知候选的事件字典：{s_schema}，请你根据事件字典，从以下输入中抽取出可能存在的事件，如果不存在某事件就输出NAN。请按照{s_format}的格式回答。

事件类型抽取(EET): 作为事件分析专员，你需要查看输入并根据事件类型名录：{s_schema}，来确定可能发生的事件。所有回答都应该基于{s_format}格式。如果事件类型不匹配，请用NAN标记。

事件论元抽取(EEA): 你是专门进行事件论元提取的专家。已知事件字典：{s_schema1}，事件类型及触发词：{s_schema2}，请你从以下输入中抽取出可能存在的论元，如果不存在某事件论元就输出NAN。请按照{s_format}的格式回答。
```


<details>
  <summary><b>不指定候选标签列表的模版</b></summary>


  ```
  实体命名识别(NER): 分析文本内容，并提取明显的实体。将您的发现以{s_format}格式提出，跳过任何不明显或不确定的部分。

  关系抽取(RE): 请从文本中抽取出所有关系三元组，并根据{s_format}的格式呈现结果。忽略那些不符合标准关系模板的实体。

  事件抽取(EE): 请分析下文，从中抽取所有可识别的事件，并按照指定的格式{s_format}呈现。如果某些信息不构成事件，请简单跳过。

  事件类型抽取(EET): 审视下列文本内容，并抽取出任何你认为显著的事件。将你的发现整理成{s_format}格式提供。

  事件论元抽取(EEA): 请您根据事件类型及触发词{s_schema2}从以下输入中抽取可能的论元。请按照{s_format}的格式回答。
  ```

</details>



<details>
  <summary><b>候选标签列表{s_schema}</b></summary>


  ```json
    NER(CLUE): ["书名", "地址", "电影", "公司", "姓名", "组织机构", "职位", "游戏", "景点", "政府"] 
    RE(DuIE): ["创始人", "号", "注册资本", "出版社", "出品公司", "作词", "出生地", "连载网站", "祖籍", "制片人", "出生日期", "主演", "改编自", ...]
    EE(DuEE-fin): {"质押": ["披露时间", "质押物占总股比", "质押物所属公司", "质押股票/股份数量", "质押物", "质押方", "质押物占持股比", "质权方", "事件时间"], "股份回购": ["回购方", "回购完成时间", "披露时间", "每股交易价格", "交易金额", "回购股份数量", "占公司总股本比例"],  ...} 
    EET(DuEE): ["交往-感谢", "组织行为-开幕", "竞赛行为-退赛", "组织关系-加盟", "组织关系-辞/离职", "财经/交易-涨价", "人生-产子/女", "灾害/意外-起火", "组织关系-裁员", ...]
    EEA(DuEE-fin): {"质押": ["披露时间", "质押物占总股比", "质押物所属公司", "质押股票/股份数量", "质押物", "质押方", "质押物占持股比", "质权方", "事件时间"], "股份回购": ["回购方", "回购完成时间", "披露时间", "每股交易价格", "交易金额", "回购股份数量", "占公司总股本比例"], ...} 
  ```

</details>


<details>
  <summary><b>结构输出格式{s_format}</b></summary>


  ```
  实体命名识别(NER): (实体,实体类型) 

  关系抽取(RE): (头实体,关系,尾实体) 

  事件抽取(EE): (事件触发词,事件类型,事件论元1#论元角色1;事件论元2#论元角色2) 

  事件类型抽取(EET): (事件触发词,事件类型) 
  
  事件论元抽取(EEA): (Event Trigger,Event Type,Argument1#Argument Role1;Argument2#Argument Role2) 
  ```

</details>



这些模板中的schema({s_schema})和结构输出格式({s_format})占位符被嵌入在模板中，用户必须指定。
有关模板的更全面理解，请参阅配置目录[configs](https://github.com/zjunlp/DeepKE/tree/main/example/llm/InstructKGC/configs) 和 文件[ner_converter.py](https://github.com/zjunlp/DeepKE/blob/main/example/llm/InstructKGC/kg2instruction/convert/converter/ner_converter.py)、[re_converter.py](https://github.com/zjunlp/DeepKE/blob/main/example/llm/InstructKGC/kg2instruction/convert/converter/re_converter.py)、[ee_converter.py](https://github.com/zjunlp/DeepKE/blob/main/example/llm/InstructKGC/kg2instruction/convert/converter/ee_converter.py)、[eet_converter.py](https://github.com/zjunlp/DeepKE/blob/main/example/llm/InstructKGC/kg2instruction/convert/converter/eet_converter.py)、[eea_converter.py](https://github.com/zjunlp/DeepKE/blob/main/example/llm/InstructKGC/kg2instruction/convert/converter/eea_converter.py) .



# 2.常见的主题关系类型

```python
wiki_cate_schema_zh = {
    '人物': ['出生地点', '出生日期', '国籍', '职业', '作品', '成就', '籍贯', '职务', '配偶', '父母', '别名', '所属组织', '死亡日期', '兄弟姊妹', '墓地'], 
    '地理地区': ['位于', '别名', '人口', '行政中心', '面积', '成就', '长度', '宽度', '海拔'], 
    '建筑': ['位于', '别名', '成就', '事件', '创建时间', '宽度', '长度', '创建者', '高度', '面积', '名称由来'], 
    '作品': ['作者', '出版时间', '别名', '产地', '改编自', '演员', '出版商', '成就', '表演者', '导演', '制片人', '编剧', '曲目', '作曲者', '作词者', '制作商', '票房', '出版平台'], 
    '生物': ['分布', '父级分类单元', '长度', '主要食物来源', '别名', '学名', '重量', '宽度', '高度'], 
    '人造物件': ['别名', '品牌', '生产时间', '材料', '产地', '用途', '制造商', '发现者或发明者'], 
    '自然科学': ['别名', '性质', '组成', '生成物', '用途', '产地', '发现者或发明者'], 
    '组织': ['位于', '别名', '子组织', '成立时间', '产品', '成就', '成员', '创始人', '解散时间', '事件'], 
    '运输': ['位于', '创建时间', '线路', '开通时间', '途经', '面积', '别名', '长度', '宽度', '成就', '车站等级'], 
    '事件': ['参与者', '发生地点', '发生时间', '别名', '赞助者', '伤亡人数', '起因', '导致', '主办方', '所获奖项', '获胜者'], 
    '天文对象': ['别名', '属于', '发现或发明时间', '发现者或发明者', '名称由来', '绝对星等', '直径', '质量'], 
    '医学': ['症状', '别名', '发病部位', '可能后果', '病因']
}
```

此处 [schema](https://github.com/zjunlp/DeepKE/blob/main/example/llm/InstructKGC/kg2instruction/schema.py) 提供了12种文本主题, 以及该主题下常见的关系类型。




# 3.转换脚本

**训练数据转换**

在对模型进行数据输入之前，需要将**数据格式化**以包含`instruction`和`input`字段。为此，我们提供了一个脚本 [kg2instruction/convert.py](https://github.com/zjunlp/DeepKE/blob/main/example/llm/InstructKGC/kg2instruction/convert.py)，它可以将数据批量转换成模型可以直接使用的格式。

> 在使用 [kg2instruction/convert.py](https://github.com/zjunlp/DeepKE/blob/main/example/llm/InstructKGC/kg2instruction/convert.py) 脚本之前，请确保参考了 [data](https://github.com/zjunlp/DeepKE/blob/main/example/llm/InstructKGC/data) 目录。该目录详细说明了每种任务所需的数据格式要求。请参考 sample.json 以了解转换前数据的格式，schema.json 则展示了 schema 的组织结构，而 processed.json 则描述了转换后的数据格式。



```bash
python kg2instruction/convert.py \
  --src_path data/NER/sample.json \
  --tgt_path data/NER/processed.json \
  --schema_path data/NER/schema.json \
  --language zh \      # 不同语言使用的template及转换脚本不同
  --task NER \         # ['RE', 'NER', 'EE', 'EET', 'EEA'] 5种任务
  --sample -1 \        # 若为-1, 则从20种指令和4种输出格式中随机采样其中一种, 否则即为指定的指令格式, -1<=sample<20
  --neg_ratio 1 \      # 表示所有样本的负采样比例
  --neg_schema 1 \     # 表示从schema中负采样的比例
  --random_sort        # 是否对指令中的schema列表进行随机排序
```

**负采样**: 假设数据集 A 包含标签 [a，b，c，d，e，f]，对于某个给定的样本 s，它可能仅涉及标签 a 和 b。我们的目标是随机从候选关系列表中引入一些原本与 s 无关的关系，比如 c 和 d。然而，值得注意的是，在输出中，c 和 d 的标签要么不被输出，要么输出为`NAN`。


`schema_path`指定schema文件(json文件)路径, schema文件共包含3行json字符串, 以固定的格式组织schema信息。这里以NER任务为例, 每行的含义如下:

```
["书名", "地址", "电影", ...]    # 实体类型列表
[]    # 空列表
{}    # 空字典
```

<details>
  <summary><b>更多</b></summary>


```
对于关系抽取(RE)任务
[]                                 # 空列表
["创始人", "号", "注册资本",...]      # 关系类型列表
{}                                 # 空字典

对于事件抽取(EE)任务
["交往-感谢", "组织行为-开幕", "竞赛行为-退赛", ...]    # 事件类型列表
["解雇方", "解约方", "举报发起方", "被拘捕者"]          # 论元角色列表
{"组织关系-裁员": ["裁员方", "裁员人数", "时间"], "司法行为-起诉": ["原告", "被告", "时间"], ...}    # 事件类型字典

对于事件类型抽取(EET)任务
["交往-感谢", "组织行为-开幕", "竞赛行为-退赛", ...]    # 事件类型列表
[]    # 空列表
{}    # 空字典

对于事件论元抽取(EEA)任务
["交往-感谢", "组织行为-开幕", "竞赛行为-退赛", ...]    # 事件类型列表
["解雇方", "解约方", "举报发起方", "被拘捕者"]          # 论元角色列表
{"组织关系-裁员": ["裁员方", "裁员人数", "时间"], "司法行为-起诉": ["原告", "被告", "时间"], ...}    # 事件类型字典
```

</details>

更详细的schema文件信息可在[data](./data)目录下各个任务目录的`schema.json`文件中查看。



**测试数据转换**

对于**测试数据**，可以使用 [kg2instruction/convert_test.py](https://github.com/zjunlp/DeepKE/blob/main/example/llm/InstructKGC/kg2instruction/convert_test.py) 脚本，它不要求数据包含标签（`entity`、`relation`、`event`）字段，**只需**提供`input`字段和相应的`schema_path`。


```bash
python kg2instruction/convert_test.py \
    --src_path data/NER/sample.json \
    --tgt_path data/NER/processed.json \
    --schema_path data/NER/schema.json \
    --language zh \      
    --task NER \          
    --sample 0 
```

**数据转换实例**


以下是一个实体识别（NER）任务数据转换的示例：

```json
转换前：
{
    "input": "相比之下，青岛海牛队和广州松日队的雨中之战虽然也是0∶0，但乏善可陈。", 
    "entity": [{"entity": "广州松日队", "entity_type": "组织机构"}, {"entity": "青岛海牛队", "entity_type": "组织机构"}]
}

转换后：
{
    "id": "e88d2b42f8ca14af1b77474fcb18671ed3cacc0c75cf91f63375e966574bd187", 
    "instruction": "请在所给文本中找出并列举['组织机构', '人物', '地理位置']提及的实体类型，不存在的类型请注明为NAN。回答应按(实体,实体类型)\n格式进行。", 
    "input": "相比之下，青岛海牛队和广州松日队的雨中之战虽然也是0∶0，但乏善可陈。", 
    "output": "(青岛海牛队,组织机构)\n(广州松日队,组织机构)\nNAN\nNAN"
}
```


转换前: 数据的格式需要符合 `DeepKE/example/llm/InstructKGC/data` 目录下为各项任务(如NER、RE、EE等)规定的结构。以NER任务为例，输入文本应标记为`input`字段，而标注数据则应标记为`entity`字段，它是一个包含多个`entity`和`entity_type`键值对的字典列表。

转换后: 将得到包含`input`文本、`instruction`指令（详细说明了候选标签列表['组织机构', '人物', '地理位置']和期望的输出格式(实体,实体类型)），以及`output`（以(实体,实体类型)形式列出在`input`中识别到的所有实体信息）的结构化数据。



<details>
  <summary><b>更多</b></summary>

- 转换前
```json
关系抽取(RE): {
    "input": "如何演好自己的角色，请读《演员自我修养》《喜剧之王》周星驰崛起于穷困潦倒之中的独门秘笈", 
    "relation": [{"head": "喜剧之王", "relation": "主演", "tail": "周星驰"}]
}
事件抽取(EE): {
    "input": "消失的“外企光环”，5月份在华裁员900余人，香饽饽变“臭”了", 
    "event": [{"event_trigger": "裁员", "event_type": "组织关系-裁员", "arguments": [{"argument": "900余人", "role": "裁员人数"}, {"argument": "5月份", "role": "时间"}]}]
}
事件类型抽取(EET): {
    "input": "前两天，被称为 “ 仅次于苹果的软件服务商 ” 的 Oracle（ 甲骨文 ）公司突然宣布在中国裁员。。", 
    "event": [{"event_trigger": "裁员", "event_type": "组织关系-裁员", "arguments": [{"argument": "前两天", "role": "时间"}, {"argument": "被称为 “ 仅次于苹果的软件服务商 ” 的 Oracle（ 甲骨文 ）公司", "role": "裁员方"}]}]
}
事件论元抽取(EEA): {
    "input": "不仅仅是中国IT企业在裁员，为何500强的甲骨文也发生了全球裁员", 
    "event": [{"event_trigger": "裁员", "event_type": "组织关系-裁员", "arguments": [{"argument": "中国IT企业", "role": "裁员方"}]}, {"event_trigger": "裁员", "event_type": "组织关系-裁员", "arguments": [{"argument": "500强的甲骨文", "role": "裁员方"}]}]
}
```

- 转换后
```json
关系抽取(RE): {
    "id": "5526d8aa9520a0feaa045ae41d347cf7ca48bd84385743ed453ea57dbe743c7c", 
    "instruction": "你是专门进行关系三元组提取的专家。已知候选的关系列表：['丈夫', '出版社', '导演', '主演', '注册资本', '编剧', '人口数量', '成立日期', '作曲', '嘉宾', '海拔', '作词', '身高', '出品公司', '占地面积', '母亲']，请你根据关系列表，从以下输入中抽取出可能存在的头实体与尾实体，并给出对应的关系三元组，如果不存在某关系就输出NAN。请按照(头实体,关系,尾实体)\n的格式回答。", 
    "input": "如何演好自己的角色，请读《演员自我修养》《喜剧之王》周星驰崛起于穷困潦倒之中的独门秘笈", 
    "output": "NAN\nNAN\nNAN\n(喜剧之王,主演,周星驰)\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN"
}
事件抽取(EE): {
    "id": "f4dcda5576849c77df664c9318d136c36a663f11ad8af98e2794b113884fa69c", 
    "instruction": "你是专门进行事件提取的专家。已知候选的事件字典：{'人生-婚礼': ['时间', '参礼人员', '地点', '结婚双方'], '组织关系-停职': ['所属组织', '停职人员', '时间'], '交往-会见': ['时间', '会见主体', '地点', '会见对象'], '组织关系-解约': ['时间', '被解约方', '解约方'], '组织行为-开幕': ['时间', '地点', '活动名称'], '人生-求婚': ['时间', '求婚对象', '求婚者'], '人生-失联': ['失联者', '时间', '地点'], '产品行为-发布': ['时间', '发布方', '发布产品'], '灾害/意外-洪灾': ['时间', '受伤人数', '地点', '死亡人数'], '产品行为-上映': ['时间', '上映方', '上映影视'], '组织行为-罢工': ['所属组织', '罢工人数', '时间', '罢工人员'], '人生-怀孕': ['时间', '怀孕者'], '灾害/意外-起火': ['时间', '受伤人数', '地点', '死亡人数'], '灾害/意外-车祸': ['时间', '受伤人数', '地点', '死亡人数'], '司法行为-开庭': ['时间', '开庭法院', '开庭案件'], '交往-探班': ['探班主体', '时间', '探班对象'], '竞赛行为-退役': ['时间', '退役者'], '组织关系-裁员': ['时间', '裁员人数'], '财经/交易-出售/收购': ['时间', '收购方', '交易物', '出售价格', '出售方'], '组织关系-退出': ['退出方', '时间', '原所属组织'], '竞赛行为-禁赛': ['时间', '被禁赛人员', '禁赛机构', '禁赛时长']}，请你根据事件字典，从以下输入中抽取出可能存在的事件，如果不存在某事件就输出NAN。请按照(事件触发词,事件类型,事件论元1#论元角色1;事件论元2#论元角色2)\n的格式回答。", 
    "input": "消失的“外企光环”，5月份在华裁员900余人，香饽饽变“臭”了", 
    "output": "NAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\n(裁员,组织关系-裁员,时间#5月份;裁员人数#900余人)\nNAN\nNAN\nNAN"
}
事件类型抽取(EET): {
    "id": "17aae856c45d7c75f1850d358dc81268a2a9604dce3b98865b3896d0f37a49ef", 
    "instruction": "作为事件分析专员，你需要查看输入并根据事件类型名录：['人生-订婚', '灾害/意外-坍/垮塌', '财经/交易-涨价', '组织行为-游行', '组织关系-辞/离职', '交往-会见', '人生-结婚', '竞赛行为-禁赛', '组织关系-裁员', '灾害/意外-袭击', '司法行为-约谈', '人生-婚礼', '竞赛行为-退役', '人生-离婚', '灾害/意外-地震', '财经/交易-跌停', '产品行为-发布', '人生-求婚', '人生-怀孕', '组织关系-解约', '财经/交易-降价']，来确定可能发生的事件。所有回答都应该基于(事件触发词,事件类型)\n格式。如果事件类型不匹配，请用NAN标记。", 
    "input": "前两天，被称为 “ 仅次于苹果的软件服务商 ” 的 Oracle（ 甲骨文 ）公司突然宣布在中国裁员。。", 
    "output": "NAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\n(裁员,组织关系-裁员)\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN"
}
事件论元抽取(EEA): {
    "id": "5079d3cb44e94ca9b0749e687b1b19edc94b60fc2c1eb97b2154bbeb93ad3955", 
    "instruction": "你是专门进行事件论元提取的专家。已知事件字典：{'组织关系-裁员': ['裁员方']}，事件类型及触发词：[{'event_type': '组织关系-裁员', 'event_trigger': '裁员'}]，请你从以下输入中抽取出可能存在的论元，如果不存在某事件论元就输出NAN。请按照(事件触发词,事件类型,事件论元1#论元角色1;事件论元2#论元角色2)\n的格式回答。", 
    "input": "不仅仅是中国IT企业在裁员，为何500强的甲骨文也发生了全球裁员", 
    "output": "(裁员,组织关系-裁员,裁员方#中国IT企业)\n(裁员,组织关系-裁员,裁员方#500强的甲骨文)"
}
```

</details>




# 4.使用
我们提供了可直接使用 [KnowLM-13b-base-v1.0](https://huggingface.co/zjunlp/knowlm-13b-base-v1.0) 模型 + LoRA权重 [knowlm-13b-ie-lora](https://huggingface.co/zjunlp/knowlm-13b-ie-lora) 进行推理的脚本[inference.py](https://github.com/zjunlp/DeepKE/blob/main/example/llm/InstructKGC/src/inference.py), 请参考 [README.md](https://github.com/zjunlp/DeepKE/blob/main/example/llm/InstructKGC/README.md) 配置环境等。

```bash
CUDA_VISIBLE_DEVICES="0" python src/inference.py \
    --model_name_or_path 'zjunlp/knowlm-13b-base-v1.0' \
    --lora_weights 'zjunlp/knowlm-13b-ie-lora' \
    --model_name 'llama' \
    --input_file 'data/NER/processed.json' \
    --output_file 'results/ner_test.json' \
    --fp16 \
    --bits 4
```

如果GPU显存不足够, 可以采用 `--bits 8` 或 `--bits 4`

`KnowLM-13b-base-v1.0` + `knowlm-13b-ie-lora` 可以处理两种信息抽取情况: 1、在指令中指定了候选关系列表；2、未在指令中指定候选关系列表

1、在指令中指定了候选关系列表的一个例子:
```json
{
    "instruction": "你是专门进行关系三元组提取的专家。已知候选的关系列表：['事件', '位于', '创建时间', '创建者', '别名', '名称由来', '宽度', '成就', '长度', '面积', '高度']，请你根据关系列表，从以下输入中抽取出可能存在的头实体与尾实体，并给出对应的关系三元组，如果不存在某关系就输出NAN。请按照(头实体,关系,尾实体)\n的格式回答。",
    "input": "韦瓦克机场又叫博勒姆机场，是一座位于巴布亚新几内亚韦瓦克的机场。IATA代码：WWK；ICAO代码：AYWK。",
    "output": "NAN\n(韦瓦克机场,位于,韦瓦克)\n(韦瓦克,位于,巴布亚新几内亚)\nNAN\nNAN\n(韦瓦克机场,别名,博勒姆机场)\nNAN\nNAN\nNAN\nNAN\nNAN\nNAN"
}
```

2、未在指令中指定候选关系列表的一个例子:
```json
{
    "instruction": "请从文本中抽取出所有关系三元组，并根据(头实体,关系,尾实体)\n的格式呈现结果。忽略那些不符合标准关系模板的实体。",
    "input": "韦瓦克机场又叫博勒姆机场，是一座位于巴布亚新几内亚韦瓦克的机场。IATA代码：WWK；ICAO代码：AYWK。",
    "output": "(韦瓦克机场,别名,博勒姆机场)\n(韦瓦克机场,位于,韦瓦克)"
}
```



# 5.评估
我们提供一个位于 [evaluate.py](https://github.com/zjunlp/DeepKE/blob/main/example/llm/InstructKGC/kg2instruction/evaluate.py) 的脚本，用于将模型的字符串输出转换为列表并计算 F1 分数。

```bash
python kg2instruction/evaluate.py \
  --standard_path data/NER/processed.json \
  --submit_path data/NER/processed.json \
  --task NER \
  --language zh
```



