Практики работы с длинными ответами

​

Три вещи, которые нужно знать в первую очередь

1. Для вывода на 10 тыс. слов нормальна реальная генерация в течение 10–20 минут. Модель последовательно генерирует десятки тысяч символов token за token, а также проходит этап рассуждения/обдумывания — общая задержка действительно велика. Дело не в медленной работе шлюза; сама генерация занимает много времени.
2. Без потоковой передачи весь результат буферизуется перед отправкой. При отсутствии потоковой передачи (stream опущен или false) сервер должен дождаться, пока модель завершит всю генерацию, и только затем отправить весь body одним ответом. В течение этих минут тайм-аут чтения вашего клиента конкурирует с этим ожиданием, и чем дольше генерация, тем выше вероятность отключения до получения результата — при этом исключение часто оказывается пустым (httpx.ReadError’s str(e) пуст), поэтому вы не сможете увидеть причину.
3. За разорванное соединение всё равно взимается плата, поэтому повторные попытки вслепую приводят к двойной тарификации. После того как сервер сгенерировал вывод, вызов тарифицируется, даже если результат до вас не дошёл. Повторная попытка после того, как вы уже получили часть body, означает, что модель запустится снова и вы заплатите повторно.

​

Используйте потоковую передачу, не используйте непотоковый режим

import json
import httpx

def generate_long_text(prompt, api_key, model="claude-opus-5", max_tokens=64000):
    url = "https://api.apiyi.com/v1/messages"
    headers = {
        "x-api-key": api_key,
        "anthropic-version": "2023-06-01",
        "content-type": "application/json",
        "accept": "text/event-stream",
    }
    payload = {
        "model": model,
        "max_tokens": max_tokens,
        "stream": True,                        # key: long output must stream
        "thinking": {"type": "adaptive"},      # adaptive thinking; the model decides depth
        "messages": [{"role": "user", "content": prompt}],
    }
    # Three-part timeout: read only covers the inter-event gap, not the whole generation
    timeout = httpx.Timeout(connect=30, write=120, read=120, pool=30)

    text, stop_reason = [], None
    with httpx.Client(timeout=timeout) as c:
        with c.stream("POST", url, json=payload, headers=headers) as r:
            if r.status_code != 200:
                raise RuntimeError(f"HTTP {r.status_code}: {r.read()[:400]}")
            event, data = None, []
            for line in r.iter_lines():
                if line == "":                 # events are separated by a blank line
                    if data:
                        d = json.loads("\n".join(data))
                        t = d.get("type") or event
                        if t == "content_block_delta" and d.get("delta", {}).get("type") == "text_delta":
                            text.append(d["delta"]["text"])
                        elif t == "message_delta":
                            stop_reason = d.get("delta", {}).get("stop_reason") or stop_reason
                    event, data = None, []
                    continue
                if line.startswith("event:"):
                    event = line[6:].strip()
                elif line.startswith("data:"):
                    data.append(line[5:].strip())
    # A Claude stream ends on message_stop, never [DONE]
    if stop_reason == "max_tokens":
        raise RuntimeError(f"truncated by max_tokens after {len(''.join(text))} chars; raise max_tokens and retry")
    return "".join(text).strip()

​

Настраивайте таймаут чтения по интервалу между событиями, а не по общему времени

# connect: establish; write: upload the request body; read: max gap between reads
timeout = httpx.Timeout(connect=30, write=120, read=120, pool=30)

​

Настройка в различных клиентах

​

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

• Симптом: сначала текст поступает нормально, затем перестает приходить вовсе — при этом соединение не возвращает ошибку и не закрывается. Клиент зависает до срабатывания собственного таймаута: если он равен одному часу, клиент прождет целый час и в итоге получит лишь небольшой начальный фрагмент.
• Причина: на межрегиональных и трансграничных сетевых маршрутах долго удерживаемое открытым соединение может зависнуть на промежуточном сетевом оборудовании. Сервер уже давно завершил генерацию и закрыл соединение, но сигнал закрытия так и не доходит до вас. Чем дольше длится соединение, тем выше вероятность этого — соединение продолжительностью 20 минут сталкивается с этим чаще, чем 3-минутное.
• Тарификация: сервер завершает генерацию и производит тарификацию как обычно (см. пункт 3 в «Три вещи, которые нужно знать в первую очередь»).

1. Настройте таймаут чтения в соответствии с интервалом между событиями (предыдущий раздел). При таймауте чтения 120 с зависание будет стоить вам двух минут ожидания перед повторной попыткой; при таймауте в один час вы потеряете целый час. Это самый важный шаг.
2. Сокращайте длительность каждого соединения: разбивайте очень длинные ответы на несколько вызовов — см. «Разбивайте очень длинные ответы на несколько вызовов» ниже.
3. Возобновляйте прерванный поток с места остановки — см. «Стратегия повторных попыток» ниже.

​

Оставьте место для max_tokens и проверяйте stop_reason

• Установите max_tokens на 64000 (при высоком уровне усилий или глубоком рассуждении задавайте ещё больше; claude-opus-5 поддерживает вывод размером до 128K).
• Проверяйте stop_reason перед использованием ответа:
  • end_turn — завершено штатно, текст полный; это единственный успешный результат.
  • max_tokens — усечено, текст может быть неполным или даже пустым. Это усечение, а не «пустой результат» — увеличьте max_tokens и повторите запрос.
  • refusal — запрос отклонён политикой безопасности; обработайте этот случай отдельно.

​

Разбивайте очень длинные ответы на несколько запросов

1. Сначала сгенерируйте план / список серий / список глав — это будет короткий вызов.
2. Затем генерируйте по одной главе или серии за вызов, укладываясь в 10k–20k символов. Добавляйте план и необходимый для каждой части контекст (описания персонажей, чем закончилась предыдущая часть), чтобы сохранить согласованность.
3. После утверждения плана части становятся независимыми, и их можно генерировать параллельно.

​

Стратегия повторных попыток

• Повторяйте попытки только при сбоях до получения заголовков ответа и при 5xx / 429 (с задержкой, не более двух раз). Это проблемы с подключением или кратковременные сбои, при которых повторный запрос имеет смысл.
• Если stream обрывается после того, как вы уже получили часть тела ответа, возобновите его с места остановки вместо запуска с самого начала. Сервер уже сгенерировал эту часть и тарифицировал её; перезапуск запустит процесс заново и потребует повторной оплаты. Сохраните полученный текст, передайте его в новом вызове как уже написанное и позвольте модели продолжить — вы заплатите только за оставшуюся часть.
• Поступайте так же и при таймауте чтения (зависшем соединении): если вы уже получили достаточное количество текста, возобновите генерацию; если почти ничего не получено, повторите весь вызов целиком.
• Логируйте request id из заголовков ответа для сверки и устранения неполадок.

messages = [{
    "role": "user",
    "content": (
        f"{original_prompt}\n\n"
        f"Here is what has been written so far:\n\n{partial_text}\n\n"
        "Continue directly from the last sentence above. Do not repeat existing content or add any commentary."
    ),
}]

​

Шпаргалка по сценариям

​

Связанные материалы