Пакетный режим (DashScope)

Batch API от DashScope выполняет запросы асинхронно по половине стоимости реального времени, с окном завершения не менее 24 часов. Qwen Code использует его через /batch-api: вы описываете массовую задачу, агент готовит план, а qwen batch отправляет его, отслеживает и записывает результаты в файлы.

Настройка пакетной модели

Укажите эндпоинт и учётные данные один раз в settings.json, затем выберите модель через batch.model. Ваша обычная модель для диалога и аутентификация остаются без изменений, в том числе когда в диалоге используется Qwen OAuth или другой провайдер.


{
  "env": { "DASHSCOPE_API_KEY": "your-key" },
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3.7-plus",
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "envKey": "DASHSCOPE_API_KEY"
      }
    ]
  },
  "batch": { "authType": "openai", "model": "qwen3.7-plus" }
}

Объедините эти поля с существующими настройками, сохранив остальные записи провайдеров. envKey задаёт имя ключа в settings.env (или переменной окружения); отдельный экспорт в оболочке не нужен. generationConfig провайдера управляет пакетной генерацией. wireApi — это протокол запросов, а не переключатель Batch: не указывайте его или используйте "chat-completions"; "responses" не поддерживается этим исполнителем.

batch.authType по умолчанию равен openai. Модель должна однозначно совпадать с одной записью OpenAI-совместимого chat-completions, имеющей baseUrl и заполненный envKey. Если идентификаторы повторяются, укажите batch.baseUrl равным точному настроенному URL. Некорректный явный выбор завершится ошибкой до загрузки; он никогда не откатывается на учётные данные диалога. Перезапустите интерактивную сессию после изменения этого выбора, чтобы её фоновый сборщик использовал те же настройки, что и дочерние команды.

Без выбора пакетной модели сохраняется прежнее поведение: Batch использует конфигурацию основной модели и требует аутентификацию по API-ключу OpenAI-совместимого формата. Учётные данные Qwen OAuth сами по не имеют маршрута Batch. Выполните qwen batch check, чтобы проверить готовность без отправки платного запроса.

Когда пакетный режим — правильный инструмент

Половина цены, без кэша. Batch списывает 50% от прайс-листа за успешные запросы, но префиксный кэш в пакетном режиме никогда не срабатывает (измерено: cached_tokens: 0). Реальное время оценивает кэшированный ввод в 20% от прайс-листа, поэтому Batch выигрывает только тогда, когда в каждом запросе мало общего: при доле кэш-попаданий h реальное время стоит около 1 − 0.8h от прайс-листа по вводу, и Batch проигрывает, когда h превышает 0,625.
Хорошо подходит: множество независимых одноходовых запросов, каждый из которых определяется собственным содержимым — перевод или суммаризация набора документов, извлечение данных по файлам. Длинные выходные данные делают Batch ещё выгоднее.
Плохо подходит: длинный общий свод правил или few-shot-префикс с короткими элементами, мало элементов, всё, что требует более одного хода. Маршрутизация собственных ходов агента через Batch показала 1,03× от реального времени и на часы медленнее.
Задержка: от секунд до часов, в основном ожидание в очереди, и она зависит от модели. Рассчитывайте на дешевизну, а не на скорость.

Чтобы проверить задание до отправки, выполните один запрос в реальном времени и сравните usage.prompt_tokens_details.cached_tokens с usage.prompt_tokens.

`/batch-api`


/batch-api translate the Markdown docs in docs/zh into English,
writing them to docs/en with the same file names

Агент выполняет qwen batch check, убеждается, что задача подходит, читает небольшую выборку, записывает план в .qwen/batch/plans/ и показывает его — ничего не загружается и не оплачивается:


qwen batch run .qwen/batch/plans/<slug>.json --dry-run
# preview: 42 item(s), window 24h — nothing uploaded, nothing billed
# model qwen-plus, thinking off, max output 8192 tokens (frozen from your current settings; retries reuse them)
# writes new files to: docs/en/ (42)
# ~180,000 in / ~190,000 out tokens (rough estimate); ...
# snapshot 3f9c2a7e5d10b884; submit exactly this batch with: qwen batch run .qwen/batch/plans/<slug>.json --expect 3f9c2a7e5d10b884

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


qwen batch run .qwen/batch/plans/<slug>.json --expect 3f9c2a7e5d10b884
# task translate-docs-20260923103000: 42 item(s), window 24h
# ...
# batch job: batch_abc123

run возвращает управление немедленно, и вам не нужно собирать результаты вручную. Агент запускает qwen batch collect <task-id> --wait как фоновую задачу (видна в /tasks) и завершает свой ход, так что вы можете продолжать работу. Этот процесс опрашивает провайдера по HTTP — без вызова модели, пока вы ждёте — и когда Batch завершается, записывает результаты и выходит. Затем агент пробуждается однократно: он сообщает, что было доставлено, удержано или завершилось с ошибкой, и выполняет любые последующие действия, которые вы запросили в исходном запросе. Элементы с ошибкой никогда не повторяются автоматически, поскольку повторная отправка снова списывает средства.

Если сессия закроется раньше, ничего не потеряется: интерактивная сессия собирает завершённые задачи проекта при запуске и во время работы и выводит одно уведомление. Установите general.batchAutoCollect в false, чтобы отключить это. Headless-запуски (qwen -p), qwen serve и клиенты IDE/ACP не выполняют автосбор.

Команды работают из любого каталога, а внутри сессии — с префиксом ! (например, !qwen batch collect <task-id>), чтобы не тратить ход модели:


qwen batch check                         # проверить настройку; ничего не оплачивается
qwen batch collect <task-id> [--wait [--timeout <s>]]   # проверить и записать целевые файлы
qwen batch retry <task-id>               # отправить повторно только элементы с ошибкой
qwen batch retry <task-id> --max-output-tokens 8192  # включить усечённые
qwen batch list                          # все записанные задачи с их проектом
qwen batch cancel <task-id>              # частичные результаты всё равно оплачиваются
qwen batch clean <task-id>               # удалить локальную запись (ничего не отменяет)

collect сообщает по каждому элементу:

delivered — записан в целевой файл;
held — исходный файл изменился после отправки (retry повторно отправляет его по новому источнику), или целевой файл уже существует с другим содержимым (разберитесь и повторно запустите collect; новый запрос не делается);
failed — усечён, пуст, содержит вызов инструмента или ошибку провайдера; retry повторно отправляет такие элементы, усечённые — только с большим --max-output-tokens.

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

Записи, безопасность и стоимость

Записи задач хранятся в ~/.qwen/batch/tasks/<task-id>/ (QWEN_BATCH_HOME переопределяет) с правами только для владельца, поскольку они содержат полные копии ваших исходных и выходных данных. Файлы планов в .qwen/batch/ проекта добавляются в .gitignore.
Задача привязана к эндпоинту и API-ключу, с которыми была отправлена (хранится только короткий хэш ключа); после смены аккаунта или региона команды отклоняют выполнение, пока вы не переключитесь обратно.
Если ответ на вызов создания потерян, run завершается с ошибкой, задача помечается как submit-unknown, и collect сверяется со списком Batch-задач провайдера вместо повторной отправки — дубликат спишет средства дважды.
Только одна команда qwen batch может работать с задачей одновременно.
Запуск замораживает ваши текущие параметры выборки, лимит выходных данных и режим мышления; повторы используют их.
Оценки рассчитываются по токенам, если не установлены QWEN_BATCH_INPUT_PRICE_PER_1M_USD и QWEN_BATCH_OUTPUT_PRICE_PER_1M_USD. Приблизительная оценка не учитывает токены мышления, которых может быть в несколько раз больше выходных. maxCostUsd плана проверяется по наихудшему случаю при лимитах запроса: для этого нужны указанные цены, maxOutputTokens и выключенное мышление или thinking_budget, иначе запуск отклоняется. Ни одна из цифр не включает расходы сессии на подготовку плана.
Неудачная удалённая очистка никогда не блокирует retry, cancel или clean; последующий collect повторит её. Файл результата, который провайдер не может выдать полностью (после одной свежей загрузки) или которого больше нет, помечает затронутые элементы как ошибочные, а не оставляет задачу застывшей.
clean отклоняет выполнение, если Batch ещё может работать или содержит несобранные результаты, если только не передан --force.
Целевые файлы должны находиться внутри проекта и вне скрытых путей (.git/, .github/, .qwen/, … на любой глубине): результаты записываются через часы после одобрения плана. Предварительный просмотр перечисляет целевые каталоги.

Архитектура: docs/design/2026-09-23-batch-api-design.md. Автономная сквозная проверка (фейковый Batch API, реальный собранный CLI) находится в docs/verification/batch-api/.