6.5 · 网页搜索集成（Web Search Integration）

网页搜索集成（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/6.5-web-search-integration

翻译时间：2026-06-09T16:09:01.178Z

翻译模型：deepseek-chat

原文字符数：13369

项目：Open WebUI (open-webui)

---

网页搜索集成

相关源文件

以下文件被用作生成此 wiki 页面的上下文：

• .github/workflows/integration-test.disabled
• backend/open_webui/models/memories.py
• backend/open_webui/retrieval/loaders/datalab_marker.py
• backend/open_webui/retrieval/loaders/main.py
• backend/open_webui/retrieval/loaders/mineru.py
• backend/open_webui/retrieval/loaders/paddleocr_vl.py
• backend/open_webui/retrieval/utils.py
• backend/open_webui/retrieval/web/firecrawl.py
• backend/open_webui/retrieval/web/utils.py
• backend/open_webui/routers/memories.py
• backend/open_webui/routers/retrieval.py
• backend/open_webui/storage/provider.py
• backend/open_webui/test/apps/webui/storage/test_provider.py
• backend/open_webui/tools/builtin.py
• backend/open_webui/utils/middleware.py
• backend/open_webui/utils/tools.py
• backend/requirements-min.txt
• backend/requirements.txt
• docker-compose.playwright.yaml
• pyproject.toml
• src/lib/apis/retrieval/index.ts
• src/lib/components/admin/Settings/Documents.svelte
• src/lib/components/admin/Settings/WebSearch.svelte
• src/lib/components/workspace/Models/BuiltinTools.svelte
• uv.lock

网页搜索集成使 Open WebUI 能够利用来自互联网的实时信息增强 LLM 响应。启用后，系统会根据用户消息生成搜索查询，使用可配置的搜索引擎执行搜索，检索并处理网页内容，并可选择通过 RAG 管道集成结果，为响应提供事实依据。

有关更广泛的 RAG 文档处理系统的信息，请参阅 RAG 与知识系统。有关聊天中间件编排的详细信息，请参阅 聊天中间件与请求流程。

用途与架构

网页搜索系统提供了一个多阶段管道，将用户查询转换为丰富的上下文：

1. 查询生成：LLM 根据对话上下文生成优化的搜索查询 backend/open_webui/utils/middleware.py:37-43。
2. 搜索执行：可配置的搜索引擎通过 process_web_search 函数返回相关 URL backend/open_webui/routers/retrieval.py:45-83。
3. 内容加载：网页加载器使用 get_web_loader 从发现的 URL 中提取文本内容 backend/open_webui/retrieval/web/utils.py:78-83。
4. RAG 集成：可选地，使用混合搜索对内容进行嵌入和检索 backend/open_webui/retrieval/utils.py:91-95。
5. 上下文注入：在中间件管道执行期间，结果被格式化并添加到聊天负载中 backend/open_webui/utils/middleware.py:44-47。

网页搜索管道架构

graph TD
    UserMessage["用户消息"]
    ChatHandler["chat_web_search_handler"]
    QueryGen["generate_queries"]
    TaskModel["TASK_MODEL LLM"]
    ProcessSearch["process_web_search"]

    subgraph "搜索引擎层"
        EngineRouter["WEB_SEARCH_ENGINE"]
        BraveEngine["search_brave"]
        GoogleEngine["search_google_pse"]
        SearxngEngine["search_searxng"]
        TavilyEngine["search_tavily"]
        DuckDuckGoEngine["search_duckduckgo"]
        ExternalEngine["search_external"]
        OtherEngines["13+ 其他引擎"]
    end

    subgraph "网页内容加载"
        LoaderRouter["WEB_LOADER_ENGINE"]
        PlaywrightLoader["Playwright 浏览器"]
        FirecrawlLoader["Firecrawl API"]
        TavilyLoader["Tavily Extract"]
        ExternalLoader["外部加载器 API"]
        DefaultLoader["get_web_loader"]
    end

    subgraph "可选的 RAG 处理"
        EmbedDecision{"BYPASS_WEB_SEARCH_EMBEDDING_AND_RETRIEVAL?"}
        ChunkText["文本分割"]
        EmbedVectors["嵌入生成"]
        VectorStore["VECTOR_DB_CLIENT"]
        HybridSearch["混合搜索 + 重排序"]
    end

    FormData["包含 files[] 的 form_data"]

    UserMessage --> ChatHandler
    ChatHandler --> QueryGen
    QueryGen --> TaskModel
    TaskModel --> ProcessSearch

    ProcessSearch --> EngineRouter
    EngineRouter --> BraveEngine
    EngineRouter --> GoogleEngine
    EngineRouter --> SearxngEngine
    EngineRouter --> TavilyEngine
    EngineRouter --> DuckDuckGoEngine
    EngineRouter --> ExternalEngine
    EngineRouter --> OtherEngines

    BraveEngine --> LoaderRouter
    GoogleEngine --> LoaderRouter
    SearxngEngine --> LoaderRouter
    TavilyEngine --> LoaderRouter
    DuckDuckGoEngine --> LoaderRouter

    LoaderRouter --> PlaywrightLoader
    LoaderRouter --> FirecrawlLoader
    LoaderRouter --> TavilyLoader
    LoaderRouter --> ExternalLoader
    LoaderRouter --> DefaultLoader

    PlaywrightLoader --> EmbedDecision
    FirecrawlLoader --> EmbedDecision
    TavilyLoader --> EmbedDecision
    ExternalLoader --> EmbedDecision
    DefaultLoader --> EmbedDecision

    EmbedDecision -->|"否（嵌入）"| ChunkText
    ChunkText --> EmbedVectors
    EmbedVectors --> VectorStore
    VectorStore --> HybridSearch
    HybridSearch --> FormData

    EmbedDecision -->|"是（绕过）"| FormData

来源：backend/open_webui/utils/middleware.py:37-47, backend/open_webui/routers/retrieval.py:45-83, backend/open_webui/retrieval/web/utils.py:27-49

配置系统

网页搜索配置通过后端的配置系统进行管理，通过管理 UI 暴露，并存储在数据库中，同时支持 Redis 同步。

支持的搜索引擎

系统支持广泛的引擎，包括 ollama_cloud、perplexity_search、searxng、yacy、google_pse、brave、kagi、mojeek、bocha、serpstack、serper、serply、searchapi、serpapi、duckduckgo、tavily、jina、bing、exa、perplexity、sougou、firecrawl、external、yandex 和 youcom src/lib/components/admin/Settings/WebSearch.svelte:16-42。

网页加载器引擎

内容提取可由多个引擎执行，包括 playwright、firecrawl、tavily 和 external src/lib/components/admin/Settings/WebSearch.svelte:43。

来源：src/lib/components/admin/Settings/WebSearch.svelte:16-43, backend/open_webui/routers/retrieval.py:54-83

查询生成过程

网页搜索查询使用 LLM 任务模型生成，以优化搜索效果。系统通过 generate_queries 函数将对话历史发送给任务模型 backend/open_webui/routers/tasks.py:38。

查询生成流程

sequenceDiagram
    participant Handler as chat_web_search_handler
    participant GenQueries as generate_queries
    participant TaskModel as TASK_MODEL LLM
    participant EventEmitter as __event_emitter__

    Handler->>EventEmitter: emit(type: "status", action: "web_search")
    Handler->>GenQueries: model, messages, prompt, type: "web_search"

    GenQueries->>TaskModel: POST /chat/completions<br/>{model, messages, prompt}
    TaskModel-->>GenQueries: {"queries": ["query1", "query2", ...]}

    alt 有效的 JSON 响应
        GenQueries->>GenQueries: 解析 { 和 } 之间的 JSON
        GenQueries->>GenQueries: 提取 queries 数组
    else 解析错误
        GenQueries->>GenQueries: 将原始响应作为单个查询
    end

    GenQueries-->>Handler: queries: List[str]

    Handler->>EventEmitter: emit(type: "status",<br/>action: "web_search_queries_generated",<br/>queries: queries)

该实现依赖 get_event_emitter 在查询生成和搜索过程中向前端提供实时状态更新 backend/open_webui/utils/middleware.py:33-36。

来源：backend/open_webui/utils/middleware.py:33-43, backend/open_webui/routers/tasks.py:38

搜索引擎实现

每个搜索引擎都实现为专用模块。检索路由器中的 process_web_search 函数 backend/open_webui/routers/retrieval.py:45 负责编排对特定引擎函数的调用。

引擎	实现函数	来源
Brave	search_brave	backend/open_webui/routers/retrieval.py:59
DuckDuckGo	search_duckduckgo	backend/open_webui/routers/retrieval.py:63
Tavily	search_tavily	backend/open_webui/routers/retrieval.py:73
SearXNG	search_searxng	backend/open_webui/routers/retrieval.py:68
Google PSE	search_google_pse	backend/open_webui/routers/retrieval.py:64
Jina	search_jina	backend/open_webui/routers/retrieval.py:65

来源：backend/open_webui/routers/retrieval.py:54-83

网页内容加载

搜索引擎返回 URL 后，网页加载器子系统会获取并提取文本内容。get_web_loader 工具 backend/open_webui/retrieval/web/utils.py:78 决定使用哪个引擎。

URL 验证

URL 通过 validate_url backend/open_webui/retrieval/web/utils.py:67 进行验证，该函数检查协议（仅允许 http 和 https）并强制执行黑名单 backend/open_webui/retrieval/web/utils.py:75-83。如果禁用了 ENABLE_RAG_LOCAL_WEB_FETCH，它还会通过解析主机名并检查私有 IP 范围来阻止本地网页获取 backend/open_webui/retrieval/web/utils.py:85-95。

内容提取

使用 get_content_from_url backend/open_webui/retrieval/utils.py:176 从 URL 中提取文本。该函数处理：

1. URL 验证 backend/open_webui/retrieval/utils.py:180。
2. Content-Type 检查，以区分文本/HTML 和二进制文件 backend/open_webui/retrieval/utils.py:184-192。
3. 通过 _extract_text_from_binary_response backend/open_webui/retrieval/utils.py:127-164 进行二进制提取（PDF、Docx 等）。

来源：backend/open_webui/retrieval/web/utils.py:67-95, backend/open_webui/retrieval/utils.py:127-192

结果处理与 RAG 集成

网页搜索结果可根据配置通过两种模式进行处理：

绕过模式（直接内容注入）

原始内容直接附加到消息负载中，无需向量存储。这适用于具有大上下文窗口的模型。

RAG 模式（向量存储与检索）

内容流经完整的 RAG 管道，涉及文本分割和嵌入生成。

RAG 集成流程

sequenceDiagram
    participant Search as process_web_search
    participant TextSplit as 文本分割器
    participant Embed as get_ef
    participant Vector as VECTOR_DB_CLIENT
    participant Context as get_sources_from_items

    Search->>Search: 加载网页内容（文档）
    Search->>TextSplit: RecursiveCharacterTextSplitter

    Search->>Embed: 通过 SentenceTransformer 生成向量

    Search->>Vector: add(collection_name, documents, vectors)
    Vector-->>Search: collection_name

    Note over Context: 稍后在中间件管道中

    Context->>Vector: query_collection(collection_name)
    Vector-->>Context: 排序后的文档块

系统使用 VECTOR_DB_CLIENT backend/open_webui/retrieval/vector/factory.py:47 进行同步操作，使用 ASYNC_VECTOR_DB_CLIENT backend/open_webui/retrieval/vector/async_client.py:48 进行检索期间的异步操作。

来源：backend/open_webui/routers/retrieval.py:32-36, backend/open_webui/retrieval/utils.py:74, backend/open_webui/retrieval/vector/factory.py:47

配置 UI

管理设置界面通过 WebSearch.svelte src/lib/components/admin/Settings/WebSearch.svelte:1-127 提供全面的网页搜索配置。

配置持久化流程

sequenceDiagram
    participant UI as WebSearch.svelte
    participant API as updateRAGConfig
    participant Backend as retrieval.py
    participant DB as PersistentConfig

    UI->>API: updateRAGConfig(token, {web: config})
    API->>Backend: POST /api/v1/retrieval/config/update
    Backend->>DB: 更新值（ENABLE_WEB_SEARCH 等）

前端在发送到后端之前，会将 UI 状态（例如用于域名过滤器的逗号分隔字符串）转换为数组 src/lib/components/admin/Settings/WebSearch.svelte:49-58。

来源：src/lib/components/admin/Settings/WebSearch.svelte:1-127, src/lib/apis/retrieval/index.ts:17