运行spaCy NLP教程代码报AttributeError：Span对象无merge属性

该报错属于spaCy版本迭代带来的不兼容问题：你参考的实操教程是基于spaCy 2.x版本编写的，当前本地环境安装的是spaCy 3.0及以上的新版本，旧版本中Span对象自带的*merge()方法*在3.0版本已被正式移除，因此会触发属性不存在的报错。

第一步：确认本地环境版本 #

运行以下代码打印当前安装的spaCy版本，验证是否为3.0及以上版本：

import spacy
print(spacy.__version__)

方案1：适配新版spaCy的API修改代码 #

新版spaCy调整了文档结构修改的逻辑，所有token合并、拆分操作必须通过doc.retokenize()的上下文管理器完成，不需要改动其他业务逻辑，仅需要替换原代码中合并实体的部分：

1. 原代码中触发报错的循环逻辑：

   for ent in doc.ents:
       ent.merge()
   

2. 替换为新版标准写法：

   with doc.retokenize() as retokenizer:
       for ent in doc.ents:
           retokenizer.merge(ent)
   

修改后完整的可运行scrub函数示例：

def scrub(text):
    doc = nlp(text)
    # 合并所有实体为单个token
    with doc.retokenize() as retokenizer:
        for ent in doc.ents:
            retokenizer.merge(ent)
    tokens = map(replace_name_with_placeholder, doc)
    return "".join(tokens)

方案2：完全适配教程代码的降级方案 #

如果不想修改教程中的原始代码，可以直接将本地spaCy降级到兼容旧API的2.3.x长期支持版本，执行以下安装命令完成降级：

pip install spacy==2.3.7

降级完成后，重新下载对应版本的en_core_web_lg模型即可直接运行原教程代码。

• 使用新版retokenize逻辑时，不要在遍历实体列表的过程中零散修改文档结构，避免出现token索引错位的问题；当前写法将所有合并操作放入上下文管理器中批量处理，可完全规避该问题。
• 实体合并完成后，单个token会继承原span的实体类型属性，原有的人名占位替换逻辑不需要做额外修改，可正常识别PERSON类型实体并完成替换。
• 调整代码时注意统一Python缩进规则，参考教程粘贴的代码存在部分缩进错位的问题，需要保证函数定义、循环块内的语句保持正确层级的缩进，避免触发缩进语法错误。
• 如果运行时出现模型加载报错，可确认下载的en_core_web_lg模型版本与spaCy版本匹配，避免出现跨版本的模型兼容问题。

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