> 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를 배포하면 모델 가중치가 다운로드되어 추론이 로컬에서 실행되는 장치에 저장됩니다. 이 페이지에서는 `inference` 패키지가 이러한 가중치를 다운로드하고 캐시하는 방법을 설명합니다.

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

## 개요

특정 모델로 처음 추론을 실행할 때 모델 가중치가 자동으로 다운로드됩니다. 가중치는 장치에 로컬로 캐시되며 모든 추론은 클라우드가 아닌 장치에서 수행됩니다.

작동 방식:

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

이 방식은 자체 호스팅 Inference와 기본 Python API에 적용됩니다.

{% hint style="warning" %}
**기본 캐시 위치.** 기본적으로 모델 가중치는 `/tmp/cache`에 저장되며, 이 디렉터리는 **호스트 정리 정책에 따라 삭제될 수 있습니다**. 프로덕션 배포 또는 재부팅 후에도 가중치를 유지해야 하는 경우에는 영구 볼륨을 사용하거나 다음 환경 변수를 사용해 영구 캐시 디렉터리를 구성하세요: `MODEL_CACHE_DIR` (아래의 [캐시 위치](#cache-location) 참조).
{% endhint %}

{% hint style="info" %}
**엔터프라이즈 오프라인 모드.** 완전히 연결이 끊긴 상태로 운영해야 하는 엔터프라이즈 배포의 경우 다음을 참조하세요: [오프라인 모드](https://docs.roboflow.com/deployment/self-hosted/enterprise/offline-mode). 이 페이지에서는 사용량 추적, 결제 및 Workflow 업데이트를 위해 연결을 유지하면서 모델 가중치를 다운로드하고 캐시하는 방법을 설명합니다.
{% endhint %}

## 캐시 위치

기본적으로 모델 가중치는 `/tmp/cache`에 캐시됩니다. 호스트 정리 정책에 따라 이 디렉터리가 삭제될 수 있습니다. Docker에서는 이 경로에 영구 볼륨을 마운트하면 컨테이너를 교체해도 캐시가 유지됩니다.

프로덕션 배포 또는 재부팅 후에도 가중치를 유지해야 하는 경우 영구 볼륨을 마운트하거나 다음 환경 변수를 사용해 영구 캐시 디렉터리를 구성하세요: `MODEL_CACHE_DIR` Inference를 가져오기 전에 환경 변수를 설정합니다:

```python
import os
# Set to a persistent directory (not /tmp)
os.environ["MODEL_CACHE_DIR"] = "/home/user/.roboflow/cache"

from inference import get_model
# ... rest of your code
```

또는 시스템 전체에 설정합니다:

```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](https://docs.roboflow.com/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("Model weights cached!")
```

### 추론 실행

```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를 통해 가중치를 미리 로드할 수 있습니다. 자세한 내용은 다음을 참조하세요. [모델 관리](https://docs.roboflow.com/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
```
