Python difflib.get_close_matches 的cutoff怎样影响候选

difflib.get_close_matches的cutoff是候选入选的最低相似度，默认0.6，允许范围是0到1，包含两端。分数达到阈值才有资格参与返回；n只限制最多返回多少个，不能把低于cutoff的候选补进结果。

官方文档地址：https://docs.python.org/3/library/difflib.html。下面用CPython 3.14源码解释实现细节，以固定短词表说明阈值作用，不提供实测性能或业务准确率。

cutoff控制入选，n控制最多返回多少

相同输入、相同候选且n不变时，提高cutoff会使入选条件更严格，结果可能减少或不变，不会因为“筛选更准确”而自动补充其他词。阈值不是分页位置，也不是编辑距离中允许修改的字符数。

把相似匹配放在候选建议层

考虑一个配置导入工具：用户输入了不在允许字段表中的名称，程序想显示“你是否想输入这些字段”。此时get_close_matches可以作为建议层，字段合法性仍由精确规则决定。

架构上可以把输入字符串、允许词表、相似度评分、cutoff门槛、数量上限和建议列表看成不同职责。词表决定可推荐范围，门槛决定哪些项目够相似，数量上限决定展示容量。这样就不会把“返回第一项”误当成“可以自动替用户修改配置”。

反例是遇到空结果就把cutoff降到0，取第一项直接落库。它可能让界面总有东西显示，却把“没有合适建议”隐藏掉了。对于配置字段、文件路径等有明确允许范围的场景，空结果应当是正常的可表达状态。

用固定词表观察阈值变化

下面故意不用带语义的单词，而选取短字符串，让字面相似度与门槛关系更清楚。这是可供读者自行执行的示例，本文没有运行代码。

from difflib import get_close_matches, SequenceMatcher

# 用短字符串隔离阈值行为，避免真实词义影响理解。
query = "abcd"
candidates = ["abc", "abxy", "wxyz"]

for threshold in (0.5, 0.8, 0.9):
    # n足够容纳整个词表，因此这里只观察cutoff筛选。
    matches = get_close_matches(query, candidates, n=3, cutoff=threshold)
    print(f"cutoff={threshold}: {matches}")

# 与CPython 3.14实现保持相同方向：候选在前，查询在后。
for item in candidates:
    score = SequenceMatcher(None, item, query).ratio()
    print(item, score)

# 提高数量上限不能让未达到阈值的项目入选。
print("高阈值、大n：", get_close_matches(query, candidates, n=20, cutoff=0.9))

按匹配块推导，abc与查询abcd有3个匹配字符，总长度为7，分数为6/7；abxy有2个匹配字符，总长度为8，分数为0.5；wxyz没有匹配字符，分数为0。因此下表是示例的预期结果，并非真实执行记录。

最后一次把n设为20，仍不能让cutoff=0.9时出现候选。若把cutoff设为0.5但n改成1，则最多只保留最相似的一项；这正好区分“入选资格”和“展示名额”。返回顺序主要按相似度排列，不应自行推断同分项目一定保留原输入顺序。

预处理与分数解释不能省略

get_close_matches比较的是传入的序列，不会自动统一大小写、去除首尾空格或处理业务别名。如果产品决定忽略大小写，应对查询与词表采用一致处理，并保留规范化值到原始展示值的映射，尤其注意多个原值规范化后相同的情况。

调试时用SequenceMatcher重算分数，还要保持相同的参数方向。CPython 3.14的实现把查询放在第二序列，逐个候选放在第一序列；SequenceMatcher的一些结果可能受方向影响。只对调了参数就断言cutoff失效，会把评分口径差异误当成过滤错误。

分数衡量字面匹配程度，不等于语义相近、拼写纠正概率或领域正确性。不同领域词表、短词与长字符串，也不应无条件共用一个“最佳阈值”。标准库接口没有替业务决定误推荐和漏推荐之间的取舍。

根据空结果和误推荐调整策略

如果建议太杂，先检查词表范围与预处理，再考虑提高阈值；如果没有建议，先确认正确候选本来就在词表中，再看阈值是否过严。缺词不能靠提高n解决，空格或大小写约定不一致也不应全部归因于cutoff。

对于真实业务，可以收集“用户是否选择建议”“空结果是否其实存在可接受候选”等反馈，再确定阈值。本文不虚构一组准确率来替代这种判断。词表非常大或字符串很长时，还要独立评估检索成本，不能因为返回n=3就认为只比较了3个候选。

cutoff等于1是不是只返回完全一致项？

对本文普通字符串用法，可理解为只接受满分匹配；如果目的就是精确查找，直接使用集合成员判断更清楚，无需绕一层相似度推荐。

cutoff越高是不是一定越快？

不能据此保证。实现有快速上界筛选，但耗时还受词表与序列特征影响；阈值含义是入选条件，不是性能承诺。

为什么只拿到字符串，没有分数？

这个函数的返回值就是候选列表。若界面需要展示分数，可以按一致方向用SequenceMatcher计算，并清楚标为相似度，避免显示成“正确概率”。

依据：Python官方参数说明、CPython 3.14实现。