Ключи API#

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

Создать ключ API#

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

1. Перейди в раздел Настройки > Ключи API
2. Нажми Добавить ключ и выбери Ultralytics в качестве провайдера
3. Введи название ключа (например, «Сервер обучения»)
4. Нажми Создать ключ

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

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

• 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.45"), который считывает 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

Полное руководство по удалённому обучению см. в разделе облачное обучение.

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

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

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

В каждой строке отображаются название ключа, его префикс, дата создания, кнопка копирования полного ключа и кнопка удаления (корзина).

Отозвать ключ#

Отзови скомпрометированный или ненужный ключ:

1. Найди ключ в разделе «Ключи API»
2. Нажми кнопку удаления (корзина)
3. Для подтверждения нажми Удалить ключ

Создать ключ заново#

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

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

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

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

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

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

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

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