API 키
Ultralytics Platform API 키는 원격 훈련, 추론 및 자동화를 위한 안전한 프로그래밍 방식의 접근을 가능하게 합니다. 다양한 사용 사례에 맞춰 특정 권한을 가진 범위 지정 키를 생성하세요.
API 키 생성
새 API 키 생성:
- 설정 > API 키로 이동합니다.
- 키 생성을 클릭합니다.
- 키 이름을 입력하세요
- 권한 범위를 선택합니다.
- 생성을 클릭합니다.
키 이름
키에 설명적인 이름을 지정합니다:
training-server- 원격 훈련 머신용ci-pipeline- CI/CD 통합용mobile-app- 모바일 애플리케이션용
권한 범위
키 권한을 제한할 범위를 선택합니다:
| 범위 | 권한 |
|---|---|
| 교육 | 훈련 시작, 메트릭 스트리밍 |
| 모델 | 모델 업로드, 다운로드, 삭제 |
| 데이터 세트 | 데이터셋 접근 및 수정 |
| 읽기 | 모든 리소스에 대한 읽기 전용 접근 |
| 쓰기 | 전체 쓰기 접근 |
| 관리자 | 계정 관리 (주의해서 사용) |
최소 권한
필요한 권한만으로 키를 생성합니다. 다른 애플리케이션에는 별도의 키를 사용하세요.
키 표시
생성 후 키는 한 번만 표시됩니다:
키 복사
전체 키는 한 번만 표시됩니다. 즉시 복사하여 안전하게 보관하십시오. 나중에 다시 검색할 수 없습니다.
키 형식
API 키는 다음 형식을 따릅니다:
ul_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
- 접두사:
ul_Ultralytics 키를 식별합니다. - 본문: 40개의 임의의 16진수 문자
- 총: 43자
API 키 사용
환경 변수
키를 환경 변수로 설정하세요:
export ULTRALYTICS_API_KEY="ul_your_key_here"
$env:ULTRALYTICS_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/...
원격 훈련
키를 사용하여 메트릭 스트리밍을 활성화하세요.
패키지 버전 요구 사항
Platform 통합에는 ultralytics>=8.4.0이 필요합니다. 하위 버전은 Platform에서 작동하지 않습니다.
pip install "ultralytics>=8.4.0"
export ULTRALYTICS_API_KEY="ul_your_key_here"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1
키 관리
키 보기
모든 키는 설정 > API 키에 나열됩니다:
| 열 | 설명 |
|---|---|
| 이름 | 키 식별자 |
| 범위 | 할당된 권한 |
| 생성됨 | 생성일 |
| 마지막 사용 | 최근 사용 |
키 해지
손상되었거나 더 이상 필요 없는 키를 해지하세요:
- 키 메뉴를 클릭하세요
- 해지를 선택하세요
- 해지 확인
즉시 적용
해지는 즉시 적용됩니다. 해당 키를 사용하는 모든 애플리케이션은 작동을 멈춥니다.
키 재생성
키가 손상된 경우:
- 동일한 범위로 새 키를 생성하세요
- 애플리케이션을 업데이트하세요
- 이전 키를 해지하세요
보안 모범 사례
허용
- 환경 변수에 키 저장
- 환경별로 별도의 키 사용
- 사용하지 않는 키는 즉시 해지
- 최소한의 필수 범위 사용
- 키 주기적으로 순환
금지
- 버전 제어에 키 커밋
- 애플리케이션 간에 키 공유
- 불필요하게 관리자 범위 사용
- 애플리케이션 출력에 키 로깅
- 클라이언트 측 코드에 키 포함
키 로테이션
보안을 위해 키를 주기적으로 순환:
- 동일한 범위로 새 키 생성
- 새 키를 사용하도록 애플리케이션 업데이트
- 애플리케이션이 올바르게 작동하는지 확인
- 이전 키 해지
순환 일정
민감한 애플리케이션의 경우 90일마다 키 순환을 고려하십시오.
문제 해결
유효하지 않은 키 오류
Error: Invalid API key
해결책:
- 키가 올바르게 복사되었는지 확인
- 키가 해지되지 않았는지 확인
- 키에 필요한 범위가 있는지 확인
- 환경 변수가 설정되었는지 확인
권한 거부됨
Error: Permission denied for this operation
해결책:
- 키 범위에 필요한 권한이 포함되어 있는지 확인
- 리소스 소유자인지 확인
- 올바른 범위로 새 키 생성
요청 제한됨
Error: Rate limit exceeded
해결책:
- 요청 빈도 줄이기
- 지수 백오프 구현
- 제한 증가를 위해 지원팀에 문의
FAQ
몇 개의 키를 생성할 수 있나요?
API 키에는 엄격한 제한이 없습니다. 다양한 애플리케이션 및 환경에 필요한 만큼 생성하세요.
키는 만료되나요?
키는 자동으로 만료되지 않습니다. 해지될 때까지 유효합니다. 보안을 위해 로테이션 구현을 고려하세요.
키 생성 후 키를 볼 수 있나요?
아니요, 전체 키는 생성 시 한 번만 표시됩니다. 분실한 경우, 새 키를 생성하고 이전 키를 해지하세요.
키는 지역별로 다른가요?
키는 모든 지역에서 작동하지만, 계정의 지역에 있는 데이터에만 액세스합니다.
팀원들과 키를 공유할 수 있나요?
더 나은 관행: 각 팀원이 자신만의 키를 생성하도록 하세요. 이를 통해 다음이 가능합니다:
- 개별 활동 추적
- 선택적 취소
- 적절한 접근 제어
