> 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/roboflow-cloud/batch-processing/troubleshooting.md).

# 문제 해결

타임아웃, SAHI 성능, OOM 오류를 포함한 일반적인 배치 처리 문제를 해결합니다.

이 페이지에는 Batch Processing의 알려진 문제, 제한 사항 및 해결 방법이 나와 있습니다. 여기에 나열되지 않은 문제가 발생하면 다음 [지원 채널](https://github.com/roboflow/inference/issues).

## 알려진 제한 사항

* 환경 변수 및 로컬 저장소에 액세스해야 하는 특정 Workflow 블록(File Sink 및 Environment Secret Store 등)은 차단되며 실행되지 않습니다.
* 이 서비스는 다음을 정의하는 Workflow에서만 작동합니다. **단일** 입력 이미지 매개변수.

## 기술 세부 정보

* 데이터는 Data Staging에 저장되며 **7일 후 만료**.
* 각 배치 처리 작업은 여러 단계로 구성됩니다(일반적으로 `processing` 및 `export`). 각 단계는 출력 배치를 생성합니다. 효율적인 전송을 위해 압축된 `export` 단계 출력을 사용하는 것이 좋습니다.
* 실행 중인 작업은 `processing` 단계에서 UI와 CLI를 모두 사용해 중단할 수 있습니다.
* 중단되거나 실패한 작업은 다시 시작할 수 있습니다.
* 서비스는 데이터를 자동으로 샤딩하고 병렬로 처리합니다.
  * 데이터 양에 따라 머신 수가 자동으로 조정됩니다(특정 워크로드에서는 처리량이 시간당 50만\~100만 이미지에 이를 수 있습니다).
  * 각 머신은 데이터 청크를 처리하는 여러 작업자를 실행합니다. 이 설정은 구성할 수 있으며, 속도와 비용의 균형을 맞추도록 조정해야 합니다.
* 이미지 작업에서 단일 샤드의 이미지 실패 수가 너무 많으면 해당 샤드는 중단되지만 나머지 작업은 계속 진행됩니다. 작업별로 이 임계값을 구성할 수 있습니다(아래의 [샤드별 이미지 실패 허용 한도](#per-shard-image-failure-tolerance) 참조).

## 작업 시간 초과

### 문제

작업 크기나 복잡성에 비해 **처리 시간 제한(시간)** 이 너무 낮게 설정되어 있으면 배치 작업이 조기에 종료됩니다.

<figure><img src="https://media.roboflow.com/inference/batch-processing/batch-processing-timeout.png" alt=""><figcaption><p>UI의 처리 시간 제한 설정</p></figcaption></figure>

### 세부 정보

시간 제한 설정(UI) 또는 `--max-runtime-seconds` (CLI)는 **모든 병렬 작업자에서 누적된 머신 실행 시간의 최댓값**.

* **전체 컴퓨팅 시간:** 제한이 2시간이고 작업에서 머신 2개를 실행하는 경우, 각 머신은 최대 1시간 동안 실행될 수 있습니다(머신 2개 × 1시간 = 총 2시간).
* **청크별 분배:** 병렬 처리를 위해 작업은 처리 청크로 나뉩니다. 시간 제한은 청크별로 분배되므로 청크가 많은데 시간 제한이 짧으면 각 청크에 할당되는 시간이 너무 부족할 수 있습니다.
* **머신 유형의 영향:** CPU에서 복잡한 Workflow를 실행하면 처리 시간이 크게 늘어납니다. 적절한 경우 GPU를 사용하세요.

### 권장 사항

* 대규모 데이터 세트나 여러 단계로 구성된 Workflow에는 넉넉한 시간 제한(예: 4\~6시간)으로 시작하세요.
* 실제 작업 실행 시간을 모니터링해 향후 시간 제한을 설정할 때 참고하세요.
* 더 빠르게 처리하려면 청크 수를 줄이거나 비디오 프레임 서브샘플링을 사용하는 방법을 고려하세요.

## SAHI를 사용하는 Workflow의 실행 시간이 너무 깁니다

### 문제

SAHI를 사용하는 작업은 특히 고해상도 입력 및 인스턴스 분할과 함께 사용할 때 예상보다 훨씬 오래 걸릴 수 있습니다.

### 원인 및 권장 사항

**슬라이스 수가 너무 많음:** SAHI는 감지를 위해 이미지를 더 작은 슬라이스로 나눕니다. 기본 설정과 고해상도 입력을 사용하는 경우 이미지 하나당 추론을 수십 회 또는 수백 회 수행할 수 있습니다.

* Image Slicer 블록 구성을 확인하세요. 슬라이스 수를 줄이거나 Workflow에서 앞쪽에 Resize Image 블록을 추가해 입력 크기를 줄이세요.

**SAHI 대신 더 큰 모델 입력 크기를 고려하세요:** 입력 크기를 더 크게 설정해 모델을 학습하면 SAHI가 전혀 필요하지 않을 수 있습니다. 먼저 소규모 샘플로 테스트하세요.

**인스턴스 분할 병목:** SAHI를 인스턴스 분할과 함께 사용하면 Detections Stitch 블록(특히 NMS 사용 시)이 주요 병목이 될 수 있습니다. 단일 프레임을 스티칭하는 데 수십 초가 걸릴 수 있습니다.

**SAHI를 사용하는 비디오 작업:** FPS 서브샘플링으로 프레임을 건너뛰세요:

* UI에서 **비디오 FPS 서브샘플링** 드롭다운을 사용하세요.
* CLI에서는 `--max-video-fps` 플래그를 사용하세요.

<figure><img src="https://media.roboflow.com/inference/batch-processing/limiting-video-fps.png" alt=""><figcaption><p>UI의 FPS 서브샘플링 설정</p></figcaption></figure>

## 메모리 부족(OOM) 오류

### 문제

Workflow가 사용 가능한 RAM 또는 VRAM보다 더 많은 메모리를 소비하면 OOM 오류로 작업이 실패합니다.

### 일반적인 원인

* **SAHI + 인스턴스 분할:** 이 조합은 메모리를 매우 많이 사용합니다. SAHI는 추론 호출 횟수를 늘리고, 인스턴스 분할은 대용량 출력(마스크, 점수)을 생성하므로 충돌이 발생하는 경우가 많습니다.
* **머신당 작업자 수가 너무 많음:** 여러 작업자를 사용하면 가벼운 Workflow의 비용과 속도를 최적화할 수 있지만, 무거운 Workflow(대형 모델 여러 개, 복잡한 후처리)는 사용 가능한 메모리를 초과할 수 있습니다.

### 권장 사항

* 대형 모델, SAHI 또는 고해상도 입력을 사용하는 Workflow에서는 머신당 작업자 수를 줄이세요(예: 1명 또는 2명).
* 고급 옵션에서 **머신당 작업자 수** 값을 낮추세요.
* 모델에 더 높은 메모리 처리량이 필요하다면 CPU에서 GPU로 전환하세요.
* 대규모 배치를 실행하기 전에 소규모 데이터셋으로 Workflow를 테스트하세요.
* 입력 해상도를 낮추거나 불필요한 블록을 제거해 Workflow를 단순화하세요.

<figure><img src="https://media.roboflow.com/inference/batch-processing/workers-number-adjustment.png" alt=""><figcaption><p>UI의 머신당 작업자 수 설정</p></figcaption></figure>

## 샤드별 이미지 실패 허용 범위

### 작동 방식

이미지 배치 작업은 병렬 실행되는 샤드로 나뉩니다. 각 샤드는 처리 중 실패한 이미지 수를 추적합니다. 단일 샤드 내 실패율이 임계값을 초과하면 해당 샤드가 중단됩니다. 나머지 작업은 영향을 받지 않고 계속됩니다.

기본적으로 플랫폼은 고정된 실패 임계값을 적용합니다. 작업 생성 요청 본문에 `maxImageFailureRate` 을 설정하면 작업별로 재정의할 수 있습니다. 값은 다음 범위의 부동 소수점 숫자입니다. `0.0` 에서 `1.0`:

* `0.0` 은(는) 실패를 허용하지 않음을 의미합니다(첫 번째 실패에서 샤드를 중단).
* `1.0` 은(는) 이미지가 몇 개 실패하든 샤드가 중단되지 않음을 의미합니다.
* 필드를 생략하거나 `null` (으)로 설정하면 플랫폼 기본값을 사용합니다.

이 매개변수는 이미지 작업에만 적용됩니다. 비디오 작업에서는 지원되지 않습니다.

### API를 통한 설정

작업 생성 페이로드에 `maxImageFailureRate` 을 포함하세요:

```json
{
  "type": "simple-image-processing-v1",
  "maxImageFailureRate": 0.1,
  ...
}
```

실패했거나 중단된 작업을 다시 시작할 때 재시작 매개변수 재정의에 값을 포함하여 이 값을 재정의할 수도 있습니다.
