Open WebUI Ollama 설정 끝장 정리: 한국어 튜닝 + JWT/API 키 + 모델 연결

Django Open WebUI Ollama

앞선 Part 2까지는

  • 맥북에 Ollama 설치
  • Qwen·Llama3·EXAONE 같은 모델 다운로드
  • Docker로 Open WebUI Ollama 컨테이너 실행
  • http://localhost:3000 접속까지 완료

여기까지가 “기본 설치 단계”였다면,
이번 3부는 한 단계 업그레이드해서

  1. 모델 연결이 제대로 되었는지 확인
  2. 한국어에 맞게 시스템 프롬프트 튜닝
  3. 장고·파이썬에서 쓸 수 있도록 JWT/API 키 구조 이해
  4. Open WebUI Ollama 환경을 보안·API 관점에서 정리

까지 한 번에 정리해보는 파트입니다.

1. 모델 연결 상태 다시 점검하기

설치는 했지만, Open WebUI가 Ollama 서버를 제대로 보고 있는지가 중요합니다.

1-1. Ollama 서버 살아 있는지 체크

In the terminal, type

ollama list
  • qwen2.5:7b, llama3:8b, exaone3.5:7.8b 같은 모델이 보이면
    → Β Ollama 엔진 쪽은 OK, Open WebUI Ollama에서만 잘 물려주면 됩니다.

1-2. Ollama URL 설정

브라우저에서 http://localhost:3000 접속 후

  1. 우상단 프로필 아이콘 → 설정(Settings)
  2. 왼쪽 메뉴에서 외부 도구 / Integrations / Connections 비슷한 항목 선택
  3. Ollama 섹션에 다음처럼 설정:
  • Base URL (또는 Server URL): http://host.docker.internal:11434

왜 localhost가 아니라 host.docker.internal 인지, 다시 한 번 정리해볼게요.

  • Open WebUI Ollama는 Docker 컨테이너 안에서 실행 중
  • 컨테이너 입장에서 localhost는 “컨테이너 자신”
  • Ollama는 맥 호스트에서 localhost:11434 로 떠 있으니,
    컨테이너에서는 그 호스트를 host.docker.internal 이름으로 부르게 됩니다.

설정 후 저장하고,
좌측 상단 모델 선택 드롭다운을 열어보면

  • qwen2.5:7b
  • llama3:8b
  • exaone3.5:7.8b

처럼 Ollama에서 내려받은 모델들이 전부 보이면

“Open WebUI ↔ Ollama”
연결이 정상이라는 뜻입니다.

2. 한국어 최적화를 위한 시스템 프롬프트 세팅

같은 모델이라도 프롬프트를 어떻게 주느냐에 따라 품질이 확 달라집니다.

2-1. 모델별 시스템 프롬프트 설정 위치

  1. Open WebUI 화면 우상단에서 모델 이름을 클릭
  2. Edit or Settings 비슷한 버튼 선택
  3. System Prompt or 시스템 메시지 영역을 찾습니다.

여기 내용을 손보면,
Open WebUI 가 해당 모델을 호출할 때마다
항상 먼저 넣어주는 “기본 지시문” 역할을 합니다.

2-2. 추천 한국어 시스템 프롬프트 예시

아래의 지시문은 어떤 모델이든 공통으로 쓸 수 있는 템플릿입니다.
모델별로 살짝씩 바꿔주면 좋아요.

너는 한국어 전용 인공지능 어시스턴트야.
모든 답변은 반드시 한국어로만 작성하고, 존댓말을 사용해줘.
반드시 다음 원칙을 지켜줘.

1. 설명은 단계별로, 초보자도 이해할 수 있게 차근차근 써줘.
2. 코드 예시를 줄 때는 주석을 충분히 달아줘.
3. 중국어(한자)와 영어 문장은 꼭 필요할 때만 짧게 사용해줘.
4. 표나 리스트로 정리할 수 있는 내용은 되도록 표나 목록으로 정리해줘.
5. 질문자가 "장고"나 "안전문화" 같은 전문 용어를 쓰면,
   그 분야에 맞춰 조금 더 디테일하게 설명해줘.

지금부터 너는 Open WebUI Ollama 환경에서 실행되는
로컬 LLM이야. 서버 밖으로는 어떤 데이터도 나가지 않는다고 가정하고,
민감한 데이터도 책임감 있게 다룬다는 관점에서 답변해줘.
  • 이 템플릿을 qwen2.5:7b, llama3:8b, exaone3.5:7.8b 각각에 맞게 살짝 튜닝하면
    한국어 중심 로컬 LLM 환경이 만들어집니다.

3. JWT 토큰과 API 키 – 인증 구조 이해하기

Open WebUI Settings

이제부터는 장고(Django) 연동을 위한 준비 단계.
오픈 웹유아이 올라마에는 다음 두 가지 개념이 나옵니다:

  1. JWT 토큰
  2. API 키 (Secret Key)

3-1. 계정 화면에서 보는 JWT 토큰

설정 → 계정(Account) 탭으로 들어가면,
하단 근처에 이런 식으로 보일 거예요:

  • JWT 토큰
  • 오른쪽에 ●●●●●●●●●● 가려진 값 + 눈 아이콘(보기) + 복사 버튼

이 JWT 토큰이 사실상 “이미 발급된 API 토큰 역할”을 합니다.
즉, API를 쓸 때:

Authorization: Bearer <여기에 JWT 토큰 값>

이렇게 넣어주면 인증이 통과됩니다.

❗ 참고: 일부 버전에서는 + 새로운 비밀 키 생성 버튼이 동작 안 하는 버그가 보고되어 있습니다.
이런 경우에도 JWT 토큰 자체를 API 키처럼 써도 문제 없습니다.

3-2. ENABLE_API_KEY_AUTH=true 환경변수

2부에서 Docker를 띄울 때 이렇게 했었죠.

docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -e ENABLE_API_KEY_AUTH=true \
  -e WEBUI_URL=http://localhost:3000 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

where ENABLE_API_KEY_AUTH=true 를 줬기 때문에:

  • Open WebUI Ollama가
    “외부에서 오는 API 요청은 JWT/API 키로 인증하겠다”
    모드로 켜진 상태입니다.

이렇게 해두면 나중에:

  • Django 백엔드에서 Open WebUI 의 /api/chat/completions 엔드포인트를 호출할 때
  • JWT 토큰을 Bearer로 넣어서 안전하게 통신You can.
api key - jwt token

4. Open WebUI Ollama API 엔드포인트 구조 미리 맛보기

다음 4부에서 본격적으로 코드를 짤 거지만,
Open WebUI Ollama의 API가 어떻게 생겼는지, 살짝 미리 맛만 볼게요.

Open WebUI Ollama는 기본적으로 OpenAI ChatCompletion 호환 API를 제공합니다:

  • 엔드포인트(기본값 예시)
POST http://localhost:3000/api/chat/completions
  • 헤더
Authorization: Bearer <JWT 또는 API 키>
Content-Type: application/json
  • 바디 예시 (Open WebUI Ollama + Qwen2.5 기준)
{
  "model": "qwen2.5:7b",
  "messages": [
    { "role": "system", "content": "너는 한국어로만 답변하는 AI." },
    { "role": "user", "content": "Open WebUI Ollama 조합이 뭐야? 쉽게 설명해줘." }
  ]
}
  • 응답 예시 구조 (OpenAI 스타일)
{
  "id": "chatcmpl-xxxx",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Open WebUI Ollama는 ..."
      },
      "finish_reason": "stop"
    }
  ]
}

이 구조만 머릿속에 들어오면,

“아, Ollama 기반의 Open WebUI 는 그냥 내 맥북 안에 있는 OpenAI 호환 서버구나”

라고 이해하시면 됩니다.
다음 4부에서는 이걸 Python 코드 + Postman으로 직접 호출해볼 거예요.

5. 보안 관점에서 보는 Ollama 기반 Open WebUI – 무엇을 조심해야 할까?

Ollama 기반의 Open WebUI 는 “로컬에서만 돌기 때문에 안전하다”는 큰 장점이 있지만,
그래도 몇 가지는 꼭 체크해두면 좋습니다.

  1. 포트를 외부에 그대로 노출하지 않기
    • 지금은 localhost:3000 이라서 맥북 안에서만 접근 가능
    • 굳이 포트를 공유기에서 포워딩하거나, 회사 네트워크에서 열어두지 않는 게 좋습니다.
  2. JWT/API 키를 GitHub 등에 올리지 않기
    • .env 파일에 OPENWEBUI_API_KEY 같은 이름으로 넣고
      .gitignoreIn .env를 반드시 포함
  3. 여러 사람이 같은 Open WebUI Ollama 인스턴스를 쓴다면?
    • Admin Panel에서 계정별 권한(Role)을 나누고
    • 관리자가 아닌 계정에는 민감한 작업(지식베이스, 설정 변경 등)을 제한

특히, 나중에 조직문화 진단 시스템·사내 리포트와 연결할 때는
Ollama 기반 Open WebUI 가 곧 사내 LLM 허브 역할을 하게 되므로,
초기 설정 단계에서 보안 감각을 한 번 짚고 가는 게 좋습니다.

6. 3부 정리

지금까지 3부에서 한 일을 정리하면:

  1. Open WebUI ↔ Ollama 서버 연결 확인
  2. 한국어에 맞는 시스템 프롬프트를 모델별로 설정
  3. 계정 화면에서 JWT 토큰을 확인and,
    이것이 Open WebUI Ollama의 API 인증 토큰 역할을 한다는 걸 이해
  4. ENABLE_API_KEY_AUTH=true 로 컨테이너를 띄워
    Ollama 기반 Open WebUI API 인증 구조를 활성화
  5. /api/chat/completions 엔드포인트가
    OpenAI ChatCompletion과 거의 같다는 개념까지 맛보기

이제 4부에서는

🔜 “Python에서 Open WebUI Ollama API 직접 호출해 보기 – 면담 요약/번역 실습”

으로 들어갈 겁니다.

Similar Posts