勉強会_APIキー活用編_中堅向け

勉強会 / A PIキー活用編 / 中堅向け（第2部・2時間） APIを“本番”で使う： 設計・コスト・運用 ～ キーの置き場所・失敗前提の設計・コストと監視 ～ 対象：PoCは作れる、本番運用の勘所を持ちたい中堅エンジニア（第2部） 面白きこともなき世を面白く

O R I EN T AT I ON 今日のゴールと前提（第2部・2時間） ゴール 前提（第1部の到達点） APIキーが危険物だと理解している • キーの“置き場所”を正しく設計できる 『どのAI＋お願い＋キー』で呼べる • AIの失敗を前提に“守る”実装ができる • コスト・監視・再現性を運用に組み込める 小さな呼び出しを設計できる ※未受講なら第1部の安全ルールを5分で補う。

PROB L EM PoCは動く。でも本番で困る キーが漏れる構成 AIが時々おかしい コストが読めない クライアントに置いたまま公開 フォーマット崩れ・嘘・空応答 呼びすぎ・想定外の課金 「動いた」と「運用できる」は別。今日はこの3つを設計で潰す。

A R CHI T EC TU R E いちばんの分かれ道：キーをどこに置く？ クライアント直（危険） サーバ経由（安全） ブラウザのコードにキーを置く キーはサーバ側だけに置く → 誰でも開発者ツールで覗ける → クライアントはサーバに頼む → 公開した瞬間に漏れる → キーはユーザーに渡らない 例外：本人だけが自分のキーを入れる“ローカルツール”はクライアント可（配布物にしない）。

WHY なぜクライアント直書きは漏れるのか ブラウザに届いた時点で、コードは“誰でも読める”状態になる。 配布したHTML/JS 開発者ツールで丸見え 中にキーが書いてある F12 → ソースを見れば 誰でもキーを取り出せる 「難読化」でも守れない。秘密は“クライアントに置かない”が唯一の答え。

SOL UT ION 安全な構成：サーバ（プロキシ）を挟む クライアント 自分のサーバ AIサービス キーを持たない キーはここだけ 結果を返す クライアントは自分のサーバにお願い → サーバがキーを付けてAIへ。キーは外に出ない。

ROBUS T ① 結果はJSONで“構造化”して受け取る 自由文のまま使う JSONで返させる AIの文章をそのまま画面へ 「この形のJSONだけ返して」 → 表記ゆれ・余計な前置きで と指示 → 機械的に取り出せる 後処理が壊れる → 壊れにくいUIに 受け取ったらparseは必ずtry/catch。崩れた時の代替表示も用意する。

ROBUS T ② 失敗を前提に“守る”実装 リトライ 一時的な失敗は間隔を空けて再試行（指数バックオフ） タイムアウト 返ってこない時に待ち続けない上限を設ける フォールバック 失敗時の代替（再入力・既定値・人手）を用意 AIは“たまに失敗する部品”として扱う。落ちないように囲うのが中堅の仕事。

CO S T/ R AT E コストとレート制限を管理する 上限を設ける まとめる/減らす キャッシュ 1日/1機能あたりの呼び出し回数や 予算に上限 不要な呼び出しを削る。1回で済む よう設計 同じ入力は結果を再利用して呼ば ない 「呼ばない設計」がいちばん効く。レート制限は“待つ・間引く”で受け流す。

SE CU R IT Y 運用のセキュリティ キー管理 環境変数/秘密管理サービス。コードに残さない・ローテーション ログにキーを出さない リクエスト記録にキーやPIIを残さない 入力の扱い 送る前に個人情報・機密を含めない／マスクする

OPS 監視と再現性 見える化（監視） 再現性（テスト） • 呼び出し回数・失敗率・遅延 • 入出力を記録して後で検証 • コストの推移 • 代表ケースを固定して回帰確認 • 異常を早く気づく仕組み • AIの『直した』を事実で確認

CASE 実例：うさうさツールのAPIあり版 ローカルツールとして安全側に倒した設計 • キーは利用者が自分で入力（配布物に埋め込まない） • 既定では何も送らない（キー未入力＝完全オフライン） • 「APIなし版」とペアで提供し、用途で選べる • 通信先は明示（外殻は通信ゼロ、API版だけが送る） → 本番サーバ運用とは別解。「本人専用・既定で送らない」なら安全に配れる。

演習（25分） AI機能のフェイルセーフ設計を描く 1 作るAI機能を1つ決める 5分 2 キーの置き場所を決める（直/サーバ） 5分 3 失敗3種への対応を書く（崩れ/遅延/超過） 10分 4 コスト上限と監視項目を1つ決める 5分

RE VI EW 後輩のAPI実装をレビューする観点 キーは外に出ないか クライアント直書き・ログ出力がないか 失敗に備えているか リトライ/タイムアウト/フォールバックの有無 コストは制御されるか 上限・キャッシュ・無限呼び出し防止

第2部のま とめ • 秘密はクライアントに置かない（公開物はサーバ経由） • AIは“たまに失敗する部品”。リトライ/タイムアウト/フォールバックで囲う • コストは上限・キャッシュ・呼ばない設計で制御。監視と記録を運用に お疲れさまでした。面白きこともなき世を面白く