meida_backend

49 Commits 1 Branch 0 Tags

3 Commits

Include renames

Author	SHA1	Message	Date
xsl	a044ea2e47	feat(retrieval): TTL+LRU result cache with generation-based invalidation TtlCache（全输入进键/惰性过期/容量逐出/命中零 DB）+ search 接线（空结果不缓存，保住 gap 埋点）+ invalidate_cache 真实现（T-P2-10）。实现： - packages/retrieval/cache.py（新建）：CacheKey 全输入进键（query/body_shape/ occasion/entity_types 排序归一/rule_boost 排序序列化哈希/top_k/失效代数）； TtlCache 惰性过期 + OrderedDict LRU（超限 popitem 最旧）+ hits/misses/ evictions 计数与 stats()；clock 可注入（单测免 sleep，默认 monotonic）； asyncio 单循环不加锁的前提写在模块 docstring；正确性红线（只缓存不可变值、命中零 DB）同处。纯逻辑，不 import 任何项目内模块（值类型由 service 以 PEP 695 泛型注入，避免循环依赖）。 - packages/retrieval/service.py：__init__ 加 keyword-only cache=None（默认禁用，行为与现状一致，既有调用点不受影响）；from_settings 按 Settings 装配进程级共享缓存（retrieval_cache_enabled=False → None；TTL/容量变化时重建）；search() 在 embed 之前查缓存——命中直接返回（零 DB、零 embed），写入与命中都做防御性拷贝（results 是 list，调用方拿不到缓存内引用），仅有结果时写缓存（空结果不缓存，record_gap 每次都跑）；invalidate_cache() 签名不变：自增 repo.INVALIDATION_VERSION（代数失效，旧代键永不命中，与 T12 的契约保持）+ 清空共享实例（仅为立即回收内存，失效正确性只依赖代数）。repo.py 未做任何改动。测试： - 单测 tests/unit/test_retrieval_cache.py（21 例，fake repo/embedding + 注入时钟，不连库）：同参二连查零 DB 且结果相等、键分量矩阵（query/ occasion/body_shape/entity_types/rule_boost/top_k 任一变化 → miss）、 TTL 过期边界（60.0 过期/59.9 命中）、LRU 逐出与命中率/计数、空结果不缓存且 gap 埋点每次触发、invalidate_cache() 代数失效（含自增语义保留断言）、cache=None 与现状一致、from_settings 装配开关与共享实例、 rule_boost 哈希确定性。全量单测 494 passed（基线 473 + 新增 21）。 - 集成 tests/integration/test_retrieval_cache.py（2 例，真实 PG + pgvector）：发布新实体 + invalidate_cache() 后同参检索立即可见（失效前缓存仍只吐旧实体，证明缓存在工作——T-P2-10 验收语义）；不失效、TTL=1s 到期（asyncio.sleep 1.1s）后新实体自然可见（双路径验收）。集成全量 40 passed。偏差说明：无（invalidate_cache() 在代数失效之外顺带清空共享缓存实例，失效正确性只依赖代数，清空仅为立即释放内存）。	2026-08-14 21:16:51 +08:00
xsl	9c1802130d	chore(prep): shared groundwork for batch-3 (admin/golden/cache) 第三批（T12 后台/T13 黄金集/T14 检索缓存）协调提交： - kb：KbAssetService（登记/审核，tryon_ready 只能随 approved 打开）+ Asset 模型与 repo - retrieval：list_gaps 缺口看板查询 + invalidate_cache() 钩子（T14 背后实现真缓存） - 配置：ADMIN_TOKEN（空=后台 404）+ 检索缓存三参数 - pytest golden marker（默认跳过，CI 强制跑）+ Makefile golden + CI 防线 5c - 测试隔离修复：test_auth_sms 加 autouse 清 sms:* 键夹具（频控计数跨运行累积会毒化后续运行——随机 IP 空间仅 254 且部分用例固定 device_id）	2026-08-14 20:57:52 +08:00
xsl	aa1287d83d	feat(retrieval): hybrid search over pgvector with hard filters and gap tracking DeterministicEmbedder（可换 BGE-M3 的接口位）+ kb_chunk 双索引写入 + 硬过滤→向量→关键词→RRF 重排管线 + kb_gap 缺口埋点（T-P2-03/04/06，TD-08）。实现： - embedding.py：EmbeddingProvider Protocol + DeterministicEmbedder （sha256 种子→归一化 1024 维假向量，同文本同向量/异文本近似正交） + build_embedding_provider 工厂（未知模型名抛 CONFIG_ERROR）。 - repo.py：upsert_chunks（整实体先删后插，逐行带 embedding_model/version，可重跑判据 T-P2-03）；hybrid_search（§8.3 CTE：硬过滤 published/ entity_types/occasion/avoid_body_shapes → <=> 余弦 topN → ts_rank topN → RRF）；record_gap（咨询锁串行化同 query+filter_ctx 的 hit_count 递增）。 - rerank.py：RRF/权重/新鲜度纯数学（独立于 SQL 以便单测逐项断言）。 - service.py：RetrievalService.search 编排 embed→检索→（空结果）gap 埋点， SearchOutcome.degraded 标记降级。测试：单测 +30（test_embedding 确定性/维度/归一化/工厂拒绝、test_rerank 公式逐项断言、test_retrieval_service 编排打桩）；集成 +5 （test_hybrid_retrieval：禁忌实体同文最近向量仍零出现、draft 零出现、关键词路径、换模型整组替换、kb_gap hit_count=2、partial 索引 EXPLAIN 验证）。全绿：ruff / mypy(retrieval+shared+domain) / lint-imports / 268 单测 / 21 集成。偏差说明： 1) 新增 rerank.py（任务文档只点名 embedding/repo/service，但重排数学必须不连库可单测，独立模块是最低成本实现，仍属 packages/retrieval/**）。 2) upsert_chunks 的 upsert 粒度是实体（先删后插）：kb_chunk 无业务自然键，行级 ON CONFLICT 不可行；换模型名=新版本整组替换，不留旧版本残向量。 3) 禁忌过滤用 COALESCE(attrs->avoid_body_shapes, '[]')兜底：jsonb NULL 的 ? 运算结果是 NULL，直接 NOT 会把未声明禁忌的好实体一并排除。 4) 关键词路过滤用 tsv @@ tsquery 而非 ts_rank>0：ts_rank 对不匹配文本返回 ~1e-20 正 epsilon，阈值过滤会把无关 chunk 全放进关键词路。 5) RRF 分量按 1/(k+1) 归一到 (0,1]，使 0.45/0.2/0.25/0.1 权重量纲可比（原始倒数 0.45×1/61 与规则项 0.25×1 完全不可比）。	2026-08-14 20:12:27 +08:00

Author

SHA1

Message

Date

xsl

a044ea2e47

feat(retrieval): TTL+LRU result cache with generation-based invalidation

TtlCache（全输入进键/惰性过期/容量逐出/命中零 DB）+ search 接线
（空结果不缓存，保住 gap 埋点）+ invalidate_cache 真实现（T-P2-10）。

实现：
- packages/retrieval/cache.py（新建）：CacheKey 全输入进键（query/body_shape/
  occasion/entity_types 排序归一/rule_boost 排序序列化哈希/top_k/失效代数）；
  TtlCache 惰性过期 + OrderedDict LRU（超限 popitem 最旧）+ hits/misses/
  evictions 计数与 stats()；clock 可注入（单测免 sleep，默认 monotonic）；
  asyncio 单循环不加锁的前提写在模块 docstring；正确性红线（只缓存不可变
  值、命中零 DB）同处。纯逻辑，不 import 任何项目内模块（值类型由 service
  以 PEP 695 泛型注入，避免循环依赖）。
- packages/retrieval/service.py：__init__ 加 keyword-only cache=None（默认
  禁用，行为与现状一致，既有调用点不受影响）；from_settings 按 Settings
  装配进程级共享缓存（retrieval_cache_enabled=False → None；TTL/容量变化
  时重建）；search() 在 embed 之前查缓存——命中直接返回（零 DB、零 embed），
  写入与命中都做防御性拷贝（results 是 list，调用方拿不到缓存内引用），
  仅有结果时写缓存（空结果不缓存，record_gap 每次都跑）；invalidate_cache()
  签名不变：自增 repo.INVALIDATION_VERSION（代数失效，旧代键永不命中，
  与 T12 的契约保持）+ 清空共享实例（仅为立即回收内存，失效正确性只
  依赖代数）。repo.py 未做任何改动。

测试：
- 单测 tests/unit/test_retrieval_cache.py（21 例，fake repo/embedding +
  注入时钟，不连库）：同参二连查零 DB 且结果相等、键分量矩阵（query/
  occasion/body_shape/entity_types/rule_boost/top_k 任一变化 → miss）、
  TTL 过期边界（60.0 过期/59.9 命中）、LRU 逐出与命中率/计数、空结果
  不缓存且 gap 埋点每次触发、invalidate_cache() 代数失效（含自增语义
  保留断言）、cache=None 与现状一致、from_settings 装配开关与共享实例、
  rule_boost 哈希确定性。全量单测 494 passed（基线 473 + 新增 21）。
- 集成 tests/integration/test_retrieval_cache.py（2 例，真实 PG + pgvector）：
  发布新实体 + invalidate_cache() 后同参检索立即可见（失效前缓存仍只吐
  旧实体，证明缓存在工作——T-P2-10 验收语义）；不失效、TTL=1s 到期
  （asyncio.sleep 1.1s）后新实体自然可见（双路径验收）。集成全量 40 passed。

偏差说明：无（invalidate_cache() 在代数失效之外顺带清空共享缓存实例，
失效正确性只依赖代数，清空仅为立即释放内存）。

2026-08-14 21:16:51 +08:00

xsl

9c1802130d

chore(prep): shared groundwork for batch-3 (admin/golden/cache)

第三批（T12 后台/T13 黄金集/T14 检索缓存）协调提交：
- kb：KbAssetService（登记/审核，tryon_ready 只能随 approved 打开）+ Asset 模型与 repo
- retrieval：list_gaps 缺口看板查询 + invalidate_cache() 钩子（T14 背后实现真缓存）
- 配置：ADMIN_TOKEN（空=后台 404）+ 检索缓存三参数
- pytest golden marker（默认跳过，CI 强制跑）+ Makefile golden + CI 防线 5c
- 测试隔离修复：test_auth_sms 加 autouse 清 sms:* 键夹具（频控计数跨运行
  累积会毒化后续运行——随机 IP 空间仅 254 且部分用例固定 device_id）

2026-08-14 20:57:52 +08:00

xsl

aa1287d83d

feat(retrieval): hybrid search over pgvector with hard filters and gap tracking

DeterministicEmbedder（可换 BGE-M3 的接口位）+ kb_chunk 双索引写入
+ 硬过滤→向量→关键词→RRF 重排管线 + kb_gap 缺口埋点（T-P2-03/04/06，TD-08）。

实现：
- embedding.py：EmbeddingProvider Protocol + DeterministicEmbedder
  （sha256 种子→归一化 1024 维假向量，同文本同向量/异文本近似正交）
  + build_embedding_provider 工厂（未知模型名抛 CONFIG_ERROR）。
- repo.py：upsert_chunks（整实体先删后插，逐行带 embedding_model/version，
  可重跑判据 T-P2-03）；hybrid_search（§8.3 CTE：硬过滤 published/
  entity_types/occasion/avoid_body_shapes → <=> 余弦 topN → ts_rank topN
  → RRF）；record_gap（咨询锁串行化同 query+filter_ctx 的 hit_count 递增）。
- rerank.py：RRF/权重/新鲜度纯数学（独立于 SQL 以便单测逐项断言）。
- service.py：RetrievalService.search 编排 embed→检索→（空结果）gap 埋点，
  SearchOutcome.degraded 标记降级。

测试：单测 +30（test_embedding 确定性/维度/归一化/工厂拒绝、test_rerank
公式逐项断言、test_retrieval_service 编排打桩）；集成 +5
（test_hybrid_retrieval：禁忌实体同文最近向量仍零出现、draft 零出现、
关键词路径、换模型整组替换、kb_gap hit_count=2、partial 索引 EXPLAIN 验证）。
全绿：ruff / mypy(retrieval+shared+domain) / lint-imports / 268 单测 /
21 集成。

偏差说明：
1) 新增 rerank.py（任务文档只点名 embedding/repo/service，但重排数学必须
   不连库可单测，独立模块是最低成本实现，仍属 packages/retrieval/**）。
2) upsert_chunks 的 upsert 粒度是实体（先删后插）：kb_chunk 无业务自然键，
   行级 ON CONFLICT 不可行；换模型名=新版本整组替换，不留旧版本残向量。
3) 禁忌过滤用 COALESCE(attrs->avoid_body_shapes, '[]')兜底：jsonb NULL
   的 ? 运算结果是 NULL，直接 NOT 会把未声明禁忌的好实体一并排除。
4) 关键词路过滤用 tsv @@ tsquery 而非 ts_rank>0：ts_rank 对不匹配文本返回
   ~1e-20 正 epsilon，阈值过滤会把无关 chunk 全放进关键词路。
5) RRF 分量按 1/(k+1) 归一到 (0,1]，使 0.45/0.2/0.25/0.1 权重量纲可比
   （原始倒数 0.45×1/61 与规则项 0.25×1 完全不可比）。

2026-08-14 20:12:27 +08:00