跳到主要内容

🚚 迁移指南：Open WebUI 0.4 到 0.5

欢迎阅读 Open WebUI 0.5 迁移指南！如果您正在处理现有的项目，或者正在构建全新的项目，本指南将带您了解从 版本 0.4 到 0.5 的关键变化，并为您提供一份易于遵循的升级 Functions 指南。让我们把这次过渡处理得尽可能顺畅吧！😊

🧐 发生了哪些改变，为什么？​

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

  • 旧架构：🎯 以前，Open WebUI 采用的是子应用（sub-app）架构，每个应用（如 ollama、openai）都是一个独立的 FastAPI 应用程序。这导致了项目结构的零碎，并在管理各个应用时带来了额外的复杂度。
  • 新架构：🚀 在 0.5 版本中，我们已过渡到了拥有多个路由（routers）的单一 FastAPI 应用。这意味着更好的代码组织、集中的数据流以及减少了冗余。

关键改变：​

以下是所做改动的总览：

  1. Apps 已经被移动到 Routers。

    • 以前是：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 请求，而不需要处理额外的解析（例如文件、tools 等杂项），那么这个辅助工具函数可能更符合您的期望。

示例：​

# 带有解析的完整 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​

所有 apps 都已被重命名并重新放置在 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. 更新 Import 导入语句​

让我们看看这种更新在您的代码中呈现为何种形式：

以前：​

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 请求。
    • 负责处理文件、tools 以及其他各种杂项任务。
    • 最适合您希望由系统自动处理完整的 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 方法的轻量级、1:1 的直接替换。
  • 统一的选项 (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. 总结：用简单的话概括关键概念​

这里有一份帮您快速记忆的秘籍：

  • 从 Apps 到 Routers：将所有的导入语句从 open_webui.apps ➡️ 更改为 open_webui.routers。
  • 统一的端点：如果同时涉及 ollama 和 openai，为了简便性，请使用 open_webui.main.chat_completion。
  • 适配函数签名：确保您的函数传入了所需的 request 对象。

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

大功告成！您已经成功地从 Open WebUI 0.4 升级到了 0.5。通过重构您的导入语句、使用统一的端点以及更新函数签名，您已完全具备了利用 0.5 版本中最新功能与技术改进的所有能力。

💬 有任何问题或反馈？ 如果您在升级时遇到了任何麻烦或者有极好的建议，随时欢迎前往 GitHub issue 提交反馈，或者在社区论坛中发帖讨论！

祝您编码愉快！✨

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.