Hugging Face's logo

Hub documentation

AI 모델을 로컬에서 사용

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

AI 모델을 로컬에서 사용

Hub의 AI 모델을 로컬 머신에서 실행할 수 있습니다. 이를 통해 다음과 같은 이점을 누릴 수 있습니다:

  • 개인정보 보호: 데이터를 원격 서버로 전송하지 않습니다.
  • 속도: 하드웨어가 제한 요인이며, 서버나 연결 속도가 아닙니다.
  • 제어: 모델을 원하는 대로 구성할 수 있습니다.
  • 비용: API 제공업체에 비용을 지불하지 않고 모델을 로컬에서 실행할 수 있습니다.

로컬 앱 사용 방법

Local apps는 Hugging Face 모델을 사용자의 머신에서 직접 실행할 수 있는 애플리케이션입니다. 시작하려면:

  1. 로컬 앱 설정에서 로컬 앱 사용을 활성화하세요.

Local Apps

  1. 지원되는 모델을 Hub에서 검색하여 선택합니다. 필터 사이드바의 Other 섹션에 있는 Apps 그룹에서 앱별로 필터링할 수 있습니다. 예를 들어 llama.cpp와 호환되는 모델:

Local Apps

  1. 모델 페이지의 “Use this model” 드롭다운에서 로컬 앱 선택을 선택합니다.

Local Apps

  1. 터미널에서 제공된 명령을 복사하여 실행합니다.

Local Apps

지원되는 로컬 앱

지원되는 로컬 앱은 로컬 앱 설정에 나열되어 있습니다.

모델 페이지에서 이 모델을 사용 드롭다운은 해당 모델이 앱과 호환될 때만 앱을 표시합니다(예: llama.cpp 또는 Ollama용 GGUF 모델).

다음 앱들이 현재 Hub에서 사용할 수 있습니다:

앱웹사이트호환되는 모델
Llamallama.appGGUF
llama.cppgithub.com/ggml-org/llama.cppGGUF
LM Studiolmstudio.aiGGUF, MLX
1월jan.aiGGUF
원자적 채팅atomic.chatGGUF, MLX
Unsloth Desktopunsloth.ai/docsGGUF, Unsloth 모델
Ollamaollama.comGGUF
vLLMdocs.vllm.aiTransformers, GGUF, AWQ, GPTQ 텍스트 생성 및 이미지-텍스트-투-텍스트 모델
SGLangdocs.sglang.ioTransformers, AWQ, GQPT 텍스트 생성 및 이미지-텍스트-투-텍스트 모델
MLX LMgithub.com/ml-explore/mlx-lmMLX 텍스트 생성 모델
Docker Model Runnerdocs.docker.com/ai/model-runnerGGUF, vLLM 호환 모델
레모네이드lemonade-server.aiGGUF, AMD Ryzen AI 모델
Pigithub.com/earendil-works/pi도구 호출이 가능한 GGUF 및 MLX 채팅 모델
Hermes Agenthermes-agent.nousresearch.com도구 호출이 가능한 GGUF 및 MLX 채팅 모델
OpenClawgithub.com/openclaw/openclaw도구 호출이 가능한 GGUF 및 MLX 채팅 모델
Draw Thingsdrawthings.aiDiffusers 텍스트-이미지 모델 및 LoRA
DiffusionBeediffusionbee.comDiffusers 텍스트-이미지 모델
JoyFusionjoyfusion.appjoyfusion 태그가 지정된 Core ML 텍스트-이미지 모델

👨‍💻 이러한 로컬 앱을 사용하려면, 위와 같이 모델 카드에서 스니펫을 복사하세요.

👷 로컬 앱을 개발 중이라면, 이 가이드에서 Hub와의 통합에 대해 배울 수 있습니다.

Llama

Llama는 GGUF 모델을 로컬에서 실행하기 위한 네이티브 macOS 및 Windows 애플리케이션입니다.

장점:

  • 메뉴 바 또는 작업 표시줄에 상주하는 경량 네이티브 앱
  • Hub에서 GGUF 모델 원클릭 설치
  • 설치된 모델로 로컬, 프라이빗 채팅
  • 컴퓨터에 적합한 추천 모델 가져오기
  • Pi, Hermes, OpenClaw와 같은 에이전트와 쉽게 통합

Llama를 사용하려면 GGUF 모델의 모델 카드로 이동하여 “이 모델 사용”을 클릭하세요. Llama가 열리며 모델 설치 과정을 안내합니다.

Llama는 현재 macOS와 Windows 모두에서 사용할 수 있습니다.

Llama.cpp

Llama.cpp는 CPU, CUDA, Metal을 포함한 다양한 하드웨어에서 최적화된 추론을 통해 LLM을 로컬에서 실행하기 위한 고성능 C/C++ 라이브러리입니다.

장점:

  • 다양한 CPU 계열에서 CPU 기반 모델의 매우 빠른 성능
  • 낮은 리소스 사용량
  • 여러 인터페이스 옵션(CLI, 웹 UI가 포함된 OpenAI 호환 서버)
  • CPU와 GPU에 최적화된 하드웨어

Llama.cpp를 사용하려면 모델 카드로 이동하여 “Use this model”을 클릭하고 명령을 복사하세요. 이 스니펫은 llama.cpp 설치(macOS 및 Linux의 경우 설치 스크립트, Windows의 경우 WinGet, 또는 소스에서 빌드) 및 모델 실행을 다룹니다:

# Install llama.cpp (macOS, Linux):
curl -LsSf https://llama.app/install.sh | sh

# Start a local OpenAI-compatible server with a web UI:
llama serve -hf unsloth/gpt-oss-20b-GGUF:Q4_K_M

# Or run inference directly in the terminal:
llama cli -hf unsloth/gpt-oss-20b-GGUF:Q4_K_M

전용 llama.cpp + HF 문서 페이지를 읽어보세요.

LM Studio

전용 LM Studio 문서 페이지를 읽어보세요

LM Studio는 로컬 LLM을 다운로드하고 실행하며 실험할 수 있는 간편한 방법을 제공하는 데스크톱 애플리케이션입니다.

장점:

  • 직관적인 그래픽 인터페이스
  • 내장 모델 브라우저
  • 개발자 도구 및 API
  • 개인 및 상업적 용도로 무료

GGUF 또는 MLX 모델의 모델 카드로 이동하여 이 모델 사용을 클릭합니다. LM Studio가 열리며 인터페이스를 통해 채팅을 시작할 수 있습니다.

1월

Jan은 사용자 친화적인 인터페이스를 갖추고 완전히 오프라인으로 실행되는 오픈 소스 ChatGPT 대안입니다.

장점:

  • 사용자 친화적인 GUI
  • 문서 및 파일과 대화
  • OpenAI 호환 API 서버를 통해 모델을 실행하고 다른 앱에서 사용할 수 있습니다

Jan을 사용하려면 GGUF 모델의 모델 카드로 이동하여 “이 모델 사용하기”를 클릭하세요. Jan이 열리며 인터페이스를 통해 채팅을 시작할 수 있습니다.

원자적 채팅

Atomic Chat은 로컬 모델을 실행하기 위한 데스크톱 채팅 애플리케이션입니다.

장점:

  • 그래픽 채팅 인터페이스
  • GGUF 및 MLX 모델을 모두 지원합니다

Atomic Chat를 사용하려면 GGUF 또는 MLX 모델의 모델 카드로 이동하여 “Use this model”을 클릭하세요. Atomic Chat가 열리며 모델이 다운로드 준비된 상태로 표시됩니다.

Unsloth Desktop

Unsloth Desktop는 로컬 모델을 실행하기 위한 Unsloth의 데스크톱 애플리케이션입니다.

장점:

  • 그래픽 인터페이스
  • GGUF 모델 및 Unsloth 생태계의 모델과 함께 작동합니다

Unsloth Desktop를 사용하려면 GGUF 또는 Unsloth 모델의 모델 카드로 이동하여 “Use this model”을 클릭하세요. 모델의 파일에서 하나를 선택한 경우, 선택한 GGUF 파일을 포함하여 모델이 열립니다.

Ollama

Ollama는 간단한 명령줄 인터페이스를 통해 컴퓨터에서 대규모 언어 모델을 로컬로 실행할 수 있는 애플리케이션입니다. GGUF 모델에서 사용할 수 있습니다.

장점:

  • 간편한 설치 및 설정
  • Hugging Face Hub와 직접 통합

Ollama를 사용하려면 모델 카드로 이동하여 “Use this model”을 클릭하고 명령을 복사하세요.

ollama run hf.co/unsloth/gpt-oss-20b-GGUF:Q4_K_M

vLLM

vLLM은 LLM을 위한 고처리량 추론 및 서빙 엔진으로, OpenAI 호환 API 서버를 제공합니다.

장점:

  • GPU에 최적화된 높은 처리량
  • Transformers, GGUF 및 양자화(AWQ, GPTQ) 모델을 지원합니다
  • OpenAI 호환 API 서버

vLLM은 텍스트 생성 및 이미지-텍스트-텍스트 모델에 사용할 수 있습니다. 모델 카드로 이동하여 이 모델 사용을 클릭하고 명령을 복사하세요:

# Install vLLM from pip:
pip install vllm

# Start the vLLM server:
vllm serve "openai/gpt-oss-20b"

# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "openai/gpt-oss-20b",
		"messages": [{"role": "user", "content": "What is the capital of France?"}]
	}'

…

SGLang

SGLang은 LLM 및 비전 언어 모델을 위한 빠른 서빙 프레임워크입니다.

장점:

  • GPU에서 고성능 서빙
  • Transformers 및 양자화(AWQ, GPTQ) 모델을 지원합니다
  • OpenAI 호환 API 서버

SGLang은 텍스트 생성 및 이미지-텍스트-텍스트 모델에 사용할 수 있습니다. 모델 카드로 이동하여 이 모델 사용을 클릭하고 명령을 복사하세요:

# Install SGLang from pip:
pip install sglang

# Start the SGLang server:
python3 -m sglang.launch_server \
    --model-path "openai/gpt-oss-20b" \
    --host 0.0.0.0 \
    --port 30000

서버는 포트 30000에서 OpenAI 호환 API를 제공합니다. 스니펫에는 lmsysorg/sglang 이미지를 사용하는 Docker 명령어도 포함되어 있습니다.

MLX LM

MLX LM는 Apple의 MLX 프레임워크를 사용하여 Apple silicon에서 LLM을 실행합니다.

장점:

  • Apple silicon에 최적화
  • 명령줄에서 대화형 채팅 및 텍스트 생성
  • OpenAI 호환 서버

MLX LM은 MLX 텍스트 생성 모델에 사용할 수 있습니다. 모델 카드로 이동하여 이 모델 사용을 클릭하고 명령을 복사하세요:

# Install MLX LM
uv tool install mlx-lm

# Interactive chat REPL
mlx_lm.chat --model "mlx-community/Qwen3-4B-4bit"

# Or start an OpenAI-compatible server
mlx_lm.server --model "mlx-community/Qwen3-4B-4bit"

Docker 모델 러너

Docker Model Runner를 사용하면 Docker CLI로 모델을 가져와 실행할 수 있습니다.

장점:

  • 익숙한 Docker 도구를 사용합니다
  • GGUF 모델 및 vLLM 호환 모델을 지원합니다

모델 카드로 이동하여 이 모델 사용을 클릭하고 명령을 복사합니다:

docker model run hf.co/unsloth/gpt-oss-20b-GGUF:Q4_K_M

Lemonade

Lemonade는 AMD 하드웨어에 최적화된 로컬 LLM 서버입니다.

장점:

  • GGUF 모델 지원
  • AMD Ryzen AI NPU용으로 구축된 모델(태그가 ryzenai-npu 또는 ryzenai-hybrid인 모델)을 실행합니다

Lemonade를 다운로드한 후, 모델 카드로 이동하여 “Use this model”을 클릭하고 명령을 복사합니다:

# Pull the model
lemonade pull unsloth/gpt-oss-20b-GGUF:Q4_K_M

# Run and chat with the model
lemonade run user.gpt-oss-20b-GGUF-Q4_K_M

# List all available models
lemonade list

Pi

Pi는 터미널에서 실행되는 코딩 에이전트입니다.

Pi는 도구 호출을 지원하는 채팅 템플릿을 가진 GGUF 및 MLX 채팅 모델에서 사용할 수 있습니다. 아래 스니펫은 먼저 로컬 OpenAI 호환 서버를 시작하고(llama serve는 GGUF 모델용, mlx_lm.server는 MLX 모델용), 이후 Pi가 해당 서버를 사용하도록 설정합니다:

# Start a local OpenAI-compatible server:
llama serve -hf unsloth/gpt-oss-20b-GGUF:Q4_K_M

# Install Pi:
npm install -g @earendil-works/pi-coding-agent

# start Pi in your project directory:
pi

# configure Pi to use your llama server:
/login llama.cpp

Hermes Agent

Hermes Agent는 로컬 모델로 실행할 수 있는 Nous Research의 AI 에이전트입니다.

Hermes Agent는 chat template이 tool calling을 지원하는 GGUF 및 MLX chat 모델에서 사용할 수 있습니다. 아래 스니펫은 먼저 로컬 OpenAI 호환 서버를 시작하고(llama serve는 GGUF 모델용, mlx_lm.server는 MLX 모델용), 이어서 Hermes Agent가 해당 서버를 사용하도록 구성합니다:

# Start a local OpenAI-compatible server:
llama serve -hf unsloth/gpt-oss-20b-GGUF:Q4_K_M

# Install Hermes:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
hermes setup

# Point Hermes at the local server:
hermes config set model.provider custom
hermes config set model.base_url http://127.0.0.1:8080/v1
hermes config set model.default unsloth/gpt-oss-20b-GGUF:Q4_K_M

# Run Hermes
hermes

OpenClaw

OpenClaw는 로컬 모델로 실행할 수 있는 오픈소스 개인 AI 에이전트입니다.

OpenClaw는 chat template이 tool calling을 지원하는 GGUF 및 MLX chat model에서 사용할 수 있습니다. 아래 스니펫은 먼저 로컬 OpenAI 호환 서버를 시작하고(llama serve는 GGUF 모델용, mlx_lm.server는 MLX 모델용), 이후 OpenClaw가 해당 서버를 사용하도록 구성합니다:

# Start a local OpenAI-compatible server:
llama serve -hf unsloth/gpt-oss-20b-GGUF:Q4_K_M

# Install OpenClaw:
npm install -g openclaw@latest

# Register the local server and set it as the default model:
openclaw onboard --non-interactive --mode local \
  --auth-choice custom-api-key \
  --custom-base-url http://127.0.0.1:8080/v1 \
  --custom-model-id "unsloth/gpt-oss-20b-GGUF:Q4_K_M" \
  --custom-provider-id llama-cpp \
  --custom-compatibility openai \
  --custom-text-input \
  --accept-risk \
  --skip-health

# Run OpenClaw
openclaw agent --local --agent main --message "Hello from Hugging Face"

Draw Things

Draw Things는 Apple 기기에서 로컬로 이미지를 생성하는 앱입니다.

장점:

  • Runs text-to-image models fully on-device
  • 기본 모델과 LoRA를 모두 가져올 수 있습니다

Draw Things를 사용하려면 Diffusers의 텍스트-이미지 모델 또는 LoRA의 모델 카드로 이동하여 “Use this model”을 클릭하세요. Draw Things가 열리고 모델이 가져와집니다.

Draw Things는 macOS에서만 사용할 수 있습니다.

DiffusionBee

DiffusionBee는 Stable Diffusion 모델을 사용하여 로컬에서 이미지를 생성하는 데스크톱 앱입니다.

장점:

  • 간단한 그래픽 인터페이스
  • 설정이나 명령줄이 필요하지 않습니다

DiffusionBee를 사용하려면 Diffusers의 텍스트-이미지 생성 모델 카드로 이동하여 “이 모델 사용”을 클릭하세요. DiffusionBee가 열리고 모델이 가져와집니다.

DiffusionBee는 macOS에서만 사용할 수 있습니다.

JoyFusion

JoyFusion은 Apple 기기에서 Core ML 모델을 사용하여 로컬에서 이미지를 생성하는 앱입니다.

JoyFusion를 사용하려면 joyfusion 태그가 지정된 Core ML 텍스트-이미지 모델의 모델 카드로 이동한 후 “Use this model”을 클릭하세요. JoyFusion이 열리고 모델이 가져와집니다.

JoyFusion은 macOS에서만 사용할 수 있습니다.

Update on GitHub

←하드웨어 자주 묻는 질문→