LocalAI는 OpenAI와 호환되는 API를 통해 대규모 언어 모델 (Large Language Models, LLM)을 로컬에서 실행할 수 있는 오픈 소스 플랫폼입니다. 이를 통해 토큰당 비용을 지불하거나 데이터를 서버 외부로 전송하지 않고도 기존의 OpenAI 클라이언트 코드 뒤에 LocalAI를 교체하여 사용할 수 있습니다. 이 가이드에서는 자동 HTTPS를 처리하는 Traefik, 영구적인 모델 및 캐시 디렉토리, 그리고 작동하는 채팅 완성 (chat-completion) 테스트를 포함하여 Docker Compose를 사용하여 LocalAI를 배포합니다. 이 과정을 마치면 여러분의 도메인에서 LocalAI가 OpenAI 호환 API를 안전하게 서비스하게 됩니다.

디렉토리 구조 설정

1. 프로젝트 디렉토리 생성:

$ mkdir -p ~/localai/{models,cache}
$ cd ~/localai

models/는 다운로드된 모델 파일을 보관하며, cache/는 재시작 간에도 데이터가 유지됩니다.

2. 환경 파일 생성:

$ nano .env

DOMAIN=localai.example.com
LETSENCRYPT_EMAIL=admin@example.com

Docker Compose로 배포하기

1. 사용자를 Docker 그룹에 추가:

$ sudo usermod -aG docker $USER
$ newgrp docker

2. Compose 매니페스트 생성:

$ nano docker-compose.yaml

services:
  traefik:
    image: traefik:v3.6
...

호스트에 NVIDIA GPU가 있는 경우 localai/localai:latest-aio-cpu를 GPU 변형 버전(latest-aio-gpu-nvidia-cuda-12)으로 교체하세요.

3. 모델 디렉토리 권한 설정 및 스택 시작:

$ sudo chmod -R 755 ~/localai/models
$ docker compose up -d
$ docker compose ps

API 검증

1. 준비 상태 확인:

$ curl -i https://localai.example.com/readyz

200 OK가 나오면 Traefik이 LocalAI로 라우팅하고 있음을 확인합니다.

2. 사용 가능한 모델 목록 확인:

$ curl https://localai.example.com/v1/models

3. 채팅 완성 (chat completion) 실행:

$ curl -X POST https://localai.example.com/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
...

LocalAI는 OpenAI 완성 (completion) 형태의 응답을 반환합니다.

대시보드 접속

브라우저에서 https://localai.example.com을 열어 모델 갤러리를 둘러보고, 새 모델을 설치하며, UI에서 추론 (inference)을 실행할 수 있습니다.

다음 단계

LocalAI가 실행 중이며 HTTPS를 통해 안전하게 서비스되고 있습니다. 이제 다음과 같은 작업을 수행할 수 있습니다:

• 특정 도메인 작업(domain-specific tasks)을 위해 갤러리에서 추가 모델 설치
• OPENAI_API_BASE를 변경하여 모든 OpenAI SDK가 LocalAI 기본 URL을 가리키도록 설정
• 이미지 생성, 임베딩 (embeddings), 그리고 더 빠른 LLM 추론 (inference)을 위해 GPU 변체 (GPU variant) 실행

추가적인 팁이 포함된 전체 가이드를 확인하려면 **Vultr Docs**의 원문 기사를 방문하세요.