> 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 구성 옵션](/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" %}
이 변수들은 Inference 서버를 구성합니다. Roboflow CLI와 Python SDK는 다른, 더 적은 수의 변수(`ROBOFLOW_API_KEY`, `ROBOFLOW_CONFIG_DIR`, 및 기타): 다음을 참고하세요 [환경 변수](https://docs.roboflow.com/reference/environment-variables) 는 참조 섹션에 있습니다.
{% endhint %}

최근 보안 설정의 소스 및 릴리스 범위는 다음을 참고하세요 [보안 구성 마이그레이션](/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>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="/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="/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>inference-models 캐시 워치독을 활성화합니다. 0보다 크게 설정하면 워치독이 시스템이 시간이 지나며 디스크 공간을 모두 소진하지 않도록 모델 아티팩트를(가장 오래되고 가장 큰 것부터) 정리합니다. USE_INFERENCE_MODELS=True일 때만 적용됩니다.</td><td>-1</td></tr><tr><td>INFERENCE_MODELS_CACHE_WATCHDOG_INTERVAL_MINUTES</td><td>inference-models 캐시 워치독 주기의 빈도입니다. 최소값은 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초이며(더 낮은 값은 상향 고정됩니다). 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>서버가 Workflows 프로파일러 추적 정보를 클라이언트에 반환할 수 있게 합니다.</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>get_workflow_specification(...)가 반환한 Workflow 정의를 캐시하는 시간(초)입니다.</td><td>900 (15 minutes)</td></tr><tr><td>ENABLE_STREAM_API</td><td>통합 비디오 관리 API를 활성화합니다. 표준 CPU, GPU, TensorRT 이미지는 이를 True로 설정하며, JetPack 5.1.1 및 6.2.0 이미지도 마찬가지입니다. 슬림 이미지와 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="/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="/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>로컬 또는 Modal Custom Python 실행을 선택합니다. 다음을 참고하세요 <a href="/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="/deployment/ko/self-hosted/inference-server/configuration/security.md#restrict-webhook-sink-destinations">서버 보안</a>.</td><td>True</td></tr></tbody></table>

## GPU 텐서 파이프라인

호환 가능한 NVIDIA GPU에서는 Workflows가 비디오 디코딩부터 모델 추론, 출력까지 이미지 데이터를 CPU를 거치지 않고 GPU에 유지할 수 있습니다. 이렇게 하면 GPU 중심의 비디오 Workflows에서 지연 시간이 줄어듭니다. 이를 위해서는 `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 서비스 루트로 설정하세요.</td><td>API_BASE_URL의 값</td></tr><tr><td>DISABLE_VERSION_CHECK</td><td>백그라운드 스레드에서 실행되는 Inference 버전 확인을 비활성화합니다. SECURE_GATEWAY가 구성된 경우 api.github.com에 게이트웨이 뒤에서 접근할 수 없으므로, 명시적인 False를 덮어쓰고 True로 강제 설정됩니다.</td><td>False</td></tr><tr><td>SECURE_GATEWAY</td><td>다음의 주소 <a href="/deployment/ko/self-hosted/enterprise/secure-gateway.md">Roboflow Secure Gateway</a> 에어갭 배포용(기존 별칭: LICENSE_SERVER)입니다. Roboflow API 및 모델 다운로드 트래픽을 게이트웨이 프록시를 통해 라우팅하고, 버전 확인을 강제로 비활성화하며, 원격 + 호스팅이 구성된 경우 로컬 Workflow 단계 실행으로 되돌아갑니다. 다음을 참고하세요 <a href="/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="/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="/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="/deployment/ko/monitoring-and-analytics/model-monitoring.md">모델 모니터링</a>.</td><td>True</td></tr><tr><td>MODEL_MONITORING_CACHE_BACKEND</td><td>모델 모니터링 pingback 데이터의 캐시 백엔드입니다. default를 사용하면 일반 캐시 선택(REDIS_HOST가 구성되었으면 Redis, 그렇지 않으면 메모리)을 따르고, memory를 사용하면 프로세스 로컬 버퍼링을 강제하여 Redis를 inference의 핫 경로에서 제외할 수 있습니다.</td><td>default</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="/deployment/ko/self-hosted/inference-server/configuration/https.md">HTTPS를 통한 Inference 제공</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="/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>inference, Workflow 및 통합 파이프라인 요청에 대해 허용된 Workspace 슬러그입니다. 다음을 참고하세요 <a href="/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>

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