> 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/roboflow/roboflow-ko/deploy/batch-processing/troubleshooting.md).
# 문제 해결
이 페이지에는 Batch Processing의 알려진 문제, 제한 사항, 그리고 우회 방법이 나열되어 있습니다. 여기에 나열되지 않은 문제가 발생하면 다음을 통해 보고해 주세요. [지원 채널](https://github.com/roboflow/inference/issues).
## 알려진 제한 사항
* 환경 변수와 로컬 스토리지에 대한 접근이 필요한 일부 Workflow 블록(File Sink 및 Environment Secret Store 등)은 차단되며 실행되지 않습니다.
* 이 서비스는 다음을 정의하는 Workflow에서만 작동합니다. **단일** input image parameter.
## 기술 세부 정보
* 데이터는 7일 만료가 적용된 Data Staging에 저장됩니다. **7일 만료**.
* 각 batch processing job에는 여러 stage가 포함되며(일반적으로 `처리` 및 `내보내기`). 각 stage는 출력 batch를 생성합니다. 다음을 사용하는 것을 권장합니다. `내보내기` 효율적인 전송을 위해 압축되므로 stage outputs를 사용하세요.
* 실행 중인 job은 `처리` 해당 stage는 UI와 CLI 모두에서 중단할 수 있습니다.
* 중단되었거나 실패한 job은 다시 시작할 수 있습니다.
* 서비스는 데이터를 자동으로 shard로 나누어 병렬 처리합니다:
* 기계 수는 데이터 볼륨에 따라 자동으로 확장됩니다(특정 워크로드에서는 처리량이 시간당 500k–1M 이미지에 이를 수 있습니다).
* 각 machine은 데이터 chunk를 처리하는 여러 worker를 실행합니다. 이는 구성 가능하며 속도와 비용의 균형을 맞추도록 조정해야 합니다.
* 이미지 job의 경우, 단일 shard에서 너무 많은 이미지가 실패하면 나머지 job은 계속 진행되는 동안 해당 shard는 중단됩니다. 이 임계값은 job별로 구성할 수 있습니다(다음을 참조 [Per-Shard Image Failure Tolerance](#per-shard-image-failure-tolerance) 아래).
## Job 시간 초과
### 문제
Batch job은 다음의 경우 조기에 종료됩니다. **Processing Timeout Hours** 가 job의 크기나 복잡성에 비해 너무 낮게 설정되어 있으면.
UI의 Processing Timeout 설정
### 세부 정보
타임아웃 설정(UI) 또는 `--max-runtime-seconds` (CLI)는 **모든 병렬 worker의 최대 누적 machine 실행 시간을 정의합니다.**.
* **총 계산 시간:** 제한 시간이 2시간이고 job이 2대의 machine을 생성하면, 각 machine은 최대 1시간 동안 실행될 수 있습니다(2대 x 1시간 = 총 2시간).
* **chunk별로 나누면:** job은 병렬 처리를 위해 processing chunk로 분할됩니다. 타임아웃은 chunk에 걸쳐 나뉘므로, chunk가 많은데 타임아웃이 짧으면 각 chunk에 남는 시간이 너무 적을 수 있습니다.
* **machine 유형도 중요합니다:** 복잡한 Workflow를 CPU에서 실행하면 처리 시간이 크게 늘어납니다. 필요할 때는 GPU를 사용하세요.
### 권장 사항
* 대용량 데이터셋이나 여러 stage로 구성된 Workflow에는 넉넉한 타임아웃(예: 4\~6시간)으로 시작하세요.
* 향후 타임아웃 설정에 반영할 수 있도록 실제 job 실행 시간을 모니터링하세요.
* 더 빠른 처리를 위해 chunk 수를 줄이거나 video frame sub-sampling을 사용하는 것을 고려하세요.
## SAHI를 사용하는 Workflow가 너무 오래 실행됨
### 문제
SAHI를 사용하는 job은 — 특히 고해상도 입력과 instance segmentation을 사용할 때 — 예상보다 훨씬 오래 걸릴 수 있습니다.
### 원인 및 권장 사항
**slice 수가 과도함:** SAHI는 탐지를 위해 이미지를 더 작은 slice로 나눕니다. 기본 설정과 고해상도 입력에서는 이미지당 수십 또는 수백 번의 추론이 발생할 수 있습니다.
* Image Slicer 블록 구성을 확인하세요. Workflow 앞부분의 Resize Image 블록을 사용해 slice 수를 줄이거나 입력을 축소하세요.
**SAHI 대신 더 큰 model input size를 고려하세요:** 더 큰 입력 차원으로 model을 학습시키면 SAHI가 전혀 필요 없게 될 수 있습니다. 먼저 작은 샘플로 테스트하세요.
**instance segmentation 병목:** SAHI를 instance segmentation과 함께 사용하면 Detections Stitch 블록(특히 NMS 사용 시)이 주요 병목이 될 수 있습니다 — 단일 frame을 stitching하는 데 수십 초가 걸릴 수 있습니다.
**SAHI를 사용하는 video job의 경우:** 프레임을 건너뛰려면 FPS sub-sampling을 사용하세요:
* UI에서는 **Video FPS sub-sampling** 드롭다운에 값을 지정하세요.
* CLI에서는 `--max-video-fps` 플래그.
UI의 FPS sub-sampling 설정
## 메모리 부족(OOM) 오류
### 문제
Workflow가 사용 가능한 RAM 또는 VRAM보다 더 많은 메모리를 소비하면 OOM 오류로 인해 job이 실패합니다.
### 일반적인 원인
* **SAHI + Instance Segmentation:** 이 조합은 메모리 사용량이 매우 큽니다. SAHI는 추론 호출 수를 늘리고, instance segmentation은 큰 출력(masks, scores)을 생성하므로 종종 충돌로 이어집니다.
* **machine당 worker가 너무 많음:** 여러 worker는 가벼운 Workflow에서 비용과 속도를 최적화하지만, 무거운 Workflow(여러 대형 model, 복잡한 후처리)는 사용 가능한 메모리를 초과하게 됩니다.
### 권장 사항
* 대형 model, SAHI 또는 고해상도 입력이 있는 Workflow에서는 machine당 worker 수를 더 적게(예: 1 또는 2) 사용하세요.
* 낮추세요 **Workers Per Machine** 값을 Advanced Options에서
* model에 더 높은 memory throughput이 필요하다면 CPU 대신 GPU로 전환하세요.
* 큰 batch를 실행하기 전에 작은 데이터셋에서 Workflow를 테스트하세요.
* 입력 해상도를 낮추거나 불필요한 블록을 제거해 Workflow를 단순화하세요.
UI의 Workers Per Machine 설정
## Per-Shard Image Failure Tolerance
### 작동 방식
이미지 batch job은 병렬로 실행되는 shard로 분할됩니다. 각 shard는 처리 중 실패한 이미지 수를 추적합니다. 단일 shard 내 실패율이 임계값을 초과하면 해당 shard는 중단됩니다. job의 나머지는 영향을 받지 않고 계속 진행됩니다.
기본적으로 플랫폼은 고정된 실패 임계값을 적용합니다. job 생성 요청 본문에서 다음을 설정하면 job별로 이를 재정의할 수 있습니다. `maxImageFailureRate` 값은 다음 사이의 float입니다. `0.0` 및 `1.0`:
* `0.0` 무관용을 의미합니다(첫 실패 시 shard를 중단합니다).
* `1.0` 실패한 이미지 수와 관계없이 shard가 중단되지 않음을 의미합니다.
* 필드를 생략하거나 `null` 플랫폼 기본값을 사용하려면
이 파라미터는 이미지 job에만 적용됩니다. video job에서는 지원하지 않습니다.
### API를 통한 설정
다음을 포함하세요. `maxImageFailureRate` job 생성 payload에:
```json
{
"type": "simple-image-processing-v1",
"maxImageFailureRate": 0.1,
...
}
```
실패했거나 중단된 job을 다시 시작할 때 restart parameters override에 포함하여 이 값을 재정의할 수도 있습니다.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.roboflow.com/roboflow/roboflow-ko/deploy/batch-processing/troubleshooting.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
