spaCy Span 的字符偏移与词元索引有什么区别

我第一次把 spaCy 的 Span.start 直接拿去切 Python 字符串时，得到的不是预期短语。问题不在 Span 文本，而在我把两套坐标混用了：start/end 是 Doc 中的词元索引，start_char/end_char 才是原文字符偏移。两者都遵循左闭右开，但计数单位完全不同。

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

这篇只围绕这个边界排查。先对照同一个 Span 的两套偏移，再处理字符范围切进词元中间的情况，最后给一份适合标注、抽取和调试的选择清单。

先分清 Span 的两套坐标

spaCy 把文本处理成 Doc，再把 Doc 切成由若干词元组成的 Span。因此 Span.start 是第一个词元在 Doc 中的位置，Span.end 是最后一个词元之后的位置；它们适合和 doc[start:end] 配合。相对地，start_char 与 end_char 是原文字符位置，适合和 doc.text[start_char:end_char] 配合。

可以把它记成一句话：切 Doc 用词元索引，切原文用字符偏移。如果把一套坐标交给另一套切片，代码通常不会报错，只会静默返回错误片段，这也是排查时最容易漏掉的证据。

用同一个 Span 对照两种切片

下面的输入故意保留空格，让字符偏移和词元索引的差异清楚可见。示例只用于说明 API 关系，不把未执行的输出当成运行证据。

import spacy
from spacy.tokens import Doc, Span

# 用固定词元和空格构造最小 Doc，便于对照两套坐标。
nlp = spacy.blank("en")
doc = Doc(
    nlp.vocab,
    words=["spaCy", "makes", "NLP", "practical", "."],
    spaces=[True, True, True, False, False],
)
span = Span(doc, 1, 4)

# start/end 是词元坐标，可直接切 Doc；end 是排除位置。
token_text = doc[span.start:span.end].text

# start_char/end_char 是字符坐标，可直接切原文字符串。
char_text = doc.text[span.start_char:span.end_char]

# 词元索引不能当作字符串索引，否则会从错误字符位置截取。
wrong_text = doc.text[span.start:span.end]

print(span.text, token_text, char_text, wrong_text)

这里的 token_text 和 char_text 都对应 Span 的文本，而 wrong_text 只是把数字碰巧当成字符位置使用。真实项目中，短文本可能让错误看起来“差不多”，一旦前面出现长单词、多个空格或非 ASCII 字符，错位就会放大。

反过来也一样：如果你已经拿到外部标注给出的字符区间，不要直接写成 doc[start:end]。先用字符范围建立 Span，或者先映射到完整词元边界，再把词元坐标保存到后续处理结构中。

处理字符边界落在词元中间的情况

实际的实体标注经常给出字符区间，但区间未必正好覆盖完整词元。spaCy 的 char_span 提供 strict、contract 和 expand 三种对齐方式：严格模式要求字符边界与词元边界匹配，不能匹配时返回 None；收缩模式只保留完全落在区间内的词元；扩展模式则包含与字符区间有部分重叠的词元。

# 假设外部标注给出字符区间，区间可能切入某个词元内部。
start_char, end_char = 1, 12

# strict 不替你猜边界；返回 None 时要保留这个信号。
strict_span = doc.char_span(
    start_char,
    end_char,
    alignment_mode="strict",
)

# contract 只留下完全包含在字符区间中的词元。
contract_span = doc.char_span(
    start_char,
    end_char,
    alignment_mode="contract",
)

# expand 会覆盖与字符区间部分重叠的完整词元。
expand_span = doc.char_span(
    start_char,
    end_char,
    alignment_mode="expand",
)

# 生产代码要显式处理 None，避免把未对齐误当成空文本。
if strict_span is None:
    print("字符边界没有严格对齐到词元")

我的经验是：需要可追溯标注时先用 strict，让脏边界暴露出来；需要尽量保留完整实体时再考虑 expand，但要记录它扩大了范围。contract 更适合“只收集完全包含的词元”这类场景，不能把它当成通用修复。

把偏移选择落到标注和调试清单

最后可以按四项复查：一是这组数字的单位是词元还是字符；二是切片对象是 Doc 还是 Python 字符串；三是字符边界是否完整覆盖词元；四是 None 是否被当成普通空值吞掉。只要把这四项写进标注函数的日志或返回结构，Span 偏移错位通常就能在入口处被定位。

常见问题

Span.start 和 start_char 可以互换吗？

不可以。前者是 Doc 中的词元偏移，后者是原文字符串的字符偏移；只有在非常特殊的文本和分词结果下数字才可能碰巧相同。

char_span 返回 None 是 spaCy 出错了吗？

通常不是。严格对齐模式遇到切进词元中间的字符区间时，返回 None 正是在提醒你边界不完整。应根据标注契约选择 contract 或 expand，或者先修正外部区间。