
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の直叩きを接続経路ごとに試してみてください。