🚰 Pipe Function: Create Custom "Agents/Models"

Open WebUI에서 **파이프(Pipes)**를 만드는 가이드에 오신 것을 환영합니다! 파이프는 Open WebUI에 새로운 모델을 추가하는 방법으로 생각될 수 있습니다. 이 문서에서는 파이프가 무엇인지, 어떻게 작동하는지, 그리고 Open WebUI 모델에 사용자 정의된 로직과 처리를 추가하기 위해 자신만의 파이프를 만드는 방법에 대해 설명할 것입니다. 이해하기 쉽도록 비유를 사용하고 세부사항을 하나하나 다루어 포괄적인 이해를 도울 것입니다.

파이프 소개

Open WebUI를 배관 시스템으로 상상해보세요. 데이터가 파이프와 밸브를 통해 흐릅니다. 이 비유에서:

• 파이프(Pipes): 데이터가 흐를 수 있는 새로운 경로를 소개할 수 있도록 하며, 사용자 정의된 로직과 처리를 추가할 수 있는 플러그인과 같습니다.
• 밸브(Valves): 파이프를 통해 데이터가 흐르는 방식을 제어하는 조정 가능한 부분입니다.

파이프를 만들면 Open WebUI 프레임워크 내에서 원하는 특정 동작을 수행하는 사용자 정의 모델을 제작하는 것입니다.

---

파이프 구조 이해하기

파이프의 구조를 이해하기 위해 기본적이고 간단한 버전의 파이프로 시작해 보겠습니다:

from pydantic import BaseModel, Field

class Pipe:
    class Valves(BaseModel):
        MODEL_ID: str = Field(default="")

    def __init__(self):
        self.valves = self.Valves()

    def pipe(self, body: dict):
        # 로직이 여기에 위치합니다
        print(self.valves, body)  # 이는 구성 옵션과 입력 본문을 출력합니다
        return "Hello, World!"

Pipe 클래스

• 정의: Pipe 클래스는 사용자 정의 로직을 정의하는 곳입니다.
• 목적: Open WebUI 내에서 플러그인이 어떻게 작동하는지를 결정하는 청사진 역할을 합니다.

밸브(Valves): 파이프 구성하기

• 정의: Valves는 Pipe 내부의 클래스이며 BaseModel을 상속받습니다.
• 목적: 파이프 사용 중 지속 가능한 구성 옵션(매개변수)을 포함합니다.
• 예시: 위 코드에서는 MODEL_ID가 기본 빈 문자열을 가진 구성 옵션입니다.

비유: 밸브는 실제 세상에서 물의 흐름을 제어하는 파이프 시스템의 손잡이와 같습니다. 파이프에서 밸브는 데이터의 흐름과 처리 방식을 사용자들이 조정할 수 있도록 해줍니다.

__init__ 메서드

• 정의: Pipe 클래스의 생성자 메서드입니다.
• 목적: 파이프의 상태를 초기화하고 필요한 구성 요소를 설정합니다.
• 최적 실천: 간단하게 유지하며 self.valves를 주로 초기화합니다.

def __init__(self):
    self.valves = self.Valves()

pipe 함수

• 정의: 사용자 정의 로직이 자리하는 핵심 함수입니다.
• 매개변수:
  • body: 입력 데이터를 포함하는 딕셔너리입니다.
• 목적: 사용자 정의 로직을 사용하여 입력 데이터를 처리하고 결과를 반환합니다.

def pipe(self, body: dict):
    # 로직이 여기에 위치합니다
    print(self.valves, body)  # 이는 구성 옵션과 입력 본문을 출력합니다
    return "Hello, World!"

참고: 항상 Valves를 Pipe 클래스의 상단에 위치시키고, 그 뒤에 __init__을 두며 pipe 함수를 위치시킵니다. 이러한 구조는 명확성과 일관성을 보장합니다.

---

파이프를 통해 다중 모델 생성하기

Open WebUI 내에서 다중 모델을 생성하고 싶다면 어떻게 해야 할까요? 이는 Pipe 클래스 안에 pipes 함수 또는 변수를 정의함으로써 가능합니다. 이러한 설정은 비공식적으로 **다중 분배기(manifold)**라 불리며, 파이프가 여러 모델을 나타낼 수 있도록 합니다.

다음과 같이 할 수 있습니다:

from pydantic import BaseModel, Field

class Pipe:
    class Valves(BaseModel):
        MODEL_ID: str = Field(default="")

    def __init__(self):
        self.valves = self.Valves()

    def pipes(self):
        return [
            {"id": "model_id_1", "name": "model_1"},
            {"id": "model_id_2", "name": "model_2"},
            {"id": "model_id_3", "name": "model_3"},
        ]

    def pipe(self, body: dict):
        # 로직이 여기에 위치합니다
        print(self.valves, body)  # 구성 옵션과 입력 본문을 출력합니다
        model = body.get("model", "")
        return f"{model}: Hello, World!"

설명

• pipes 함수:

  • 딕셔너리 목록을 반환합니다.
  • 각 딕셔너리는 고유한 id와 name 키를 가진 모델을 나타냅니다.
  • 이러한 모델은 개별적으로 Open WebUI 모델 선택기에 나타납니다.

• 업데이트된 pipe 함수:

  • 선택된 모델을 기반으로 입력을 처리합니다.
  • 이 예에서는 반환 문자열에 모델 이름을 포함시킵니다.

---

예시: OpenAI 프록시 파이프

OpenAI API에 요청을 프록시하는 파이프를 만들게 될 실용적인 예를 살펴보겠습니다. 이 파이프는 OpenAI에서 사용할 수 있는 모델을 가져오고 사용자가 Open WebUI를 통해 상호작용할 수 있도록 합니다.

from pydantic import BaseModel, Field
import requests

class Pipe:
    class Valves(BaseModel):
        NAME_PREFIX: str = Field(
            default="OPENAI/",
            description="모델 이름 앞에 추가할 접두사입니다.",
        )
        OPENAI_API_BASE_URL: str = Field(
            default="https://api.openai.com/v1",
            description="OpenAI API 엔드포인트에 접근하기 위한 기본 URL입니다.",
        )
        OPENAI_API_KEY: str = Field(
            default="",
            description="OpenAI API 요청을 인증하기 위한 API 키입니다.",
        )

    def __init__(self):
        self.valves = self.Valves()

    def pipes(self):
        if self.valves.OPENAI_API_KEY:
            try:
                headers = {
                    "Authorization": f"Bearer {self.valves.OPENAI_API_KEY}",
                    "Content-Type": "application/json",
                }

                r = requests.get(
                    f"{self.valves.OPENAI_API_BASE_URL}/models", headers=headers
                )
                models = r.json()
                return [
                    {
                        "id": model["id"],
                        "name": f{self.valves.NAME_PREFIX}{model.get("name", model["id"])},
                    }
                    for model in models["data"]
                    if "gpt" in model["id"]
                ]

            except Exception as e:
                return [
                    {
                        "id": "error",
                        "name": "모델을 가져오는 중 오류가 발생했습니다. API 키를 확인하세요.",
                    },
                ]
        else:
            return [
                {
                    "id": "error",
                    "name": "API 키가 제공되지 않았습니다.",
                },
            ]

    def pipe(self, body: dict, __user__: dict):
        print(f"pipe:{__name__}")
        headers = {
            "Authorization": f"Bearer {self.valves.OPENAI_API_KEY}",
            "Content-Type": "application/json",
        }

        # 모델 이름에서 모델 ID 추출
        model_id = body["model"][body["model"].find(".") + 1 :]

        # 본문에서 모델 ID를 업데이트
        payload = {**body, "model": model_id}
        try:
            r = requests.post(
                url=f"{self.valves.OPENAI_API_BASE_URL}/chat/completions",
                json=payload,
                headers=headers,
                stream=True,
            )

            r.raise_for_status()

            if body.get("stream", False):
                return r.iter_lines()
            else:
                return r.json()
        except Exception as e:
            return f"오류: {e}"

세부 구성

Valves 설정

• NAME_PREFIX:
  • Open WebUI에서 표시되는 모델 이름 앞에 접두사를 추가합니다.
  • 기본값: "OPENAI/".
• OPENAI_API_BASE_URL:
  • OpenAI API를 위한 기본 URL을 지정합니다.
  • 기본값: "https://api.openai.com/v1".
• OPENAI_API_KEY:
  • 인증을 위한 OpenAI API 키입니다.
  • 기본값: "" (빈 문자열; 제공해야 함).

pipes 함수

• 목적: 사용 가능한 OpenAI 모델을 가져와 Open WebUI에서 접근 가능하게 합니다.

• 절차:

  1. API 키 확인: API 키가 제공되었는지 확인합니다.
  2. 모델 가져오기: OpenAI API에 GET 요청을 보내 사용 가능한 모델을 검색합니다.
  3. 모델 필터링: id에 "gpt"를 포함하는 모델을 반환합니다.
  4. 오류 처리: 문제가 발생하면 오류 메시지를 반환합니다.

• 반환 형식: 각 모델에 대해 id 및 name을 포함하는 사전 리스트.

pipe 함수

• 목적: 선택한 OpenAI 모델에 대한 요청을 처리하고 응답을 반환합니다.

• 매개변수:

  • body: 요청 데이터를 포함합니다.
  • __user__: 사용자 정보를 포함합니다 (이 예제에서는 사용되지 않지만 인증 또는 로그에 유용할 수 있음).

• 절차:

  1. 헤더 준비: API 키와 콘텐츠 유형으로 헤더를 설정합니다.
  2. 모델 ID 추출: 선택한 모델 이름에서 실제 모델 ID를 추출합니다.
  3. 페이로드 준비: 올바른 모델 ID와 함께 본문을 업데이트합니다.
  4. API 요청 실행: OpenAI API의 채팅 완성 엔드포인트에 POST 요청을 보냅니다.
  5. 스트리밍 처리: stream이 True이면 라인의 반복 가능한 객체를 반환합니다.
  6. 오류 처리: 예외를 포착하고 오류 메시지를 반환합니다.

프록시 파이프 확장

Anthropic, Perplexity 등의 추가 서비스 제공자를 지원하도록 이 프록시 Pipe를 수정하려면, pipes 및 pipe 함수 내에서 API 엔드포인트, 헤더 및 로직을 조정하세요.

---

내부 Open WebUI 함수 사용

때로는 Pipe 내에서 Open WebUI의 내부 기능을 사용하는 것이 필요할 수 있습니다. open_webui 패키지에서 이러한 기능을 직접 가져올 수 있습니다. 최적화를 위해 내부 기능이 변경될 가능성이 낮지만 항상 최신 문서를 참조하세요.

Open WebUI 내부 함수를 사용하는 방법은 다음과 같습니다:

from pydantic import BaseModel, Field
from fastapi import Request

from open_webui.models.users import Users
open_webui.utils.chat에서 generate_chat_completion 가져오기

클래스 Pipe:
    def __init__(self):
        pass

    async def pipe(
        self,
        body: dict,
        __user__: dict,
        __request__: Request,
    ) -> str:
        # 업데이트된 서명과 함께 통합 엔드포인트 사용
        user = Users.get_user_by_id(__user__["id"])
        body["model"] = "llama3.2:latest"
        return await generate_chat_completion(__request__, body, user)

설명

• Imports:

  • Users from open_webui.models.users: 사용자 정보를 가져오기 위해.
  • generate_chat_completion from open_webui.utils.chat: 내부 로직을 사용해 채팅 답변을 생성하기 위해.

• 비동기 pipe 함수:

  • 매개변수:
    • body: 모델에 대한 입력 데이터.
    • __user__: 사용자 정보를 포함하는 딕셔너리.
    • __request__: FastAPI의 요청 객체 (generate_chat_completion에 필요).
  • 프로세스:
    1. 사용자 객체 가져오기: ID를 사용해 사용자 객체를 검색.
    2. 모델 설정: 사용될 모델 지정.
    3. 답변 생성: generate_chat_completion 호출을 통해 입력을 처리하고 출력 생성.

중요한 참고사항

• 함수 시그니처: 최신 Open WebUI 코드베이스 또는 문서를 참조하여 가장 정확한 함수 시그니처와 매개변수를 확인하세요.
• 최신 관행: 예외와 오류를 신중하게 처리하여 원활한 사용자 경험을 보장하세요.

---

자주 묻는 질문

Q1: 왜 Open WebUI에서 Pipe를 사용해야 합니까?

A: Pipe를 사용하면 Open WebUI에 사용자 정의 논리 및 처리를 통해 새로운 "모델"을 추가할 수 있습니다. 이는 외부 API를 통합하고, 모델 동작을 수정하며, 핵심 코드베이스를 변경하지 않고 혁신적인 기능을 추가할 수 있는 유연한 플러그인 시스템입니다.

---

Q2: Valves란 무엇이며 왜 중요한가요?

A: Valves는 Pipe의 구성 가능한 매개변수입니다. 이는 설정 또는 컨트롤과 같으며 Pipe가 작동하는 방식을 결정합니다. Valves를 조정하면 기본 코드를 수정하지 않고도 Pipe의 동작을 변경할 수 있습니다.

---

Q3: Valves 없이 Pipe를 만들 수 있나요?

A: 네, 지속적인 구성 옵션이 필요하지 않은 Pipe의 경우 Valves 클래스를 정의하지 않고 간단한 Pipe를 만들 수 있습니다. 그러나 Flexibility와 확장 가능성을 위해 Valves를 포함하는 것이 좋은 관행입니다.

---

Q4: API 키를 사용할 때 Pipe의 보안을 어떻게 유지할 수 있나요?

A: API 키와 같은 민감한 정보를 절대 Pipe에 하드코딩하지 마세요. 대신 Valves를 사용하여 API 키를 안전하게 입력하고 저장하세요. 이러한 키를 적절히 처리하고 로그에 기록하거나 노출시키지 않도록 하세요.

---

Q5: pipe 함수와 pipes 함수의 차이는 무엇인가요?

A:

• pipe 함수: 주 모델의 입력 데이터를 처리하고 출력을 생성하는 주요 함수입니다. 단일 모델의 로직을 처리합니다.

• pipes 함수: 여러 모델에 대한 정의 목록을 반환함으로써 Pipe가 여러 모델을 나타낼 수 있도록 합니다. 각 모델은 Open WebUI에서 개별적으로 나타납니다.

---

Q6: Pipe에서 오류를 처리하는 방법은?

A: pipe 및 pipes 함수 내에서 try-except 블록을 사용하여 예외를 포착하세요. 의미 있는 오류 메시지를 반환하거나 오류를 검증하여 사용자가 문제가 발생한 이유를 알 수 있도록 하세요.

---

Q7: Pipe에서 외부 라이브러리를 사용할 수 있나요?

A: 네, 필요할 경우 외부 라이브러리를 가져와 사용할 수 있습니다. 환경 내에서 모든 종속성이 적절히 설치되고 관리되었는지 확인하세요.

---

Q8: Pipe를 어떻게 테스트하나요?

A: 개발 환경에서 Open WebUI를 실행하고 인터페이스에서 사용자 정의 모델을 선택하여 Pipe를 테스트하세요. Pipe가 다양한 입력 및 설정에서 예상대로 작동하는지 확인하세요.

---

Q9: Pipe 코드를 조직화하기 위한 모범 사례가 있습니까?

A: 네, 다음 지침을 따르세요:

• Valves를 Pipe 클래스의 상단에 위치시키세요.
• __init__ 메서드에서 변수를 초기화하세요, 주로 self.valves를.
• __init__ 메서드 다음에 pipe 함수를 배치하세요.
• 명확하고 설명적인 변수 이름을 사용하세요.
• 코드를 명확히 하기 위한 주석을 작성하세요.

---

Q10: 최신 Open WebUI 문서는 어디에서 찾을 수 있나요?

A: 공식 Open WebUI 저장소 또는 문서 사이트를 방문하여 가장 최신 정보, 함수 시그니처, 예제 및 발생할 수 있는 변경 사항에 대한 마이그레이션 가이드를 확인하세요.

---

결론

이제 Open WebUI에서 Pipe를 생성하고 사용하는 방법에 대해 철저히 이해하셨을 것입니다. Pipe는 Open WebUI의 기능을 확장하고 맞춤할 수 있는 강력한 방법을 제공합니다. 외부 API를 통합하든, 새로운 모델을 추가하든, 복잡한 논리를 삽입하든, Pipe는 이를 가능하게 할 유연성을 제공합니다.

기억하세요:

• Pipe 클래스에서 명확하고 일관된 구조를 사용하세요.
• 구성 가능한 옵션을 위해 Valves를 활용하세요.
• 사용자 경험을 개선하기 위해 오류를 신중히 처리하세요.
• 최신 문서를 참조하세요 업데이트나 변경 사항이 있는지 확인합니다.

코딩을 즐기시고, Pipes로 Open WebUI를 확장하는 재미를 누리세요!