External

注意

本教程为社区贡献，不属于 Open WebUI 团队的官方支持范围。它仅用于演示如何针对特定用例自定义 Open WebUI。想要贡献？请查看贡献教程。

提示

有关与 Web Search 相关的所有环境变量的完整列表（包括并发设置、结果数量等），请参阅 Environment Configuration 环境变量配置文档。

故障排除

在网页搜索时遇到问题？请参阅 Web Search Troubleshooting Guide 网页搜索故障排除指南 以获取常见问题的解决方案，例如代理配置、连接超时和空内容。

外部网页搜索 API (External Web Search API)

此选项允许您将 Open WebUI 连接到您自己托管的外部网页搜索 API 端点。如果您希望执行以下操作，这将非常有用：

• 集成 Open WebUI 原生不支持的搜索引擎。
• 实现自定义搜索逻辑、过滤或结果处理。
• 使用私有或内部的搜索索引。

安装与配置

1. 导航到 Open WebUI 的 Admin Panel（管理面板）。
2. 前往 Settings（设置）选项卡，然后选择 Web Search（网页搜索）。
3. 将 Enable Web Search（启用网页搜索）切换至开启位置。
4. 将下拉菜单中的 Web Search Engine（网页搜索引擎）设置为 external。
5. 在 External Search URL 框中填写您自定义搜索 API 端点的完整 URL（例如，http://localhost:8000/search 或 https://my-search-api.example.com/api/search）。
6. 在 External Search API Key 框中填写用于向您的自定义搜索端点进行身份验证的机密 API Key。如果您的端点不需要身份验证，请留空（不建议公开端点使用）。
7. 点击 Save（保存）。

API 规范 (API Specification)

Open WebUI 将通过以下方式与您的 External Search URL 进行交互：

• 方法： POST

• 请求头 (Headers)：

  • Content-Type: application/json
  • Authorization: Bearer <YOUR_EXTERNAL_SEARCH_API_KEY>

• 请求体 (Request Body) (JSON)：

  {
    "query": "The user's search query string",
    "count": 5 // The maximum number of search results requested
  }

  • query（字符串）：用户输入的搜索词。
  • count（整数）：Open WebUI 期望的建议最大结果数。如果需要，您的 API 可以返回较少的结果。

• 期望的响应体 (Response Body) (JSON)： 您的 API 端点 必须 返回搜索结果对象的 JSON 数组。每个对象应包含以下结构：

  [
    {
      "link": "URL of the search result",
      "title": "Title of the search result page",
      "snippet": "A brief description or snippet from the search result page"
    },
    {
      "link": "...",
      "title": "...",
      "snippet": "..."
    }
    // ... potentially more results up to the requested count
  ]

  • link（字符串）：指向搜索结果的直接 URL。

  • title（字符串）：网页的标题。

  • snippet（字符串）：网页内容中与查询相关的描述性文本片段。

    如果发生错误或未找到结果，您的端点理想情况下应返回一个空 JSON 数组 []。

示例实现 (Python/FastAPI)

下面是一个使用 Python 配合 FastAPI 以及 duckduckgo-search 库的自托管搜索 API 简单示例。

import uvicorn
from fastapi import FastAPI, Header, Body, HTTPException
from pydantic import BaseModel
from duckduckgo_search import DDGS

EXPECTED_BEARER_TOKEN = "your_secret_token_here"

app = FastAPI()

class SearchRequest(BaseModel):
    query: str
    count: int

class SearchResult(BaseModel):
    link: str
    title: str | None
    snippet: str | None

@app.post("/search")
async def external_search(
    search_request: SearchRequest = Body(...),
    authorization: str | None = Header(None),
):
    expected_auth_header = f"Bearer {EXPECTED_BEARER_TOKEN}"
    if authorization != expected_auth_header:
        raise HTTPException(status_code=401, detail="Unauthorized")

    query, count = search_request.query, search_request.count

    results = []
    try:
        with DDGS() as ddgs:
            search_results = ddgs.text(
                query, safesearch="moderate", max_results=count, backend="lite"
            )

        results = [
            SearchResult(
                link=result["href"],
                title=result.get("title"),
                snippet=result.get("body"),
            )
            for result in search_results
        ]

    except Exception as e:
        print(f"Error during DuckDuckGo search: {e}")

    return results

if __name__ == "__main__":
    uvicorn.run("main:app", host="0.0.0.0", port=8888)