API Keys#

Ultralytics Platform API 키를 사용하면 원격 학습, 추론 및 자동화를 위한 안전한 프로그래밍 방식 액세스가 가능합니다. 다양한 사용 사례에 맞게 AES-256-GCM 암호화가 적용된 이름 지정된 키를 생성하세요.

API 키 생성#

새 API 키 생성:

1. Settings > API Keys로 이동하십시오.
2. Create Key를 클릭하십시오.
3. 키 이름(예: "Training Server")을 입력하십시오.
4. Create Key를 클릭하십시오.

키 이름#

키에 설명적인 이름을 지정하십시오:

• training-server - 원격 학습 머신용
• ci-pipeline - CI/CD 통합용
• local-dev - 로컬 개발용

키 표시#

생성 후, 키가 확인 대화상자에 표시됩니다:

키 형식#

API 키는 다음 형식을 따릅니다:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

• 접두사: ul_은 Ultralytics 키를 식별합니다.
• Body: 40개의 무작위 16진수 문자
• Total: 43자

키 보안#

• 키는 AES-256-GCM 암호화로 저장되며, 평문으로 저장되지 않습니다.
• 처음 11개 문자(ul_ 및 8개의 16진수 문자)는 표시용 접두사 역할을 하므로, 키를 노출하지 않고도 식별할 수 있습니다.

API 키 사용#

환경 변수#

키를 환경 변수로 설정하십시오:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

YOLO CLI를 사용하여 키를 검증하고 저장합니다:

yolo login YOUR_API_KEY

yolo logout(으)로 저장된 키를 제거합니다.

HTTP 헤더#

API 요청에 키를 포함하십시오:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/...

또는 pip install "ultralytics-platform>=0.1.5" Python SDK에 전달하면 ULTRALYTICS_API_KEY도 읽습니다:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

사용 가능한 모든 엔드포인트는 REST API Reference를 참조하세요.

원격 학습(Remote Training)#

키로 메트릭 스트리밍을 활성화하십시오.

시작하기 전에 Ultralytics 패키지를 설치하거나 업데이트하세요:

pip install -U ultralytics

export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1

전체 원격 학습 가이드는 Cloud Training을 참조하세요.

키 관리#

키 보기#

모든 키는 Settings > API Keys 탭에 나열됩니다.

각 키 카드에는 키 이름, 복사 가능한 키 값, 상대적인 생성 시간, 그리고 해지 버튼이 표시됩니다.

키 취소#

손상되었거나 더 이상 필요하지 않은 키를 취소하십시오:

1. API Keys 섹션에서 해당 키를 찾으십시오.
2. Revoke(휴지통) 버튼을 클릭하십시오.
3. 취소를 확인하십시오.

키 재생성#

키가 손상된 경우:

1. 같은 이름으로 새 키를 생성하십시오.
2. 애플리케이션을 업데이트하십시오.
3. 이전 키를 취소하십시오.

워크스페이스 API 키#

API 키는 현재 활성화된 워크스페이스에 한정됩니다:

• 개인 워크스페이스: 키가 개인 계정으로 인증됩니다.
• 팀 워크스페이스: 키는 팀 워크스페이스 소유자 권한으로 인증되며, 해당 워크스페이스에서 전체 소유자 권한을 가집니다.

사이드바에서 워크스페이스를 전환할 때, API 키 섹션에는 해당 워크스페이스의 키가 표시됩니다. 워크스페이스 키에는 소유자 권한이 수반되므로, 오직 워크스페이스 소유자만 키를 생성, 조회 또는 해지할 수 있습니다. 역할에 대한 자세한 내용은 팀을 참조하세요.

온프레미스 워커 키#

온프레미스 호스트를 연결하면 별도의 워커 키가 발급됩니다. 워커 키는 이 탭이 아니라 온프레미스 연동을 통해 관리되며, API 키와 함께 나열되지 않고, 호스트를 연결 해제함으로써 해지됩니다(이 경우 해당 호스트의 대기 중 및 실행 중인 작업도 취소됩니다).

보안 모범 사례#

권장 사항(Do)#

• 키를 환경 변수에 저장하십시오.
• 환경별로 별도의 키를 사용하십시오.
• 사용하지 않는 키는 즉시 취소하십시오.
• 주기적으로 키를 순환시키십시오.
• 설명적인 이름을 사용하여 키 용도를 식별하십시오.

금지 사항(Don't)#

• 키를 버전 관리 시스템에 커밋하지 마십시오.
• 애플리케이션 간에 키를 공유하지 마십시오.
• 애플리케이션 출력에 키를 기록하지 마십시오.
• 클라이언트 측 코드에 키를 포함하지 마십시오.

키 순환#

보안을 위해 주기적으로 키를 순환시키십시오:

1. 같은 이름으로 새 키를 생성하십시오.
2. 새 키를 사용하도록 애플리케이션을 업데이트하십시오.
3. 애플리케이션이 올바르게 작동하는지 확인하십시오.
4. 이전 키를 취소하십시오.

문제 해결#

유효하지 않은 키 오류#

Error: Invalid API key

해결 방법:

1. 키가 올바르게 복사되었는지 확인하세요(ul_ 접두사 포함).
2. 키가 취소되지 않았는지 확인하십시오.
3. 환경 변수가 설정되었는지 확인하십시오.
4. ultralytics>=8.4.120을(를) 사용하고 있는지 확인하세요.

권한 거부#

Error: Permission denied for this operation

해결 방법:

1. 리소스 소유자이거나 적절한 워크스페이스 액세스 권한이 있는지 확인하십시오.
2. 키가 올바른 워크스페이스에 속해 있는지 확인하십시오.
3. 팀 워크스페이스에서 키를 관리하는 경우, 자신이 워크스페이스 소유자인지 확인하세요. 다른 역할에는 Workspace owner access required이 표시됩니다.
4. 필요한 경우 새 키를 생성하십시오.

속도 제한#

Error: Rate limit exceeded

해결 방법:

1. 요청 빈도를 줄이세요. 카테고리별 한도는 요청 제한 표를 참조하세요.
2. Retry-After 헤더를 사용하여 지수 백오프를 구현하세요.
3. 격리된 추론 용량이 필요할 때는 dedicated endpoint를 사용하세요.

FAQ#