[Попробуйте пакетный вывод со скидкой 50%
Запускайте крупномасштабное прогнозирование быстрее и дешевле с поддерживаемыми моделями:
qwen/qwen3-vl-235b-a22b-a22b-instruct, openai/gpt-oss-120b, deepseek/deepseek-r1-0528, qwen/qwen3-4b-fp8.](https://novita.ai/docs/guides/llm-batch-api)
Разработчики часто сталкиваются с медленным временем отклика и высокими сетевыми затратами при отправке тысяч отдельных вызовов API. Пакетный API решает эту проблему, объединяя несколько независимых запросов в одну операцию, что снижает задержки, использование полосы пропускания и накладные расходы на соединение.
В этой статье объясняется, что такое пакетный API, чем он отличается от стандартных API, и как Пакетный API от Novita AI обеспечивает крупномасштабный асинхронный вывод через структурированный ввод JSONL, эффективную обработку файлов и надежное отслеживание ошибок. Также рассматриваются ключевые факторы эффективности, такие как стоимость, задержка и пропускная способность, а также приводится краткое руководство по внедрению и мониторингу.
Попробуйте пакетный вывод со скидкой 50%
Запускайте крупномасштабное прогнозирование быстрее и дешевле с поддерживаемыми моделями:
qwen/qwen3-vl-235b-a22b-a22b-instruct, openai/gpt-oss-120b, deepseek/deepseek-r1-0528, qwen/qwen3-4b-f
Что такое пакетный API？
Пакетный API: объединяет несколько независимых вызовов API (например, GET, POST, PUT, DELETE) в один HTTP-запрос.
Структура ответа: сервер возвращает результаты всех подзапросов по порядку, указывая успех или ошибку для каждого.
Ключевое отличие пакетного API от стандартного
Обычные запросы
Клиент
├──► Запрос 1 (/user/1)
│ └──► Ответ сервера 1
├──► Запрос 2 (/user/2)
│ └──► Ответ сервера 2
└──► Запрос 3 (/order)
└──► Ответ сервера 3
Пакетный запрос
Клиент
└──► Единый запрос (/batch)
├─ Подзапрос 1: GET /user/1
├─ Подзапрос 2: GET /user/2
└─ Подзапрос 3: POST /order
↓
Сервер обрабатывает все
↓
Объединенный ответ:
[Result1, Result2, Result3]
Пакетный API может помочь:
Снизить сетевую задержку за счет отправки одного объединенного запроса вместо множества.
Сократить использование полосы пропускания и накладные расходы на соединение, так как заголовки и рукопожатия общие.
Повысить производительность клиента, особенно на мобильных устройствах или медленных сетях.
Упростить логику транзакций, обеспечивая единую обработку ошибок или откат.
Оптимизировать пропускную способность API-шлюза, предотвращая перегрузку запросами.
Типичные сценарии использования пакетного API
| Сценарий | Описание |
|---|---|
| 1. Массовые запросы данных | Получение нескольких пользователей, товаров или публикаций сразу, чтобы избежать повторяющихся запросов. |
| 2. Массовая запись или обновление | Создание или обновление нескольких записей в одной операции (например, пакетная загрузка, обновление запасов). |
| 3. Оптимизация производительности фронтенда | Снижение количества HTTP-вызовов из браузеров или мобильных приложений для ускорения времени загрузки. |
| 4. Агрегация бэкенд-задач | В микросервисных системах объединение нескольких внутренних вызовов API в один внешний вызов. |
| 5. Синхронизация данных | Синхронизация состояний нескольких ресурсов или выполнение пакетных операций (например, тегирование, удаление). |
| 6. Оптимизация лимита запросов | Снижение нагрузки на API-шлюз и экономия полосы пропускания за счет консолидации запросов. |
Ключевые факторы, влияющие на эффективность пакетного API
Насколько пакетные API могут снизить затраты по сравнению с API в реальном времени?
Согласно отраслевому анализу (Growth-onomics), сокращение затрат составляет около 20–45%, в основном за счет меньшего количества сетевых переходов, более низких накладных расходов на соединение и концентрированной обработки, хотя точная экономия зависит от частоты вызовов, размера пакета и архитектуры системы.
Что насчет задержки — могут ли пакетные API действительно завершить работу «в течение 24 часов»?
Пакетные API обычно работают асинхронно с гораздо более высокой задержкой, чем API в реальном времени; многие системы выполняют обработку ежечасно или ежедневно, поэтому «выполнение в течение 24 часов» зависит от SLA, а не гарантировано.
Влияют ли размер пакета или размер файла на скорость?
Да. Более крупные пакеты (например, больше строк JSONL) почти линейно увеличивают время передачи и разбора; хотя пропускная способность растет, общее время завершения одного пакета увеличивается.
Почему пакетные API лучше подходят для рабочих нагрузок с высокой пропускной способностью?
Объединяя тысячи запросов в один процесс, пакетные API снижают накладные расходы на отдельный вызов и позволяют выполнять параллельное исполнение или повторное использование кэша, что часто повышает пропускную способность на 17–92% в крупномасштабных операциях, хотя это сопровождается более высокой задержкой.
Как использовать пакетный API？
Пакетный API от Novita полностью совместим с интерфейсом OpenAI, поддерживает
/v1/chat/completionsи/v1/completions, поэтому существующий код можно повторно использовать с минимальными изменениями. Он принимает входные файлы.jsonl, где каждая строка представляет отдельный запрос к одной и той же модели, идентифицируемый уникальнымcustom_idдля удобного отслеживания. Вывод также выполняется в формате JSONL, что делает крупномасштабную постобработку, анализ и интеграцию простыми и эффективными.
1. Подготовьте входной файл для пакетной обработки
Создайте файл .jsonl, где каждая строка представляет один запрос API в формате JSON.
Пример (batch_input.jsonl):
{"custom_id": "req-1", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "user", "content": "Summarize: batch API basics"}], "max_tokens": 200}}
{"custom_id": "req-2", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "system", "content": "You are concise."},{"role": "user", "content": "List 3 batch API use cases"}], "max_tokens": 150}}
Правила:
- Один запрос на строку.
- Все запросы должны использовать одну и ту же модель.
- Каждая строка должна содержать уникальный
custom_id.
2. Загрузите входной файл и создайте пакет
Используйте Python или curl для загрузки файла и немедленного запуска пакетной задачи.
Python
from openai import OpenAI
client = OpenAI(base_url="https://api.novita.ai/openai/v1", api_key="YOUR_API_KEY")
# Upload + create batch
uploaded = client.files.create(file=open("batch_input.jsonl", "rb"), purpose="batch")
batch = client.batches.create(
input_file_id=uploaded.id,
endpoint="/v1/chat/completions",
completion_window="48h"
)
print("file_id:", uploaded.id)
print("batch_id:", batch.id)
curl
export API_KEY="YOUR_API_KEY"
# Upload file
upload_response=$(curl -s -X POST \
-H "Authorization: Bearer ${API_KEY}" \
-F 'file=@batch_input.jsonl' -F 'purpose=batch' \
https://api.novita.ai/openai/v1/files)
# Extract file_id and start batch
file_id=$(echo $upload_response | jq -r '.id')
curl -X POST https://api.novita.ai/openai/v1/batches \
-H "Authorization: Bearer ${API_KEY}" \
-H "Content-Type: application/json" \
-d "{\"input_file_id\": \"$file_id\", \"endpoint\": \"/v1/chat/completions\", \"completion_window\": \"48h\"}"
3. Проверьте статус пакета
Вы можете проверить прогресс в любое время, используя идентификатор пакета.
batch = client.batches.retrieve("batch_xxx")
print(batch.status)
Статусы включают:
VALIDATING– входной файл проверяетсяPROGRESS– выполняетсяCOMPLETED– завершен успешноFAILED– завершен с ошибкойEXPIRED– превышено окно в 48 часов
4. Получите результаты
После завершения скачайте файл с результатами через output_file_id:
output = client.files.content("file_xxx")
print(output.read().decode("utf-8"))
Каждая строка в выводе соответствует одному входному запросу, сопоставленному по custom_id.
Советы:
поддерживается только
deepseek/deepseek-r1-0528До 50 000 запросов в одном пакете
Размер входного файла ≤ 100 МБ
Окно завершения фиксировано на 48 часов
Вывод сохраняется в течение 30 дней
Как обрабатывать неудачные запросы в пакетном API?
Ошибки, возникающие во время пакетной обработки, записываются в отдельный файл ошибок, доступ к которому осуществляется через поле error_file_id. Каждый неудачный подзапрос содержит код ошибки и описание. Распространенные примеры:
| Код ошибки | Описание | Решение |
|---|---|---|
| 400 | Недопустимый формат запроса | Проверьте синтаксис JSONL и обязательные поля |
| 401 | Ошибка аутентификации | Проверьте API-ключ |
| 404 | Пакет не найден | Проверьте идентификатор пакета |
| 429 | Превышен лимит запросов | Снизьте частоту запросов |
| 500 | Ошибка сервера | Свяжитесь с провайдером или повторите попытку позже |
Разработчики должны повторно обработать только неудачные записи с помощью очереди повторных попыток или меньшего последующего пакета, вместо повторной отправки всего исходного файла.
Какие эндпоинты предоставляет Novita AI для операций с пакетным API?
| Эндпоинт | Назначение |
|---|---|
| Создать пакет | Отправить новую пакетную задачу, содержащую несколько запросов. |
| Получить пакет | Получить статус или результаты конкретного пакета по его идентификатору. |
| Отменить пакет | Остановить выполняющуюся пакетную задачу до завершения. |
| Список пакетов | Получить список всех отправленных пакетных задач для аккаунта. |
| Загрузить файл | Загрузить входные файлы с данными (например, JSONL). |
| Список файлов | Просмотреть все загруженные файлы. |
| Получить файл | Получить метаданные файла по его идентификатору. |
| Удалить файл | Удалить загруженный файл. |
| Получить содержимое файла | Скачать фактическое содержимое файла (например, результаты или журнал ошибок). |
Пакетный API объединяет множество небольших запросов в один эффективный рабочий процесс. Используя Пакетный API от Novita AI, разработчики могут снизить сетевые затраты до 45%, масштабировать пропускную способность до 50 000 запросов в пакете и упростить обработку ошибок за счет встроенных эндпоинтов ведения журнала и получения данных. Хотя он жертвует скоростью в реальном времени, он обеспечивает исключительную эффективность для массового вывода, синхронизации и рабочих нагрузок по обработке данных.
Novita AI — это облачная платформа ИИ, которая предлагает разработчикам простой способ развертывания моделей ИИ с использованием нашего простого API, а также предоставляет доступное и надежное облако GPU для создания и масштабирования решений.
