介绍

自动补全看起来可能是一个小功能，但它有着巨大的影响。它节省了输入时间，帮助人们更快找到他们想要的东西，并防止“没有结果”的搜索。

本文是构建自动补全的实用指南，使用 Manticore Search。你将看到如何使用：

• CALL AUTOCOMPLETE 和 /autocomplete HTTP 端点
• 使用 CALL KEYWORDS 进行快速字典查找
• 使用内嵌搜索和高亮显示进行句子补全
• 在生产中运行自动补全的实用技巧

谁应该阅读此文

本指南适用于为在线商店、文档网站或内部工具添加搜索建议的开发人员——特别是如果你使用或计划使用 Manticore Search。示例是动手实践的，可以直接在你的数据上尝试。

快速决策指南

• 当你需要从索引数据中获取容错的多词建议时，使用 CALL AUTOCOMPLETE（或 POST /autocomplete）。
• 当你想要快速、字典式的单词或非常短语的补全时，使用 CALL KEYWORDS。
• 当你想要短语或句子级别的建议（例如显示文档句子的其余部分）时，使用内嵌搜索和高亮显示。
• 如果你想要两个词的预测（预测“下一个词”），请启用 bigram_index。

先决条件和注意事项

• Buddy 是 CALL AUTOCOMPLETE 和 /autocomplete HTTP 端点所必需的。如果未安装 Buddy，这些调用将无法工作。
• 目标表必须启用内嵌 (min_infix_len)。Manticore 会缓存 min_infix_len 检查约 30 秒以提高性能；如果你修改 min_infix_len（例如，在调整搜索性能或在现有表上启用自动补全时），你可能会在该窗口期间看到短暂的不一致。
• CALL AUTOCOMPLETE 仅缓存成功的检查。如果你禁用 min_infix_len 或删除表，后续的自动补全调用可能会表现得过时，直到缓存更新或出现错误。

CALL AUTOCOMPLETE — 快速示例 (SQL)

这是从你的索引中获取建议候选项的最直接方法。

CALL AUTOCOMPLETE('ice', 'products');

典型的结果集包含一列名为 query 的行：

+---------------+
| query         |
+---------------+
| ice           |
| ice cream     |
| iceberg       |
| iceland       |
+---------------+

CALL AUTOCOMPLETE 的工作原理（简要）

CALL AUTOCOMPLETE 是一种高层次的便利功能，它协调 Manticore 内部的几个低层次原语，以生成快速、相关的建议。实际上，它结合了：

• CALL KEYWORDS：快速字典查找，返回前缀/内嵌令牌候选项和统计信息（docs/hits）。这就是自动补全从索引字典中提供强大、低延迟候选项的原因。
• 建议例程（历史上通过 CALL SUGGEST / CALL QSUGGEST 暴露）：生成模糊变体的例程（特别是最后一个词），并帮助生成容错的替代方案。
• 模糊搜索逻辑：为模糊搜索引入的相同编辑距离（Levenshtein）和排名启发式，自动补全流程重用这些逻辑来对候选项进行排名和过滤。

这些组件协同工作：关键字提供候选项，建议/模糊例程扩展和修复它们，模糊逻辑根据距离和流行度对结果进行排名/过滤。键盘布局猜测（启用时）会尽早应用，以便在计算模糊性之前纠正布局错误的输入。

何时不直接调用 CALL KEYWORDS

CALL KEYWORDS 是一个极好的、非常快速的工具，当你需要严格的基于字典的补全（精确的前缀/内嵌匹配）时。然而，它不提供容错或多词建议组合。对于多词、容错的建议，优先使用 CALL AUTOCOMPLETE；对于非常短的前缀、热门列表，或当你明确想要仅字典结果时使用 CALL KEYWORDS。

选项映射（高层次）

• CALL AUTOCOMPLETE 中的 fuzziness 对应于限制编辑距离，类似于建议 API 中的 max_edits。
• preserve 控制是否保留非模糊令牌与模糊匹配一起。
• layouts 启用在模糊评估之前的键盘布局猜测。

注意：这里描述的原语内部组合反映了实现方法，但应视为实现细节——在设计应用程序时，依赖于文档化的 CALL AUTOCOMPLETE API 和选项，而不是内部行为。

这些内部组合就是为什么 CALL AUTOCOMPLETE 通常提供比单独运行 CALL KEYWORDS 更好、更可用的建议。

HTTP/JSON 示例（Buddy）

如果你更喜欢 HTTP 或有一个与 JSON 通信的前端，请使用 Buddy 提供的 /autocomplete 端点：

POST /autocomplete
{
  "table": "products",
  "query": "ice"
}

JSON 响应返回一个建议补全的数组（和元数据），你可以在 UI 中呈现。

CALL AUTOCOMPLETE 选项解释

CALL AUTOCOMPLETE 接受几个选项来调整行为。以下是你最常使用的选项：

• layouts：以逗号分隔的键盘布局代码（us、ru、ua、de、fr 等）。使用此选项检测布局错误的输入（例如，在英文布局下输入“ghbdtn”时，你本想输入“привет” - 俄语的“你好”）。需要至少两个布局来比较字符位置。
• fuzziness：0、1 或 2（默认 2）。匹配错别字的最大 Levenshtein 距离。设置为 0 以禁用模糊性。
• preserve：0 或 1（默认 0）。如果为 1，建议将包括未获得模糊匹配的单词（对于保留专有名词或短令牌很有用）。
• prepend / append: 布尔值 (0/1)。如果为真，则在最后一个单词前/后添加星号以扩展前缀/后缀 (例如，prepend -> *word，append -> word*)。
• expansion_len: 扩展最后一个标记的字符数 (默认 10)。控制将被视为扩展的字符数。

带选项的示例 (SQL)

CALL AUTOCOMPLETE('ghbdtn', 'comments', 'layouts=us,ru', 'fuzziness=1');

这将检测到 “ghbdtn” 是 “привет”（俄语的 “hello”）的布局错误版本，并应用模糊匹配以找到正确的建议。

调用关键字 — 基于标记的补全

当您只需要建议单个单词（或结尾）并希望获得最大速度时，CALL KEYWORDS 是一个很好的替代方案。它使用索引字典而不是扫描文档，这使得它非常高效。

基本语法：

CALL KEYWORDS('ca*', 'products', 1 AS stats, 'hits' AS sort_mode);

这将返回带有 tokenized 和 normalized 形式的行以及可选的统计信息（docs，hits）。按 hits 排序可以显示最受欢迎的补全。

示例结果（说明性）：

+------+-----------+------------+------+------+
| qpos | tokenized | normalized | docs | hits |
+------+-----------+------------+------+------+
| 1    | ca*       | cat        | 1    | 2    |
| 1    | ca*       | carnivorous| 1    | 1    |
+------+-----------+------------+------+------+

bigram_index 技巧

如果您的表启用了 bigram_index，则索引将相邻单词对存储为标记。这使您可以建议可能的下一个单词（“预测下一个单词”），而不仅仅是完成当前标记。这是一种简单但强大的方法，可以在不添加外部 ML 模型的情况下改善多词建议。

使用中缀搜索和高亮的句子补全

对于短语或句子尾部的补全（例如，从文档中自动补全句子的其余部分），使用带通配符的中缀查询并突出显示匹配项。例如，要查找字段以输入片段开头的文档：

• 用户输入时可以发出的查询示例：
  • ^"m*"
  • ^"my *"
  • ^"my c*"
  • ^"my ca*"

使用 ^ 锚点从开头匹配，使用 * 扩展其余部分。启用高亮后，您可以提取匹配部分并将其作为建议呈现（例如：“我的猫喜欢 …”）。

这种方法在您希望建议完整短语或文档片段而不是孤立标记时效果最佳。

集成模式（前端 → 后端）

一个最小的、适合生产的流程如下：

1. 对用户输入进行防抖（150–300 毫秒），以避免过多请求。
2. 对于 1–2 个字符，使用 CALL KEYWORDS 或热列表。
3. 对于 3 个或更多字符，调用 /autocomplete 或 CALL AUTOCOMPLETE。根据您的用户包含适当的选项（layouts，fuzziness）。
4. 显示带有高亮匹配的建议。
5. 跟踪点击并根据受欢迎程度或业务规则重新排序建议。

用户体验提示

• 在桌面上显示 6–10 个建议，在移动设备上显示 3–5 个。
• 如果相关，按类型分组（例如，产品、文档、人员）。
• 始终提供后备选项：例如，“搜索 {query}”。

生产提示

• min_infix_len: 确保根据您的语言和用例适当设置此值。非常小的值会增加索引大小和 CPU 使用；非常大的值会降低匹配灵活性。
• 缓存：允许 ~30 秒以使诸如 min_infix_len 的更改生效。
• 速率限制：对于高流量使用请求限流或内存缓存。
• 索引维护：考虑为最常见的前缀预计算一个“顶级建议”表。

故障排除清单

如果自动补全行为异常：

1. 验证是否安装了 Buddy（如果使用 /autocomplete）。
2. 确认表中已设置 min_infix_len 并启用了中缀。
3. 如果您最近更改了表设置，请在 30 秒后重试以允许内部缓存刷新。
4. 尝试 CALL KEYWORDS 以确保字典中存在相同前缀的标记。
5. 检查可能影响结果的编码和标记化设置（morphology，stopwords）。

示例：完整流程（示例）

用户输入：“ice c”

客户端（防抖）发送：

POST /autocomplete
{
  "table": "products",
  "query": "ice c",
  "options": { "fuzziness": 1 }
}

服务器返回建议，如“冰淇淋”、“冰咖啡”、“冰冷”。用户界面显示这些；在选择后，客户端导航到类似 /search?q=ice+cream 的搜索 URL 或使用所选建议获取产品详细信息。

结论

自动补全是一个小的用户体验功能，但带来了巨大的价值：更快的搜索、更少的死胡同和更高的用户满意度。使用 Manticore Search，您可以在实现建议时做出实用选择——从快速的、字典驱动的 CALL KEYWORDS 到更灵活、容错的 CALL AUTOCOMPLETE（以及通过 Buddy 的 HTTP /autocomplete 端点）。使用此处描述的方法来平衡延迟、准确性和资源成本，以满足您的应用需求。

尝试在您的索引上运行本文中的示例，监控建议质量，并调整 fuzziness 和 min_infix_len 等选项以匹配您的数据和用户。如果您需要一个轻量级的起点，可以为最常见的前缀构建一个短热列表，并通过 CALL AUTOCOMPLETE 路由更长的输入。

构建更智能、更快速的搜索与自动补全。