적합한 도구 선택하기

CLI, Python SDK 또는 REST API를 언제 사용해야 하는지.

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

한눈에 보기

	CLI	Python SDK	REST API
적합한 대상	임시 스크립트, AI 에이전트, 셸 자동화	노트북, 예약 작업, Python 애플리케이션	비-Python 서비스, 웹훅, 엣지 장치
인증	ROBOFLOW_API_KEY 환경 변수 또는 roboflow login	에 전달된 API 키 Roboflow(...) 또는 ROBOFLOW_API_KEY	api_key= 쿼리 파라미터 또는 본문 필드
출력	기본적으로 보기 좋은 표, --json 스크립팅용	Python 딕셔너리와 객체	JSON
설치	pip install roboflow	pip install roboflow	None
지원 범위	SDK를 추적; 에이전트 친화적	REST와 동일하지만 편의 도우미가 추가됨	공식 경로 - 모든 기능은 여기에서 먼저 제공됩니다
오류	종료 코드(0 / 1 / 2 / 3) + stderr의 JSON 오류 본문	Python 예외	HTTP 상태 코드 + JSON 오류 본문

CLI를 사용할 때

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

구체적으로:

• 프로토타입을 만들고 있으며 Python을 작성하지 않고도 빠르게 결과를 보고 싶습니다.

• Roboflow 작업을 다른 도구에 파이프하고 싶습니다(roboflow project list --json | jq …).

• Claude Code, Cursor 같은 AI 코딩 에이전트를 사용 중입니다. CLI의 구조화된 JSON 출력과 안정적인 종료 코드는 Python REPL보다 에이전트가 소비하기 쉽습니다.

• 다음을 작성하고 있습니다 Makefile, 이미지 업로드, 학습 시작, 또는 데이터셋 다운로드를 수행하는 GitHub Action이나 셸 스크립트.

다음을 참조하세요 CLI.

Python SDK를 사용할 때

이미 Python 환경에 있고 다음이 필요하다면 SDK를 사용하세요 타입이 있는 객체, 관용적 도우미, 그리고 호출 간 상태. SDK는 REST API 위에 얇게 감싼 래퍼이지만, 다음을 추가합니다:

• 워크스페이스 / 프로젝트 / 버전 / 모델 탐색 가능한 메서드를 가진 객체.

• 동시 업로드(upload_dataset(num_workers=10)).

• 예측 시각화 도우미(전체 roboflow 패키지가 설치된 경우 - 아닐 roboflow-slim).

• 추론과 업로드를 결합하는 능동 학습 루프.

• vision-events 수집에 직접 접근.

구체적으로:

• Jupyter 노트북에서 데이터셋을 반복 작업 중입니다.

• 필요할 때 업로드, 학습, 또는 추론을 실행하는 Python 서비스를 구축 중입니다.

• 작업을 연결해야 합니다(업로드 → 학습 → 준비 완료 대기 → 예측).

• 기존 Python 앱에 Roboflow를 통합하고 있습니다.

다음을 참조하세요 Python SDK.

REST API를 사용할 때

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

구체적으로:

• JavaScript / TypeScript / Go / Rust 클라이언트를 구축 중입니다.

• 커스텀 펌웨어가 실행되는 웹캠이나 센서에서 이벤트를 전송 중입니다.

• Zapier / n8n / 노코드 자동화 도구와 통합해야 합니다.

• 특정 기능이 SDK에 들어오기 전에 REST API에 먼저 출시됩니다.

다음을 참조하세요 REST API.

도구 혼합하기

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

• CI/CD 데이터셋을 업로드하고 학습을 시작하는 데 CLI를 사용합니다.

• Python 데이터 파이프라인 학습 결과에 반응하고 모델 버전을 조정하는 데 SDK를 사용합니다.

• 프로덕션 앱 추론을 실행하고 이벤트를 전송하는 데 REST API를 사용합니다.

동일한 작업 공간과 API 키가 세 가지 모두에 대해 인증되므로 자격 증명이 늘어나지 않습니다.

추론은 특별합니다

훈련된 모델을 이미지나 비디오에 실행할 때, 이 세 가지 외에도 추가 선택지가 있습니다. 호스팅 추론은 Roboflow Serverless Hosted API 에서 serverless.roboflow.com에서 실행되며; 더 높은 처리량 또는 온프레미스 사용 사례는 Roboflow Inference (자체 호스팅) 및 전용 배포 (관리형 GPU 머신)을 참조하세요.

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