모델 연결 - 딥러닝 언어 모델

"모델"은 매개변수화된 일련의 수학적 함수라고 할 수 있습니다. 모델을 사용한다는 것은 그러한 함수에 입력을 제공하고, 출력을 받는 것입니다.

\hat{y} = f(x; \theta)

(1)

모델의 수학적 연산에는 다양한 프레임워크가 사용됩니다. 파이토치나 텐서플로우가 대표적이고, 그 밖에도 다양합니다. 수학적 연산만 올바르게 구현된다면 어떤 것이든 사용할 수 있습니다.

그런데 이런 연산을 호출하는 데 코드가 필요하다면 모델의 사용은 너무 기술적인 일이 됩니다. 사용자가 AI를 사용하는 목표는 코드 작성과 함수 호출이 아닌 지식의 습득과 가공입니다. 이런 목표를 달성하는 수단으로써 지능형 모델이 역할을 해야 합니다. 그래서 수학적 연산을 수행하는 코드 실행은 내부적으로 처리하고, 외부적으로는 일반적인 REST API를 제공하는 플랫폼들이 널리 활용되고 있습니다.

이런 플랫폼들은 종종 ‘모델 엔진’, ‘모델 제공자(provider)’ 등으로 부르기도 합니다. 여기서는, '모델 제공자’라는 용어를 사용하겠습니다. OpenAI의 ChatGPT, 앤트로픽의 클로드(Claude) 등과 같은 모델 제공자의 지능 모델은 원격 서버에서 실행됩니다. 반면, Ollama와 같은 모델 제공자는 원격 서버가 아닌 ‘로컬’ 컴퓨터에서 모델을 호출할 수 있도록 해줍니다.

클라우드 서비스든 로컬이든, Open WebUI와 같은 프론트엔드 서비스는 REST API를 사용해 요청을 보내고, 응답을 받아 화면에 출력하는 역할을 수행합니다. 즉, Open WebUI는 모델의 연산을 직접 수행하지 않고, 네트워크 통신을 통해 모델을 사용합니다. Ollama처럼 동일한 컴퓨터에서 동작하는 서비스라도 여전히 네트워크를 사용합니다. 그래서 Open WebUI는 특정한 규격의 REST API로 된 서비스라면 어떤 것과도 연결할 수 있습니다.

Open WebUI가 제공하는 연결 유형은 두 가지이며, 설치 시 기본 URL이 함께 설정되어 있습니다.

Ollama: Ollama 고유 API로 연결합니다. 추론 호출뿐 아니라 모델 다운로드·삭제·언로드 같은 관리 기능까지 지원합니다.
OpenAI API: OpenAI의 /v1 규격을 사용하는 방식입니다. OpenAI는 물론, 같은 규격을 노출하는 다른 제공자까지 모두 이 유형으로 연결하며 추론 호출에 집중합니다.

두 유형 모두 관리자 설정(Admin Settings) → 연결(Connections) 에서 추가·관리합니다. 아래에서는 Ollama, OpenAI, 그리고 OpenAI 호환 제공자 순으로 살펴봅니다.

1Ollama 연결¶

Ollama는 Ollama API 프로토콜(기본 포트 11434)을 통해 Open WebUI와 연결됩니다. Open WebUI를 설치하면 기본 연결이 자동으로 설정되며, 연결되지 않을 경우 대부분 네트워크 설정 문제입니다. 연결은 관리자 설정(Admin Settings) → 연결(Connections) 에서 관리할 수 있습니다.

1.1연결 주소¶

같은 컴퓨터: Open WebUI와 Ollama가 동일한 머신에서 동작하면 루프백 주소 http://localhost:11434로 별도 설정 없이 연결됩니다.
Docker 컨테이너: Open WebUI가 컨테이너 안에서 동작하고 Ollama가 호스트에서 동작하면 http://host.docker.internal:11434를 연결 주소로 지정합니다. 컨테이너 안의 localhost는 호스트가 아니라 컨테이너 자신을 가리키기 때문입니다.

1.2모델 관리¶

다운로드: 관리 화면에서 모델 태그명(예: llama3, qwen2:7b)을 입력해 로컬 서버로 내려받습니다. 관리자 설정에 들어가지 않고도 대화 화면 상단의 모델 선택창에서 필요한 모델을 즉석에서 요청해 받을 수도 있습니다.
언로드(Eject): 관리자에게는 메모리에 적재된(warm) 모델을 내리는 Eject 버튼이 표시됩니다. 이 버튼은 POST /api/models/unload(관리자 전용)를 호출해 GPU/VRAM을 비웁니다.

1.3다중 Ollama 인스턴스¶

여러 대의 가속 머신에 Ollama가 분산되어 있다면 연결 주소를 여러 개 등록해 추론 요청을 분산할 수 있습니다.

로드 밸런싱: 동시 사용자의 요청을 등록된 인스턴스에 무작위(random selection)로 분배하는 기본적인 로드 밸런싱을 제공합니다.
모델 병합: 인스턴스 간에 모델 ID가 정확히 일치해야 하나의 모델로 병합되어 표시됩니다.
Prefix ID: 여러 인스턴스가 같은 이름의 모델을 서빙할 때, 접두사(예: remote/)를 붙여 인스턴스별로 구분합니다.
Model IDs (Filter): 노출할 모델만 화이트리스트로 지정합니다. 비워 두면 모든 모델이 표시됩니다.
연결 타임아웃: 모델 목록 조회 타임아웃은 AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST 환경 변수로 조정합니다(기본 10초).

2OpenAI 연결¶

OpenAI는 가장 널리 쓰이는 클라우드 모델 제공자로, 설치 시 기본 연결 대상에 포함되어 있습니다. Ollama와 달리 모델이 원격 서버에서 실행되므로, 연결에는 OpenAI에서 발급한 API 키가 필요합니다. 연결은 관리자 설정(Admin Settings) → 연결(Connections) → OpenAI → 관리(Manage) 에서 새 연결 추가(Add New Connection) 로 등록합니다.

Base URL: https://api.openai.com/v1
API Key: platform.openai.com에서 발급한 비밀 키(sk-로 시작)를 입력합니다.
Model IDs (Filter): 비워 두면 제공자의 모든 모델을 자동 감지하고, 값을 입력하면 화이트리스트로 동작해 지정한 모델만 노출합니다.

Google Gemini, Mistral, Groq, DeepSeek 등 OpenAI 규격을 따르는 다른 제공자도 같은 방식으로 연결할 수 있습니다.

3OpenAI 호환 API (OpenAI-Compatible) 연결¶

vLLM, LocalAI, LM Studio처럼 OpenAI 규격의 엔드포인트를 노출하는 다양한 추론 서버를 이 방식으로 연결합니다.

연결 정보 입력: 연결 목록에 제공자를 추가하고, 서버가 제공하는 Base URL(예: vLLM의 http://<server-ip>:8000/v1)과 필요한 경우 API Key를 입력합니다.
모델 목록 자동 동기화: 연결되면 제공자가 서빙 중인 모델 목록을 자동으로 불러와 대화 화면의 모델 선택창에 표시합니다.
수동 모델 등록 (Model IDs Filter): 일부 서버는 /models 조회 엔드포인트를 제공하지 않아 모델 목록을 자동으로 가져오지 못합니다. 이때는 Model IDs (Filter) 입력란에 모델 ID(예: qwen2:7b)를 직접 입력해 등록합니다.
브라우저 직접 연결 (Direct Connections): 기본적으로 Open WebUI 백엔드가 모델 API 요청을 중계하지만, Direct Connections를 켜면 사용자의 브라우저가 모델 API로 직접 요청을 보냅니다. 백엔드 부하와 지연을 줄일 수 있습니다.
- 설정 방식: 관리자 패널의 Direct Connections 토글을 켜거나, 컨테이너 실행 시 ENABLE_DIRECT_CONNECTIONS=True 환경 변수를 설정합니다.
- 주의사항: 브라우저가 제공자 API 서버와 직접 통신(Cross-Origin)하므로, 대상 API 서버에 CORS(Cross-Origin Resource Sharing) 허용 설정이 되어 있어야 합니다.