すべての記事
テストは緑のまま、本番だけが止まる — 録画フィクスチャがモデル停止を隠す構造と freshness gate
録画済み API レスポンスで回るテストは、モデル停止をすり抜けます。テストが全部緑のまま本番だけ404になる構造を最小構成で再現し、pytest 起動前に cassette を検疫する freshness gate の実装、走査コストの実測、しきい値の決め方をまとめました。
gemini-flash-latest への追従をやめた日 — モデルの静かな置き換えに耐えるバッチ設計
発表を伴わないモデル更新で、安定していたバッチの拒否率が一晩で4倍を超えました。gemini-flash-latest への追従をやめ、ピン留めとカナリア昇格の二段構えに移行するまでの実測と設計判断をまとめております。
難読化されたスタックトレースを Gemini に渡していました — retrace を前段に置くまで、診断はもっともらしく外れ続けます
release ビルドのスタックトレースは R8 で名前が潰れています。それをそのまま Gemini に渡すと、診断は落ち着いた文体のまま外れます。retrace を前段に置き、mapping を versionCode で突合し、復元できないときは断定させない。42件で数え直した記録です。
生成ログを丸ごと残すのをやめました — 3層の保持設計とプロンプト指紋で追跡性だけを残す
Gemini API のリクエストとレスポンスを丸ごと保存する運用をやめ、3層の保持設計とプロンプト指紋に切り替えた記録です。本文を消しても原因を辿れる最小限のログとは何か、成功ログを3%に絞った理由、切り替え後3週間の実感まで書いています。
TTS の継ぎ目を耳に残さない — 長文ナレーションの抑揚と無音境界を整える設計
長文を文単位で割って合成すると、文の変わり目で抑揚がリセットされ継ぎ目が耳につきます。文脈プライミング・ゼロクロス整合・句読点別の適応的無音・冪等なシーム台帳の四層で、繋ぎ目を聞こえなくする設計を実装ごとまとめます。
同じナレーションを二度生成しない — TTS 音声を端末にキャッシュする鍵設計と失効の運用
瞑想・癒し系アプリのように同じ音声を何度も再生する場面で、Gemini TTS の出力そのものをキャッシュしてコストを実質ゼロに近づける設計です。テキストだけでは足りないキャッシュキーの組み立て方、サーバ生成キャッシュと端末キャッシュの二層構成、モデル停止期限への備えとしての失効ポリシーを、動くコードと実測値でまとめました。
例外にならない失敗を型で閉じる — Gemini API のレスポンスを判別可能ユニオンに正規化する
HTTP 200 なのに本文が空、という失敗は try/catch では捕まりません。finishReason と blockReason を判別可能ユニオンに正規化し、never による網羅性チェックで処理漏れをコンパイル時に潰す設計をまとめました。
音声が全部できるまで待たせない — Gemini TTS ストリーミング生成を配信経路に組み込む設計
gemini-3.1-flash-tts-preview が streamGenerateContent に対応しました。最初の音が出るまで実測1.8秒の配信経路を、PCM境界処理・文単位の再開・preview停止フォールバックまで含めて設計します。
ワンクリックデプロイの『その先』— AI Studio から Cloud Run に出した Gemini アプリを本番に引き上げる点検手順
AI Studio の build タブから Cloud Run へワンクリックデプロイした Gemini アプリは、そのままでは本番相当ではありません。APIキーの保管・認証・費用上限・観測の4点を、gcloud コマンドつきで点検する手順を整理しました。
元データを消しても生成物は残る — Gemini 派生データに削除を伝播させる台帳設計
ユーザーが元データを削除しても、Gemini で生成した埋め込みやキャッシュにはテキストが残り続けます。生成時に由来を記録する provenance 台帳、シンク別の削除伝播ワーカー、取りこぼしを数える検証スイープまで、削除を派生データに追随させる設計をまとめました。
url_context が取得に失敗しても答えは返ってくる — 取得ステータスを検証してから通すゲート設計
url_context ツールは対象URLの取得に失敗しても、それらしい回答を返します。url_context_metadata の取得ステータスを読み、根拠URLが実際に読めた時だけ答えを確定する検証ゲートと、失敗時のフォールバックを実装します。
Gemini API × Astro でAI機能付きコンテンツサイトを作る実装ガイド
Astro の Server Endpoints と Content Collections を Gemini API と組み合わせ、AI要約・関連記事生成・自動タグ付けを実装する手順を、動くコードとともに解説します。