跳到主要内容

🚚 迁移指南：Open WebUI 0.4 至 0.5

欢迎来到 Open WebUI 0.5 的迁移指南！无论您是在现有项目上工作，还是在构建新项目，本指南将引导您了解从 0.4 版到 0.5 版的关键变化，并提供一个易于遵循的升级路线图。让我们尽量使这个过渡过程变得顺畅！😊

🧐 有哪些变化以及为什么？​

在 Open WebUI 0.5 中，我们对架构进行了全面改进，使其更加简洁、统一且可扩展。以下是整体情况：

  • 旧架构： 🎯 以前，Open WebUI 基于子应用架构构建，每个应用程序（例如 ollama、openai）都是一个独立的 FastAPI 应用程序。这导致了碎片化和管理应用程序时的复杂性。
  • 新架构： 🚀 在 0.5 版中，我们已经过渡到一个包含多个路由器的单一 FastAPI 应用程序。这意味着更好的组织结构、集中的流程和减少冗余。

关键变化：​

以下是对主要变化的概述：

  1. 应用程序被迁移到路由器。

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

  2. 主应用程序结构简化。

    • 旧的 open_webui.apps.webui 已经转变为 open_webui.main，成为项目的中央入口点。

  3. 统一的 API 端点

    • Open WebUI 0.5 引入了一个统一的函数 chat_completion，位于 open_webui.main 中，取代了针对不同模型（如 ollama 和 openai）的单独函数。这提供了统一且简化的 API 体验。然而，这些单个函数的直接继承者是 generate_chat_completion，来自 open_webui.utils.chat。如果您希望进行轻量级的 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)：一个轻量级的 1:1 替代品，用于之前的 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 issue 上提出或在社区论坛中提问！

祝您编码愉快！✨