> 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/production-checklist.md).

# 프로덕션 준비 체크리스트

Roboflow 배포를 위한 프로덕션 준비 - HTTP 오류 처리 및 재시도, 타임아웃과 콜드 스타트, 속도 제한, 전용 배포 복제본 크기 조정.

을 [배포 옵션을 선택한](https://docs.roboflow.com/deployment/ko/choosing-a-deployment.md) 후에는 이 페이지를 참고해 프로덕션 트래픽을 처리하기 전에 통합을 강화하세요. 여기에서는 오류 처리와 재시도, 시간 초과와 콜드 스타트, 속도 제한, 그리고 다음 항목의 복제본 크기 조정을 다룹니다. [전용 배포](https://docs.roboflow.com/deployment/ko/roboflow-cloud/dedicated-deployments.md).

## Cloud Streaming

Cloud Streaming을 [지속적으로 사용하기 전에](https://docs.roboflow.com/deployment/ko/roboflow-cloud/cloud-streaming.md) :

* 의도한 Workflow, 모델, 입력 및 이미지 출력으로 소스 연결을 확인하고 처리 통계가 계속 증가하는지 검증하세요.
* 검토하세요: [처리 속도 및 크레딧 동작](https://docs.roboflow.com/deployment/ko/roboflow-cloud/cloud-streaming/pricing-and-limits.md). 미리보기와 테스트에서 크레딧이 소모될 수 있으며, 페이지를 닫아도 배포가 중지되지는 않습니다.
* 제어된 대상에서 다음을 테스트하세요: [싱크 필터, 페이로드 및 쿨다운](https://docs.roboflow.com/deployment/ko/roboflow-cloud/cloud-streaming/consume-results.md#send-results-with-a-workflow-sink). 저장된 초안뿐 아니라 실행 중인 스냅샷에서 싱크가 활성화되어 있는지 확인하세요.
* 재시작 또는 복구 중에 공백과 상태 초기화가 발생할 수 있으므로 이에 대비하세요. 다운스트림 수신기는 중복 이벤트와 전송 실패를 허용하도록 설계하세요.
* 필요한 경우 [오프라인 알림](https://docs.roboflow.com/deployment/ko/roboflow-cloud/cloud-streaming/manage-and-monitor.md#offline-notifications) 을 구성하고, 알림이 커넥터에만 제공되는 조건과 Workspace 전체에 적용되는 제한을 파악하세요.
* 재생 권한 부여 정보를 로그에 남기지 말고 필요한 경우에만 갱신하세요. 명시적 중지 또는 API 취소가 최종 상태에 도달하는지 확인하세요.

## 셀프 호스팅 서버 액세스

셀프 호스팅 배포의 경우 원격 클라이언트를 허용하기 전에 [네트워크 액세스, 인증 및 관측 가능성](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/security.md) 을 확인하세요. CLI 또는 서버 이미지 업그레이드 시 [보안 구성 마이그레이션](https://docs.roboflow.com/deployment/ko/self-hosted/inference-server/configuration/security-migration.md) 을 검토하세요.

## HTTP 오류 및 재시도

Roboflow의 추론 및 관리 API는 표준 HTTP 상태 코드를 사용합니다. REST 상태 코드, SDK 예외 및 CLI 종료 코드를 아우르는 전체 도구 간 표는 [오류 및 상태 코드](https://docs.roboflow.com/reference/errors-and-status-codes)에 있습니다. 프로덕션에서 지켜야 할 핵심 원칙은 실제로 재시도할 수 있는 항목만 재시도하는 것입니다.

<table data-search="false"><thead><tr><th>상태</th><th>재시도?</th><th>안내</th></tr></thead><tbody><tr><td>200 / 204</td><td>-</td><td>성공입니다.</td></tr><tr><td>400</td><td>아니요</td><td>잘못된 요청입니다. 페이로드를 수정하세요. 재시도해도 같은 잘못된 요청이 전송됩니다.</td></tr><tr><td>401 / 403</td><td>아니요</td><td>인증 또는 액세스 실패입니다. 재시도해도 키가 유효해지지 않습니다. API 키와 해당 키의 범위를 확인하세요.</td></tr><tr><td>402 / 423</td><td>아니요</td><td>요금제 제한, 할당량 도달 또는 결제 일시 중지입니다. 루프에서 재시도하지 말고 <a href="https://roboflow.com/pricing">결제</a> 문제를 해결하세요.</td></tr><tr><td>404</td><td>아니요</td><td>리소스가 존재하지 않거나 해당 키로 볼 수 없습니다.</td></tr><tr><td>429</td><td>예</td><td>요청 제한에 걸렸습니다. 대기 시간을 늘린 뒤 지수 백오프를 적용해 재시도하세요(자세한 내용은 <a href="#rate-limits">속도 제한</a>).</td></tr><tr><td>5xx</td><td>예</td><td>일시적인 서버 오류입니다. 백오프를 적용해 안전하게 재시도할 수 있습니다.</td></tr></tbody></table>

**백오프 패턴.** 그리고 `429` 및 `5xx`, 지수 백오프와 지터를 적용해 재시도하고(예: 1초, 2초, 4초, 8초에 임의의 오프셋을 더함), 시도 횟수에 상한을 두세요. 절대 자동으로 재시도하지 `401`/`403`/`404`/`400` 말고, 해당 오류를 애플리케이션에 전달하세요.

다음을 호출할 때 [전용 배포](https://docs.roboflow.com/deployment/ko/roboflow-cloud/dedicated-deployments.md#http-api) 관리 서비스(`https://roboflow.cloud`), 응답 코드를 명시적으로 확인하세요. a `200` 는 JSON 본문을 반환하고, 그 외의 코드는 오류 메시지를 문자열로 반환합니다.

## 시간 초과 및 콜드 스타트

다음 [서버리스 클라우드 API](https://docs.roboflow.com/deployment/ko/roboflow-cloud/serverless-api.md) 는 필요할 때 모델을 로드합니다. 서버에 이미 상주하지 않는 모델에 대한 첫 요청("워밍업")은 몇 초가 걸릴 수 있으며, 한동안 유휴 상태였던 모델(예: 추론 간격이 약 10분인 경우)은 언로드되어 다음 호출 때 다시 로드해야 할 수 있습니다.

* **클라이언트 시간 제한을 넉넉하게 설정하세요.** 콜드 스타트 때 작동할 정도로 짧은 클라이언트 시간 제한을 설정하면, 그렇지 않았다면 성공했을 요청도 실패합니다. 첫 요청과 유휴 시간 이후의 워밍업을 고려해 여유 시간을 확보하세요.
* **모델을 미리 준비하세요.** 지연 시간을 예측 가능하게 유지하는 것이 중요하다면, 지연 시간에 민감한 트래픽을 보내기 전에 워밍업 요청을 보내 모델이 이미 캐시된 상태가 되도록 하세요.
* **응답 헤더를 확인하세요.** 서버리스 응답에는 `x-model-cold-start` (이 요청에서 로드 비용이 발생했는지 여부)와 `x-processing-time`. 콜드 스타트 빈도와 지연 시간을 모니터링하는 데 사용하세요. 둘 다 요금에 영향을 주지 않습니다. 이미지당 요금은 [서버리스 요금](https://docs.roboflow.com/deployment/ko/roboflow-cloud/serverless-api/model-pricing.md) 에서 확인하세요.
* **업로드 크기를 제한 이하로 유지하세요.** Serverless Cloud API는 최대 **20 MB**까지 파일 업로드를 지원하며, 이보다 큰 이미지는 거부됩니다. 전송 전에 이미지 크기를 줄이세요(Python SDK는 이를 자동으로 처리합니다). 어차피 이미지는 모델의 입력 크기에 맞게 조정되므로 대개 정확도에 영향을 주지 않습니다. 일괄 처리에도 이미지당 동일한 20 MB 제한이 적용됩니다.

콜드 스타트 없이 지속적으로 낮은 지연 시간을 유지하려면 [전용 배포](https://docs.roboflow.com/deployment/ko/roboflow-cloud/dedicated-deployments.md) 또는 [자체 호스팅 추론](https://docs.roboflow.com/deployment/ko/self-hosted/self-hosted.md) 공유 서버리스 엔드포인트 대신 사용하세요.

## 요청 한도

* **서버리스 클라우드 API.** 에서 `429`, 요청 속도를 늦추고 지수 백오프를 적용해 재시도하세요. 한도에 계속 도달하거나 더 높은 처리량이 필요하면 엔터프라이즈 지원 담당자 또는 [Roboflow 포럼](https://discuss.roboflow.com), 또는 [전용 배포](https://docs.roboflow.com/deployment/ko/roboflow-cloud/dedicated-deployments.md).
* **Deployment Manager API.** 엣지 기기 관리 엔드포인트는 엔드포인트별 명시적 제한을 적용하며, 제한을 초과하면 다음을 반환합니다. `429` 제한을 초과하면 반환합니다. 예를 들어 기기 로그는 다음으로 제한됩니다. **IP당 분당 5회 요청** 및 **전역적으로 분당 50회**, 원격 측정 데이터 조회는 다음으로 제한됩니다. **기기당 분당 60회 요청** 10초 동안 최대 10회 요청을 버스트로 허용합니다. 자세한 내용은 다음을 참조하세요. [Deployment Manager API](https://docs.roboflow.com/deployment/ko/self-hosted/enterprise/deployment-manager.md#errors) 통합에 폴링을 구현하기 전에 정확한 제한과 오류 형식을 확인하세요.

사용 중인 경로에 대해 문서화된 수치가 없는 경우, `429` 고정된 한도를 가정하지 말고 속도를 늦춰야 한다는 신호로 간주하고 [지원팀에 문의하세요](https://roboflow.com/sales) 더 높은 한도가 필요한 경우.

## Dedicated Deployment 복제본 크기 설정

을 생성할 때 [Dedicated Deployment](https://docs.roboflow.com/deployment/ko/roboflow-cloud/dedicated-deployments.md#http-api)에서 `min_replicas` 와 `max_replicas` 를 설정할 수 있습니다(둘 다 기본값은 `1`):

* **`min_replicas`** 는 계속 실행 상태로 유지되는 복제본 수입니다. 최솟값을 높이면 상시 가동 용량이 늘어나는 대신, 트래픽이 급증할 때 콜드 스타트 지연 시간이 줄어듭니다.
* **`max_replicas`** 는 부하가 증가할 때 배포가 확장될 수 있는 최대 범위를 제한합니다. 피크 처리량을 높이려면 이 값을 늘리세요.

트래픽이 안정적인 경우에는 `min_replicas` 와 `max_replicas` 를 `1` 로 설정하는 것이 가장 간단한 시작점입니다. 단일 복제본이 피크 부하를 감당하지 못하면 `max_replicas` 를 늘리고, 한동안 요청이 없다가 들어온 첫 요청의 응답이 너무 느리면 `min_replicas` 를 늘리세요.

### 자동 일시 중지와의 상호 작용

Dedicated Deployment는 **일정 시간 동안 활동이 없으면 자동으로 일시 중지됩니다** (일시 중지 시간은 `dev-cpu` 및 `dev-gpu` 유형의 경우 1시간으로 고정됨). API 키를 사용해 요청을 보내면 다시 시작됩니다. 일시 중지된 배포에는 실행 중인 복제본이 없으므로, 배포를 다시 시작하는 요청에는 재개 지연 시간이 발생합니다.

* 항상 준비된 상태여야 하는 프로덕션 트래픽에는 **지속 실행 `prod-cpu` / `prod-gpu`** 유형을 사용하세요.
* 임시 `dev-cpu` / `dev-gpu` 유형은 테스트와 프로토타이핑에 사용하세요. 이 유형은 몇 시간 후 자동으로 삭제되기도 합니다.
* 가동 시간이 아니라 요청 수를 기준으로 과금하거나, 사용자 지정 일시 중지/복제본 정책이 필요하다면 [영업팀에 문의하세요](https://roboflow.com/sales).

## 서비스를 시작하기 전에

* 모든 아웃바운드 호출을 재시도 대상으로 처리하며, `429` 및 `5xx` 오류만 백오프를 적용해 재시도합니다.
* 클라이언트 시간 제한은 서버리스 콜드 스타트도 충분히 감당할 수 있도록 설정되어 있습니다.
* 이미지는 20MB 업로드 제한을 넘지 않도록 크기가 조정됩니다.
* API 키에는 필요한 최소한의 [범위](https://docs.roboflow.com/reference/authentication/authentication/scoped-api-keys) 만 사용하며, 하드코딩하지 않고 비밀 정보로 저장합니다.
* 전용 배포의 경우, `min_replicas` / `max_replicas` 를 트래픽에 맞게 설정하고 상시 트래픽에는 `prod-*` 유형을 선택했습니다.
* 배포를 모니터링하고( [모델 모니터링](https://docs.roboflow.com/deployment/ko/monitoring-and-analytics/model-monitoring.md) ), 오류율 및 지연 시간 악화에 대한 알림을 설정합니다.
