GUI와 함께 Ollama 사용법 (호스팅된 대체 연결)

Ollama가 별도 GUI가 필요한 이유

GUI와 함께 Ollama를 사용하는 방법을 알고 싶다면, 먼저 Ollama 프로젝트가 서버이자 명령줄 도구라는 사실을 받아들이셔야 합니다. Ollama는 모델을 가져오고 로컬 포트에서 요청에 응답합니다. 채팅 창은 다른 프로그램의 역할이며, 훌륭한 옵션이 여러 가지 있습니다.

이러한 분리는 유용합니다. Ollama는 로컬 머신에서 OpenAI 스타일 API를 노출하기 때문입니다 (기본적으로 /v1 아래 포트 11434). 사용자 지정 OpenAI Base URL을 설정할 수 있는 프론트엔드는 이를 사용할 수 있습니다. 동일한 특성 때문에 나중에 해당 프론트엔드를 다른 곳으로 연결할 수도 있습니다. 이 글은 먼저 로컬 설정을 설명한 후 호스팅된 엔드포인트를 두 번째 연결로 추가합니다.

프론트 엔드 선택

대부분의 사용자를 위한 세 가지 도구 계열이 있습니다. 최신 설치 단계는 자주 변경되므로 각 프로젝트의 자체 문서를 확인하세요.

• Open WebUI. 자체 호스팅 브라우저 인터페이스입니다. Ollama를 직접 지원하며 모든 OpenAI 호환 연결도 허용합니다. 일반적으로 Docker 또는 pip로 설치합니다.
• 데스크톱 클라이언트. Chatbox나 Msty와 같은 네이티브 앱은 설정 화면을 통해 Ollama 서버나 OpenAI 호환 제공업체를 추가할 수 있게 해줍니다. 별도 서버를 실행할 필요가 없습니다.
• 롤플레이 및 글쓰기용 프론트엔드. SillyTavern은 OpenAI 호환 엔드포인트를 추가할 수 있게 하며, 장편 소설과 성인용 동반자 캐릭터를 위한 유사한 도구들이 존재합니다.

Docker 컨테이너를 원하지 않는다면 데스크톱 클라이언트가 가장 빠른 경로입니다. 하나의 네트워크에서 여러 사람이 사용할 공유 인터페이스가 필요하다면 Open WebUI가 일반적인 선택입니다.

Open WebUI로 단계별 설정

1. Ollama를 설치하고 시작하며, ollama pull 명령으로 모델을 가져옵니다. 더 진행하기 전에 터미널에서 응답하는지 확인하세요.
2. Open WebUI를 시작합니다. Docker의 일반적인 패턴은 포트를 게시하고 데이터용 볼륨을 마운트하는 것입니다.
3. 웹 페이지를 열고 첫 번째 로컬 계정을 생성(관리자가 됨)한 후, 관리자 설정에서 연결 영역을 찾아보세요.
4. Ollama URL이 Ollama가 실행되는 머신을 가리키는지 확인하세요. 둘 다 같은 호스트에 있는 경우 포트 11434의 로컬 주소가 일반적입니다. Open WebUI가 컨테이너 내에서 실행되는 경우 localhost는 컨테이너 자체를 의미하므로 모델 목록이 비어 있는 가장 흔한 이유입니다.
5. 새로고침하고 드롭다운에서 모델을 선택한 후 메시지를 보내세요.

완전한 로컬 GUI입니다. 데이터가 컴퓨터를 벗어나지 않으며 속도는 GPU 또는 CPU에 따라 달라집니다.

호스팅된 OpenAI 호환 연결 추가

이제 대체 방법을 살펴보겠습니다. 로컬에서 실행할 수 있는 모델이 긴 장면에는 너무 작거나 GPU가 렌더링 중으로 바쁠 수 있습니다. 동일한 GUI에 두 번째 연결을 추가할 수 있습니다. 이를 위해서는 Google 또는 이메일과 비밀번호로 가입한 후 API 키 페이지에서 발급받을 수 있는 API 키가 필요합니다. 한 번의 클릭으로 사용 가능한 $0.50 트라이얼 크레딧은 결제가 필요 없으며 7일 동안 유효합니다.

Open WebUI에서 다음 값으로 OpenAI 연결을 추가하세요:

• Base URL: https://api.ollamansfw.com/v1
• API 키: 귀하의 키를 Authorization: Bearer 형식으로 전송합니다.
• 모델: uncensored

컨테이너 실행 시 환경 변수를 선호한다면 Open WebUI는 이 목적으로 OPENAI_API_BASE_URL 및 OPENAI_API_KEY을 문서로 제공합니다:

Copydocker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=https://api.ollamansfw.com/v1 \
  -e OPENAI_API_KEY=YOUR_KEY \
  -v open-webui:/app/backend/data \
  --name open-webui ghcr.io/open-webui/open-webui:main
# model to pick in the UI: uncensored

새로고침 후 모델 드롭다운에서 로컬 모델 옆에 uncensored가 표시되어야 합니다. 프론트엔드는 GET /v1/models를 통해 이를 찾습니다. 이제 동일한 대화 목록 내에서 로컬 모델과 호스팅된 모델 간에 전환할 수 있습니다.

GUI 외부에서 엔드포인트 테스트

GUI가 모호한 오류를 표시할 때, 문제가 키에 있는지 인터페이스에 있는지 판단하는 가장 빠른 방법은 직접 호출입니다. 다음은 curl을 사용한 스트리밍 요청입니다:

Copycurl -N https://api.ollamansfw.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "stream": true,
    "messages": [{"role": "user", "content": "Write two sentences about a lighthouse keeper."}]
  }'

사용량 정보가 끝나는 data: 줄 시리즈를 볼 수 있어야 합니다. 이것이 작동하면 키와 URL이 정상이며 문제는 프론트 엔드에 있습니다. 문제 해결 페이지에는 누락된 /v1이나 키의 후행 공백과 같은 일반적인 실수가 다뤄집니다.

로컬 모델에 사용하는 클라이언트 설정은 대부분 그대로 적용됩니다. Temperature, top_p, stop 시퀀스, seed 및 페널티는 모델에 전달됩니다.

내 코드에서 호스팅된 엔드포인트 사용

GUI는 하나의 클라이언트입니다. 스크립트와 작은 앱은 또 다른 클라이언트이며 호스팅된 엔드포인트는 표준 OpenAI SDK와 함께 작동합니다. 함수 호출 및 JSON 모드가 지원되므로 GUI나 에이전트가 이를 사용하는 경우 중요합니다.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.ollamansfw.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply with a JSON object with keys title and summary."},
        {"role": "user", "content": "A short story about a lighthouse keeper."},
    ],
)
print(resp.choices[0].message.content)

Node.js에서의 패턴은 동일합니다:

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.ollamansfw.com/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "Name three sailing knots." }],
});
for await (const part of stream) {
  process.stdout.write(part.choices[0]?.delta?.content ?? "");
}

빠른 시작 가이드에는 tool_choice를 사용한 tool calls 예제 등 더 많은 예제가 포함되어 있습니다.

일반적인 문제 및 해결 방법

GUI 설정의 대부분 실패는 짧은 원인 목록에서 비롯됩니다.

• 로컬 연결에 대한 빈 모델 목록. 프론트 엔드가 Ollama에 도달할 수 없습니다. 주소를 확인하고 컨테이너화된 GUI는 호스트를 localhost로 보지 못한다는 점을 기억하세요.
• 호스팅된 엔드포인트에서 401 오류. 키가 누락되었거나 잘못되었습니다. 공백 없이 다시 붙여넣고 GUI가 베어러 토큰으로 전송하는지 확인하세요.
• 모든 요청에 404 오류. Base URL에 /v1이 없거나 두 번 포함되어 있을 수 있습니다.
• 응답이 멈추거나 UI가 응답 없음 상태가 됩니다. 일부 프론트엔드는 프록시를 통해 스트리밍 출력을 버퍼링합니다. 위의 직접 curl 테스트를 시도하고 스트리밍이 되는 경우, GUI 앞의 프록시 설정을 확인하세요.
• 느린 로컬 응답. 모델이 VRAM에 너무 커서 시스템 메모리로 스파일링됩니다. 더 작은 양자화를 선택하거나 해당 채팅을 호스팅된 연결로 전환하세요.

성인용 소설 및 동반자 앱의 규칙은 하나입니다: 호스팅 모델은 합법적인 성인 사용에 대해 거부 없이 응답하지만, 미성년자가 포함된 성적 콘텐츠는 절대 허용되지 않으며 서비스는 이를 엄격히 적용합니다.

GUI에서 알아야 할 제한 사항 및 비용

프론트엔드는 동시에 여러 요청을 보낼 수 있습니다. 예를 들어 메인 응답이 스트리밍되는 동안 백그라운드에서 채팅 제목을 생성할 때와 같습니다. 전체 키는 8개의 동시 요청과 분당 300개의 요청을 허용합니다. 체험 키는 2개의 동시 요청과 분당 60개의 요청을 허용합니다. 스트리밍 요청은 스트림이 끝날 때까지 슬롯을 유지합니다. 제한을 초과하면 HTTP 429 오류가 발생하며, 코드 rate_limited 또는 concurrency가 반환됩니다. 일시적 과부하 시 Retry-After: 5와 함께 429 오류가 발생합니다. GUI에서 백그라운드 제목 생성을 끄는 것은 체험 키에서 간단한 해결책입니다.

비용은 토큰 기준입니다: 입력 1M당 $0.15, 출력 1M당 $0.50. 2,000 토큰의 이력과 500 토큰의 응답을 가진 채팅 턴은 $0.0003 + $0.00025 = $0.00055가 듭니다. 응답 헤더에는 X-Balance-USD이 포함되어 있어 크레딧이 줄어드는 것을 확인할 수 있습니다. 충전 방법은 가격 책정 페이지에서 확인하세요. 이 사이트는 암호화폐 전용입니다: TRC20의 USDT 또는 Base의 USDC, $20부터 $500까지의 전체 금액.

컨텍스트 창은 100,000 토큰이므로 히스토리가 증가할수록 턴당 비용이 더 많이 듭니다. 모든 히스토리가 매번 전송되기 때문입니다. 대부분의 GUI에는 오래된 메시지를 줄이거나 요약하는 설정이 있습니다.

더 많은 가이드

• Ollama 소프트웨어 대안: 호스팅된 무검열 API
• Ollamansfw API 가격 정책: 토큰 비용 설명
• Uncensored LLM API 가이드