API 키
Ultralytics Platform API 키는 원격 학습, 추론 및 자동화를 위한 안전한 프로그래밍 방식 액세스를 가능하게 합니다. 다양한 사용 사례에 맞춰 AES-256-GCM 암호화가 적용된 명명된 키를 생성하세요.
API 키 생성
새 API 키 생성:
- 설정 > API 키로 이동합니다.
- 키 생성을 클릭합니다.
- 키의 이름을 입력하십시오(예: "훈련 서버")
- 키 생성을 클릭합니다.
키 이름
키에 설명적인 이름을 지정합니다:
training-server- 원격 훈련 머신용ci-pipeline- CI/CD 통합용local-dev- 로컬 개발용
키 표시
생성 후 키는 한 번만 표시됩니다:
키 복사
생성 후 키를 복사하여 쉽게 참조하십시오. 키는 키 목록에서도 볼 수 있습니다. 플랫폼은 전체 키 값을 해독하여 표시하므로 언제든지 복사할 수 있습니다.
키 형식
API 키는 다음 형식을 따릅니다:
ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4
- 접두사:
ul_Ultralytics 키를 식별합니다. - 본문: 40개의 임의의 16진수 문자
- 총: 43자
키 보안
- 키들은 AES-256-GCM 암호화로 저장됩니다
- 인증은 빠른 접두사 조회 및 해시 비교를 위해 SHA-256 해시를 사용합니다.
- 전체 키 값은 절대 평문으로 저장되지 않습니다
API 키 사용
환경 변수
키를 환경 변수로 설정하세요:
export ULTRALYTICS_API_KEY="YOUR_API_KEY"
$env:ULTRALYTICS_API_KEY = "YOUR_API_KEY"
YOLO CLI
YOLO CLI를 사용하여 키를 설정하세요:
yolo settings api_key="YOUR_API_KEY"
코드 내
python 스크립트에서 키를 사용하세요:
import os
# From environment (recommended)
api_key = os.environ.get("ULTRALYTICS_API_KEY")
# Or directly (not recommended for production)
api_key = "YOUR_API_KEY"
HTTP 헤더
API 요청에 키를 포함하세요:
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://platform.ultralytics.com/api/...
사용 가능한 모든 엔드포인트는 REST API 문서를 참조하십시오.
원격 훈련
키를 사용하여 메트릭 스트리밍을 활성화하세요.
패키지 버전 요구 사항
플랫폼 통합을 위해서는 ultralytics8.4.35 이상이 필요합니다. 이보다 낮은 버전은 플랫폼과 호환되지 않습니다.
pip install "ultralytics>=8.4.35"
export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1
전체 원격 교육 가이드를 보려면 클라우드 교육을 참조하십시오.
키 관리
키 보기
모든 키는 다음 목록에 나와 있습니다. Settings > API Keys 탭:
각 키 카드에는 키 이름, 전체 복호화된 키 값(복사 가능), 상대적 생성 시간 및 취소 버튼이 표시됩니다.
키 해지
손상되었거나 더 이상 필요 없는 키를 해지하세요:
- API 키 섹션에서 키를 찾으세요
- 취소 (휴지통) 버튼을 클릭합니다.
- 해지 확인
즉시 적용
해지는 즉시 적용됩니다. 해당 키를 사용하는 모든 애플리케이션은 작동을 멈춥니다.
키 재생성
키가 손상된 경우:
- 동일한 이름으로 새 키를 생성합니다.
- 애플리케이션을 업데이트하세요
- 이전 키를 해지하세요
작업 공간 API 키
API 키는 현재 활성화된 작업 공간에 범위가 지정됩니다:
- 개인 작업 공간: 키는 개인 계정으로 인증됩니다.
- 팀 작업 공간: 키는 팀 컨텍스트 내에서 인증됩니다.
사이드바에서 작업 공간을 전환할 때 API 키 섹션에는 해당 작업 공간의 키가 표시됩니다. 작업 공간 API 키를 관리하려면 편집자 역할 이상이 필요합니다. 역할에 대한 자세한 내용은 팀을 참조하십시오.
보안 모범 사례
허용
- 환경 변수에 키 저장
- 환경별로 별도의 키 사용
- 사용하지 않는 키는 즉시 해지
- 키 주기적으로 순환
- 핵심 목적을 식별하기 위해 설명적인 이름을 사용하십시오
금지
- 버전 제어에 키 커밋
- 애플리케이션 간에 키 공유
- 애플리케이션 출력에 키 로깅
- 클라이언트 측 코드에 키 포함
키 로테이션
보안을 위해 키를 주기적으로 순환:
- 동일한 이름으로 새 키 생성
- 새 키를 사용하도록 애플리케이션 업데이트
- 애플리케이션이 올바르게 작동하는지 확인
- 이전 키 해지
순환 일정
민감한 애플리케이션의 경우 90일마다 키 순환을 고려하십시오.
문제 해결
유효하지 않은 키 오류
Error: Invalid API key
해결책:
- 키가 올바르게 복사되었는지 확인하십시오(포함하여
ul_접두사) - 키가 해지되지 않았는지 확인
- 환경 변수가 설정되었는지 확인
- 사용하고 있는지 확인하십시오
ultralytics>=8.4.35
권한 거부됨
Error: Permission denied for this operation
해결책:
- 리소스 소유자인지 또는 적절한 작업 공간 접근 권한이 있는지 확인하십시오.
- 키가 올바른 워크스페이스에 속하는지 확인합니다.
- 필요한 경우 새 키를 생성합니다.
요청 제한됨
Error: Rate limit exceeded
해결책:
- 요청 빈도 감소 — 엔드포인트별 제한 사항은 속도 제한 테이블을 참조하십시오
- 지수적 백오프를 사용하여 구현하십시오.
Retry-After헤더 - 무제한 추론 처리량을 위한 전용 엔드포인트 사용
FAQ
몇 개의 키를 생성할 수 있나요?
API 키에는 엄격한 제한이 없습니다. 다양한 애플리케이션 및 환경에 필요한 만큼 생성하세요.
키는 만료되나요?
키는 자동으로 만료되지 않습니다. 해지될 때까지 유효합니다. 보안을 위해 로테이션 구현을 고려하세요.
키 생성 후 키를 볼 수 있나요?
예, 전체 키 값은 키 목록에서 볼 수 있습니다. Settings > API Keys. 플랫폼은 키를 해독하고 표시하므로 언제든지 복사할 수 있습니다.
키는 지역별로 다른가요?
키는 모든 지역에서 작동하지만, 계정의 지역에 있는 데이터에만 액세스합니다.
팀원들과 키를 공유할 수 있나요?
모범 사례: 각 팀원이 고유한 키를 생성하도록 하십시오. 팀 작업 공간의 경우, 편집자 역할 이상을 가진 각 구성원은 해당 작업 공간에 한정된 키를 생성할 수 있습니다.
