🚚 迁移指南：从 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 应用，并配备了多个 路由器（routers）。这意味着更好的组织、更集中化的流程以及减少冗余。

关键变化：

以下是变化概览：

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 体验。然而，这些独立函数的直接继任者是 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

选择最适合您的用例的方法！

4. 更新函数签名。
   • 函数签名现在遵循新的格式，需要传入 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.ollama	open_webui.routers.ollama
open_webui.apps.openai	open_webui.routers.openai
open_webui.apps.audio	open_webui.routers.audio
open_webui.apps.retrieval	open_webui.routers.retrieval
open_webui.apps.webui	open_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 请求，不处理额外的解析或任务。
   • 这是以前 main.generate_chat_completions、ollama.generate_chat_completion 和 openai.generate_chat_completion 函数在 Open WebUI 0.4 中的直接继任者。
   • 最适合简化和更轻量级的使用场景。

示例：

# 用于带有解析的完整 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. 简单术语总结关键概念

以下是快速记忆要点：

• 从 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 提交问题或在社区论坛中提问！

编码愉快！✨