Ollama 도구 연동

Continue.dev + Ollama (VS Code)

Continue는 VS Code/JetBrains에서 GitHub Copilot처럼 동작하는 오픈소스 AI 코딩 어시스턴트입니다. Ollama와 완벽하게 통합되어 무료로 무제한 사용할 수 있습니다.

동작 원리

설치

# 1. VS Code 확장 마켓플레이스에서 설치
1. VS Code 열기
2. Extensions (Ctrl+Shift+X)
3. "Continue" 검색
4. Install 클릭

# 또는 CLI로 설치
code --install-extension continue.continue

설정

Continue 사이드바에서 설정 파일을 열거나 ~/.continue/config.json 직접 편집:

// ~/.continue/config.json
{
  "models": [
    {
      "title": "CodeLlama 13B",
      "provider": "ollama",
      "model": "codellama:13b",
      "apiBase": "http://localhost:11434"
    },
    {
      "title": "Llama 3.2",
      "provider": "ollama",
      "model": "llama3.2"
    }
  ],
  "tabAutocompleteModel": {
    "title": "Starcoder2 3B",
    "provider": "ollama",
    "model": "starcoder2:3b"
  },
  "embeddingsProvider": {
    "provider": "ollama",
    "model": "nomic-embed-text"
  }
}

사용법

1. 인라인 코드 생성 (Ctrl+I)

# 코드 편집기에서 Ctrl+I 누르고 요청
"피보나치 수열 생성 함수를 재귀로 작성해줘"

# Continue가 자동으로 코드 생성 및 삽입
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

2. 코드 설명 (Ctrl+L)

# 코드 블록 선택 후 Ctrl+L
"이 코드가 무엇을 하는지 설명해줘"

# 사이드바에 설명 표시

3. 리팩토링

# 코드 선택 후 Ctrl+I
"이 함수를 타입 힌트를 추가하고 docstring 작성해줘"

def fibonacci(n: int) -> int:
    """
    Calculate the nth Fibonacci number recursively.

    Args:
        n: The position in the Fibonacci sequence (0-indexed)

    Returns:
        The nth Fibonacci number
    """
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

4. 탭 자동완성 (실험적)

# 코드 작성 중 탭 눌러 자동완성
def sort_list(items):
    # Tab 누르면 자동으로 제안
    return sorted(items)  # ← Continue가 생성

팁 & 트릭

# 모델 미리 다운로드
ollama pull codellama:13b
ollama pull llama3.2
ollama pull starcoder2:3b
ollama pull nomic-embed-text

키보드 단축키

@컨텍스트 프로바이더

Continue는 @ 기호로 다양한 컨텍스트를 LLM에 전달할 수 있습니다.

# 채팅에서 @로 컨텍스트 추가
@파일명          # 특정 파일을 컨텍스트로
@폴더명          # 폴더 전체를 컨텍스트로
@url             # 웹 페이지 내용
@codebase        # 전체 코드베이스 검색
@terminal        # 터미널 출력
@docs            # 사전 인덱싱된 문서
@git diff        # Git 변경사항
@problems        # VS Code 문제 탭 내용

# 예시
"@src/auth.py 이 파일의 보안 취약점을 분석해줘"
"@codebase 인증 관련 코드를 모두 찾아줘"
"@terminal 방금 에러 메시지를 분석해줘"

멀티 모델 설정

// ~/.continue/config.json - 작업별 모델 분리
{
  "models": [
    {
      "title": "코딩 전용 (Qwen2.5-Coder)",
      "provider": "ollama",
      "model": "qwen2.5-coder:14b"
    },
    {
      "title": "일반 대화 (Llama 3.2)",
      "provider": "ollama",
      "model": "llama3.2"
    },
    {
      "title": "한국어 특화 (EEVE)",
      "provider": "ollama",
      "model": "eeve-korean:10.8b"
    }
  ],
  "tabAutocompleteModel": {
    "title": "자동완성 (빠른 모델)",
    "provider": "ollama",
    "model": "starcoder2:3b"
  }
}
// 채팅 사이드바에서 드롭다운으로 모델 전환 가능

워크스페이스 설정

# 프로젝트별 Continue 설정
# .continue/config.json (프로젝트 루트)
# 전역 설정보다 우선 적용됨

# 워크스페이스 설정 예시
{
  "models": [
    {
      "title": "프로젝트 전용 모델",
      "provider": "ollama",
      "model": "codellama:13b",
      "systemMessage": "당신은 FastAPI + PostgreSQL 프로젝트의 전문가입니다. 이 프로젝트는 Python 3.11, FastAPI, SQLAlchemy를 사용합니다."
    }
  ],
  "contextProviders": [
    {
      "name": "docs",
      "params": {
        "sites": [
          {
            "title": "FastAPI 문서",
            "startUrl": "https://fastapi.tiangolo.com/"
          }
        ]
      }
    }
  ]
}

Aider + Ollama (CLI)

Aider는 터미널에서 동작하는 AI 페어 프로그래밍 도구로, Git과 완벽하게 통합됩니다. 코드 변경사항을 자동으로 커밋하고, 여러 파일을 동시에 수정할 수 있습니다.

Aider의 가장 큰 장점은 Git 네이티브 통합입니다. AI가 코드를 수정하면 자동으로 의미 있는 커밋 메시지와 함께 Git 커밋이 생성되므로, 변경 이력을 추적하고 필요 시 쉽게 되돌릴 수 있습니다.

설치

# Python 3.8+ 필요
pip install aider-chat

# 또는 pipx로 격리 설치
pipx install aider-chat

# 설치 확인
aider --version
# aider version 0.x.x

Ollama 연동 설정

# 기본 사용 (모델 지정)
aider --model ollama/codellama:13b

# 환경 변수로 기본 모델 설정
export AIDER_MODEL=ollama/llama3.2
export OLLAMA_API_BASE=http://localhost:11434

# ~/.aider.conf.yml 생성 (영구 설정)
cat > ~/.aider.conf.yml <<EOF
model: ollama/codellama:13b
edit-format: whole
auto-commits: true
dirty-commits: false
EOF

사용법

1. 프로젝트에서 Aider 시작

# Git 저장소 루트에서 실행
cd ~/my-project
aider --model ollama/codellama:13b

# 특정 파일 지정
aider src/main.py tests/test_main.py --model ollama/llama3.2

# 모든 Python 파일
aider src/*.py

2. 코드 생성

# Aider 프롬프트
> main.py에 FastAPI 앱을 생성하고, /health 엔드포인트를 추가해줘

# Aider가 자동으로 코드 생성 및 파일 작성
# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/health")
async def health_check():
    return {"status": "healthy"}

# Aider가 자동으로 Git 커밋
Applied edit to main.py
Commit 3a8f7e1 Add FastAPI health endpoint

3. 버그 수정

> user.py의 validate_email 함수에 버그가 있어. 잘못된 이메일을 허용하고 있어.

# Aider가 코드 분석 후 수정
I found the issue. The regex pattern is missing the @ symbol check.

# 수정된 코드
import re

def validate_email(email: str) -> bool:
    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
    return bool(re.match(pattern, email))

Applied edit to user.py
Commit b4c2d9f Fix email validation regex

4. 리팩토링

> database.py의 모든 함수에 타입 힌트와 docstring을 추가하고, 에러 핸들링을 개선해줘

# 여러 함수 동시 리팩토링
Applied edit to database.py
- Added type hints to 5 functions
- Added docstrings following Google style
- Added proper exception handling
Commit 7e1a5c3 Refactor database.py with type hints and docs

Aider 명령어

고급 사용

전체 코드베이스 검색

# 저장소 맵 활성화 (--map-tokens 옵션)
aider --model ollama/llama3.2 --map-tokens 2048

> 인증 관련 모든 함수를 찾아서 JWT 토큰 검증 로직을 추가해줘

# Aider가 전체 코드베이스 검색 후 관련 파일 자동 수정

테스트 자동 생성

aider src/calculator.py

> calculator.py의 모든 함수에 대한 pytest 테스트를 tests/test_calculator.py에 생성해줘

Applied edit to tests/test_calculator.py
Created 8 test functions
Commit a3d8e4f Add comprehensive tests for calculator

파일 감시 모드 (--watch-files)

# 파일 변경 감지 모드로 실행
aider --model ollama/codellama:13b --watch-files

# 동작 방식:
1. 에디터에서 코드 수정
2. 주석으로 AI 요청 추가:
# AI: 이 함수에 에러 핸들링 추가해줘
3. 파일 저장 → Aider가 자동 감지
4. AI가 주석을 읽고 코드 수정
5. 자동 커밋

.aiderignore 설정

# .aiderignore (프로젝트 루트에 생성)
# .gitignore와 동일한 문법

# 빌드 산출물 무시
dist/
build/
*.min.js

# 자동 생성 파일 무시
migrations/
*.lock

# 민감한 파일 무시
.env
*.pem
secrets/

# 대용량 파일 무시 (토큰 절약)
*.csv
*.json
data/

편집 포맷 비교

# 편집 포맷 지정
aider --model ollama/codellama:13b --edit-format whole
aider --model ollama/codellama:13b --edit-format diff
aider --model ollama/codellama:13b --edit-format udiff

Open WebUI (ChatGPT 스타일 인터페이스)

Open WebUI는 Ollama를 위한 완전한 기능을 갖춘 ChatGPT 스타일 웹 인터페이스입니다. 브라우저에서 대화, 문서 업로드, RAG, 팀 협업, 멀티모달, 음성 인식 등 모든 기능을 제공합니다. 개인 사용부터 기업 배포까지 다양한 시나리오를 지원합니다.

설치 방법

방법 1: Docker (권장 - 가장 쉬움)

# CPU 전용 (MacBook, 일반 PC)
docker run -d -p 3000:8080 \
  -v open-webui:/app/backend/data \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

# GPU 지원 (NVIDIA RTX, A100 등)
docker run -d -p 3000:8080 \
  --gpus all \
  -v open-webui:/app/backend/data \
  -v ollama:/root/.ollama \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:cuda

# Apple Silicon (M1/M2/M3)
docker run -d -p 3000:8080 \
  --platform linux/arm64 \
  -v open-webui:/app/backend/data \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

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

방법 2: Docker Compose (프로덕션 추천)

# docker-compose.yml
version: '3.8'

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama:/root/.ollama
    restart: always
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
      - WEBUI_SECRET_KEY="your-secret-key-change-this"
      - WEBUI_AUTH=true
      - ENABLE_SIGNUP=true
      - DEFAULT_MODELS=llama3.2,codellama:13b
      - ENABLE_RAG_WEB_SEARCH=true
      - RAG_EMBEDDING_MODEL=nomic-embed-text
    depends_on:
      - ollama
    restart: always

volumes:
  ollama:
  open-webui:

# 실행
docker-compose up -d

# 로그 확인
docker-compose logs -f open-webui

# 중지
docker-compose down

# 재시작
docker-compose restart

방법 3: Python으로 설치 (개발자용)

# Python 3.11+ 필요
git clone https://github.com/open-webui/open-webui.git
cd open-webui

# 가상 환경 생성
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 의존성 설치
pip install -r requirements.txt

# 환경 변수 설정
export OLLAMA_BASE_URL=http://localhost:11434
export WEBUI_SECRET_KEY="your-secret-key"

# 실행
bash start.sh

# 또는 개발 모드
npm install
npm run dev  # http://localhost:5173

초기 설정

1. 첫 번째 계정 생성 (관리자)

# 브라우저에서 http://localhost:3000 접속
1. "Sign up" 클릭
2. 이름, 이메일, 비밀번호 입력
3. 첫 번째 사용자는 자동으로 관리자 권한 부여

# 이후 사용자는 일반 권한으로 생성됨

2. 기본 모델 다운로드

# 웹 UI에서 직접 다운로드
Settings → Models → Pull a model from Ollama.com

# 추천 시작 모델
llama3.2           # 범용 대화 (3B 또는 7B)
codellama:13b      # 코딩 전문
mistral            # 빠르고 정확
nomic-embed-text   # RAG용 임베딩

# 또는 터미널에서 미리 다운로드
ollama pull llama3.2
ollama pull codellama:13b
ollama pull nomic-embed-text

3. 기본 설정 최적화

# Settings → General
✓ Default Model: llama3.2
✓ Request Mode: Chat (대화형)
✓ System Prompt: (비워두거나 커스텀)

# Settings → Interface
✓ Theme: Dark (or Auto)
✓ Language: 한국어
✓ Chat Direction: LTR

# Settings → Audio
✓ STT Engine: Web API (또는 Whisper)
✓ TTS Engine: Web API

핵심 기능 상세

1. 대화 관리

# 새 대화 시작
1. 상단 "+ New Chat" 버튼 클릭
2. 또는 Ctrl + Shift + O (단축키)

# 대화 검색
왼쪽 사이드바 상단 검색창에 키워드 입력
예: "python 코드" 입력 → 관련 대화 필터링

# 대화 폴더 구조화
1. 대화 우클릭 → "Move to Folder"
2. 폴더 생성: "프로젝트", "학습", "디버깅" 등
3. 드래그 앤 드롭으로 이동

# 대화 내보내기
1. 대화 설정 (⋮) 클릭
2. Export → Markdown or JSON 선택
3. 파일 저장 → Notion, Obsidian 등에 활용

# 대화 공유 (팀 협업)
1. 대화 설정 → Share
2. 링크 생성 → 팀원에게 전달
3. 권한 설정: View Only / Can Edit

2. 문서 업로드 & RAG (검색 증강 생성)

RAG는 문서를 업로드하고 LLM이 그 내용을 기반으로 답변하게 하는 기술입니다.

# 단일 문서 업로드 (빠른 질문)
1. 채팅 입력창 왼쪽 📎 아이콘 클릭
2. 파일 선택 (PDF, DOCX, TXT, MD, 코드 등)
3. 자동으로 임베딩 생성
4. 질문: "이 문서의 주요 결론은?"

# 지원 파일 형식
- 문서: PDF, DOCX, PPTX, TXT, MD
- 코드: .py, .js, .java, .cpp, .go, .rs
- 데이터: CSV, JSON, XML
- 기타: HTML, RTF

# 영구 문서 컬렉션 (지식 베이스)
1. Settings → Documents → Upload
2. 여러 파일 동시 업로드 (드래그 앤 드롭)
3. 태그 추가: #manual, #api, #guide
4. 모든 채팅에서 이 문서 검색 가능

# 채팅에서 문서 활성화
1. 채팅 시작
2. 메시지 입력창 위 "# Add Document" 클릭
3. 활성화할 문서 선택 (여러 개 가능)
4. 선택된 문서에서만 정보 검색

RAG 고급 설정

# Settings → Documents → RAG
Embedding Model: nomic-embed-text     # 임베딩 모델
Chunk Size: 1000                      # 텍스트 분할 크기
Chunk Overlap: 200                    # 청크 오버랩
Top K: 5                               # 검색할 문서 수
Relevance Threshold: 0.5              # 관련성 임계값

# 임베딩 모델 추천
영어 문서: nomic-embed-text (768차원, 빠름)
다국어 (한국어 포함): mxbai-embed-large
코드: nomic-embed-text

실전 RAG 활용 예제

# 시나리오 1: 회사 문서 Q&A 봇
1. 모든 사내 매뉴얼 PDF 업로드 (100개+)
2. 태그: #hr, #it, #finance
3. 질문: "휴가 신청 절차는?"
→ HR 매뉴얼에서 관련 정보 추출 후 답변

# 시나리오 2: 코드베이스 분석
1. 프로젝트의 모든 .py 파일 업로드
2. 질문: "인증 로직이 어떤 파일에 있어?"
→ auth.py, middleware.py 등에서 관련 코드 찾아 설명

# 시나리오 3: 연구 논문 요약
1. 논문 PDF 10개 업로드
2. 질문: "Transformer 아키텍처의 한계점은?"
→ 10개 논문에서 관련 내용 통합 요약

3. 멀티모달 & 비전

# 이미지 분석 (llava, bakllava 모델 필요)
ollama pull llava:13b

# 사용
1. 채팅에서 모델을 llava:13b로 변경
2. 이미지 업로드 (PNG, JPG, WEBP)
3. 질문: "이 이미지에서 무엇이 보이나요?"
4. 질문: "이 다이어그램을 설명해줘"
5. 질문: "이 코드 스크린샷을 분석해줘"

# 실전 활용
- UI 목업 → "이 디자인을 HTML/CSS로 구현해줘"
- 에러 스크린샷 → "이 에러 원인과 해결 방법은?"
- 다이어그램 → "이 아키텍처의 문제점은?"
- 손글씨 수학 → "이 수식을 풀어줘"

4. 음성 입력 & 출력

# STT (Speech-to-Text) 설정
Settings → Audio → STT
Engine: Web API (브라우저 내장) 또는 Whisper API

# Whisper (Ollama) 사용
1. Whisper 모델 다운로드
ollama pull whisper

2. Open WebUI 설정
Settings → Audio → STT Engine: Whisper (Ollama)
Settings → Audio → STT Model: whisper

3. 사용: 채팅 입력창 🎤 아이콘 클릭 → 말하기

# TTS (Text-to-Speech)
Settings → Audio → TTS
Engine: Web API (무료) 또는 ElevenLabs (고품질)

# 메시지 음성 재생
1. AI 응답 위에 마우스 오버
2. 🔊 아이콘 클릭
3. 자동으로 음성 재생

5. 프롬프트 템플릿 & 프리셋

# 프롬프트 템플릿 생성
Settings → Prompts → + New Prompt

# 템플릿 1: 코드 리뷰
Name: Code Review
Command: /review
Prompt:
"""
당신은 10년 경력의 시니어 개발자입니다.
다음 코드를 상세히 리뷰하고 개선점을 제안해주세요:

**체크리스트:**
1. 버그 및 오류 가능성
2. 성능 최적화 기회
3. 코드 가독성 및 유지보수성
4. 보안 취약점 (SQL injection, XSS 등)
5. 베스트 프랙티스 준수 여부

**코드:**
{{CODE}}

**리뷰 형식:**
- 🔴 Critical: 즉시 수정 필요
- 🟡 Important: 개선 권장
- 🟢 Nice to have: 선택적 개선
"""

# 사용
채팅에서 "/review" 입력 후 코드 붙여넣기

# 템플릿 2: 문서 요약
Name: Summarize Document
Command: /summary
Prompt:
"""
다음 문서를 3단계로 요약해주세요:

1. **한 줄 요약** (핵심 메시지)
2. **주요 포인트** (3-5개 불릿 포인트)
3. **상세 요약** (1-2 문단)

문서:
{{DOCUMENT}}
"""

# 템플릿 3: 번역
Name: Translate
Command: /translate
Prompt:
"""
다음 텍스트를 {{TARGET_LANG}}로 자연스럽게 번역해주세요.
전문 용어는 정확하게 번역하고, 맥락을 유지하세요.

원문:
{{TEXT}}
"""

# 템플릿 4: 학습 도우미
Name: Explain Like I'm 5
Command: /eli5
Prompt:
"""
다음 개념을 5살 아이도 이해할 수 있도록 쉽게 설명해주세요:
- 비유와 예시 사용
- 전문 용어 최소화
- 단계별 설명

개념: {{CONCEPT}}
"""

관리자 기능

사용자 관리

# Admin Panel 접근
Settings → Admin Panel (관리자만 보임)

# 사용자 추가
Admin Panel → Users → + Add User
Name: 홍길동
Email: hong@company.com
Password: (임시 비밀번호)
Role: User (또는 Admin)

# 사용자 권한 관리
User Actions:
- Edit: 정보 수정
- Delete: 사용자 삭제
- Ban: 일시 정지
- Set as Admin: 관리자 승격

# 대량 사용자 등록 (CSV)
1. CSV 파일 준비
name,email,role
김철수,kim@company.com,user
이영희,lee@company.com,admin

2. Admin Panel → Import Users
3. CSV 업로드 → 자동 생성

모델 관리

# 모델 다운로드
Settings → Models → Pull a model
llama3.2:7b
codellama:13b
mistral:latest
qwen2.5-coder:14b

# 모델 삭제
모델 우클릭 → Delete

# 모델 별칭 (사용자 친화적 이름)
Settings → Models → Model Aliases
llama3.2:7b → "일반 대화"
codellama:13b → "코딩 전문가"

# 모델 접근 제어
Admin Panel → Models → Permissions
특정 사용자/그룹만 특정 모델 사용 허용
예: GPT-4 모델은 Senior 팀만 접근

시스템 설정

# 회원가입 제어
Admin Panel → Settings → General
Enable Signup: false     # 공개 가입 차단
Default Role: user        # 기본 권한

# API 키 관리
Admin Panel → Settings → API Keys
외부 서비스 연동용 API 키 생성/관리

# 감사 로그
Admin Panel → Audit Logs
모든 사용자 활동 로그 확인
- 로그인/로그아웃
- 모델 사용
- 문서 업로드/삭제
- 설정 변경

플러그인 & 확장

1. Web Search (실시간 검색)

# SearxNG 연동
Settings → Web Search
Enable: true
Engine: SearxNG
URL: https://searx.example.com

# 사용
채팅에서 "#" 입력 후 검색
예: "#오늘 날씨는?" → 실시간 검색 후 답변

2. Python Code Interpreter

# 설정
Settings → Functions → Python Interpreter
Enable: true

# 사용
채팅: "피보나치 수열 20개 계산해줘"
→ Python 코드 자동 생성 및 실행 → 결과 표시

# 지원 라이브러리
numpy, pandas, matplotlib, requests, beautifulsoup4

3. Wolfram Alpha (수학/과학)

# API 키 발급
1. https://products.wolframalpha.com/api/ 가입
2. App ID 발급

# 설정
Settings → Functions → Wolfram Alpha
App ID: YOUR_APP_ID

# 사용
"∫ x² dx 계산해줘"
"태양과 지구의 거리는?"

API 통합

# Open WebUI API 키 생성
Settings → Account → API Keys → + New Key
Name: MyApp
Expires: Never (또는 30 days)

# Python에서 API 사용
import requests

url = "http://localhost:3000/api/chat"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "model": "llama3.2",
    "messages": [
        {"role": "user", "content": "Hello!"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

# JavaScript에서 사용
const response = await fetch('http://localhost:3000/api/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'llama3.2',
    messages: [{role: 'user', content: 'Hello!'}]
  })
});

const data = await response.json();
console.log(data);

프로덕션 배포

HTTPS 설정 (Nginx + Let's Encrypt)

# Nginx 설정
server {
    listen 80;
    server_name ai.company.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name ai.company.com;

    ssl_certificate /etc/letsencrypt/live/ai.company.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ai.company.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

백업 및 복원

# 데이터 백업
docker run --rm \
  -v open-webui:/source \
  -v $(pwd):/backup \
  alpine tar czf /backup/open-webui-backup-$(date +%Y%m%d).tar.gz -C /source .

# 복원
docker run --rm \
  -v open-webui:/target \
  -v $(pwd):/backup \
  alpine sh -c "cd /target && tar xzf /backup/open-webui-backup-20250212.tar.gz"

# 자동 백업 (cron)
0 2 * * * /path/to/backup-script.sh

환경 변수 전체 목록

# docker-compose.yml 또는 .env 파일
OLLAMA_BASE_URL=http://ollama:11434
WEBUI_SECRET_KEY=random-secret-key-min-32-chars
WEBUI_AUTH=true
ENABLE_SIGNUP=false
DEFAULT_MODELS=llama3.2,codellama:13b
DEFAULT_USER_ROLE=user
ENABLE_RAG_WEB_SEARCH=true
RAG_EMBEDDING_MODEL=nomic-embed-text
CHUNK_SIZE=1000
CHUNK_OVERLAP=200
RAG_TOP_K=5
ENABLE_IMAGE_GENERATION=false
IMAGE_GENERATION_API_URL=http://stable-diffusion:7860
WHISPER_MODEL=whisper
TTS_ENGINE=web_api

문제 해결

# 문제 1: Ollama 연결 안됨
증상: "Cannot connect to Ollama"
해결:
1. Ollama가 실행 중인지 확인: curl http://localhost:11434
2. Docker 네트워크: host.docker.internal → localhost 변경
3. OLLAMA_BASE_URL 환경 변수 확인

# 문제 2: 모델이 보이지 않음
해결:
ollama list                    # 모델 확인
ollama pull llama3.2           # 모델 다운로드
docker restart open-webui      # 재시작

# 문제 3: RAG 임베딩 실패
해결:
ollama pull nomic-embed-text   # 임베딩 모델 설치
Settings → Documents → RAG → Embedding Model 설정

# 문제 4: 메모리 부족
해결:
# docker-compose.yml에 리소스 제한 추가
deploy:
  resources:
    limits:
      memory: 4G

# 문제 5: 느린 응답
해결:
1. 더 작은 모델 사용 (7B → 3B)
2. GPU 활성화 (--gpus all)
3. Ollama num_ctx 줄이기 (4096 → 2048)

LangChain + Ollama (Python)

LangChain은 LLM 기반 애플리케이션 개발 프레임워크입니다. Ollama와 통합하여 체인, 에이전트, RAG 파이프라인을 구축할 수 있습니다.

설치

# LangChain 및 Ollama 통합 설치
pip install langchain langchain-community

# 또는 전체 패키지
pip install langchain langchain-community langchain-ollama

기본 사용

1. 간단한 LLM 호출

from langchain_community.llms import Ollama

# Ollama LLM 초기화
llm = Ollama(model="llama3.2")

# 텍스트 생성
response = llm.invoke("파이썬으로 퀵소트 알고리즘을 작성해줘")
print(response)

2. 스트리밍 응답

from langchain_community.llms import Ollama

llm = Ollama(model="llama3.2")

# 스트리밍으로 응답 받기
for chunk in llm.stream("긴 이야기를 들려줘"):
    print(chunk, end="", flush=True)

3. 채팅 모델

from langchain_community.chat_models import ChatOllama
from langchain.schema import HumanMessage, SystemMessage

chat = ChatOllama(model="llama3.2")

messages = [
    SystemMessage(content="당신은 파이썬 전문가입니다."),
    HumanMessage(content="FastAPI로 REST API를 만드는 방법을 알려줘")
]

response = chat.invoke(messages)
print(response.content)

체인 (Chains)

프롬프트 템플릿

from langchain_community.llms import Ollama
from langchain.prompts import PromptTemplate
from langchain.chains import LLMChain

llm = Ollama(model="codellama:13b")

# 프롬프트 템플릿 정의
template = """당신은 {language} 전문가입니다.
다음 작업을 수행하는 코드를 작성해주세요:

작업: {task}

코드:"""

prompt = PromptTemplate(
    input_variables=["language", "task"],
    template=template
)

# 체인 생성
chain = LLMChain(llm=llm, prompt=prompt)

# 실행
result = chain.run(
    language="Python",
    task="CSV 파일을 읽고 Pandas DataFrame으로 변환"
)
print(result)

순차 체인

from langchain.chains import SimpleSequentialChain, LLMChain
from langchain.prompts import PromptTemplate
from langchain_community.llms import Ollama

llm = Ollama(model="llama3.2")

# 체인 1: 아이디어 생성
template1 = "웹 애플리케이션 아이디어를 한 문장으로 제안해줘: {topic}"
prompt1 = PromptTemplate(input_variables=["topic"], template=template1)
chain1 = LLMChain(llm=llm, prompt=prompt1)

# 체인 2: 기술 스택 제안
template2 = "이 아이디어에 적합한 기술 스택을 추천해줘: {idea}"
prompt2 = PromptTemplate(input_variables=["idea"], template=template2)
chain2 = LLMChain(llm=llm, prompt=prompt2)

# 순차 실행
overall_chain = SimpleSequentialChain(chains=[chain1, chain2])
result = overall_chain.run("AI 기반 학습 플랫폼")
print(result)

RAG (Retrieval-Augmented Generation)

from langchain_community.llms import Ollama
from langchain_community.embeddings import OllamaEmbeddings
from langchain_community.vectorstores import Chroma
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain.chains import RetrievalQA
from langchain_community.document_loaders import TextLoader

# 1. 문서 로드
loader = TextLoader("company_docs.txt")
documents = loader.load()

# 2. 텍스트 분할
text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=1000,
    chunk_overlap=200
)
texts = text_splitter.split_documents(documents)

# 3. 임베딩 생성 (Ollama)
embeddings = OllamaEmbeddings(model="nomic-embed-text")

# 4. 벡터 DB 생성
vectorstore = Chroma.from_documents(
    documents=texts,
    embedding=embeddings,
    persist_directory="./chroma_db"
)

# 5. RAG 체인 생성
llm = Ollama(model="llama3.2")
qa_chain = RetrievalQA.from_chain_type(
    llm=llm,
    chain_type="stuff",
    retriever=vectorstore.as_retriever(search_kwargs={"k": 3})
)

# 6. 질문
query = "회사의 휴가 정책은 무엇인가요?"
result = qa_chain.invoke({"query": query})
print(result["result"])

에이전트

from langchain.agents import initialize_agent, Tool
from langchain.agents import AgentType
from langchain_community.llms import Ollama
import requests

# 도구 정의
def search_wikipedia(query: str) -> str:
    url = f"https://en.wikipedia.org/api/rest_v1/page/summary/{query}"
    response = requests.get(url)
    if response.status_code == 200:
        return response.json().get("extract", "No results")
    return "Error"

def calculate(expression: str) -> str:
    try:
        return str(eval(expression))
    except:
        return "Invalid expression"

tools = [
    Tool(
        name="Wikipedia",
        func=search_wikipedia,
        description="위키피디아에서 정보 검색"
    ),
    Tool(
        name="Calculator",
        func=calculate,
        description="수학 계산 수행"
    )
]

# 에이전트 초기화
llm = Ollama(model="llama3.2", temperature=0)
agent = initialize_agent(
    tools,
    llm,
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
    verbose=True
)

# 실행
result = agent.run("파이썬이 언제 만들어졌는지 찾고, 현재 연도에서 빼서 나이를 계산해줘")
print(result)

LlamaIndex + Ollama (RAG)

LlamaIndex는 RAG(검색 증강 생성) 전문 프레임워크입니다. 대용량 문서, 데이터베이스, API와 LLM을 연결하여 지능형 질의응답 시스템을 구축합니다.

설치

# LlamaIndex 및 Ollama 통합
pip install llama-index llama-index-llms-ollama llama-index-embeddings-ollama

기본 RAG 파이프라인

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.ollama import Ollama
from llama_index.embeddings.ollama import OllamaEmbedding

# 1. LLM 및 임베딩 설정
Settings.llm = Ollama(model="llama3.2", request_timeout=120.0)
Settings.embed_model = OllamaEmbedding(model_name="nomic-embed-text")

# 2. 문서 로드 (디렉토리 내 모든 파일)
documents = SimpleDirectoryReader("./docs").load_data()

# 3. 인덱스 생성
index = VectorStoreIndex.from_documents(documents)

# 4. 쿼리 엔진 생성
query_engine = index.as_query_engine()

# 5. 질문
response = query_engine.query("프로젝트의 주요 기능은 무엇인가요?")
print(response)

고급 기능

1. 커스텀 프롬프트

from llama_index.core import PromptTemplate

# 커스텀 QA 프롬프트
qa_template = PromptTemplate(
    """당신은 기술 문서 전문가입니다.

Context information:
---------------------
{context_str}
---------------------

Question: {query_str}

위 컨텍스트를 바탕으로 정확하고 상세하게 답변해주세요.
답변을 찾을 수 없다면 "정보 없음"이라고 답하세요."""
)

query_engine = index.as_query_engine(
    text_qa_template=qa_template
)

response = query_engine.query("API 인증 방법은?")
print(response)

2. 채팅 엔진

# 대화 히스토리를 유지하는 채팅 엔진
chat_engine = index.as_chat_engine()

# 대화
response1 = chat_engine.chat("FastAPI가 뭐야?")
print(response1)

# 이전 대화를 기억
response2 = chat_engine.chat("그럼 Flask와 비교하면?")
print(response2)

3. 다중 문서 소스

from llama_index.core import SimpleDirectoryReader
from llama_index.readers.web import SimpleWebPageReader

# 로컬 파일
local_docs = SimpleDirectoryReader("./docs").load_data()

# 웹 페이지
web_docs = SimpleWebPageReader().load_data([
    "https://docs.python.org/3/tutorial/"
])

# 합쳐서 인덱스 생성
all_docs = local_docs + web_docs
index = VectorStoreIndex.from_documents(all_docs)

4. 지속적 저장

from llama_index.core import StorageContext, load_index_from_storage

# 인덱스 저장
index.storage_context.persist(persist_dir="./storage")

# 나중에 로드
storage_context = StorageContext.from_defaults(persist_dir="./storage")
loaded_index = load_index_from_storage(storage_context)

Cline + Ollama (VS Code 자율 에이전트)

Cline은 VS Code에서 동작하는 자율 AI 코딩 에이전트입니다. Continue.dev가 사용자의 지시에 따라 코드를 생성하는 반면, Cline은 파일 생성/수정, 터미널 명령 실행, 브라우저 조작까지 자율적으로 수행합니다. Ollama와 연동하면 완전 무료로 로컬 AI 에이전트를 사용할 수 있습니다.

설치

# VS Code 확장 마켓플레이스에서 설치
1. VS Code 열기
2. Extensions (Ctrl+Shift+X)
3. "Cline" 검색
4. Install 클릭

# 또는 CLI로 설치
code --install-extension saoudrizwan.claude-dev

Ollama 연동 설정

# Cline 설정 (VS Code 사이드바)
1. Cline 아이콘 클릭 (사이드바)
2. 설정 아이콘 클릭
3. API Provider → "Ollama" 선택
4. Base URL: http://localhost:11434
5. Model: codellama:13b (또는 원하는 모델)

# 추천 모델 조합
기본 모델: qwen2.5-coder:14b     # 코드 생성 품질 우수
대안 모델: codellama:13b          # 안정적, 메모리 효율적
경량 모델: qwen2.5-coder:7b      # GPU 8GB 미만

사용법

1. 자율 코딩 작업

# Cline 채팅에서 자연어로 요청
"FastAPI로 TODO 앱을 만들어줘. SQLite 데이터베이스 사용하고,
CRUD 엔드포인트와 Pydantic 모델을 포함해줘."

# Cline이 자율적으로 수행하는 작업:
1. main.py 생성 - FastAPI 앱 코드
2. models.py 생성 - Pydantic 스키마
3. database.py 생성 - SQLite 연결
4. requirements.txt 생성 - 의존성
5. 터미널에서 pip install 실행

# 각 단계마다 사용자 승인 요청 (안전장치)

2. 파일 수정 및 리팩토링

"src/ 디렉토리의 모든 Python 파일에 타입 힌트를 추가하고,
docstring을 Google 스타일로 작성해줘."

# Cline이 각 파일을 읽고 수정 계획을 수립
# 파일별 diff를 보여주며 승인 요청

3. 디버깅 및 테스트

"tests/ 폴더를 만들고 main.py의 모든 엔드포인트에 대한
pytest 테스트를 작성한 다음, 테스트를 실행해서 결과를 알려줘."

# Cline이 테스트 작성 → 실행 → 실패 시 자동 수정

팁 & 주의사항

# Cline에 최적화된 모델 다운로드
ollama pull qwen2.5-coder:14b     # 최고 품질
ollama pull codellama:13b          # 안정적 대안
ollama pull qwen2.5-coder:7b      # 경량 옵션

API 통합 (Python, JavaScript)

Python API 클라이언트

requests 라이브러리

import requests
import json

# 기본 생성 요청
def generate(prompt: str, model: str = "llama3.2") -> str:
    url = "http://localhost:11434/api/generate"
    payload = {
        "model": model,
        "prompt": prompt,
        "stream": False
    }

    response = requests.post(url, json=payload)
    return response.json()["response"]

# 사용
result = generate("Python으로 Hello World 작성")
print(result)

스트리밍

import requests

def generate_stream(prompt: str):
    url = "http://localhost:11434/api/generate"
    payload = {
        "model": "llama3.2",
        "prompt": prompt,
        "stream": True
    }

    with requests.post(url, json=payload, stream=True) as response:
        for line in response.iter_lines():
            if line:
                data = json.loads(line)
                if "response" in data:
                    print(data["response"], end="", flush=True)

generate_stream("긴 이야기를 들려줘")

채팅 API

import requests

def chat(messages: list) -> str:
    url = "http://localhost:11434/api/chat"
    payload = {
        "model": "llama3.2",
        "messages": messages,
        "stream": False
    }

    response = requests.post(url, json=payload)
    return response.json()["message"]["content"]

# 대화
messages = [
    {"role": "system", "content": "당신은 파이썬 전문가입니다."},
    {"role": "user", "content": "FastAPI로 REST API 만드는 방법은?"}
]

response = chat(messages)
print(response)

JavaScript/Node.js API 클라이언트

Fetch API (브라우저)

// 기본 생성
async function generate(prompt) {
  const response = await fetch('http://localhost:11434/api/generate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      model: 'llama3.2',
      prompt: prompt,
      stream: false
    })
  });

  const data = await response.json();
  return data.response;
}

// 사용
generate('JavaScript로 Hello World').then(console.log);

스트리밍 (Node.js)

const https = require('https');

function generateStream(prompt) {
  const data = JSON.stringify({
    model: 'llama3.2',
    prompt: prompt,
    stream: true
  });

  const options = {
    hostname: 'localhost',
    port: 11434,
    path: '/api/generate',
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Content-Length': data.length
    }
  };

  const req = http.request(options, (res) => {
    res.on('data', (chunk) => {
      const line = chunk.toString();
      const parsed = JSON.parse(line);
      process.stdout.write(parsed.response);
    });
  });

  req.write(data);
  req.end();
}

generateStream('긴 이야기를 들려줘');

ollama-js 라이브러리

// 설치
// npm install ollama

import { Ollama } from 'ollama';

const ollama = new Ollama({ host: 'http://localhost:11434' });

// 생성
const response = await ollama.generate({
  model: 'llama3.2',
  prompt: 'TypeScript로 타입 정의하는 방법'
});

console.log(response.response);

// 채팅
const chatResponse = await ollama.chat({
  model: 'llama3.2',
  messages: [
    { role: 'user', content: 'React Hook 설명해줘' }
  ]
});

console.log(chatResponse.message.content);

Claude API 하이브리드 연동

Claude API와 Ollama를 함께 사용하면 클라우드의 고품질 추론과 로컬의 프라이버시·비용 절감을 동시에 확보할 수 있습니다. 이 섹션에서는 하이브리드 아키텍처 설계부터 라우팅, 폴백, 비용 최적화까지 실전 패턴을 다룹니다.

왜 Claude + Ollama인가?

하이브리드 아키텍처

작업 유형별 라우터

데이터 민감도, 작업 복잡도, 예산 잔여량을 기준으로 Claude와 Ollama를 자동 분기하는 라우터입니다.

import anthropic
import requests
from enum import Enum
from dataclasses import dataclass

class TaskComplexity(Enum):
    LOW = "low"        # 보일러플레이트, 단순 변환
    MEDIUM = "medium"  # 일반 코딩, 요약
    HIGH = "high"      # 아키텍처 설계, 복잡한 분석

class HybridRouter:
    """Claude API + Ollama 하이브리드 라우터"""

    def __init__(self, daily_budget: float = 5.0):
        self.claude = anthropic.Anthropic()
        self.ollama_url = "http://localhost:11434"
        self.daily_budget = daily_budget
        self.spent_today = 0.0

    def route(self, prompt: str, sensitive: bool = False,
              complexity: TaskComplexity = TaskComplexity.MEDIUM) -> str:
        """작업 조건에 따라 최적 엔진 선택"""

        # 규칙 1: 민감 데이터 → 항상 로컬
        if sensitive:
            return self._call_ollama(prompt)

        # 규칙 2: 예산 소진 → 로컬 전환
        if self.spent_today >= self.daily_budget:
            return self._call_ollama(prompt)

        # 규칙 3: 복잡도 기반 분기
        if complexity == TaskComplexity.HIGH:
            return self._call_claude(prompt, "claude-sonnet-4-20250514")
        elif complexity == TaskComplexity.MEDIUM:
            return self._call_claude(prompt, "claude-haiku-4-20250414")
        else:
            return self._call_ollama(prompt)

    def _call_claude(self, prompt, model):
        resp = self.claude.messages.create(
            model=model, max_tokens=2048,
            messages=[{"role": "user", "content": prompt}]
        )
        self.spent_today += resp.usage.input_tokens * 0.000003
        return resp.content[0].text

    def _call_ollama(self, prompt, model="llama3.2"):
        resp = requests.post(f"{self.ollama_url}/api/generate",
            json={"model": model, "prompt": prompt, "stream": False})
        return resp.json()["response"]

# 사용 예시
router = HybridRouter(daily_budget=3.0)

# 복잡한 설계 → Claude
result = router.route("마이크로서비스 인증 아키텍처 설계해줘",
                      complexity=TaskComplexity.HIGH)

# 민감 데이터 → 항상 Ollama
result = router.route("이 고객 데이터를 요약해줘: ...",
                      sensitive=True)

# 단순 작업 → Ollama
result = router.route("Python 리스트 컴프리헨션 예제",
                      complexity=TaskComplexity.LOW)

오프라인 폴백 패턴

Claude API 호출 실패 시 자동으로 Ollama로 전환하는 비동기 폴백 패턴입니다.

import anthropic
import httpx
import asyncio
from typing import Optional

class ResilientLLM:
    """Claude 우선 호출 + Ollama 자동 폴백"""

    def __init__(self):
        self.claude = anthropic.AsyncAnthropic()
        self.ollama_url = "http://localhost:11434"

    async def generate(self, prompt: str,
                       prefer_local: bool = False) -> dict:
        if prefer_local:
            return await self._try_ollama(prompt)

        # Claude 우선 시도
        try:
            resp = await self.claude.messages.create(
                model="claude-sonnet-4-20250514",
                max_tokens=2048,
                messages=[{"role": "user", "content": prompt}]
            )
            return {"text": resp.content[0].text,
                    "engine": "claude", "model": "sonnet"}

        except (anthropic.APIConnectionError,
                anthropic.RateLimitError,
                anthropic.APIStatusError) as e:
            print(f"⚠️ Claude 실패, Ollama 폴백: {e}")
            return await self._try_ollama(prompt)

    async def _try_ollama(self, prompt: str) -> dict:
        async with httpx.AsyncClient() as client:
            resp = await client.post(
                f"{self.ollama_url}/api/generate",
                json={"model": "llama3.2",
                      "prompt": prompt, "stream": False},
                timeout=60.0
            )
            return {"text": resp.json()["response"],
                    "engine": "ollama", "model": "llama3.2"}

# 사용
llm = ResilientLLM()
result = await llm.generate("이 코드를 리팩터링해줘: ...")
print(f"엔진: {result['engine']}, 모델: {result['model']}")

LiteLLM 통합 설정

LiteLLM 프록시로 Claude와 Ollama를 하나의 엔드포인트로 통합하면 클라이언트 코드 변경 없이 자동 라우팅·폴백을 구현할 수 있습니다.

# litellm_config.yaml — Claude 기본 + Ollama 폴백
model_list:
  - model_name: "smart"           # 복잡한 작업용
    litellm_params:
      model: "anthropic/claude-sonnet-4-20250514"
      api_key: "os.environ/ANTHROPIC_API_KEY"

  - model_name: "smart"           # 폴백
    litellm_params:
      model: "ollama/llama3.2"
      api_base: "http://localhost:11434"

  - model_name: "fast"            # 단순 작업용
    litellm_params:
      model: "ollama/llama3.2"
      api_base: "http://localhost:11434"

router_settings:
  routing_strategy: "simple-shuffle"
  num_retries: 2
  fallbacks: [{"smart": ["fast"]}]

# 클라이언트: 하나의 엔드포인트로 통합 사용
from openai import OpenAI

client = OpenAI(base_url="http://localhost:4000", api_key="anything")

# 복잡한 작업 → Claude (실패 시 자동 Ollama 폴백)
resp = client.chat.completions.create(
    model="smart",
    messages=[{"role": "user", "content": "아키텍처 설계해줘"}]
)

# 단순 작업 → 직접 Ollama
resp = client.chat.completions.create(
    model="fast",
    messages=[{"role": "user", "content": "Hello World 예제"}]
)

비용 최적화 시나리오

월간 10만 요청 기준, 4가지 전략별 예상 비용을 비교합니다.

기타 유용한 도구

Twinny (VS Code 확장)

# Continue의 대안, 더 가벼움
1. VS Code Extensions에서 "Twinny" 설치
2. Settings → Ollama API URL: http://localhost:11434
3. 모델 선택: codellama:7b

# 특징
- 빠른 자동완성
- 낮은 리소스 사용
- 간단한 UI

ShellGPT (터미널 AI)

# 설치
pip install shell-gpt

# Ollama 연동
export OPENAI_API_BASE="http://localhost:11434/v1"
export OPENAI_API_KEY="ollama"
export DEFAULT_MODEL="llama3.2"

# 사용
sgpt "현재 디렉토리의 큰 파일 찾는 명령어"
# find . -type f -exec du -h {} + | sort -rh | head -n 10

# 코드 생성
sgpt --code "Python으로 JSON 파일 읽기"

Fabric (패턴 기반 프롬프트)

# 설치
pip install fabric-ai

# Ollama 설정
fabric --setup
API Base: http://localhost:11434
Model: llama3.2

# 사용 (다양한 패턴)
cat article.txt | fabric --pattern summarize
cat code.py | fabric --pattern explain_code
cat email.txt | fabric --pattern extract_insights

AnythingLLM (문서 관리)

# Docker로 설치
docker run -d -p 3001:3001 \
  -v anythingllm:/app/server/storage \
  -e OLLAMA_BASE_PATH="http://host.docker.internal:11434" \
  mintplexlabs/anythingllm

# 접속
http://localhost:3001

# 기능
- 문서 업로드 (PDF, DOCX, TXT)
- 워크스페이스별 RAG
- 채팅 히스토리
- 에이전트 모드

도구 비교

다음 단계

도구 연동을 완료했다면, 이제 고급 활용법을 배워봅시다!

도구 선택 가이드

Ollama와 연동할 수 있는 도구가 많아 처음 시작할 때 어떤 도구를 선택해야 할지 혼란스러울 수 있습니다. 아래 의사결정 트리를 참고하여 자신의 개발 환경과 목적에 맞는 최적의 도구를 선택하세요.

모델 추천 가이드

작업 유형에 따라 최적의 모델이 다릅니다. 아래 표를 참고하여 GPU 메모리와 작업 목적에 맞는 모델을 선택하세요.

통합 트러블슈팅

도구와 Ollama를 연동할 때 자주 발생하는 문제와 해결 방법입니다.

연결 거부 (Connection Refused)

# 증상: "Connection refused" 또는 "ECONNREFUSED"

# 원인 1: Ollama 서비스가 실행되지 않음
ollama serve                      # Ollama 시작
systemctl start ollama            # systemd로 시작

# 원인 2: 잘못된 포트/호스트
curl http://localhost:11434       # 연결 테스트
# "Ollama is running" 메시지 확인

# 원인 3: Docker 환경에서 localhost 접근 불가
# host.docker.internal 또는 컨테이너 IP 사용
OLLAMA_BASE_URL=http://host.docker.internal:11434

CORS 오류 (브라우저 앱)

# 증상: "Access-Control-Allow-Origin" 오류

# 해결: Ollama 환경 변수로 CORS 허용
OLLAMA_ORIGINS="*" ollama serve

# 또는 특정 도메인만 허용
OLLAMA_ORIGINS="http://localhost:3000,http://localhost:5173" ollama serve

# systemd 사용 시
sudo systemctl edit ollama
# [Service] 섹션에 추가:
Environment="OLLAMA_ORIGINS=*"

메모리 부족 (Out of Memory)

# 증상: "out of memory" 또는 응답 없음

# 확인: 현재 메모리 사용량
nvidia-smi                        # GPU 메모리
free -h                           # 시스템 메모리

# 해결 1: 더 작은 모델 사용
ollama run llama3.2:3b            # 7B → 3B로 변경

# 해결 2: 컨텍스트 길이 줄이기
ollama run llama3.2 --ctx 2048    # 기본 4096 → 2048

# 해결 3: 사용 안 하는 모델 언로드
curl http://localhost:11434/api/generate \
  -d '{"model":"llama3.2","keep_alive":0}'

느린 응답 속도

# 확인: GPU가 사용되고 있는지
ollama ps                         # 실행 중인 모델 확인
nvidia-smi                        # GPU 사용률 확인

# 해결 1: GPU 레이어 수 늘리기
OLLAMA_NUM_GPU=999 ollama serve    # 모든 레이어를 GPU에

# 해결 2: 동시 요청 제한
OLLAMA_NUM_PARALLEL=1 ollama serve # 동시 요청 1개로 제한

# 해결 3: 양자화 모델 사용
ollama pull codellama:13b-q4_0    # Q4 양자화 (더 빠름)

도구별 연결 확인 명령어

# Ollama 상태 확인
curl http://localhost:11434/api/tags   # 설치된 모델 목록
curl http://localhost:11434/api/ps     # 실행 중인 모델

# Continue.dev: VS Code 출력 패널 확인
View → Output → Continue 선택 → 로그 확인

# Aider: verbose 모드로 디버깅
aider --model ollama/llama3.2 --verbose

# Open WebUI: Docker 로그
docker logs open-webui --tail 50

# LangChain: Python 디버깅
import langchain
langchain.debug = True

핵심 정리

• Ollama 도구 연동의 핵심 개념과 흐름을 정리합니다.
• Continue.dev + Ollama (VS Code)를 단계별로 이해합니다.
• 실전 적용 시 기준과 주의점을 확인합니다.

실무 팁

• 입력/출력 예시를 고정해 재현성을 확보하세요.
• Ollama 도구 연동 범위를 작게 잡고 단계적으로 확장하세요.
• Continue.dev + Ollama (VS Code) 조건을 문서화해 대응 시간을 줄이세요.