跳到主要内容

🚚 迁移指南：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 在 open_webui.main 中引入了一个统一函数 chat_completion，取代了 ollama 和 openai 等模型的独立函数。这提供了统一且精简的 API 体验。但是，这些独立函数的直接继承者是 open_webui.utils.chat 中的 generate_chat_completion。如果您希望进行轻量级 POST 请求，而无需处理额外的解析（例如文件、工具或其他杂项），那么此实用函数可能正是您想要的。

示例：​

# Full API flow with parsing (new function):
from open_webui.main import chat_completion

# Lightweight, direct POST request (direct successor):
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, # New parameter
    ) -> str:
        # Write your function here

📌 我们为什么要进行这些更改？

  • 简化代码库，使其更易于扩展和维护。
  • 统一 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

之后：​

# Separate router imports
from open_webui.routers.ollama import generate_chat_completion
from open_webui.routers.openai import generate_chat_completion

# Or use the unified endpoint
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 函数的直接继承者。
    • 最适合简化和更轻量级的场景。

示例：​

# Use this for the full API flow with parsing:
from open_webui.main import chat_completion

# Use this for a stripped-down, direct POST request:
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:
        # Calls OpenAI endpoint
        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:
        # Uses the unified endpoint with updated signature
        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 或在社区论坛中提问！

祝您编程愉快！✨