django-recommender-search-backend-patterns

实验性 Django 推荐与搜索后端最佳实践

用于 Django 后端的实现模式，支持混合结果推荐（Personalize / Databricks / 微服务扇出）和由 OpenSearch 支持的搜索/信息流。共 8 个类别、48 条规则，按对执行生命周期的影响排序——靠前的类别会影响其后的所有环节。

这是 react-fetch-cache-patterns 技能的后端对应项。React 负责客户端瀑布请求和缓存；本技能负责服务端扇出、下游保护、OpenSearch 查询设计和机器学习混合编排。

适用场景

• 构建或审查 Django 视图，向 AWS Personalize、Databricks Model Serving、内部微服务或任何机器学习推理下游发起扇出请求
• 设计 OpenSearch 查询端点（搜索结果、无限信息流、分面搜索）
• 实现混合多个排序器输出的推荐端点
• 调查“下游服务降级时 Django 后端变慢”或“Personalize 配额耗尽”等问题
• 为出站调用添加缓存、重试、熔断器或速率限制
• 在同步和异步 Django 视图之间进行选择，配置 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；切勿顺序等待
• orch-return-exceptions-on-fanout — 设置 return_exceptions=True，避免一次失败导致整个 gather 失败
• orch-propagate-request-deadline — 将截止时间传递给每个下游调用，以限制整个请求的延迟
• orch-reuse-async-clients — 在模块作用域为每个下游服务创建一个 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 — 对任何分页端点使用 search_after 游标，而不是 from/size
• 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 — 使用最大边际相关性，避免 Top-K 结果过于单一
• blend-dedup-across-sources — 按规范化的条目 ID 去重；对跨来源相互印证的条目给予加分
• blend-cold-start-fallback — 为新用户提供热门/编辑推荐兜底；采用分层个性化
• blend-anonymous-vs-personalized-paths — 为匿名流量使用按细分群体键控的轻量缓存；仅对已登录用户使用机器学习

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 — 使用两个 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），或使用 sync_to_async 并设置 thread_sensitive=True
• 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 — 使用 contextvars.ContextVar 存储每个请求的状态；不要使用 threading.local
• 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 — 使用 ETag、Cache-Control 和 Vary，以便 CDN/客户端复用
• api-compression-and-payload-shaping — 使用 gzip/brotli、稀疏字段集；内部 API 使用 msgpack
• api-throttle-per-user-and-endpoint — 按用户/匿名用户以及每个高开销端点配置 DRF 节流类

使用方法

1. 打开 references/_sections.md，了解类别定义和影响原因
2. 阅读各规则文件，查看错误与正确的代码示例（每个文件约 150-300 行 Python 代码）
3. 如需可直接使用的脚手架，请参阅 脚手架模板
4. AGENTS.md 导航文档（自动生成）提供了用于浏览的目录

脚手架模板

assets/templates/ 下有五个可直接调整使用的 Python 模板：

模板	用途
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 — 服务端步骤函数的工作流模式