Skip to main content

🚚 迁移指南：Open WebUI 0.4 到 0.5

欢迎阅读 Open WebUI 0.5 迁移指南！无论您正在处理现有项目还是构建新项目，本指南都将为您详细介绍从 0.4 版本到 0.5 版本 的关键变化，并提供一个清晰的升级路线图。让我们一起平稳地完成这次升级！😊

🧐 发生了什么变化以及原因？​

在 Open WebUI 0.5 中，我们对架构进行了全面改进，使项目变得更简单、更统一且更具可扩展性。以下是整体概况：

  • 旧架构： 🎯 此前，Open WebUI 采用子应用架构（sub-app architecture），每个应用（如 ollama、openai）都是一个独立的 FastAPI 应用。这种结构导致了应用管理的碎片化和额外的复杂性。
  • 新架构： 🚀 在 0.5 版本中，我们转向了一个具有多个路由器（Router）的单一 FastAPI 应用。这样的改变带来了更好的组织结构、集中的处理流程和更少的冗余代码。

主要变化：​

以下是具体的变更内容：

  1. 应用转移至路由器

    • 之前：open_webui.apps
    • 现在：open_webui.routers

  2. 主应用结构优化

    • 原有的 open_webui.apps.webui 已重构为 open_webui.main，成为项目的统一入口点。

  3. API 端点统一化

    • Open WebUI 0.5 在 open_webui.main 中引入了统一的 chat_completion 函数，取代了之前 ollama 和 openai 的独立函数。这为开发者提供了一致且精简的 API 体验。不过，如果您需要原有函数的直接替代方案，可以使用 open_webui.utils.chat 中的 generate_chat_completion。这个轻量级函数适合那些不需要处理额外解析（如文件、工具等）的简单 POST 请求场景。

示例：​

# 包含解析功能的完整 API 流程（新函数）：
from open_webui.main import chat_completion

# 轻量级直接 POST 请求（直接替代方案）：
from open_webui.utils.chat import generate_chat_completion

请根据您的具体需求选择合适的方案！

  1. 函数签名更新
    • 函数签名采用新的格式，需要包含 request 对象
    • 通过函数签名中的 __request__ 参数获取 request 对象，示例如下：
class Pipe:
    def __init__(self):
        pass

    async def pipe(
        self,
        body: dict,
        __user__: dict,
        __request__: Request, # 新增的请求对象参数
    ) -> str:
        # 在此实现您的函数逻辑

📌 这些改变的目的是什么？

  • 简化代码库结构，提升可扩展性和可维护性
  • 统一 API 接口，优化开发者使用体验
  • 通过消除冗余组件提高系统性能

✅ 逐步迁移指南​

按照以下步骤更新您的项目。

🔄 1. 从 apps 迁移到 routers​

所有应用都已重命名并移至 open_webui.routers 下。这将影响您代码中的导入语句。

导入路径的快速更改：

旧路径新路径
open_webui.apps.ollamaopen_webui.routers.ollama
open_webui.apps.openaiopen_webui.routers.openai
open_webui.apps.audioopen_webui.routers.audio
open_webui.apps.retrievalopen_webui.routers.retrieval
open_webui.apps.webuiopen_webui.main

📜 重要示例​

关于主应用（webui）的特殊情况说明：

  • 原属于 webui 的内容？ 现在位于项目根目录或 open_webui.main 中。
  • 例如：
    • 之前 (0.4)： 
      from open_webui.apps.webui.models import SomeModel
    • 现在 (0.5)： 
      from open_webui.models import SomeModel

总的来说，只需将 open_webui.apps 替换为 open_webui.routers—但 webui 例外，它现在是 open_webui.main！

👩‍💻 2. 更新导入语句​

让我们看看代码中的具体更新：

之前：​

from open_webui.apps.ollama import main as ollama
from open_webui.apps.openai import main as openai

现在：​

# 单独的路由器导入
from open_webui.routers.ollama import generate_chat_completion
from open_webui.routers.openai import generate_chat_completion

# 或使用统一端点
from open_webui.main import chat_completion

💡 专业提示： 建议优先使用统一端点（chat_completion），以获得更简单的使用体验和更好的未来兼容性。

📝 补充说明：在 main.chat_completion 和 utils.chat.generate_chat_completion 之间选择​

根据您的使用场景，可以选择：

  1. open_webui.main.chat_completion：

    • 模拟向 /api/chat/completions 发送 POST 请求
    • 处理文件、工具和其他杂项任务
    • 适用于需要自动处理完整 API 流程的场景

  2. open_webui.utils.chat.generate_chat_completion：

    • 直接发送 POST 请求，不处理额外的解析或任务
    • 这是 Open WebUI 0.4 中原有 main.generate_chat_completions、ollama.generate_chat_completion 和 openai.generate_chat_completion 函数的直接替代者
    • 适用于简化的轻量级场景

示例：​

# 使用此函数获取完整的 API 流程和解析功能：
from open_webui.main import chat_completion

# 使用此函数获取精简的直接 POST 请求：
from open_webui.utils.chat import generate_chat_completion

📋 3. 适配更新后的函数签名​

我们更新了函数签名以更好地适应新架构。如果您在寻找直接替代方案，可以从 open_webui.utils.chat 中的轻量级工具函数 generate_chat_completion 开始。对于完整的 API 流程，请使用 open_webui.main 中的新统一 chat_completion 函数。

函数签名变化：​

旧版直接替代（新版）统一选项（新版）
openai.generate_chat_completion(form_data: dict, user: UserModel)generate_chat_completion(request: Request, form_data: dict, user: UserModel)chat_completion(request: Request, form_data: dict, user: UserModel)
  • 直接替代（generate_chat_completion）：原有 ollama/openai 方法的轻量级一对一替代方案
  • 统一选项（chat_completion）：用于完整的 API 流程，包括文件解析和附加功能

示例：​

如果您使用 chat_completion，您的函数现在应该是这样的：

🛠️ 如何重构您的自定义函数​

让我们重写一个示例函数以匹配新结构：

之前 (0.4)：​

from pydantic import BaseModel
from open_webui.apps.ollama import generate_chat_completion

class User(BaseModel):
    id: str
    email: str
    name: str
    role: str

class Pipe:
    def __init__(self):
        pass

    async def pipe(self, body: dict, __user__: dict) -> str:
        # 调用 OpenAI 端点
        user = User(**__user__)
        body["model"] = "llama3.2:latest"
        return await ollama.generate_chat_completion(body, user)

现在 (0.5)：​

from pydantic import BaseModel
from fastapi import Request

from open_webui.utils.chat import generate_chat_completion


class User(BaseModel):
    id: str
    email: str
    name: str
    role: str


class Pipe:
    def __init__(self):
        pass

    async def pipe(
        self,
        body: dict,
        __user__: dict,
        __request__: Request,
    ) -> str:
        # 使用更新后签名的统一端点
        user = User(**__user__)
        body["model"] = "llama3.2:latest"
        return await generate_chat_completion(__request__, body, user)

重要说明：​

  • 您必须在新的函数签名中传递 Request 对象（__request__）
  • 其他可选参数（如 __user__ 和 __event_emitter__）确保了更复杂用例的灵活性

🌟 4. 回顾：简明的关键概念​

这里是一个快速参考清单：

  • 从应用到路由器： 将所有导入从 open_webui.apps ➡️ open_webui.routers 更新
  • 统一端点： 如果同时涉及 ollama 和 openai，使用 open_webui.main.chat_completion 以简化操作
  • 适配函数签名： 确保您的函数传递所需的 request 对象

🎉 太好了！您已准备就绪！​

就是这样！您已成功从 Open WebUI 0.4 迁移到 0.5。通过重构导入、使用统一端点和更新函数签名，您现在可以充分利用 0.5 版本中的最新特性和改进。

💬 有问题或反馈？ 如果您遇到任何问题或有建议，欢迎在 GitHub issues 上提出或在社区论坛中询问！

祝您编码愉快！✨