LocalAI 모델 설치·실행

LocalAI 모델 설치·실행

LocalAI에서 모델을 설치하고 실행하는 방법은 여러 가지예요. 이 문서는 모델 설치 방식(갤러리, Hugging Face, OCI, 로컬 파일)과 실행 방법을 정리해요. LocalAI는 각 모델을 전용 백엔드(엔진)로 라우팅하며, 백엔드는 필요할 때 불러와요.

웹 UI로 설치

웹 인터페이스(http://localhost:8080)를 연 뒤 모델 갤러리에서 모델을 찾아 설치해요. Discover 페이지에서 모델 이름을 검색해 Install하면 돼요. qwen3-4b 같은 작은 모델은 CPU에서도 바로 동작해요.

출처: https://localai.io/docs/basics/getting_started/

CLI로 설치·실행

LocalAI를 시작하면서 인자로 설치할 모델을 지정할 수 있어요.

local-ai run qwen3-4b
local-ai run huggingface://TheBloke/phi-2-GGUF/phi-2.Q8_0.gguf
local-ai run ollama://gemma:2b

모델 관리는 CLI로 해요.

local-ai models list           # 갤러리의 모델 목록
local-ai models install <name> # 모델 설치

--help로 local-ai run의 다른 옵션을 확인할 수 있어요.

다양한 소스에서 설치

LocalAI는 local-ai run 인자로 다양한 소스를 지원해요.

  • 갤러리: local-ai run qwen3-4b처럼 이름으로.
  • Hugging Face: huggingface://user/repo/file.gguf 형식.
  • Ollama: ollama://gemma:2b 형식.
  • 로컬 파일: 로컬 GGUF 파일 경로나 URL(https://.../phi-2.yaml)로.

모델 파일을 models 디렉터리에 직접 복사해 실행할 수도 있어요(모델 문서 참고).

컴포저블 백엔드

LocalAI의 코어는 작고, 각 모델 백엔드는 전용 gRPC 서비스로 존재해요. llama.cpp, vLLM, whisper.cpp, stable-diffusion, MLX 같은 엔진을 하나의 통합 API로 노출하고, 백엔드는 OCI 이미지로 제공·격리 실행돼요. 그래서 쓰는 것만 설치·업그레이드·제거할 수 있고, 하나의 백엔드 오류가 나머지를 끌어내리지 않아요.

더 알아보기