Skip to main content

🚚 迁移指南：Open WebUI 0.4 到 0.5

欢迎阅读 Open WebUI 0.5 迁移指南！无论您是在处理现有项目还是构建新项目，本指南都将带您了解从 版本 0.4 到 0.5 的关键变化，并为升级您的函数 (Functions) 提供一份易于遵循的路线图。让我们让这次过渡尽可能顺利！😊

🧐 发生了什么变化，为什么要变？​

在 Open WebUI 0.5 中，我们对架构进行了彻底改革，以使项目更简单、更统一且更具可扩展性。以下是大局观：

  • 旧架构： 🎯 此前，Open WebUI 基于子应用架构构建，每个应用（例如 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 请求，那么这个工具函数可能正是您想要的。

示例：​


# 带有解析的完整 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 方法的轻量级 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 或在社区论坛中提问！

祝您编码愉快！✨