로깅 및 디버깅

상세 로깅을 활성화하고, HTTP 요청을 검사하고, 일반적인 SDK 오류를 진단하세요.

SDK가 예상치 못한 일을 할 때, 그 이유를 알아내는 가장 빠른 방법은 보통 내부의 HTTP 요청과 응답을 살펴보는 것입니다.

자세한 요청 로깅 활성화

SDK는 Python의 표준 로깅 모듈과 requests 라이브러리를 하위에서 사용합니다. SDK가 만드는 모든 HTTP 요청을 보려면:

import logging
import http.client as http_client

http_client.HTTPConnection.debuglevel = 1
logging.basicConfig(level=logging.DEBUG)
logging.getLogger("urllib3").setLevel(logging.DEBUG)
logging.getLogger("urllib3").propagate = True

그러면 각 요청 라인, 헤더(SDK가 가리는 부분은 가려진 상태로), 그리고 응답 상태가 출력됩니다. 이 기능을 켠 상태로 SDK 호출을 한 번만 실행하면 실제로 무엇이 전송되는지 정확히 볼 수 있습니다.

실패한 단일 호출 검사

전역 로깅을 활성화하지 않고 한 번의 호출을 검사하려면, 어댑터를 직접 사용하세요. 다음의 모든 고수준 메서드는 워크스페이스 / 프로젝트 / 버전 최종적으로 다음의 함수 중 하나를 호출합니다: roboflow.adapters.rfapi (또는 deploymentapi, vision_events_api); 이를 직접 호출하면 원시 응답을 반환하며, 고수준 메서드가 수행하는 후처리는 건너뜁니다:

from roboflow.adapters import rfapi

response = rfapi.get_workflow("YOUR_API_KEY", workspace_url="my-workspace", workflow_url="slow-webhooks")
print(response)

고수준 호출에서 예외가 발생했다면, 같은 어댑터 호출도 보통 다음 예외를 발생시킵니다: RoboflowError 이 예외의 문자열은 서버의 응답 본문을 그대로 담고 있어, 고수준 메서드가 감쌀 수 있는 잘못된 요청 오류를 진단하는 데 유용합니다.

흔한 오류

RoboflowError: 401

인증 실패. 다음 중 하나입니다:

• ROBOFLOW_API_KEY 가 설정되지 않았거나,

• 에 전달된 키가 Roboflow(api_key=...) 잘못되었거나,

• 키는 유효하지만 해당 작업에 필요한 범위를 포함하지 않거나. 다음을 참조하세요: 범위 지정 API 키.

RoboflowError: 404

리소스를 찾을 수 없습니다. workspace / project / version 슬러그가 웹 앱의 URL 표시줄에 있는 값과 일치하는지 확인하세요. 슬러그는 항상 표시 이름과 일치하지 않으며, SDK는 전체에서 슬러그를 사용합니다.

RoboflowError: 423 Locked

작업공간이 결제 일시중지 상태입니다. 웹 앱의 결제 페이지에서 해결하거나 지원팀에 문의하세요.

RuntimeError from restore()

이 항목은 현재 휴지통에 없습니다. 이미 30일 보관 기간 후 영구적으로 삭제되었거나, 아직 작업공간에서 활성 상태입니다.

느린 업로드

Workspace.upload_dataset() 기본값은 num_workers=10입니다. 큰 데이터셋의 경우 이를 늘리세요(최대 약 25까지 - 그 이상이면 속도 제한 응답이 나타나기 시작합니다). 반대로 네트워크가 제한적이거나 인프라를 공유하는 경우에는 줄이세요.

ImportError on roboflow-slim

roboflow-slim 는 Pillow, NumPy, OpenCV, Matplotlib을 포함하지 않습니다. 다음에서 import하거나 roboflow.models.* 를 호출하거나 .predict(...).save(...)-스타일 시각화 헬퍼를 사용하려면 전체 roboflow 패키지를 설치하세요.

소스에서 어디를 볼지

스택 추적이 다음을 가리키면 roboflow.core.workspace.py 또는 roboflow.adapters.rfapi, 해당 GitHub 소스는 검색이 가능하고 메서드도 짧습니다. 메서드의 정확한 시그니처는 어댑터 docstring이 기준입니다.

버그 신고

다음에서 이슈를 열 때 github.com/roboflow/roboflow-python에 다음을 포함하세요:

• roboflow.__version__

• 사용 중인 Python 버전

• 최소 재현 예제(API 키는 가린 상태로)

• 전체 추적 정보 또는 위에서 설명한 자세한 로깅 출력

HTTP 요청 / 응답이 포함된 이슈는 보통 한 번의 왕복으로 해결할 수 있습니다. 포함되지 않은 이슈는 이를 수집하기 위한 추가 후속 확인이 필요한 경우가 많습니다.