メインコンテンツへスキップ
見出し画像

LLMのストリーミングが最後にまとめて届くときの確認順

    社内の問い合わせ画面にClaude APIのストリーミングを組み込みました。手元のPCでは文字が流れるように出るのに、検証サーバーへ置くと、20秒ほど何も表示されないまま全文が一度に現れます。APIを呼ぶコードに stream=True は付いていて、ログにも content_block_delta が1件ずつ出ています。つまりAPIから受け取る側は正しく動いていて、その先のどこかで止まっていることになります。
    自分たちは以下の順で切り分けました。

    手順1 APIとアプリのサーバーを分けて見る

    最初に、アプリを介さずAPIへ直接つなぎ、ストリームが逐次届くかを見ます。curl の -N はバッファを切るオプションです。これを付けないと curl 自身が出力をためるので、プロキシを疑う前に自分の確認で騙されます。

    curl -N <https://api.anthropic.com/v1/messages> \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "content-type: application/json" \
      -d '{"model":"claude-sonnet-5-5","max_tokens":512,"stream":true,
           "messages":[{"role":"user","content":"1から30まで数えて"}]}'
    

    イベントが1行ずつ流れれば、APIまでは問題ありません。次に、アプリのサーバーのポートへプロキシを通さずに同じ形で curl します。たとえば uvicorn を 8000 番で動かしているなら、localhost:8000 を直接叩きます。

    • ここで逐次届くなら、原因はアプリより前段(プロキシ、CDN)にある

    • ここでもまとめて届くなら、アプリの実装か、ミドルウェアが本文を一度読み切っている

    今回は直接叩いた時点では逐次届きました。プロキシ側に絞れた形です。

    手順2 レスポンスヘッダーを見る

    プロキシ経由の応答ヘッダーを curl -sI ではなく -D - で取ります。HEAD ではアプリが違う応答を返すことがあるためです。

    curl -N -s -D - -o /dev/null <https://example.internal/api/chat> \
      -H "content-type: application/json" \
      -d '{"message":"数えて"}'
    

    見るのは次の3行です。

    • Content-Type が text/event-stream になっているか。application/json のままだと、フレームワークがストリームとして扱っていない

    • Content-Encoding が gzip になっていないか。圧縮はブロック単位でバッファするため、短いイベントが溜まってから出る

    • Content-Length が付いていないか。付いているなら、どこかで本文を読み切ってから返している

    自分たちの環境では、Content-Type は正しく、Content-Encoding に gzip が付いていました。nginx の gzip がSSEにも掛かっていたわけです。

    手順3 nginxのバッファと圧縮を切る

    nginx は既定で、上流の応答をバッファに溜めてからクライアントへ送ります。proxy_buffering が on のままだと、LLMの出力のように少しずつ届く応答が、バッファが満ちるか上流が閉じるまで出てきません。ストリーミング用のロケーションだけ、次のように切ります。

    location /api/chat {
        proxy_pass <http://app:8000>;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        gzip off;
        proxy_read_timeout 300s;
    }
    

    proxy_http_version 1.1 と Connection の空指定は、上流との接続を保つための組です。1.0 のままだと応答ごとに接続が閉じ、チャンク転送も使えません。proxy_read_timeout は既定の60秒だと、長い生成の途中で切られることがあるので延ばしています。
    nginx の設定を触れない場合は、アプリ側から応答ヘッダーで頼む方法もあります。X-Accel-Buffering: no を付けると、nginx はその応答に限ってバッファを使いません。

    from fastapi import FastAPI
    from fastapi.responses import StreamingResponse
    
    app = FastAPI()
    
    @app.post("/api/chat")
    async def chat(body: ChatBody):
        return StreamingResponse(
            generate(body.message),
            media_type="text/event-stream",
            headers={
                "Cache-Control": "no-cache",
                "X-Accel-Buffering": "no",
            },
        )
    

    手順4 アプリ側のミドルウェアを疑う

    プロキシを直しても変わらないとき、残るのはアプリの中です。FastAPI や Starlette では、GZipMiddleware がストリーミング応答を一定量まとめて圧縮します。ログ用のミドルウェアが response.body を読んでいると、そこで全文を待ちます。
    確認は簡単で、ミドルウェアを1つずつ外して手順1の localhost 直叩きをやり直します。自分たちの環境では、アクセスログを整形するために入れた自作ミドルウェアが、応答の本文を文字列にして記録していました。ストリームを丸ごと読んでいたので、直前の手順で直してもまとめて届く動きは変わりませんでした。ヘッダーだけを記録する形にして解消しています。
    ここは今回いちばん時間を使った箇所です。nginx を直した時点で終わったつもりになり、アプリ側を見る順番が遅れました。

    手順5 CDNと、サーバーレスの実行環境

    社内サーバーならここまでで済むことが多いのですが、CDN や WAF を前に置いている構成では、そちらにも同じ種類の設定があります。たとえばCloudflareの前段では、圧縮やバッファの挙動がプランや設定で変わります。Vercel のサーバーレス関数では、フレームワークの側でストリーミングを有効にしていないと、関数の終了までまとめて返ります。環境ごとの細かい条件は自分の環境でしか確かめていないので、ここは各サービスの公式ドキュメントで該当ページを開いて確認してください。
    見分け方は共通です。手順1の直叩きで逐次届き、プロキシ経由でまとめて届くなら、間に挟まっている層をネットワークの手前から順に外していきます。外せない層は、ヘッダーの指定でバッファを避けられるかを試します。

    クライアント側の確認

    APIから画面までの途中で止まっていないのに、画面だけまとめて出ることもあります。ブラウザの fetch で読むときは、response.body.getReader() で少しずつ読み、そのたびに状態を更新しているかを見ます。await response.text() で読み切ってしまうと、サーバーが逐次送っていても画面は最後に1回だけ更新されます。

    const res = await fetch("/api/chat", { method: "POST", body });
    const reader = res.body.getReader();
    const decoder = new TextDecoder();
    for (;;) {
      const { value, done } = await reader.read();
      if (done) break;
      appendText(decoder.decode(value, { stream: true }));
    }
    

    TextDecoder の stream: true を付け忘れると、日本語がチャンクの境目で文字化けします。3バイトの文字が2つのチャンクに割れるためで、ストリーミングを入れた直後に見つかりやすい不具合です。

    再発防止

    同じ原因を二度踏まないために、デプロイ後の確認項目へ1行足しました。

    • 本番相当の経路で curl -N を実行し、最初のイベントが届くまでの秒数を記録する

    • 最初のイベントが2秒を超えたら、手順1から順に層を外して調べる

    LLMのストリーミングは、どこか1か所の層がバッファを持つだけで機能しなくなります。しかも正常系のテストではレスポンス全文が揃うため、テストは緑のままです。体感の遅さでしか気づけない不具合なので、最初のイベントまでの秒数を数字で見ておくと、設定を変えた後の退行にも早く気づけます。
    まだ確かめられていないのは、社内のVPN経由でつないだときの挙動です。VPN装置が応答をバッファする例を聞いたことはありますが、自分たちの環境では再現していません。該当する構成の方は、手順1の直叩きを接続経路ごとに試してみてください。

    あなたへのおすすめ