django-recommender-search-backend-patterns

実験的な Django レコメンダーと検索バックエンドのベストプラクティス

複数の結果を返すレコメンデーション（Personalize／Databricks／マイクロサービスへのファンアウト）と、OpenSearch を利用した検索／フィードを提供する Django バックエンドの実装パターンです。8 カテゴリーにわたる 48 のルールを、実行ライフサイクルへの影響度順に並べています。前のカテゴリーは、その後のすべてに連鎖的に影響します。

これは react-fetch-cache-patterns スキルのバックエンド版です。React はクライアント側のウォーターフォールとキャッシュを扱い、このスキルはサーバー側のファンアウト、下流サービスの保護、OpenSearch のクエリ設計、ML ブレンドのオーケストレーションを扱います。

適用する場面

• AWS Personalize、Databricks Model Serving、社内マイクロサービスなど、ML 推論の下流サービスにファンアウトする Django ビューを構築またはレビューするとき
• OpenSearch のクエリーエンドポイント（検索結果、無限スクロールのフィード、ファセット検索）を設計するとき
• 複数のランカー出力をブレンドするレコメンデーションエンドポイントを実装するとき
• 「下流サービスの障害時に Django バックエンドが遅い」または「Personalize のクォータを使い切った」という問題を調査するとき
• 外部呼び出しにキャッシュ、リトライ、サーキットブレーカー、レート制限を追加するとき
• 同期ビューと非同期ビューのどちらを使うか選択するとき、または uvicorn と gunicorn を設定するとき
• ページネーション付きフィード、部分的な結果、縮退時のパス向けに DRF のレスポンス形式を設計するとき

優先度別のルールカテゴリー

#	カテゴリー	影響度	プレフィックス	ルール数
1	ファンアウトのオーケストレーション	CRITICAL	orch-	8
2	外部サービスの保護	CRITICAL	protect-	7
3	OpenSearch クエリーパターン	CRITICAL	search-	8
4	結果のブレンドとパーソナライズ	HIGH	blend-	5
5	キャッシュ戦略	HIGH	cache-	5
6	レジリエンスと部分的な結果	HIGH	resilience-	5
7	非同期処理と並行性	MEDIUM-HIGH	async-	5
8	API レスポンスの設計	MEDIUM	api-	5

クイックリファレンス

1. ファンアウトのオーケストレーション（CRITICAL）

• orch-parallel-fanout-asyncio-gather — 独立した下流呼び出しには asyncio.gather を使い、逐次的に await しないでください
• orch-return-exceptions-on-fanout — 1 つの呼び出しの失敗が gather 全体に影響しないよう、return_exceptions=True を指定してください
• orch-propagate-request-deadline — リクエスト全体のレイテンシを制限するため、すべての下流呼び出しにデッドラインを渡してください
• orch-reuse-async-clients — モジュールスコープで下流サービスごとに 1 つの httpx.AsyncClient を使い、リクエストごとに作成しないでください
• orch-bounded-fanout-concurrency — asyncio.Semaphore でリクエストごとのファンアウト数を制限し、コネクションプールを保護してください
• orch-no-blocking-in-async-view — 非同期ビューで同期 ORM／IO を使ってイベントループをブロックしないでください
• orch-avoid-await-in-loop — for item in items: await ... は逐次実行です。内包表記と asyncio.gather を使ってください
• orch-batch-with-bulk-endpoint — N 個の並列呼び出しではなくバルクエンドポイントを使い、バッチ処理には DataLoader パターンを使ってください

2. 外部サービスの保護（重大）

• protect-per-downstream-timeout-budget — 各下流サービスの p99 に合わせて、サービスごとに異なるタイムアウトを設定します
• protect-circuit-breaker-per-downstream — 下流サービスごとにサーキットブレーカーを設け、障害を分離します
• protect-jittered-retry-backoff — 全ジッター付き指数バックオフを使用し、再試行時の集中アクセスを防ぎます
• protect-no-retry-on-4xx — 4xx および冪等でないリクエストの失敗では再試行をスキップし、接続エラーと読み取りエラーを区別します
• protect-bulkhead-connection-pool — 下流サービスごとに接続プールを設け、遅いサービスによってほかのサービスが圧迫されないようにします
• protect-client-side-rate-limit — 各下流サービスへのリクエストにトークンバケット方式を適用し、クォータを超えないようにします
• protect-honor-retry-after-header — 429／503 の Retry-After（秒数または HTTP 日付）を解析します

3. OpenSearch のクエリパターン（重大）

• search-use-search-after-not-from — ページネーションを行うすべてのエンドポイントで、from/size の代わりに search_after カーソルを使用します
• search-filter-source-fields — 表示するフィールドに _source を限定し、ソート可能なフィールドには docvalue_fields を使用します
• search-bool-filter-vs-must — スコアリングしない句はキャッシュ可能な filter に、スコアリングする句は must に指定します
• search-function-score-for-blending — function_score を使用して、パーソナライズのシグナルをエンジン内でブレンドします
• search-stable-tiebreaker-sort — 安定したカーソルを実現するため、ソートの最後には必ず _id（または一意な数値フィールド）を指定します
• search-alias-for-blue-green-reindex — エイリアス経由でクエリを実行し、インデックス名を直接指定しないでください
• search-enable-request-cache — ヒットを返すクエリでは request_cache=true を指定し、リクエストボディを正規化します
• search-shard-aware-routing — ルーティングキーを使用して、クエリごとのシャードへのファンアウトを制限します

4. 結果のブレンドとパーソナライズ（高）

• blend-normalize-scores-across-sources — Personalize／Databricks／OpenSearch の結果をブレンドする前に、Min-Max または RRF でスコアを正規化します
• blend-mmr-for-diversity — 上位 K 件の結果が同質化しないよう、最大限界関連性（MMR）を使用します
• blend-dedup-across-sources — 正規アイテム ID で重複を排除し、複数のソースで裏付けられた結果にはボーナスを加えます
• blend-cold-start-fallback — 新規ユーザーには人気順／編集者選定のフォールバックを用意し、段階的にパーソナライズします
• blend-anonymous-vs-personalized-paths — 匿名ユーザーのトラフィックにはセグメントキー単位の低コストなキャッシュを使用し、ログインユーザーにのみ ML を適用します

5. キャッシュ戦略（高）

• cache-redis-with-stampede-protection — SETNX ロック、ジッター付き TTL、確率的な早期リフレッシュを組み合わせます
• cache-version-on-model-deploy — モデルのバージョンをキャッシュキーに組み込み、再学習時のフラッシュを不要にします
• cache-segment-keyed-isolation — コンテキスト間の情報漏えいを防ぐため、認証／ロール／ロケール／セグメントをキーに含めます
• cache-two-tier-process-and-redis — 最も頻繁に使われるキーには、Redis の前段にプロセス内 LRU キャッシュを配置します
• cache-negative-results — 存在しないデータや空の結果を、短い TTL でキャッシュします

6. レジリエンスと部分的な結果（高）

• resilience-partial-response-envelope — レスポンスに partial: true、sources_used、failed_sources を含めます
• resilience-serve-stale-from-redis — 2 種類の TTL（新鮮なデータ＋古いデータ）を設定し、オリジンに障害が発生した場合は古いデータを返します
• resilience-default-ranking-fallback — すべての ML ソースが停止した場合に、事前計算済みのデフォルトランキングを使用します
• resilience-per-source-observability — すべての下流呼び出しに、構造化されたソース／結果のメタデータを付与します
• resilience-degrade-search-gracefully — OpenSearch の障害時に、ティア 1 → ティア 2 → ティア 3 の順でフォールバックします

7. 非同期処理と並行性（中〜高）

• async-sync-to-async-orm — Django 4.1 以降の非同期 ORM（aget、afilter）を使用するか、thread_sensitive=True を指定して sync_to_async を使用します
• async-worker-model-uvicorn-vs-gunicorn — 真の非同期並行性を実現するため、ASGI（uvicorn または gunicorn+UvicornWorker）を実行します
• async-fire-and-forget-with-create-task — 分析／監査には create_task を使用し、エラーハンドラーを追加してタスクへの参照を保持します
• async-context-vars-for-request-scope — リクエストごとの状態には threading.local ではなく contextvars.ContextVar を使用します
• async-cancel-on-client-disconnect — await request.is_disconnected() を確認し、キャンセルを伝播させます

8. API レスポンスの設計（中）

• api-cursor-pagination-in-drf — ページ番号方式ではなくカーソルページネーションを使用し、不透明な base64 カーソルを使います
• api-serializer-perf-select-related — select_related／prefetch_related／only を使用して N+1 を解消します
• api-etag-and-cache-control-headers — CDN／クライアントでの再利用に ETag + Cache-Control + Vary を使用します
• api-compression-and-payload-shaping — gzip／brotli、スパースフィールドセットを使用します。内部 API には msgpack を使用します
• api-throttle-per-user-and-endpoint — ユーザー／匿名ユーザーごと、および高負荷なエンドポイントごとに DRF スロットルクラスを設定します

使用方法

1. カテゴリーの定義と影響の根拠については、references/_sections.md を開いてください
2. 誤ったコードと正しいコードの例については、個別のルールファイルを読んでください（各ファイルは Python コードを含み、約 150～300 行です）
3. すぐに使えるスキャフォールドについては、スキャフォールドテンプレート を参照してください
4. AGENTS.md のナビゲーションドキュメント（自動生成）には、閲覧用の目次があります

スキャフォールドテンプレート

assets/templates/ に、用途に合わせてすぐに調整できる Python テンプレートが 5 つあります。

テンプレート	用途
fanout_recommender_service.py.template	Personalize／Databricks／マイクロサービスへの非同期ファンアウトクライアント。下流サービスごとのサーキットブレーカー、上限付きタイムアウト、部分的な結果の返却に対応します
opensearch_search_view.py.template	DRF ビュー + OpenSearch の search_after カーソル + function_score によるブレンド + _source フィルタリング
result_blender.py.template	スコアの正規化 + MMR による多様性確保 + 正規 ID の重複排除 + コールドスタート時のフォールバック
redis_cache_with_stampede.py.template	SETNX ロックとジッター付き TTL を備えた、スタンピード対策済みキャッシュ関数デコレーター
degraded_response.py.template	ソースごとのステータスフラグとティアベースのフォールバックを備えた部分的な結果のエンベロープ

参照ファイル

ファイル	説明
references/_sections.md	カテゴリーの定義、順序、影響の根拠、ティアの定義
assets/templates/_template.md	新しいルールを作成するためのテンプレート
metadata.json	バージョン、参照情報、概要

関連スキル

• react-fetch-cache-patterns — React のデータ取得とキャッシュ（Suspense、クエリライブラリ、プリフェッチ）を扱うクライアント側の関連スキル
• io-bound-data-processing — バッチおよびパイプラインのワークロード向け Python 非同期パターン
• inngest-nextjs-patterns — サーバー側ステップ関数のワークフローパターン