API 키#

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

API 키 생성#

새 API 키를 생성합니다:

1. 설정 > API 키로 이동합니다.
2. Add Key을(를) 클릭하고 공급자로 Ultralytics을(를) 선택합니다.
3. 키 이름을 입력합니다(예: "Training Server").
4. 키 생성을 클릭합니다.

키 이름#

키를 설명하는 이름을 지정합니다:

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

키 표시#

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

에이전트용 공급자 키#

동일한 Settings > API Keys 탭에는 Agents에서 사용하는 외부 모델 공급자의 키도 저장됩니다. 워크스페이스 소유자만 이러한 키를 추가, 교체 또는 제거할 수 있으며, 팀 멤버는 어떤 공급자가 연결되어 있는지 확인할 수 있습니다. 누락된 공급자를 연결하려면 소유자에게 요청하세요. 소유자로서 공급자를 연결하려면 다음을 수행합니다.

1. Add Key을(를) 클릭합니다.
2. 워크플로의 언어 모델 또는 시각-언어 모델에 맞는 공급자를 선택합니다.
3. 해당 공급자의 API 키를 API Key에 붙여넣은 다음 Save Key을(를) 클릭합니다. 대화상자의 Get an API key 링크는 공급자의 키 페이지를 엽니다.

Ultralytics 키는 외부 모델 공급자를 인증하지 않습니다. 공급자 사용량은 저장된 키와 연결된 공급자 계정을 통해 청구됩니다. 공급자 키를 교체하려면 키 행의 편집 제어 요소를 사용하세요.

키 형식#

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

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

• 접두사: ul_는 Ultralytics 키를 식별합니다.
• 본문: 무작위 16진수 문자 40개
• 총 길이: 43자

키 보안#

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

API 키 사용#

환경 변수#

키를 환경 변수로 설정합니다:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Python>=3.11 환경에서 YOLO CLI를 사용하여 키를 검증하고 저장합니다:

yolo login YOUR_API_KEY

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

HTTP 헤더#

API 요청에 키를 포함합니다:

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

또는 Python SDK(pip install "ultralytics-platform>=0.1.45")에 전달하면, ULTRALYTICS_API_KEY 또는 api_key이 생략된 경우 yolo login가 저장한 키를 읽습니다.

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

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

원격 학습#

키를 사용하여 메트릭 스트리밍을 활성화합니다.

시작하기 전에 Python>=3.11 환경에서 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 키 섹션에서 키를 찾습니다.
2. 폐기(휴지통) 버튼을 클릭합니다.
3. 폐기를 확인합니다.

키 재생성#

키가 유출된 경우:

1. 같은 이름으로 새 키를 생성합니다.
2. 애플리케이션을 업데이트합니다.
3. 이전 키를 폐기합니다.

워크스페이스 API 키#

API 키의 범위는 현재 활성화된 워크스페이스로 제한됩니다:

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

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

On Premise 작업자 키#

On Premise 호스트를 연결하면 별도의 작업자 키가 발급됩니다. 작업자 키는 이 탭이 아니라 On Premise 통합에서 관리되며, API 키와 함께 나열되지 않습니다. 호스트 연결을 해제하면 작업자 키가 폐기되고 해당 호스트의 대기 중인 작업과 실행 중인 작업도 취소됩니다.

보안 모범 사례#

권장 사항#

• 키를 환경 변수에 저장합니다.
• 환경마다 별도의 키를 사용합니다.
• 사용하지 않는 키를 즉시 폐기합니다.
• 키를 정기적으로 교체합니다.
• 키의 용도를 식별할 수 있도록 설명적인 이름을 사용합니다.

금지 사항#

• 키를 버전 관리 시스템에 커밋합니다.
• 애플리케이션 간에 키를 공유합니다.
• 애플리케이션 출력에 키를 기록합니다.
• 클라이언트 측 코드에 키를 삽입합니다.

키 교체#

보안을 위해 키를 정기적으로 교체합니다:

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

문제 해결#

잘못된 키 오류#

Error: Invalid API key

해결 방법:

1. 키가 올바르게 복사되었는지 확인합니다(ul_ 접두사 포함).
2. 키가 폐기되지 않았는지 확인합니다.
3. 환경 변수가 설정되었는지 확인합니다.
4. Python>=3.11 및 ultralytics>=8.4.120을(를) 사용하고 있는지 확인하십시오.

권한 거부#

Error: Permission denied for this operation

해결 방법:

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

요청 제한#

Error: Rate limit exceeded

해결 방법:

1. 요청 빈도를 줄입니다. 카테고리별 제한은 rate limit table을 참조하십시오.
2. Retry-After 헤더를 사용하여 지수 백오프를 구현합니다.
3. 격리된 추론 용량이 필요한 경우 전용 엔드포인트를 사용합니다

FAQ#