API-ключи#

Ключи API Ultralytics Platform обеспечивают безопасный программный доступ для удаленного обучения, инференса и автоматизации. Создавай именованные ключи с шифрованием AES-256-GCM для различных сценариев использования.

Создать API key#

Создай новый API-ключ:

1. Перейди в Settings > API Keys
2. Нажми Create Key
3. Введи название ключа (например, "Training Server")
4. Нажми Create Key

Название ключа#

Дай своему ключу описательное название:

• training-server — для машин удаленного обучения
• ci-pipeline — для CI/CD-интеграции
• local-dev — для локальной разработки

Отображение ключа#

После создания ключ отображается в диалоговом окне подтверждения:

Формат ключа#

API-ключи имеют следующий формат:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

• Префикс: ul_ идентифицирует ключи Ultralytics
• Тело: 40 случайных шестнадцатеричных символов
• Всего: 43 символа

Безопасность ключей#

• Ключи хранятся с использованием шифрования AES-256-GCM, а не в открытом виде
• Первые 11 символов (ul_ плюс 8 шестнадцатеричных символов) служат в качестве отображаемого префикса, поэтому ключ можно идентифицировать без его раскрытия

Использование API-ключей#

Переменная окружения#

Установи ключ в качестве переменной окружения:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Проверь и сохрани ключ с помощью 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.5"), который также считывает ULTRALYTICS_API_KEY:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

Ознакомься со справочником по REST API для получения информации обо всех доступных эндпоинтах.

Удаленное обучение#

Включи потоковую передачу метрик с помощью своего ключа.

Установи или обнови пакет 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

Ознакомься с разделом Облачное обучение для получения полного руководства по удаленному обучению.

Управление ключами#

Просмотр ключей#

Все ключи перечислены на вкладке Settings > API Keys:

На каждой карточке ключа отображаются имя ключа, значение ключа с возможностью копирования, относительное время создания и кнопка отзыва.

Отзыв ключа#

Отозови ключ, если он скомпрометирован или больше не нужен:

1. Найди ключ в разделе API Keys
2. Нажми кнопку Revoke (корзина)
3. Подтверди отзыв

Перегенерация ключа#

Если ключ скомпрометирован:

1. Создай новый ключ с тем же названием
2. Обнови свои приложения
3. Отозови старый ключ

API-ключи рабочего пространства#

API-ключи привязаны к текущему активному рабочему пространству:

• Личное рабочее пространство: Ключи аутентифицируют тебя как личный аккаунт
• Командное рабочее пространство: ключи выполняют аутентификацию от имени владельца командного рабочего пространства с полными правами владельца в этом рабочем пространстве

При переключении рабочих пространств на боковой панели в разделе API Keys отображаются ключи для этого рабочего пространства. Поскольку ключ рабочего пространства наделяет правами владельца, только владелец рабочего пространства может создавать, просматривать или отзывать его. Подробнее о ролях см. в разделе Teams.

Ключи воркеров On Premise#

Подключение хоста On Premise создает отдельный ключ воркера. Ключи воркеров управляются через интеграцию On Premise, а не на этой вкладке, никогда не выводятся в списке вместе с твоими ключами API и отзываются путем отключения хоста, что также отменяет поставленные в очередь и выполняющиеся задания этого хоста.

Лучшие практики безопасности#

Делай#

• Храни ключи в переменных окружения
• Используй отдельные ключи для разных сред
• Своевременно отзывай неиспользуемые ключи
• Периодически меняй (ротируй) ключи
• Используй описательные названия для определения назначения ключей

Не делай#

• Не коммить ключи в систему контроля версий
• Не делись ключами между приложениями
• Не выводи ключи в логах приложения
• Не встраивай ключи в клиентский код

Ротация ключей#

Периодически меняй ключи в целях безопасности:

1. Создай новый ключ с тем же названием
2. Обнови приложения, чтобы они использовали новый ключ
3. Проверь, что приложения работают корректно
4. Отозови старый ключ

Устранение неполадок#

Ошибка неверного ключа#

Error: Invalid API key

Решения:

1. Убедись, что ключ скопирован правильно (включая префикс ul_)
2. Убедись, что ключ не был отозван
3. Подтверди, что переменная окружения установлена
4. Убедись, что ты используешь ultralytics>=8.4.120

Доступ запрещен#

Error: Permission denied for this operation

Решения:

1. Проверь, что ты являешься владельцем ресурса или имеешь соответствующий доступ к рабочему пространству
2. Проверь, что ключ принадлежит нужному рабочему пространству
3. Если ты управляешь ключами в командном рабочем пространстве, убедись, что ты являешься владельцем рабочего пространства — у других ролей отображается Workspace owner access required
4. Создай новый ключ, если это необходимо

Превышение лимита запросов (Rate Limited)#

Error: Rate limit exceeded

Решения:

1. Сократи частоту запросов — см. таблицу лимитов для ограничений по категориям
2. Реализуй экспоненциальную задержку (backoff), используя заголовок Retry-After
3. Используй выделенный эндпоинт, когда тебе нужна изолированная емкость для инференса

FAQ#