Brave
本教程为社区贡献，不属于 Open WebUI 团队的官方支持范围。它仅用于演示如何针对特定用例自定义 Open WebUI。想要贡献？请查看贡献教程。
有关与 Web Search 相关的所有环境变量的完整列表（包括并发设置、结果数量等），请参阅 Environment Configuration 环境变量配置文档。
在网页搜索时遇到问题？请参阅 Web Search Troubleshooting Guide 网页搜索故障排除指南 以获取常见问题的解决方案，例如代理配置、连接超时和空内容。
Brave API
Open WebUI 内置了两个由 Brave 支持的搜索引擎，它们共享相同的 API Key（BRAVE_SEARCH_API_KEY）和相同的速率限制，但请求不同的 API 端点（Endpoint）：
| 引擎 (Engine) | 端点 (Endpoint) | 行为 |
|---|---|---|
brave | /res/v1/web/search | 经典网页搜索。返回简短的片段（snippets）；然后 Open WebUI 会抓取每个结果的 URL 来构建 LLM 上下文。 |
brave_llm_context | /res/v1/llm/context | LLM 优化的搜索。直接返回经过预提取且按相关度评分的完整网页段落。完全跳过搜索后的抓取步骤。拉取大小受 BRAVE_SEARCH_CONTEXT_TOKENS 限制（默认值为 8192，范围为 1024–32768）。 |
如果您希望减少网络往返（round-trips）次数、获取更高保真度的 段落而无需抓取步骤，请选择 brave_llm_context；如果您需要经典的“片段-抓取”流程（例如在您的 Pipeline 中，抓取工作会执行一些有用的标准化处理），请选择 brave。在遇到 HTTP 429 错误后，两个引擎都会自动重试一次，并带有 1 秒的退避（backoff）时间。
Docker Compose 设置
将以下环境变量添加到您的 Open WebUI docker-compose.yaml 文件中：
services:
open-webui:
environment:
ENABLE_WEB_SEARCH: True
WEB_SEARCH_ENGINE: "brave" # 也可以是 "brave_llm_context"
BRAVE_SEARCH_API_KEY: "YOUR_API_KEY"
# BRAVE_SEARCH_CONTEXT_TOKENS: 8192 # 仅适用于 brave_llm_context
WEB_SEARCH_RESULT_COUNT: 3
WEB_SEARCH_CONCURRENT_REQUESTS: 1速率限制（免费档）
Brave 的免费层（free tier）API 实施了 每秒 1 次请求 的严格限制。如果您的 LLM 生成了多个搜索查询（这很常见），您可能会遇到 HTTP 429 "Too Many Requests" 错误。
建议免费层用户采用以下配置：
- 在管理面板（Admin Panel） > Settings > Web Search 中将 “Concurrent Requests”（并发请求数）设置为
1。或者使用环境变量： - 设置
WEB_SEARCH_CONCURRENT_REQUESTS: 1以确保请求是按顺序处理而不是并行处理。
自动重试行为：
Open WebUI 会自动处理来自 Brave API 的 429 速率限制响应。当收到速率限制错误时，系 统将：
- 等待 1 秒（遵守 Brave 的速率限制）
- 重新尝试请求一次
- 仅当重试也返回错误时才宣告失败
这意味着，即使您的连接速度足够快，可以在一秒钟内发送多个顺序请求，自动重试机制也应能妥善恢复，而无需用户干预。
如果您使用的是 Brave 的付费层，且拥有更高的速率限制，则可以增加 WEB_SEARCH_CONCURRENT_REQUESTS 以实现更快的并行搜索。
WEB_SEARCH_CONCURRENT_REQUESTS 设置控制的是单个搜索请求的并发性，而不是整个应用程序的全局并发性。
- 不构成问题的情况：对于单用户实例或低流量的设置，用 户极少在完全相同的秒内点击“回车”，将并发限制设置为
1通常足以保持在免费层限制内（1 次请求/秒）。 - 构成问题的情况：如果多个用户在完全相同的时刻触发网页搜索（例如，3 个用户在同一秒内搜索），Open WebUI 将并行处理这些请求。每个用户的请求都会创建自己的连接池，这意味着 3 个请求将同时发送到 API，从而触发免费层的速率限制错误。
注意：如果您运行的环境有多个并发用户活跃地使用网页搜索，强烈建议升级到付费 API 层。免费层并不是为了支持多用户部署的吞吐量而设计的。