LocalAI Docker 설치 가이드: 로컬 OpenAI 호환 API 서버 ⋆ Blog * JackerLab

개요

LocalAI는 OpenAI API 호환 로컬 추론 서버입니다. 텍스트 생성, 이미지 생성, 음성 인식(STT), 음성 합성(TTS), 임베딩 등을 로컬에서 실행할 수 있습니다. 기존 OpenAI SDK/앱을 코드 변경 없이 LocalAI로 대체할 수 있으며, GPU 없이도 CPU만으로 실행 가능합니다.

항목	내용
GitHub	https://github.com/mudler/LocalAI
공식 사이트	https://localai.io
문서	https://localai.io/docs
라이선스	MIT
GitHub Stars	28K+

LocalAI란?

OpenAI API 드롭인 대체

# 기존 OpenAI API 호출
curl https://api.openai.com/v1/chat/completions ...

# LocalAI로 변경 (URL만 바꾸면 됨!)
curl http://localhost:8080/v1/chat/completions ...

기존 OpenAI를 사용하는 모든 앱/라이브러리에서 URL만 변경하면 LocalAI를 사용할 수 있습니다.

핵심 특징

✅ OpenAI API 100% 호환: 기존 코드 그대로 사용
✅ GPU 불필요: CPU만으로 실행 가능
✅ 멀티모달: 텍스트, 이미지, 음성, 임베딩
✅ 프라이버시: 데이터가 로컬에만 존재
✅ 다중 백엔드: llama.cpp, vLLM, transformers 등
✅ 모델 갤러리: 원클릭 모델 설치
✅ Anthropic API: Claude API도 호환 (v3.10+)

LocalAI 생태계

프로젝트	설명
LocalAI	OpenAI 호환 API 서버
LocalAGI	AI 에이전트 플랫폼
LocalRecall	시맨틱 검색/메모리
Cogito	Go 에이전트 라이브러리

주요 기능

🔤 텍스트 생성

엔드포인트	설명
`/v1/chat/completions`	채팅 (ChatGPT 호환)
`/v1/completions`	텍스트 완성
`/v1/edits`	텍스트 편집

🖼️ 이미지 생성

엔드포인트	설명
`/v1/images/generations`	이미지 생성 (DALL-E 호환)

지원 백엔드: Stable Diffusion, FLUX, SDXL, etc.

🎤 음성 처리

엔드포인트	설명
`/v1/audio/transcriptions`	음성 → 텍스트 (Whisper)
`/v1/audio/translations`	음성 번역
`/v1/audio/speech`	텍스트 → 음성 (TTS)

📊 임베딩

엔드포인트	설명
`/v1/embeddings`	벡터 임베딩 생성

👁️ 비전 (GPT-4V 호환)

엔드포인트	설명
`/v1/chat/completions`	이미지 분석 (멀티모달)

🛠️ 함수 호출

기능	설명
Functions	OpenAI Functions API 호환
Tools	Tool calling 지원
MCP	Model Context Protocol 지원

🌐 실시간 API

기능	설명
Realtime API	WebSocket 기반 실시간 대화
Voice + Text	음성/텍스트 멀티모달

지원 백엔드

백엔드	모델	GPU 가속
llama.cpp	LLaMA, Mistral, Phi, Qwen 등	CUDA, ROCm, Metal, Vulkan
vLLM	다양한 LLM	CUDA, ROCm
transformers	HuggingFace 모델	CUDA, ROCm
Stable Diffusion	이미지 생성	CUDA
whisper.cpp	음성 인식	CUDA, Metal
Piper	TTS	CPU
Bark	TTS	CUDA

GPU 지원

하드웨어	지원
NVIDIA CUDA 12/13	✅
AMD ROCm	✅
Intel oneAPI	✅
Vulkan	✅
Apple Metal	✅
NVIDIA Jetson	✅

시스템 요구 사항

항목	최소	권장
CPU	4 코어	8+ 코어
RAM	8GB	16GB+
GPU	없음 (CPU 가능)	NVIDIA 8GB+ VRAM
포트	8080	–

💡 모델 크기에 따라 RAM/VRAM 요구사항이 달라집니다. 7B 모델은 약 4-8GB, 13B는 8-16GB 필요.

Docker 설치

방법 1: AIO (All-in-One) CPU

가장 간단한 설치. 기본 모델이 사전 구성되어 있습니다.

# docker-compose.yml
services:
  localai:
    image: localai/localai:latest-aio-cpu
    container_name: localai
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    environment:
      - DEBUG=false
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/readyz"]
      interval: 1m
      timeout: 20s
      retries: 5

방법 2: AIO GPU (NVIDIA CUDA 12)

# docker-compose.yml
services:
  localai:
    image: localai/localai:latest-aio-gpu-nvidia-cuda-12
    container_name: localai
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    environment:
      - DEBUG=false
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/readyz"]
      interval: 1m
      timeout: 20s
      retries: 5

방법 3: Standard CPU (모델 수동 설정)

# docker-compose.yml
services:
  localai:
    image: localai/localai:latest
    container_name: localai
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    environment:
      - DEBUG=false
      - THREADS=4
      - CONTEXT_SIZE=2048

방법 4: Standard GPU (NVIDIA CUDA 12)

# docker-compose.yml
services:
  localai:
    image: localai/localai:latest-gpu-nvidia-cuda-12
    container_name: localai
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    environment:
      - DEBUG=false
      - THREADS=4
      - CONTEXT_SIZE=4096
      - GPU_LAYERS=35
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

방법 5: AMD GPU (ROCm)

# docker-compose.yml
services:
  localai:
    image: localai/localai:latest-aio-gpu-hipblas
    container_name: localai
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    devices:
      - /dev/kfd
      - /dev/dri
    group_add:
      - video
    environment:
      - DEBUG=false

방법 6: Intel GPU

# docker-compose.yml
services:
  localai:
    image: localai/localai:latest-aio-gpu-intel
    container_name: localai
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    devices:
      - /dev/dri
    environment:
      - DEBUG=false

방법 7: API 키 보호

# docker-compose.yml
services:
  localai:
    image: localai/localai:latest-aio-cpu
    container_name: localai
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    environment:
      - DEBUG=false
      - API_KEY=your-secret-api-key

방법 8: Traefik + HTTPS

# docker-compose.yml
services:
  localai:
    image: localai/localai:latest-aio-gpu-nvidia-cuda-12
    container_name: localai
    restart: unless-stopped
    volumes:
      - ./models:/models
    environment:
      - DEBUG=false
      - API_KEY=your-secret-api-key
    networks:
      - traefik_network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.localai.rule=Host(`ai-api.example.com`)"
      - "traefik.http.routers.localai.entrypoints=websecure"
      - "traefik.http.routers.localai.tls.certresolver=letsencrypt"
      - "traefik.http.services.localai.loadbalancer.server.port=8080"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

networks:
  traefik_network:
    external: true

환경 변수

기본 설정

변수	설명	기본값
`THREADS`	CPU 스레드 수	자동
`CONTEXT_SIZE`	컨텍스트 크기	`512`
`DEBUG`	디버그 로그	`false`
`API_KEY`	API 키 보호	–

GPU 설정

변수	설명
`GPU_LAYERS`	GPU에 오프로드할 레이어 수
`MAIN_GPU`	메인 GPU 인덱스
`TENSOR_SPLIT`	다중 GPU 분할

모델 설정

변수	설명
`MODELS_PATH`	모델 디렉토리
`PRELOAD_MODELS`	시작 시 로드할 모델
`MMAP`	메모리 매핑 사용

성능 설정

변수	설명
`F16`	FP16 사용
`PARALLEL_REQUESTS`	병렬 요청 활성화

모델 설치

모델 갤러리 (WebUI)

URL: http://localhost:8080
→ Models 탭 → 원하는 모델 Install

CLI로 설치

# 모델 목록 확인
docker exec localai local-ai models list

# 모델 설치
docker exec localai local-ai models install llama-3.2-3b-instruct:q4_k_m
docker exec localai local-ai models install mistral-7b-instruct:q4_k_m
docker exec localai local-ai models install phi-4:q4_k_m

다양한 소스에서 설치

# 갤러리에서
local-ai run llama-3.2-1b-instruct:q4_k_m

# HuggingFace에서
local-ai run huggingface://TheBloke/phi-2-GGUF/phi-2.Q8_0.gguf

# Ollama 레지스트리에서
local-ai run ollama://gemma:2b

# URL에서
local-ai run https://example.com/model.yaml

# OCI 레지스트리에서
local-ai run oci://localai/phi-2:latest

AIO 이미지 기본 모델

AIO 이미지에는 OpenAI 호환 이름의 모델이 사전 설정되어 있습니다:

OpenAI 이름	실제 모델
`gpt-4`	오픈소스 LLM
`gpt-4-vision-preview`	멀티모달 LLM
`whisper-1`	Whisper
`tts-1`	TTS 모델

API 사용 예시

채팅 (Chat Completions)

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ]
  }'

스트리밍

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Tell me a story"}],
    "stream": true
  }'

임베딩

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-ada-002",
    "input": "Hello world"
  }'

이미지 생성

curl http://localhost:8080/v1/images/generations \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stablediffusion",
    "prompt": "A beautiful sunset over mountains",
    "size": "512x512"
  }'

음성 인식 (Whisper)

curl http://localhost:8080/v1/audio/transcriptions \
  -F "file=@audio.mp3" \
  -F "model=whisper-1"

음성 합성 (TTS)

curl http://localhost:8080/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Hello, how are you?",
    "voice": "alloy"
  }' --output speech.mp3

함수 호출

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "What is the weather in Seoul?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get weather information",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string"}
          }
        }
      }
    }]
  }'

Python SDK 사용

from openai import OpenAI

# LocalAI 연결
client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed"  # API_KEY 설정 시 실제 키 사용
)

# 채팅
response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)
print(response.choices[0].message.content)

# 임베딩
embeddings = client.embeddings.create(
    model="text-embedding-ada-002",
    input="Hello world"
)
print(embeddings.data[0].embedding)

모델 설정 (YAML)

커스텀 모델 설정:

# models/my-model.yaml
name: my-llama
backend: llama-cpp
parameters:
  model: /models/llama-3.2-3b.gguf
  context_size: 4096
  threads: 8
  gpu_layers: 35
  f16: true

# 프롬프트 템플릿
template:
  chat: |
    {{.Input}}
    ### Response:

통합 예시

Open WebUI 연결

# docker-compose.yml
services:
  localai:
    image: localai/localai:latest-aio-gpu-nvidia-cuda-12
    container_name: localai
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    restart: unless-stopped
    ports:
      - "3000:8080"
    volumes:
      - ./open-webui-data:/app/backend/data
    environment:
      - OPENAI_API_BASE_URL=http://localai:8080/v1
      - OPENAI_API_KEY=not-needed

LangChain 연결

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="http://localhost:8080/v1",
    api_key="not-needed",
    model="gpt-4"
)

response = llm.invoke("Hello!")

백업 및 업데이트

데이터 구조

./models/
├── *.gguf          # 모델 파일
├── *.yaml          # 모델 설정
└── */              # 백엔드별 데이터

백업

# 모델은 용량이 크므로 설정만 백업
tar -czvf localai-config-backup.tar.gz models/*.yaml

업데이트

docker compose pull
docker compose down
docker compose up -d

트러블슈팅

GPU 인식 안 됨

# NVIDIA 드라이버 확인
nvidia-smi

# Docker GPU 테스트
docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

메모리 부족

environment:
  # 컨텍스트 크기 줄이기
  - CONTEXT_SIZE=1024
  # GPU 레이어 줄이기
  - GPU_LAYERS=20

모델 로딩 느림

environment:
  # 메모리 매핑 사용
  - MMAP=true

이미지 태그 가이드

태그	설명
`latest`	최신 Standard CPU
`latest-aio-cpu`	AIO CPU (권장)
`latest-aio-gpu-nvidia-cuda-12`	AIO NVIDIA GPU
`latest-aio-gpu-nvidia-cuda-13`	AIO NVIDIA GPU (최신 CUDA)
`latest-aio-gpu-hipblas`	AIO AMD GPU
`latest-aio-gpu-intel`	AIO Intel GPU
`latest-gpu-vulkan`	Vulkan GPU

대안 비교

기능	LocalAI	Ollama	vLLM
OpenAI API 호환	✅ 완전	✅ 부분	✅ 부분
이미지 생성	✅	❌	❌
음성 (STT/TTS)	✅	❌	❌
GPU 불필요	✅	✅	❌
다중 백엔드	✅ 다양	❌ llama.cpp만	❌ vLLM만
모델 갤러리	✅	✅	❌
함수 호출	✅	✅	✅
설치 난이도	쉬움	매우 쉬움	중간
성능	좋음	좋음	매우 좋음

선택 가이드

용도	추천
OpenAI 완전 대체	LocalAI
간단한 LLM 실행	Ollama
고성능 프로덕션	vLLM
이미지+음성+텍스트	LocalAI

활용 사례

1. 기존 앱 로컬화

목적: 클라우드 OpenAI → 로컬 전환

# 기존 코드 변경 없이 URL만 변경
client = OpenAI(
    base_url="http://localhost:8080/v1",  # 이것만 추가
    api_key="..."
)

2. 프라이버시 중심 AI

목적: 민감한 데이터 로컬 처리

의료 데이터 분석
법률 문서 처리
기업 내부 문서

3. 오프라인 AI

목적: 인터넷 없이 AI 사용

에어갭 환경
선박/항공기
원격 지역

4. 개발/테스트

목적: API 비용 절감

로컬 개발 환경
CI/CD 테스트
프로토타입

5. 멀티모달 파이프라인

목적: 텍스트+이미지+음성 통합

# 음성 → 텍스트 → LLM → 이미지 → TTS
# 모두 단일 API 서버에서 처리

마무리

LocalAI는 OpenAI API의 완벽한 로컬 대체제입니다. 텍스트, 이미지, 음성을 모두 지원하며, 기존 코드를 변경하지 않고 URL만 바꿔서 사용할 수 있습니다.

핵심 장점

장점	설명
API 호환	OpenAI/Anthropic 드롭인 대체
멀티모달	텍스트, 이미지, 음성, 임베딩
GPU 불필요	CPU만으로 실행 가능
프라이버시	데이터 로컬 유지
다중 백엔드	llama.cpp, vLLM, transformers 등
함수 호출	Functions, Tools, MCP

이런 분께 추천

기존 OpenAI 코드를 로컬에서 실행하고 싶은 분
이미지 생성 + 음성 + LLM을 한 서버에서 원하는 분
GPU 없이 AI를 실행하고 싶은 분
프라이버시가 중요한 기업/개인
API 비용을 절감하고 싶은 개발자

개요