实体抽取 - 全面指南 · Semantica Cookbook

1概览

本 notebook 提供了一份使用 Semantica 强大的 NER（命名实体识别）模块从文本中抽取命名实体的全面指南。你将学习使用多种抽取器、方法和高级功能来识别和分类文本中的实体。

学习目标

学完本 notebook 后，你将能够：

使用 NERExtractor 和 NamedEntityRecognizer 抽取实体
了解不同的抽取方法（pattern、regex、ML、HuggingFace、LLM）
使用 EntityClassifier 对实体进行分类和分组
使用 EntityConfidenceScorer 评估抽取质量
使用 CustomEntityDetector 创建自定义实体模式
配置抽取参数以获得最佳结果
高效处理多个文档
优雅地处理边界情况和错误

你将学到什么

组件	用途	使用时机
`NERExtractor`	核心实体抽取	快速、简单的抽取
`NamedEntityRecognizer`	带配置的高级 NER	需要精细控制时
`EntityClassifier`	对实体进行分类和分组	组织已抽取的实体
`EntityConfidenceScorer`	对实体置信度打分	质量评估
`CustomEntityDetector`	领域特定实体	需要自定义模式时

2安装

从 PyPI 安装 Semantica：

pip install semantica
# 或安装所有可选依赖：
pip install semantica[all]

# 安装 semantica 包
!pip install semantica

3步骤 1：使用 NERExtractor 进行基础实体抽取

让我们从使用 NERExtractor 的最简单方法开始。该类提供了一个用于从文本中抽取命名实体的直接接口。

什么是 NERExtractor？

NERExtractor 是核心实体抽取类，它： - 识别命名实体（人物、组织、地点、日期等） - 返回包含文本、类型、位置和置信度的实体对象 - 支持多种抽取方法 - 开箱即用，具有合理的默认值

from semantica.semantic_extract import NERExtractor

# 初始化抽取器
ner_extractor = NERExtractor()

# 包含各种实体类型的示例文本
text = """
Apple Inc. is a technology company founded by Steve Jobs, Steve Wozniak, and Ronald Wayne 
in Cupertino, California on April 1, 1976. The company's current CEO is Tim Cook, who took 
over from Steve Jobs in August 2011. Apple is headquartered at One Apple Park Way in Cupertino.
"""

# 抽取实体
entities = ner_extractor.extract(text)

print(f" Extracted {len(entities)} entities:\n")
print("-" * 80)

for i, entity in enumerate(entities, 1):
    # 同时处理 dict 和对象两种格式
    entity_text = entity.get('text', entity.get('entity', '')) if isinstance(entity, dict) else entity.text
    entity_type = entity.get('type', entity.get('label', 'Unknown')) if isinstance(entity, dict) else entity.label
    confidence = entity.get('confidence', 1.0) if isinstance(entity, dict) else getattr(entity, 'confidence', 1.0)

    print(f"{i:2d}. {entity_text:30s} | Type: {entity_type:12s} | Confidence: {confidence:.2f}")

print("-" * 80)

理解实体对象

每个抽取出的实体包含：

属性	描述	示例
`text`	实体文本	"Apple Inc."
`label/type`	实体类别	"ORG"（组织）
`start_char`	起始位置	0
`end_char`	结束位置	10
`confidence`	抽取置信度（0-1）	0.95
`metadata`	附加信息	{"method": "ml"}

常见实体类型

PERSON：人物，包括虚构角色
ORG：公司、机构、组织
GPE：国家、城市、州（地缘政治实体）
LOC：非 GPE 地点、山脉、水体
DATE：绝对或相对日期或时间段
TIME：小于一天的时间
MONEY：货币金额
PERCENT：百分比值

4步骤 2：在上下文中可视化实体

让我们创建一个简单的可视化，以查看在原始文本中高亮显示的实体。

def highlight_entities(text, entities):
    """
    创建一个带有实体标记的简单文本可视化。
    """
    # 按类型对实体进行分组
    entity_types = {}
    for entity in entities:
        entity_text = entity.get('text', entity.get('entity', '')) if isinstance(entity, dict) else entity.text
        entity_type = entity.get('type', entity.get('label', 'Unknown')) if isinstance(entity, dict) else entity.label

        if entity_type not in entity_types:
            entity_types[entity_type] = []
        entity_types[entity_type].append(entity_text)

    print("\n Entity Visualization:\n")
    print("=" * 80)

    for entity_type, entity_list in sorted(entity_types.items()):
        unique_entities = list(set(entity_list))
        print(f"\n{entity_type}:")
        for ent in unique_entities:
            print(f"  • {ent}")

    print("\n" + "=" * 80)

# 可视化已抽取的实体
highlight_entities(text, entities)

5步骤 3：不同的抽取方法

Semantica 支持多种抽取方法，每种方法各有优势：

方法对比

方法	准确性	使用场景	所需条件
pattern	⭐⭐	简单、可预测的模式	无
regex	⭐⭐⭐	自定义模式、ID、代码	正则知识
ml（spaCy）	⭐⭐⭐⭐	通用文本、多语言	spaCy 模型
huggingface	⭐⭐⭐⭐⭐	领域特定、微调	HF 模型
llm	⭐⭐⭐⭐⭐	复杂、自定义类型	API 密钥

让我们尝试不同的方法：

from semantica.semantic_extract import NERExtractor

sample_text = "Apple Inc. was founded by Steve Jobs in Cupertino, California in 1976."

print(" Comparing Extraction Methods:\n")
print("=" * 80)

# 尝试不同的方法
methods_to_try = ["pattern", "regex", "ml"]

for method_name in methods_to_try:
    try:
        print(f"\n Method: {method_name.upper()}")
        print("-" * 40)

        extractor = NERExtractor(method=method_name)
        entities = extractor.extract(sample_text)

        print(f"Found {len(entities)} entities:")
        for entity in entities[:5]:  # 显示前 5 个
            entity_text = entity.get('text', entity.get('entity', '')) if isinstance(entity, dict) else entity.text
            entity_type = entity.get('type', entity.get('label', 'Unknown')) if isinstance(entity, dict) else entity.label
            print(f"  • {entity_text} ({entity_type})")

    except Exception as e:
        print(f"  ️  Method '{method_name}' not available: {str(e)[:50]}")

print("\n" + "=" * 80)

6步骤 4：使用 NamedEntityRecognizer 进行高级实体识别

NamedEntityRecognizer 通过配置参数对抽取过程提供更多控制。

关键参数：

methods：要使用的抽取方法列表（例如 ["spacy", "rule-based"]）
confidence_threshold：最低置信度分数（0.0-1.0，默认：0.5）
merge_overlapping：是否合并重叠的实体（默认：True）
include_standard_types：包含标准实体类型（PERSON、ORG、LOC 等）

from semantica.semantic_extract import NamedEntityRecognizer

# 使用自定义配置创建识别器
ner = NamedEntityRecognizer(
    methods=["spacy"],  # 使用 spaCy 进行基于 ML 的抽取
    confidence_threshold=0.7,  # 只保留高置信度的实体
    merge_overlapping=True,  # 合并重叠的实体提及
    include_standard_types=True  # 包含标准实体类型
)

# 用于批处理的示例文本
texts = [
    "Tim Cook is the CEO of Apple Inc., based in Cupertino.",
    "Microsoft Corporation, founded by Bill Gates, is headquartered in Redmond, Washington.",
    "Amazon was founded by Jeff Bezos in Seattle in 1994.",
    "Google was started by Larry Page and Sergey Brin at Stanford University."
]

print(" Advanced Entity Recognition Results:\n")
print("=" * 80)

all_entities = []
for i, text in enumerate(texts, 1):
    entities = ner.extract_entities(text)
    all_entities.extend(entities)

    print(f"\n Text {i}: {text[:60]}...")
    print(f"   Found {len(entities)} entities:")

    for entity in entities:
        entity_text = entity.get('text', entity.get('entity', '')) if isinstance(entity, dict) else entity.text
        entity_type = entity.get('type', entity.get('label', 'Unknown')) if isinstance(entity, dict) else entity.label
        confidence = entity.get('confidence', 1.0) if isinstance(entity, dict) else getattr(entity, 'confidence', 1.0)
        print(f"     • {entity_text:25s} | {entity_type:10s} | Confidence: {confidence:.2f}")

print(f"\n Total entities extracted: {len(all_entities)}")
print("=" * 80)

7步骤 5：实体分类

使用 EntityClassifier 按类型对实体进行分类和分组，并消歧相似的实体。

什么是 EntityClassifier？

EntityClassifier 可以帮助你： - 按类型对实体进行分类（规范化诸如 "ORG" 与 "ORGANIZATION" 之类的变体） - 按类别对实体进行分组以便分析 - 当存在多个候选时对实体进行消歧 - 跨不同抽取方法标准化实体类型

from semantica.semantic_extract import EntityClassifier

# 初始化分类器
classifier = EntityClassifier()

# 对之前抽取的实体进行分类
classified = classifier.classify_entities(all_entities)

print("️  Entity Classification Results:\n")
print("=" * 80)

for entity_type, entity_list in sorted(classified.items()):
    print(f"\n{entity_type} ({len(entity_list)} entities):")
    print("-" * 40)

    # 获取唯一的实体文本
    unique_entities = set()
    for entity in entity_list:
        entity_text = entity.get('text', entity.get('entity', '')) if isinstance(entity, dict) else entity.text
        unique_entities.add(entity_text)

    for entity_text in sorted(unique_entities):
        print(f"  • {entity_text}")

print("\n" + "=" * 80)

8步骤 6：置信度打分

使用 EntityConfidenceScorer 评估并改进已抽取实体的置信度分数。

为什么要进行置信度打分？

置信度分数可以帮助你： - 过滤低质量的抽取结果（例如，只保留置信度 > 0.8 的实体） - 对实体进行优先级排序，以便人工审核或验证 - 评估不同方法或文本的抽取质量 - 做出明智的决策，决定使用哪些实体

from semantica.semantic_extract import EntityConfidenceScorer

# 初始化置信度打分器
scorer = EntityConfidenceScorer()

# 对实体打分
scored_entities = scorer.score_entities(all_entities)

print(" Entity Confidence Scoring:\n")
print("=" * 80)

# 按置信度等级分组
high_confidence = []
medium_confidence = []
low_confidence = []

for entity in scored_entities:
    confidence = entity.get('confidence', 1.0) if isinstance(entity, dict) else getattr(entity, 'confidence', 1.0)

    if confidence >= 0.8:
        high_confidence.append(entity)
    elif confidence >= 0.5:
        medium_confidence.append(entity)
    else:
        low_confidence.append(entity)

print(f" High Confidence (≥0.8): {len(high_confidence)} entities")
print(f"️  Medium Confidence (0.5-0.8): {len(medium_confidence)} entities")
print(f" Low Confidence (<0.5): {len(low_confidence)} entities")

print("\n Confidence Distribution:")
print("-" * 40)

# 展示每个类别的部分示例
if high_confidence:
    print("\nHigh Confidence Examples:")
    for entity in high_confidence[:3]:
        entity_text = entity.get('text', entity.get('entity', '')) if isinstance(entity, dict) else entity.text
        entity_type = entity.get('type', entity.get('label', 'Unknown')) if isinstance(entity, dict) else entity.label
        confidence = entity.get('confidence', 1.0) if isinstance(entity, dict) else getattr(entity, 'confidence', 1.0)
        print(f"  • {entity_text} ({entity_type}) - {confidence:.2f}")

print("\n" + "=" * 80)

9步骤 7：自定义实体检测

使用 CustomEntityDetector 定义领域特定的实体模式。

何时使用自定义模式？

自定义模式适用于： - 领域特定实体（例如产品代码、发票编号） - 结构化标识符（例如电子邮件地址、电话号码） - 行业特定术语（例如医疗代码、法律引用） - 标准 NER 无法识别的自定义格式

from semantica.semantic_extract import CustomEntityDetector
import re

# 定义自定义模式
custom_patterns = {
    "EMAIL": r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b',
    "PHONE": r'\b\d{3}[-.]?\d{3}[-.]?\d{4}\b',
    "PRODUCT_CODE": r'\b[A-Z]{2,3}-\d{4,6}\b',
    "URL": r'https?://[^\s]+'
}

# 初始化自定义检测器
custom_detector = CustomEntityDetector(patterns=custom_patterns)

# 包含自定义实体的示例文本
custom_text = """
For support, contact support@apple.com or call 1-800-692-7753.
Order product SKU-12345 from https://store.apple.com.
Technical inquiries: tech@apple.com or visit our website.
"""

print(" Custom Entity Detection:\n")
print("=" * 80)

for entity_type in custom_patterns.keys():
    entities = custom_detector.detect_custom_entities(custom_text, entity_type)

    if entities:
        print(f"\n{entity_type}:")
        for entity in entities:
            entity_text = entity.get('text', entity.get('entity', '')) if isinstance(entity, dict) else entity.text
            print(f"  • {entity_text}")

print("\n" + "=" * 80)

10步骤 8：批处理

使用批处理能力高效处理多个文档。

批处理的好处：

性能：一次调用处理多个文档
一致性：对所有文档应用相同的配置
效率：减少初始化带来的开销
可扩展性：处理大规模文档集合

# 示例文档集合
documents = [
    "Apple Inc. released the iPhone 15 in September 2023.",
    "Microsoft announced Azure AI updates at Build 2023 in Seattle.",
    "Google's Sundar Pichai spoke at I/O 2023 in Mountain View, California.",
    "Tesla's Elon Musk unveiled the Cybertruck in Austin, Texas.",
    "Amazon Web Services launched new features in Northern Virginia."
]

print(" Batch Processing Results:\n")
print("=" * 80)

# 处理所有文档
batch_results = ner.process_batch(documents)

# 分析结果
total_entities = 0
entity_type_counts = {}

for i, (doc, entities) in enumerate(zip(documents, batch_results), 1):
    total_entities += len(entities)

    print(f"\n Document {i}:")
    print(f"   Text: {doc[:50]}...")
    print(f"   Entities: {len(entities)}")

    for entity in entities:
        entity_type = entity.get('type', entity.get('label', 'Unknown')) if isinstance(entity, dict) else entity.label
        entity_type_counts[entity_type] = entity_type_counts.get(entity_type, 0) + 1

print(f"\n Batch Processing Summary:")
print("-" * 40)
print(f"Documents processed: {len(documents)}")
print(f"Total entities: {total_entities}")
print(f"Average per document: {total_entities/len(documents):.1f}")

print("\n Entity Type Distribution:")
for entity_type, count in sorted(entity_type_counts.items(), key=lambda x: x[1], reverse=True):
    print(f"  {entity_type}: {count}")

print("\n" + "=" * 80)

11步骤 9：最佳实践与技巧

选择合适的方法

对于通用文本，从 ML（spaCy）开始
对于结构化数据（ID、代码），使用 patterns/regex
对于领域特定需求，尝试 HuggingFace
对于复杂、自定义的实体类型，考虑 LLM

优化性能

设置合适的置信度阈值（生产环境为 0.7-0.8）
对多个文档使用批处理
启用 merge_overlapping 以减少重复
缓存抽取器而不是重新创建它们

需要避免的常见陷阱

不要使用非常低的置信度阈值（< 0.5）
不要在循环中一次处理一个文档
不要忽略实体元数据（其中包含有用信息）
不要忘记处理抽取错误

何时使用每个类

使用场景	推荐类
快速抽取	`NERExtractor`
精细控制	`NamedEntityRecognizer`
实体分组	`EntityClassifier`
质量评估	`EntityConfidenceScorer`
领域特定	`CustomEntityDetector`

12小结

你学到了什么

在本 notebook 中，你学会了如何：

使用 NERExtractor 和 NamedEntityRecognizer 抽取实体
对比不同的抽取方法（pattern、regex、ML、HuggingFace、LLM）
使用 EntityClassifier 对实体进行分类和分组
使用 EntityConfidenceScorer 对实体置信度打分
使用 CustomEntityDetector 创建自定义模式
批量处理文档以提高效率
应用生产环境的最佳实践

关键要点

多种方法可用：根据你的需求选择（速度 vs 准确性）
配置很重要：调整参数以获得最佳结果
置信度是关键：使用阈值过滤低质量的抽取结果
自定义模式有效：适用于领域特定实体
批处理可扩展：高效处理多个文档

下一步

下一篇 Notebook：06-relation-extraction.html
学习如何抽取你所识别实体之间的关系！

延伸阅读： - Semantic Extract API 参考 - 高级抽取技术 - 构建知识图谱

有问题或疑问？ 请查看我们的 GitHub 仓库或文档。