> 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/workflows/ko/manage/manage-workflows.md).

# Workflows 관리

## 소개

[Roboflow 워크플로](/workflows/ko/build/create-a-workflow.md) 는 웹 앱에서 만들고 호스팅 엔드포인트로 배포하는 시각적 컴퓨터 비전 파이프라인입니다. 이 페이지는 작업공간의 워크플로를 나열, 조회, 생성, 업데이트하는 관리 영역을 REST API와 Python SDK를 통해 다룹니다. 이미지나 비디오 스트림에 대해 워크플로를 실행하려면 다음을 참조하세요 [Workflows 런타임 문서](/workflows/ko/deploy/deploy-a-workflow.md).

## HTTP API

[Roboflow 워크플로](/workflows/ko/build/create-a-workflow.md) 는 웹 앱에서 만들고 호스팅 엔드포인트로 배포할 수 있는 시각적 컴퓨터 비전 파이프라인입니다. REST API는 관리 영역을 노출합니다. 이미지나 비디오 스트림에 대해 워크플로를 실행하려면 다음을 참조하세요 [이미지에서 모델 실행](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api#http-api) 그리고 [Workflows 런타임 문서](/workflows/ko/deploy/deploy-a-workflow.md).

`API 키` 는 쿼리 매개변수로 또는 요청 본문에 전달할 수 있습니다. 필요한 scope는 각 엔드포인트에 표시됩니다.

### 프로젝트 기본 워크플로

각 프로젝트에는 호스팅된 모델 엔드포인트를 뒷받침하는 기본 워크플로가 있습니다. 이 프로젝트 범위 작업을 사용해 해당 워크플로를 읽거나 모델 단계에서 사용할 모델을 선택하세요.

#### 프로젝트 기본 워크플로 가져오기

<mark style="color:초록색;">`GET`</mark> `/:workspace/:project/deploy`

필수 scope: `project:read`

```bash
curl "https://api.roboflow.com/my-workspace/my-project/deploy?api_key=$ROBOFLOW_API_KEY"
```

프로젝트에 기본 워크플로가 없으면 이 요청이 하나를 생성합니다. 응답에는 프로젝트, 기본 워크플로, 선택된 모델, 배포 가능 여부, 활성 학습 상태가 표시됩니다:

```json
{
  "project": {
    "id": "abc123",
    "url": "my-project",
    "name": "내 프로젝트",
    "owner": "my-workspace-id",
    "type": "object-detection",
    "classes": ["고양이", "개"],
    "multilabel": false
  },
  "workflow": {
    "id": "wf_xyz",
    "name": "내 프로젝트 기본 워크플로",
    "url": "my-project-base-workflow",
    "workspaceUrl": "my-workspace",
    "inferencePath": "/infer/workflows/my-workspace/my-project-base-workflow"
  },
  "model": {
    "id": "rfdetr-medium",
    "kind": "pretrained",
    "displayName": "RF-DETR Medium",
    "modelId": "rfdetr-medium"
  },
  "deployability": {
    "status": "배포 가능",
    "modelWasConfigured": false,
    "selectedModelId": null,
    "selectionReason": null
  },
  "activeLearning": {
    "enabled": false,
    "collectionLimits": {
      "dataPercentage": 100,
      "minutelyUsageLimit": 10,
      "hourlyUsageLimit": 100,
      "dailyUsageLimit": 1000,
      "labelingBatchesRecreationFrequency": "daily",
      "usageQuotaName": "upload_quota_active_learning",
      "imageCompressionLevel": 95,
      "maxImageHeight": 1080,
      "maxImageWidth": 1920,
      "persistPredictions": true
    },
    "filters": []
  },
  "baseWorkflowWasCreated": false
}
```

`model` 는 `null` 모델이 구성되지 않았을 때. `deployability.status` 는 `"배포 불가"` 워크플로가 추론을 제공할 수 없을 때. `baseWorkflowWasCreated` 이 요청이 기본 워크플로를 생성했는지 여부를 알려줍니다.

#### 프로젝트 기본 워크플로 모델 선택

<mark style="color:초록색;">`POST`</mark> `/:workspace/:project/deploy/model`

필수 scope: `project:update`

설정 `model.type` 을 `"model_id"`, `"sam3"`, 또는 `"clip"`:

```bash
curl -X POST "https://api.roboflow.com/my-workspace/my-project/deploy/model" \\
  -H "Content-Type: application/json" \\
  -d '{
    "api_key": "'$ROBOFLOW_API_KEY'",
    "model": {
      "type": "model_id",
      "modelId": "rfdetr-medium"
    }
  }'
```

다음의 경우 `"model_id"`, `modelId` 필수입니다. `displayName` 및 `taskType` 는 선택 사항입니다. 다음의 경우 `"sam3"` 및 `"clip"`, 비어 있지 않은 `클래스` 배열을 `modelId`:

```json
{
  "api_key": "YOUR_API_KEY",
  "model": {
    "type": "sam3",
    "classes": ["고양이", "개"]
  }
}
```

응답의 형태는 [프로젝트 기본 워크플로 가져오기](#get-a-project-base-workflow)다음과 같습니다.  `400` 응답은 `model` 값이 없거나 유효하지 않음을 의미합니다.

데이터 수집을 활성화하거나, 수집 한도를 설정하거나, 검토 대기열의 이미지를 나열하려면 [활성 학습 HTTP API](https://docs.roboflow.com/deployment/monitoring-and-analytics/active-learning#http-api).

### 워크플로 나열

<mark style="color:초록색;">`GET`</mark> `/:workspace/workflows`

워크스페이스의 모든 워크플로를 나열합니다.

**쿼리**

<table data-search="false"><thead><tr><th>이름</th><th>유형</th><th>설명</th><th data-type="checkbox">필수</th></tr></thead><tbody><tr><td><code>API 키</code></td><td>string</td><td>워크스페이스의 API 키.</td><td>true</td></tr></tbody></table>

**예제 요청**

```bash
curl "https://api.roboflow.com/my-workspace/workflows?api_key=$ROBOFLOW_API_KEY"
```

**응답**

```json
{
  "workflows": [
    {
      "id": "wf_abc123",
      "name": "느린 웹훅",
      "url": "slow-webhooks",
      "createdAt": "2026-04-12T17:05:33.000Z"
    }
  ],
  "status": "ok"
}
```

필수 scope: `workflow:read`.

### 워크플로 가져오기

<mark style="color:초록색;">`GET`</mark> `/:workspace/workflows/:workflowUrl`

워크플로의 사양, 메타데이터, 그리고(공개되지 않은 워크플로의 경우) 권한 상태를 반환합니다.

```bash
curl "https://api.roboflow.com/my-workspace/workflows/slow-webhooks?api_key=$ROBOFLOW_API_KEY"
```

공개 워크플로는 `API 키`없이 접근할 수 있습니다. 비공개 워크플로는 `workflow:read` scope가 필요합니다.

### 워크플로 버전 나열

<mark style="color:초록색;">`GET`</mark> `/:workspace/workflows/:workflowUrl/versions`

```bash
curl "https://api.roboflow.com/my-workspace/workflows/slow-webhooks/versions?api_key=$ROBOFLOW_API_KEY"
```

워크플로 사양의 버전별 스냅샷을 반환합니다.

### 워크플로 생성

<mark style="color:초록색;">`POST`</mark> `/:workspace/createWorkflow`

**헤더**

| 이름           | 값                  |
| ------------ | ------------------ |
| Content-Type | `application/json` |

**본문**

<table data-search="false"><thead><tr><th width="180">이름</th><th width="140">유형</th><th>설명</th><th data-type="checkbox">필수</th></tr></thead><tbody><tr><td><code>API 키</code></td><td>string</td><td>워크스페이스 API 키.</td><td>true</td></tr><tr><td><code>name</code></td><td>string</td><td>표시 이름.</td><td>true</td></tr><tr><td><code>url</code></td><td>string</td><td>워크플로의 URL 슬러그.</td><td>true</td></tr><tr><td><code>config</code></td><td>string</td><td>JSON으로 인코딩된 워크플로 사양(아래 참고).</td><td>true</td></tr><tr><td><code>template</code></td><td>string</td><td>JSON으로 인코딩된 템플릿 메타데이터. 없다면 <code>"{}"</code> 를 전달하세요.</td><td>false</td></tr></tbody></table>

**다음에 대한 참고 사항 `config`**: API는 저장된 형태 `{"specification": {...}}`를 기대합니다. bare specification을 전달하면 SDK 어댑터가 자동으로 감싸주지만, 직접 REST 호출을 할 경우 직접 감싸야 합니다.

**예제 요청**

```bash
curl -X POST "https://api.roboflow.com/my-workspace/createWorkflow" \\
  -H 'Content-Type: application/json' \\
  -d '{"api_key":"'$ROBOFLOW_API_KEY'","name":"내 워크플로","url":"my-workflow","config":"{\"specification\":{\"version\":\"1.0\",\"inputs\":[],\"steps\":[],\"outputs\":[]}}"}'
```

쿼리 매개변수로도 동일한 필드를 보낼 수 있지만, 그 경우 `template` 가 필요합니다. 긴 URL은 잘리므로 큰 사양은 본문을 사용하세요.

```bash
curl -X POST "https://api.roboflow.com/my-workspace/createWorkflow" \\
  --get \\
  --data-urlencode "api_key=$ROBOFLOW_API_KEY" \\
  --data-urlencode "name=내 워크플로" \\
  --data-urlencode "url=my-workflow" \\
  --data-urlencode 'config={"specification":{"version":"1.0","inputs":[],"steps":[],"outputs":[]}}' \\
  --data-urlencode 'template={}'
```

**응답**

```json
{
  "workflows": { "id": "wf_xyz789", "url": "my-workflow" },
  "status": "ok"
}
```

필수 scope: `workflow:create`.

### 워크플로 업데이트

<mark style="color:초록색;">`POST`</mark> `/:workspace/updateWorkflow`

**헤더**

| 이름           | 값                  |
| ------------ | ------------------ |
| Content-Type | `application/json` |

**본문**

<table data-search="false"><thead><tr><th>이름</th><th>유형</th><th>설명</th><th data-type="checkbox">필수</th></tr></thead><tbody><tr><td><code>id</code></td><td>string</td><td>워크플로의 내부 ID.</td><td>true</td></tr><tr><td><code>name</code></td><td>string</td><td>표시 이름.</td><td>true</td></tr><tr><td><code>url</code></td><td>string</td><td>URL 슬러그.</td><td>true</td></tr><tr><td><code>config</code></td><td>string</td><td>JSON으로 인코딩된 워크플로 사양(Create의 참고 사항 참조).</td><td>true</td></tr></tbody></table>

```bash
curl -X POST "https://api.roboflow.com/my-workspace/updateWorkflow?api_key=$ROBOFLOW_API_KEY" \\
  -H 'Content-Type: application/json' \\
  -d '{"id":"wf_xyz789","name":"내 워크플로","url":"my-workflow","config":"{\"specification\":{\"version\":\"1.0\",\"steps\":[]}}"}'
```

필수 scope: `workflow:update`.

### 워크플로 포크

<mark style="color:초록색;">`POST`</mark> `/:workspace/forkWorkflow`

다른 워크스페이스의 워크플로를 이 워크스페이스로 복사합니다.

**본문**

<table data-search="false"><thead><tr><th>이름</th><th>유형</th><th>설명</th><th data-type="checkbox">필수</th></tr></thead><tbody><tr><td><code>source_workspace</code></td><td>string</td><td>원본 워크플로를 소유한 워크스페이스의 슬러그.</td><td>true</td></tr><tr><td><code>source_workflow</code></td><td>string</td><td>원본 워크플로의 URL 슬러그.</td><td>true</td></tr><tr><td><code>name</code></td><td>string</td><td>포크의 표시 이름. 기본값은 원본 이름입니다.</td><td>false</td></tr><tr><td><code>url</code></td><td>string</td><td>포크의 URL 슬러그. 생략하면 자동 생성됩니다.</td><td>false</td></tr></tbody></table>

```bash
curl -X POST "https://api.roboflow.com/my-workspace/forkWorkflow?api_key=$ROBOFLOW_API_KEY" \\
  -H 'Content-Type: application/json' \\
  -d '{"source_workspace":"other-workspace","source_workflow":"their-workflow","name":"내 포크","url":"my-fork"}'
```

필수 scope: `workflow:create`.

### 워크플로 토큰 생성

<mark style="color:초록색;">`POST`</mark> `/:workspace/workflowToken`

공개 클라이언트(예: 브라우저)에서 워크플로를 실행하는 데 적합한 단기 토큰을 생성합니다.

```bash
curl -X POST "https://api.roboflow.com/my-workspace/workflowToken?api_key=$ROBOFLOW_API_KEY"
```

### 워크플로 삭제(소프트 삭제)

<mark style="color:빨간색;">`DELETE`</mark> `/:workspace/workflows/:workflowUrl`

워크플로를 휴지통으로 이동합니다. 다음을 참조하세요 [휴지통 관리](https://docs.roboflow.com/platform/workspaces/trash#delete-a-workflow) 응답 형태와 복원 흐름을 확인하세요.

### 워크플로 실행

워크플로 실행은 관리 API가 아니라 `https://serverless.roboflow.com`에 있습니다. 다음을 참조하세요 [이미지에서 모델 실행](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api#http-api) 및 제품 문서의 [워크플로 배포](/workflows/ko/deploy/deploy-a-workflow.md).

## Python SDK

[Roboflow 워크플로](/workflows/ko/build/create-a-workflow.md) 는 시각적 컴퓨터 비전 파이프라인입니다. SDK는 list/get/create를 `Workspace`에서 직접 노출합니다. update, fork, delete는 저수준 `rfapi` 어댑터에 있습니다.

### 워크플로 나열

```python
import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
workspace = rf.workspace()

workflows = workspace.list_workflows()
for w in workflows:
    print(w["id"], w["name"], w["url"] )
```

### 워크플로 가져오기

```python
workflow = workspace.get_workflow("slow-webhooks")
print(workflow["specification"] )
```

이 `url` 인수는 워크플로의 슬러그(웹 앱 URL 표시줄에 보이는 값)이며 Firestore id가 아닙니다.

### 워크플로 생성

```python
workflow = workspace.create_workflow(
    name="내 워크플로",
    definition={
        "version": "1.0",
        "inputs": [...],
        "steps": [...],
        "outputs": [...],
    },
)
print(workflow["id"], workflow["url"] )
```

다음을 전달하세요 `definition=None` 나중에 웹 앱에서 편집할 빈 워크플로 껍데기를 생성하려면.

SDK는 bare specification dict(`{"version": ..., "steps": ...}`) 또는 감싼 형태(`{"specification": {...}}`); 둘 다 받아들이며, 필요하면 래핑을 정규화하고 UTF-8 BOM이 있으면 제거합니다.

### 워크플로 업데이트

`Workspace` 는 업데이트를 직접 노출하지 않습니다. 저수준 어댑터를 사용하세요:

```python
from roboflow.adapters import rfapi

rfapi.update_workflow(
    api_key="YOUR_API_KEY",
    workspace_url=workspace.url,
    workflow_id=workflow["id"],
    workflow_name="내 워크플로",
    workflow_url="my-workflow",
    config={"version": "1.0", "steps": [...]},
)
```

### 워크플로 포크

다른 워크스페이스의 워크플로를 자신의 워크스페이스로 복사합니다. 공개 템플릿을 사용할 때 유용합니다:

```python
from roboflow.adapters import rfapi

forked = rfapi.fork_workflow(
    api_key="YOUR_API_KEY",
    workspace_url=workspace.url,
    source_workspace="other-workspace",
    source_workflow="their-workflow",
    name="내 포크",       # 선택 사항; 기본값은 원본 이름
    url="my-fork",        # 선택 사항; 기본값은 자동 생성된 슬러그
)
```

### 워크플로 버전 나열

```python
versions = rfapi.list_workflow_versions(
    api_key="YOUR_API_KEY",
    workspace_url=workspace.url,
    workflow_url="my-workflow",
)
```

### 워크플로 삭제(소프트 삭제)

```python
rfapi.delete_workflow(api_key="YOUR_API_KEY", workspace_url=workspace.url, workflow_url="my-workflow")
```

이렇게 하면 워크플로가 워크스페이스의 [휴지통](https://docs.roboflow.com/platform/workspaces/trash#python-sdk) 으로 이동하며, 30일 후 영구 정리됩니다. 다음을 통해 복원하세요 `Workspace.restore_from_trash("workflow", id)` - 다음을 참조하세요 [삭제 및 복원](https://docs.roboflow.com/platform/workspaces/trash#workflows).

### 워크플로 실행

워크플로 실행은 [Inference SDK](https://inference.roboflow.com) 그리고 [Workflows 런타임](/workflows/ko/deploy/deploy-a-workflow.md)에 있으며, `roboflow` 패키지에 있지 않습니다. Python에서는:

```python
from inference_sdk import InferenceHTTPClient

client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key="YOUR_API_KEY",
)
result = client.run_workflow(
    workspace_name="my-workspace",
    workflow_id="my-workflow",
    images={"image": "photo.jpg"},
)
```

## CLI

명령줄에서 워크플로를 나열, 생성, 업데이트, 포크하고 버전을 관리할 수 있습니다.

### 워크플로 나열

```bash
roboflow workflow list
```

```bash
roboflow workflow list --json
```

### 워크플로 상세 정보 가져오기

```bash
roboflow workflow get my-workflow
```

```bash
roboflow workflow get my-workflow --json
```

### 워크플로 생성

```bash
roboflow workflow create --name "내 워크플로"
```

JSON 정의 파일이 있는 경우:

```bash
roboflow workflow create --name "내 워크플로" --definition workflow.json
```

#### 옵션

| 플래그             | 설명            |
| --------------- | ------------- |
| `--name`        | 워크플로 이름(필수)   |
| `--definition`  | JSON 정의 파일 경로 |
| `--description` | 워크플로 설명       |

### 워크플로 업데이트

워크플로 정의 업데이트:

```bash
roboflow workflow update my-workflow --definition updated.json
```

### 워크플로 버전 나열

```bash
roboflow workflow version list my-workflow
```

```bash
roboflow workflow version list my-workflow --json
```

### 워크플로 포크

현재 워크스페이스의 워크플로를 포크하려면:

```bash
roboflow workflow fork my-workflow
```

다른 워크스페이스에서 포크하려면:

```bash
roboflow workflow fork other-workspace/their-workflow
```

### JSON 출력

모든 워크플로 명령은 `--json` 형식의 출력을 지원합니다:

```bash
roboflow workflow list --json | jq '.[].name'
roboflow workflow create --name "Test" --json
```

종료 코드: 0 = 성공, 1 = 오류, 2 = 인증 오류, 3 = 찾을 수 없음.