🚚 마이그레이션 가이드: Open WebUI 0.4에서 0.5로

Open WebUI 0.5 마이그레이션 가이드에 오신 것을 환영합니다! 기존 프로젝트를 작업하거나 새로운 프로젝트를 구축하는 경우, 이 가이드는 버전 0.4에서 0.5로의 주요 변경 사항을 안내하고 Functions를 업그레이드하기 위한 간단한 로드맵을 제공할 것입니다. 이 전환을 최대한 매끄럽게 만들어봅시다! 😊

---

🧐 변경 사항과 그 이유는 무엇인가요?

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는 모델별 개별 함수(ollama, openai)를 대체하는 chat_completion이라는 통합 함수를 open_webui.main에 도입했습니다. 이를 통해 일관되고 간소화된 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 함수의 직접 후속 모듈입니다.
   • 간소화되고 가벼운 시나리오에 가장 적합합니다.

예제:

# 파싱을 포함한 전체 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 메서드의 경량화된 1:1 대체 모듈입니다.
• 통합 옵션 (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 issue를 열거나 커뮤니티 포럼에 문의하세요!

행복한 코딩 되세요! ✨