跳到主要内容

🚚 迁移指南：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. 应用已迁移到路由器（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 请求，无需处理额外的解析（例如文件、工具或其他杂项），这个实用函数可能是您想要的。

示例：​

# 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. 回顾：简单术语中的关键概念​

这里有一个快速备忘单供您记住

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

编程愉快！✨