API Keys#
Ultralytics Platform API 키는 원격 학습, 추론 및 자동화를 위한 안전한 프로그래밍 방식의 액세스를 활성화합니다. 다양한 사용 사례에 맞춰 AES-256-GCM 암호화가 적용된 이름 있는 키를 생성하십시오.
API 키 생성#
새 API 키 생성:
- Settings > API Keys로 이동하십시오.
- Create Key를 클릭하십시오.
- 키 이름(예: "Training Server")을 입력하십시오.
- Create Key를 클릭하십시오.
키 이름#
키에 설명적인 이름을 지정하십시오:
training-server- 원격 학습 머신용ci-pipeline- CI/CD 통합용local-dev- 로컬 개발용
키 표시#
생성 후, 키가 확인 대화상자에 표시됩니다:
나중에 쉽게 참조할 수 있도록 생성 직후 키를 복사해 두세요. 키는 키 목록에도 표시됩니다. 플랫폼에서 전체 키 값을 복호화하여 표시하므로 언제든지 복사할 수 있습니다.
키 형식#
API 키는 다음 형식을 따릅니다:
ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4- Prefix:
ul_은 Ultralytics 키임을 나타냅니다. - Body: 40개의 무작위 16진수 문자
- Total: 43자
키 보안#
- 키는 AES-256-GCM 암호화로 저장됩니다.
- 인증은 빠른 인덱스 조회를 위해 SHA-256 해시를 사용합니다.
- 전체 키 값은 일반 텍스트로 저장되지 않습니다.
API 키 사용#
환경 변수#
키를 환경 변수로 설정하십시오:
export ULTRALYTICS_API_KEY="YOUR_API_KEY"YOLO CLI#
YOLO CLI를 사용하여 키를 검증하고 저장합니다:
yolo login YOUR_API_KEYyolo logout 명령어로 저장된 키를 제거합니다.
HTTP 헤더#
API 요청에 키를 포함하십시오:
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://platform.ultralytics.com/api/...사용 가능한 모든 엔드포인트는 REST API Reference를 참조하십시오.
원격 학습(Remote Training)#
키로 메트릭 스트리밍을 활성화하십시오.
시작하기 전에 Ultralytics 패키지를 설치하거나 업데이트하세요:
pip install -U ultralyticsexport ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1완전한 원격 학습 가이드는 Cloud Training을 참조하십시오.
키 관리#
키 보기#
모든 키는 Settings > API Keys 탭에 나열됩니다:
각 키 카드에는 키 이름, 복사 가능한 키 값, 상대적인 생성 시간, 사용 횟수, 그리고 폐기 버튼이 표시됩니다.
키 취소#
손상되었거나 더 이상 필요하지 않은 키를 취소하십시오:
- API Keys 섹션에서 해당 키를 찾으십시오.
- Revoke(휴지통) 버튼을 클릭하십시오.
- 취소를 확인하십시오.
취소는 즉시 적용됩니다. 해당 키를 사용하는 모든 애플리케이션은 작동을 멈춥니다.
키 재생성#
키가 손상된 경우:
- 같은 이름으로 새 키를 생성하십시오.
- 애플리케이션을 업데이트하십시오.
- 이전 키를 취소하십시오.
워크스페이스 API 키#
API 키는 현재 활성화된 워크스페이스에 한정됩니다:
- 개인 워크스페이스: 키가 개인 계정으로 인증됩니다.
- 팀 워크스페이스: 키가 팀 컨텍스트 내에서 인증됩니다.
사이드바에서 워크스페이스를 전환하면 API Keys 섹션에 해당 워크스페이스의 키가 표시됩니다. 워크스페이스 API 키를 관리하려면 편집자 이상의 역할이 필요합니다. 역할에 대한 자세한 내용은 Teams를 참조하십시오.
보안 모범 사례#
권장 사항(Do)#
- 키를 환경 변수에 저장하십시오.
- 환경별로 별도의 키를 사용하십시오.
- 사용하지 않는 키는 즉시 취소하십시오.
- 주기적으로 키를 순환시키십시오.
- 설명적인 이름을 사용하여 키 용도를 식별하십시오.
금지 사항(Don't)#
- 키를 버전 관리 시스템에 커밋하지 마십시오.
- 애플리케이션 간에 키를 공유하지 마십시오.
- 애플리케이션 출력에 키를 기록하지 마십시오.
- 클라이언트 측 코드에 키를 포함하지 마십시오.
키 순환#
보안을 위해 주기적으로 키를 순환시키십시오:
- 같은 이름으로 새 키를 생성하십시오.
- 새 키를 사용하도록 애플리케이션을 업데이트하십시오.
- 애플리케이션이 올바르게 작동하는지 확인하십시오.
- 이전 키를 취소하십시오.
중요한 애플리케이션의 경우 90일마다 키를 순환시키는 것을 고려하십시오.
문제 해결#
유효하지 않은 키 오류#
Error: Invalid API key해결 방법:
- 키가 (
ul_접두사를 포함하여) 올바르게 복사되었는지 확인하십시오. - 키가 취소되지 않았는지 확인하십시오.
- 환경 변수가 설정되었는지 확인하십시오.
ultralytics>=8.4.104버전을 사용하고 있는지 확인하세요.
권한 거부#
Error: Permission denied for this operation해결 방법:
- 리소스 소유자이거나 적절한 워크스페이스 액세스 권한이 있는지 확인하십시오.
- 키가 올바른 워크스페이스에 속해 있는지 확인하십시오.
- 필요한 경우 새 키를 생성하십시오.
속도 제한#
Error: Rate limit exceeded해결 방법:
- 요청 빈도를 줄이십시오. 엔드포인트별 제한은 rate limit table을 참조하십시오.
Retry-After헤더를 사용하여 지수 백오프를 구현하십시오.- 격리된 추론 용량이 필요할 때는 전용 엔드포인트를 사용하세요.
FAQ#
키를 몇 개까지 생성할 수 있습니까?#
API 키 개수에는 엄격한 제한이 없습니다. 다양한 애플리케이션과 환경에 필요한 만큼 자유롭게 생성하십시오.
키가 만료됩니까?#
키는 자동으로 만료되지 않습니다. 취소될 때까지 유효합니다. 보안을 위해 주기적으로 키를 순환시키는 것을 고려하십시오.
생성 후 키를 다시 볼 수 있습니까?#
네, 전체 키 값은 Settings > API Keys의 키 목록에서 볼 수 있습니다. 플랫폼이 키를 복호화하여 표시하므로 언제든지 복사할 수 있습니다.
키가 지역별로 고정되어 있습니까?#
키는 지역에 관계없이 작동하지만, 계정의 지역 내 데이터에만 액세스할 수 있습니다.
팀원들과 키를 공유할 수 있습니까?#
더 나은 방법: 각 팀원이 자신의 키를 직접 생성하도록 하십시오. 팀 작업 공간의 경우, 편집자(Editor) 역할 이상의 권한을 가진 구성원은 해당 작업 공간 범위 내에서 키를 생성할 수 있습니다.