spaCy 怎样给连续词元构造带标签的Span

在 spaCy 里，连续词元构造带标签的 Span，关键是把 Doc 的半开区间 [start, end) 传给 Span 构造器，再用 label 绑定业务标签。也就是说，start 对应第一个要包含的词元，end 对应第一个不包含的词元；不要把它当成最后一个词元的下标。

官方地址：https://spacy.io/api/span

一、先把 Doc 切片和 Span 放在同一张图里

把一句文本看成一个带编号的 Doc，例如词元依次是 OpenAI、发布、GPT、模型。取 [1, 3) 得到的是“发布”和“GPT”，因为左边界包含，右边界排除。这个约定与 Python 切片一致，也方便连续区间首尾相接。

import spacy
from spacy.tokens import Span

# 创建最小英文管线；只依赖分词结果，不要求加载实体识别模型
nlp = spacy.blank("en")
doc = nlp("OpenAI 发布 GPT 模型")

# [1, 3) 包含下标 1 和 2，不包含下标 3
start, end = 1, 3
span = Span(doc, start, end)

print(span.text)       # 发布 GPT
print(span.start)      # 1
print(span.end)        # 3

这里的 Span 是从父 Doc 上截取的一段视图。它保留了起止位置和文本关系，后续可以读取 text、start、end 等属性。区间语义先理清，后面加标签时就不容易出现“少选一个词”或“多选一个词”的偏移。

二、用 Span 构造器把标签绑定到连续词元

需要把这段文字当作某类业务对象时，把标签传给构造器即可。标签最好使用项目中稳定、可读的枚举约定，例如 PRODUCT、ORG 或 LOCATION，这样后续序列化和规则判断更直观。

from spacy.tokens import Span

# 选择 GPT 模型这一段，并声明它属于 PRODUCT 类别
product_span = Span(doc, 2, 4, label="PRODUCT")

# label_ 是可读的字符串标签；label 是 spaCy 内部的整数标识
print(product_span.text)      # GPT 模型
print(product_span.label_)    # PRODUCT
print(product_span.label)     # 一个由 spaCy 管理的整数标识

# 将自定义 Span 放进 Doc.spans，避免误把它当作模型自动识别的实体
doc.spans.setdefault("manual", []).append(product_span)
print(doc.spans["manual"][0].text)

手工创建的 Span 不会因为构造完成就自动变成 doc.ents。如果它代表模型识别的命名实体并且不与现有实体冲突，可以在明确知道写回语义后再赋给 doc.ents；如果只是规则、词典或人工标注结果，使用 doc.spans 保存通常更稳妥。

三、把边界检查放在 Span 构造之前

实际项目中，start 和 end 往往来自匹配器、外部标注文件或模型输出。不要直接把外部数值交给构造器；先把“区间非空、顺序正确、索引未越界、标签非空”这些约束写成一个小函数，错误就能在入口处被解释。

from spacy.tokens import Span

def make_labeled_span(doc, start, end, label):
    # 先拒绝空标签，避免下游出现没有类别的业务对象
    if not isinstance(label, str) or not label.strip():
        raise ValueError("label must be a non-empty string")

    # 使用半开区间：start 必须小于 end，end 可以等于 len(doc)
    if start  len(doc) or start >= end:
        raise ValueError("span range must satisfy 0 

这个检查函数没有替 spaCy 做额外的分词或实体判断，它只负责保护本文章的区间契约。尤其要留意 end == len(doc) 是合法的，因为它表示选择到最后一个词元；而 start == end 表示空区间，不应被当成一个有效业务 Span。

四、按承载方式选择 spans、ents 还是 SpanGroup

构造出 Span 后，还要决定它放在哪里。只需要临时读取时，保留局部变量即可；需要把规则标注附着在文档上时，可放进 doc.spans；只有当它确实是文档的命名实体集合，并且与已有实体边界不冲突时，才考虑更新 doc.ents。不要为了“看起来像实体”而覆盖模型结果。

一种实用的决策顺序是：先确认区间，再构造 Span；接着确认来源，再选择承载容器；最后才交给序列化、检索或下游规则。这样可以把“区间错误”和“写回位置不合适”分成两类问题处理。

常见问题

end 为什么不是最后一个词元的下标？

spaCy 的 Span 使用半开区间，end 是第一个不包含的位置。例如 Span(doc, 1, 3) 覆盖 1 和 2。这个设计与 Python 切片一致，也能让 [0, 2) 和 [2, 4) 无缝拼接。

构造了 Span 后，为什么 doc.ents 还是空的？

Span 构造只是创建对象，不等于自动注册为命名实体。规则标注可以放入 doc.spans 的命名空间；只有明确需要更新实体集合时，才按项目的实体写回策略处理。

可以把不连续的词元一次构造成一个 Span 吗？

Span 表示 Doc 上连续的一段切片。如果目标跨越不连续词元，应拆成多个 Span，或使用更适合承载多个候选的分组结构，不要用一个带空洞的 start/end 区间冒充不连续结果。

速查：一条稳定的构造清单

• 先确认 0 。
• 用 Span(doc, start, end, label="...") 构造连续区间。
• 从 span.text、span.start、span.end 和 span.label_ 读取结果。
• 规则或人工标注优先放入 doc.spans，不要无条件覆盖 doc.ents。