Hugging Face перестроила hf CLI под ИИ‑агентов: до 6 раз меньше токенов на сложных задачах — VogueTech

Что нового

Hugging Face серьёзно обновила свой консольный инструмент hf — официальный CLI для работы с Hugging Face Hub. Теперь его явно оптимизировали не только под людей, но и под код‑агентов вроде Claude Code, Codex, Cursor, Gemini и других.

Ключевые изменения и цифры:

Два режима вывода:
- «Человеческий» — цветной ANSI‑вывод, таблицы, подсказки, прогресс‑бары.
- «Агентский» — компактный структурированный текст без ANSI, без обрезки строк, в формате TSV, с полными ID, ISO‑датами и всеми тегами.
Автоопределение агентов по переменным окружения: CLAUDECODE, CLAUDE_CODE (Claude Code), CODEX_SANDBOX (Codex), плюс флаги для Cursor, Gemini, Pi и универсальный AI_AGENT.
Подсказки следующей команды: почти каждая операция заканчивается готовой командой с подставленными ID.
Без блокирующих промптов в агентском режиме: опасные действия для агентов сразу падают с явным советом Use --yes to skip confirmation.
Повторяемые операции:
- hf repos create --exist-ok не ломается, если репозиторий уже есть.
- Повторная загрузка файлов аккуратно докатывает изменения.
- Для тяжёлых операций есть --dry-run с точным списком файлов и объёмом.
Стандартизированное дерево команд: ресурс + глагол (hf models ls, hf repos create, hf jobs ps, hf collections delete), логичные алиасы (list/ls, remove/rm).
Управление форматом вывода:
- Автоматический выбор формата (human/agent) по контексту.
- Принудительный формат: --format human | agent | json | quiet.
- Доп‑флаги --json, --quiet, -q для пайплайнов.
Новый skill для агентов:
- Автогенерируемая краткая шпаргалка по всем командам hf.
- Подгружается в контекст агента через hf skills add (отдельно есть hf skills add --claude).

Бенчмарки по токенам и успешности задач:

Тесты на 18 нетривиальных задачах с двумя агентами:
- Claude Code (Sonnet 4.6)
  - hf CLI: 0,94 успеха.
  - curl / huggingface_hub (без CLI): 0,84 успеха.
  - Токены: curl/SDK тратят 1,3–1,6× больше токенов.
  - Самообман (агент говорит, что всё сделал, но на Hub изменений нет):
    - CLI: 2 ошибки из 163 запусков.
    - curl/SDK: 11 ошибок из 163 запусков.
- Codex (GPT‑5.5)
  - hf CLI: 0,93 успеха.
  - curl / SDK: 0,92 успеха.
  - Токены: curl/SDK тратят 1,6–1,8× больше токенов.
  - Самообман:
    - CLI: 3/163.
    - curl/SDK: 10/163.
На сложных задачах с несколькими шагами curl/SDK в отдельных кейсах сжигают 2,4–6× больше токенов, чем hf.
Масштаб использования агентов:
- Hugging Face начал атрибутировать трафик агентов в апреле 2026 года.
- Один только Claude Code — около 40 000 пользователей и почти 49 млн запросов к Hub за короткий период.

Как это работает

Автоопределение режима: человек или агент

hf построен поверх Python‑библиотеки huggingface_hub и при запуске проверяет переменные окружения, которые выставляют IDE и код‑агенты:

CLAUDECODE / CLAUDE_CODE — Claude Code
CODEX_SANDBOX — Codex
сигналы от Cursor, Gemini, Pi
общий флаг AI_AGENT

Если hf видит, что команду вызывает агент, он:

Включает агентский формат вывода.
Помечает каждый HTTP‑запрос к Hub user‑agent‑строкой вида agent/<name>, чтобы Hugging Face мог считать статистику по агентам.

Один и тот же запрос — два разных вывода

Пример: список моделей автора Qwen.

Режим для человека (по умолчанию в интерактивном терминале):

hf models ls --author Qwen --sort downloads --limit 3

ID                      CREATED_AT  DOWNLOADS  LIBRARY_NAME  LIKES  PIPELINE_TAG     PRIVATE  TAGS
----------------------  ----------  ---------  ------------  -----  ---------------  -------  -------------------------
Qwen/Qwen3-0.6B         2025-04-27  21156913   transformers  1285   text-generation  False    transformers, safetens...
Qwen/Qwen2.5-1.5B-Ins...2024-09-17  15143953   transformers  725   text-generation  False    transformers, safetens...
Qwen/Qwen3-4B           2025-04-27  14808352   transformers  625   text-generation  False    transformers, safetens...

Hint: Use `--no-truncate` or `--format json` to display full values.

Таблица подстраивается под ширину терминала, длинные строки обрезаются, цвета и иконки показывают статус.

Режим для агента (автоопределение по env):

hf models ls --author Qwen --sort downloads --limit 3

id created_at downloads library_name likes pipeline_tag private tags
Qwen/Qwen3-0.6B 2025-04-27T03:40:08+00:00 21156913 transformers 1285 text-generation False ['transformers', 'safetensors', 'qwen3', 'text-generation', 'conversational', 'arxiv:2505.09388', 'base_model:Qwen/Qwen3-0.6B-Base', 'base_model:finetune:Qwen/Qwen3-0.6B-Base', 'license:apache-2.0', 'text-generation-inference', 'endpoints_compatible', 'deploy:azure', 'region:us']
Qwen/Qwen2.5-1.5B-Instruct 2024-09-17T14:10:29+00:00 15143953 transformers 725 text-generation False['transformers', 'safetensors', 'qwen2', 'text-generation', 'chat', 'conversational', 'en', 'arxiv:2407.10671', 'base_model:Qwen/Qwen2.5-1.5B', 'base_model:finetune:Qwen/Qwen2.5-1.5B', 'license:apache-2.0', 'text-generation-inference', 'endpoints_compatible', 'deploy:azure', 'region:us']
Qwen/Qwen3-4B 2025-04-27T03:41:29+00:00 14808352 transformers 625 text-generation False ['transformers', 'safetensors', 'text-generation', 'arxiv:2309.00071', 'arxiv:2505.09388', 'base_model:Qwen/Qwen3-4B-Base', 'base_model:finetune:Qwen/Qwen3-4B-Base', 'license:apache-2.0', 'endpoints_compatible', 'deploy:azure', 'region:us']

Под капотом для вывода используются методы вроде .table(...), .result(...), .json(). Они принимают «сырые» данные и рендерят их в нужном формате.

Разделение stdout / stderr и подсказки

hf строго разделяет данные и подсказки:

Всё, что нужно парсить агенту (таблицы, TSV, JSON), идёт в stdout.
Подсказки, ошибки, предупреждения и «следующие команды» — в stderr.

Пример подсказки следующего шага:

$ hf jobs run --detach python:3.12 python train.py

✓ Job started
id: 6f3a1c2e9b
url: https://huggingface.co/jobs/celinah/6f3a1c2e9b

Hint: Use `hf jobs logs 6f3a1c2e9b` to fetch the logs.

Ошибка с явным фиксом:

Error: Not logged in. Run `hf auth login` first.

Без висящих промптов и с безопасным повтором

Агенты не могут нажать y в терминале и часто повторяют команды после таймаута. Поэтому hf в агентском режиме:

Не ждёт подтверждения на разрушающие действия, а сразу выдаёт ошибку с инструкцией:

$ hf repos delete my-org/old-model

Error: You are about to permanently delete model 'my-org/old-model'. Proceed?
Use --yes to skip confirmation.

Поддерживает идемпотентные операции:
- hf repos create --exist-ok не падает, если репозиторий уже создан.
- Повторные upload корректно перекоммитят файлы.
Даёт сухой прогон для операций с данными:

$ hf download deepseek-ai/DeepSeek-V4-Pro config.json --dry-run

[dry-run] Will download 1 files (out of 1) totalling 1.8K.

file        size
config.json 1.8K

Предсказуемое дерево команд и примеры

Командная структура hf намеренно простая:

Ресурс + действие: models ls, repos create, jobs ps, collections delete.
Алиасы: list/ls, remove/rm.

Каждый --help заканчивается реальными примерами, которые удобно копировать и которые агенты быстро матчат по шаблону:

$ hf models ls --help
...
Examples
  $ hf models ls --sort downloads --limit 10
  $ hf models ls --search "qwen" --author Qwen
  $ hf models ls Qwen/Qwen3-4B --tree

Для пайплайнов есть режимы:

-q — только ID по одному на строку, удобно для xargs или while read:

$ hf models ls --author Qwen -q | head -3
Qwen/Qwen3-0.6B
Qwen/Qwen2.5-1.5B-Instruct
Qwen/Qwen3-4B

--json — структурированный JSON для jq и других инструментов.

Как проводили бенчмарк

Hugging Face собрал 18 задач, которые похожи на реальные запросы коду‑агенту, а не на учебные примеры:

собрать статистику по моделям трендового орг‑аккаунта;
посмотреть дерево файлов и размеры в репозитории;
загрузить папку с include/exclude‑масками;
удалить файлы;
скопировать файлы между репозиториями;
открыть PR с добавлением лицензии;
создать репозиторий с веткой и тегом;
синхронизировать и почистить Bucket;
собрать коллекцию и т.п.

Каждая задача запускалась в чистой сессии с одним способом доступа к Hub:

Только hf CLI.
curl и/или Python‑SDK huggingface_hub — без hf.

Для hf тестировали две конфигурации — с установленным skill и без него. Основные цифры в таблице — это сравнение CLI vs curl/SDK; вклад skill разбирается отдельно.

Параметры эксперимента:

1 свежий инстанс агента на запуск.
Никаких MCP‑серверов, CLAUDE.md, AGENTS.md или других подсказок.
Задача и доступные инструменты выдаются одним промптом.
Агент должен завершить работу маркером TASK_COMPLETE или TASK_FAILED, но итог всегда проверяется по живому Hub.
Для каждой пары «задача/инструмент» — 10 прогонов, с учётом недетерминизма агентов.
Итого около 520 запусков на агента (18 задач × 3 инструмента × 10 повторов, с ограничением на одну дорогую Jobs‑задачу) и около 1000 прогонов суммарно.
Тестировали на Claude Code (Sonnet 4.6) и Codex (GPT‑5.5).

Успешность засчитывали только если изменения реально появились на Hub: создана ветка, удалён файл, обновлён Bucket и т.д.

hf‑skill: как он устроен

hf умеет генерировать skill — компактную справку по всем командам, которую агент подхватывает в контекст:

Автоматически строится из живого дерева команд hf на каждый релиз.
Одна строка на команду: сигнатура, короткое описание, важные флаги.
Группировка по ресурсам, плюс мини‑глоссарий общих опций.
Пропускает очевидные флаги, чтобы не раздувать контекст.

Эффект:

Число вызовов инструмента на задачу падает примерно с 10 до 7 — около 30% меньше команд, потому что агент не тратит шаги на --help и угадывание аргументов.
Общий расход токенов почти не снижается, а иногда растёт: skill всегда добавляет фиксированный блок текста в контекст.
Надёжность выполнения задач skill почти не меняет, но ускоряет «обучение» агента работе с CLI.

Что это значит для вас

Кому это нужно в первую очередь

ML‑инженеры и MLOps, которые уже живут в Hugging Face Hub:
- управление моделями, датасетами и Spaces из терминала;
- автоматизация CI/CD на Hub через скрипты и агентов;
- запуск и мониторинг Jobs прямо из CLI.
Разработчики IDE‑плагинов и ассистентов кода:
- проще встроить работу с Hub через один инструмент hf, чем собирать цепочки HTTP‑запросов;
- меньше токенов на каждую задачу — дешевле и быстрее с точки зрения API‑биллинга.
Команды, которые строят собственных агентов поверх Claude Code, GPT‑5.5 и локальных моделей:
- агенту проще описать задачу в виде пары CLI‑команд, чем заставлять его конструировать REST‑цепочку каждый раз.

Где hf CLI особенно полезен

Сложные многошаговые операции на Hub:
- создание репозитория с веткой и тегом;
- массовое копирование и удаление файлов между репами;
- синхронизация Bucket с очисткой лишних файлов;
- построение коллекций и управление ими.
В бенчмарках именно на таких задачах curl/SDK тратят 2,4–6× больше токенов, чем hf.
Интерактивная работа с Hub через агента:
- вы даёте агенту одну инструкцию, он сам подбирает команды hf;
- подсказки «следующей команды» и предсказуемое дерево команд делают сценарии стабильнее.
Сценарии с частыми ретраями:
- hf проектировали так, чтобы повторная команда не ломала состояние: --exist-ok, аккуратные перезаливки, --dry-run.

Где можно обойтись без hf

Простые одношаговые чтения:
- получить метаданные модели;
- посчитать строки датасета;
- прочитать один файл.
В таких кейсах curl и huggingface_hub по токенам сопоставимы с CLI, иногда даже чуть дешевле.
Если у вас уже есть плотная интеграция на уровне REST/SDK и агенты не используются:
- переход на hf — это доп‑слой, который не всегда нужен.

Ограничения и подводные камни

hf — это отдельный бинарник, его нужно установить на все среды, где работает агент.
Skill увеличивает контекст каждого запроса агента:
- если у вас жёсткие лимиты по токенам контекста, нужно балансировать между удобством и размером подсказки.
Продукты Hugging Face могут быть ограничены в России:
- доступ к Hugging Face Hub и установочным скриптам может потребовать VPN или прокси, в зависимости от вашей сети и локальных ограничений.

Место на рынке

Hugging Face решает специфичную задачу: сделать работу с Hugging Face Hub эффективной именно для код‑агентов. Напрямую это конкурирует не с моделями вроде GPT‑5.5 или Claude 4, а с двумя способами интеграции:

Прямой REST через curl.
Python‑SDK huggingface_hub.

По фактам из бенчмарка:

По успешности задач:
- На Claude Code (Sonnet 4.6) CLI даёт 0,94 успеха против 0,84 у curl/SDK. Разрыв заметный, особенно на задачах с записями (создание/изменение ресурсов).
- На Codex (GPT‑5.5) разница по успешности минимальна: 0,93 vs 0,92, но CLI всё ещё чуть надёжнее и реже «врёт» о завершённых задачах.
По токенам:
- В среднем curl/SDK тратят 1,3–1,8× больше токенов на ту же задачу.
- На сложных сценариях разрыв доходит до 2,4–6×.

Это означает, что для интеграций именно с Hugging Face Hub hf CLI сейчас даёт более выгодный баланс «стоимость токенов / стабильность», чем прямой REST или голый SDK, особенно когда в цепочке участвуют агенты.

Если вы строите агента, который работает и с другими сервисами (GitHub, облака, базы данных), hf становится ещё одним специализированным инструментом в «поясе» агента — рядом с git‑CLI, облачными CLIs и т.п.

Установка

Hugging Face рекомендует подключать hf к вашему агенту так:

1. Установка hf CLI

Unix‑подобные системы (Linux, macOS):

curl -LsSf https://hf.co/cli/install.sh | bash

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

После установки убедитесь, что hf доступен в PATH.

2. Установка skill для агента

hf skills add
hf skills add --claude

Первая команда добавляет общий skill, вторая — вариант, оптимизированный под Claude Code.

Посмотреть skill можно так:

hf skills preview

3. Аутентификация в Hugging Face Hub

hf auth login

Агент должен запускать команды от имени пользователя или сервисного аккаунта с нужными правами.

4. Пример промпта для агента

Когда всё установлено, можно дать агенту задачу в духе:

Use `hf` to list my Hugging Face Hub models, datasets, and Spaces. Take a look at how I am currently using the Hub and suggest a few ways you could help me.

Агент сам подберёт команды hf, выполнит их и вернётся с анализом и идеями.

Как запустить: рабочие примеры команд

Ниже — примеры команд из статьи, которые можно использовать и в ручном режиме, и через агента.

Список моделей автора с сортировкой по скачиваниям

hf models ls --author Qwen --sort downloads --limit 3

Формат вывода можно принудительно задать:

hf models ls --author Qwen --sort downloads --limit 3 --format human
hf models ls --author Qwen --sort downloads --limit 3 --format agent
hf models ls --author Qwen --sort downloads --limit 3 --format json
hf models ls --author Qwen --sort downloads --limit 3 --format quiet

Запуск Job и просмотр логов

hf jobs run --detach python:3.12 python train.py

# Подсказка от CLI
hf jobs logs 6f3a1c2e9b

Удаление репозитория (с защитой от случайного запуска агентом)

# Без подтверждения от агента команда упадёт с подсказкой
hf repos delete my-org/old-model

# Явное подтверждение
hf repos delete my-org/old-model --yes

Сухой прогон загрузки файла

hf download deepseek-ai/DeepSeek-V4-Pro config.json --dry-run

Поиск команд и примеров

hf models ls --help

Пайплайн: взять первые три ID моделей автора

hf models ls --author Qwen -q | head -3

Если вы уже используете Hugging Face Hub и планируете подключать агентов к своей инфраструктуре, hf CLI сейчас выглядит как базовый инструмент: он экономит токены, уменьшает количество ошибок и упрощает жизнь и людям, и ИИ‑ассистентам.