> 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/deployment/ko/self-hosted/inference-server/configuration/environment-variables.md).

# Inference Server 환경 변수

자체 호스팅 Roboflow Inference 서버를 제어하는 환경 변수 - 실행 공급자, 캐싱, 워크플로, Roboflow API 재시도, 원격 측정, HTTPS, 보안.

추론 서버의 동작은 환경 변수 집합으로 제어합니다. 모든 변수는 [`inference/core/env.py`](https://github.com/roboflow/inference/blob/main/inference/core/env.py)에 정의되어 있으며, 아래 변수는 추가 설명이 필요한 항목입니다.

다음과 같이 `-e` 를 사용해 컨테이너에 전달하세요( [자주 변경되는 설정은 Docker 구성 옵션](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/docker-configuration.md) 을 참조하세요).

```bash
docker run -it --rm -e ENV_VAR_NAME=env_var_value -p 127.0.0.1:9001:9001 roboflow/roboflow-inference-server-cpu:latest
```

{% hint style="info" %}
이 변수는 추론 서버를 구성합니다. Roboflow CLI와 Python SDK는 다른 더 적은 수의 변수(예: `ROBOFLOW_API_KEY`, `ROBOFLOW_CONFIG_DIR` 등)를 읽습니다. 자세한 내용은 참조 섹션의 [환경 변수](https://docs.roboflow.com/reference/environment-variables) 를 확인하세요.
{% endhint %}

최근 보안 설정의 소스 및 릴리스 범위는 [보안 구성 마이그레이션](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/security-migration.md#release-status).

## 실행 및 모델

<table data-search="false"><thead><tr><th>변수</th><th>설명</th><th>기본값</th></tr></thead><tbody><tr><td>ONNXRUNTIME_EXECUTION_PROVIDERS</td><td>우선순위 순서에 따른 실행 공급자 목록입니다. 플랫폼에서 공급자를 지원하지 않으면 경고가 표시됩니다.</td><td>자세한 내용은 <a href="https://github.com/roboflow/inference/blob/main/inference/core/env.py">env.py</a></td></tr><tr><td>RUNS_ON_JETSON</td><td>Inference가 Jetson 장치에서 실행되는지 여부입니다. Jetson 아키텍처용 모든 Docker 빌드에서는 True로 설정됩니다.</td><td>False</td></tr><tr><td>MODEL_VALIDATION_DISABLED</td><td>시험 추론을 건너뛰어 모델 로딩 속도를 높입니다.</td><td>False</td></tr><tr><td>MAX_CONCURRENT_INFERENCE_REQUESTS</td><td>작업자당 한 번에 처리할 최대 HTTP 요청 수입니다. 초과 요청은 대기열에서 기다립니다. 요청이 급증할 때 서버의 메모리 부족을 방지합니다. 0으로 설정하면 제한이 비활성화됩니다.</td><td>0</td></tr><tr><td>CONCURRENT_INFERENCE_REQUESTS_QUEUE_TIMEOUT</td><td>대기 중인 요청이 사용 가능한 슬롯을 기다리는 시간(초)입니다. 이 시간이 지나면 서버는 503과 <code>Retry-After: 1</code>을 응답합니다. 0으로 설정하면 한도에 도달했을 때 요청을 즉시 거부합니다.</td><td>30</td></tr><tr><td>SAM2_MAX_EMBEDDING_CACHE_SIZE</td><td>GPU 메모리에 보관할 SAM2 임베딩 수입니다. 각 임베딩은 16777216바이트를 차지합니다.</td><td>100</td></tr><tr><td>SAM2_MAX_LOGITS_CACHE_SIZE</td><td>CPU 메모리에 보관할 SAM2 로짓 수입니다. 각 로짓은 262144바이트를 차지합니다.</td><td>1000</td></tr><tr><td>DISABLE_SAM2_LOGITS_CACHE</td><td>SAM2 로짓 캐싱을 비활성화합니다. 디버깅하거나 메모리 사용량을 최소화할 때 유용하지만, 유사한 요청을 반복 처리하는 속도가 느려집니다.</td><td>False</td></tr></tbody></table>

## `inference-models` 백엔드

<table data-search="false"><thead><tr><th>변수</th><th>설명</th><th>기본값</th></tr></thead><tbody><tr><td>USE_INFERENCE_MODELS</td><td>inference-models 백엔드를 선택합니다. 이미지 설정이 이 값을 재정의할 수 있습니다.</td><td>코어 라이브러리에서는 False</td></tr><tr><td>ALLOW_INFERENCE_MODELS_DIRECTLY_ACCESS_LOCAL_PACKAGES</td><td>코드를 포함한 로컬 모델 패키지의 사용을 허용합니다. 온라인 모델 인증과 호환되지 않습니다. 자세한 내용은 <a href="https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/model-security.md">모델 패키지 보안</a>.</td><td>False</td></tr><tr><td>ALLOW_INFERENCE_MODELS_UNTRUSTED_PACKAGES</td><td>신뢰할 수 없는 것으로 분류된 다운로드 패키지를 허용합니다. 로컬에서 직접 로드하는 것과는 별개입니다. 자세한 내용은 <a href="https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/security-migration.md#model-package-trust">이미지 마이그레이션 기본값</a>.</td><td>핵심 라이브러리에서는 False이며, 이미지에 따라 다릅니다.</td></tr><tr><td>MAX_INFERENCE_MODELS_CACHE_SIZE_MB</td><td>추론 모델 캐시 감시 기능을 활성화합니다. 0보다 큰 값으로 설정하면 감시 기능이 모델 아티팩트를 정리합니다(오래되고 용량이 큰 항목부터). 이를 통해 시간이 지나면서 시스템의 디스크 공간이 부족해지는 것을 방지합니다. USE_INFERENCE_MODELS=True인 경우에만 적용됩니다.</td><td>-1</td></tr><tr><td>INFERENCE_MODELS_CACHE_WATCHDOG_INTERVAL_MINUTES</td><td>추론 모델 캐시 감시 주기입니다. 최소값은 15분입니다.</td><td>60</td></tr><tr><td>ENABLE_CUDA_MEMORY_RECLAMATION_WATCHDOG</td><td>캐시되었지만 사용되지 않는 CUDA 메모리를 torch.cuda.empty_cache()를 통해 드라이버에 주기적으로 반환하는 백그라운드 데몬을 활성화합니다. PyTorch의 캐싱 할당자는 해제된 디바이스 메모리 블록을 자체 풀에 보관하며 스스로 반환하지 않습니다. 따라서 장시간 실행되는 서버에서는 동시 또는 배치 추론의 최고 사용량이 고착되어 예약된 VRAM이 계속 늘어납니다. 이 감시 기능은 고정된 주기로 남는 메모리를 회수하며, 현재 사용 중인 할당에는 영향을 주지 않습니다. 실제로 동시 사용량이 과도하게 높아 발생하는 OOM은 방지하지 않습니다. CUDA에서 USE_INFERENCE_MODELS=True인 경우에만 의미가 있습니다.</td><td>False</td></tr><tr><td>CUDA_MEMORY_RECLAMATION_WATCHDOG_INTERVAL_SECONDS</td><td>CUDA 메모리 감시 기능의 회수 주기입니다. 최소값은 5초이며, 더 낮은 값은 5초로 올려 적용합니다. ENABLE_CUDA_MEMORY_RECLAMATION_WATCHDOG=True인 경우에만 적용됩니다.</td><td>300</td></tr></tbody></table>

## 워크플로 및 비디오

<table data-search="false"><thead><tr><th>변수</th><th>설명</th><th>기본값</th></tr></thead><tbody><tr><td>ENABLE_WORKFLOWS_PROFILING</td><td>서버가 워크플로 프로파일러 추적 정보를 클라이언트에 반환하도록 허용합니다.</td><td>False</td></tr><tr><td>WORKFLOWS_PROFILER_BUFFER_SIZE</td><td>프로파일러 버퍼 크기입니다. 버퍼에 추적되는 연속된 Workflows Execution Engine run(...) 호출 횟수를 뜻합니다.</td><td>64</td></tr><tr><td>WORKFLOWS_DEFINITION_CACHE_EXPIRY</td><td>워크플로 정의를 메모리 또는 Redis에 캐시할 시간(초)입니다. 파일 캐시는 만료되지 않습니다.</td><td>900(15분)</td></tr><tr><td>ENABLE_STREAM_API</td><td>통합 비디오 관리 API를 활성화합니다. 표준 CPU, GPU, TensorRT 이미지와 JetPack 5.1.1 및 6.2.0 이미지에서는 이 값이 True로 설정되어 있습니다. slim 이미지와 JetPack 6.0.0 및 7.1.0 이미지에서는 설정되어 있지 않습니다. 고정한 이미지를 확인하세요.</td><td>핵심 라이브러리에서는 False이며, 나열된 이미지에서는 True입니다.</td></tr><tr><td>STREAM_API_PRELOADED_PROCESSES</td><td>유휴 상태로 준비해 둘 비디오 워커 수입니다. GPU에서 워커 시작 시간을 줄여 줍니다. 이미지에서 이 값을 재정의할 수 있습니다.</td><td>핵심 라이브러리에서는 0</td></tr><tr><td>STREAM_MANAGER_MAX_ACTIVE_PIPELINES</td><td>유휴 워커를 포함해 관리할 파이프라인 프로세스의 상한입니다. 상한을 초과해 새 워커가 필요한 요청은 거부됩니다. STREAM_API_PRELOADED_PROCESSES 값이 더 크면 해당 값까지 상한이 높아집니다. 자세한 내용은 <a href="https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/video-configuration.md">비디오 구성</a>.</td><td>8</td></tr><tr><td>STREAM_MANAGER_MAX_RAM_MB</td><td>스트림 관리자와 워커에 할당되는 총 RAM 예산입니다. 새 워커를 추가했을 때 예상 총량이 이 값을 초과하면 추가가 거부됩니다. 이는 추정치에 기반한 보호 장치이지, 엄격한 메모리 제한은 아닙니다.</td><td>설정되지 않음(RAM 상한 없음)</td></tr><tr><td>ALLOW_UNSAFE_GSTREAMER_PIPELINES</td><td>런타임 보안 강화가 예정된 빌드에서 신뢰할 수 있는 원시 파이프라인에 대한 미디어 참조 검증을 우회합니다. 자세한 내용은 <a href="https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/security-migration.md#video-source-validation">마이그레이션 범위</a>.</td><td>해당 빌드에서는 False</td></tr><tr><td>ALLOW_CUSTOM_PYTHON_EXECUTION_IN_WORKFLOWS</td><td>Custom Python을 로컬에서 실행하도록 허용합니다. Modal 실행을 비활성화하지는 않습니다.</td><td>True</td></tr><tr><td>WORKFLOWS_CUSTOM_PYTHON_EXECUTION_MODE</td><td>Custom Python을 로컬에서 실행할지 Modal에서 실행할지 선택합니다. 자세한 내용은 <a href="https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/security-migration.md#offline-custom-python">오프라인 마이그레이션 동작</a>.</td><td>로컬</td></tr><tr><td>ALLOW_WEBHOOK_WORKFLOWS_SINK_TO_NON_GLOBAL_ADDRESSES</td><td>Webhook Sink가 루프백, 사설, 링크 로컬 및 기타 전역이 아닌 주소에 연결하도록 허용합니다. 신뢰할 수 없는 호출자가 웹훅 대상을 선택할 수 있는 경우 False로 설정하세요. 값에 관계없이 리디렉션과 HTTP(S) 프록시는 거부됩니다. 자세한 내용은 <a href="https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/security.md#restrict-webhook-sink-destinations">서버 보안</a>.</td><td>True</td></tr></tbody></table>

## GPU 텐서 파이프라인

성능이 충분한 NVIDIA GPU에서는 워크플로가 비디오 디코딩부터 모델 추론, 출력까지 이미지 데이터를 CPU로 옮기지 않고 GPU에 유지할 수 있습니다. 이를 통해 GPU를 많이 사용하는 비디오 워크플로의 지연 시간을 줄입니다. 사용하려면 `USE_INFERENCE_MODELS=True`, 컴퓨트 기능 7.5 이상을 지원하는 GPU(T4, RTX 20 시리즈 이상 등. V100은 해당하지 않음), 그리고 `onnx.gpu` 또는 Jetson Docker 이미지입니다. 호환되는 GPU와 이미지가 없으면 Inference는 일반 CPU 기반 실행으로 대체됩니다.

<table data-search="false"><thead><tr><th>변수</th><th>설명</th><th>기본값</th></tr></thead><tbody><tr><td>ENABLE_TENSOR_DATA_REPRESENTATION</td><td>GPU 텐서 파이프라인을 활성화합니다. GPU 상주 Workflows 실행과 하드웨어 가속(NVDEC) 비디오 디코딩이 포함됩니다.</td><td>False</td></tr><tr><td>WORKFLOWS_IMAGE_TENSOR_DEVICE</td><td>텐서 파이프라인이 활성화되었을 때 Workflow 텐서가 배치되는 Torch 장치입니다.</td><td>사용 가능하면 cuda, 아니면 cpu</td></tr><tr><td>VIDEO_SOURCE_BUFFER_SIZE</td><td>비디오 소스당 버퍼링되는 디코딩된 프레임 수입니다.</td><td>텐서 파이프라인이 활성화된 경우 8, 그렇지 않으면 64</td></tr><tr><td>VIDEO_SOURCE_ADAPTIVE_BACKPRESSURE</td><td>예상 프레임 속도가 아닌 버퍼 상태를 기준으로 버퍼링된 프레임을 삭제합니다.</td><td>ENABLE_TENSOR_DATA_REPRESENTATION과 일치합니다.</td></tr><tr><td>WORKFLOWS_ENFORCE_DENSE_INSTANCE_MASKS</td><td>텐서 파이프라인 모델에서 RLE 인코딩된 마스크 대신 밀집 인스턴스 분할 마스크를 반환합니다.</td><td>False</td></tr><tr><td>WORKFLOWS_SAM_VIDEO_MASK_REPRESENTATION</td><td>텐서 파이프라인의 SAM 비디오 추적 블록에서 사용하는 마스크 형식(rle 또는 dense)입니다.</td><td>rle</td></tr><tr><td>DISABLE_GSTREAMER_VIDEO_SOURCES</td><td>GStreamer 기반 비디오 소스를 비활성화하고 표준 CPU 디코딩을 사용합니다.</td><td>False</td></tr></tbody></table>

## Roboflow API 연결

<table data-search="false"><thead><tr><th>변수</th><th>설명</th><th>기본값</th></tr></thead><tbody><tr><td>TRANSIENT_ROBOFLOW_API_ERRORS</td><td>재시도할 Roboflow API의 HTTP 코드 목록입니다. 쉼표로 구분하며 GET 엔드포인트에만 적용됩니다.</td><td>설정되지 않음</td></tr><tr><td>TRANSIENT_ROBOFLOW_API_ERRORS_RETRIES</td><td>일시적 오류(연결 오류 및 일시적 HTTP 코드)를 재시도할 횟수입니다. GET 엔드포인트에만 적용됩니다.</td><td>3</td></tr><tr><td>TRANSIENT_ROBOFLOW_API_ERRORS_RETRY_INTERVAL</td><td>일시적 Roboflow API 오류에 대한 재시도 사이의 지연 시간입니다. GET 엔드포인트에만 적용됩니다.</td><td>3</td></tr><tr><td>RETRY_CONNECTION_ERRORS_TO_ROBOFLOW_API</td><td>Roboflow API 연결 오류를 재시도할지 여부입니다. GET 엔드포인트에만 적용됩니다.</td><td>False</td></tr><tr><td>ROBOFLOW_API_REQUEST_TIMEOUT</td><td>Roboflow API 요청의 제한 시간(초, 정수)입니다.</td><td>설정되지 않음</td></tr><tr><td>API_PROXY_BASE_URL</td><td>apiproxy/* 엔드포인트에 대한 Roboflow API 프록시 요청에 사용하는 기본 URL입니다. 장시간 실행되는 서드파티 프록시 호출에서 Firebase Hosting의 시간 초과를 피하려면 직접 연결할 heavy-API Cloud Run 서비스의 루트 URL로 설정하세요.</td><td>API_BASE_URL 값</td></tr><tr><td>DISABLE_VERSION_CHECK</td><td>백그라운드 스레드에서 실행되는 Inference 버전 확인을 비활성화합니다. SECURE_GATEWAY가 구성된 경우 명시적으로 False로 설정했더라도 True로 강제 설정됩니다. 게이트웨이 뒤에서는 api.github.com에 연결할 수 없기 때문입니다.</td><td>False</td></tr><tr><td>SECURE_GATEWAY</td><td>주소: <a href="https://docs.roboflow.com/deployment/ko/self-hosted/enterprise/secure-gateway.md">Roboflow Secure Gateway</a> 에어갭 배포용(이전 별칭: LICENSE_SERVER)입니다. Roboflow API 및 모델 다운로드 트래픽을 게이트웨이 프록시를 통해 라우팅하고, 버전 확인을 강제로 비활성화하며, 원격 실행과 호스팅 실행이 함께 구성된 경우 로컬 Workflow 단계 실행으로 대체합니다. 자세한 내용은 <a href="https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/docker-configuration.md#secure-gateway">Docker 구성 옵션</a>.</td><td>설정되지 않음</td></tr></tbody></table>

## 모니터링 및 텔레메트리

<table data-search="false"><thead><tr><th>변수</th><th>설명</th><th>기본값</th></tr></thead><tbody><tr><td>ENABLE_PROMETHEUS</td><td>Prometheus /metrics 엔드포인트를 활성화합니다. 자세한 내용은 <a href="https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/telemetry.md">텔레메트리</a>.</td><td>Docker Hub 이미지의 경우 True</td></tr><tr><td>DOCKER_SOCKET_PATH</td><td>컨테이너에 마운트된 Docker 데몬 소켓의 경로입니다. 지정하면 데몬 소켓에서 Docker 컨테이너 통계를 폴링할 수 있습니다. 자세한 내용은 <a href="https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/telemetry.md#docker-container-metrics">텔레메트리</a>.</td><td>설정되지 않음</td></tr><tr><td>METRICS_ENABLED</td><td>Roboflow <a href="https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/model-monitoring.md">모델 모니터링을 제어합니다</a>.</td><td>True</td></tr><tr><td>MODEL_MONITORING_CACHE_BACKEND</td><td>모델 모니터링 핑백 데이터의 캐시 백엔드입니다. 일반적인 캐시 선택을 따르려면 default를 사용하세요(REDIS_HOST가 설정된 경우 Redis, 그렇지 않으면 메모리). memory를 사용하면 프로세스 내 버퍼링을 강제하여 추론 핫 경로에서 Redis를 제외합니다.</td><td>기본값</td></tr></tbody></table>

## HTTPS

<table data-search="false"><thead><tr><th>변수</th><th>설명</th><th>기본값</th></tr></thead><tbody><tr><td>ENABLE_HTTPS</td><td>Inference 서버의 HTTPS를 활성화하거나 비활성화합니다. True인 경우 서버는 SSL_CERTFILE 및 SSL_KEYFILE을 읽고 TLS를 통해 트래픽을 제공합니다. 자세한 내용은 <a href="https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/https.md">HTTPS를 통한 추론 제공</a>.</td><td>False</td></tr><tr><td>SSL_CERTFILE</td><td>ENABLE_HTTPS=True일 때 제공되는 PEM 인코딩 TLS 인증서의 경로입니다.</td><td>/etc/inference/certs/server.crt</td></tr><tr><td>SSL_KEYFILE</td><td>SSL_CERTFILE에 해당하는 PEM 인코딩 TLS 개인 키의 경로입니다.</td><td>/etc/inference/certs/server.key</td></tr><tr><td>SSL_KEYFILE_PASSWORD</td><td>Uvicorn용 암호화된 키의 암호 문구입니다. 병렬 Gunicorn 실행기에서는 지원되지 않습니다.</td><td>설정되지 않음</td></tr><tr><td>SSL_CA_CERTS</td><td>HTTPS용 클라이언트 CA 번들입니다. 자세한 내용은 <a href="https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/https.md#mutual-tls">mTLS 적용 및 릴리스 범위</a>.</td><td>설정되지 않음</td></tr></tbody></table>

## 인증 및 입력 보안

<table data-search="false"><thead><tr><th>변수</th><th>설명</th><th>기본값</th></tr></thead><tbody><tr><td>WORKSPACES_WHITELISTED_FOR_LOCAL_DEPLOYMENT</td><td>추론, Workflow 및 통합 파이프라인 요청에 허용되는 Workspace 슬러그입니다. 자세한 내용은 <a href="https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/security.md#enforce-authentication">인증 및 예외</a>.</td><td>설정되지 않음</td></tr><tr><td>MODELS_CACHE_AUTH_ENABLED</td><td>호출자가 Roboflow 모델에 액세스할 수 있는지 온라인으로 확인합니다. 이 모드에서는 로컬 패키지를 직접 로드하는 요청을 거부합니다.</td><td>False</td></tr><tr><td>ALLOW_OFFLINE_MODEL_CACHE_AUTH_BYPASS</td><td>오프라인 모드와 모델 캐시 인증을 모두 활성화한 경우 명시적인 인증 우회 설정이 필요합니다. 신뢰할 수 있는 단일 테넌트 배포에서만 사용하세요.</td><td>False</td></tr></tbody></table>

사용자 지정 Python 실행 및 URL 이미지 가져오기를 제어하는 변수(`ALLOW_CUSTOM_PYTHON_EXECUTION_IN_WORKFLOWS`, `ALLOW_URL_INPUT`, `ALLOW_URL_TO_NON_GLOBAL_ADDRESSES`, `VALIDATE_IMAGE_URL_REDIRECTS`등)는 다음 문서에 설명되어 있습니다. [자체 호스팅 서버 보안](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/security.md) 및 [허용되는 입력 형식](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/input-formats.md).
