Open WebUI

Open WebUI

이 가이드는 Open WebUI를 LiteLLM에 연결하는 방법을 안내합니다. LiteLLM을 Open WebUI와 함께 사용하면 팀이 다음을 할 수 있어요:

  • Open WebUI에서 100개 이상의 LLM에 접근
  • 지출/사용량 추적, 예산 한도 설정
  • 요청/응답 로그를 langfuse, s3, gcs 버킷 등의 로깅 목적지로 전송
  • 접근 제어 설정 - 예: Open WebUI가 접근할 수 있는 모델 제어

빠른 시작

  • LiteLLM Quickstart로 LiteLLM을 먼저 설정하세요.

1. LiteLLM과 Open WebUI 시작

2. LiteLLM에 Virtual Key 생성

Virtual Key는 LiteLLM Proxy에 인증할 수 있게 해주는 API Key예요. Open WebUI가 LiteLLM에 접근하도록 허용하는 Virtual Key를 만들 거예요.

2.1 LiteLLM 사용자 관리 계층

LiteLLM에서는 Organizations, Teams, Users, Virtual Keys를 만들 수 있어요. 이 튜토리얼에서는 Team과 Virtual Key를 만들 거예요.

  • Organization - Organizations는 Teams의 그룹입니다.(US Engineering, EU Developer Tools)
  • Team - Team은 Users의 그룹입니다.(Open WebUI Team, Data Science Team 등)
  • User - User는 개별 사용자예요.(직원, 개발자, 예: [email protected])
  • Virtual Key - Virtual Key는 LiteLLM Proxy에 인증할 수 있게 해주는 API Key예요. Virtual Key는 User 또는 Team에 연결됩니다.

Team이 생성되면 Team에 User를 초대할 수 있어요. LiteLLM 사용자 관리에 대해 더 읽어보려면 여기를 참고하세요.

2.2 LiteLLM에 Team 생성

http://localhost:4000/ui로 이동해 새 team을 만드세요.

2.2 LiteLLM에 Virtual Key 생성

http://localhost:4000/ui로 이동해 새 virtual key를 만드세요.

LiteLLM은 Open WebUI에서 어떤 모델을 사용할 수 있는지 지정할 수 있게 해줍니다(키가 접근 가능한 모델을 지정함으로써).

3. Open WebUI를 LiteLLM에 연결

Open WebUI에서 Settings -> Connections로 이동해 LiteLLM에 새 연결을 만드세요.

다음 정보를 입력하세요:

  • URL: http://localhost:4000(여러분의 litellm proxy base url)
  • Key: your-virtual-key(이전 단계에서 만든 키)

3.1 테스트 요청

왼쪽 상단에서 모델을 선택하면 2단계에서 키에 접근을 허용한 모델만 보일 거예요.

모델을 선택한 뒤 메시지 내용을 입력하고 Submit을 클릭하세요.

3.2 사용량 및 지출 추적

기본 추적

요청을 보낸 뒤 LiteLLM UI의 Logs 섹션으로 이동해 Model, Usage, Cost 정보를 확인하세요.

사용자별 추적

각 Open WebUI 사용자의 지출과 사용량을 추적하려면 Open WebUI와 LiteLLM을 모두 구성하세요:

  • Open WebUI에서 사용자 정보 헤더 활성화

Open WebUI가 요청 헤더에 사용자 정보를 포함하게 하려면 다음 환경 변수를 설정하세요:

ENABLE_FORWARD_USER_INFO_HEADERS=True

자세한 내용은 Environment Variable Configuration Guide를 참고하세요.

  • LiteLLM이 사용자 헤더를 파싱하도록 구성

사용자 추적을 위한 요청 헤더 매핑을 지정하려면 LiteLLM config.yaml에 다음을 추가하세요:

general_settings:
  user_header_mappings:
    - header_name: X-OpenWebUI-User-Id
      litellm_user_role: internal_user
    - header_name: X-OpenWebUI-User-Email
      litellm_user_role: customer

ⓘ 사용 가능한 추적 옵션

user_header_mappings의 header_name에 다음 헤더 중 아무거나 사용할 수 있어요:

  • X-OpenWebUI-User-Id
  • X-OpenWebUI-User-Email
  • X-OpenWebUI-User-Name

잘 아는 소규모 사용자 그룹을 호스팅할 때는 이들이 가독성이 좋고 귀속(attribution)을 더 쉽게 만듭니다. 필요에 따라 선택하되, Open WebUI에서는 다음을 참고하세요:

  • 사용자는 자신의 사용자 이름을 수정할 수 있음
  • 관리자는 모든 계정의 사용자 이름과 이메일을 수정할 수 있음

이 영상은 openweb ui 헤더를 LiteLLM user roles에 매핑하는 방법을 안내합니다.

Open WebUI에서 thinking 콘텐츠 렌더링

Open WebUI는 reasoning/thinking 콘텐츠가 thinking response 태그로 렌더링되도록 요구합니다. 특정 모델에 대해 이렇게 렌더링하려면 merge_reasoning_content_in_choices litellm 파라미터를 사용할 수 있어요.

예시 litellm config.yaml:

model_list:
  - model_name: thinking-anthropic-claude-sonnet-5 # Bedrock Anthropic
    litellm_params:
      model: bedrock/us.anthropic.claude-sonnet-5
      thinking: {"type": "enabled", "budget_tokens": 1024}
      max_tokens: 1080
      merge_reasoning_content_in_choices: true
  - model_name: vertex_ai/gemini-3.1-pro-preview # Vertex AI Gemini
    litellm_params:
      model: vertex_ai/gemini-3.1-pro-preview
      thinking: {"type": "enabled", "budget_tokens": 1024}
      merge_reasoning_content_in_choices: true

Open WebUI에서 테스트하기

모델 드롭다운에서 thinking-anthropic-claude-sonnet-5를 선택하세요.

추가 리소스

지출 추적에 커스텀 헤더 추가

지출과 사용량을 추적하기 위해 요청에 커스텀 헤더를 추가할 수 있어요.

litellm_settings:
  extra_spend_tag_headers:
    - "x-custom-header"

지출과 사용량을 추적하기 위해 요청에 커스텀 헤더를 추가할 수 있어요.

더 알아보기 (Learn more)