カテゴリ提案 API を本番に載せた夜のことです。ローカルでは一文字ずつ流れていた Gemini の応答が、デプロイした途端に数十秒の沈黙のあと、全文がドンと返ってくるようになりました。画面だけ見ると、フリーズしているのと変わりません。
Gemini API 側は、ちゃんと streamGenerateContent で小分けに返してくれています。間に挟まるプラットフォーム(Cloud Run・Vercel・Cloudflare Workers・Nginx)か、私自身のコードが、応答を バッファ していたのです。
最初にお伝えしたいのは、原因の見当をつける前に curl --no-buffer で経路を切り分けるのが、いちばん遠回りに見えて近道だということです。本番だけストリーミングが効かなくなる代表的な 5 つの原因と、プラットフォーム別の対処を書き残します。私が実際に踏んだ順に並べておりますので、同じ課題に向き合っている方の叩き台になれば幸いです。
まず「本当にバッファされているか」を切り分ける
私の経験では、本番だけ起きるストリーミング不具合の多くは、Gemini API ではなく経路上のどこかで chunk が貯められていることが原因でした。最初に切り分けるべきは「サーバー側はちゃんと小分けで吐いているのか」「クライアント側はちゃんと小分けで受け取れているのか」の 2 点です。
最も信用できる検証は curl --no-buffer です。ターミナルから本番エンドポイントを直接叩いて、文字が段階的に流れてくるかを観察します。
curl --no-buffer -N \
-H "Content-Type: application/json" \
-X POST "https://your-app.example.com/api/chat" \
-d '{"prompt": "Gemini API のストリーミング検証用。長めに答えて"}' \
2>&1 | tee /tmp/stream.log--no-buffer は curl 自身の標準出力バッファを切り、-N で transfer-encoding chunked を待たずに受け取ります。これで「数十秒沈黙 → ドカッと出る」なら経路でバッファされており、「ポロポロ出てくる」ならサーバーは正常で、ブラウザ側の問題(fetch ReadableStream の扱いや SSE クライアント)に絞れます。
ブラウザの DevTools で確認するなら、Network パネルの該当リクエストを開いて EventStream タブまたは Timing の Content Download フェーズを見ます。Content Download が長く伸びていれば正常にストリーミングできており、Waiting (TTFB) だけが伸びている場合はサーバー側で全文生成を待ってから返している状態です。
原因 1: レスポンスを await response.text() で受けてしまっている
実装ミスとして一番多いのがこれです。Gemini SDK の generateContentStream() を呼んでも、その結果を JSON.stringify したり一旦バッファに詰めてから返すと、サーバー側でストリーミングは死にます。Next.js の Route Handler や Hono などのフレームワークでは、Response.body に ReadableStream をそのまま渡す形に揃えます。
// app/api/chat/route.ts (Next.js App Router)
import { GoogleGenAI } from "@google/genai";
export const runtime = "nodejs"; // ★ Edge にしない(後述)
export const dynamic = "force-dynamic";
export async function POST(req: Request) {
const { prompt } = await req.json();
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! });
// SDK のストリームを Web Streams にブリッジ
const stream = new ReadableStream({
async start(controller) {
const encoder = new TextEncoder();
try {
const result = await ai.models.generateContentStream({
model: "gemini-2.5-flash", // モデル名は提供状況に合わせて差し替えてください
contents: prompt,
});
for await (const chunk of result) {
const text = chunk.text;
if (text) controller.enqueue(encoder.encode(text));
}
} catch (err) {
controller.error(err);
} finally {
controller.close();
}
},
});
return new Response(stream, {
headers: {
"Content-Type": "text/plain; charset=utf-8",
"Cache-Control": "no-cache, no-transform",
"X-Accel-Buffering": "no", // Nginx 経路のバッファ無効化(後述)
"Transfer-Encoding": "chunked",
},
});
}ここで効くのは Cache-Control: no-transform と X-Accel-Buffering: no の 2 つです。後者は Nginx 系のリバースプロキシに「このレスポンスはバッファするな」と伝えるヒントです。Nginx を自前で挟んでいる構成では特に効きますが、マネージドな経路では無視されることもあるため、あくまで保険として入れております。
なお、古い記事や手元のサンプルに @google/generative-ai を使った例が残っている場合は、@google/genai への移行を先に済ませておくと、ストリームの取り出し方(result.stream が不要になり、chunk.text がプロパティになる点)で迷わずに済みます。
原因 2: Cloud Run の HTTP/2 とコネクションタイムアウト
Cloud Run はストリーミング自体を普通に扱えますが、私が踏んだ罠は 2 つあります。
1 つ目は request timeout です。デフォルトは 300 秒ですが、過去の設定で 60 秒などに絞ったままにしていると、Gemini 2.5 Pro の長い応答が途中で 504 になります。gcloud run services update YOUR_SERVICE --timeout=300 で明示しておくと、設定の食い違いを疑わずに済みます。
2 つ目は HTTP/2 の設定です。gcloud run services update YOUR_SERVICE --use-http2 で切り替えられますが、これはコンテナ側が h2c を話せることが前提です。Node の標準 HTTP サーバーのままでは通信できなくなる場合があるため、切り替えたらまず curl で疎通を確かめます。
壁紙アプリ向けの類似カテゴリ提案 API を Cloud Run に載せたとき、私の環境では数秒分の chunk がまとまって届く挙動が出ていました。原因を HTTP/1.1 だと決めつけて --use-http2 を入れたのですが、実際に効いたのは、サーバー側で出力のたびに明示的に書き出す処理を足したことのほうでした。設定を一つ変えて直った気がしても、curl --no-buffer で再計測するまでは、直ったと言わないことにしています。 この線引きは、それ以来崩さないようにしています。
原因 3: Vercel の Edge Runtime と Node Runtime の違い
Vercel に Next.js App Router をデプロイしている場合、Route Handler の runtime 指定 によってストリーミング挙動が大きく変わります。
| 設定 | ストリーミング | 最大実行時間 | 備考 |
|---|---|---|---|
runtime = "edge" | 安定 | プランごとに異なります(公式の Functions limits をご確認ください) | Web Streams ネイティブ。fetch ベース実装と相性が良い |
runtime = "nodejs" | 標準で OK だが要 force-dynamic | プランと maxDuration 設定で決まります | export const dynamic = "force-dynamic" を必ず指定 |
落とし穴は、Edge Runtime に載せた関数が外部呼び出しの回数や実行時間の上限に当たることと、Node Runtime で force-dynamic を書き忘れて Static 化されることです。後者の場合、ビルド時にレスポンスが事前生成されてしまい「常に同じ内容が一括で返ってくる」謎の挙動になります。ストリーミングが壊れたように見えて、実は何も生成されていなかった、という状況です。
最大実行時間を伸ばしたいときは、vercel.json で関数ごとに指定します(上限はプランに依存します)。
{
"functions": {
"app/api/chat/route.ts": {
"maxDuration": 300
}
}
}原因 4: Cloudflare Workers / Pages Functions のレスポンス整形
自分のサイトを Cloudflare Workers に載せているので、ここは特によく踏みます。Cloudflare Workers は ReadableStream をネイティブで扱えますが、間に cache-worker.js のようなキャッシュレイヤーを挟むと、応答ボディを await response.text() してから返す古い実装が紛れ込んでいるケース が定期的に発生します。
正しい Workers 側の中継パターンはこうです:
// _workers/cache-worker.js(簡略)
export default {
async fetch(request, env, ctx) {
// ストリーミング系の API はキャッシュをバイパス
const url = new URL(request.url);
if (url.pathname.startsWith("/api/chat")) {
const upstream = await fetch(request);
// ★ body をそのまま転送(クローンや text() 化は厳禁)
return new Response(upstream.body, {
status: upstream.status,
headers: {
...Object.fromEntries(upstream.headers),
"Cache-Control": "no-cache, no-transform",
},
});
}
// 他のパスは通常キャッシュ処理
return cacheHandler(request, env, ctx);
},
};upstream.body をそのまま new Response(..., { ... }) の第一引数に渡すのがポイントです。response.clone() を Promise.all で待ったり、await response.text() を経由すると、その時点で全文受信を待つので「Workers レイヤーでバッファされた」結果になります。
加えて、Smart Placement などで Worker の実行場所とオリジンが離れていると、往復の遅延がバッファリングのように見えることがあります。まず計測してから有効にするかどうかを決めるのが安全です。
原因 5: クライアント側 fetch + ReadableStream の処理ミス
サーバーが完璧でも、ブラウザ側で「全文受信してから一気に描画する」コードを書いていると、ユーザー体験はバッファされたのと同じです。fetch の ReadableStream は async iterator で 1 chunk ずつ取り出します。
// クライアント側
async function streamChat(prompt: string, onToken: (t: string) => void) {
const res = await fetch("/api/chat", {
method: "POST",
body: JSON.stringify({ prompt }),
headers: { "Content-Type": "application/json" },
});
if (!res.body) throw new Error("no body");
const reader = res.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
onToken(decoder.decode(value, { stream: true }));
}
}ここで decoder.decode(value, { stream: true }) の { stream: true } を忘れない ようにします。マルチバイト文字(日本語)を chunk の境界で受け取ると、これがないと文字化けや「不完全な文字を捨てる」挙動になり、結果として「数秒ごとに 50 文字単位で表示される」見え方になります。
React で扱うなら、chunk のたびに useState を呼ぶのではなく、useRef に溜めて描画フレームごとに反映する形にします。react-markdown のような重い変換は、最後にまとめて通すと体感が軽くなります。
検証用チェックリスト
デプロイの前に、私が手元で通している項目です。
curl --no-buffer -Nで文字が段階的に出ることを確認- Response ヘッダに
Cache-Control: no-cache, no-transformとX-Accel-Buffering: noを設定 - Cloud Run は
--timeoutを明示(--use-http2は疎通確認とセットで) - Vercel の Node Runtime は
export const dynamic = "force-dynamic"を明示 - Cloudflare Workers の中継は
upstream.bodyを直接受け渡し - クライアントの
TextDecoder.decode(value, { stream: true })を指定
この順番で見るようになってから、本番だけストリーミングが死ぬ事故に振り回される時間は、はるかに短くなりました。
全体を振り返って
ストリーミング応答が本番だけ効かない問題は、Gemini API の側ではなく、経路上のプラットフォームと、それを正しく扱えていない実装に原因があることが大半でした。最初に curl --no-buffer で経路の挙動を切り分け、次にサーバー実装(await response.text() をしていないか)とヘッダ、最後にプラットフォーム固有の設定を順に見ていくと、ほとんどの症状は説明がつきます。
一方で、設定を変えて直った気がしても、本当に効いたのがどの変更だったのかは、計測し直さないと分からないのだと思います。
次の一歩としては、いま動いている本番エンドポイントに、上の curl --no-buffer を 1 回だけ当ててみていただければと思います。「沈黙 → ドカッ」が再現するなら、この記事のどれかの章に該当しているはずです。
同じく個人で複数のサービスを並行運用している方の、デバッグの時間を少しでも短くできていれば嬉しく思います。