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

# 배치 처리

## 소개

배치 처리는 실행하는 데 비용 효율적인 방법입니다 [워크플로](https://docs.roboflow.com/workflows) 이미지 배치와 저장된 비디오에 대해. 대량의 데이터를 비동기적으로 처리하는 데 이상적입니다.

배치 처리는 대규모 배치를 실행하는 데 필요한 인프라를 자동으로 프로비저닝합니다.

{% hint style="info" %}
배치 처리는 Growth 및 Enterprise 요금제에서 사용할 수 있습니다. "배치 처리" 탭에서 작업을 시작하거나, 자산 라이브러리의 선택 항목에서 워크플로를 실행할 수 있습니다. [자산 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library).
{% endhint %}

Roboflow 웹 인터페이스 또는 API(클라이를 통해)를 통해 배치 처리 작업을 구성할 수 있습니다.

작업을 시작하면, 데이터를 처리하기 위해 클라우드에 머신이 프로비저닝됩니다. 그런 다음 선택한 워크플로를 데이터에 대해 실행한 결과가 담긴 JSON 파일을 받게 됩니다.

다음 비디오에서는 배치 처리를 자세히 설명합니다:

{% embed url="<https://www.youtube.com/watch?v=S7K2j2IeQrM>" %}

## 웹 앱

### 배치 처리 작업 만들기

배치 처리 작업을 만들려면 Roboflow 대시보드 왼쪽 사이드바에서 Deployments를 클릭하세요. 그런 다음 "배치 처리" 탭을 클릭합니다:

<figure><img src="/files/9537b40de33224b9b609e89ff4cf81692716ce8c" alt=""><figcaption></figcaption></figure>

"새 배치 작업"을 클릭하여 배치 처리 작업을 만드세요.

작업을 구성할 수 있는 창이 열립니다:

<figure><img src="/files/d876195e37694ec267162c0d48db9f67aee4fed5" alt=""><figcaption></figcaption></figure>

#### 워크플로 선택

작업 구성을 시작하려면 먼저 워크플로를 선택하세요. 아직 워크플로가 없다면 시작하기 위해 워크플로 문서를 참조하세요.

#### 이미지 또는 비디오 업로드

다음으로, 워크플로를 실행할 이미지나 비디오를 업로드해야 합니다.

#### 하드웨어 구성

배치 처리 작업은 CPU 또는 GPU에서 실행할 수 있습니다. GPU 작업은 더 빠르지만 더 비쌉니다.

가격 정보는 Roboflow 가격 문서를 참조하세요.

작업에 사용할 CPU 또는 GPU를 선택하세요:

<figure><img src="/files/a991101c0524ac5a483a4f8e84f6369f89efdbc2" alt=""><figcaption></figcaption></figure>

고급 구성 옵션은 "고급 옵션" 탭에서도 사용할 수 있습니다. 이러한 옵션은 기본값으로 두는 것을 권장합니다.

#### 작업 시작

"배치 작업 만들기"를 클릭하여 배치 처리 작업을 시작하세요.

작업에 대한 인프라가 프로비저닝되고 처리가 시작됩니다.

### 작업 진행 상황 모니터링

작업을 시작하면, 처리가 구성 중인지, 배치 데이터가 처리 중인지, 작업이 완료되었는지를 나타내는 상태 표시기가 나타납니다.

배치의 처리 완료 정도를 실시간으로 모니터링할 수 있습니다.

데이터를 처리하는 데 걸리는 시간은 처리하는 이미지나 비디오 수, 워크플로의 복잡성, CPU 또는 GPU 하드웨어를 선택했는지에 따라 달라집니다.

작업을 열어 세부 정보를 확인할 수 있습니다. 여기에는 작업이 어떤 이미지에서 실행되었는지를 보여주는 "입력 소스"가 포함됩니다: [자산 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library) 이들을 선택하는 데 사용된 검색 쿼리(해당 선택을 다시 여는 링크 포함) 또는 수동으로 선택한 이미지 수입니다.

### 앱에서 워크플로 실행

외에도 [API](#http-api) 및 [CLI](#cli), Roboflow 앱에서 직접 배치 처리 작업을 시작하여 [워크플로](https://docs.roboflow.com/workflows) 대규모 저장 이미지 세트에 대해 워크플로를 실행할 수 있습니다. 이를 수행하는 방법은 두 가지입니다:

* 필요할 때, 자산 라이브러리에서.
* 각 [데이터 소스](https://docs.roboflow.com/datasets/create-and-upload/adding-data/datasources) 가 클라우드 버킷의 새 이미지를 미러링할 때 자동으로.

#### 자산 라이브러리에서

다음 [자산 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library) 를 사용하면 선택한 이미지에서 필요할 때 워크플로를 실행할 수 있습니다.

이미지를 수동으로 선택하거나 현재 검색과 일치하는 모든 이미지를 선택한 다음 "워크플로 실행"을 클릭하세요. 결과를 이미지에 다시 쓰는 방법을 포함한 전체 흐름은 [워크플로 실행](https://docs.roboflow.com/platform/workspaces/asset-library#running-a-workflow).

#### 데이터 소스가 미러링할 때 자동으로

하나의 [데이터 소스](https://docs.roboflow.com/datasets/create-and-upload/adding-data/datasources) 클라우드 버킷의 이미지와 메타데이터를 워크스페이스로 미러링합니다. 각 미러 가져오기마다 새 이미지에 대해 워크플로를 자동으로 실행할 수 있습니다. 이렇게 하면 새 데이터가 도착할 때 수동 단계 없이 태깅, 품질 점수 매기기, 사전 라벨링과 같은 보강이 최신 상태로 유지됩니다.

이러한 자동화는 [데이터 소스](https://app.roboflow.com/settings/datasources) 페이지의 "워크플로 실행" 섹션에서 구성합니다.

{% hint style="info" %}
워크플로 실행을 관리하려면 배치 자동화를 관리할 권한이 있는 워크스페이스 역할이 필요합니다. "워크플로 실행" 섹션이 보이지 않으면 워크스페이스 관리자에게 문의하세요.
{% endhint %}

자동화를 추가하려면:

1. "워크플로 실행" 섹션에서 "워크플로 실행 추가"를 클릭합니다.
2. 자동화의 이름을 입력합니다.
3. "실행 시"에서 "동기화 시"를 선택하고 [데이터 소스](https://docs.roboflow.com/datasets/create-and-upload/adding-data/datasources) 을 선택하여 이를 트리거해야 합니다.
4. 실행할 워크플로를 선택합니다. 이 워크플로는 정확히 하나의 `image` 입력
5. 을 가져야 합니다.
6. "만들기"를 클릭합니다.

선택한 데이터 소스 중 하나가 미러링할 때마다, 자동화는 해당 미러가 가져온 이미지에 대해 배치 처리 작업으로 워크플로를 실행합니다. 진행 상황은 Activity Center와 Deployments 아래의 "배치 처리" 탭에서 다른 배치 처리 작업과 동일하게 추적할 수 있습니다.

워크플로가 결과를 이미지에 다시 써서 자산 라이브러리에서 검색할 수 있게 하려면, [결과를 자산 라이브러리에 다시 쓰기](https://docs.roboflow.com/platform/workspaces/asset-library#writing-results-back-to-the-asset-library).

### API 또는 CLI로 작업 실행

프로그래밍 방식으로 배치 처리 작업을 생성하고 실행하려면 아래의 [HTTP API](#http-api) 및 [CLI](#cli) 섹션을 참조하세요. 일반적인 문제를 디버깅하려면 [문제 해결](/deployment/ko/roboflow-cloud/batch-processing/troubleshooting.md).

## HTTP API

**빠른 링크:**

* [데이터 수집](#ingest-data) (비디오, 단일 이미지, 이미지)
* [배치 상태 확인](#check-batch-status) (항목 수, 샤드 세부 정보)
* [작업 시작](#start-a-job)
* [작업 진행 상황 모니터링](#monitor-job-progress) (작업 상태, 단계, 작업)
* [결과 내보내기](#export-results) (출력 파트, 다운로드 URL)
* [웹훅 알림](#webhook-notifications)

### 데이터 수집

#### 비디오 업로드

## Upload a video

> Request a signed URL to upload a video file. After receiving the response, PUT the video to the \`uploadURL\` with the provided \`extensionHeaders\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Data Ingestion","description":"Upload images and videos to Data Staging before processing."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/data-staging/v1/external/{workspace}/batches/{batch_id}/upload/video":{"post":{"operationId":"uploadVideo","tags":["Data Ingestion"],"summary":"Upload a video","description":"Request a signed URL to upload a video file. After receiving the response, PUT the video to the `uploadURL` with the provided `extensionHeaders`.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/batch_id"},{"$ref":"#/components/parameters/api_key"},{"name":"fileName","in":"query","required":true,"schema":{"type":"string"},"description":"Name of the video file (e.g. `my_video.mp4`)."}],"responses":{"200":{"description":"Signed URL details for uploading the video.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"signedURLDetails":{"type":"object","properties":{"uploadURL":{"type":"string","description":"PUT the video file to this URL."},"method":{"type":"string","description":"HTTP method to use for the upload."},"extensionHeaders":{"type":"object","additionalProperties":{"type":"string"},"description":"Include these headers in the PUT request."},"maxFileSize":{"type":"integer","description":"Maximum file size in bytes."}}}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"batch_id":{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$"},"description":"Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}}}}
```

#### 이미지 업로드

## Upload a single image

> Upload a single image via multipart form data. Best for batches up to 5,000 images.\
> \
> \*\*Note:\*\* Single-image and bulk uploads cannot be combined for the same batch.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Data Ingestion","description":"Upload images and videos to Data Staging before processing."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/data-staging/v1/external/{workspace}/batches/{batch_id}/upload/image":{"post":{"operationId":"uploadImage","tags":["Data Ingestion"],"summary":"Upload a single image","description":"Upload a single image via multipart form data. Best for batches up to 5,000 images.\n\n**Note:** Single-image and bulk uploads cannot be combined for the same batch.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/batch_id"},{"$ref":"#/components/parameters/api_key"},{"name":"fileName","in":"query","required":true,"schema":{"type":"string"},"description":"Name of the image file."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The image file to upload."}}}}}},"responses":{"200":{"description":"Image uploaded successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"batch_id":{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$"},"description":"Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}}}}
```

#### 이미지 대량 업로드

## Bulk upload images

> Request a signed URL for uploading a \`.tar\` archive of images. Recommended for batches exceeding 5,000 images. Bundle up to 500 images per archive.\
> \
> The response contains a signed URL and extension headers. Pack images into a \`.tar\` archive and PUT it to the signed URL.\
> \
> \*\*Note:\*\* Bulk and single-image uploads cannot be combined for the same batch.\
> \
> When performing bulk ingestion, data is indexed in the background. There may be a short delay before all data is available.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Data Ingestion","description":"Upload images and videos to Data Staging before processing."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/data-staging/v1/external/{workspace}/batches/{batch_id}/bulk-upload/image-files":{"post":{"operationId":"bulkUploadImages","tags":["Data Ingestion"],"summary":"Bulk upload images","description":"Request a signed URL for uploading a `.tar` archive of images. Recommended for batches exceeding 5,000 images. Bundle up to 500 images per archive.\n\nThe response contains a signed URL and extension headers. Pack images into a `.tar` archive and PUT it to the signed URL.\n\n**Note:** Bulk and single-image uploads cannot be combined for the same batch.\n\nWhen performing bulk ingestion, data is indexed in the background. There may be a short delay before all data is available.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/batch_id"},{"$ref":"#/components/parameters/api_key"}],"responses":{"200":{"description":"Signed URL details for uploading a tar archive.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"signedURLDetails":{"type":"object","properties":{"shardId":{"type":"string","format":"uuid","description":"Unique identifier for this shard upload."},"uploadURL":{"type":"string","description":"PUT the tar archive to this URL."},"method":{"type":"string","description":"HTTP method to use for the upload."},"extensionHeaders":{"type":"object","additionalProperties":{"type":"string"},"description":"Include these headers in the PUT request."},"maxNumberOfImages":{"type":"integer","description":"Maximum number of images per tar archive."},"maxShardSize":{"type":"integer","description":"Maximum tar archive size in bytes."}}}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"batch_id":{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$"},"description":"Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}}}}
```

### 배치 상태 확인

## Get batch item count

> Returns the count of ingested items in a batch. Use this to verify all data has been ingested before starting a job.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Batch Status","description":"Inspect staged data and batch contents."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/data-staging/v1/external/{workspace}/batches/{batch_id}/count":{"get":{"operationId":"getBatchCount","tags":["Batch Status"],"summary":"Get batch item count","description":"Returns the count of ingested items in a batch. Use this to verify all data has been ingested before starting a job.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/batch_id"},{"$ref":"#/components/parameters/api_key"}],"responses":{"200":{"description":"Batch item count.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"count":{"type":"integer","description":"Number of items in the batch."}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"batch_id":{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$"},"description":"Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}}}}
```

#### 샤드 업로드 세부 정보 확인

## List batch shards

> Returns shard details for a bulk-upload batch. Paginated — use \`nextPageToken\` from the response to fetch subsequent pages.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Batch Status","description":"Inspect staged data and batch contents."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/data-staging/v1/external/{workspace}/batches/{batch_id}/shards":{"get":{"operationId":"getBatchShards","tags":["Batch Status"],"summary":"List batch shards","description":"Returns shard details for a bulk-upload batch. Paginated — use `nextPageToken` from the response to fetch subsequent pages.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/batch_id"},{"$ref":"#/components/parameters/api_key"},{"$ref":"#/components/parameters/nextPageToken"}],"responses":{"200":{"description":"Paginated list of batch shards.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"shards":{"type":"array","items":{"type":"object"},"description":"List of shard objects."},"nextPageToken":{"type":"string","nullable":true,"description":"Token for fetching the next page of results. `null` if no more pages."}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"batch_id":{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$"},"description":"Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."},"nextPageToken":{"name":"nextPageToken","in":"query","required":false,"schema":{"type":"string"},"description":"Pagination token from a previous response."}}}}
```

### 작업 시작

## Start a batch processing job

> Start a batch processing job that runs a Workflow against staged data.\
> \
> \*\*Job ID constraints:\*\* Lowercase letters, digits, hyphens, and underscores only. Maximum 20 characters.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Processing","description":"Start and monitor batch processing jobs."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/batch-processing/v1/external/{workspace}/jobs/{job_id}":{"post":{"operationId":"startJob","tags":["Processing"],"summary":"Start a batch processing job","description":"Start a batch processing job that runs a Workflow against staged data.\n\n**Job ID constraints:** Lowercase letters, digits, hyphens, and underscores only. Maximum 20 characters.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/job_id"},{"$ref":"#/components/parameters/api_key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStartRequest"}}}},"responses":{"200":{"description":"Job started successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"job_id":{"name":"job_id","in":"path","required":true,"schema":{"type":"string","maxLength":20,"pattern":"^[a-z0-9_-]+$"},"description":"Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}},"schemas":{"JobStartRequest":{"type":"object","required":["type","jobInput","computeConfiguration","processingSpecification"],"properties":{"type":{"type":"string","enum":["simple-image-processing-v1"],"description":"Job type."},"jobInput":{"type":"object","required":["type","batchId"],"properties":{"type":{"type":"string","enum":["staging-batch-input-v1"],"description":"Input type."},"batchId":{"type":"string","description":"The batch ID containing the data to process."}}},"computeConfiguration":{"type":"object","required":["type","machineType"],"properties":{"type":{"type":"string","enum":["compute-configuration-v2"],"description":"Configuration type."},"machineType":{"type":"string","enum":["cpu","gpu"],"description":"Machine type. Use `gpu` for Workflows with multiple or large models."},"workersPerMachine":{"type":"integer","default":4,"description":"Number of parallel workers per machine. Reduce for memory-intensive Workflows."}}},"processingTimeoutSeconds":{"type":"integer","default":3600,"description":"Maximum cumulative machine runtime in seconds across all parallel workers."},"processingSpecification":{"type":"object","required":["type","workspace","workflowId"],"properties":{"type":{"type":"string","enum":["workflows-processing-specification-v1"],"description":"Processing specification type."},"workspace":{"type":"string","description":"Workspace containing the Workflow."},"workflowId":{"type":"string","description":"The Workflow to run. Find this in the Workflow Editor under \"Deploy\"."},"aggregationFormat":{"type":"string","enum":["jsonl","csv"],"default":"jsonl","description":"Output format for aggregated results."}}},"notificationsURL":{"type":"string","format":"uri","description":"Webhook URL for job completion notifications. Custom webhook headers are not yet supported. The only header sent is `Authorization: Bearer rf_{workspace_id}`."}}}}}}
```

### 작업 진행 상황 모니터링

#### 작업 상태 가져오기

## Get job status

> Returns the current status of a batch processing job.

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Processing","description":"Start and monitor batch processing jobs."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/batch-processing/v1/external/{workspace}/jobs/{job_id}":{"get":{"operationId":"getJobStatus","tags":["Processing"],"summary":"Get job status","description":"Returns the current status of a batch processing job.","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/job_id"},{"$ref":"#/components/parameters/api_key"}],"responses":{"200":{"description":"Job status details.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"jobStatus":{"type":"string","description":"Current job status (e.g. `pending`, `processing`, `completed`, `failed`)."},"progress":{"type":"number","description":"Processing progress as a fraction between 0 and 1."}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"job_id":{"name":"job_id","in":"path","required":true,"schema":{"type":"string","maxLength":20,"pattern":"^[a-z0-9_-]+$"},"description":"Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}}}}
```

#### 작업 단계 목록

## List job stages

> Returns the list of stages for a job. Each job typically has \`processing\` and \`export\` stages, each producing an output batch.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Processing","description":"Start and monitor batch processing jobs."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/batch-processing/v1/external/{workspace}/jobs/{job_id}/stages":{"get":{"operationId":"getJobStages","tags":["Processing"],"summary":"List job stages","description":"Returns the list of stages for a job. Each job typically has `processing` and `export` stages, each producing an output batch.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/job_id"},{"$ref":"#/components/parameters/api_key"}],"responses":{"200":{"description":"List of job stages.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"stages":{"type":"array","items":{"type":"object"},"description":"List of stage objects. Each stage has an ID and an output batch ID."}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"job_id":{"name":"job_id","in":"path","required":true,"schema":{"type":"string","maxLength":20,"pattern":"^[a-z0-9_-]+$"},"description":"Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}}}}
```

#### 단계 작업 목록

## List tasks for a stage

> Returns the list of tasks for a specific job stage. Paginated — use \`nextPageToken\` from the response to fetch subsequent pages.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Processing","description":"Start and monitor batch processing jobs."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/batch-processing/v1/external/{workspace}/jobs/{job_id}/stages/{stage_id}/tasks":{"get":{"operationId":"getStageTasks","tags":["Processing"],"summary":"List tasks for a stage","description":"Returns the list of tasks for a specific job stage. Paginated — use `nextPageToken` from the response to fetch subsequent pages.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/job_id"},{"name":"stage_id","in":"path","required":true,"schema":{"type":"string"},"description":"The stage identifier."},{"$ref":"#/components/parameters/api_key"},{"$ref":"#/components/parameters/nextPageToken"}],"responses":{"200":{"description":"Paginated list of tasks.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"tasks":{"type":"array","items":{"type":"object"},"description":"List of task objects."},"nextPageToken":{"type":"string","nullable":true,"description":"Token for fetching the next page of results. `null` if no more pages."}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"job_id":{"name":"job_id","in":"path","required":true,"schema":{"type":"string","maxLength":20,"pattern":"^[a-z0-9_-]+$"},"description":"Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."},"nextPageToken":{"name":"nextPageToken","in":"query","required":false,"schema":{"type":"string"},"description":"Pagination token from a previous response."}}}}
```

### 결과 내보내기

#### 출력 파트 목록

## List output batch parts

> Lists the parts of an output batch. Use the \`export\` stage output batch for compressed results.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Data Export","description":"Download results after processing completes."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/data-staging/v1/external/{workspace}/batches/{batch_id}/parts":{"get":{"operationId":"listBatchParts","tags":["Data Export"],"summary":"List output batch parts","description":"Lists the parts of an output batch. Use the `export` stage output batch for compressed results.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/batch_id"},{"$ref":"#/components/parameters/api_key"}],"responses":{"200":{"description":"List of batch parts.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"parts":{"type":"array","items":{"type":"object","properties":{"partName":{"type":"string","description":"Name of the batch part."}}},"description":"List of batch part objects."}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"batch_id":{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$"},"description":"Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."}}}}
```

#### 다운로드 URL 목록

## List download URLs

> Returns paginated download URLs for files in a batch part.<br>

```json
{"openapi":"3.0.3","info":{"title":"Roboflow Batch Processing API","version":"1.0"},"tags":[{"name":"Data Export","description":"Download results after processing completes."}],"servers":[{"url":"https://api.roboflow.com"}],"paths":{"/data-staging/v1/external/{workspace}/batches/{batch_id}/list":{"get":{"operationId":"listDownloadUrls","tags":["Data Export"],"summary":"List download URLs","description":"Returns paginated download URLs for files in a batch part.\n","parameters":[{"$ref":"#/components/parameters/workspace"},{"$ref":"#/components/parameters/batch_id"},{"$ref":"#/components/parameters/api_key"},{"$ref":"#/components/parameters/nextPageToken"},{"name":"partName","in":"query","schema":{"type":"string"},"description":"Filter by part name (from the list parts response)."}],"responses":{"200":{"description":"Paginated list of download URLs.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"filesMetadata":{"type":"array","items":{"type":"object","properties":{"downloadURL":{"type":"string","description":"Signed URL to download the file."},"fileName":{"type":"string","description":"Original file name."},"partName":{"type":"string","nullable":true,"description":"Part name this file belongs to."},"shardId":{"type":"string","nullable":true,"description":"Shard ID (for bulk-upload batches)."},"contentType":{"type":"string","description":"Content type (e.g. `image`, `video`)."},"nestedContentType":{"type":"string","nullable":true,"description":"Nested content type, if applicable."}}},"description":"List of file metadata objects with download URLs."},"nextPageToken":{"type":"string","nullable":true,"description":"Token for fetching the next page of results. `null` if no more pages."}}}}}}}}}},"components":{"parameters":{"workspace":{"name":"workspace","in":"path","required":true,"schema":{"type":"string"},"description":"Your Roboflow workspace identifier."},"batch_id":{"name":"batch_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9_-]+$"},"description":"Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores."},"api_key":{"name":"api_key","in":"query","required":true,"schema":{"type":"string"},"description":"Your Roboflow API key."},"nextPageToken":{"name":"nextPageToken","in":"query","required":false,"schema":{"type":"string"},"description":"Pagination token from a previous response."}}}}
```

### 웹훅 알림

상태를 폴링하는 대신, 수집이나 처리가 완료되면 알림을 받도록 웹훅을 사용할 수 있습니다. 참조하세요 [CLI 사용법](#webhook-automation) 웹훅 구성 및 페이로드 형식은

## CLI

를 설치하면 `inference-cli` 를 사용할 수 있게 됩니다 `inference rf-cloud` 명령을 통해 배치 처리 및 데이터 스테이징과 상호작용할 수 있습니다. 이는 Roboflow 배치 처리의 핵심 구성 요소입니다.

### 설정

```bash
pip install inference-cli
export ROBOFLOW_API_KEY="YOUR-API-KEY-GOES-HERE"
```

클라우드 스토리지 지원의 경우:

```bash
pip install 'inference-cli[cloud-storage]'
```

API 키를 찾는 데 도움이 필요하면 [인증 가이드](https://docs.roboflow.com/reference/authentication/authentication/find-your-roboflow-api-key).

### 데이터 수집

#### 이미지

```bash
inference rf-cloud data-staging create-batch-of-images \\
  --images-dir <your-images-dir-path> \\
  --batch-id <your-batch-id>
```

#### 비디오

```bash
inference rf-cloud data-staging create-batch-of-videos \\
  --videos-dir <your-videos-dir-path> \\
  --batch-id <your-batch-id>
```

{% hint style="info" %}
**배치 ID 형식:** 소문자여야 하며, 최대 64자까지 가능하고, 문자, 숫자, 하이픈(`-`), 밑줄(`_`).
{% endhint %}

#### 클라우드 스토리지

데이터가 이미 클라우드 스토리지(S3, Google Cloud Storage, Azure)에 있다면, 파일을 로컬로 다운로드하지 않고 직접 처리할 수 있습니다.

**이미지의 경우:**

```bash
inference rf-cloud data-staging create-batch-of-images \\
  --data-source cloud-storage \\
  --bucket-path <cloud-path> \\
  --batch-id <your-batch-id>
```

**비디오의 경우:**

```bash
inference rf-cloud data-staging create-batch-of-videos \\
  --data-source cloud-storage \\
  --bucket-path <cloud-path> \\
  --batch-id <your-batch-id>
```

다음 `--bucket-path` 매개변수는 다음 공급자를 지원합니다. Glob 패턴은 수집할 파일을 필터링합니다:

| 공급자                  | 경로 형식                       | Glob 예시                                                    |
| -------------------- | --------------------------- | ---------------------------------------------------------- |
| S3                   | `s3://bucket-name/path/`    | `s3://my-bucket/training-data/**/*.jpg` - 모든 JPG를 재귀적으로    |
| Google Cloud Storage | `gs://bucket-name/path/`    | `gs://my-bucket/videos/2024-*/*.mp4` - 폴더 내 MP4 `2024-*` 들 |
| Azure Blob Storage   | `az://container-name/path/` | `az://container/images/*.png` - 이미지 폴더의 PNG                |

{% hint style="info" %}
클라우드 스토리지 자격 증명은 **CLI에서만** 사전 서명된 URL을 생성하는 데 사용됩니다. 이러한 자격 증명은 **절대 업로드되지 않습니다** Roboflow 서버로.
{% endhint %}

{% hint style="warning" %}
생성된 사전 서명 URL은 24시간 동안 유효합니다. 배치 처리 작업이 이 시간 내에 완료되도록 하세요.
{% endhint %}

대규모 데이터셋의 경우, 시스템은 이미지를 자동으로 각각 20,000개 파일씩 청크로 분할합니다. 비디오는 1,000개 미만의 배치에서 가장 잘 작동합니다.

#### 서명된 URL 수집

고급 자동화의 경우, 로컬 파일 대신 서명된 URL을 통해 데이터를 수집할 수 있습니다:

| 플래그                             | 설명                                               |
| ------------------------------- | ------------------------------------------------ |
| `--data-source references-file` | 서명된 URL로 참조된 파일을 처리합니다.                          |
| `--references <path_or_url>`    | 파일 URL이 포함된 JSONL 파일의 경로 또는 그런 파일을 가리키는 서명된 URL. |

**참조 파일 형식(JSONL):**

```
{"name": "<unique-file-name-1>", "url": "https://<signed-url>"}
{"name": "<unique-file-name-2>", "url": "https://<signed-url>"}
```

{% hint style="info" %}
서명된 URL 수집은 Growth Plan 및 Enterprise 고객에게 제공됩니다.
{% endhint %}

### 스테이징된 데이터 검사

```bash
inference rf-cloud data-staging show-batch-details --batch-id <your-batch-id>
```

### 작업 시작

#### 이미지 처리

```bash
inference rf-cloud batch-processing process-images-with-workflow \\
  --workflow-id <workflow-id> \\
  --batch-id <batch-id> \\
  --machine-type gpu
```

#### 비디오 처리

```bash
inference rf-cloud batch-processing process-videos-with-workflow \\
  --workflow-id <workflow-id> \\
  --batch-id <batch-id> \\
  --machine-type gpu \\
  --max-video-fps <your-desired-fps>
```

{% hint style="info" %}
**워크플로 ID 찾기:** Roboflow 앱에서 워크플로 편집기를 열고 "배포"를 클릭한 다음 코드 스니펫에서 식별자를 찾으세요.
{% endhint %}

{% hint style="info" %}
기본적으로 처리는 CPU에서 실행됩니다.  `--machine-type gpu` 여러 개의 크거나 큰 모델이 있는 워크플로에는&#x20;
{% endhint %}

### 작업 진행 상황 모니터링

시작 명령은  **작업 ID**를 출력합니다. 상태를 확인하는 데 사용하세요:

```bash
inference rf-cloud batch-processing show-job-details --job-id <your-job-id>
```

### 결과 내보내기

작업 세부 정보에는  **출력 배치 ID**가 포함됩니다. 결과를 내보내는 데 사용하세요:

```bash
inference rf-cloud data-staging export-batch \\
  --target-dir <dir-to-export-result> \\
  --batch-id <output-batch-of-a-job>
```

### 웹훅 자동화

상태를 폴링하는 대신, 수집이나 처리가 완료되면 알림을 받도록 웹훅을 사용할 수 있습니다.

#### 데이터 수집 웹훅

CLI 명령 `create-batch-of-images` 및 `create-batch-of-videos` 는 다음을 지원합니다:

| 플래그                                     | 설명                  |
| --------------------------------------- | ------------------- |
| `--notifications-url <webhook_url>`     | 알림을 위한 웹훅 엔드포인트.    |
| `--notification-category ingest-status` | 전체 수집 프로세스 상태. 기본값. |
| `--notification-category files-status`  | 개별 파일 처리 상태.        |

알림은 다음을 포함한  `Authorization` 헤더가 있는 HTTP POST를 통해 전달됩니다. 헤더에는 Roboflow Publishable Key가 포함됩니다.

**수집 상태 알림**

```json
{
    "type": "roboflow-data-staging-notification-v1",
    "event_id": "8c20f970-fe10-41e1-9ef2-e057c63c07ff",
    "ingest_id": "8cd48813430f2be70b492db67e07cc86",
    "batch_id": "test-batch-117",
    "shard_id": null,
    "notification": {
        "type": "ingest-status-notification-v1",
        "success": false,
        "error_details": {
            "type": "unsafe-url-detected",
            "reason": "Untrusted domain found: https://example.com/image.png"
        }
    },
    "delivery_attempt": 1
}
```

**파일 상태 알림**

```json
{
    "type": "roboflow-data-staging-notification-v1",
    "event_id": "8f42708b-aeb7-4b73-9d83-cf18518b6d81",
    "ingest_id": "d5cb69aa-b2d1-4202-a1c1-0231f180bda9",
    "batch_id": "prod-batch-1",
    "shard_id": "0d40fa12-349e-439f-83f8-42b9b7987b33",
    "notification": {
        "type": "ingest-files-status-notification-v1",
        "success": true,
        "ingested_files": [
            "000000494869.jpg",
            "000000186042.jpg"
        ],
        "failed_files": [
            {
                "type": "file-size-limit-exceeded",
                "file_name": "big_image.png",
                "reason": "단일 이미지의 최대 크기는 20971520B입니다."
            }
        ],
        "content_truncated": false
    },
    "delivery_attempt": 1
}
```

#### 작업 완료 웹훅

추가 `--notifications-url` 를 작업 시작 시:

```bash
inference rf-cloud batch-processing process-images-with-workflow \\
  --workflow-id <workflow-id> \\
  --batch-id <batch-id> \\
  --notifications-url <webhook_url>
```

**작업 완료 알림**

```json
{
  "type": "roboflow-batch-job-notification-v1",
  "event_id": "8f42708b-aeb7-4b73-9d83-cf18518b6d81",
  "job_id": "<your-batch-job-id>",
  "job_state": "success | fail",
  "delivery_attempt": 1
}
```

### 클라우드 스토리지 인증

#### AWS S3 및 S3 호환 스토리지

자격 증명은 다음에서 자동으로 감지됩니다:

1. **환경 변수:**

```bash
export AWS_ACCESS_KEY_ID=your-access-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-access-key
export AWS_SESSION_TOKEN=your-session-token  # 선택 사항
```

2. **AWS 자격 증명 파일** (`~/.aws/credentials`, `~/.aws/config`)
3. **IAM 역할** (EC2, ECS, Lambda)

**이름이 지정된 프로필:**

```bash
export AWS_PROFILE=production
```

**S3 호환 서비스(Cloudflare R2, MinIO 등):**

```bash
export AWS_ENDPOINT_URL=https://account-id.r2.cloudflarestorage.com
export AWS_REGION=auto  # R2는 region='auto'가 필요합니다
export AWS_ACCESS_KEY_ID=your-r2-access-key
export AWS_SECRET_ACCESS_KEY=your-r2-secret-key
```

#### Google Cloud Storage

자격 증명은 다음에서 감지됩니다:

1. **서비스 계정 키 파일** (자동화에 권장):

```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
```

2. **사용자 자격 증명** gcloud CLI에서(`gcloud auth login`)
3. **GCP 메타데이터 서비스** (Google Cloud Platform에서 실행할 때)

#### Azure Blob Storage

**SAS 토큰(권장):**

```bash
export AZURE_STORAGE_ACCOUNT_NAME=mystorageaccount
export AZURE_STORAGE_SAS_TOKEN="sv=2021-06-08&ss=b&srt=sco&sp=rl&se=2024-12-31"
```

**계정 키:**

```bash
export AZURE_STORAGE_ACCOUNT_NAME=mystorageaccount
export AZURE_STORAGE_ACCOUNT_KEY=your-account-key
```

Azure CLI를 통해 SAS 토큰 생성:

```bash
az storage container generate-sas \\
  --account-name mystorageaccount \\
  --name my-container \\
  --permissions rl \\
  --expiry 2024-12-31T23:59:59Z
```

#### 사용자 지정 스크립트

고급 사용 사례의 경우, 서명된 URL 파일 생성을 위한 스크립트를 참조하세요:

* **AWS S3:** [generateS3SignedUrls.sh](https://raw.githubusercontent.com/roboflow/roboflow-python/main/scripts/generateS3SignedUrls.sh)
* **Google Cloud Storage:** [generateGCSSignedUrls.sh](https://github.com/roboflow/roboflow-python/blob/main/scripts/generateGCSSignedUrls.sh)
* **Azure Blob Storage:** [generateAzureSasUrls.sh](https://raw.githubusercontent.com/roboflow/roboflow-python/main/scripts/generateAzureSasUrls.sh)

### 모든 옵션 살펴보기

```bash
inference rf-cloud --help
inference rf-cloud data-staging --help
inference rf-cloud batch-processing --help
```