본문으로 건너뛰기
For the complete documentation index, see llms.txt. This page is also available as Markdown.

배치 처리

클라우드 인프라를 제공받아 대규모 이미지와 저장된 비디오 배치에 워크플로를 실행합니다.

개요

배치 처리는 다음을 실행하는 비용 효율적인 방법입니다. 워크플로 이미지 배치와 저장된 동영상에 적용할 수 있습니다. 대량의 데이터를 비동기적으로 처리하는 데 적합합니다.

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

배치 처리는 Roboflow 크레딧 시스템을 이용하는 모든 워크스페이스와 Enterprise 플랜에서 사용할 수 있습니다. "Batch Processing" 탭에서 작업을 시작하거나, 에셋 라이브러리.

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

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

작업은 CPU 또는 GPU 머신에서 실행됩니다. GPU 작업은 더 빠르지만 비용이 더 많이 듭니다. 자세한 내용은 크레딧 페이지를 참조하세요. CPU 및 GPU 요금입니다. 작업에 걸리는 시간은 처리하는 이미지 또는 동영상의 수, Workflow의 복잡도, 머신 유형에 따라 달라집니다. 일반적인 문제는 문제 해결.

다음 동영상에서 일괄 처리를 자세히 설명합니다:

웹 앱

왼쪽 사이드바에서 "배포"를 열고 "일괄 처리" 탭을 선택합니다.

"새 일괄 작업"을 클릭하고 다음 단계를 따릅니다:

  1. 다음을 선택합니다: Workflow.

  2. 처리할 이미지 또는 동영상을 업로드합니다.

  3. CPU 또는 GPU 하드웨어를 선택합니다. 변경할 필요가 없다면 "고급 옵션"은 기본값으로 둡니다.

  4. "일괄 작업 만들기"를 클릭합니다.

작업 목록에는 각 작업의 진행 상황이 실시간으로 표시됩니다. 이 탭에서 시작한 작업은 나만 볼 수 있는 활동 센터에도 표시됩니다. 작업을 클릭하면 세부 정보를 확인할 수 있습니다. "소스 및 유형"에는 작업이 실행된 이미지가 표시됩니다. 다음 중 하나로 확인할 수 있습니다. 에셋 라이브러리 이미지를 선택한 검색어(에셋 라이브러리에서 열기 링크 포함) 또는 직접 선택한 이미지 수가 표시됩니다.

에셋 라이브러리에서

에셋 라이브러리에서 에셋 라이브러리, 이미지를 선택하거나 검색 조건에 맞는 이미지를 모두 선택한 다음 "워크플로 실행"을 클릭합니다. 전체 과정과 결과를 이미지에 다시 기록하는 방법은 워크플로 실행하기 에서 확인하세요.

에이전트에서

질문 Roboflow 에이전트 에게 Asset Library 이미지에서 게시된 Workflow를 실행하도록 요청하세요. 직접 선택한 이미지, 검색 조건과 일치하는 이미지 또는 전체 라이브러리에서 실행할 수 있습니다. 작업 현황을 알려 달라고 할 수도 있으며, 작업이 완료되면 채팅으로 알려 줍니다. 에이전트가 시작한 작업은 백그라운드 작업에도 표시됩니다.

에이전트는 Batch Processing을 채팅 탭으로 열 수도 있습니다. 새 작업 양식에 에이전트가 합의한 Workflow와 설정을 입력하지만, 컴퓨터에서 파일을 직접 선택해야 합니다.

데이터 소스 미러링 시 자동 실행

다음이 데이터 소스 미러링될 때마다 Batch Processing 작업이 새로 가져온 이미지에 Workflow를 실행할 수 있습니다(예: 태그나 사전 라벨을 최신 상태로 유지). 의 "Workflow runs" 섹션에서 데이터 소스 페이지에서 "Add workflow run"을 클릭합니다. "Run when"에서 "On Sync"를 선택하고, 이를 트리거할 데이터 소스를 선택합니다. Workflow에는 정확히 하나의 image 입력.

"워크플로 실행" 섹션이 보이지 않으면 배치 자동화를 관리할 수 있는 역할을 Workspace 관리자에게 요청하세요.

결과를 검색할 수 있도록 하려면 다음을 참조하세요. 결과를 Asset Library에 다시 쓰기.

HTTP API

빠른 링크:

데이터 수집

동영상 업로드

Upload a video

post

Request a signed URL to upload a video file. After receiving the response, PUT the video to the uploadURL with the provided extensionHeaders.

Authorizations
api_keystringRequired

Your Roboflow API key.

Path parameters
workspacestringRequired

Your Roboflow workspace identifier.

batch_idstring · max: 64Required

Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$
Query parameters
fileNamestringRequired

Name of the video file (e.g. my_video.mp4).

Responses
200

Signed URL details for uploading the video.

application/json
statusstringOptionalExample: ok
post/data-staging/v1/external/{workspace}/batches/{batch_id}/upload/video
POST /data-staging/v1/external/{workspace}/batches/{batch_id}/upload/video?fileName=text HTTP/1.1
Host: api.roboflow.com
Accept: */*
200

Signed URL details for uploading the video.

{
  "status": "ok",
  "signedURLDetails": {
    "uploadURL": "text",
    "method": "PUT",
    "extensionHeaders": {
      "Content-Type": "application/octet-stream",
      "x-goog-content-length-range": "1,1073741824"
    },
    "maxFileSize": 1073741824
  }
}

이미지 업로드

Upload a single image

post

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.

Authorizations
api_keystringRequired

Your Roboflow API key.

Path parameters
workspacestringRequired

Your Roboflow workspace identifier.

batch_idstring · max: 64Required

Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$
Query parameters
fileNamestringRequired

Name of the image file.

Body
filestring · binaryOptional

The image file to upload.

Responses
200

Image uploaded successfully.

application/json
statusstringOptionalExample: ok
post/data-staging/v1/external/{workspace}/batches/{batch_id}/upload/image
POST /data-staging/v1/external/{workspace}/batches/{batch_id}/upload/image?fileName=text HTTP/1.1
Host: api.roboflow.com
Content-Type: multipart/form-data
Accept: */*
Content-Length: 17

{
  "file": "binary"
}
200

Image uploaded successfully.

{
  "status": "ok"
}

이미지 일괄 업로드

Bulk upload images

post

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.

Authorizations
api_keystringRequired

Your Roboflow API key.

Path parameters
workspacestringRequired

Your Roboflow workspace identifier.

batch_idstring · max: 64Required

Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$
Responses
200

Signed URL details for uploading a tar archive.

application/json
statusstringOptionalExample: ok
post/data-staging/v1/external/{workspace}/batches/{batch_id}/bulk-upload/image-files
POST /data-staging/v1/external/{workspace}/batches/{batch_id}/bulk-upload/image-files HTTP/1.1
Host: api.roboflow.com
Accept: */*
200

Signed URL details for uploading a tar archive.

{
  "status": "ok",
  "signedURLDetails": {
    "shardId": "123e4567-e89b-12d3-a456-426614174000",
    "uploadURL": "text",
    "method": "PUT",
    "extensionHeaders": {
      "Content-Type": "application/x-tar",
      "x-goog-content-length-range": "1,536870912"
    },
    "maxNumberOfImages": 500,
    "maxShardSize": 536870912
  }
}

배치 상태 확인

Get batch item count

get

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

Authorizations
api_keystringRequired

Your Roboflow API key.

Path parameters
workspacestringRequired

Your Roboflow workspace identifier.

batch_idstring · max: 64Required

Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$
Responses
200

Batch item count.

application/json
statusstringOptionalExample: ok
countintegerOptional

Number of items in the batch.

Example: 42
get/data-staging/v1/external/{workspace}/batches/{batch_id}/count
GET /data-staging/v1/external/{workspace}/batches/{batch_id}/count HTTP/1.1
Host: api.roboflow.com
Accept: */*
200

Batch item count.

{
  "status": "ok",
  "count": 42
}

샤드 업로드 세부 정보 확인

List batch shards

get

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

Authorizations
api_keystringRequired

Your Roboflow API key.

Path parameters
workspacestringRequired

Your Roboflow workspace identifier.

batch_idstring · max: 64Required

Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$
Query parameters
nextPageTokenstringOptional

Pagination token from a previous response.

Responses
200

Paginated list of batch shards.

application/json
statusstringOptionalExample: ok
shardsobject[]Optional

List of shard objects.

nextPageTokenstring · nullableOptional

Token for fetching the next page of results. null if no more pages.

get/data-staging/v1/external/{workspace}/batches/{batch_id}/shards
GET /data-staging/v1/external/{workspace}/batches/{batch_id}/shards HTTP/1.1
Host: api.roboflow.com
Accept: */*
200

Paginated list of batch shards.

{
  "status": "ok",
  "shards": [
    {}
  ],
  "nextPageToken": "text"
}

작업 시작

Start a batch processing job

post

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.

Authorizations
api_keystringRequired

Your Roboflow API key.

Path parameters
workspacestringRequired

Your Roboflow workspace identifier.

job_idstring · max: 20Required

Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$
Body
typestring · enumRequired

Job type.

Possible values:
processingTimeoutSecondsintegerOptional

Maximum cumulative machine runtime in seconds across all parallel workers.

Default: 3600
notificationsURLstring · uriOptional

Webhook URL for job completion notifications. Custom webhook headers are not yet supported. The only header sent is Authorization: Bearer rf_{workspace_id}.

Responses
200

Job started successfully.

application/json
statusstringOptionalExample: ok
post/batch-processing/v1/external/{workspace}/jobs/{job_id}
POST /batch-processing/v1/external/{workspace}/jobs/{job_id} HTTP/1.1
Host: api.roboflow.com
Content-Type: application/json
Accept: */*
Content-Length: 415

{
  "type": "simple-image-processing-v1",
  "jobInput": {
    "type": "staging-batch-input-v1",
    "batchId": "text"
  },
  "computeConfiguration": {
    "type": "compute-configuration-v2",
    "machineType": "cpu",
    "workersPerMachine": 4
  },
  "processingTimeoutSeconds": 3600,
  "processingSpecification": {
    "type": "workflows-processing-specification-v1",
    "workspace": "text",
    "workflowId": "text",
    "aggregationFormat": "jsonl"
  },
  "notificationsURL": "https://example.com"
}
200

Job started successfully.

{
  "status": "ok"
}

작업 진행 상황 모니터링

작업 상태 가져오기

Get job status

get

Returns the current status of a batch processing job.

Authorizations
api_keystringRequired

Your Roboflow API key.

Path parameters
workspacestringRequired

Your Roboflow workspace identifier.

job_idstring · max: 20Required

Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$
Responses
200

Job status details.

application/json
statusstringOptionalExample: ok
jobStatusstringOptional

Current job status (e.g. pending, processing, completed, failed).

progressnumberOptional

Processing progress as a fraction between 0 and 1.

get/batch-processing/v1/external/{workspace}/jobs/{job_id}
GET /batch-processing/v1/external/{workspace}/jobs/{job_id} HTTP/1.1
Host: api.roboflow.com
Accept: */*
200

Job status details.

{
  "status": "ok",
  "jobStatus": "text",
  "progress": 1
}

작업 단계 목록

List job stages

get

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

Authorizations
api_keystringRequired

Your Roboflow API key.

Path parameters
workspacestringRequired

Your Roboflow workspace identifier.

job_idstring · max: 20Required

Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$
Responses
200

List of job stages.

application/json
statusstringOptionalExample: ok
stagesobject[]Optional

List of stage objects. Each stage has an ID and an output batch ID.

get/batch-processing/v1/external/{workspace}/jobs/{job_id}/stages
GET /batch-processing/v1/external/{workspace}/jobs/{job_id}/stages HTTP/1.1
Host: api.roboflow.com
Accept: */*
200

List of job stages.

{
  "status": "ok",
  "stages": [
    {}
  ]
}

단계 태스크 목록

List tasks for a stage

get

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

Authorizations
api_keystringRequired

Your Roboflow API key.

Path parameters
workspacestringRequired

Your Roboflow workspace identifier.

job_idstring · max: 20Required

Job identifier. Lowercase, max 20 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$
stage_idstringRequired

The stage identifier.

Query parameters
nextPageTokenstringOptional

Pagination token from a previous response.

Responses
200

Paginated list of tasks.

application/json
statusstringOptionalExample: ok
tasksobject[]Optional

List of task objects.

nextPageTokenstring · nullableOptional

Token for fetching the next page of results. null if no more pages.

get/batch-processing/v1/external/{workspace}/jobs/{job_id}/stages/{stage_id}/tasks
GET /batch-processing/v1/external/{workspace}/jobs/{job_id}/stages/{stage_id}/tasks HTTP/1.1
Host: api.roboflow.com
Accept: */*
200

Paginated list of tasks.

{
  "status": "ok",
  "tasks": [
    {}
  ],
  "nextPageToken": "text"
}

결과 내보내기

출력 파트 목록

List output batch parts

get

Lists the parts of an output batch. Use the export stage output batch for compressed results.

Authorizations
api_keystringRequired

Your Roboflow API key.

Path parameters
workspacestringRequired

Your Roboflow workspace identifier.

batch_idstring · max: 64Required

Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$
Responses
200

List of batch parts.

application/json
statusstringOptionalExample: ok
get/data-staging/v1/external/{workspace}/batches/{batch_id}/parts
GET /data-staging/v1/external/{workspace}/batches/{batch_id}/parts HTTP/1.1
Host: api.roboflow.com
Accept: */*
200

List of batch parts.

{
  "status": "ok",
  "parts": [
    {
      "partName": "text"
    }
  ]
}

다운로드 URL 목록

List download URLs

get

Returns paginated download URLs for files in a batch part.

Authorizations
api_keystringRequired

Your Roboflow API key.

Path parameters
workspacestringRequired

Your Roboflow workspace identifier.

batch_idstring · max: 64Required

Batch identifier. Lowercase, max 64 chars: letters, digits, hyphens, underscores.

Pattern: ^[a-z0-9_-]+$
Query parameters
nextPageTokenstringOptional

Pagination token from a previous response.

partNamestringOptional

Filter by part name (from the list parts response).

Responses
200

Paginated list of download URLs.

application/json
statusstringOptionalExample: ok
nextPageTokenstring · nullableOptional

Token for fetching the next page of results. null if no more pages.

get/data-staging/v1/external/{workspace}/batches/{batch_id}/list
GET /data-staging/v1/external/{workspace}/batches/{batch_id}/list HTTP/1.1
Host: api.roboflow.com
Accept: */*
200

Paginated list of download URLs.

{
  "status": "ok",
  "filesMetadata": [
    {
      "downloadURL": "text",
      "fileName": "text",
      "partName": "text",
      "shardId": "text",
      "contentType": "text",
      "nestedContentType": "text"
    }
  ],
  "nextPageToken": "text"
}

웹훅 알림

상태를 폴링하는 대신 웹훅을 사용해 데이터 수집 또는 처리가 완료될 때 알림을 받을 수 있습니다. 웹훅 구성 및 페이로드 형식은 CLI 사용법 을 참조하세요.

CLI

inference rf-cloud inference rf-cloud 를 사용해 로컬 또는 클라우드 이미지와 동영상을 준비하고 처리하세요. 이미 에셋 라이브러리에 있는 이미지에는 roboflow batch.

를 사용하세요.

설정

로컬 파일 또는 클라우드 파일의 경우 Inference CLI를 설치하세요:

클라우드 스토리지를 지원하려면:

API 키를 찾는 데 도움이 필요하면 인증 가이드.

데이터 수집

이미지

동영상

배치 ID는 소문자로 입력하고, 길이는 최대 64자여야 합니다. 사용할 수 있는 문자는 영문자, 숫자, 하이픈(-), 밑줄(_).

클라우드 스토리지

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

이미지의 경우:

동영상의 경우:

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

제공자
경로 형식
글로브 예시

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: 2024-* 폴더의 MP4 파일

Azure Blob Storage

az://container-name/path/

az://container/images/*.png: images 폴더의 PNG 파일

클라우드 스토리지 자격 증명은 CLI에서 프리사인 URL을 생성하는 데 로컬에서만 사용됩니다. Roboflow 서버로 업로드되지 않습니다.

대용량 데이터 세트의 경우 시스템이 이미지를 각각 20,000개 파일로 구성된 청크로 자동 분할합니다. 동영상은 1,000개 미만으로 배치하는 것이 가장 좋습니다.

서명된 URL 수집

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

플래그
설명

--data-source references-file

서명된 URL로 참조된 파일을 처리합니다.

--references <path_or_url>

파일 URL이 포함된 JSONL 파일의 경로 또는 해당 파일을 가리키는 서명된 URL입니다.

참조 파일은 다음을 사용합니다 JSONL:

서명된 URL을 통한 수집 기능은 Enterprise 및 이전 Growth 요금제에서 사용할 수 있습니다.

스테이징된 데이터 검사

작업 시작

이미지 처리

동영상 처리

Workflow ID를 찾으려면 Roboflow 앱에서 Workflow Editor를 열고 "Deploy"를 클릭한 다음, 코드 스니펫에서 식별자를 확인하세요.

기본적으로 처리는 CPU에서 실행됩니다. 여러 개의 모델이나 대형 모델을 사용하는 Workflow에는 --machine-type gpu 를 사용하세요.

작업 진행 상황 모니터링

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

결과 내보내기

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

웹후크 자동화

상태를 폴링하는 대신 웹후크를 사용하면 수집 또는 처리가 완료될 때 알림을 받을 수 있습니다.

데이터 수집 웹후크

CLI 명령어 create-batch-of-images 및 create-batch-of-videos 은 다음 옵션을 지원합니다:

플래그
설명

--notifications-url <webhook_url>

알림을 받을 웹후크 엔드포인트입니다.

--notification-category ingest-status

전체 데이터 수집 프로세스 상태입니다. 기본값입니다.

--notification-category files-status

개별 파일 처리 상태입니다.

알림은 다음을 포함하는 HTTP POST로 전송됩니다: Authorization 헤더에는 Roboflow 게시 가능 키가 포함됩니다.

수집 상태 알림

파일 상태 알림

작업 완료 웹후크

추가 --notifications-url 작업을 시작할 때:

작업 완료 알림

클라우드 스토리지 인증

AWS S3 및 S3 호환 스토리지

자격 증명은 다음 위치에서 자동으로 검색됩니다:

  1. 환경 변수:

  1. AWS 자격 증명 파일(~/.aws/credentials, ~/.aws/config)

  2. IAM 역할(EC2, ECS, Lambda)

이름이 지정된 프로필:

S3 호환 서비스(예: Cloudflare R2, MinIO)의 경우:

Google Cloud Storage

자격 증명은 다음 위치에서 검색됩니다:

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

  1. gcloud CLI의 사용자 자격 증명(gcloud auth login)

  2. GCP 메타데이터 서비스(Google Cloud Platform에서 실행 중인 경우)

Azure Blob Storage

SAS 토큰(권장):

계정 키:

Azure CLI를 사용해 SAS 토큰을 생성합니다. 다음을 <expiry-utc> 미래의 UTC 시간으로 바꾸고 YYYY-MM-DDTHH:MMZ 형식을 사용합니다:

사용자 지정 스크립트

고급 사용 사례에서는 서명된 URL 파일을 생성하는 참조 스크립트를 확인하세요:

모든 옵션 살펴보기

에셋 라이브러리 이미지

바꾸기 <workspace-url> 을(를) 워크스페이스 슬러그로 바꿉니다(예: my-workspace). image 입력이 하나 있는 게시된 워크플로를 선택합니다. 기타 필수 입력에는 기본값을 지정하되, 배치 처리에서 이미지마다 채우는 image 입력은 제외합니다. 배치 처리에서 이미지마다 채우는 source_id는 예외입니다.

Roboflow CLI를 설치하거나 업데이트한 다음로그인하고 워크플로 목록을 확인합니다:

게시된 워크플로의 JSON 출력에서 id 를 사용합니다. 처리할 이미지를 RoboQL 검색으로 찾습니다:

검색 결과의 이미지 ID를 --image-ids:

구조화된 필터와 일치하는 모든 이미지를 처리하려면 --image-ids 를 --query "tag:night-shift"로 바꿉니다. 에셋 라이브러리 전체를 처리하려면 --all 을 사용합니다. 선택 옵션은 정확히 하나만 선택합니다.

생성 응답에는 taskId, jobId및 requestId가 포함됩니다. 작업이 완료될 때까지 기다리려면 태스크 ID를 사용하고, 작업을 확인하려면 작업 ID를 사용합니다:

터미널을 닫거나 대기 명령이 시간 초과되더라도 작업은 계속 실행됩니다. 네트워크 오류가 발생하면 동일한 옵션으로 다시 시도하세요. 중복 작업이 생성되지 않도록 requestId 값을 응답 또는 오류 안내에서 가져와 --request-id <request-id> 로 전달하세요.

작업을 중지하려면 batch abort <job-id> 를 사용하고, 기존 구성으로 다시 시도하려면 batch restart <job-id> 를 사용하세요. 두 명령 모두 확인을 요청하므로 스크립트에서 사용하려면 --yes 를 추가하세요. 작업을 다시 시작하면 크레딧이 소모될 수 있습니다.

마지막 업데이트

도움이 되었나요?