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