responseSchema で $ref が使えず詰まったら — responseJsonSchema で再帰スキーマを本番で扱う
Gemini の responseSchema は OpenAPI サブセットで $ref/$defs が使えず、共有定義も再帰も表現できません。responseJsonSchema へ移行し、多言語フィールドの再利用とカテゴリ木の再帰を本番で扱う実装をまとめました。
長尺PDFの章ごと要約で、まる一章が要約から消えていたとき — 被覆率を計測して取りこぼしを塞ぐ運用メモ
章ごと要約→全体再結合は長尺PDFに効きますが、抽出漏れや再結合で一章がまるごと消えても要約は素知らぬ顔で完走します。被覆率という一つの数字で取りこぼしを検知し、消えた章だけ再実行する監査つきパイプラインを実装で示します。
同じナレーションを二度生成しない — TTS 音声を端末にキャッシュする鍵設計と失効の運用
瞑想・癒し系アプリのように同じ音声を何度も再生する場面で、Gemini TTS の出力そのものをキャッシュしてコストを実質ゼロに近づける設計です。テキストだけでは足りないキャッシュキーの組み立て方、サーバ生成キャッシュと端末キャッシュの二層構成、モデル停止期限への備えとしての失効ポリシーを、動くコードと実測値でまとめました。
無料ユーザー一人あたりのトークン予算を決める — AdMob 収益と AI 機能のコストを釣り合わせる設計
レート制限は秒あたりを守りますが、月末の請求は守ってくれません。広告収益から一人あたりのトークン予算を逆算し、呼び出しラッパー一か所で台帳を作り、ソフトキャップで段階的に降格させ、上位1%の消費比率で濫用を検知するまでを、動くコードとともにまとめます。
Gemini API のシステム指示とプロンプト設計 — 出力品質を劇的に上げる実践テクニック
Gemini API のシステム指示（system_instruction）とプロンプトエンジニアリングの実践的なテクニックを解説します。出力品質にダイレクトに効く設計パターンを、動作するコード例と共に紹介します。
gemini-embedding-2 の検索精度が伸びないとき、最初に task_type を疑う
gemini-embedding-2 の検索が惜しい外れ方をするとき、原因は task_type の指定漏れや不一致であることが多いです。ドキュメントとクエリで用途を揃え、再現率を取り戻す実装と検証手順をまとめました。
構造化出力のストリーミングで、完成したフィールドから順に画面へ出す — 不完全なJSONを安全に読む部分パース
responseSchema でストリーミングすると、JSONが閉じるまで画面は真っ白なまま待たされます。不完全なJSONを安全に補完して読む部分パースと、一度出した値を後退させない逆流防止を組み、最初のフィールドまでの体感を実測とともに縮める設計を残します。
モデルの提供終了通知が届くたびに慌てないために — Gemini 依存を一枚の層に閉じ込める個人アプリ設計
画像生成モデルの停止通知が届いた朝、依存が散らばっていると差し替えは半日仕事になります。Gemini 依存を一枚のポート層に閉じ込め、フォールバックと廃止期限のCI監視まで含めた個人アプリ設計を、動くコードとともに残します。
Managed Agents を本番に上げる前に、固定シナリオで挙動を測る — 非決定的なエージェントに回帰スイートと段階昇格を敷く
公開プレビューの Managed Agents は隔離サンドボックスで自律的に動く分、プロンプトや設定を少し変えただけで挙動が静かにずれます。単発プロンプトのように出力を一度突き合わせるだけでは足りません。固定シナリオを何度も回して合格率で測る回帰ハーネスと、影→カナリア→全面の段階昇格、逸脱時の自動ロールバックまでを、動く Python とともに設計します。
使っているモデルの廃止予告だけを拾う — url-context に公式チェンジログを読ませる仕組み
画像モデルの停止を公開3日前に知って肝を冷やしました。url-context に公式チェンジログを直接読ませ、自分が実際に使っているモデルの廃止予告だけを構造化して差分通知する仕組みを、そのまま動く Python と運用で削った過検知の調整まで含めて組み立てます。
一晩のバッチで静かに落ちた数十件をどう拾うか — Gemini Batch API の行単位リトライ台帳
Batch API の「完了」は「全件成功」ではありません。個人開発で夜間バッチを回し続けるなかで見えた、行単位の結果台帳・一時失敗と恒久失敗の切り分け・選択的リトライ・恒久失敗の無限リトライ防止を、SQLite で組んだ状態機械の動くコードとともに残します。
公開前に「意味が近すぎる過去記事」を弾く — Gemini Embedding でトピック共食いを防ぐ類似ゲート
記事数が数百本を超えると、新しく書いた記事が過去記事と検索面で共食いを起こします。gemini-embedding-2 で本文の意味ベクトルを持ち、公開前にコサイン類似で近すぎる既存記事を弾くゲートを、動くコードと閾値の決め方まで実装します。