Skip to content

Instantly share code, notes, and snippets.

@kun432
Last active August 17, 2026 14:22
Show Gist options
  • Select an option

  • Save kun432/28557bd4bbbcbcdb22e6e55fe4f3a129 to your computer and use it in GitHub Desktop.

Select an option

Save kun432/28557bd4bbbcbcdb22e6e55fe4f3a129 to your computer and use it in GitHub Desktop.

Web API最適化デモガイド

https://github.com/kun432/python-web-api-sample

このプロジェクトは、Goal modeに対応したコーディングエージェントを使うWeb API最適化デモに利用できます。初期実装はAPIとして正しく動作しますが、データ量や同時アクセスが増えると顕在化する複数の性能上の問題を含んでいます。

デモで見せたいこと

単一の遅い処理を削除するのではなく、複数の独立した達成条件について測定・改善・再測定を繰り返し、すべて満たすまで作業を継続する様子を見せます。

想定する課題と改善方法は次のとおりです。

段階 課題 想定する改善
1 注文ごとに注文明細を取得するため、対象注文数に比例してSQL実行回数が増える(N+1 query) JOINや一括取得を使い、注文と注文明細を少ないSQLで取得する
2 地域・期間による注文検索と、注文IDによる注文明細検索に適切なインデックスがなく、テーブル全体を走査する クエリ条件と実行計画を確認し、orders(region, created_at)やorder_items(order_id)などのインデックスを追加する
3 売上合計、日別売上、商品別売上をPythonで計算するため、多数の行をDBからアプリケーションへ転送している SUM、COUNT、GROUP BYなどを使い、集計をSQL側で行う
4 売上合計、注文数、上位商品、日別売上の各計算が、同じ条件の注文データを個別に取得している クエリを統合するか、1回取得した中間結果をリクエスト内で共有して重複処理をなくす
5 同じ期間・地域の分析結果でも、リクエストのたびに同じ集計を実行する start、end、regionをキーに結果を安全に再利用する
6 更新などで再利用できる結果がないとき、同じキーへ並列アクセスがあると全リクエストが同じ集計を開始する(cache stampede) キー単位のsingle-flightを導入し、最初のリクエストだけが計算し、ほかのリクエストはその結果を待つ
7 注文追加後も古い分析結果がキャッシュに残る。一方、キャッシュ全削除では無関係な地域の高速化効果も失われる 新規注文の地域と日付を含むキャッシュキーだけを無効化し、無関係な地域・期間のキャッシュは保持する
8 分析の計算中に注文が追加されると、無効化後に古い計算結果が保存され直す可能性がある 更新世代の確認、再検証、または適切な同期により古い結果の復活を防ぐ

改善の流れは、前半のDBアクセス最適化と、後半の結果再利用および並列アクセス制御に分かれます。前半で単発リクエストを高速化し、後半で繰り返しアクセス、同時アクセス、更新後の整合性を改善します。

実際の修正回数はエージェントの判断によって変わります。デモの目的は一定回数修正させることではなく、独立した評価条件をすべて検証してGoalを完了させることです。

評価器はすべてリポジトリ内で公開します。エージェントはベンチマークとテストを自由に読み、実行できます。強いエージェントが一度の実装で全条件を満たすことも、正しい結果として扱います。

benchmark.pyが測定する内容

benchmark.pyは実装方式を判定せず、外部から観測できるレイテンシと集計結果だけを出力します。キャッシュや並列制御に固有のヘッダーは要求しません。合格条件は後述のGoalプロンプトで定義し、測定値が目標を超えていても終了コードは0です。

デフォルトでは次の順序で測定します。

  1. 条件を変えた逐次リクエスト
    • 地域・期間が異なる条件を順番に取得する
    • 単発処理のp50とp95を測る
  2. 同一条件の反復リクエスト
    • 同じ条件を事前に1回取得した後、5回続けて取得する
    • 同じ分析を繰り返した場合のp50とp95を測る
  3. 更新直後の集中アクセス
    • JPへ71,003円の注文を追加し、直後に同じ分析条件へ10リクエストを同時送信する
    • p50、p95、全レスポンスの一致、注文数と売上の増分を確認する
  4. 複数キーへの並列リクエスト
    • 地域・期間が異なる4条件を事前に取得する
    • 4条件を使って合計10リクエストを同時送信し、p50とp95を測る
  5. 注文登録後の集計結果
    • JPとUSの分析結果を取得後、JPへ83,117円の注文を追加する
    • JPの注文数と売上が正しく増え、USの結果が変化しないことを確認する
    • 更新後のJPとUSを再取得する時間も測る

リクエスト回数と並列数は、--sequential-requests、--repeat-requests、--concurrencyで変更できます。p95はnearest-rank方式で計算します。

評価方針

ベンチマークが評価するのは次の結果だけです。

  • 異なる条件でも単発処理が十分に速い
  • 同じ条件を繰り返すと高速に応答できる
  • 更新直後にアクセスが集中しても、正しい同一結果を規定時間内に返せる
  • 複数条件への並列アクセスも規定時間内に返せる
  • 注文登録後に、影響する集計だけが変化する
  • 注文登録後も、影響しない条件は高速に応答できる

これらをどう実現するかはエージェントに指定しません。想定解は前述のDBアクセス最適化、結果の再利用、同一処理の合流、影響範囲を限定した無効化ですが、同じ外部挙動を満たす別の実装も合格です。

初期実装では、単発処理が約800 ms、更新直後の集中アクセスと複数条件の並列アクセスが1秒を超えることがあります。値は実行環境によって変動します。測定を比較するときは、データベースを再生成してサーバーも再起動してください。

pytestが検証する内容

uv run pytestはレスポンス形式、集計値、注文登録後の反映、入力検証に加えて、分析処理と注文登録が競合した場合の整合性を検証します。

競合テストではタイミング依存のsleepを使わず、次の順序を同期イベントで確実に作ります。

  1. GETが古いデータを使って分析結果を計算する
  2. 計算後、結果を返す直前でGETを停止する
  3. POSTで対象期間・地域へ注文を追加する
  4. GETの停止を解除する
  5. 次のGETで追加した注文が反映されることを確認する

このテストは特定の実装方式を要求しません。更新世代の管理、保存前の再検証、ロック設計の変更など、外部から見た整合性を満たす方法であれば合格です。初期実装は結果を再利用しないため合格しますが、単純なキャッシュと無効化だけを追加した実装では、処理中の古い結果が復活して不合格になる可能性があります。

デモの準備

uv sync
uv run python seed.py
uv run pytest
uv run uvicorn app:app --workers 1

別のターミナルで初期値を確認します。

uv run python benchmark.py

ベンチマークは更新後の整合性を検証するためにJPの注文を2件追加します。デモ開始前には、必ずデータベースを初期化してください。

uv run python seed.py

比較条件を一定にするため、Uvicornは1 workerで実行します。worker数の増加や外部サービスの導入は対象外です。

Goal mode用プロンプト

売上分析APIを最適化してください。

完了条件:
- `uv run pytest`がすべて成功すること
- 分析処理中に注文が登録された場合でも、その後の分析結果に新しい注文が反映され、古い結果が残らないこと
- `uv run python benchmark.py`の測定結果が次をすべて満たすこと
  - 条件を変えた逐次リクエストのp95が100 ms未満
  - 同一条件の反復リクエストのp95が10 ms未満
  - 更新直後の集中アクセスのp95が120 ms未満
  - 更新直後の集中アクセスですべてのレスポンスが同一
  - 更新直後の集中アクセスで注文数の増分が1
  - 更新直後の集中アクセスで売上の増分が追加金額と一致
  - 複数キーへの並列リクエストのp95が120 ms未満
  - 注文追加後の注文数の増分が1
  - 注文追加後の売上の増分が、追加した注文の金額と一致
  - 注文追加後、更新対象の再取得が100 ms未満
  - 注文追加後、他地域の再取得が10 ms未満
  - 無関係な地域の分析結果が変化しない

制約:
- `benchmark.py`とテストを変更しないこと
- 公開HTTP APIとレスポンス形式を変更しないこと
- データセットを削減しないこと
- 外部サービスを導入しないこと
- Uvicornは1 workerのままにすること

最適化方法はプロンプトで指定しません。Goalに達したかどうかは、テスト結果とbenchmark.pyが出力する観測値を完了条件と照合して判断します。

デモ時の注意

本ドキュメントはは想定課題と改善案を含む発表者用ノートです。.gitignoreには登録されていますが、同じ作業ディレクトリに置けばlsやfindで発見できます。エージェントへ作業ディレクトリを渡す前に、リポジトリ外へ退避してください。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment