13.3 · OpenAI 集成（OpenAI Integration）

多模型对话工作台与知识应用入口 · 本章是 Open WebUI DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Open WebUI 章节13.3 状态全文译文模块认证、权限与安全、工具、记忆与模型调用、系统架构、接口与服务契约

项目要点页2.5 参考项目项目章节目录Open WebUI DeepWiki 原始章节OpenAI Integration 上一章13.2 下一章13.4

源码线索

backend/open_webui/routers/ollama.py
backend/open_webui/routers/openai.py
backend/open_webui/utils/embeddings.py
backend/open_webui/utils/misc.py
backend/open_webui/utils/payload.py
backend/open_webui/utils/response.py
src/lib/apis/ollama/index.ts
src/lib/apis/openai/index.ts
src/lib/components/chat/Settings/Connections.svelte
payload.py

模块标签

认证、权限与安全
工具、记忆与模型调用
系统架构
接口与服务契约
界面与交互

中文译文

OpenAI 集成（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/13.3-openai-integration

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

翻译模型：deepseek-chat

原文字符数：11727

项目：Open WebUI (open-webui)

---

OpenAI 集成

系统架构

OpenAI 集成实现为一个 FastAPI 路由器，它将请求代理到一个或多个兼容 OpenAI 的后端，同时提供模型访问控制、请求转换和响应缓存等附加功能。

组件概览

graph TB
    Client["客户端应用"]
    Router["openai.py 路由器<br/>/openai/*"]

    subgraph "配置层"
        Config["AppConfig"]
        EnvVars["环境变量<br/>OPENAI_API_BASE_URLS<br/>OPENAI_API_KEYS<br/>OPENAI_API_CONFIGS"]
    end

    subgraph "请求处理"
        Headers["get_headers_and_cookies()<br/>认证与请求头"]
        ModelFilter["get_filtered_models()<br/>访问控制"]
        ReasoningHandler["openai_reasoning_model_handler()<br/>o1-* 模型转换"]
    end

    subgraph "外部 API"
        OpenAI["OpenAI API<br/>api.openai.com"]
        Azure["Azure OpenAI"]
        Anthropic["Anthropic API<br/>（通过 get_anthropic_models）"]
        Custom["自定义兼容 OpenAI<br/>的端点"]
    end

    subgraph "响应处理"
        Cache["@cached TTL<br/>MODELS_CACHE_TTL"]
        AccessControl["check_model_access()<br/>模型权限"]
    end

    Client -->|HTTP 请求| Router
    Router --> Config
    Config --> EnvVars
    Router --> Headers
    Headers --> ModelFilter
    ModelFilter --> AccessControl
    Router --> ReasoningHandler

    Router -->|代理请求| OpenAI
    Router -->|代理请求| Azure
    Router -->|代理请求| Anthropic
    Router -->|代理请求| Custom

    OpenAI --> Cache
    Azure --> Cache
    Anthropic --> Cache
    Custom --> Cache

    Cache -->|响应| Client

来源： backend/open_webui/routers/openai.py:1-68, backend/open_webui/utils/access_control.py:31-31

请求流架构

sequenceDiagram
    participant C as 客户端
    participant R as 路由器 [openai.py]
    participant H as get_headers_and_cookies()
    participant A as 认证处理器
    participant P as 代理 [session_pool.py]
    participant E as 外部 API

    C->>R: POST /openai/v1/chat/completions
    R->>R: 根据模型确定 url_idx
    R->>H: 获取请求头与 cookies

    alt auth_type == "bearer"
        H->>A: 添加 Bearer 令牌
    else auth_type == "system_oauth"
        H->>A: get_oauth_token(user_id, session_id)
        A-->>H: OAuth access_token
    else auth_type == "azure_ad"
        H->>A: get_microsoft_entra_id_access_token()
        A-->>H: Azure AD 令牌
    end

    H-->>R: headers, cookies

    alt 推理模型 (o1-*)
        R->>R: openai_reasoning_model_handler()
        Note over R: 将 max_tokens 转换为 max_completion_tokens<br/>将 system 转换为 developer/user
    end

    R->>P: get_session()
    P->>E: 带认证的 HTTP POST
    E-->>P: 响应（流式/JSON）
    P-->>R: stream_wrapper()
    R-->>C: StreamingResponse

来源： backend/open_webui/routers/openai.py:158-220, backend/open_webui/routers/openai.py:137-155, backend/open_webui/utils/session_pool.py:60-61

配置系统

OpenAI 集成支持多个独立的 API 端点，每个端点具有自己的配置、认证和模型过滤。

配置结构

系统使用三种互补的配置结构：

配置项	类型	用途	示例
`OPENAI_API_BASE_URLS`	`list[str]`	API 端点 URL 列表	`["https://api.openai.com/v1", "http://localhost:8000"]`
`OPENAI_API_KEYS`	`list[str]`	与每个 URL 对应的 API 密钥	`["sk-...", ""]`
`OPENAI_API_CONFIGS`	`dict[str, dict]`	每个 URL 的高级配置	`{"0": {"enable": true, "model_ids": []}}`

来源： src/lib/apis/openai/index.ts:35-40, src/lib/components/chat/Settings/Connections.svelte:62-67

OPENAI_API_CONFIGS 模式

OPENAI_API_CONFIGS 字典允许对每个后端进行细粒度控制：

enable：布尔值，用于启用/禁用特定端点。
model_ids：白名单，指定从此端点暴露的特定模型。
prefix_id：字符串前缀，添加到模型 ID 前以防止冲突。
auth_type：指定认证机制（例如 bearer、azure_ad、system_oauth）。
headers：自定义 HTTP 请求头，包含在对该后端的每个请求中。

来源： backend/open_webui/routers/openai.py:185-218, src/lib/components/chat/Settings/Connections.svelte:26-28

认证方法

该集成支持多种认证方法，可通过 get_headers_and_cookies 中的 auth_type 字段按端点配置。

认证实现细节

Bearer 令牌（默认）

使用静态 API 密钥的标准 OpenAI 兼容认证。

if auth_type == 'bearer' or auth_type is None:
    # 未指定时默认使用 bearer
    token = f'{key}'

来源： backend/open_webui/routers/openai.py:187-189

系统 OAuth

与 oauth_manager 集成，根据 oauth_session_id cookie 为登录用户检索令牌。

elif auth_type == 'system_oauth':
    cookies = request.cookies
    oauth_token = None
    try:
        if request.cookies.get('oauth_session_id', None):
            oauth_token = await request.app.state.oauth_manager.get_oauth_token(
                user.id,
                request.cookies.get('oauth_session_id', None),
            )
    except Exception as e:
        log.error(f'获取 OAuth 令牌时出错：{e}')
    if oauth_token:
        token = f'{oauth_token.get("access_token", "")}'

来源： backend/open_webui/routers/openai.py:195-210

Microsoft Entra ID / Azure AD

使用 get_microsoft_entra_id_access_token，该函数利用 DefaultAzureCredential 为 Azure OpenAI 服务获取令牌。

elif auth_type in ('azure_ad', 'microsoft_entra_id'):
    token = get_microsoft_entra_id_access_token()

来源： backend/open_webui/routers/openai.py:211-212, backend/open_webui/routers/openai.py:223-238

模型发现与过滤

系统聚合来自所有已配置端点的模型，并应用过滤和转换。

Anthropic 和 Google GenAI

系统包含针对提供 OpenAI 兼容代理层的非 OpenAI 提供商的特化处理器。

Anthropic：get_models_request 函数使用 is_anthropic_url 检查 URL 是否为 Anthropic 端点，并分派到 get_anthropic_models。
Google GenAI：通常通过标准 OpenAI 兼容端点或自定义基础 URL 处理。

来源： backend/open_webui/routers/openai.py:132-134, backend/open_webui/utils/anthropic.py:66-67

模型转换（推理模型）

openai_reasoning_model_handler 确保与 OpenAI 推理模型（o1 系列）的兼容性。

令牌映射：将 max_tokens 转换为 max_completion_tokens。
角色映射：将 system 角色调整为 user（对于 o1-mini/o1-preview）或 developer（对于较新的推理模型）。

来源： backend/open_webui/routers/openai.py:137-155

响应流式传输与负载处理

该集成支持流式响应，并通过实用函数处理复杂的负载映射。

负载转换

payload.py 中的函数处理 Open WebUI 与 OpenAI 格式之间的参数转换。

apply_model_params_to_body_openai：映射 temperature、top_p、seed 和 logit_bias 等参数。它还解析 custom_params，并在转发前移除 OpenWebUI 特有的参数，如 stream_response 或 function_calling。
apply_system_prompt_to_body：将系统提示注入消息列表，并通过 prompt_variables_template 处理变量替换（例如 {{USER_NAME}}）。

来源： backend/open_webui/utils/payload.py:86-117, backend/open_webui/utils/payload.py:16-40

流式传输与用量标准化

系统使用 normalize_usage 标准化不同提供商（OpenAI、Ollama、llama.cpp）的用量统计。

标准化：将 prompt_tokens、completion_tokens 和 prompt_eval_count 映射到标准的 input_tokens 和 output_tokens 字段。
流式传输：stream_wrapper 管理 aiohttp 响应生命周期，而 stream_chunks_handler 处理实际的数据流。

来源： backend/open_webui/utils/response.py:11-49, backend/open_webui/utils/session_pool.py:61-61, backend/open_webui/utils/misc.py:56-56

数据流：聊天请求到 OpenAI 后端

graph TD
    subgraph "Open WebUI 后端"
        API["POST /openai/v1/chat/completions"]
        Payload["apply_model_params_to_body_openai()"]
        Auth["get_headers_and_cookies()"]
        Proxy["get_session() & request()"]
    end

    subgraph "外部提供商"
        OpenAI["OpenAI API"]
        Azure["Azure OpenAI"]
        Anthropic["Anthropic API"]
    end

    API --> Payload
    Payload --> Auth
    Auth --> Proxy
    Proxy --> OpenAI
    Proxy --> Azure
    Proxy --> Anthropic

来源： backend/open_webui/routers/openai.py:158-220, backend/open_webui/utils/payload.py:86-117, backend/open_webui/utils/session_pool.py:60-62

关键类与函数

实体	位置	角色
`get_headers_and_cookies`	`openai.py`	解析认证令牌（Bearer、OAuth、Azure AD）和代理请求的请求头。
`openai_reasoning_model_handler`	`openai.py`	修改 OpenAI o1 推理模型的负载（角色和令牌字段调整）。
`apply_model_params_to_body_openai`	`payload.py`	将 UI 参数转换并映射到 OpenAI API 字段，处理 `custom_params`。
`normalize_usage`	`response.py`	标准化来自各种后端格式的令牌用量指标。
`get_models_request`	`openai.py`	编排标准 OpenAI 和特化 Anthropic 端点的模型发现。
`generate_embeddings`	`embeddings.py`	将嵌入请求分派到 Ollama 或兼容 OpenAI 的后端。

来源： backend/open_webui/routers/openai.py:158-220, backend/open_webui/routers/openai.py:137-155, backend/open_webui/utils/payload.py:86-117, backend/open_webui/utils/response.py:11-49, backend/open_webui/routers/openai.py:125-134, backend/open_webui/utils/embeddings.py:24-89