跳到主要内容

🚚 迁移指南： OPL 数据空间0.4 → 0.5

这份指南面向正在维护旧插件，或基于旧结构构建新插件的开发者。它总结了 OPL 数据空间0.4 到 0.5 之间的关键变化，并给出 Function / Pipe 的升级路径。

发生了什么变化​

OPL 数据空间0.5 对项目结构做了较大调整，目标是让架构更统一、更易扩展、更适合长期维护。

旧架构​

以前 OPL 数据空间基于“sub-app”结构，每个 app，例如 ollama、openai，都是单独的 FastAPI 应用。这会带来结构分散、调用路径重复、维护复杂度偏高的问题。

新架构​

从 0.5 开始， OPL 数据空间改成了：

  • 一个统一的 FastAPI 主应用
  • 多个 routers

这样整体结构更清晰，也更适合继续扩展。

核心变化​

1. apps 迁移到 routers​

  • 旧：open_webui.apps
  • 新：open_webui.routers

2. 主应用入口简化​

旧的 open_webui.apps.webui 已被重构为 open_webui.main，成为项目中心入口。

3. 新的统一 API 入口​

0.5 引入了新的统一函数：

  • open_webui.main.chat_completion

它取代了过去针对 ollama、openai 分别存在的调用路径。

如果你只想做一个轻量级的直接 POST 请求，而不处理文件、工具或其他额外解析流程，那么更接近旧行为的直接替代物是：

  • open_webui.utils.chat.generate_chat_completion
from open_webui.main import chat_completion
from open_webui.utils.chat import generate_chat_completion

4. 函数签名更新​

新的函数签名要求传入 request 对象。对于插件作者来说，这意味着你需要在函数签名中加入 __request__：

class Pipe:
    async def pipe(
        self,
        body: dict,
        __user__: dict,
        __request__: Request,
    ) -> str:
        ...

迁移步骤​

1. 把 apps 导入改成 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 下找对象，0.5 后很多内容会挪到项目根层或 open_webui.main。

例如：

from open_webui.apps.webui.models import SomeModel

迁移后可能变成：

from open_webui.models import SomeModel

规则可以粗暴记成：

  • 大多数地方：apps → routers
  • webui：改看 open_webui.main 或项目根层

2. 更新 import​

旧写法​

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，后续兼容性通常更好。

3. 决定使用 chat_completion 还是 generate_chat_completion​

open_webui.main.chat_completion​

  • 模拟 /api/chat/completions 的完整处理流程
  • 会额外处理文件、工具和其他杂项流程
  • 适合你希望“完整走一遍 OPL 数据空间 API 逻辑”的情况

open_webui.utils.chat.generate_chat_completion​

  • 更轻量的直接 POST 请求
  • 更接近旧版本中的 main.generate_chat_completions / ollama.generate_chat_completion / openai.generate_chat_completion
  • 适合你只想完成核心模型调用，不想额外引入完整解析流程的情况

4. 更新函数签名​

新签名需要显式接收 Request 对象。

旧写法（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:
        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)

迁移时的记忆点​

  • apps 改成 routers
  • webui 改看 open_webui.main
  • 新增统一入口 chat_completion
  • 函数签名中加入 __request__

总结​

从 0.4 迁移到 0.5，核心是三件事：

  1. 改 import 路径
  2. 选择新的统一或轻量调用入口
  3. 给函数签名补上 __request__

完成这些后，你的插件就可以顺利适配 0.5 的结构。

💬 如果迁移过程中遇到问题，可以到 GitHub 提 issue 或去社区讨论区求助。