Пакетная обработка - это мощный подход для эффективной обработки больших объемов запросов. Вместо обработки запросов по одному с немедленными ответами, пакетная обработка позволяет отправлять несколько запросов вместе для асинхронной обработки. Этот паттерн особенно полезен, когда:

• Вам нужно обрабатывать большие объемы данных
• Немедленные ответы не требуются
• Вы хотите оптимизировать затраты
• Вы проводите масштабные оценки или анализ

API пакетных сообщений - это наша первая реализация этого паттерна.

​

API пакетных сообщений

API пакетных сообщений - это мощный и экономичный способ асинхронной обработки больших объемов запросов Messages. Этот подход хорошо подходит для задач, не требующих немедленных ответов, при этом большинство пакетов обрабатывается менее чем за 1 час, снижая затраты на 50% и увеличивая пропускную способность.

Вы можете изучить справочник API напрямую в дополнение к этому руководству.

​

Как работает API пакетных сообщений

Когда вы отправляете запрос в API пакетных сообщений:

1. Система создает новый пакет сообщений с предоставленными запросами Messages.
2. Затем пакет обрабатывается асинхронно, каждый запрос обрабатывается независимо.
3. Вы можете опрашивать статус пакета и получать результаты, когда обработка всех запросов завершена.

Это особенно полезно для массовых операций, не требующих немедленных результатов, таких как:

• Масштабные оценки: Эффективная обработка тысяч тестовых случаев.
• Модерация контента: Асинхронный анализ больших объемов пользовательского контента.
• Анализ данных: Генерация выводов или сводок для больших наборов данных.
• Массовая генерация контента: Создание большого количества текста для различных целей (например, описания продуктов, сводки статей).

​

Ограничения пакетов

• Пакет сообщений ограничен либо 100 000 запросами Message, либо размером 256 МБ, в зависимости от того, что будет достигнуто первым.
• Мы обрабатываем каждый пакет максимально быстро, большинство пакетов завершается в течение 1 часа. Вы сможете получить доступ к результатам пакета, когда все сообщения будут обработаны или через 24 часа, в зависимости от того, что наступит раньше. Пакеты истекают, если обработка не завершается в течение 24 часов.
• Результаты пакетов доступны в течение 29 дней после создания. После этого вы все еще можете просматривать пакет, но его результаты больше не будут доступны для загрузки.
• Пакеты привязаны к Рабочему пространству. Вы можете просматривать все пакеты и их результаты, созданные в рабочем пространстве, к которому принадлежит ваш API-ключ.
• Ограничения скорости применяются как к HTTP-запросам API пакетов, так и к количеству запросов в пакете, ожидающих обработки. См. Ограничения скорости API пакетных сообщений. Кроме того, мы можем замедлить обработку в зависимости от текущего спроса и объема ваших запросов. В этом случае вы можете увидеть больше запросов, истекающих через 24 часа.
• Из-за высокой пропускной способности и параллельной обработки пакеты могут немного превысить настроенный лимит расходов вашего рабочего пространства.

​

Поддерживаемые модели

API пакетных сообщений в настоящее время поддерживает:

• Claude 3.5 Sonnet (claude-3-5-sonnet-20240620 и claude-3-5-sonnet-20241022)
• Claude 3.5 Haiku (claude-3-5-haiku-20241022)
• Claude 3 Haiku (claude-3-haiku-20240307)
• Claude 3 Opus (claude-3-opus-20240229)

​

Что можно включать в пакеты

Любой запрос, который вы можете сделать к API Messages, может быть включен в пакет. Это включает:

• Зрение
• Использование инструментов
• Системные сообщения
• Многоходовые разговоры
• Любые бета-функции

Поскольку каждый запрос в пакете обрабатывается независимо, вы можете смешивать различные типы запросов в одном пакете.

​

Ценообразование

API пакетов предлагает значительную экономию затрат. Все использование тарифицируется по 50% от стандартных цен API.

​

Как использовать API пакетных сообщений

​

Подготовка и создание пакета

Пакет сообщений состоит из списка запросов на создание сообщения. Форма отдельного запроса включает:

• Уникальный custom_id для идентификации запроса Messages
• Объект params со стандартными параметрами API Messages

Вы можете создать пакет, передав этот список в параметр requests:

В этом примере два отдельных запроса объединены в пакет для асинхронной обработки. Каждый запрос имеет уникальный custom_id и содержит стандартные параметры, которые вы бы использовали для вызова API Messages.

Когда пакет создается впервые, ответ будет иметь статус обработки in_progress.

{
  "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2024-09-24T18:37:24.100435Z",
  "expires_at": "2024-09-25T18:37:24.100435Z",
  "cancel_initiated_at": null,
  "results_url": null
}

​

Отслеживание вашего пакета

Поле processing_status пакета сообщений указывает на этап обработки пакета. Он начинается как in_progress, затем обновляется до ended, когда все запросы в пакете завершили обработку и результаты готовы. Вы можете отслеживать состояние вашего пакета, посетив Консоль или используя конечную точку получения:

Вы можете опрашивать эту конечную точку, чтобы узнать, когда обработка завершилась.

​

Получение результатов пакета

После завершения обработки пакета каждый запрос Messages в пакете будет иметь результат. Существует 4 типа результатов:

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

Результаты пакета доступны для загрузки как в Консоли, так и по results_url в пакете сообщений. Из-за потенциально большого размера результатов р

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

Результаты будут в формате .jsonl, где каждая строка является допустимым JSON-объектом, представляющим результат одного запроса в пакете сообщений. Для каждого потокового результата вы можете выполнить различные действия в зависимости от его custom_id и типа результата. Вот пример набора результатов:

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-3-5-sonnet-20241022","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-3-5-sonnet-20241022","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

Если ваш результат содержит ошибку, его result.error будет установлен в нашу стандартную форму ошибки.

​

Использование кэширования промптов с пакетами сообщений

API пакетных сообщений поддерживает кэширование промптов, позволяя потенциально снизить затраты и время обработки пакетных запросов. Скидки на цены от кэширования промптов и пакетов сообщений могут складываться, обеспечивая еще большую экономию затрат при совместном использовании обеих функций. Однако, поскольку пакетные запросы обрабатываются асинхронно и параллельно, попадания в кэш предоставляются по мере возможности. Пользователи обычно получают частоту попаданий в кэш от 30% до 98%, в зависимости от их схем трафика.

Чтобы максимизировать вероятность попаданий в кэш в ваших пакетных запросах:

1. Включите идентичные блоки cache_control в каждый запрос Message в вашем пакете
2. Поддерживайте постоянный поток запросов, чтобы предотвратить истечение срока действия записей кэша после их 5-минутного срока жизни
3. Структурируйте ваши запросы так, чтобы они разделяли как можно больше кэшированного контента

Пример реализации кэширования промптов в пакете:

В этом примере оба запроса в пакете включают идентичные системные сообщения и полный текст “Гордости и предубеждения”, помеченный с помощью cache_control для увеличения вероятности попаданий в кэш.

​

Лучшие практики для эффективной пакетной обработки

Чтобы получить максимальную отдачу от API пакетов:

• Регулярно отслеживайте статус обработки пакетов и реализуйте соответствующую логику повторных попыток для неудачных запросов.
• Используйте значимые значения custom_id для легкого сопоставления результатов с запросами, так как порядок не гарантируется.
• Рассмотрите возможность разбиения очень больших наборов данных на несколько пакетов для лучшей управляемости.
• Проведите тестовый запуск одной формы запроса с API Messages, чтобы избежать ошибок проверки.

​

Устранение распространенных проблем

При возникновении неожиданного поведения:

• Проверьте, что общий размер пакетного запроса не превышает 256 МБ. Если размер запроса слишком большой, вы можете получить ошибку 413 request_too_large.
• Убедитесь, что вы используете поддерживаемые модели для всех запросов в пакете.
• Убедитесь, что каждый запрос в пакете имеет уникальный custom_id.
• Убедитесь, что прошло менее 29 дней с момента created_at пакета (не с момента завершения обработки `ende

d_at`). Если прошло более 29 дней, результаты больше не будут доступны для просмотра.

• Подтвердите, что пакет не был отменен.

Обратите внимание, что сбой одного запроса в пакете не влияет на обработку других запросов.

​

Хранение и конфиденциальность пакетов

• Изоляция рабочего пространства: Пакеты изолированы в рамках рабочего пространства, в котором они созданы. Доступ к ним могут получить только API-ключи, связанные с этим рабочим пространством, или пользователи с разрешением на просмотр пакетов рабочего пространства в Консоли.

• Доступность результатов: Результаты пакетов доступны в течение 29 дней после создания пакета, предоставляя достаточно времени для получения и обработки.

​

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

import anthropic

client = anthropic.Anthropic()

message_batch = client.beta.messages.batches.create(
    betas: ["max-tokens-3-5-sonnet-2024-07-15"],
    ...
)