◉GEMINI LABEN
●OMNI 1.2 — Gemini Omni 1.2 Flash が GA になりました(11/5)。最長15秒の動画生成と会話での編集に対応し、1.1 Flash は 12/3 に自動で 1.2 へ振り替わります●COMPUTER — Computer Use が Interactions / GenerateContent API で GA になりました(10/30)●LIVE — Live と TTS のプレビュー版は最短 11/17 に停止します(残り7日)。移行先は gemini-3.8-live と 3.8 系 TTS です●CLI — Gemini API CLI(gemini-api)がベータで登場(10/27)。エージェントやCI向けのゼロ依存クライアントです●2.5 PRO — gemini-2.5-pro と 2.5-flash は 12/1 から自動で振り替えられます(残り21日)。移行先は 3.8 Flash と 3.5 Flash-Lite です●NEW — クラッシュ報告を毎回ゼロから読ませない — 既知バグ早見表を先に grep し…●OMNI 1.2 — Gemini Omni 1.2 Flash が GA になりました(11/5)。最長15秒の動画生成と会話での編集に対応し、1.1 Flash は 12/3 に自動で 1.2 へ振り替わります●COMPUTER — Computer Use が Interactions / GenerateContent API で GA になりました(10/30)●LIVE — Live と TTS のプレビュー版は最短 11/17 に停止します(残り7日)。移行先は gemini-3.8-live と 3.8 系 TTS です●CLI — Gemini API CLI(gemini-api)がベータで登場(10/27)。エージェントやCI向けのゼロ依存クライアントです●2.5 PRO — gemini-2.5-pro と 2.5-flash は 12/1 から自動で振り替えられます(残り21日)。移行先は 3.8 Flash と 3.5 Flash-Lite です●NEW — クラッシュ報告を毎回ゼロから読ませない — 既知バグ早見表を先に grep し…
記事一覧/API / SDK
◈ API / SDK/2026-05-20中級

Gemini API のストリーミングが本番だけまとめて返ってくる — Cloud Run・Vercel・Cloudflare のバッファリング対処

ローカル開発では一文字ずつ流れるのに本番デプロイ後だけ応答が一括で返ってくる — Cloud Run / Vercel / Cloudflare Workers / Nginx で発生するストリーミングバッファリング問題を、原因と対処パターン別に整理しました。

gemini-api293streaming18troubleshooting64cloud-run6vercelcloudflare4

カテゴリ提案 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 のような重い変換は、最後にまとめて通すと体感が軽くなります。

検証用チェックリスト

デプロイの前に、私が手元で通している項目です。

  1. curl --no-buffer -N で文字が段階的に出ることを確認
  2. Response ヘッダに Cache-Control: no-cache, no-transform と X-Accel-Buffering: no を設定
  3. Cloud Run は --timeout を明示(--use-http2 は疎通確認とセットで)
  4. Vercel の Node Runtime は export const dynamic = "force-dynamic" を明示
  5. Cloudflare Workers の中継は upstream.body を直接受け渡し
  6. クライアントの TextDecoder.decode(value, { stream: true }) を指定

この順番で見るようになってから、本番だけストリーミングが死ぬ事故に振り回される時間は、はるかに短くなりました。

全体を振り返って

ストリーミング応答が本番だけ効かない問題は、Gemini API の側ではなく、経路上のプラットフォームと、それを正しく扱えていない実装に原因があることが大半でした。最初に curl --no-buffer で経路の挙動を切り分け、次にサーバー実装(await response.text() をしていないか)とヘッダ、最後にプラットフォーム固有の設定を順に見ていくと、ほとんどの症状は説明がつきます。

一方で、設定を変えて直った気がしても、本当に効いたのがどの変更だったのかは、計測し直さないと分からないのだと思います。

次の一歩としては、いま動いている本番エンドポイントに、上の curl --no-buffer を 1 回だけ当ててみていただければと思います。「沈黙 → ドカッ」が再現するなら、この記事のどれかの章に該当しているはずです。

同じく個人で複数のサービスを並行運用している方の、デバッグの時間を少しでも短くできていれば嬉しく思います。

シェア

お読みいただきありがとうございます

Gemini Lab は広告なしで運営しており、サーバー費用などの運営コストはメンバーシップのご支援で賄っています。実装コード・ベンチマーク・本番設計パターンなど、実務でお役立ていただける記事を毎日更新しています。もし読んでよかったと感じていただけましたら、ぜひご覧ください。

  • ✦コピー&ペーストで使える実装コード付き
  • ✦毎日新しい上級ガイドを追加
  • ✦¥580/月 または ¥1,480 の永久アクセス
メンバーシップを見る →

もしこの記事がお役に立ちましたら、チップ(¥150)で応援いただけると大変励みになります。広告なしでの運営を続けるため、皆さまのご支援が大きな力になっています。

関連記事

◈ API / SDK2026-10-19
404 と 429 が同じログに並んだら、上限より先にモデル名を確かめます
Gemini API のログに 404 NOT_FOUND と 429 RESOURCE_EXHAUSTED が混ざって出たとき、どちらから疑うかの順番と、生成を伴わずに切り分ける最小の Python スクリプトをまとめます。
◈ API / SDK2026-10-16
models は 200 なのに generateContent だけ 403 になる日 — 切り分けの順番を先に決めておく
モデル一覧の取得は 200 で通るのに、生成リクエストだけが 403 permission_denied で止まるときの切り分け手順です。キー・プロジェクト・請求の順に確かめる小さな診断スクリプトと、リトライしてはいけない理由、サポートへ渡す材料の揃え方をまとめました。
◈ API / SDK2026-05-17
Gemini API で画像バッチ分析の INVALID_ARGUMENT エラーを診断する
Gemini API で複数画像をまとめて分析すると INVALID_ARGUMENT(HTTP 400)で止まる。MIME タイプ・サイズ・contents の構造・画像そのものの破損を切り分ける表と、google-genai SDK で書き直した検査コード、inline と File API の使い分け基準をまとめました(2026年11月時点)。