LocalAI 빠른 시작: OpenAI 호환 대형 언어 모델을 로컬에서 실행하기

LocalAI 는 자신의 하드웨어 (노트북, 워크스테이션, 온프레미스 서버) 에서 AI 워크로드를 실행하기 위해 설계된 자체 호스팅, 로컬 우선 추론 서버로, OpenAI API 와의 호환성을 제공하여 기존 도구를 그대로 사용할 수 있도록 합니다.

이 프로젝트는 클라우드 API URL 을 교체할 수 있는 실용적인 호환성을 목표로 하며, 다양한 백엔드와 모드 (텍스트, 이미지, 오디오, 임베딩 등) 를 지원합니다.

LocalAI 란 무엇이며 엔지니어들이 사용하는 이유는 무엇인가요?

LocalAI 는 채팅 완료, 임베딩, 이미지 생성, 오디오 엔드포인트 등 주요 OpenAI 엔드포인트를 mirroring 하는 HTTP REST API 를 제공합니다. 이를 통해 기존 OpenAI 호환 툴링을 자체 인프라로 재지향할 수 있습니다.

기본 텍스트 생성을 넘어, LocalAI 의 기능 세트는 RAG 를 위한 임베딩, 확산 기반 이미지 생성, 음성 인식 (STT), 음성 합성 (TTS) 과 같은 일반적인 “프로덕션 빌딩 블록"을 포괄하며, 선택적으로 GPU 가속 및 분산 패턴을 지원합니다.

자체 호스팅 LLM 서비스를 평가 중이라면 LocalAI 는 API 호환성 (통합의 용이성) 에 중점을 두면서도 모델 설치 및 설정의 마찰을 줄이기 위해 내장된 웹 UI 와 모델 갤러리 워크플로우를 제공하므로 흥미로운 옵션입니다.

Ollama, vLLM, Docker Model Runner 및 managed 클라우드 제공자를 포함한 자체 호스팅 및 클라우드 LLM 호스팅 옵션의 더 넓은 비교를 원하시면 2026 년 LLM 호스팅 가이드를 참조하세요.

LocalAI 를 Ollama, vLLM, LM Studio 등 다른 도구와 나란히 비교하고 싶다면 2026 년 주요 로컬 LLM 도구 비교가 API 지원, 하드웨어 호환성 및 프로덕션 준비도를 다룹니다. 모델 자체 인프라 유지의 더 넓은 맥락에 대해서는 LLM 자체 호스팅 및 AI 주권에서 데이터 주재 및 규정 준수 동기를 다룹니다.

실제로 잘 작동하는 LocalAI 설치 옵션

LocalAI 는 여러 방법으로 설치할 수 있지만, 대부분의 팀에게 가장 빠르고 위험이 낮은 시작점은 컨테이너 (Docker 또는 Podman) 입니다. 아래 예제를 진행하는 동안 명령어 참조가 필요하다면 Docker 치트시트가 가장 빈번하고 유용한 Docker 명령어를 다룹니다.

Docker 를 통한 가장 빠른 시작

이 명령어는 LocalAI 서버를 시작하고 포트 8080 에서 API 와 웹 UI 를 바인딩합니다:

docker run -p 8080:8080 --name local-ai -ti localai/localai:latest

LocalAI 의 컨테이너 문서에 따르면 이는 작동하는 서버를 빠르게 구축하는 가장 빠른 경로이며, http://localhost:8080 에서 API 에 액세스할 수 있습니다.

적합한 LocalAI 컨테이너 이미지 선택

LocalAI 는 하드웨어에 맞게 선택할 수 있도록 여러 컨테이너 플러버를 게시합니다:

• 광범위한 호환성을 위한 CPU 이미지.
• NVIDIA CUDA, AMD ROCm, Intel oneAPI 및 Vulkan 을 위한 GPU 전용 이미지.
• OpenAI 유사 모델 이름으로 매핑된 모델이 사전 구성된 올인원 (AIO) 이미지.

상위 GitHub README 에는 CPU 전용 및 여러 GPU 옵션 (NVIDIA CUDA 변형, AMD ROCm, Intel, Vulkan) 과 AIO 변형을 위한 구체적인 docker run 예제가 포함되어 있습니다.

재시작 간 모델 지속성

저장소를 마운트하지 않으면 다운로드한 모델이 컨테이너 생명주기 변경 간에 유지되지 않을 수 있습니다. 컨테이너 가이드는 모델을 마운트하는 것을 권장합니다. 예를 들어:

docker run -ti --name local-ai -p 8080:8080 \
  -v "$PWD/models:/models" \
  localai/localai:latest-aio-cpu

이렇게 하면 컨테이너 내부의 /models 가 호스트에서 영구적으로 유지됩니다.

최소한의 Docker Compose 빠른 시작

LocalAI 는 리포지토리에 참조 docker-compose.yaml 을 제공하며, 포트 8080 바인딩, /models 볼륨 마운트, MODELS_PATH=/models 설정, 그리고 명령어 목록에 모델을 사전 로드하는 (리포지토리 예제에서는 phi-2) 일반적인 패턴을 보여줍니다. 이를 설정에 맞게 적응하는 동안 Docker Compose 치트시트가 유용한 참조가 됩니다.

“좋은 기본값” Compose 설정 (CPU) 은 다음과 같습니다:

services:
  localai:
    image: localai/localai:latest
    container_name: local-ai
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    environment:
      - MODELS_PATH=/models

핵심 아이디어는 상위 예제와 동일합니다: 호스트 모델 디렉터리 ↔ 컨테이너 /models.

LocalAI 와 함께 Docker 의 네이티브 docker model 툴링을 사용하는 경우, Docker Model Runner 치트시트가 pull, run, package 및 설정 명령어를 다룹니다.

컨테이너가 아닌 LocalAI 설치

LocalAI 는 플랫폼별 방법 (예: macOS DMG 및 Linux 바이너리) 을 통한 설치와 Kubernetes 와 같은 더 넓은 배포 옵션도 지원합니다.

Linux 에서 스크립트 설치를 선호하는 경우, DeepWiki 빠른 시작 가이드는 하드웨어를 자동으로 감지하고 시스템에 맞게 구성하는 install.sh 경로를 설명합니다.

예측 가능한 사용 순서

신뢰할 수 있는 LocalAI 워크플로는 다음과 같습니다:

LocalAI 시작 → 모델 설치 또는 가져오기 → 로드된 모델 확인 → OpenAI 호환 엔드포인트 호출.

이 순서는 서버 시작, 갤러리 또는 CLI 를 통해 모델 설치, curl 로 엔드포인트 테스트로 프로세스를 구성하는 공식 “시도해 보기” 및 “모델 설정” 가이드와 일치합니다.

서버 시작 및 건강 상태 확인

서버가 실행된 후 일반적인 초기 점검은 준비 상태 엔드포인트 (/readyz) 입니다:

curl http://localhost:8080/readyz

문제 해결 가이드는 LocalAI 가 응답 가능한지 확인하기 위한 첫 번째 진단 도구로 /readyz 를 사용합니다.

갤러리에서 모델 설치 또는 URI 가져오기

LocalAI 는 두 가지 주류 모델 온보딩 워크플로우를 제공합니다:

• 모델 갤러리 설치: 웹 UI 를 통해 UI 를 열고, Models 탭으로 이동하여 모델을 탐색한 후 설치를 클릭합니다.
• CLI 기반 설치 및 실행: local-ai models list, local-ai models install, local-ai run 을 사용합니다.

문서에서는 모델 URI (Hugging Face 리포지토리, 직접 모델 파일 URI 및 기타 레지스트리) 를 통한 모델 가져오기도 지원하며, 웹 UI 는 고급 구성을 위한 YAML 편집기가 포함된 전용 Import Model 워크플로우를 포함합니다.

LocalAI 가 제공할 수 있는 것 확인

OpenAI 호환 API 를 통해 배포된 모델을 나열하려면:

curl http://localhost:8080/v1/models

이는 컨테이너 설치 후 “다음 단계” 및 문제 해결 진단 도구로서 명시적으로 권장됩니다.

배워야 할 주요 명령줄 파라미터

LocalAI 의 CLI 는 포괄적인 설정 표면과 함께 local-ai run 명령어를 중심으로 구축되었습니다. 두 가지 중요한 운영 동작을 강조해야 합니다:

• 모든 CLI 플래그는 환경 변수로 설정할 수 있습니다.
• 환경 변수는 CLI 플래그보다 우선합니다.

아래는 실무자들이 초기에 주로 사용하는 파라미터로 의도에 따라 그룹화되었습니다. 모든 기본값 및 환경 변수 이름은 상위 CLI 참조에서 가져왔습니다. Ollama 를 LocalAI 와 함께 평가하는 경우, Ollama CLI 치트시트가 비교를 위한 serve, run, ps 및 모델 관리 명령어를 다룹니다.

핵심 서버 및 저장소 플래그

LocalAI 의 FAQ 에도 기본 모델 저장소 위치가 문서화되어 있으며, 기본 디렉터리 (예: 홈 디렉터리를 가득 채우는 것을 피하기 위해) 외부에 모델을 원하는 경우 LOCALAI_MODELS_PATH 또는 --models-path 사용을 명시적으로 권장합니다.

성능 및 용량 플래그

더 넓은 호환성 및 가속 제약 조건을 위해 모델 호환성 표는 어떤 백엔드가 어떤 가속 모드 (CUDA, ROCm, SYCL, Vulkan, Metal, CPU) 를 지원하는지 문서화하며, 명시적으로 구성되지 않은 모델이 자동으로 로드될 수 있음을 알립니다. YAML 설정을 통해 동작을 고정할 수 있습니다. 더 높은 처리량의 멀티 GPU 배포 (PagedAttention 포함) 에 대해서는 vLLM 빠른 시작 가이드가 프로덕션 지향 설정으로 비교 가능한 OpenAI 호환 서버를 안내합니다.

API, 보안 및 UI 플래그

LocalAI 를 원격으로 노출하는 경우 엔드포인트를 보호하고 API 키로 액세스를 제한해야 합니다. API 키는 효과적으로 전체 액세스를 부여합니다.

웹 UI 투어 및 시스템 매핑

기본적으로 LocalAI 는 API (비활성화하지 않는 한) 와 함께 내장 웹 UI 를 제공합니다. 문서에 따르면 UI 는 서버와 동일한 호스트 및 포트 (일반적으로 http://localhost:8080) 에서 접근할 수 있습니다.

내장 UI 에서 할 수 있는 작업

웹 UI 는 브라우저 기반 인터페이스로 다음을 포괄합니다:

• 모델 관리 및 갤러리 탐색 경험
• 채팅 상호작용
• 이미지 생성 및 텍스트 음성 인터페이스
• 분산 및 P2P 설정

라우트 구조는 UI 표면 영역에 대한 명확한 정신 모델을 제공합니다:

• /: 대시보드
• /browse: 모델 갤러리 브라우저
• /chat/: 채팅
• /text2image/: 이미지 생성
• /tts/: 텍스트 음성
• /talk/: 음성 상호작용
• /p2p: P2P 설정 및 모니터링

모델 갤러리 및 “모델 가져오기” 워크플로우

엔지니어에게 가장 중요한 UI 기능은 모델 온보딩입니다. 공식 “모델 설정” 가이드는 다음을 설명합니다:

• Models 탭을 통해 원클릭 설치로 모델 설치.
• 간단한 모드 (URI + 환경설정) 및 YAML 편집기 및 유효성 검사 도구가 포함된 고급 모드를 지원하는 Import Model UI 를 통한 모델 가져오기.

이는 LocalAI 가 궁극적으로 YAML 설정에 기반하여 모델을 실행하기 때문에 중요합니다. 모델 디렉터리에서 개별 YAML 파일을 관리하거나 --models-config-file 을 사용하여 여러 모델 정의를 가진 단일 파일을 사용하거나 시작 시 원격 YAML URL 을 참조할 수 있습니다.

터미널에 붙여넣을 수 있는 예제

LocalAI 의 OpenAI 호환 엔드포인트는 친숙한 요청 형식을 받아들이고 JSON 응답 (오디오 엔드포인트는 오디오 페이로드 반환) 을 반환하도록 설계되었습니다.

curl 을 사용한 채팅 완료 예제

LocalAI “시도해 보기” 페이지는 채팅 완료 엔드포인트를 직접 호출하는 방법을 보여줍니다:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      { "role": "user", "content": "LocalAI 에 대한 한 단락 설명을 작성하세요." }
    ],
    "temperature": 0.2
  }'

AIO 이미지는 gpt-4 와 같은 OpenAI 유사 이름으로 매핑된 사전 구성된 모델을 제공하며, 컨테이너 문서는 이러한 모델이 오픈 소스 모델에 기반한다고 설명합니다.

AIO 이미지를 사용하지 않는 경우, 설치한 모델 이름으로 "model" 을 교체하세요 (/v1/models 로 확인).

RAG 파이프라인을 위한 예제 임베딩

LocalAI 는 임베딩을 지원하며, 임베딩 엔드포인트는 llama.cpp, bert.cpp, sentence-transformers 를 포함한 여러 백엔드와 호환됩니다.

OpenAI 호환 엔드포인트에 대한 최소 “이 텍스트 임베딩” 요청은 다음과 같습니다:

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-ada-002",
    "input": "LocalAI 임베딩은 시맨틱 검색 및 RAG 에 편리합니다."
  }'

LocalAI 의 임베딩 문서에서는 embeddings: true 를 설정하여 YAML 설정을 통해 임베딩이 어떻게 활성화되는지도 보여줍니다.

OpenAI 호환 클라이언트 사용 예제

LocalAI 는 표준 OpenAI 클라이언트 라이브러리를 LocalAI 기본 URL (필요시 API 키 설정) 로 지향하여 사용할 수 있도록 설계되었습니다. 이 “드롭인 교체” 목표는 상위 README 및 OpenAI 호환성 문서 모두에서 설명됩니다.

일반적인 설정은 다음과 같습니다:

• 기본 URL: http://localhost:8080/v1
• API 키: 기본적으로 필요하지 않거나 --api-keys 를 설정한 경우 필요

보안 및 문제 해결 필수 사항

노출하기 전에 LocalAI 서버 보안 강화

LocalAI 는 기본적으로 로컬 호스트에서 완전히 열린 상태로 실행될 수 있습니다. 공개 인터페이스에 바인딩하거나 인그레스를 통해 노출하는 경우 다음 제어 중 적어도 하나를 추가하세요:

• --api-keys / API_KEY 를 사용하여 API 키 인증 활성화.
• 역방향 프록시 및 네트워크 제어 (방화벽, 허용 목록, VPN) 를 앞에 배치.
• API 만 필요한 경우 웹 UI 비활성화 (--disable-webui).
• 브라우저 기반 클라이언트가 실제로 필요하지 않는 한 CORS 비활성화 유지.

API 키가 활성화되면 OpenAI 호환 엔드포인트는 Authorization Bearer 헤더 또는 x-api-key 헤더 등 일반적인 위치에서 자격 증명을 허용합니다.

작동하지 않을 때 빠른 진단

LocalAI 의 문제 해결 가이드는 대부분의 “실행 중인지” 사례를 해결하는 작은 검사 세트를 제안합니다:

# 준비 상태 확인
curl http://localhost:8080/readyz

# 모델 목록
curl http://localhost:8080/v1/models

# 버전 확인
local-ai --version

DEBUG=true 또는 --log-level=debug 를 통해 디버그 로깅 활성화 방법을 문서화하며, Docker 배포의 경우 docker logs local-ai로 컨테이너 로그를 확인합니다.