# AI 모델을 로컬에서 사용

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

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

## 로컬 앱 사용 방법

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

1. [로컬 앱 설정](https://huggingface.co/settings/local-apps)에서 **로컬 앱 사용**을 활성화하세요.

![Local Apps](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/local-apps/settings.png)

2. **지원되는 모델**을 Hub에서 검색하여 선택합니다. 필터 사이드바의 `Other` 섹션에 있는 `Apps` 그룹에서 앱별로 필터링할 수 있습니다. 예를 들어 [llama.cpp와 호환되는 모델](https://huggingface.co/models?apps=llama.cpp):

![Local Apps](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/local-apps/search_llamacpp.png)

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

![Local Apps](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/local-apps/button.png)

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

![Local Apps](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/local-apps/command.png)

## 지원되는 로컬 앱

지원되는 로컬 앱은 [로컬 앱 설정](https://huggingface.co/settings/local-apps)에 나열되어 있습니다.

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

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

| 앱 | 웹사이트 | 호환되는 모델 |
| --- | --- | --- |
|  [Llama](#llama) | [llama.app](https://llama.app) | GGUF |
|  [llama.cpp](#llamacpp) | [github.com/ggml-org/llama.cpp](https://github.com/ggml-org/llama.cpp) | GGUF |
|  [LM Studio](#lm-studio) | [lmstudio.ai](https://lmstudio.ai) | GGUF, MLX |
|  [1월](#jan) | [jan.ai](https://jan.ai) | GGUF |
|  [원자적 채팅](#atomic-chat) | [atomic.chat](https://atomic.chat) | GGUF, MLX |
|  [Unsloth Desktop](#unsloth-desktop) | [unsloth.ai/docs](https://unsloth.ai/docs) | GGUF, Unsloth 모델 |
|  [Ollama](#ollama) | [ollama.com](https://ollama.com) | GGUF |
|  [vLLM](#vllm) | [docs.vllm.ai](https://docs.vllm.ai) | Transformers, GGUF, AWQ, GPTQ 텍스트 생성 및 이미지-텍스트-투-텍스트 모델 |
|  [SGLang](#sglang) | [docs.sglang.io](https://docs.sglang.io) | Transformers, AWQ, GQPT 텍스트 생성 및 이미지-텍스트-투-텍스트 모델 |
|  [MLX LM](#mlx-lm) | [github.com/ml-explore/mlx-lm](https://github.com/ml-explore/mlx-lm) | MLX 텍스트 생성 모델 |
|  [Docker 모델 러너](#docker-model-runner) | [docs.docker.com/ai/model-runner](https://docs.docker.com/ai/model-runner/) | GGUF, vLLM 호환 모델 |
|  [레모네이드](#lemonade) | [lemonade-server.ai](https://lemonade-server.ai) | GGUF, AMD Ryzen AI 모델 |
|  [Pi](#pi) | [github.com/earendil-works/pi](https://github.com/earendil-works/pi) | 도구 호출이 가능한 GGUF 및 MLX 채팅 모델 |
|  [허메스 에이전트](#hermes-agent) | [hermes-agent.nousresearch.com](https://hermes-agent.nousresearch.com/) | 도구 호출이 가능한 GGUF 및 MLX 채팅 모델 |
|  [OpenClaw](#openclaw) | [github.com/openclaw/openclaw](https://github.com/openclaw/openclaw) | 도구 호출이 가능한 GGUF 및 MLX 채팅 모델 |
|  [Draw Things](#draw-things) | [drawthings.ai](https://drawthings.ai) | Diffusers 텍스트-이미지 모델 및 LoRA |
|  [DiffusionBee](#diffusionbee) | [diffusionbee.com](https://diffusionbee.com) | Diffusers 텍스트-이미지 모델 |
|  [JoyFusion](#joyfusion) | [joyfusion.app](https://joyfusion.app) | `joyfusion` 태그가 지정된 Core ML 텍스트-이미지 모델 |

> [!TIP]
> 👨‍💻 이러한 로컬 앱을 사용하려면, 위와 같이 모델 카드에서 스니펫을 복사하세요.
>
> 👷 로컬 앱을 개발 중이라면, [이 가이드](https://huggingface.co/docs/hub/en/models-adding-libraries)에서 Hub와의 통합에 대해 배울 수 있습니다.

### Llama

[Llama](https://llama.app)는 GGUF 모델을 로컬에서 실행하기 위한 네이티브 macOS 및 Windows 애플리케이션입니다.

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

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

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

### Llama.cpp[[llamacpp]]

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, 또는 소스에서 빌드) 및 모델 실행을 다룹니다:

```sh
# 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 문서 페이지](./gguf-llamacpp)를 읽어보세요.

### LM Studio

> [!NOTE]
> 전용 [LM Studio 문서 페이지](./lmstudio)를 읽어보세요

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

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

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

### 1월

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

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

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

### 원자적 채팅

[Atomic Chat](https://atomic.chat)은 로컬 모델을 실행하기 위한 데스크톱 채팅 애플리케이션입니다.

**장점:**
- 그래픽 채팅 인터페이스
- GGUF 및 MLX 모델을 모두 지원합니다

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

### Unsloth Desktop

[Unsloth Desktop](https://unsloth.ai/docs)는 로컬 모델을 실행하기 위한 Unsloth의 데스크톱 애플리케이션입니다.

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

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

### Ollama

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

**장점:**
- 간편한 설치 및 설정
- Hugging Face Hub와 직접 통합

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

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

### vLLM

[vLLM](https://docs.vllm.ai)은 LLM을 위한 고처리량 추론 및 서빙 엔진으로, OpenAI 호환 API 서버를 제공합니다.

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

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

```sh
# 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](https://docs.sglang.io)은 LLM 및 비전 언어 모델을 위한 빠른 서빙 프레임워크입니다.

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

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

```sh
# 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](https://github.com/ml-explore/mlx-lm)는 Apple의 MLX 프레임워크를 사용하여 Apple silicon에서 LLM을 실행합니다.

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

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

```sh
# 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](https://docs.docker.com/ai/model-runner/)를 사용하면 Docker CLI로 모델을 가져와 실행할 수 있습니다.

**장점:**
- 익숙한 Docker 도구를 사용합니다
- GGUF 모델 및 vLLM 호환 모델을 지원합니다

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

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

### Lemonade

[Lemonade](https://lemonade-server.ai)는 AMD 하드웨어에 최적화된 로컬 LLM 서버입니다.

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

[Lemonade를 다운로드](https://lemonade-server.ai)한 후, 모델 카드로 이동하여 "Use this model"을 클릭하고 명령을 복사합니다:

```sh
# 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](https://github.com/earendil-works/pi)는 터미널에서 실행되는 코딩 에이전트입니다.

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

```sh
# 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](https://hermes-agent.nousresearch.com/)는 로컬 모델로 실행할 수 있는 Nous Research의 AI 에이전트입니다.

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

```sh
# 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](https://github.com/openclaw/openclaw)는 로컬 모델로 실행할 수 있는 오픈소스 개인 AI 에이전트입니다.

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

```sh
# 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](https://drawthings.ai)는 Apple 기기에서 로컬로 이미지를 생성하는 앱입니다.

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

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

> [!NOTE]
> Draw Things는 macOS에서만 사용할 수 있습니다.

### DiffusionBee

[DiffusionBee](https://diffusionbee.com)는 Stable Diffusion 모델을 사용하여 로컬에서 이미지를 생성하는 데스크톱 앱입니다.

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

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

> [!NOTE]
> DiffusionBee는 macOS에서만 사용할 수 있습니다.

### JoyFusion

[JoyFusion](https://joyfusion.app)은 Apple 기기에서 Core ML 모델을 사용하여 로컬에서 이미지를 생성하는 앱입니다.

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

> [!NOTE]
> JoyFusion은 macOS에서만 사용할 수 있습니다.