求助：spaCy SpanCategorizer正确Example对象格式及示例

一、格式正确的Example对象示例 #

下面是包含两个文档、两个标签（PRODUCT和BRAND）的完整Example示例，明确展示金标（reference）和预测模板（prediction）的格式：

import spacy
from spacy.tokens import Doc, Span, Example
from spacy.lang.en import English

# 初始化基础nlp对象
nlp = English()

# 第一个金标文档：带标注的reference
text1 = "I bought an iPhone 15 and a MacBook Pro."
doc1 = nlp.make_doc(text1)
# 按标签分组存储Span到doc.spans
doc1.spans["PRODUCT"] = [
    Span(doc1, 3, 5, label="PRODUCT"),  # 对应文本"iPhone 15"
    Span(doc1, 7, 9, label="PRODUCT")   # 对应文本"MacBook Pro"
]
doc1.spans["BRAND"] = [
    Span(doc1, 3, 4, label="BRAND"),    # 对应文本"iPhone"
    Span(doc1, 7, 8, label="BRAND")     # 对应文本"MacBook"
]

# 第二个金标文档
text2 = "The Samsung Galaxy S24 beats the Google Pixel 8."
doc2 = nlp.make_doc(text2)
doc2.spans["PRODUCT"] = [
    Span(doc2, 2, 4, label="PRODUCT"),  # 对应文本"Galaxy S24"
    Span(doc2, 6, 8, label="PRODUCT")   # 对应文本"Pixel 8"
]
doc2.spans["BRAND"] = [
    Span(doc2, 1, 2, label="BRAND"),    # 对应文本"Samsung"
    Span(doc2, 5, 6, label="BRAND")     # 对应文本"Google"
]

# 生成Example对象：prediction用仅含文本的空文档，训练时模型会在这上面生成预测
pred_doc1 = nlp.make_doc(text1)
example1 = Example(pred_doc1, doc1)

pred_doc2 = nlp.make_doc(text2)
example2 = Example(pred_doc2, doc2)

# 最终的训练示例列表
training_examples = [example1, example2]

核心说明 #

• reference（金标文档）：必须包含完整的Span标注，通过doc.spans按标签或统一key存储。
• prediction（预测文档）：训练时只需是包含原始文本的空标注文档，模型会自动填充预测结果，再和reference对比计算损失。
• 也可以用Example.from_dict从字典直接构建，适合批量导入标注数据。

二、你的标注代码修复 #

你的代码存在几个导致spaCy无法识别标签的问题，修复后的版本如下：

phrase_matches = phrase_matcher(doc)

# 关键：SpanCategorizer默认监听"sc"这个SpanGroup key，统一存储所有标注
spans_key = "sc"
doc.spans[spans_key] = []

for match_id, start, end in phrase_matches:
    match_label = nlp.vocab.strings[match_id]
    # 直接创建带标签的Span，添加到统一的SpanGroup
    span = Span(doc, start, end, label=match_label)
    doc.spans[spans_key].append(span)

# 如果你需要同时按标签单独分组，保留下面的代码（可选）
# for label in labels:
#     doc.spans[label] = []
# for match_id, start, end in phrase_matches:
#     match_label = nlp.vocab.strings[match_id]
#     span = Span(doc, start, end, label=match_label)
#     doc.spans[match_label].append(span)
#     doc.spans["sc"].append(span)

修复要点 #

1. 统一SpanGroup key：spaCy的SpanCategorizer默认读取doc.spans["sc"]中的标注，如果你的标注存在其他key下，模型会找不到。如果要自定义key，需要在训练配置中指定。
2. 避免冗余操作：原代码中重复创建Span的操作可以简化，直接生成带标签的Span即可。
3. 确保标签在vocab中：如果match_label是新标签，提前用nlp.vocab.strings.add(match_label)将其加入词汇表，避免识别失败。

三、训练配置补充 #

如果使用自定义的SpanGroup key，需要在config.cfg中明确配置：

[components.spancat]
factory = "spancat"
spans_key = "你的SpanGroup名称"  # 比如你用了按标签分组的key，这里要对应
labels = ["PRODUCT", "BRAND"]  # 列出你所有的标签

内容的提问来源于stack exchange，提问作者Paola