AI 搜索

适用读者：Halo 站长、主题集成人员

AI 搜索在关键词结果之外生成一段基于站内文章的综合回答，同时保留传统结果供访客继续浏览。

数据路径

• 关键词结果：GET /search/halo-results，直接读取插件 Lucene 索引。
• AI 综合回答：POST /search/answer，进入独立搜索 RAG 流程并使用 SSE。
• 搜索回答不会进入自定义意图路由。

入口依赖说明

AI 搜索的检索能力不依赖 Halo 官方搜索插件：关键词结果来自本插件自己的 Lucene 索引，AI 综合回答也由本插件接口生成。

但默认访客搜索框由 Halo 官方搜索插件提供。因此，启用面向访客的 AI 搜索时，应同时安装并启用 Halo 官方搜索插件。只有当当前主题或自定义代码已经提供可点击的兼容搜索入口时，官方搜索插件才可以省略。

插件仍支持 Ctrl/Cmd + K、/ 快捷键和 window.SearchWidget.open() 调用，但这些属于备用或二次集成方式。页面上没有可见搜索按钮时，普通访客通常不会发现该能力，不能仅凭快捷键可用就认为访客搜索配置完整。

配置步骤

1. 确保文章索引正常。
2. 安装并启用 Halo 官方搜索插件，确认访客页面出现搜索框；若使用主题或自定义入口替代，则确认入口可点击并能打开 AI 搜索。
3. 开启搜索功能。
4. 按需开启 AI 综合回答。
5. 设置关键词结果数量、专用 System Prompt 和输出上限。
6. 独立设置搜索主题与主题色。
7. 在实时预览中验证关键词结果和回答区域。

访客端效果

访客从主题搜索入口或快捷键打开 AI 搜索后，可以在同一弹框中看到两类结果：上方是带站内引用的 AI 综合回答，下方保留传统关键词结果。点击引用或文章标题可以继续阅读原文。

提示词建议

搜索回答应短于聊天回答，直接总结结果差异，并避免生成索引中不存在的文章。专用提示词为空时会回退到对话提示词。

常见问题

现象	检查
关键词结果为空	索引、搜索总开关、文章是否公开
有关键词结果但无 AI 回答	showAiAnswer、Chat 模型、SSE 代理
页面上没有搜索按钮	优先检查 Halo 官方搜索插件是否安装并启用；若不使用官方插件，必须由主题或自定义代码提供兼容入口
搜索入口没有接管主题	主题是否暴露 window.SearchWidget.open()、Widget 注入和浏览器控制台
回答最后一次性出现	Nginx/CDN 缓冲
结果摘要含危险 HTML	前端应保持当前清洗逻辑，不直接渲染未知 HTML

验证

• 使用文章标题中的精确词测试关键词结果。
• 使用语义问题测试 AI 综合回答。
• 确认传统结果和 AI 引用指向同一站点文章。
• 点击访客页面上可见的搜索框或搜索按钮，确认能打开 AI 搜索。
• 再补充验证 Ctrl/Cmd + K、/ 快捷键，确保备用入口可用。

相关接口见 Public API。