Open WebUI OpenAI 호환 API 설정 가이드

개방형 WebUI란 무엇입니까?

Open WebUI는 AI 모델과 채팅하고 OpenAI 호환 모델 공급자를 연결하기 위한 자체 호스팅 인터페이스입니다.

이 Open WebUI 설정은 관리자 연결 패널에서 TokenHub를 추가합니다. OpenAI Chat Completions 프로토콜을 사용하고 공급자가 /models를 노출하지 않을 때 수동 모델 허용 목록을 제공합니다. 연결은 하나의 OpenAI 호환 공급자가 사용자에게 하나 이상의 모델을 노출할 수 있는 관리자 연결 패널에 속합니다. 자동 모델 검색을 사용할 수 없는 경우 채팅 엔드포인트가 손상되었다고 가정하는 대신 모델 허용 목록을 사용하고 Docker로 자체 호스팅할 때 Open WebUI 컨테이너 내부에서 네트워크 액세스를 테스트하세요.

Open WebUI는 모든 공급자에 대해 별도의 플러그인을 요구하는 대신 프로토콜별로 모델 서비스를 관리합니다. TokenHub를 OpenAI API Connection로 추가합니다. 그런 다음 Open WebUI는 /models 및 /chat/completions를 API 기본 URL에 추가합니다.

관리 연결 아래에 TokenHub를 추가하세요.

이는 Open WebUI의 공식 Step 1: Add Your Provider Connection 순서를 따릅니다.

관리자 계정으로 Open WebUI에 로그인합니다.
Settings → Admin → Connections로 이동합니다.
Manage OpenAI API Connections를 찾아 Add Connection(더하기 버튼)를 클릭합니다.
URL에 https://us-api.tokenhub.com/v1를 입력합니다.
API Key에 TokenHub API 키를 입력하세요.
연결 확인에서 모델이 반환되지 않으면 Model IDs (Filter) 아래에 정확한 TokenHub 모델 ID를 입력하고 더하기 버튼을 클릭하여 허용 목록에 추가하세요.
Save를 클릭합니다.

URL에 /chat/completions를 넣지 마십시오. Open WebUI는 요청 경로 자체를 추가하므로 전체 요청 URL는 중복된 경로를 생성합니다.

연결 확인 및 모델 ID 이해(필터)

저장하기 전에 Open WebUI는 공급자의 /models 엔드포인트에 표준 Bearer 토큰 요청을 보냅니다. 문서에는 채팅 완료가 작동하더라도 일부 호환 서비스가 이 검색 요청에 400, 401 또는 403을 반환한다고 나와 있습니다. 다음 순서로 테스트하세요.

Model IDs (Filter) 아래에 모델 ID를 수동으로 추가하고 저장하세요.
새 채팅을 시작하고 모델이 선택기에 나타나는지 확인하세요.
실제 채팅 완료 요청을 테스트할 수 있도록 이를 선택하고 메시지를 보냅니다.

각 모델 ID를 한 번만 추가하세요. Open WebUI는 주변 공백을 잘라냅니다. 연결 옆의 스위치는 설정을 삭제하지 않고 공급자를 일시적으로 비활성화합니다.

원격 API를 호스트.docker.internal로 대체하지 마십시오.

공식 host.docker.internal 팁은 Open WebUI 컨테이너가 Docker 호스트에서 실행되는 모델 서버에 도달해야 하는 경우에만 적용됩니다. TokenHub는 원격 HTTPS 서비스이므로 https://us-api.tokenhub.com/v1를 유지하세요. 컨테이너만 시간 초과되는 경우 URL를 localhost로 변경하는 대신 DNS 확인, 아웃바운드 HTTPS 액세스 및 프록시 구성을 검사하세요.

Open WebUI가 실제로 보내는 요청을 확인하세요.

채팅을 생성하고 허용 목록에 추가한 TokenHub 모델을 선택하세요.
먼저 짧은 텍스트 전용 메시지를 보내세요.
TokenHub 요청 로그에서 경로가 /v1/chat/completions이고 모델 ID가 정확하며 사용량이 기록되었는지 확인합니다.
기본 채팅 작업 후에만 테스트 도구, 이미지, 지식 기능을 별도로 테스트합니다. Open WebUI의 컨트롤은 선택한 모델이나 호환 엔드포인트가 해당 기능을 지원한다고 보장하지 않습니다.

404의 경우 먼저 URL가 /v1에서 끝나는지 확인하세요. 모델이 누락된 경우 **Model IDs (Filter)**로 돌아갑니다. Docker에서만 오류가 발생하는 경우 컨테이너 네트워크를 검사합니다.

공식 참고자료

Open WebUI: OpenAI-compatible 공급자 연결

모델 선택 방법

작업모델 선택이유

복잡한 작업도구 사용 추론 모델계획, 다단계 실행, 긴 컨텍스트에 적합합니다.

일상 작업균형 잡힌 모델품질, 속도, 비용의 균형을 제공합니다.

요약 및 가벼운 작업빠르고 저렴한 모델요약과 단순 반복 비용을 줄입니다.

TokenHub 모델 보기

WebUI API 설정 FAQ 열기

Open WebUI에 OpenAI 호환 API를 어떻게 추가하나요?

설정 → 관리 → 연결을 열고 OpenAI API 연결 관리에서 연결을 추가하세요. TokenHub /v1 URL과 API 키를 입력한 후 저장하세요.

Open WebUI URL에 /chat/completions가 포함되어야 합니까?

아니요. /v1로 끝나는 API 루트를 사용하세요. Open WebUI는 각 작업에 대한 요청 경로를 구성합니다.

Open WebUI 모델 목록이 비어 있는 이유는 무엇입니까?

모델 검색을 사용할 수 없는 경우 모델 ID(필터) 아래에 정확한 TokenHub 모델 ID를 추가하고 저장한 후 새 채팅 모델 선택기를 다시 엽니다.

Dockerized Open WebUI가 TokenHub에 도달할 수 없는 이유는 무엇입니까?

Open WebUI 컨테이너 내부에서 DNS, 프록시, 인증서 및 아웃바운드 액세스를 테스트합니다. 호스트-브라우저 연결은 컨테이너에 네트워크 액세스 권한이 있음을 증명하지 않습니다.

Open WebUI가 TokenHub를 사용하고 있는지 어떻게 확인하나요?

새 채팅에서 구성된 모델을 선택하고, 짧은 메시지를 보내고, TokenHub 요청 로그에서 모델 ID, 상태 및 토큰 사용을 확인하세요.

WebUI API 설정 열기