Spacy手动创建Span可视化遇KeyError 'sc'问题求助

问题场景 #

在spaCy中手动创建Span时遇到可视化异常：

• 当doc.spans同时包含"xx"和"sc"两个key时，调用displacy.render(doc, style="span")可以正常渲染所有Span
• 但仅保留doc.spans["xx"]，并通过options={"spans_key":"xx"}指定渲染该key的Span时，触发KeyError: 'sc'，无法正常显示

正常工作的代码 #

from spacy.tokens import Span
text = "Welcome to the Bank of China. "
nlp = spacy.blank("en")
doc = nlp(text)

doc.spans["xx"] = [Span(doc, 0, 1, "ORG")]
doc.spans["sc"] = [
    Span(doc, 3, 6, "ORG"), 
    Span(doc, 5, 6, "GPE"),
    Span(doc, 2, 4, "welcome")
]
displacy.render(doc, style="span")

报错的代码 #

doc.spans["xx"] = [
    Span(doc, 3, 6, "ORG"), 
    Span(doc, 5, 6, "GPE"),
    Span(doc, 2, 4, "welcome")
]
displacy.render(doc, style="span", options={"spans_key":"xx"})

问题原因 #

这个问题的核心是spaCy的Displacy渲染Span时，会读取doc.spans中所有已注册的span组元数据，哪怕你指定了spans_key。如果之前的代码里给doc.spans["sc"]赋过值（哪怕后续删除了这个key），spaCy内部的缓存或元数据可能还保留着"sc"的记录，导致Displacy尝试读取不存在的"sc"key，从而抛出KeyError。

尤其如果你是在同一个运行会话（比如同一个脚本、Notebook单元格）中先跑了正常代码，再跑报错代码，doc对象是复用的，doc.spans里的"sc"元数据并没有被彻底清除，哪怕你重新给"xx"赋值也没用。

解决方法 #

• 创建全新的Doc对象：每次测试都生成新的doc，避免复用残留了旧span组元数据的实例：

from spacy.tokens import Span
text = "Welcome to the Bank of China. "
nlp = spacy.blank("en")
# 每次都创建新的doc实例
doc = nlp(text)
doc.spans["xx"] = [
    Span(doc, 3, 6, "ORG"), 
    Span(doc, 5, 6, "GPE"),
    Span(doc, 2, 4, "welcome")
]
displacy.render(doc, style="span", options={"spans_key":"xx"})

• 清除所有残留的span组：如果必须复用Doc对象，先调用doc.spans.clear()彻底清空所有span组，再重新赋值：

# 清空所有已注册的span组
doc.spans.clear()
doc.spans["xx"] = [
    Span(doc, 3, 6, "ORG"), 
    Span(doc, 5, 6, "GPE"),
    Span(doc, 2, 4, "welcome")
]
displacy.render(doc, style="span", options={"spans_key":"xx"})

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