長文出力の実践ガイド

​

最初に知っておくべき3つのこと

1. 10k語の出力では、実際の生成に10～20分かかるのは正常です。 モデルは数万文字をtokenごとに出力し、さらに推論／thinkingフェーズもあるため、エンドツーエンドのレイテンシーは実際に長くなります。これはゲートウェイが遅いのではなく、生成そのものに時間がかかっているためです。
2. 非ストリーミングでは、すべてをバッファリングしてから送信します。 非ストリーミング（streamが省略されている、またはfalseの場合）では、サーバーはモデルが生成全体を完了するまで待機し、その後にレスポンスボディ全体を一度に返す必要があります。その数分間、クライアントの読み取りタイムアウトとの競争になり、生成が長いほど結果が到着する前に切断される可能性が高くなります。また、例外は空であることが多く（httpx.ReadErrorのstr(e)が空欄）、原因を確認できません。
3. 接続が切断されても課金されるため、無計画なリトライは二重課金になります。 サーバーが出力を生成した時点で、結果が届かなかった場合でも呼び出しは課金されます。すでにボディの一部を受信した後にリトライすると、モデルは再度実行され、再び料金が発生します。

​

ストリーミングを使用し、非ストリーミングは使用しない

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)

​

各クライアントでの設定方法

​

Streams も停止することがある：途中で接続の受信が止まる現象

• 症状：最初は通常どおりテキストが届きますが、その後何も届かなくなります。それにもかかわらず、接続はエラーにも切断にもなりません。クライアントは自身のタイムアウトまでハングします。タイムアウトが1時間の場合、丸々1時間待たされた挙句、最初のわずかな断片しか得られません。
• 原因：リージョン間や国境をまたぐネットワーク経路において、長時間維持されている接続が中間ネットワーク機器でスタックすることがあります。サーバー側ではとっくに生成を完了して接続を切断しているにもかかわらず、その切断通知がクライアントに届きません。接続時間が長くなるほど、この現象が発生する可能性が高くなります（3分の接続よりも20分の接続の方が頻繁に発生します）。
• 課金：サーバー側で生成が完了し、通常どおり課金されます（「最初に知っておくべき3つのこと」のポイント3を参照）。

1. 読み取りタイムアウトをイベント間隔に合わせて設定する（前セクション参照）。読み取りタイムアウトを120秒に設定していれば、停止が発生してもリトライまでに2分しかかかりませんが、1時間の読み取りタイムアウトでは丸々1時間かかります。これが最も重要です。
2. 各接続の時間を短くする：非常に長い出力は複数の呼び出しに分割してください（下記の「非常に長い出力を複数の呼び出しに分割する」を参照）。
3. 中断された stream を停止した位置から再開する — 下記の「リトライ戦略」を参照してください。

​

max_tokens に余裕を持たせ、stop_reason を確認する

• max_tokens は 64000 から開始してください（高い effort / 深い thinking ではさらに多く指定してください。claude-opus-5 は 128K 出力に対応しています）。
• レスポンスを使用する前に stop_reason を確認してください:
  • end_turn — 正常に完了しており、テキストは完全です。これが唯一の成功です。
  • max_tokens — 切り詰められており、テキストが不完全、または空の場合もあります。これは切り詰めであり、「空の結果」ではありません — max_tokens を増やして再試行してください。
  • refusal — 安全ポリシーにより拒否されました。別途処理してください。

​

非常に長い出力を複数の呼び出しに分割する

1. まずアウトライン / エピソード一覧 / 章リストを生成します（短時間の呼び出し）。
2. 次に、各出力を1万〜2万文字未満に抑えつつ、1回の呼び出しにつき1つの章またはエピソードを生成します。各パートの一貫性を保つため、アウトラインと必要なコンテキスト（キャラクター設定や直前のパートの結末など）を含めます。
3. アウトラインが確定すれば、各パートは独立しているため並列実行が可能です。

​

Retry strategy

• Retry only on failures before the response headers arrive, and on 5xx / 429 (with backoff, at most twice). Those are connection or transient issues where a retry makes sense.
• If a stream drops after you already received part of the body, resume from where it stopped instead of starting over. The server has generated and billed it; restarting runs it again and pays again. Keep the text you received, include it in a new call as what has been written so far, and let the model continue — you pay only for the remainder.
• Treat a read timeout (a stalled connection) the same way: if you already have a good amount of text, resume; if you received almost nothing, retry the whole call.
• Log the request id from the response headers for reconciliation and troubleshooting.

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."
    ),
}]

​

シナリオ別チートシート

​

関連