diff --git a/docs/features/plugin/migration/index.mdx b/docs/features/plugin/migration/index.mdx new file mode 100644 index 0000000..34fb457 --- /dev/null +++ b/docs/features/plugin/migration/index.mdx @@ -0,0 +1,184 @@ +--- +sidebar_position: 3 +title: "๐Ÿš€ Migrating Functions: Open WebUI 0.4 to 0.5" +--- + +# ๐Ÿš€ Migration Guide: Open WebUI 0.4 to 0.5 + +Welcome to the Open WebUI 0.5 migration guide! If you're working on existing projects or building new ones, this guide will walk you through the key changes from **version 0.4 to 0.5** and provide an easy-to-follow roadmap for upgrading your Functions. Let's make this transition as smooth as possible! ๐Ÿ˜Š + +--- + +## ๐Ÿง What Has Changed and Why? + +With Open WebUI 0.5, weโ€™ve overhauled the architecture to make the project **simpler, more unified, and scalable**. Here's the big picture: + +- **Old Architecture:** ๐ŸŽฏ Previously, Open WebUI was built on a **sub-app architecture** where each app (e.g., `ollama`, `openai`) was a separate FastAPI application. This caused fragmentation and extra complexity when managing apps. +- **New Architecture:** ๐Ÿš€ With version 0.5, we have transitioned to a **single FastAPI app** with multiple **routers**. This means better organization, centralized flow, and reduced redundancy. + +### Key Changes: +Hereโ€™s an overview of what changed: +1. **Apps have been moved to Routers.** + - Previous: `open_webui.apps` + - Now: `open_webui.routers` + +2. **Main app structure simplified.** + - The old `open_webui.apps.webui` has been transformed into `open_webui.main`, making it the central entry point for the project. + +3. **Unified API Endpoint.** + - Instead of separate functions for models like `ollama` and `openai`, we now offer a **unified function** (`chat_completion`) in `open_webui.main` for a consistent API experience. + +4. **Updated Function Signatures.** + - Function signatures now adhere to a new format, requiring a `request` object. + +๐Ÿ“Œ **Why did we make these changes?** +- To simplify the codebase, making it easier to extend and maintain. +- To unify APIs for a more streamlined developer experience. +- To enhance performance by consolidating redundant elements. + +--- + +## โœ… Step-by-Step Migration Guide + +Follow this guide to smoothly update your project. + +--- + +### ๐Ÿ”„ 1. Shifting from `apps` to `routers` + +All apps have been renamed and relocated under `open_webui.routers`. This affects imports in your codebase. + +Quick changes for import paths: + +| **Old Path** | **New Path** | +|-----------------------------------|-----------------------------------| +| `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` | + +--- + +### ๐Ÿ‘ฉโ€๐Ÿ’ป 2. Updating Import Statements + +Letโ€™s look at what this update looks like in your code: + +#### Before: +```python +from open_webui.apps.ollama import main as ollama +from open_webui.apps.openai import main as openai +``` + +#### After: +```python +# 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 +``` + +**๐Ÿ’ก Pro Tip:** Prioritize the unified endpoint (`chat_completion`) for simplicity and future compatibility. + +--- + +### ๐Ÿ“‹ 3. Adapting to Updated Function Signatures + +Weโ€™ve updated the **function signatures** to better fit the new architecture. + +#### Function Signature Changes: +| **Old** | **New** | +|-----------------------------------------|-----------------------------------------| +| `openai.generate_chat_completion(form_data: dict)` | `chat_completion(request: Request, form_data: dict)` | + +#### Example: + +If you're using `chat_completion`, hereโ€™s how your function should look now: + +### ๐Ÿ› ๏ธ How to Refactor Your Custom Function +Letโ€™s rewrite a sample function to match the new structure: + +#### Before (0.4): +```python +from open_webui.apps.openai import generate_chat_completion + +class Pipe: + def __init__(self): + pass + + async def pipe(self, body: dict) -> str: + # Calls OpenAI endpoint + return await openai.generate_chat_completion(body) +``` + +#### After (0.5): +```python +from open_webui.main import chat_completion +from fastapi import Request + +class Pipe: + def __init__(self): + pass + + async def pipe( + self, + body: dict, + __request__: Request, + ) -> str: + # Uses the unified endpoint with updated signature + return await chat_completion(__request__, body) +``` + +### Important Notes: +- You must pass a `Request` object (`__request__`) in the new function signature. +- Other optional parameters (like `__user__` and `__event_emitter__`) ensure flexibility for more complex use cases. + +--- + +### ๐ŸŒŸ 4. Recap: Key Concepts in Simple Terms + +Hereโ€™s a quick cheat sheet to remember: +- **Apps to Routers:** Update all imports from `open_webui.apps` โžก๏ธ `open_webui.routers`. +- **Unified Endpoint:** Use `open_webui.main.chat_completion` for simplicity if both `ollama` and `openai` are involved. +- **Adapt Function Signatures:** Ensure your functions pass the required `request` object. + +--- + +### โœ๏ธ Example Project on Open WebUI 0.5 + +Hereโ€™s a simple example to tie everything together: + +```python +from open_webui.main import chat_completion +from fastapi import Request +from typing import Any, Optional, Callable + +class ChatBotService: + def __init__(self): + self.name = "ChatBot" + + async def handle_request( + self, + user_input: dict, + __request__: Request, + __task__=None, + ) -> str: + # Call the unified endpoint for chat completion + response = await chat_completion(__request__, user_input) + return response +``` + +--- + +## ๐ŸŽ‰ Hooray! You're Ready! + +That's it! You've successfully migrated from **Open WebUI 0.4 to 0.5**. By refactoring your imports, using the unified endpoint, and updating function signatures, you'll be fully equipped to leverage the latest features and improvements in version 0.5. + +--- + +๐Ÿ’ฌ **Questions or Feedback?** +If you run into any issues or have suggestions, feel free to open a [GitHub issue](https://github.com/open-webui/open-webui) or ask in the community forums! + +Happy coding! โœจ \ No newline at end of file