spaCy模糊匹配报错‘extra fields not permitted’原因咨询

问题重现 #

使用spaCy 3.5.0及en_core_web_sm 3.5.0运行以下代码时出现报错：

import spacy
from spacy.matcher import Matcher

nlp = spacy.load("en_core_web_sm")
matcher = Matcher(nlp.vocab)

pattern = [{"LOWER": "hello"}, {"FUZZY": "world"}]
matcher.add("my_name", [pattern])

报错信息：

MatchPatternError: Invalid token patterns for matcher rule 'my_name'
[pattern -> 1 -> FUZZY] extra fields not permitted

原因解释 #

spaCy 3.5.0版本的基础Matcher并不支持FUZZY这个匹配属性。你看到的官方文档示例大概率是针对更高版本的spaCy（v3.6及以上）——从v3.6开始，Matcher才新增了对FUZZY、FUZZY1等模糊匹配字段的支持；或者是文档里的模糊匹配示例是针对PhraseMatcher而非基础Matcher的，两者用法有明显区别。

在3.5.0的Matcher规则中，只允许使用预定义的属性键（比如LOWER、TEXT、POS、DEP等），FUZZY不属于这个范围，因此会触发“额外字段不被允许”的错误。

解决方案 #

根据需求，有两种可行的解决方式：

1. 使用PhraseMatcher实现模糊匹配（适配3.5.0版本）

PhraseMatcher在3.5.0中支持通过fuzzy_k参数设置模糊匹配的编辑距离（即允许字符错误的次数），示例代码：

import spacy
from spacy.matcher import PhraseMatcher

nlp = spacy.load("en_core_web_sm")
# attr指定匹配时使用的文本属性（这里用小写形式），fuzzy_k=1允许1次字符编辑
matcher = PhraseMatcher(nlp.vocab, attr="LOWER", fuzzy_k=1)
# 定义要匹配的短语模式
pattern = nlp("hello world")
matcher.add("my_name", [pattern])

# 测试模糊匹配
doc = nlp("hello wrold")
matches = matcher(doc)
for match_id, start, end in matches:
    print(f"匹配结果: {doc[start:end].text}")

2. 升级spaCy到3.6及以上版本

如果坚持要使用基础Matcher的FUZZY字段，直接把spaCy和对应模型升级到3.6或更高版本，原代码就能正常运行。升级命令：

pip install -U spacy
python -m spacy download en_core_web_sm

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