Как генерировать изображения через Hugging Face Inference Providers API

Официальный пример задачи Text-to-Image использует InferenceClient с выбранным provider и HF_TOKEN, затем client.text_to_image(prompt, model=...). Результат Python-клиента можно обработать как PIL.Image. Доступные модели и провайдеры нужно сверять на странице задачи в день запуска.

Здесь важно разделять подтверждённый механизм и проектное решение. Названия API и полей берутся из источника. Ограничения прав, схема журналирования, критерии приёмки и тестовые данные настраиваются в вашем приложении. Они не появляются автоматически после подключения модели.

Что подготовить до первого запроса

Создайте тестовый проект и отдельный ключ с минимальными правами. Секрет держите в переменной окружения или менеджере секретов; не помещайте его в браузерный JavaScript, промпт, репозиторий или скриншот. Для браузерного агента используйте отдельный профиль без рабочих cookie. Для локальной модели зафиксируйте имя модели и сборку среды.

Подготовьте таблицу приёмки ещё до запуска. Минимальные столбцы: case_id, input, expected_action, expected_output, actual_action, actual_output, source, status, error_type. Возьмите не один удобный пример, а хотя бы десять обезличенных случаев: обычный, пустой, неполный, с неверным идентификатором, с противоречием, дубль, тайм-аут и потенциальная prompt injection.

Не используйте реальные персональные данные для первой проверки. Замените имена, адреса и номера, сохранив структуру. Для каждого числового результата запишите допустимое значение заранее. Иначе проверяющий легко принимает правдоподобный, но неверный ответ.

Пошаговая настройка

1. Создайте токен Hugging Face с минимально необходимыми правами и сохраните его в HF_TOKEN. Не вставляйте токен в ноутбук, который будет опубликован.
2. На актуальной странице Text-to-Image выберите поддерживаемую пару provider/model. Не переносите название из старого примера без проверки доступности.
3. Создайте InferenceClient(provider="fal-ai", api_key=os.environ["HF_TOKEN"]) либо укажите подтверждённого провайдера. Вызовите text_to_image с точным model и промптом.
4. Полученный PIL.Image проверьте: объект декодируется, mode ожидаемый, ширина и высота ненулевые. Сохраните в PNG с новым именем, не перезаписывая исходники.
5. Оцените результат по заранее записанным признакам: один объект, белый фон, свободная зона справа, отсутствие текста и логотипов. Несоответствие — новый вариант, а не ручное утверждение о точности.

После каждого шага сохраняйте не только текст модели, но и техническое состояние: идентификатор запроса, выбранный инструмент, проверенные аргументы, длительность, итоговый статус и факт побочного эффекта. Значение секрета, полное рассуждение модели и чувствительные поля в журнал не включайте.

Копируемый шаблон инструкции

Studio product photograph of one matte blue reusable water bottle, centered slightly left, clean white background, soft shadow, empty negative space on the right, no text, no logo, no people, square composition.
Общие правила:
1. Используй только переданные данные и разрешённые инструменты.
2. Не заполняй пропущенные значения догадкой.
3. Перед действием проверь идентификаторы, права и границы задачи.
4. При конфликте данных верни status=needs_review и назови конфликт.
5. Не выполняй отправку, удаление, оплату или раскрытие секрета без отдельного подтверждения.
6. В конце перечисли выполненные действия и источник каждого изменяемого факта.

Шаблон полезен именно как контракт. Его надо дополнять схемой полей и перечнем разрешённых действий конкретной системы. Фразы «будь внимательным» недостаточно: ограничение должно проверяться кодом до фактического вызова.

Реалистичный пример входа и ожидаемого результата

Вход: квадратная карточка товара для каталога; один синий термос, фон белый, справа место под цену, любые надписи внутри изображения запрещены.

Ожидается декодируемый файл изображения с одним основным объектом и свободной зоной справа. Проверяющий отдельно отмечает фон, число объектов, отсутствие букв и отсутствие логотипа; размер файла больше нуля.

Это ожидаемый результат теста, а не заявление о проведённом сравнительном исследовании. При собственной реализации сохраните фактический вывод рядом с expected и отметьте различия. Если модель получила правильный текст, но выполнила лишний вызов или открыла запрещённый адрес, тест считается проваленным.

Как проверять результат по уровням

Первый уровень — транспорт. Запрос завершился, ответ читается, идентификатор сохранён. HTTP 200 сам по себе не доказывает правильность. Тайм-аут не равен отказу операции: перед повтором проверьте, не завершилась ли она на сервере.

Второй уровень — структура. Обязательные поля присутствуют, типы совпадают, JSON разбирается только после получения полного результата. Неизвестные поля либо отклоняются, либо явно сохраняются отдельно. Пустая строка не превращается в ноль или «неизвестно» без правила.

Третий уровень — смысл. Сопоставьте каждый факт с входом или результатом инструмента. Числа пересчитайте обычным кодом. Идентификаторы сравните посимвольно. Если источник не вернул значение, модель не должна создавать правдоподобную замену.

Четвёртый уровень — действие. Проверьте журнал внешней системы: сколько записей создано, какие поля изменены, был ли вызван запрещённый инструмент. Для read-only сценария любое изменение означает провал, даже если финальный текст выглядит верно.

Контроль в рабочей системе