Пакетные запросы в Python для OpenAI-совместимого LLM API
Для пакетной работы с LLM API на Python не нужен специальный эндпоинт: нужен пул рабочих потоков, соблюдающий лимиты запросов, правило повторных попыток для HTTP 429 и файл результатов, из которого можно продолжить работу. Это руководство реализует все три компонента с использованием OpenAI SDK, настроенного на ваш base URL.

Ключевые моменты
- API имеет два метода: чат-завершения и список моделей, поэтому пакетирование выполняется на вашей стороне с помощью пула параллельных запросов.
- Полный ключ позволяет 8 одновременных запросов и 300 в минуту; пробный ключ — 2 и 60. Настройте размер пула соответственно.
- Повторяйте запрос при 429, используя заголовок Retry-After, и различайте ограничения по частоте запросов и параллелизм.
- Записывайте каждый результат в файл JSONL по завершении, чтобы при сбое потерялись минуты, а не весь запуск.
Как работает пакетная обработка
Эндпоинт совместим с OpenAI и предоставляет POST /v1/chat/completions и GET /v1/models. Отдельного эндпоинта для отправки задания (с файлом) и получения результата позже нет. Пакет — это цикл обычных запросов, выполняемых параллельно с учетом лимитов в коде. Это проще, чем кажется, и дает результаты по мере завершения, а не в конце.
Числа, определяющие архитектуру, — это лимиты. Полный ключ позволяет 8 одновременных запросов и 300 в минуту. Пробный ключ — 2 одновременных и 60 в минуту. Максимальный размер тела запроса — 8 МБ. Потоковый запрос удерживает слот параллелизма до завершения потока, поэтому для пакетных задач отключите потоковую передачу.
Почему не отправить все сразу? Пакет — это проблема пропускной способности с пределом, который вы должны соблюдать. Цикл, отправляющий 5000 запросов так быстро, как Python может их создать, получит стену ответов 429, потратит время на повторные попытки и скроет полезные ошибки в шуме. Пул, удерживающий не более 8 запросов в полете, поддерживает движение конвейера на скорости, разрешенной сервисом. Код одинаков для 50 строк и для 500 000. Запланируйте три компонента: ограниченный пул, одно правило повторных попыток и файл результатов только для добавления.
Идентификатор модели — uncensored, аутентификация — Authorization: Bearer <key>, а базовый URL — https://api.unfilteredvideo.com/v1. Если у вас еще нет ключа, на странице API-ключ доступен пробный баланс за $0,50 в один клик.
Установка и настройка
Вам нужен Python 3.9 или новее и официальный пакет openai. Поместите ключ в переменную окружения, а не в скрипт.
pip install openai
export API_KEY="paste-your-key-here"
# quick check that the key and base URL work
curl https://api.unfilteredvideo.com/v1/models -H "Authorization: Bearer $API_KEY"
Список моделей должен показывать uncensored. Теперь подготовьте входные данные в формате JSONL: один объект на строку с идентификатором и текстом для обработки. Идентификатор позволит вам возобновить работу позже.
{"id": "r001", "text": "Summarise this product review in one sentence: ..."}
{"id": "r002", "text": "Summarise this product review in one sentence: ..."}
Пул потоков в пределах лимитов
Для большинства скриптов ThreadPoolExecutor — самый короткий путь. Клиент OpenAI безопасен для использования между потоками, а работа связана с сетью, поэтому потоки подходят. Установите размер пула равным лимиту параллелизма, не больше: дополнительные потоки просто собирают ошибки 429.
import json, os
from concurrent.futures import ThreadPoolExecutor, as_completed
from openai import OpenAI
client = OpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
WORKERS = 8 # use 2 on a trial key
def run_one(row):
resp = client.chat.completions.create(
model=MODEL,
temperature=0.2,
max_tokens=200,
messages=[{"role": "user", "content": row["text"]}],
)
return {
"id": row["id"],
"output": resp.choices[0].message.content,
"in": resp.usage.prompt_tokens,
"out": resp.usage.completion_tokens,
}
rows = [json.loads(line) for line in open("input.jsonl")]
with ThreadPoolExecutor(max_workers=WORKERS) as pool, open("output.jsonl", "a") as out:
futures = [pool.submit(run_one, r) for r in rows]
for f in as_completed(futures):
out.write(json.dumps(f.result()) + "\n")
out.flush()
Эта версия не поддерживает повторные попытки и возобновление, поэтому она служит отправной точкой. Клиент создается с параметром max_retries=0 на стороне клиента, потому что SDK по умолчанию выполняет повторные попытки самостоятельно, а вам нужно одно место, которое владеет правилом повторных попыток. В следующих двух разделах добавляется это правило и логика возобновления.
Правильная обработка 429
В этом API есть три вида ошибок 429, требующих немного разных реакций:
rate_limited: вы отправили слишком много запросов за минуту. Замедлитесь. Пул с меньшим количеством воркеров или короткая пауза решают эту проблему.concurrency: слишком много запросов находилось в состоянии выполнения одновременно. Размер вашего пула превышает лимит, или у вас есть открытые потоки, о которых вы забыли.- Временная перегрузка: 429 с заголовком
Retry-After: 5. С вашим кодом все в порядке. Подождите указанное время и попробуйте снова.
Один помощник повторных попыток покрывает все три случая. Он ждет Retry-After, если он присутствует, иначе делает экспоненциальную паузу с небольшим джиттером. Запросы, которые завершились ошибкой или были отклонены, не оплачиваются, поэтому повторные попытки бесплатны.
import random, time
import openai
from openai import OpenAI
client = OpenAI(api_key=__import__("os").environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
def call_with_retry(messages, attempts=6):
for n in range(attempts):
try:
return client.chat.completions.create(model=MODEL, messages=messages, max_tokens=200)
except openai.RateLimitError as e:
wait = e.response.headers.get("Retry-After")
delay = float(wait) if wait else min(60, 2 ** n) + random.random()
print("429", getattr(e, "code", None), "waiting", round(delay, 1), "s")
time.sleep(delay)
except (openai.APIConnectionError, openai.APITimeoutError):
time.sleep(min(30, 2 ** n))
raise RuntimeError("gave up after %d attempts" % attempts)
Не повторяйте запросы вслепую при каждой ошибке. Статус 400 означает, что ваш запрос неверен, например, тело превышает 8 МБ или сообщение имеет неверный формат, и повторная отправка приведет к той же ошибке. Запишите его с идентификатором строки и переходите дальше.
Асинхронная версия с семафором
Если ваш скрипт уже работает в цикле событий или вы хотите обслуживать веб-сервис, используйте AsyncOpenAI и asyncio.Semaphore, ограничивающий количество запросов в полете. Семафор выполняет роль размера пула.
import asyncio, json, os
from openai import AsyncOpenAI
client = AsyncOpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1", max_retries=0)
MODEL = "uncensored"
sem = asyncio.Semaphore(8)
async def run_one(row, out):
async with sem:
resp = await client.chat.completions.create(
model=MODEL,
max_tokens=200,
messages=[{"role": "user", "content": row["text"]}],
)
out.write(json.dumps({"id": row["id"], "output": resp.choices[0].message.content}) + "\n")
out.flush()
async def main():
rows = [json.loads(l) for l in open("input.jsonl")]
with open("output.jsonl", "a") as out:
await asyncio.gather(*(run_one(r, out) for r in rows))
asyncio.run(main())
Оберните вызов в ту же логику повторных запросов, что и выше, используя await asyncio.sleep вместо time.sleep. Одно замечание: gather с десятками тысяч сопрограмм создает их все одновременно. Для очень больших входных данных обрабатывайте файл по частям в несколько тысяч строк.
Возобновление запуска
Долгие задания терпят неудачу по банальным причинам: ноутбук переходит в спящий режим, соединение разрывается, вы нажимаете Ctrl+C. Поскольку каждая завершенная строка добавляется в output.jsonl с ее идентификатором, возобновление означает пропуск идентификаторов, которые у вас уже есть.
import json, os
from openai import OpenAI
client = OpenAI(api_key=os.environ["API_KEY"], base_url="https://api.unfilteredvideo.com/v1")
MODEL = "uncensored"
def done_ids(path="output.jsonl"):
if not os.path.exists(path):
return set()
return {json.loads(line)["id"] for line in open(path) if line.strip()}
finished = done_ids()
todo = [r for r in map(json.loads, open("input.jsonl")) if r["id"] not in finished]
print(len(finished), "done,", len(todo), "to go")
Передайте todo в любой из пулов выше. Откройте выходной файл в режиме добавления, а не перезаписи, иначе перезапуск сотрет ваш прогресс. Также записывайте ошибки во второй файл, errors.jsonl, чтобы можно было перезапустить только неудачные задачи после прочтения причин их сбоев.
Для повторяемого вывода при перезапусках передавайте фиксированный seed вместе с низким temperature. Значение seed передается модели вместе с top_p, stop и штрафами.
Тестирование на малой выборке
Запустите 20 строк, прежде чем запускать 20 000. Выберите строки, включающие ваши худшие случаи: самый длинный ввод, ввод с необычными символами, пустой ввод. Оцените выходные данные визуально, проверьте, что usage соответствует вашей оценке стоимости, и подтвердите работу помощника повторных запросов, временно увеличив количество воркеров выше вашего лимита. Вы должны увидеть ответ 429 с кодом concurrency в журнале, ожидание и успешный повторный запрос. Лучше увидеть это на 20 строках, чем обнаружить проблему на строке 9 000.
Если задание требует структурированного вывода, добавьте JSON-режим с параметром response_format={"type": "json_object"}, опишите ключи в промпте и разберите каждый ответ внутри блока try. Подсчитайте сбои парсинга на тестовой выборке. Если частота превышает один-два процента, обычно это означает, что промпт требует более четкой схемы, что дешевле исправить сейчас, чем перезапускать позже. Строки, которые не удалось распарсить, попадают в errors.jsonl с их идентификатором, а логика возобновления считает их не выполненными.
Наконец, установите тайм-аут клиента, соответствующий вашему самому длинному ожидаемому выводу. SDK принимает параметр timeout=60 на клиенте или для отдельного запроса; застрявший запрос, который никогда не вернется, иначе будет занимать один из ваших 8 слотов столько, сколько он будет висеть.
Размер пула и оценка времени
Пропускная способность ограничена двумя вещами: параллельными запросами, деленными на время выполнения одного запроса, и лимитом запросов в минуту. На полном ключе лимит составляет 300 в минуту, что равно 5 в секунду. Если типичный запрос занимает 2 секунды, 8 воркеров производят 8 / 2 = 4 запроса в секунду, или 240 в минуту, что ниже лимита. Если запросы занимают 1 секунду, 8 воркеров попытаются выполнить 8 в секунду и упрутся в лимит, поэтому добавьте небольшую задержку или примите периодические ответы 429, которые поглощает ваш помощник повторных запросов.
Со скоростью 4 в секунду 10 000 строк занимают 2 500 секунд, около 42 минут. На пробном ключе, с 2 параллельными запросами и лимитом 60 в минуту, потолок составляет 1 в секунду, поэтому те же 10 000 строк займут 10 000 секунд, почти 2 часа 47 минут. На практике пробный баланс на $0,50 закончится раньше этого, что делает его хорошим местом для тестирования скрипта на нескольких сотнях строк, а не для продакшена.
Стоимость большого пакета
Цены: $0,15 за 1 млн входных токенов и $0,50 за 1 млн выходных токенов. Возьмем задачу классификации: 50 000 строк, каждая примерно 200 входных токенов и 100 выходных токенов.
- Вход: 50 000 × 200 = 10 000 000 токенов, что составляет 10 × $0,15 = $1,50.
- Выход: 50 000 × 100 = 5 000 000 токенов, что составляет 5 × $0,50 = $2,50.
- Итого: $4,00, или $0,00008 за строку.
Приведенный выше скрипт записывает in и out для каждой строки, поэтому вы можете вычислить тот же показатель по результатам вашего реального запуска. Заголовок ответа X-Balance-USD также показывает оставшийся баланс, а X-Request-Id — это то, что нужно указать, если вы обратитесь за помощью на страницах документации или поддержки.
Баланс пополняется предоплаченными целыми суммами от $20 до $500, с бонусом +5% от $50, +10% от $100 и +15% от $200, оплачивается криптовалютой (USDT в сети TRC20 или USDC в сети Base). Он не сгорает. На странице тарифов приведены полные детали. Одно замечание для чувствительных наборов данных: промпты не используются для обучения.
Дополнительные руководства
Вопросы и ответы
Есть ли у API эндпоинт для пакетной обработки?
Нет. API предоставляет эндпоинты для чат-завершений и списка моделей. Пакетная обработка выполняется за счёт параллельных запросов из вашего кода в пределах лимитов: 8 одновременных запросов и 300 запросов в минуту для полного ключа.
Сколько потоков мне использовать?
Используйте 8 рабочих потоков для полного ключа и 2 для пробного ключа, соблюдая лимиты параллельных запросов. Превышение количества потоков приводит к ошибкам 429.
Что делать при получении HTTP 429?
Подождите значение заголовка Retry-After, если он указан, иначе сделайте паузу на несколько секунд и повторите запрос. Отказавшие запросы не списываются, поэтому повторная отправка не стоит денег.
Можно ли использовать потоковую передачу в пакетной задаче?
Можно, но не стоит. Потоковый запрос удерживает слот параллельных запросов до завершения потока, что снижает пропускную способность. Отключите потоковую передачу для пакетной работы.
Ваш ключ — на расстоянии одной формы
Создайте аккаунт, скопируйте ключ, измените базовый URL. Это вся настройка.