SiameseUIE实操手册：test.py中extract_pure_entities函数调用详解
1. 为什么你需要读懂这个函数
你刚登录云实例，执行完python test.py，屏幕上跳出了几行清晰的实体结果——“人物：李白，杜甫，王维”“地点：碎叶城，成都，终南山”。看起来很顺利。但如果你打算把这套能力用到自己的业务里，比如从客服对话中精准抓取客户提到的城市、从历史文档中批量提取人物关系，或者想改造成支持“机构”“时间”等新类型，那光看输出远远不够。
真正决定抽取质量的，不是模型加载那几行提示，而是test.py里那个被反复调用的核心函数：extract_pure_entities。它不只是一段逻辑代码，更是整个镜像“无冗余、直观、可定制”特性的技术支点。它在受限环境下绕过依赖冲突，在固定PyTorch版本里稳定运行，在50G系统盘上不写缓存，最终把原始文本变成干净、结构化、可直接入库的实体列表。
本手册不讲模型原理，不堆参数配置，只聚焦一件事：手把手带你拆解extract_pure_entities的每一次调用，搞懂它怎么工作、为什么这么设计、以及你该如何安全地修改它。无论你是想复用现有逻辑、调试异常结果，还是扩展新实体类型，这里都有你马上能用的答案。
2. 函数入口：从test.py的5个例子说起
test.py的核心是一个名为test_examples的列表，它定义了5个预置测试用例。每个用例都是一个字典，包含四个关键字段：
{ "name": "例子1：历史人物+多地点", "text": "李白出生在碎叶城，杜甫在成都修建了杜甫草堂，王维隐居在终南山。", "schema": {"人物": None, "地点": None}, "custom_entities": {"人物": ["李白", "杜甫", "王维"], "地点": ["碎叶城", "成都", "终南山"]} }这四部分共同构成了extract_pure_entities的完整输入。我们逐个拆解它们的实际作用：
2.1 text：原始文本，是抽取的唯一原材料
它就是你要处理的句子，没有任何预处理。镜像不强制要求清洗标点或分句——因为extract_pure_entities内部会做上下文对齐。你传入“李白出生在碎叶城”，函数就基于这个字符串做匹配；你传入整段新闻稿，它也照单全收。关键提醒：文本中不能包含未声明的实体类型。比如你在schema里只写了“人物”和“地点”，却在text里写了“2023年”，这个年份不会被识别——这不是bug，而是设计使然：它拒绝猜测，只做确定性抽取。
2.2 schema：定义你要什么，而不是它能抽什么
schema = {"人物": None, "地点": None}看似简单，实则承担两个重要角色：
- 类型声明：告诉函数“本次任务只关心这两类实体”，其他所有词（如动词“出生”、介词“在”）自动忽略；
- 结构占位：为后续结果组织提供键名。抽取完成后，结果字典的键一定严格对应
schema的键，不会多也不会少。
你可能会问：“为什么值是None？” 因为schema只负责定义“有哪些槽位”，不参与匹配逻辑。真正的匹配规则，由下一个参数custom_entities或内置正则决定。
2.3 custom_entities：控制精度的开关，也是你最该关注的字段
这是整个函数行为的分水岭。它的存在与否，直接决定extract_pure_entities走哪条路径：
- 当
custom_entities是字典（如例子中所示）：启用自定义实体模式。函数会严格比对text中是否出现custom_entities里列出的每一个字符串，并确保匹配结果完全一致（“杜甫”不会匹配“杜甫草堂”，“成都”不会匹配“成都市”）。这是镜像默认启用的模式，也是实现“无冗余”的核心机制。 - 当
custom_entities是None：启用通用规则模式。函数放弃精确匹配，转而使用内置正则：- 人物：匹配连续2-4个汉字，且不在停用词表中（如“的”“了”“在”）；
- 地点：匹配包含“市”“省”“县”“州”“城”“区”“镇”“村”“岛”“山”“河”“湖”“海”的2-6字词。
重要实践建议：在生产环境中，强烈推荐始终使用
custom_entities字典模式。通用规则看似省事，但容易产生“北京”匹配“北京市”、“上海”匹配“上海市”的冗余，或漏掉“苏轼”“王维”等非现代常用名。自定义模式虽然多写几行，但结果可控、可验证、可审计。
3. 函数内部：三步走，每一步都不可跳过
extract_pure_entities的源码逻辑清晰分为三个阶段。理解它们，你就掌握了调试和扩展的钥匙。
3.1 阶段一：预处理与对齐（preprocess_and_align）
函数第一件事不是匹配，而是“对齐”。它调用镜像内置的ChineseTokenizer（基于vocab.txt）对text进行分词，并记录每个字符在原始文本中的起始位置。例如：
原文：李白出生在碎叶城 分词后：['李', '白', '出', '生', '在', '碎', '叶', '城'] 位置映射：[0,1,2,3,4,5,6,7]这一步解决了中文NLP最头疼的问题：模型内部按字/词切分，但业务需求按“字符串”返回。没有这个映射，你得到的只是“第5-7个token”，而不是“碎叶城”这个完整词。镜像之所以能在不修改PyTorch的前提下稳定运行，正是因为这一步完全脱离了transformers库的复杂pipeline，用纯Python实现，轻量且可靠。
3.2 阶段二：双路匹配引擎（match_engine）
这是函数真正的“大脑”，根据custom_entities的值选择不同策略：
自定义模式分支：
它遍历custom_entities中每个实体列表（如"人物": ["李白", "杜甫"]），对每个候选词在text中执行子串搜索（text.find(entity)）。找到后，再通过上一步的位置映射，确认该子串是否落在同一个token序列内——防止“杜甫草堂”被误拆成“杜甫”和“草堂”。所有匹配结果按原文顺序去重合并，确保“李白”只出现一次，即使文本中写了两遍。通用规则分支：
它先用正则扫描全文，找出所有符合“2-4字+非停用词”的片段作为人物候选，再用另一组正则扫描含地理后缀的词作为地点候选。最后，它会对候选结果做长度优先过滤：如果“北京市”和“北京”同时被匹配，只保留更长的“北京市”，避免层级冗余。
调试技巧：当你发现某个实体没被抽出来，第一步不是怀疑模型，而是检查
text.find("你的实体")是否返回-1。常见原因包括：原文有空格/换行/全角标点（如“李白 出生”中间是全角空格）、实体名大小写不一致（镜像默认区分大小写）、或实体名被标点隔断（如“李白，出生”）。
3.3 阶段三：结果组装与去重（assemble_result）
匹配完成后，函数不会直接返回列表。它会：
- 按
schema键名分组，把所有“人物”匹配项归入"人物"键下，所有“地点”归入"地点"键下； - 对每个键下的列表执行严格去重（不是简单
list(set())，而是保留首次出现顺序）； - 将结果转换为标准Python列表（非tensor、非generator），确保你能直接
print(result["人物"])或json.dump(result, f)。
这一步保证了输出永远是干净、扁平、可序列化的字典，无需额外转换就能喂给数据库或API。
4. 实战：如何安全地修改和扩展
镜像允许你修改test.py，但必须遵守三条铁律。违反任何一条，都可能导致模型加载失败或抽取结果错乱。
4.1 修改test_examples：添加新测试用例
这是最安全的扩展方式。只需在test_examples列表末尾追加新字典：
# 正确示例：新增一个“现代人物+机构”场景（注意：schema仍只声明已支持类型） { "name": "例子6：现代人物+企业", "text": "张一鸣创立了字节跳动，王兴创办了美团。", "schema": {"人物": None, "地点": None}, # 保持原schema，地点暂不填 "custom_entities": {"人物": ["张一鸣", "王兴"]} # 只声明人物，地点留空 }关键约束：schema的键必须是镜像当前支持的类型（目前仅“人物”“地点”）。如果你想支持“机构”，不能直接加"机构": None——这会导致extract_pure_entities报错，因为函数内部没有对应的匹配逻辑。
4.2 扩展新实体类型：修改extract_pure_entities函数体
要支持“机构”，你需要编辑test.py中extract_pure_entities函数的匹配逻辑。重点修改两个地方：
在
schema解析部分增加类型判断：
找到类似if entity_type == "人物":的代码块，在其后添加：elif entity_type == "机构": # 新增机构匹配逻辑 candidates = re.findall(r'[\u4e00-\u9fa5]{2,8}(?:公司|集团|科技|有限|股份|银行|证券|保险|基金|协会|学会|中心|局|部|委)', text)在结果组装部分增加键名：
确保result字典初始化时包含"机构"键：result = {k: [] for k in schema.keys()} # 如果schema里有"机构"，result["机构"]就自动存在
风险警告：不要删除函数开头的
# === DEPENDENCY SHIELD ===注释块及之后的环境兼容代码。这些代码屏蔽了torchvision等视觉库的导入，一旦删除，import torch会触发冲突，导致整个脚本崩溃。
4.3 调试与验证：三步快速定位问题
当你修改后运行报错，按此顺序排查：
- 检查路径与权限：执行
ls -l nlp_structbert_siamese-uie_chinese-base/，确认vocab.txt、pytorch_model.bin、config.json三个文件存在且大小非零； - 验证函数签名：确保你调用
extract_pure_entities时，参数顺序和名称完全匹配——必须是extract_pure_entities(text, schema, custom_entities)，少一个参数或换顺序都会报TypeError； - 最小化复现：新建一个极简测试文件
debug.py，只写三行：
如果这三行都跑不通，问题一定在环境或基础依赖上，而非你的业务逻辑。from test import extract_pure_entities result = extract_pure_entities("测试文本", {"人物": None}, {"人物": ["测试"]}) print(result)
5. 总结：掌握这个函数，你就掌握了SiameseUIE的命脉
extract_pure_entities看似只是test.py里的一个工具函数，但它浓缩了整个镜像的设计哲学：在资源受限的硬约束下，用最简代码实现最高可控性。它不追求大而全的通用抽取，而是用“自定义实体+严格匹配”换来结果的确定性；它不依赖最新版框架，而是用纯Python预处理和正则引擎保障兼容性；它不生成复杂嵌套结构，而是输出一眼就能看懂的扁平字典。
你现在应该清楚：
- 如何阅读并理解
test.py中每个测试用例的意图； custom_entities参数是精度与灵活性的总开关，生产环境务必使用；- 函数内部的三阶段（对齐→匹配→组装）是调试的黄金路径；
- 扩展新类型必须修改函数体，但绝不能碰依赖屏蔽代码块。
下一步，打开你的test.py，找到第127行左右的def extract_pure_entities(，对照本文逐行阅读。你会发现，那些曾让你困惑的缩进和注释，此刻都变得清晰而有力。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
