📊 Open WebUI 모니터링

모니터링으로 Open WebUI 건강 유지 🩺

Open WebUI 인스턴스를 모니터링하는 것은 안정적으로 실행되고, 성능이 좋으며, 문제를 신속히 식별하고 해결할 수 있도록 하는 데 필수적입니다. 이 가이드에서는 기본 가용성 확인에서 심층적인 모델 응답 테스트에 이르는 세 가지 모니터링 수준을 설명합니다.

왜 모니터링해야 할까요?

• 가동 시간 보장: 중단 및 서비스 중단을 사전에 탐지합니다.
• 성능 통찰: 응답 시간을 추적하고 잠재적인 병목현상을 식별합니다.
• 초기 문제 탐지: 문제가 사용자에게 심각한 영향을 미치기 전에 포착합니다.
• 마음의 평화: Open WebUI 인스턴스가 원활하게 실행되고 있다는 자신감을 가집니다.

🚦 모니터링 수준

세 가지 수준의 모니터링을 다룰 것입니다. 기본적인 것부터 더 포괄적인 것까지 진행합니다:

1. 기본 상태 확인: Open WebUI 서비스가 실행되고 응답 중인지 확인합니다.
2. 모델 연결성 확인: Open WebUI가 구성된 모델에 연결하고 나열할 수 있는지 확인합니다.
3. 모델 응답 테스트 (심층 상태 확인): 모델이 실제로 요청을 처리하고 응답을 생성할 수 있는지 확인합니다.

레벨 1: 기본 상태 확인 엔드포인트 ✅

가장 간단한 모니터링 수준은 /health 엔드포인트를 확인하는 것입니다. 이 엔드포인트는 공개적으로 접근 가능하며 (인증 불필요), Open WebUI 서비스가 올바르게 실행 중인 경우 200 OK 상태 코드를 반환합니다.

테스트 방법:

curl 또는 HTTP 클라이언트를 사용하여 이 엔드포인트를 확인할 수 있습니다:

   # 기본 상태 확인 - 인증 불필요
   curl https://your-open-webui-instance/health

기대 출력: 성공적인 상태 확인은 200 OK HTTP 상태 코드를 반환합니다. 기본 상태 확인의 경우 응답 본문의 내용은 일반적으로 중요하지 않습니다.

Uptime Kuma를 사용한 기본 상태 확인 🐻

Uptime Kuma는 환상적이고 오픈소스이면서 사용하기 쉬운 셀프 호스팅 업타임 모니터링 도구입니다. Open WebUI 모니터링에 강력히 권장됩니다.

Uptime Kuma 설정 단계:

1. 새 모니터 추가: Uptime Kuma 대시보드에서 "새 모니터 추가"를 클릭합니다.
2. 모니터 설정 구성:
   • 모니터 유형: "HTTP(s)"를 선택합니다.
   • 이름: 모니터에 설명적인 이름을 지정합니다. 예: "Open WebUI 상태 확인"
   • URL: 상태 확인 엔드포인트 URL 입력: http://your-open-webui-instance:8080/health (여기서 your-open-webui-instance:8080을 실제 Open WebUI 주소 및 포트로 대체).
   • 모니터링 간격: 확인 빈도를 설정합니다 (예: 60초는 매 분 단위).
   • 재시도 횟수: 서비스가 중단된 것으로 간주하기 전 재시도 횟수 설정 (예: 3회 재시도).

이 확인이 검증하는 것:

• 웹 서버 가용성: 웹 서버(Nginx, Uvicorn 등)가 요청에 응답하고 있는지 확인합니다.
• 애플리케이션 실행 상태: Open WebUI 애플리케이션 자체가 실행 중이고 초기화 상태인지 확인합니다.
• 기본 데이터베이스 연결성: 일반적으로 애플리케이션이 데이터베이스에 연결할 수 있는지 기본 체크를 포함합니다.

레벨 2: Open WebUI 모델 연결 🔗

기본 가용성을 넘어 /api/models 엔드포인트를 모니터링할 수 있습니다. 이 엔드포인트는 인증이 필요하며, Open WebUI가 구성된 모델 제공자 (예: Ollama, OpenAI)와 성공적으로 통신하고 사용 가능한 모델 목록을 검색할 수 있는지 확인합니다.

모델 연결성을 모니터링해야 하는 이유?

• 모델 제공자 문제: 모델 제공자 서비스 문제 (예: API 중단, 인증 실패)를 탐지합니다.
• 구성 오류: Open WebUI 내 모델 제공자 설정의 구성 오류를 식별합니다.
• 모델 가용성 보장: 예상했던 모델이 실제로 Open WebUI에서 접근 가능한지 확인합니다.

API 엔드포인트 세부사항:

Open WebUI API 문서에서 /api/models 엔드포인트와 응답 구조에 대한 전체 정보를 확인하세요.

curl을 사용한 테스트 방법 (인증 필요):

이 엔드포인트에 접근하려면 API 키가 필요합니다. 아래의 "인증 설정" 섹션에서 API 키 생성 지침을 확인하세요.

   # 인증된 모델 연결 확인
   curl -H "Authorization: Bearer YOUR_API_KEY" https://your-open-webui-instance/api/models

(YOUR_API_KEY를 실제 API 키로, your-open-webui-instance를 Open WebUI 주소로 대체하세요.)

기대 출력: 성공적인 요청은 200 OK 상태 코드와 모델 목록이 포함된 JSON 응답을 반환합니다.

API 키 인증 설정 🔑

먼저 Open WebUI에서 API 키를 활성화하고 하나를 생성해야 /api/models 엔드포인트를 모니터링할 수 있습니다:

1. API 키 활성화 (관리자 필요):

   • 관리자 권한으로 Open WebUI에 로그인하세요.
   • 관리자 설정 (일반적으로 오른쪽 상단 메뉴에서) > 일반 설정으로 이동합니다.
   • "API 키 사용" 설정을 찾아 켜기로 설정합니다.
   • 변경 사항 저장을 클릭합니다.

2. API 키 생성 (사용자 설정):

   • 사용자 설정 (일반적으로 오른쪽 상단의 프로필 아이콘 클릭)을 엽니다.
   • 계정 섹션으로 이동합니다.
   • 새 API 키 생성을 클릭합니다.
   • API 키에 설명이 포함된 이름을 입력합니다 (예: "모니터링 API 키").
   • 생성된 API 키를 복사하고 안전하게 저장합니다. 이 키는 모니터링 설정에 필요합니다.

   (선택 사항이지만 권장) 보안 모범 사례를 위해 비관리자 사용자 계정을 생성하고 해당 사용자에 대한 API 키를 생성하는 것을 고려하세요. 이는 모니터링 API 키가 유출되었을 경우의 잠재적 영향을 제한합니다.

   설정에서 API 키 생성 옵션이 보이지 않으면 Open WebUI 관리자가 API 키가 활성화되었는지 확인해야 합니다.

Uptime Kuma를 사용한 모델 연결 모니터링 🐻

1. Uptime Kuma에서 새 모니터 생성:

   • 모니터 유형: "HTTP(s) - JSON Query".
   • 이름: "Open WebUI 모델 연결 상태 확인".
   • URL: http://your-open-webui-instance:8080/api/models (URL을 변경하세요).
   • 메서드: "GET".
   • 예상 상태 코드: 200.

2. JSON Query 설정 (모델 목록 확인):

   • JSON Query: $count(data[*])>0
     • 설명: 이 JSONata 쿼리는 API 응답의 data 배열(모델 목록을 포함)이 0보다 큰 항목을 포함하는지 확인합니다. 즉, 하나 이상의 모델이 반환되었는지 확인합니다.
   • 예상 값: true (쿼리는 모델이 나열된 경우 true를 반환해야 함).

3. 인증 헤더 추가:

   • Uptime Kuma 모니터 설정의 "헤더" 섹션에서 "헤더 추가"를 클릭합니다.
   • 헤더 이름: Authorization
   • 헤더 값: Bearer YOUR_API_KEY (YOUR_API_KEY를 생성된 API 키로 대체).

4. 모니터링 간격 설정: 권장 간격: 300초 (5분) 이상. 모델 목록은 일반적으로 자주 변경되지 않습니다.

대체 JSON Query (고급):

더 특정한 JSONata 쿼리를 사용하여 특정 모델 또는 제공자를 확인할 수 있습니다. 아래는 몇 가지 예입니다:

• 적어도 하나의 Ollama 모델 확인: $count(data[owned_by=ollama])>0
• 특정 모델이 존재하는지 확인 (예: gpt-4o): $exists(data[id=gpt-4o])
• 여러 특정 모델이 존재하는지 확인 (예: gpt-4o와 gpt-4o-mini): $count(data[id in [gpt-4o, gpt-4o-mini]]) = 2

JSONata 쿼리를 테스트하고 최적화하려면 jsonata.org에서 샘플 API 응답을 사용하여 작동 여부를 확인하세요.

3단계: 모델 응답 테스트 (심층 상태 점검) 🤖

가장 포괄적인 모니터링을 위해 모델이 실제로 요청을 처리하고 응답을 생성할 수 있는지 테스트할 수 있습니다. 이는 /api/chat/completions 엔드포인트에 간단한 채팅 완료 요청을 보내는 것입니다.

모델 응답 테스트 이유

• 엔드-투-엔드 확인: API 요청에서 모델 응답까지 전체 모델 파이프라인이 작동하는지 확인.
• 모델 로딩 문제: 특정 모델이 로드되거나 응답하지 못하는 문제 감지.
• 백엔드 처리 오류: 모델이 응답을 생성하지 못하게 하는 백엔드 논리 오류 감지.

curl을 사용한 테스트 (인증된 POST 요청):

이 테스트는 API 키가 필요하며 채팅 완료 엔드포인트에 간단한 메시지를 POST 요청으로 보냅니다.

# 인증된 POST 요청으로 모델 응답 테스트
curl -X POST https://your-open-webui-instance/api/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d {
    "messages": [{"role": "user", "content": "Respond with the word HEALTHY"}],
    "model": "llama3.1",  # 사용할 것으로 예상되는 모델로 대체
    "temperature": 0      # 일관된 응답을 위해 온도를 0으로 설정
  }

(YOUR_API_KEY, your-open-webui-instance, llama3.1 값을 실제 값으로 대체하세요.)

예상 출력: 성공적인 요청은 200 OK 상태 코드와 챗봇 응답이 포함된 JSON 응답을 반환합니다. 응답이 "HEALTHY"라는 단어를 포함하는지 확인합니다 (또는 프롬프트에 따라 유사한 예상 응답).

Uptime Kuma에서 3단계 모니터링을 설정하려면 POST 요청, JSON 본문, 인증 헤더 및 응답 내용을 검증하기 위한 JSON 쿼리를 포함한 HTTP(s) 모니터를 구성해야 합니다. 이는 더 고급 설정으로, 특정 요구 사항에 맞게 사용자 정의할 수 있습니다.

이 모니터링 단계를 구현하면 Open WebUI 인스턴스의 상태, 신뢰성 및 성능을 적극적으로 보장하여 사용자에게 일관된 긍정적 경험을 제공할 수 있습니다.