Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 10. 16:13

Open WebUI Pipelines 가이드 2026: 로컬 LLM을 위한 웹 검색, Rate Limiting 및 커스텀 로직

요약

Open WebUI Pipelines를 활용하여 Open WebUI에 커스텀 로직을 추가하는 방법을 설명합니다. Python 미들웨어 서버로서 웹 검색, Rate Limiting, RAG 등의 기능을 소스 코드 수정 없이 구현할 수 있습니다.

핵심 포인트

  • Pipelines는 OpenAI API 프록시 역할을 하는 별도의 Python 미들웨어 서버임
  • 필터(Filter)는 요청 전후에 로깅이나 속도 제한 등의 로직을 추가함
  • 파이프(Pipe)는 웹 검색이나 커스텀 RAG처럼 모델 자체를 대체함
  • Docker를 통해 간편하게 배포 및 실행 가능함

이 기사는 원래 aifoss.dev에 게시되었습니다.

요약 (TL;DR): Open WebUI Pipelines는 Open WebUI와 LLM 사이에서 실행되는 Python 미들웨어 서버로, Open WebUI의 소스 코드를 수정하지 않고도 커스텀 로직 (Custom Logic)을 추가할 수 있습니다. 단 한 번의 docker run 명령어로 배포할 수 있습니다. Open WebUI를 실행하는 대부분의 사용자는 이를 사용하지 않는데, 이는 개인용 채팅 UI를 웹 접속 및 프로그래밍 가능한 동작을 갖춘 다중 사용자 플랫폼으로 변모시킬 수 있는 기능을 놓치고 있음을 의미합니다.

이 가이드를 마치고 나면 다음을 갖게 됩니다:

  • Ollama와 함께 실행되며 Open WebUI v0.9.5에 연결된 Pipelines 서버
  • LLM이 응답하기 전에 실시간 결과를 가져오는 작동 가능한 웹 검색 파이프라인 (Web Search Pipeline)
  • 공유 팀 배포를 위해 사용자당 요청 수를 제한하는 Rate Limit 필터 (Rate Limit Filter)

Pipelines의 실제 정체

Pipelines는 Open WebUI 내부에서 로드되는 플러그인이 아닙니다. 이는 9099 포트에서 실행되는 투명한 OpenAI API 프록시 (Proxy) 역할을 하는 별도의 서버입니다. Open WebUI는 Ollama나 다른 OpenAI 호환 백엔드(OpenAI-compatible backend)와 통신하는 것과 정확히 동일한 방식으로 Pipelines와 통신합니다. Pipelines는 사용자가 프로그래밍한 대로 동작한 후, 결과를 직접 반환하거나 (수정되었을 수도 있는) 요청을 실제 LLM으로 전달합니다.

이러한 아키텍처는 다음과 같은 이유로 중요합니다:

  • Pipelines 로직은 브라우저가 아닌 서버 측 (Server-side)에서 실행됩니다.
  • 사용자가 클라이언트를 변경하더라도 이를 우회할 수 없습니다.
  • 요청 간의 상태 (State)를 유지할 수 있습니다 (요청 카운터, 캐시, 메모리 등).

파이프라인에는 두 가지 유형이 있습니다:

유형작동 방식용도
필터 (Filter)요청을 감쌉니다: inlet() → LLM → outlet()Rate limiting (속도 제한), 로깅 (Logging), 시스템 프롬프트 주입 (System Prompt Injection), 콘텐츠 필터링
파이프 (Pipe)LLM을 완전히 대체하며, Open WebUI에서 "모델"로 나타납니다웹 검색 (Web Search), 커스텀 RAG, 비-OpenAI API 래핑 (Wrapping)

필터는 기존 모델 주변에 동작을 추가합니다. 파이프는 그 자체가 모델입니다.

사전 요구 사항

  • Open WebUI v0.9.5 실행 중 (Ollama + Open WebUI Linux 설정 가이드 참조)
  • 동일한 호스트에 Docker 설치됨
  • 11434 포트(기본값)에서 Ollama 실행 중
  • Python 3.11: 파이프라인 (Pipelines)을 로컬에서 개발하려는 경우에만 필요 — 그 외에는 Docker가 처리함

1단계: 파이프라인 (Pipelines) 서버 배포

docker run -d \
  -p 9099:9099 \
  --add-host=host.docker.internal:host-gateway \
...

플래그 (Flag) 상세 설명:

  • -p 9099:9099 — 호스트에서 파이프라인 (Pipelines) API를 노출합니다.
  • --add-host=host.docker.internal:host-gateway — 컨테이너가 호스트 머신의 서비스(Ollama, 로컬 API, SearXNG)에 접근할 수 있게 합니다.
  • -v pipelines:/app/pipelines — 파이프라인 (Pipelines) Python 파일들을 이름이 지정된 Docker 볼륨 (Volume)에 영구 저장합니다. 이 파일들은 컨테이너 재시작 및 업데이트 후에도 유지됩니다.

서버가 작동하는지 확인하세요:

curl http://localhost:9099/
# 예상 결과: {"detail":"Not Found"}  ← 서버가 응답하고 있음을 의미합니다

기본 API 키는 0p3n-w3bu!입니다. 이는 공개된 정보이므로 로컬호스트 (localhost) 환경에서는 괜찮지만, 네트워크 접근이 가능한 환경에서는 적절하지 않습니다. docker run 명령에 -e WEBUI_SECRET_KEY=your-actual-secret을 추가하여 키를 변경하세요.

2단계: 파이프라인 (Pipelines)을 Open WebUI에 연결

  1. Open WebUI → Admin Panel (관리 패널) → Settings (설정) → Connections (연결)
  2. **+**를 클릭하여 새로운 OpenAI 호환 연결을 추가합니다.
  3. API URL: http://localhost:9099
    • Open WebUI 자체가 Docker에서 실행 중이라면, 대신 http://host.docker.internal:9099를 사용하세요.
  4. API key: 0p3n-w3bu! (또는 설정한 키)
  5. 저장 후 페이지를 새로고침합니다.

이제 파이프 (Pipe) 유형의 파이프라인 (Pipelines)이 Open WebUI의 모델 선택기 (Model picker)에 나타납니다. 필터 (Filter) 유형의 파이프라인 (Pipelines)은 Admin Panel (관리 패널) → Pipelines (파이프라인) 아래에 나타나며, 여기서 특정 모델 또는 모든 모델에 할당할 수 있습니다.

파이프라인 (Pipeline) 예시 1: 실시간 웹 검색

이 파이프 (Pipe) 파이프라인 (Pipeline)은 검색 결과를 가져와 쿼리를 로컬 Ollama 모델로 전달하기 전에 컨텍스트 (Context)로 주입합니다. 결과적으로, 여러분의 LLM은 별도의 미세 조정 (Fine-tuning) 없이도 최신 사건에 관한 질문에 답변할 수 있습니다.

DuckDuckGo에 대하여: DDG의 비공식 스크래핑 (Scraping) API는 명백한 무료 선택지이지만, 2026년 현재는 속도 제한 (Rate limiting)이 매우 엄격합니다. 동일한 IP에서 몇 번의 쿼리만 실행해도 202 Ratelimit 오류가 발생합니다. 요청 사이에 지연 시간을 두는 가벼운 개인용으로는 작동하지만, 모든 메시지마다 실행되는 파이프라인 (Pipeline) 용도로는 신뢰할 수 없습니다. 두 가지 실질적인 대안은 다음과 같습니다:

  • Brave Search API — 무료 티어 제공, 월 2,000회 쿼리 가능, 실제 JSON API 방식
  • SearXNG (자체 호스팅, 비용 제로, 속도 제한 없음) — API 호출 부분만 교체하면 완료

Docker가 파이프라인 볼륨 (Volume)을 매핑하는 파일 위치를 생성하세요. 기본 설치의 경우, 다음 명령어로 경로를 찾을 수 있습니다:

docker inspect pipelines | grep -A5 Mounts
# "Source" 경로를 찾으세요. 일반적으로 /var/lib/docker/volumes/pipelines/_data 입니다.

해당 디렉토리에 web_search_pipeline.py라는 이름으로 저장하세요:

from typing import List, Optional
import requests
from pydantic import BaseModel
...

저장한 후, Admin Panel → Pipelines로 이동하여 Refresh를 클릭하세요. "Web Search"가 나타납니다. UI를 통해 밸브 (Valves) (Brave 키 또는 SearXNG URL)를 설정하세요. 변경 사항은 아무것도 재시작하지 않고 즉시 적용됩니다.

파이프라인 예시 2: 사용자별 속도 제한 (Per-User Rate Limiting)

여러 명이 Open WebUI 인스턴스를 사용하는 경우, 속도 제한 (Rate limits)이 필요합니다. 속도 제한이 없으면, 헤비 유저 한 명이 요청을 쌓아두어 다른 모든 사용자의 접속을 차단할 수 있습니다. 이 필터는 슬라이딩 윈도우 (Sliding window) 방식을 사용하여 사용자 ID별 요청을 추적합니다:

rate_limit_filter.py로 저장하세요:

from typing import List, Optional
...

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0