> 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).

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

일단 [배포 옵션을 선택한 후](/deployment/ko/choosing-a-deployment.md), 프로덕션 트래픽을 처리하기 전에 이 페이지를 사용해 통합을 강화하세요. 여기에는 오류 처리와 재시도, 타임아웃과 콜드 스타트, 속도 제한, 그리고 [전용 배포](/deployment/ko/roboflow-cloud/dedicated-deployments.md).

## HTTP 오류 및 재시도

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

| 상태            | 재시도? | 지침                                                                                                     |
| ------------- | ---- | ------------------------------------------------------------------------------------------------------ |
| `200` / `204` | -    | 성공입니다.                                                                                                 |
| `400`         | 아니요  | 잘못된 요청 - 페이로드를 수정하세요. 재시도하면 동일한 잘못된 요청이 전송됩니다.                                                         |
| `401` / `403` | 아니요  | 인증 또는 액세스 실패입니다. 재시도해도 키가 유효해지지 않습니다. API 키와 해당 스코프를 확인하세요.                                            |
| `402` / `423` | 아니요  | 요금제 제한, 할당량 도달 또는 결제 일시중지입니다. 다음에서 해결하세요: [결제](https://roboflow.com/pricing) 쪽에서 해결하고, 루프에서 재시도하지 마세요. |
| `404`         | 아니요  | 리소스가 존재하지 않거나 키에 보이지 않습니다.                                                                             |
| `429`         | 예    | 속도 제한에 걸렸습니다. 지수 백오프로 대기한 후 재시도하세요(참조: [속도 제한](#rate-limits)).                                         |
| `5xx`         | 예    | 일시적인 서버 오류입니다. 백오프로 재시도해도 안전합니다.                                                                       |

**백오프 패턴.** 에 대해 `429` 그리고 `5xx`, 지수 백오프와 지터를 사용해 재시도하세요(예: 1초, 2초, 4초, 8초에 무작위 오프셋 추가). 시도 횟수에는 상한을 두세요. 절대로 `401`/`403`/`404`/`400` 자동으로는 재시도하지 마세요 - 대신 애플리케이션에 노출하세요.

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

## 타임아웃과 콜드 스타트

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

* **클라이언트 타임아웃은 넉넉하게 설정하세요.** 콜드 스타트에서 걸릴 정도로 짧은 클라이언트 타임아웃은 원래는 성공했을 요청도 실패시킵니다. 첫 요청과 유휴 기간 이후의 요청을 위해 워밍업 여유 시간을 두세요.
* **모델을 예열하세요.** 예측 가능한 지연 시간이 중요하다면, 지연 시간에 민감한 트래픽 전에 워밍업 요청을 보내 모델이 이미 캐시되도록 하세요.
* **응답 헤더를 확인하세요.** Serverless 응답에는 `x-model-cold-start` (이번 요청이 로드 비용을 발생시켰는지 여부) 및 `x-processing-time`이 포함됩니다. 이를 사용해 콜드 스타트 빈도와 처리 시간을 모니터링하세요. 다음을 참조하세요: [Serverless 요금](/deployment/ko/roboflow-cloud/serverless-api/pricing.md) 에서 이러한 헤더가 결제에 어떻게 반영되는지 확인하세요.
* **업로드는 제한 이하로 유지하세요.** Serverless Cloud API는 최대 **20 MB**크기의 파일 업로드를 허용합니다. 더 큰 이미지는 거부됩니다. 전송 전에 이미지를 축소하세요(Python SDK는 이를 자동으로 수행합니다). 이미지는 어차피 모델 입력 크기에 맞게 리사이즈되므로 정확도에 보통 영향을 주지 않습니다. Batch Processing도 이미지당 동일한 20 MB 제한을 적용합니다.

콜드 스타트 없이 지속적으로 낮은 지연 시간을 원한다면 [전용 배포](/deployment/ko/roboflow-cloud/dedicated-deployments.md) 또는 [Self-Hosted Inference](/deployment/ko/self-hosted/self-hosted.md) 공유 Serverless 엔드포인트 대신 사용하세요.

## 속도 제한

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

경로에 대해 문서화된 수치가 없다면, `429` 를 고정 예산으로 가정하지 말고 물러서라는 신호로 보세요. 그리고 [지원팀에 문의하세요](https://roboflow.com/sales) 더 높은 제한이 필요하다면.

## 전용 배포 레플리카 크기 조정

다음을 생성할 때 [전용 배포](/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` 한동안 조용했던 뒤의 첫 요청이 너무 느릴 때.

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

전용 배포 **비활성 기간 이후 자동 일시중지** - 다음의 경우 1시간으로 고정됨: `dev-cpu` 그리고 `dev-gpu` 유형 - API 키로 요청을 보내면 재개됩니다. 일시중지된 배포는 레플리카를 서비스하지 않으므로, 이를 재개하는 요청은 재개 지연 시간을 감수하게 됩니다.

* 다음을 사용하세요: **지속형 `prod-cpu` / `prod-gpu`** 항상 준비되어 있어야 하는 프로덕션 트래픽에는 유형을 사용하세요.
* 일시적 `dev-cpu` / `dev-gpu` 유형은 테스트와 프로토타이핑에 남겨 두세요 - 또한 몇 시간 후 자동으로 삭제됩니다.
* 가동 시간 대신 요청 수 기준의 과금이나 사용자 지정 일시중지/레플리카 정책이 필요하다면, [영업팀에 문의하세요](https://roboflow.com/sales).

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

* 재시도는 모든 외부 호출을 감싸며, 다음만 재시도합니다: `429` 그리고 `5xx` 백오프와 함께.
* 클라이언트 타임아웃은 Serverless 콜드 스타트를 감안할 만큼 넉넉합니다.
* 이미지는 20 MB 업로드 제한 이하가 되도록 축소됩니다.
* API 키는 필요한 최소 [스코프](https://docs.roboflow.com/reference/authentication/authentication/scoped-api-keys) 를 사용하고, 하드코딩하지 않고 비밀 값으로 저장됩니다.
* 전용 배포의 경우, `min_replicas` / `max_replicas` 는 부하에 맞게 크기가 조정되어 있고, 다음을 선택했습니다: `prod-*` 유형은 항상 켜져 있는 트래픽용입니다.
* 배포를 모니터링합니다 - 다음을 참조하세요: [모델 모니터링](/deployment/ko/monitoring-and-analytics/model-monitoring.md) - 그리고 오류율 및 지연 시간 회귀에 대해 경고를 설정하세요.