> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/reference/ko/inference/inference-python/offline-weights.md).

# 모델 가중치 다운로드

Roboflow Inference를 배포할 때 모델 가중치는 로컬에서 추론이 실행되는 기기로 다운로드됩니다. 이 페이지에서는 패키지가 어떻게 `추론` 이러한 가중치를 다운로드하고 캐시하는지 다룹니다.

{% hint style="info" %}
원본 `.pt`  가중치 파일을 Roboflow Inference 생태계 밖에서 실행하고 싶으신가요? 다음을 참조하세요 [모델 가중치 다운로드](https://docs.roboflow.com/models/model-weights/download-roboflow-model-weights).
{% endhint %}

## 개요

모델 가중치는 주어진 모델로 추론을 처음 실행할 때 자동으로 다운로드됩니다. 가중치는 기기에 로컬로 캐시되며, 모든 추론은 기기에서 수행됩니다(클라우드가 아님).

작동 방식:

1. 인터넷에 연결된 상태에서 모델 가중치를 기기로 다운로드합니다.
2. 가중치는 기기에 로컬로 캐시됩니다.
3. 캐시된 가중치를 사용해 기기에서 추론을 실행합니다.

이 접근 방식은 모든 Roboflow 배포 방법에서 동작하며 빠르고 로컬한 추론을 보장합니다.

{% hint style="warning" %}
**기본 캐시 위치.** 기본적으로 모델 가중치는 `/tmp/cache`에 저장되며, 이는 **시스템 재부팅 시 지워집니다**. 프로덕션 배포나 재부팅 간에도 가중치를 유지해야 하는 모든 시나리오에서는 `MODEL_CACHE_DIR`  환경 변수(다음 참조: [캐시 위치](#cache-location) ).
{% endhint %}

{% hint style="info" %}
**엔터프라이즈 오프라인 모드.** 완전히 연결이 끊긴 동작이 필요한 엔터프라이즈 배포의 경우, 다음을 참조하세요: [오프라인 모드](https://docs.roboflow.com/deployment/self-hosted/enterprise/offline-mode). 이 페이지는 사용 추적, 청구, 워크플로 업데이트를 위한 연결을 유지하면서 모델 가중치 다운로드 및 캐싱에 중점을 둡니다.
{% endhint %}

## 캐시 위치

기본적으로 모델 가중치는 `/tmp/cache`. **이 디렉터리는 시스템 재부팅 시 지워집니다**, 즉 각 재시작 후 모델 가중치를 다시 다운로드해야 합니다.

프로덕션 배포 또는 재부팅 간에도 가중치를 유지해야 하는 모든 시나리오에서는 **반드시** 다음 환경 변수를 사용해 영구 캐시 디렉터리를 구성해야 합니다: `MODEL_CACHE_DIR`  환경 변수:

```python
import os
# 영구 디렉터리로 설정 (/tmp 아님)
os.environ["MODEL_CACHE_DIR"] = "/home/user/.roboflow/cache"

from inference import get_model
# ... 나머지 코드
```

또는 시스템 전역으로 설정하세요:

```bash
export MODEL_CACHE_DIR="/home/user/.roboflow/cache"
```

디렉터리가 존재하고 적절한 권한이 있는지 확인하세요:

```bash
mkdir -p /home/user/.roboflow/cache
chmod 755 /home/user/.roboflow/cache
```

{% hint style="success" %}
**Docker 배포.** Docker에서 Inference를 실행할 때는 컨테이너 재시작 간에도 가중치를 보존하도록 영구 캐시 볼륨을 마운트하세요. 다음 참조: [Docker 구성](https://docs.roboflow.com/deployment/self-hosted/inference-server/configuration/docker-configuration#persistent-model-cache) 를 참조하세요.
{% endhint %}

## 네이티브 Python API

해당 [네이티브 Python API](/reference/ko/inference/inference-python/native-python-api.md) 모델을 로드할 때 가중치를 자동으로 다운로드하고 캐시합니다. `get_model()`.

### 가중치 사전 다운로드

```python
from inference import get_model

# 모델 로드(가중치를 다운로드하고 캐시함)
model = get_model(
    model_id="rfdetr-base",
    api_key="YOUR_ROBOFLOW_API_KEY"
)
print("모델 가중치가 캐시되었습니다!")
```

### 추론 실행 중

```python
from inference import get_model

# 기기 내 추론에 캐시된 가중치 사용
model = get_model(
    model_id="rfdetr-base",
    api_key="YOUR_ROBOFLOW_API_KEY"
)

results = model.infer("path/to/image.jpg")
```

자가 호스팅 Inference Server에서는 대신 HTTP를 통해 가중치를 사전 로드할 수 있습니다. 다음 참조: [모델 관리](/reference/ko/inference/inference-sdk/model-management.md).

## 모범 사례

1. **먼저 영구 캐시를 구성하세요.** 어떤 가중치도 다운로드하기 전에 `MODEL_CACHE_DIR` 를 영구 디렉터리로 가리키도록 구성하세요( `/tmp` 아님). 이는 재부팅 시 캐시된 가중치를 잃지 않도록 프로덕션 배포에서 필수적입니다.
2. **설정 중에 사전 다운로드하세요.** 배포 설정 단계에서 필요한 모든 모델 가중치를 다운로드하여 캐시되고 바로 사용할 수 있도록 하세요.
3. **Docker에서 영구 캐시를 사용하세요.** 항상 [영구 볼륨을 마운트하세요](https://docs.roboflow.com/deployment/self-hosted/inference-server/configuration/docker-configuration#persistent-model-cache) Docker 컨테이너에서 실행할 때. 컨테이너 파일 시스템에 저장된 가중치는 재시작 시 사라집니다.
4. **배포 전에 확인하세요.** 프로덕션에 배포하기 전에 모델이 올바르게 캐시되었고 캐시 디렉터리가 재부팅 간에도 유지되는지 확인하세요.
5. **모델 ID를 문서화하세요.** 애플리케이션에 필요한 모든 모델 ID와 버전의 목록을 유지해 사전 캐싱과 문제 해결을 더 쉽게 하세요.
6. **저장 공간을 고려하세요.** 모델 가중치는 클 수 있습니다(모델당 100MB\~1GB 이상). 영구 캐시 디렉터리에 충분한 디스크 공간이 있는지 확인하세요.
7. **재부팅 동작을 테스트하세요.** 가중치를 캐시한 후 시스템 재부팅 뒤에도 유지되는지 테스트하여 캐시 구성이 올바른지 확인하세요.

## 문제 해결

### 재부팅 후 가중치가 사라짐

기본 캐시 위치(`/tmp/cache`)는 재부팅 시 지워집니다. 다음에 설명된 대로 영구 캐시 디렉터리를 구성하세요 [캐시 위치](#cache-location), 또는 다음을 사용하세요 [Docker용 영구 볼륨 마운트](https://docs.roboflow.com/deployment/self-hosted/inference-server/configuration/docker-configuration#persistent-model-cache).

### 모델을 찾을 수 없음 오류

* 모델이 실제로 다운로드되었는지 확인하세요(다음으로 캐시 디렉터리를 확인: `ls -lh $MODEL_CACHE_DIR`).
* 다운로드할 때와 완전히 동일한 `model_id` 을 사용하고 있는지 확인하세요.
* 다음을 확인하세요 `MODEL_CACHE_DIR` 사용자 지정 위치를 사용하는 경우 올바르게 설정되어 있는지.

### 권한 문제

애플리케이션이 캐시 디렉터리에 대한 읽기/쓰기 권한을 가지고 있는지 확인하세요:

```bash
chmod -R 755 /path/to/cache
```