로컬 모델

로컬 모델 (Ollama, vLLM, LocalAI)

Ollama, vLLM, LocalAI 같은 로컬 모델 서버를 Docker Agent에 연결하는 방법을 설명해요. OpenAI 호환 API만 있으면 어떤 로컬 서버든 연결할 수 있어요.

출처: 문서

본문

Docker Agent는 어떤 OpenAI 호환 로컬 모델 서버와도 연결할 수 있어요. 이 가이드는 가장 인기 있는 옵션을 다룬답니다:

  • Ollama — 쓰기 쉬운 로컬 모델 러너
  • vLLM — 고성능 추론 서버
  • LocalAI — 다양한 백엔드를 위한 OpenAI 호환 API

팁 Docker Model Runner 가장 쉬운 로컬 모델 경험을 원한다면 Docker Desktop에 내장되어 있고 추가 설정이 필요 없는 Docker Model Runner를 고려해 보세요.

Ollama

Ollama는 LLM을 로컬에서 실행하는 인기 있는 도구예요. Docker Agent에는 쉬운 구성을 위한 내장 ollama alias가 있어요.

설정

  • ollama.ai에서 Ollama 설치
ollama pull llama3.2
ollama pull qwen2.5-coder

ollama serve

구성

내장 ollama alias 사용:

agents:
  root:
    model: ollama/llama3.2
    description: Local assistant
    instruction: You are a helpful assistant.

ollama alias는 자동으로 다음을 사용해요:

커스텀 포트 또는 호스트

Ollama가 다른 호스트나 포트에서 실행된다면:

models:
  my_ollama:
    provider: ollama
    model: llama3.2
    base_url: http://192.168.1.100:11434/v1

agents:
  root:
    model: my_ollama
    description: Remote Ollama assistant
    instruction: You are a helpful assistant.

인기 있는 Ollama 모델

모델 크기 용도
llama3.2 3B 범용, 빠름
llama3.1 8B 더 나은 추론
qwen2.5-coder 7B 코드 생성
mistral 7B 범용
codellama 7B 코드 작업
deepseek-coder 6.7B 코드 생성

vLLM

vLLM은 처리량에 최적화된 고성능 추론 서버예요.

설정

# vLLM 설치
pip install vllm

# 서버 시작
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.2-3B-Instruct \
  --port 8000

구성

providers:
  vllm:
    api_type: openai_chatcompletions
    base_url: http://localhost:8000/v1

agents:
  root:
    model: vllm/meta-llama/Llama-3.2-3B-Instruct
    description: vLLM-powered assistant
    instruction: You are a helpful assistant.

LocalAI

LocalAI는 다양한 백엔드에서 동작하는 OpenAI 호환 API를 제공해요.

설정

# Docker로 실행
docker run -p 8080:8080 --name local-ai \
  -v ./models:/models \
  localai/localai:latest-cpu

구성

providers:
  localai:
    api_type: openai_chatcompletions
    base_url: http://localhost:8080/v1

agents:
  root:
    model: localai/gpt4all-j
    description: LocalAI assistant
    instruction: You are a helpful assistant.

일반 커스텀 프로바이더

어떤 OpenAI 호환 서버든:

providers:
  my_server:
    api_type: openai_chatcompletions
    base_url: http://localhost:8000/v1
    # token_key: MY_API_KEY  # 인증이 필요하면

agents:
  root:
    model: my_server/model-name
    description: Custom server assistant
    instruction: You are a helpful assistant.

성능 팁

참고 로컬 모델 고려사항

  • 메모리: 큰 모델일수록 더 많은 RAM/VRAM이 필요해요. 7B 모델은 보통 8-16GB RAM이 필요해요.
  • GPU: GPU 가속은 속도를 크게 높여요. 서버의 GPU 지원을 확인하세요.
  • 컨텍스트 길이: 로컬 모델은 보통 클라우드 모델보다 컨텍스트 윈도우가 작아요.
  • 도구 호출: 모든 로컬 모델이 함수/도구 호출을 지원하는 건 아니에요. 모델의 능력을 테스트해 보세요.

예시: 오프라인 개발 에이전트

agents:
  developer:
    model: ollama/qwen2.5-coder
    description: Offline code assistant
    instruction: |
      You are a software developer working offline.
      Focus on code quality and clear explanations.
    max_iterations: 20
    toolsets:
      - type: filesystem
      - type: shell
      - type: think
      - type: todo

문제 해결

연결 거부 (Connection Refused)

모델 서버가 실행 중이고 접근 가능한지 확인하세요:

curl http://localhost:11434/v1/models  # Ollama
curl http://localhost:8000/v1/models   # vLLM

모델을 찾을 수 없음

모델이 내려받아져 있고/사용 가능한지 확인:

ollama list  # 사용 가능한 Ollama 모델 목록

응답이 느림

  • GPU 가속이 활성화되어 있는지 확인
  • 더 작은 모델 시도
  • 설정에서 max_tokens 줄이기

더 알아보기 (Learn more)