> 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). # Batch Processing 대규모 이미지 배치와 저장된 비디오에서 클라우드 인프라를 사용해 워크플로를 실행합니다. ## 정보 배치 처리는 실행하는 비용 효율적인 방법입니다 [워크플로](https://docs.roboflow.com/workflows) 이미지 배치와 저장된 비디오에 대해 사용할 수 있습니다. 비동기적으로 대량의 데이터를 처리하는 데 이상적입니다. 배치 처리는 대규모 배치를 실행하는 데 필요한 인프라를 자동으로 프로비저닝합니다. {% hint style="info" %} 배치 처리는 Growth 및 Enterprise 요금제에서 사용할 수 있습니다. "배치 처리" 탭에서 작업을 시작하거나, 다음 항목의 선택에서 워크플로를 실행할 수 있습니다. [에셋 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library). {% endhint %} Roboflow 웹 인터페이스 또는 API(CLI를 통해)를 통해 배치 처리 작업을 구성할 수 있습니다. 작업을 시작하면 데이터 처리를 위해 클라우드에 머신이 프로비저닝됩니다. 그런 다음 데이터에 대해 실행한 워크플로의 출력이 포함된 JSON 파일을 받게 됩니다. 다음 비디오는 배치 처리를 자세히 설명합니다: {% embed url="" %} ## 웹 앱 ### 배치 처리 작업 생성 배치 처리 작업을 생성하려면 Roboflow 대시보드의 왼쪽 사이드바에서 Deployments를 클릭하세요. 그런 다음 "배치 처리" 탭을 클릭합니다:
"새 배치 작업"을 클릭하여 배치 처리 작업을 생성합니다. 작업을 구성할 수 있는 창이 열립니다:
#### 워크플로 선택 작업 구성을 시작하려면 먼저 워크플로를 선택하세요. 아직 워크플로가 없다면 시작하려면 워크플로 문서를 참조하세요. #### 이미지 또는 비디오 업로드 다음으로, 워크플로를 실행할 이미지 또는 비디오를 업로드해야 합니다. #### 하드웨어 구성 CPU 또는 GPU에서 배치 처리 작업을 실행할 수 있습니다. GPU 작업은 더 빠르지만 더 비쌉니다. 요금 정보는 Roboflow 요금 문서를 참조하세요. 작업에 사용할 CPU 또는 GPU를 선택하세요:
고급 구성 옵션은 "고급 옵션" 탭에서도 사용할 수 있습니다. 이러한 옵션은 기본값으로 두는 것을 권장합니다. #### 작업 시작 배치 처리 작업을 시작하려면 "배치 작업 생성"을 클릭하세요. 작업용 인프라가 프로비저닝되고 처리가 시작됩니다. ### 작업 진행 상황 모니터링 작업을 시작하면 처리가 구성 중일 때, 배치 데이터가 처리 중일 때, 그리고 작업이 완료되었을 때를 나타내는 상태 표시기가 나타납니다. 배치의 얼마나 많은 부분이 처리되었는지 실시간으로 모니터링할 수 있습니다. 데이터 처리에 걸리는 시간은 처리하는 이미지 또는 비디오 수, 워크플로의 복잡성, 그리고 CPU 또는 GPU 하드웨어를 선택했는지 여부에 따라 달라집니다. 작업을 열어 작업이 실행된 이미지를 보여주는 "입력 소스"를 포함한 세부 정보를 확인하세요: [에셋 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library) 이미지를 선택하는 데 사용한 검색 쿼리(해당 선택을 다시 열 수 있는 링크 포함) 또는 수동으로 선택한 이미지 수. ### 앱에서 워크플로 실행 다음 항목 외에도 [API](#http-api) 및 [CLI](#cli)를 통해 Roboflow 앱에서 직접 배치 처리 작업을 시작하여 [워크플로](https://docs.roboflow.com/workflows) 를 대규모 저장 이미지 집합에 대해 실행할 수 있습니다. 이를 수행하는 방법은 세 가지입니다: * 에셋 라이브러리에서 필요할 때. * Roboflow Agent에 요청하여 필요할 때. * 자동으로, 다음 경우마다 [데이터 소스](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). #### Agent에서 다음에게 요청하세요 [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) 게시된 워크플로를 다음 항목의 이미지에 실행하도록 [에셋 라이브러리](https://docs.roboflow.com/platform/workspaces/asset-library): 사용자가 선택한 이미지, 검색과 일치하는 이미지 또는 전체 라이브러리. Agent는 작업을 나열하고 하나의 상태를 보고할 수도 있습니다. Agent가 시작한 작업은 백그라운드 작업과 "배치 처리" 탭에서 추적하세요. 작업이 완료되면 Agent가 채팅에서 알려줍니다. Agent는 채팅에서 배치 처리를 탭으로 열어 작업 목록, 특정 작업의 세부 정보 또는 새 작업 양식을 표시할 수도 있습니다. 새 작업 양식에서는 워크플로와 합의한 설정을 채워 넣고, 파일은 사용자가 컴퓨터에서 직접 선택합니다. 양식에서 작업을 시작하거나 Agent에게 시작하도록 요청할 수 있습니다. #### 데이터 소스 미러링 시 자동으로 A [데이터 소스](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. 실행할 워크플로를 선택합니다. 정확히 하나의 `이미지` 입력 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\`.
```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.
```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.
```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.
```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.
```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.
```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.
```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.
```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.
```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.
```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 \ --batch-id ``` #### 비디오 ```bash inference rf-cloud data-staging create-batch-of-videos \ --videos-dir \ --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 \ --batch-id ``` **비디오의 경우:** ```bash inference rf-cloud data-staging create-batch-of-videos \ --data-source cloud-storage \ --bucket-path \ --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 ` | 파일 URL이 포함된 JSONL 파일의 경로 또는 해당 파일을 가리키는 서명된 URL입니다. | **참조 파일 형식(JSONL):** ``` {"name": "", "url": "https://"} {"name": "", "url": "https://"} ``` {% hint style="info" %} 서명된 URL 수집은 Growth Plan 및 Enterprise 고객에게 제공됩니다. {% endhint %} ### 스테이징된 데이터 검사 ```bash inference rf-cloud data-staging show-batch-details --batch-id ``` ### 작업 시작 #### 이미지 처리 ```bash inference rf-cloud batch-processing process-images-with-workflow \ --workflow-id \ --batch-id \ --machine-type gpu ``` #### 비디오 처리 ```bash inference rf-cloud batch-processing process-videos-with-workflow \ --workflow-id \ --batch-id \ --machine-type gpu \ --max-video-fps ``` {% hint style="info" %} **워크플로 ID 찾기:** Roboflow 앱에서 워크플로 편집기를 열고 "배포"를 클릭한 다음 코드 스니펫에서 식별자를 찾으세요. {% endhint %} {% hint style="info" %} 기본적으로 처리는 CPU에서 실행됩니다. `--machine-type gpu` 다중 또는 대형 모델을 사용하는 워크플로에 사용하세요. {% endhint %} ### 작업 진행 상황 모니터링 시작 명령은 **작업 ID**를 출력합니다. 상태 확인에 사용하세요: ```bash inference rf-cloud batch-processing show-job-details --job-id ``` ### 결과 내보내기 작업 세부 정보에는 **출력 배치 ID**가 포함됩니다. 결과를 내보내는 데 사용하세요: ```bash inference rf-cloud data-staging export-batch \ --target-dir \ --batch-id ``` ### 웹훅 자동화 상태를 폴링하는 대신, 웹훅을 사용해 수집 또는 처리가 완료되었을 때 알림을 받을 수 있습니다. #### 데이터 수집 웹훅 CLI 명령 `create-batch-of-images` 및 `create-batch-of-videos` 는 다음을 지원합니다: | 플래그 | 설명 | | --------------------------------------- | ------------------- | | `--notifications-url ` | 알림용 웹훅 엔드포인트. | | `--notification-category ingest-status` | 전체 수집 프로세스 상태. 기본값. | | `--notification-category files-status` | 개별 파일 처리 상태. | 알림은 다음 헤더가 포함된 HTTP POST를 통해 전달됩니다. `Authorization` 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 \ --batch-id \ --notifications-url ``` **작업 완료 알림** ```json { "type": "roboflow-batch-job-notification-v1", "event_id": "8f42708b-aeb7-4b73-9d83-cf18518b6d81", "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 ```