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

Django Open WebUI Ollama

앞선 第二部分까지는

  • 맥북에 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 서버 살아 있는지 체크

터미널에서

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 或 Settings 비슷한 버튼 선택
  3. System Prompt 或 시스템 메시지 영역을 찾습니다.

여기 내용을 손보면,
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

其中 ENABLE_API_KEY_AUTH=true 를 줬기 때문에:

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

이렇게 해두면 나중에:

  • Django 백엔드에서 Open WebUI 의 /api/chat/completions 엔드포인트를 호출할 때
  • JWT 토큰을 Bearer로 넣어서 안전하게 통신你可以
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 같은 이름으로 넣고
      .gitignore在 .env를 반드시 포함
  3. 여러 사람이 같은 Open WebUI Ollama 인스턴스를 쓴다면?
    • Admin Panel에서 계정별 권한(Role)을 나누고
    • 관리자가 아닌 계정에는 민감한 작업(지식베이스, 설정 변경 등)을 제한

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

6. 3부 정리

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

  1. Open WebUI ↔ Ollama 서버 연결 확인
  2. 한국어에 맞는 시스템 프롬프트를 모델별로 설정
  3. 계정 화면에서 JWT 토큰을 확인和
    이것이 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 직접 호출해 보기 – 면담 요약/번역 실습”

으로 들어갈 겁니다.

类似文章