简介：一款基于 Python3 的本地化知识图谱标注工具源码，面向知识图谱构建、NLP 工程与算法研究人员，用于解决文本中命名实体和关系的高效联合标注问题。工具通过自定义快捷键和背景色区分实体与关系类型，支持撤销、取消标注及文本格式化，可导入文本文件、自定义实体与关系模板，并将标注结果导出为五元组 CSV 等下游任务数据，便于衔接知识图谱构建或机器学习训练。压缩包为 zip 格式，共 7 个文件，包含 2 个 Python 主程序、实体与关系配置文件、requirements.txt 依赖清单及项目配置，整体仅 7KB，结构精简，适合快速部署和二次开发。目前已有 65 人学习下载。读者可从源码中直接查看核心标注交互逻辑、配置加载方式、颜色模块与标注文件解析思路，获得一套可运行的本地标注工具基础实现；对需要搭建轻量标注环境、评估标注工具实现方案或在此基础上扩展一键标注与网页部署功能的开发者，是一份具备直接参考价值的源码包。

1. 知识图谱标注工具源码包：与其自己写爬虫攒三元组，不如先把标注这件事做对

做过实体识别和关系抽取的人都有同感：模型调参是玄学，但数据标注是体力活。市面上现成的标注平台要么太贵，要么绑死云端，要么标签体系改不动。这份知识图谱标注工具源码包，解决的就是“私有化部署 + 自定义标签体系 + 离线标注”这件事。它不依赖外部标注平台，前端标注界面可以直接在浏览器里跑，后端提供实体识别、关系标注、属性填充的完整流程。适合这类人：需要构建特定领域知识图谱的开发者、在做信息抽取但被数据标注卡住的团队、想给客户交付一套可二次开发的标注系统的软件工程师。我第一次拿到这套源码时的感受是：功能不多不少，但工程结构很诚实，该有的都有了。

2. 标注体系设计：实体、关系、属性三要素决定标注效率

知识图谱标注和图像框选标注完全是两回事。图像标注只需要拉一个框写上类别，知识图谱标注要求在文本或表格数据里同时完成实体边界、关系方向、属性键值这三类操作。这套源码把这套体系拆分成了可配置的schema驱动结构，改配置就能切换领域，不需要改动页面代码。

2.1 数据模型：SPO三元组标注的底层结构

知识图谱的底层表达是SPO三元组，也就是Subject（主语）、Predicate（谓语）、Object（宾语）。这套标注工具的数据模型围绕这个结构设计，每完成一次标注就生产一个SPO实例。在源码里，标注记录的存储结构大致是这样一个JSON形态：

{ "id": "anno_1024", "text": "某公司成立于2005年，总部位于某市高新区。", "spo_list": [ { "subject": { "text": "某公司", "entity_type": "ORG", "offset": [0, 3] }, "predicate": "成立时间", "object": { "text": "2005年", "entity_type": "DATE", "offset": [5, 10] } } ] }

这段结构里最关键的是offset字段，它记录了实体在原文中的起止位置，标注工具导出的结果下游模型可以直接消费。源码里对这部分的处理逻辑是：前端根据用户鼠标框选的文字动态计算offset，后端负责校验重复标注和实体类型冲突。还有一个容易被忽视的设计——谓词（predicate）没有绑定在固定的实体类型上，而是通过schema配置来约束，比如"成立时间"这个谓词只允许ORG类型作为主语，这样能减少无效标注。

2.2 Schema配置：如何用一份JSON换一套标签体系

这套工具的核心扩展点是schema.json，它定义了整套标注任务的标签规则。换领域只需要改这个文件，不需要动前端组件。文件结构大概是：

{ "entity_types": [ {"id": "ORG", "name": "组织机构", "color": "#2E86AB"}, {"id": "PERSON", "name": "人物", "color": "#A23B72"}, {"id": "DATE", "name": "日期", "color": "#F18F01"} ], "relation_types": [ { "id": "found_time", "name": "成立时间", "subject_type": ["ORG"], "object_type": ["DATE"] }, { "id": "headquarter", "name": "总部位于", "subject_type": ["ORG"], "object_type": ["LOC"] } ], "attributes": { "ORG": ["简称", "全称", "别称"], "PERSON": ["职位", "国籍"] } }

schema里同时定义了实体类型、关系类型和属性字段，关系还做了subject类型和object类型的约束。标注界面的下拉框、实体高亮颜色、关系连线语义全部由这份JSON驱动。字段比较多，看的时候留意几个关键参数：subject_type表示该关系允许哪些实体类型作为主语，object_type表示宾语类型，attributes是附加的实体元数据标注项。在实际使用时，建议把与领域无关的关系（如"相关"这种泛化谓词）全部从schema里删掉，会让标注一致性提升一个档次。

3. 前端标注器与后端工程：源码包怎么在本地跑起来

拿到源码包之后第一步是把它跑起来。这套项目采用的是前后端分离结构，前端是标注工作台，后端是数据服务和导出接口。

3.1 环境准备与项目目录结构解读

先看一下源码包的目录组织方式，这决定了后续改哪里。典型的结构是按功能分模块的：

annotation-tool/ # 源码包根目录

├── frontend/ │ ├── src/ │ │ ├── components/ │ │ ├── pages/ │ │ ├── store/ │ │ └── main.js │ └── package.json ├── backend/ │ ├── app.py │ ├── models/ │ ├── services/ │ └── utils/ ├── configs/ │ └── schema.json └── README.md

后端看起来是基于Python的Flask框架写的，app.py是入口文件，models目录处理数据持久化，services目录放业务逻辑，utils目录放导入导出工具。前端用的是Vue单页应用方案，main.js是前端入口，components目录是标注面板相关的组件。 这种目录结构对二次开发很友好——改前端配色和标注交互就去frontend/src/components，改数据导出格式就去backend/services，换领域标签只动configs/schema.json。如果对Flask不熟，也不用怕，后端逻辑很薄，主要是几个HTTP接口和本地文件读写，核心标注态都在前端维护。 ### 3.2 启动步骤：后端起服务、前端起开发服务器 启动流程不复杂，本地跑起来只需要两个终端窗口。先启动后端： ```bash cd annotation-tool/backend pip install -r requirements.txt python app.py --host 127.0.0.1 --port 5001

requirements.txt里锁定了依赖版本。启动成功后终端会输出监听地址，看到Running on http://127.0.0.1:5001就说明后端就绪。这里host地址和port参数值得说明一下：host设成127.0.0.1只允许本机访问，如果要部署到局域网让团队多人标注，就要改成0.0.0.0；port默认5001是为了避开Flask开发服务器常见的5000端口占用问题，如果被占用可以改成5002或6001。

再启动前端开发服务器：

cd annotation-tool/frontend npm install npm run serve

npm install会把Vue及其依赖装到node_modules目录。npm run serve起来之后默认监听8080端口，浏览器访问http://localhost:8080，就能看到标注工作台的登录页。如果要连接后端接口，前端代码里有一处环境变量需要确认：

// frontend/src/api/http.js const BASE_URL = process.env.VUE_APP_API_BASE || 'http://127.0.0.1:5001/api'; export default BASE_URL;

这里环境变量VUE_APP_API_BASE如果没配置，默认指向本地5001端口。如果你修改了后端端口，这里要对齐，否则前端调用接口会全部404。

3.3 核心标注流程：从打开文本到产出三元组

标注器的主界面通常分成三块：左侧是文本列表，中间是待标注文本区，右侧是标注操作面板。一个完整的标注操作流程是：

1. 在左侧列表选择一条待标注文本，中间区域会显示原文。
2. 用鼠标在文本区选中一个词或短语，系统自动弹出实体类型选择浮层。
3. 选择实体类型（比如ORG、PERSON、DATE），选中的文字会以对应颜色的高亮显示。
4. 点击已标注的实体，再点击右侧面板的"添加关系"按钮，进入关系标注模式。
5. 选择另一个实体作为宾语，再从关系下拉框里选谓词，即可生成一组SPO。
6. 如需给实体补充属性，选中实体后右侧面板的"属性块"会展示schema里约定的属性字段。

整个流程的设计意图是让标注者把注意力集中在文本理解上，而不是维护标签ID表。源码里对实体去重做了处理，同一段文字被重复标注时后端会返回冲突提示，标注者可以选择复用已有实体或强制新建。关系标注那块还有一个细节：不同类型的实体在右侧面板会有不同的待选谓词列表，这是前端根据schema.json里的subject_type和object_type动态过滤的结果，有效避免了标出"产品->成立时间"这种不合逻辑的关系。

说一下回退机制。标注过程中不可避免会标错，工具提供了单步撤销和历史记录两种方式，Ctrl+Z撤销上一步操作，历史记录面板可以回到任意历史节点。这套实现用的是前端状态快照栈，每一次标注操作都会压栈一份当前文本的全部标注状态，所以撤销的代价很小。

4. 避坑清单：标注工具项目五个最常见的翻车现场

这套源码整体质量不错，但不代表没有坑。以下五条是我实际使用或审查类似项目时遇到的高频问题，每一条都对应了具体场景，有一条算一条。

4.1 offset计算错位：标注结果错一个字全盘皆输

现象：从标注工具导出的实体offset与实际文本位置对不上，模型训练时实体错位，F1直接崩到个位数。

原因：前端计算offset用的是JavaScript的字符串索引，但浏览器对中文和emoji的处理并不一致。中文按UTF-16码元计算索引时，生僻字和特殊符号会占两个码元位置，导致偏差。

解决：在后端引入字节级对齐校验，前端提交标注记录时，后端重新从原文中截取offset对应的文本片段，与标注的实体文本做比对。这个工具源码里已经有类似的validate_offsets函数，建议不要跳过后端的校验逻辑直接入库：

# backend/services/validator.py def validate_offsets(text, entity_text, start, end): # 按码点取原文片段，而不是按字节索引 sliced = text[start:end] if sliced != entity_text: # 自动尝试前后偏移修正 for delta in (-1, 1, -2, 2): if text[start+delta:end+delta] == entity_text: return start+delta, end+delta return None return start, end

这个修正逻辑是逐级尝试前后偏移量，能覆盖大多数由码元差异导致的错位问题。如果传回了None，说明实体文本和原文差异太大，就不能静默接受，要提示标注者重新标注。

4.2 实体嵌套与重叠标注冲突

现象：标注人名时把"某科技公司创始人张三"整段标成PERSON，但"某科技公司"同时也被标成了ORG，两个标注区域发生重叠，保存时报冲突。

原因：实体嵌套是知识图谱标注里的天然难点。人物实体包含组织实体，或者组织名包含人名，前端如果只判断区域重叠就拒绝保存，会让标注者很沮丧，但如果不校验就会产生脏数据。

解决：在数据模型层区分"完全重叠"和"部分重叠"两类情况。完全重叠说明标注者误操作，直接阻止；部分重叠则允许并标记为嵌套关系，导出时自动展开成普通SPO。源码里在后端标注接收接口做了分级处理：

# backend/services/annotation_service.py def check_overlap(spo, existing_annotations): new_region = set(range(spo['subject']['offset'][0], spo['subject']['offset'][1])) for anno in existing_annotations: old_region = set(range(anno['subject']['offset'][0], anno['subject']['offset'][1])) if new_region == old_region: return "exact_duplicate" if new_region & old_region: return "partial_overlap" return "ok"

遇到"exact_duplicate"直接给前端返回409状态码，前端弹出提示；"partial_overlap"则允许入库。这条逻辑对于标注包含关系（如机构名嵌套在人物履历里）特别重要。

4.3 关系方向标反：谓词语义被搞反

现象：导出的三元组出现"某市高新区(主语) -> 总部位于(谓词) -> 某公司(宾语)"这种倒挂关系，模型训练后关系抽取精确率惨不忍睹。

原因：标注者在选择主语和宾语时，没有严格按照句子语义顺序。尤其当主语和宾语在文本中出现的顺序与语义方向不一致时（比如"某公司的总部位于某市高新区"），前端如果引导不够，很容易把文本先出现的实体默认当主语。

解决：在关系标注模式下，前端默认按文本先后顺序填充主语和宾语，但提供交换按钮让标注者手动反转。源码里已经在关系创建弹窗上加了交换功能，关键是养成习惯：每标注完一组SPO，扫一眼右侧面板里"主语->谓词->宾语"的展示顺序，把倒挂的当场换过来。

4.4 批量导入数据编码混乱

现象：从数据库或Excel导出的文本数据丢进标注系统后，某些字符变成乱码，尤其是引号和特殊符号。

原因：文件编码不一致。UTF-8的文本和GBK的文本混在一起，后端统一按UTF-8处理，GBK文件里的中文字符就会全部变问号。

解决：在导入入口增加编码探测和转换层：

# backend/services/importer.py import chardet def read_text_file(path): raw = open(path, 'rb').read() detect = chardet.detect(raw) encoding = detect.get('encoding', 'utf-8') if encoding != 'utf-8': return raw.decode(encoding).encode('utf-8').decode('utf-8') return raw.decode('utf-8')

源码的importer模块里已经有相似的编码兼容逻辑，如果你拿到的是早期版本且没有这段代码，一定要自己补上，否则中文字符的标注任务会变成一场灾难。

4.5 多人标注冲突：同一个实体出现多个版本

现象：两个人标注同一份文本，一个人把"某公司"标成ORG，另一个人漏标了，或者标成PERSON，导入模型训练数据时同一实体在不同样本里的标签不一致。

原因：这是标注一致性管理问题。源头在于标注任务没有锁定机制，同一份文本可以被多人同时领取并各自保存。

解决：在任务分配层加状态机，文本进去验证队列后就进入"标注中"状态，只有提交质检后才能进入"已完成"状态，其他人不能再打开。源码的后端预留了task_status字段，通过更新状态字段来控制任务流转。实际使用时建议再加入一条硬约束：每次提交前，系统自动统计当前标注结果与已完成文本的实体类型分布差异，超过阈值就强制让标注者复核。

5. 标注数据导出与复用：让清洗后的结果无缝喂给模型

标注的最终目的是生产训练数据。很多标注工具导出的数据格式单一，喂给模型前还要写一堆转换脚本。这套源码的导出模块做了功能分层，数据可以直接对接主流序列标注框架。

5.1 导出格式选型：BIO、JSONL和三元组CSV

源码的导出模块支持三种格式：BIO序列标注格式、JSONL行式数据和CSV三元组表。三种格式对应不同的下游任务，选型依据可以按这张表来：

三种格式导出的数据总量一致，但组织方式完全不同。实体识别类的模型训练推荐BIO格式，关系抽取类的推荐JSONL直接喂给联合解码模型，最终入库和查询用CSV最方便。这个工具前端导出按钮会调用后端对应接口，如果要在导出时做字段过滤，直接改services/export_service.py里的字典映射即可。

5.2 三元组去重与冲突合并的清洗逻辑

标注过程中会不可避免地产生重复三元组和冲突三元组。比如同一句话被两个人标注，一个标了"某公司-成立时间-2005年"，另一个标了"某公司-成立时间-2005年5月"，如果不做清洗，训练数据里会出现两个答案。源码里有一个utils/dedup.py模块，处理优先级为：

# backend/utils/dedup.py def merge_spo_annotations(annotation_list): merged = {} for item in annotation_list: key = (item['subject']['text'], item['predicate'], item['object']['text']) if key not in merged: merged[key] = item else: # 冲突时取置信度更高的一条 old_item = merged[key] if item.get('confidence', 0.5) > old_item.get('confidence', 0.5): merged[key] = item return list(merged.values())

置信度字段在标注界面上有一个可选的打分控件，标注者可以给每条关系打1-5分。如果没有标注confidence字段，就保留先提交的记录。这里要提醒一下：导出CSV前最好跑一遍这个去重逻辑，否则冗余三元组会造成统计结果虚高，后面做图数据库查询会看到一坨重复边。

5.3 标注进度统计与质检抽样

质检是标注工序里最容易被跳过的一环。这套工具提供一个简单的进度统计接口，按任务、按标注者两个维度输出统计结果。常用的指标是有效标注率，即质检通过的标注数占总数比例。后端接口实现方式是聚合查询标注记录表：

# backend/services/statistics.py def compute_quality_metrics(db, task_id): total = db.fetch_count("SELECT COUNT(*) FROM annotations WHERE task_id=?", (task_id,)) passed = db.fetch_count("SELECT COUNT(*) FROM annotations WHERE task_id=? AND status='passed'", (task_id,)) conflict = db.fetch_count("SELECT COUNT(*) FROM annotations WHERE task_id=? AND status='conflict'", (task_id,)) return {"total": total, "passed_rate": passed / total, "conflict_count": conflict}

可以使用状态字段status来标记每条标注记录是否通过质检，这个字段在导入时可被丢弃，不会污染模型训练数据。

6. 用一致性检查脚本给标注结果做最后一道体检

标注做完了，但导出前还有一个值得养成的习惯：跑一遍数据一致性检查。我从实际项目里总结出一个小技巧，就是把检查项量化成脚本输出，用数字来判断这批数据是否达到可以进入训练环节的标准。下面这段脚本可以放在后端utils目录里直接执行：

# backend/utils/quality_check.py import json def run_quality_checks(jsonl_path): report = {} with open(jsonl_path, 'r', encoding='utf-8') as f: lines = [json.loads(line) for line in f if line.strip()] report['total_samples'] = len(lines) spo_count = [len(item.get('spo_list', [])) for item in lines] report['avg_spo_per_sample'] = round(sum(spo_count) / max(len(lines), 1), 2) report['empty_sample_count'] = len([c for c in spo_count if c == 0]) # 检查主语遗漏与宾语遗漏 missing_subject = 0 missing_object = 0 for item in lines: for spo in item.get('spo_list', []): if not spo.get('subject') or not spo.get('subject', {}).get('text'): missing_subject += 1 if not spo.get('object') or not spo.get('object', {}).get('text'): missing_object += 1 report['missing_subject'] = missing_subject report['missing_object'] = missing_object # 检查关系类型是否合法（从schema读取合法谓词表） schema = json.load(open('configs/schema.json', encoding='utf-8')) valid_predicates = {r['id'] for r in schema['relation_types']} illegal_predicate = 0 for item in lines: for spo in item.get('spo_list', []): if spo.get('predicate') not in valid_predicates: illegal_predicate += 1 report['illegal_predicate'] = illegal_predicate return report if __name__ == '__main__': report = run_quality_checks('exported_annotations.jsonl') print(json.dumps(report, ensure_ascii=False, indent=2))

这段脚本不复杂，但每项指标都有实际意义。total_samples让你知道数据集体量；avg_spo_per_sample过低说明标注者可能漏标了大量关系；empty_sample_count过高意味着文本质量差或任务分配有问题；missing_subject和missing_object是SPO结构完整性底线，任何一条不为0都必须手工修复；illegal_predicate是从schema合法表里校验出来的脏数据，通常是schema版本更替后老标签残留导致的。跑完后报告如果四项异常都是0，这批数据就算过了我自己的验收线。

我给这套工具补过一些别的检查逻辑，比如实体类型分布统计和同一实体的标签一致性检查，都是基于这段脚本扩的。从那以后我每次做标注项目，导出前都强制走一遍这个体检流程，不再依赖肉眼抽查。标注工具做得再好，数据质量始终是知识图谱项目的地基。希望这份体检脚本能帮你在交付前拦住最后一波脏数据。希望帮到你。

本文还有配套的精品资源，点击获取