API-ключи#

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

Создание API-ключа#

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

1. Перейди в Settings > API Keys
2. Нажми Добавить ключ и выбери Ultralytics в качестве провайдера
3. Введи имя ключа (например, "Training Server")
4. Нажми Create Key

Имя ключа#

Дай ключу понятное имя:

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

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

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

Ключи провайдеров для агентов#

На той же вкладке Настройки > Ключи API также хранятся ключи для внешних провайдеров моделей, используемых агентами. Только владелец рабочего пространства может добавлять, заменять или удалять эти ключи; участники команды могут видеть, какие провайдеры подключены. Попроси владельца подключить недостающего провайдера. Чтобы подключить провайдера в качестве владельца:

1. Нажми Добавить ключ.
2. Выбери провайдера, соответствующего языковой модели или модели компьютерного зрения твоего рабочего процесса.
3. Вставь ключ API этого провайдера в поле Ключ API, а затем нажми Сохранить ключ. Ссылка Получить ключ API в диалоговом окне открывает страницу ключей провайдера.

Ключ Ultralytics не осуществляет аутентификацию внешних провайдеров моделей. Использование провайдера оплачивается через учетную запись провайдера, связанную с сохраненным ключом. Используй элемент управления редактированием в строке ключа, чтобы заменить ключ провайдера.

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

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 для Python>=3.11:

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.32"), который считывает ULTRALYTICS_API_KEY или ключ, сохраненный yolo login, если api_key опущен:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

Все доступные конечные точки смотри в справочнике REST API.

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

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

Установи или обнови пакет Ultralytics для Python>=3.11 перед началом:

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 Keys
2. Нажми кнопку Revoke (корзина)
3. Подтверди отзыв

Перевыпуск ключа#

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

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

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

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

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

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

Ключи On Premise worker#

При подключении хоста On Premise создаётся отдельный ключ worker. Ключи worker управляются через интеграцию 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. Снизь частоту запросов — ограничения для каждой категории см. в таблице ограничений частоты запросов
2. Реализуй экспоненциальную задержку с использованием заголовка Retry-After
3. Используй выделенную конечную точку, если нужна изолированная вычислительная ёмкость для инференса

Часто задаваемые вопросы#