Higress ai-search 插件深度解析：为 LLM 接入 Google/Bing/Arxiv/Elasticsearch/夸克搜索引擎增强回答能力

Higress ai-search 插件深度解析为 LLM 接入 Google/Bing/Arxiv/Elasticsearch/夸克搜索引擎增强回答能力【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higressHigress 的ai-search插件通过在请求转发到 LLM 之前并行调用多个搜索引擎把实时搜索结果注入到提示模板中并可自动在最终回答里追加引用来源。本文基于插件的官方文档 README.md 与源码实现main.go、engine/types.go 及各引擎实现完整讲解其运行属性、全部配置字段、搜索重写机制与各类配置示例帮助你在 Higress 网关上为 DeepSeek 等模型构建带联网检索、论文检索或私有知识库检索能力的 AI 服务。一、功能定位与运行机制插件的核心逻辑是拦截 OpenAI 兼容格式的聊天请求从messages中取出最后一条 user 消息作为查询词向配置的搜索引擎发起检索将结果格式化后填充进提示模板并替换原请求体再放行到上游 LLM响应阶段则根据配置决定是否把引用来源标题链接列表插入回答内容中。关键运行属性属性值说明执行阶段默认阶段在转发到 LLM 供应商之前执行保证能先改写 prompt执行优先级460优先级数值越大越先执行需排在请求改写类插件之前从源码结构看插件通过 main.go 的init()注册了完整的请求/响应处理链onHttpRequestHeaders校验content-type是否为 JSON非 JSON 直接跳过移除Accept-Encoding、Content-Length头并设置 100MB 的请求体缓冲上限onHttpRequestBody提取用户查询、执行搜索或先执行搜索重写、替换请求体onHttpResponseHeaders/onStreamingResponseBody/onHttpResponseBody仅在开启needReference时介入负责将引用来源分别插入流式 SSE 响应或非流式响应。一个值得注意的设计是失败快速降级当搜索重写调用 LLM 失败、或所有引擎都没有返回结果时插件会记录日志并直接ResumeHttpRequest放行原请求即搜索失败不阻塞对话。二、插件配置字段详解2.1 顶层配置字段名称数据类型填写要求默认值描述defaultEnablebool选填true插件功能默认是否开启。设置为 false 时仅当请求中包含web_search_options字段时才启用插件功能needReferencebool选填false是否在回答中添加引用来源referenceFormatstring选填**References:**\n%s引用内容格式必须包含%s占位符配置不合法会在启动时直接报错referenceLocationstring选填head引用位置head在回答开头tail在回答结尾defaultLangstring选填-默认搜索语言代码如 zh-CN/en-USpromptTemplatestring选填内置模板提示模板必须包含{search_results}和{question}占位符缺少任一占位符配置校验会失败searchFromarray of object必填-搜索引擎配置列表至少配置一个引擎否则配置解析报错no available search engine foundsearchRewriteobject选填-搜索重写配置用于使用 LLM 服务优化搜索查询关于promptTemplate如果不开启needReference内置模板只要求模型综合多个网页回答但不给出网页引用来源如果开启needReference内置模板会额外要求模型在正文对应位置以[X]编号形式引用可多引用如[3][5]并要求区分列举类、创作类、客观问答类问题分别采用不同的回答策略。两种内置模板都包含{cur_date}占位符由插件在运行时填入北京时间当日日期格式2006年1月2日可用于增强时效性问答的准确性。2.2 搜索引擎通用配置searchFrom数组中每个引擎项共享以下字段名称数据类型填写要求默认值描述typestring必填-引擎类型google/bing/arxiv/elasticsearch/quarkserviceNamestring必填-后端服务名称Higress 中的服务来源 FQDN 集群servicePortnumber必填-后端服务端口apiKeystring必填*-搜索引擎 API 密钥Arxiv 免费接口不需要countnumber选填10单次搜索返回结果数量startnumber选填0搜索结果偏移量从第 start1 条结果开始返回timeoutMillisecondnumber选填5000API 调用超时时间毫秒optionArgsmap选填-搜索引擎特定参数key-value 格式直接拼接到请求 URL 上源码中每个引擎都实现了统一的 SearchEngine 接口NeedExectue/Client/CallArgs/ParseResult各引擎通过NeedExectue判断是否响应当前搜索上下文见下文搜索重写这是多引擎并行检索的扩展点。三、各搜索引擎的具体实现与特定配置3.1 Google 搜索特定配置名称数据类型填写要求默认值描述cxstring必填-Google 自定义搜索引擎 ID用于指定搜索范围从 google.go 源码可以看到几个关键实现细节参数校验约束初始化时强制要求count小于 10 且start count 100超限直接配置失败。这与 Google Custom Search API 单页最多 10 条、最大偏移 100 条的协议限制一致因此要取更多结果必须用多条目 start 递增的并发方案见第五节配置示例请求构造调用customsearch.googleapis.com/customsearch/v1start参数按 Google 协议传的是start1defaultLang会转换成lrlang_XX参数附加到 URL 上结果解析除snippet摘要外还会读取pagemap.metatags.0.og:description网页的 og:description 元数据并以...\n分隔拼接到正文内容中为 LLM 提供更丰富的上下文去重多引擎结果合并时以Link为键去重见 main.go。3.2 Bing 搜索apiKey通过Ocp-Apim-Subscription-Key请求头传递调用api.bing.microsoft.com/v7.0/searchdefaultLang映射为mkt参数。从 bing.go 的解析逻辑看Bing 引擎不只返回webPages.value网页结果还会解析deepLinks每个网页下的站内子链接作为独立结果展开news.value新闻结果以description字段作为正文内容。因此在optionArgs中传入answerCount、responseFilter如包含 news等参数可以进一步控制返回类型。3.3 Arxiv 论文搜索特定配置名称数据类型填写要求默认值描述arxivCategorystring选填-搜索的论文类别如 cs.AI, cs.CL 等Arxiv 官方类别分类法Arxiv 是免费开放接口不需要 API Key。从 arxiv.go 看其请求与解析特点是查询词会被转换成all:关键词形式多关键词之间以AND连接如果搜索重写识别出了论文类别运行时优先级高于静态配置的arxivCategory还会追加ANDcat:类别限定最终请求export.arxiv.org/api/query?search_query...max_results...start...返回 Atom XML 格式解析每条论文时提取 title、alternate 链接、摘要summary、作者列表与发布时间并格式化为摘要 Authors Publication time的正文喂给 LLM。3.4 Elasticsearch 私有知识库搜索特定配置名称数据类型填写要求默认值描述indexstring必填-要搜索的 Elasticsearch 索引名称contentFieldstring必填-要查询的内容字段名称semanticTextFieldstring必填-要查询的 embedding 字段名称linkFieldstring选填-结果链接字段名称当配置needReference时需要填写否则初始化报错titleFieldstring选填-结果标题字段名称当配置needReference时需要填写usernamestring选填-Elasticsearch 用户名passwordstring选填-Elasticsearch 密码从 elasticsearch.go 可以看到插件发送的是一个混合检索Hybrid Search请求体使用rrfReciprocal Rank Fusion倒数排名融合检索器同时执行两路检索——基于contentField的match标准全文匹配BM25 语义基于semanticTextField的semantic向量检索再由 RRF 融合两路排名得到最终结果。请求 URL 为/{index}/_search?from{start}size{count}认证走 Basic Auth 头。版本与 License 前提RRF 查询要求 Elasticsearch 版本在8.8 及以上文档向量化依赖 Elasticsearch 内置 Embedding 模型semantic_text 能力该功能需要 Elasticsearch 企业版 License 或 30 天 Trial License如需改用第三方 Embedding 模型可按 Elasticsearch 官方向量搜索文档自行部署。另外main.go 中在初始化 ES 引擎时会把needReference传入用于在插件启动阶段就校验linkField/titleField是否齐全避免运行期才发现配置缺失。3.5 夸克Quark搜索特定配置名称数据类型填写要求默认值描述contentModestring选填summary内容模式summary使用摘要snippetfull使用正文优先 markdownText为空则用 mainText从 quark.go 看夸克引擎调用阿里云 IQS 的cloud-iqs.aliyuncs.com通用搜索接口apiKey以X-API-Key头传递结果按pageItems数组解析并在客户端侧按count截断index count。contentMode取值非法时配置会直接校验失败这是五个引擎中少数在启动期做枚举值校验的字段。一个实现细节如果searchFrom中只配置了 quark 引擎搜索重写会自动选用中文互联网专用提示词见 4.2 节以更好地适配中文互联网内容检索。四、搜索重写searchRewrite用 LLM 优化检索4.1 功能与适用场景搜索重写功能先调用一个可配置的 LLM 服务对用户的原始查询进行分析作用包括判断是否需要搜索——如果用户消息不是提问如闲聊、翻译要求LLM 会返回none插件直接放行原请求完全不触发搜索逻辑查询改写——把自然语言问题转成更适合搜索引擎的关键词组合Arxiv 类别识别——自动判断问题所属论文领域并添加cat:类别限定私有库关键词拆分——把长查询拆成多个精准关键词组合逗号分隔。官方文档强烈建议在使用 Arxiv 或 Elasticsearch 引擎时启用此功能对 Arxiv 搜索它能准确识别论文领域并优化英文关键词对私有知识库搜索它能提供更精准的关键词匹配。4.2 配置字段名称数据类型填写要求默认值描述llmServiceNamestring必填-LLM 服务名称Higress 服务来源llmServicePortnumber必填-LLM 服务端口llmApiKeystring选填-LLM 服务 API 密钥以 Bearer Token 传递llmUrlstring必填-LLM 服务 API 地址OpenAI 兼容 chat/completionsllmModelNamestring必填-LLM 模型名称timeoutMillisecondnumber选填30000API 调用超时时间毫秒maxCountnumber选填3搜索重写生成的最大查询次数配置解析逻辑在 main.go四个必填字段任一缺失都会导致插件启动失败maxCount会被注入到重写提示词的{max_count}占位符中。4.3 提示词按引擎组合自动选择插件内置了五份搜索重写提示词prompts 目录配置加载时按已启用引擎的组合自动选用已配置的引擎组合选用的提示词文件说明Arxiv 私有库 互联网full.md全场景Arxiv 互联网无私有库arxiv.md含完整的 Arxiv Category 枚举表私有库 互联网private.md区分 internet:/private: 两类查询仅互联网含 google/bing 等internet.md基础联网查询改写仅 quarkchinese-internet.md面向中文互联网优化以 internet.md 为例重写提示词要求 LLM 按 What → How → Adjust → Final 的思路分析并按固定格式输出internet: 黄金价格走势 internet: The trend of gold prices每行以internet:/private:/ Arxiv Category如cs.AI:为前缀多行用换行分隔总条数不超过maxCount若判断无需搜索则只输出none。arxiv.md 中还内嵌了完整的 Arxiv Category 枚举清单cs.、math.、quant-ph、stat.* 等供 LLM 判定论文领域时查表使用。4.4 重写结果到搜索上下文的映射main.go 将 LLM 返回的每行解析为SearchContextinternet: xxx→ 互联网引擎google/bing/quark 均响应其NeedExectue对internet/空上下文均返回 trueprivate: a,b→ 按逗号拆分为多个关键词仅 Elasticsearch 引擎响应其他前缀即 Arxiv Category→ 仅 Arxiv 引擎响应并携带类别限定。源码中还有一个提升召回率的策略当识别出 Arxiv 类别时会同时再追加一个不带类别限定的备份查询确保不因类别误判而漏检重写请求失败或输出中不含任何有效上下文时均直接放行原始请求不搜索。五、完整配置示例以下示例全部继承自官方 README可直接复制到 Higress 控制台或WasmPlugin资源中使用注意serviceName需先在服务来源中配置好对应域名如customsearch.googleapis.com、api.bing.microsoft.com、cloud-iqs.aliyuncs.com、export.arxiv.org可参考仓库内同目录的 guide.md 中的分步教程。5.1 基础配置单搜索引擎needReference: true searchFrom: - type: google apiKey: your-google-api-key cx: search-engine-id serviceName: google-svc.dns servicePort: 443 count: 5 optionArgs: fileType: pdf5.2 Arxiv 搜索配置searchFrom: - type: arxiv serviceName: arxiv-svc.dns servicePort: 443 arxivCategory: cs.AI count: 105.3 夸克搜索配置searchFrom: - type: quark serviceName: quark-svc.dns servicePort: 443 apiKey: quark api key contentMode: full # 可选值summary(默认)或full5.4 多搜索引擎配置defaultLang: en-US promptTemplate: | # Search Results: {search_results} # Please answer this question: {question} searchFrom: - type: google apiKey: google-key cx: github-search-id # 专门搜索GitHub内容的搜索引擎ID serviceName: google-svc.dns servicePort: 443 - type: google apiKey: google-key cx: news-search-id # 专门搜索Google News内容的搜索引擎ID serviceName: google-svc.dns servicePort: 443 - type: bing apiKey: bing-key serviceName: bing-svc.dns servicePort: 443 optionArgs: answerCount: 55.5 并发查询分页取更多结果由于搜索引擎对单次查询返回结果数量有限制如 Google 单次最多 100 条且单页不超过 10 条可以通过小 count start 偏移 多条目并发的方式获取更大结果集。例如要获取 30 条结果可配置 count10 并配置三个查询start 分别为 0、10、20searchFrom: - type: google apiKey: your-google-api-key cx: search-engine-id serviceName: google-svc.dns servicePort: 443 start: 0 count: 10 - type: google apiKey: your-google-api-key cx: search-engine-id serviceName: google-svc.dns servicePort: 443 start: 10 count: 10 - type: google apiKey: your-google-api-key cx: search-engine-id serviceName: google-svc.dns servicePort: 443 start: 20 count: 10注意过高的并发可能会导致被搜索引擎限流需要根据实际情况调整。5.6 Elasticsearch 配置对接私有知识库searchFrom: - type: elasticsearch serviceName: es-svc.static index: knowledge_base contentField: content semanticTextField: semantic_text # username: elastic # password: password5.7 自定义引用格式与位置needReference: true referenceFormat: ### 数据来源\n%s searchFrom: - type: bing apiKey: your-bing-key serviceName: search-service.dns servicePort: 8080needReference: true referenceLocation: tail # 在回答结尾添加引用而不是开头 searchFrom: - type: bing apiKey: your-bing-key serviceName: search-service.dns servicePort: 80805.8 搜索重写配置searchFrom: - type: google apiKey: your-google-api-key cx: search-engine-id serviceName: google-svc.dns servicePort: 443 searchRewrite: llmServiceName: llm-svc.dns llmServicePort: 443 llmApiKey: your-llm-api-key llmUrl: https://api.example.com/v1/chat/completions llmModelName: gpt-3.5-turbo timeoutMillisecond: 150005.9 按需启用插件兼容 OpenAI 搜索模型协议defaultEnable: false searchFrom: - type: google apiKey: your-google-api-key cx: search-engine-id serviceName: google-svc.dns servicePort: 443配置defaultEnable: false后只有当请求体中包含web_search_options字段时插件才激活即使是空对象web_search_options: {}也会激活可以兼容 OpenAI 的搜索模型协议让同一 LLM 端点根据客户端是否要求联网来动态开关搜索增强。5.10 动态调整搜索深度search_context_size在请求的web_search_options中携带search_context_size参数可动态调整搜索查询次数{ web_search_options: { search_context_size: medium } }search_context_size支持三个级别见 main.go取值效果适用场景low生成 1 个搜索查询简单问题medium生成 3 个搜索查询默认值常规问题high生成 5 个搜索查询复杂问题该设置会覆盖配置中的maxCount值并在每次请求时基于原始提示词模板重新替换{max_count}占位符允许客户端按问题复杂度动态调整搜索深度。传入未知值时插件会打警告日志并回退使用配置的maxCount。六、引用来源注入的实现细节开启needReference后插件在搜索阶段就为每条结果生成了[序号] 标题形式的引用列表main.go并按referenceLocation在响应阶段注入非流式响应onHttpResponseBody读取choices.0.message.content若回答以think开头如 DeepSeek-R1 等推理模型默认会把引用插在/think之后即思考过程与正式回答之间否则按 head/tail 位置拼接后整体替换。流式 SSE 响应onStreamingResponseBody实现更为精细——head 模式对choices.0.delta.content做 30 字节滑动缓冲确认首段内容不是think后在首个 delta 前拼接引用若首段是思考内容则持续缓冲直到检测到完整的/think标签再插入并能处理 【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考