> 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/reference/ko/platform/choosing-the-right-tool.md).

# 올바른 도구 선택하기

Roboflow는 세 가지 개발자 도구를 통해 동일한 기반 플랫폼을 제공합니다. 이들은 서로 배타적이지 않으며, 대부분의 프로덕션 워크플로는 세 가지를 모두 사용합니다. 이 페이지는 빠른 의사결정 가이드입니다.

## 한눈에 보기

|            | CLI                                          | Python SDK                                        | REST API                                   |
| ---------- | -------------------------------------------- | ------------------------------------------------- | ------------------------------------------ |
| **적합한 용도** | 임시 스크립트, AI 에이전트, 셸 자동화                      | 노트북, 예약 작업, Python 애플리케이션                         | Python이 아닌 서비스, 웹훅, 엣지 디바이스                |
| **인증**     | `ROBOFLOW_API_KEY` 환경 변수 또는 `roboflow login` | API 키가 전달되는 `Roboflow(...)` 또는 `ROBOFLOW_API_KEY` | `Authorization: Bearer` 헤더(쿼리 매개변수는 기존 방식) |
| **출력**     | 기본적으로 보기 좋은 표, `--json` 스크립팅용                | Python dict와 객체                                   | JSON                                       |
| **설치**     | `pip install roboflow`                       | `pip install roboflow`                            | 없음                                         |
| **커버리지**   | SDK를 추적함; 에이전트 친화적                           | REST와 동일하며 편의 헬퍼 추가                               | 공식 기준 - 모든 기능이 여기에 먼저 제공됩니다                |
| **오류**     | 종료 코드(0 / 1 / 2 / 3) + stderr의 JSON 오류 본문    | Python 예외                                         | HTTP 상태 코드 + JSON 오류 본문                    |

## CLI를 사용할 때

무언가를 하고 싶을 때 CLI를 사용하세요 **한 번만 하거나 셸 파이프라인의 한 단계로 실행할 때**. 출력 형식과 종료 코드는 스크립팅과 AI 에이전트를 위해 설계되었습니다.

구체적으로:

* Python을 작성하지 않고 빠르게 결과를 보고 프로토타입을 만들고 있습니다.
* Roboflow 작업을 다른 도구로 파이프하고 싶습니다 (`roboflow project list --json | jq …`).
* AI 코딩 에이전트(Claude Code, Cursor)를 사용 중이라면, CLI의 구조화된 JSON 출력과 안정적인 종료 코드는 Python REPL보다 에이전트가 처리하기 쉽습니다.
* 당신은 `Makefile`, 이미지를 업로드하고, 학습을 시작하거나, 데이터셋을 다운로드하는 GitHub Action 또는 셸 스크립트를 작성하고 있습니다.

참조: [CLI](/reference/ko/platform/cli.md).

## Python SDK를 사용할 때

이미 Python 환경에 있고 다음을 원할 때 SDK를 사용하세요 **타입이 지정된 객체, 관용적인 헬퍼, 그리고 호출 간 상태**. SDK는 REST API를 감싼 얇은 래퍼이지만, 다음을 추가합니다:

* `워크스페이스` / `프로젝트` / `버전` / `모델` 탐색 가능한 메서드를 가진 객체.
* 동시 업로드 (`upload_dataset(num_workers=10)`).
* 예측 시각화 헬퍼(전체 `roboflow` 패키지가 설치된 경우 - `roboflow-slim`).
* 추론과 업로드를 결합한 능동 학습 루프.
* vision-events 수집에 직접 접근.

구체적으로:

* Jupyter 노트북에서 데이터셋을 반복 수정하고 있습니다.
* 업로드, 학습, 또는 필요 시 추론을 수행하는 Python 서비스를 구축하고 있습니다.
* 작업을 연결해야 합니다(업로드 → 학습 → 준비 완료 대기 → 예측).
* 기존 Python 앱에 Roboflow를 통합하고 있습니다.

참조: [Python SDK](/reference/ko/platform/python-sdk.md).

## REST API를 사용할 때

REST API를 사용할 때는 **Python 환경이 아닐 때**, Python 패키지를 설치할 수 없는 환경(브라우저, Cloudflare Worker, 임베디드 디바이스, 작은 zipfile을 사용하는 Lambda)에서 호출해야 하거나, 웹훅에서 Roboflow를 사용하고 싶을 때입니다.

구체적으로:

* JavaScript / TypeScript / Go / Rust 클라이언트를 만들고 있습니다.
* 커스텀 펌웨어가 실행되는 웹캠이나 센서에서 이벤트를 전송하고 있습니다.
* Zapier / n8n / 노코드 자동화 도구와 통합해야 합니다.
* 특정 기능이 SDK에 반영되기 전에 REST API에 먼저 제공됩니다.

참조: [REST API](/reference/ko/platform/rest-api.md).

## 도구 혼합 사용

실제로 팀들은 세 가지를 모두 사용합니다:

* **CI/CD** CLI를 사용해 데이터셋을 업로드하고 학습을 시작합니다.
* **Python 데이터 파이프라인** SDK를 사용해 학습 결과에 반응하고 모델 버전을 조정합니다.
* **프로덕션 앱** REST API를 사용해 추론을 실행하고 이벤트를 전송합니다.

동일한 워크스페이스와 API 키가 세 가지 모두에 대해 인증되므로, 자격 증명이 늘어나지 않습니다.

## 추론은 특별합니다

이미지나 비디오에서 학습된 모델을 실행할 때는 이 세 가지 외에 추가 선택지가 있습니다. 호스팅 추론은 [Roboflow Serverless Hosted API](https://docs.roboflow.com/deployment/roboflow-cloud/serverless-api) 에서 `serverless.roboflow.com`; 더 높은 처리량이나 온프레미스 사용 사례는 다음을 참조하세요 [Roboflow Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted) (자가 호스팅) 및 [전용 배포](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments) (관리형 GPU 머신).

CLI의 `infer` 명령, SDK의 `model.predict()`, 그리고 추론 URL에 대한 직접 REST 호출은 모두 동일한 기반 추론 엔진으로 가는 경로입니다.

추론 요청의 인증 방식도 플랫폼 REST API와 다릅니다. 추론 URL을 직접 호출할 때는 API 키를 다음의 형태로 보내세요: `Authorization: Bearer` 헤더; 헤더를 사용하면 키가 URL과 서버 로그에 남지 않습니다. 키를 다음으로 전달하는 것은 `api_key` 쿼리 매개변수나 본문 필드는 기존 채널입니다. 모든 서버 버전에서 여전히 동작하지만, 새 코드에는 권장되지 않습니다. 다음을 사용할 때 `inference-sdk`, 헤더를 직접 구성하는 대신 클라이언트에서 전송 방식을 한 번만 설정하세요: 참조 [API 키 전송](/reference/ko/inference/inference-sdk/configuration.md#api-key-transport).