跳到主要内容

网页搜索

Open WebUI 中的网页搜索允许语言模型从互联网实时调取最新信息。当系统表现未达预期时，本指南将协助您排查和解决常见的故障。

常见的网页搜索问题​

1. 在 HTTP 代理后网页搜索失败​

如果您在 HTTP 代理之后运行 Open WebUI，您可能会注意到搜索查询本身是成功的（例如，SearXNG 能够正常返回链接列表），但随后的网页正文提取却以失败告终，日志中输出类似于以下报错：

  • [Errno -3] Temporary failure in name resolution（临时域名解析失败）
  • Connection timeout to host（主机连接超时）
  • The content provided is empty（提供的内容为空）

出现这种故障的原因是网页内容抓取器（fetcher）在默认情况下不会读取您的 http_proxy / https_proxy 环境变量。

✅ 解决方案：

  1. 导航至：Admin Panel（管理员面板） > Settings（设置） > Web Search（网页搜索）
  2. 勾选启用 Trust Proxy Environment（信任代理环境）
  3. 保存设置

或者，您也可以直接在启动时配置环境变量 WEB_SEARCH_TRUST_ENV：

WEB_SEARCH_TRUST_ENV=True
信息

这是一个 PersistentConfig（持久化配置）变量，这意味着它既可以在启动时通过环境变量配置，也可以在管理员面板界面中进行配置。一旦在图形界面中设置并保存，数据库中的配置值将优先于环境变量生效。

该项配置旨在告知 Open WebUI 的网页内容加载模块去主动遵循您操作系统环境变量中的代理设置（http_proxy、https_proxy）。如果不开启此项，即便您的搜索引擎可以通过代理正常调取链接，在对搜索到的链接内容进行正文抓取时依然会因为无法穿透代理而报错。

2. 来自 SearXNG 的 403 Forbidden（禁止访问）错误​

如果您使用 SearXNG 作为搜索引擎，且在后端日志中持续看到 403 Client Error: Forbidden 报错，说明 SearXNG 端的 JSON 格式输出未被启用。

✅ 解决方案：

修改您 SearXNG 服务的 settings.yml 配置文件，并在 formats 格式白名单中加入 json 选项：

search:
  formats:
    - html
    - json

修改完成后，请重启您的 SearXNG 实例以使配置生效。

3. 内容为空或召回质量低劣​

如果网页搜索召回的内容为空，或整体召回质量很差，这通常是因为 context 窗口太窄或内容提取出现了偏差。

✅ 解决方案：

  • 调大模型的 context 长度参数：普通网页常常包含多达 4,000 至 8,000+ 字符的 Token 占用。如果您的模型 context 限制仅为 2048 Tokens，您将会直接错失掉绝大部分的主体正文。请导航至 Admin Panel > Models > Settings > Advanced Parameters 将其配置到 16384+ Tokens（任何低于此阈值的限制都会使网页搜索效果大打折扣）。

  • 核实检索结果的数量：调整 WEB_SEARCH_RESULT_COUNT 变量，以微调每次搜索时应该抓取多少个网页。

    在 Native/Agentic 智能体工具调用模式下，如果大模型在调用 search_web 工具时省略了 count 参数，Open WebUI 将默认使用全局的 WEB_SEARCH_RESULT_COUNT 参数。如果模型自主指定了 count，其最大限制依然会被锁定在管理员在后台配置的上限内。

  • 更换抓取引擎：调整 WEB_LOADER_ENGINE 变量，对于那些使用了大量 JavaScript 渲染的复杂网页，建议将其改为 playwright；或接入 firecrawl / tavily 以获取更加干净完美的正文提取质量。

有关 context 窗口限制的更多原理解释，请参阅 RAG 排障指南。

4. 网络连接超时​

如果网页搜索频繁发生超时无响应：

✅ 解决方案：

  • 限制并发请求量：配置 WEB_SEARCH_CONCURRENT_REQUESTS=1 以使用单线程串行请求（这对于使用 Brave 免费版接口的实例是硬性要求）。

  • 调低网页加载并发数：如果您单次需要抓取大量的网页，建议调小 WEB_LOADER_CONCURRENT_REQUESTS 的参数。

  • 测试底层网络连通性：确保 Open WebUI 部署实例的所在网络能够畅通访问对应的搜索引擎接口，并能顺利连通搜索结果中的每一个目标 URL。

环境变量参考手册​

有关所有网页搜索相关环境变量的完整清单，请参考 环境变量配置手册。

核心变量速查：

环境变量名作用与功能说明
WEB_SEARCH_TRUST_ENV允许在网页内容抓取时读取系统代理环境
WEB_SEARCH_RESULT_COUNT单次搜索允许抓取的结果网页最大数量
WEB_SEARCH_CONCURRENT_REQUESTS对搜索引擎接口发起的最大并发请求数
WEB_LOADER_CONCURRENT_REQUESTS抓取网页正文时的最大并发执行数
WEB_LOADER_ENGINE抓取网页所采用的内容提取引擎类型
This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.