merge: T8 pgvector 混合检索与缺口埋点（T-P2-03/04/06，TD-08）
This commit is contained in:
@@ -0,0 +1,99 @@
|
||||
"""DeterministicEmbedder 与工厂：纯数学，不连库不联网（T-P2-03 接口位）."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import math
|
||||
|
||||
import pytest
|
||||
|
||||
from packages.retrieval.embedding import (
|
||||
DETERMINISTIC_MODEL_NAME,
|
||||
DeterministicEmbedder,
|
||||
build_embedding_provider,
|
||||
)
|
||||
from packages.shared.config import get_settings
|
||||
from packages.shared.errors import AppError, ErrorCode
|
||||
|
||||
|
||||
def _dot(a: list[float], b: list[float]) -> float:
|
||||
return sum(x * y for x, y in zip(a, b, strict=True))
|
||||
|
||||
|
||||
async def test_same_text_embeds_to_same_vector() -> None:
|
||||
embedder = DeterministicEmbedder(dimensions=1024)
|
||||
first, second = await embedder.embed(["白衬衫怎么搭配", "白衬衫怎么搭配"])
|
||||
assert first == second
|
||||
|
||||
|
||||
async def test_dimensions_match_declaration() -> None:
|
||||
vec = (await DeterministicEmbedder(dimensions=1024).embed(["hello"]))[0]
|
||||
assert len(vec) == 1024
|
||||
small = (await DeterministicEmbedder(dimensions=8).embed(["hello"]))[0]
|
||||
assert len(small) == 8
|
||||
|
||||
|
||||
async def test_vectors_are_l2_normalized() -> None:
|
||||
for text in ("hello", "中文知识片段", ""):
|
||||
vec = (await DeterministicEmbedder(dimensions=1024).embed([text]))[0]
|
||||
assert math.isclose(_dot(vec, vec), 1.0, rel_tol=1e-6, abs_tol=1e-9)
|
||||
|
||||
|
||||
async def test_different_texts_are_near_orthogonal() -> None:
|
||||
"""不同文本近似正交（|dot| ≪ 1）：向量召回管线在无真模型时仍可测."""
|
||||
|
||||
left, right = await DeterministicEmbedder(dimensions=1024).embed(
|
||||
["interview outfit advice", "winter skincare routine"]
|
||||
)
|
||||
assert left != right
|
||||
assert abs(_dot(left, right)) < 0.1
|
||||
|
||||
|
||||
async def test_batch_preserves_order_and_length() -> None:
|
||||
texts = ["alpha", "beta", "gamma"]
|
||||
vectors = await DeterministicEmbedder(dimensions=16).embed(texts)
|
||||
assert len(vectors) == len(texts)
|
||||
singles = [(await DeterministicEmbedder(dimensions=16).embed([t]))[0] for t in texts]
|
||||
assert vectors == singles
|
||||
|
||||
|
||||
def test_metadata_is_stable() -> None:
|
||||
embedder = DeterministicEmbedder(dimensions=8)
|
||||
assert embedder.model_name == DETERMINISTIC_MODEL_NAME
|
||||
assert embedder.version
|
||||
assert embedder.dimensions == 8
|
||||
|
||||
|
||||
def test_invalid_dimensions_rejected() -> None:
|
||||
with pytest.raises(ValueError, match="dimensions"):
|
||||
DeterministicEmbedder(dimensions=0)
|
||||
|
||||
|
||||
def test_factory_builds_deterministic_embedder(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
# 带 alias 的 Settings 字段按字段名构造会被静默忽略 —— 统一走
|
||||
# setenv + cache_clear（上批经验，见任务文档 §2）。
|
||||
monkeypatch.setenv("KB_EMBEDDING_MODEL", "deterministic-v1")
|
||||
monkeypatch.setenv("KB_VECTOR_DIMENSIONS", "1024")
|
||||
get_settings.cache_clear()
|
||||
try:
|
||||
settings = get_settings()
|
||||
provider = build_embedding_provider(settings)
|
||||
assert isinstance(provider, DeterministicEmbedder)
|
||||
assert provider.model_name == "deterministic-v1"
|
||||
assert provider.dimensions == 1024
|
||||
finally:
|
||||
monkeypatch.undo()
|
||||
get_settings.cache_clear()
|
||||
|
||||
|
||||
def test_factory_rejects_unknown_model(monkeypatch: pytest.MonkeyPatch) -> None:
|
||||
monkeypatch.setenv("KB_EMBEDDING_MODEL", "bge-m3-onnx")
|
||||
get_settings.cache_clear()
|
||||
try:
|
||||
settings = get_settings()
|
||||
assert settings.kb_embedding_model == "bge-m3-onnx"
|
||||
with pytest.raises(AppError) as excinfo:
|
||||
build_embedding_provider(settings)
|
||||
assert excinfo.value.code == ErrorCode.CONFIG_ERROR
|
||||
finally:
|
||||
monkeypatch.undo()
|
||||
get_settings.cache_clear()
|
||||
@@ -0,0 +1,158 @@
|
||||
"""RRF 融合 + 权重 + 新鲜度的数学正确性（T-P2-04 验收 3）：构造已知名次断言最终序."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import itertools
|
||||
from datetime import UTC, datetime, timedelta
|
||||
|
||||
import pytest
|
||||
|
||||
from packages.retrieval.rerank import (
|
||||
DEFAULT_RERANK_WEIGHTS,
|
||||
FRESHNESS_HALF_LIFE_DAYS,
|
||||
RRF_K,
|
||||
RecallRow,
|
||||
freshness_score,
|
||||
rerank,
|
||||
rrf_component,
|
||||
rrf_score,
|
||||
)
|
||||
|
||||
NOW = datetime(2026, 8, 14, 12, 0, 0, tzinfo=UTC)
|
||||
|
||||
|
||||
def _row(
|
||||
chunk_id: int,
|
||||
*,
|
||||
vec_rank: int | None = None,
|
||||
kw_rank: int | None = None,
|
||||
updated_at: datetime = NOW,
|
||||
entity_id: int = 1,
|
||||
) -> RecallRow:
|
||||
return RecallRow(
|
||||
chunk_id=chunk_id,
|
||||
entity_id=entity_id,
|
||||
chunk_type="text",
|
||||
text=f"chunk-{chunk_id}",
|
||||
updated_at=updated_at,
|
||||
vec_rank=vec_rank,
|
||||
kw_rank=kw_rank,
|
||||
)
|
||||
|
||||
|
||||
# --- 单路 RRF 分量 ------------------------------------------------------------
|
||||
def test_rrf_component_is_max_normalized() -> None:
|
||||
assert rrf_component(1) == pytest.approx(1.0) # (60+1)/(60+1)
|
||||
assert rrf_component(2) == pytest.approx(61 / 62)
|
||||
assert rrf_component(RRF_K + 2) == pytest.approx(0.5) # 61/122：名次再排后一半
|
||||
assert rrf_component(None) == 0.0
|
||||
assert rrf_component(0) == 0.0
|
||||
assert rrf_component(-3) == 0.0
|
||||
|
||||
|
||||
def test_rrf_component_monotonic_non_increasing() -> None:
|
||||
values = [rrf_component(r) for r in range(1, 20)]
|
||||
assert all(a >= b for a, b in itertools.pairwise(values))
|
||||
|
||||
|
||||
def test_rrf_score_is_sum_of_raw_reciprocals() -> None:
|
||||
assert rrf_score(1, 2) == pytest.approx(1 / 61 + 1 / 62)
|
||||
assert rrf_score(None, 1) == pytest.approx(1 / 61)
|
||||
assert rrf_score(1, None) == pytest.approx(1 / 61)
|
||||
assert rrf_score(None, None) == 0.0
|
||||
|
||||
|
||||
# --- 新鲜度 ------------------------------------------------------------------
|
||||
def test_freshness_half_life_decay() -> None:
|
||||
assert freshness_score(NOW, now=NOW) == pytest.approx(1.0)
|
||||
old = NOW - timedelta(days=FRESHNESS_HALF_LIFE_DAYS)
|
||||
assert freshness_score(old, now=NOW) == pytest.approx(0.5)
|
||||
older = NOW - timedelta(days=2 * FRESHNESS_HALF_LIFE_DAYS)
|
||||
assert freshness_score(older, now=NOW) == pytest.approx(0.25)
|
||||
# 时钟漂移产生未来时间戳 → 按 0 天处理，不放大分数
|
||||
future = NOW + timedelta(hours=1)
|
||||
assert freshness_score(future, now=NOW) == pytest.approx(1.0)
|
||||
|
||||
|
||||
# --- 加权公式 ----------------------------------------------------------------
|
||||
def test_final_score_follows_architecture_formula() -> None:
|
||||
"""final = 0.45×vec + 0.2×kw + 0.25×rule + 0.1×fresh，逐项核对."""
|
||||
|
||||
row = _row(1, vec_rank=1, kw_rank=3)
|
||||
boost = {1: 0.5}
|
||||
scored = rerank([row], rule_boost=boost, now=NOW)
|
||||
expected = 0.45 * 1.0 + 0.2 * (61 / 63) + 0.25 * 0.5 + 0.1 * 1.0
|
||||
assert scored[0].final_score == pytest.approx(expected)
|
||||
assert scored[0].vec_score == pytest.approx(1.0)
|
||||
assert scored[0].kw_score == pytest.approx(61 / 63)
|
||||
assert scored[0].rule_score == pytest.approx(0.5)
|
||||
assert scored[0].freshness_score == pytest.approx(1.0)
|
||||
|
||||
|
||||
def test_default_weights_match_architecture_section_8_3() -> None:
|
||||
assert DEFAULT_RERANK_WEIGHTS == {
|
||||
"vector": 0.45,
|
||||
"keyword": 0.2,
|
||||
"rule": 0.25,
|
||||
"freshness": 0.1,
|
||||
}
|
||||
|
||||
|
||||
def test_dual_recall_beats_single_recall() -> None:
|
||||
"""两路都命中的 chunk 应压过只有向量路命中、名次更高的 chunk."""
|
||||
|
||||
both = _row(1, vec_rank=5, kw_rank=2)
|
||||
vec_only = _row(2, vec_rank=1)
|
||||
scored = rerank([both, vec_only], now=NOW)
|
||||
by_id = {c.chunk_id: c for c in scored}
|
||||
assert by_id[1].final_score > by_id[2].final_score
|
||||
|
||||
|
||||
def test_rule_boost_lifts_lower_recall_chunk() -> None:
|
||||
"""规则权重 0.25×boost 可以把召回名次落后的 chunk 抬到最前（自建知识库的意义）."""
|
||||
|
||||
rank5 = _row(1, vec_rank=5)
|
||||
rank1 = _row(2, vec_rank=1)
|
||||
scored = rerank([rank5, rank1], rule_boost={1: 1.0}, now=NOW)
|
||||
assert scored[0].chunk_id == 1
|
||||
assert scored[0].rule_score == pytest.approx(1.0)
|
||||
|
||||
|
||||
def test_keyword_only_chunk_gets_zero_vector_score() -> None:
|
||||
scored = rerank([_row(7, kw_rank=1)], now=NOW)
|
||||
assert scored[0].vec_score == 0.0
|
||||
assert scored[0].kw_score == pytest.approx(1.0)
|
||||
|
||||
|
||||
def test_freshness_breaks_ties_toward_newer_chunk() -> None:
|
||||
"""名次相同（现实中少见，但公式上可能）时，更新鲜者胜."""
|
||||
|
||||
fresh = _row(1, vec_rank=2, updated_at=NOW)
|
||||
stale = _row(2, vec_rank=2, updated_at=NOW - timedelta(days=90))
|
||||
scored = rerank([fresh, stale], now=NOW)
|
||||
assert scored[0].chunk_id == 1
|
||||
delta = scored[0].final_score - scored[1].final_score
|
||||
assert delta == pytest.approx(0.1 * (1.0 - 0.5**3))
|
||||
|
||||
|
||||
def test_zero_weight_dimension_ignores_that_signal() -> None:
|
||||
old = _row(1, vec_rank=1, updated_at=NOW - timedelta(days=365))
|
||||
new = _row(2, vec_rank=2, updated_at=NOW)
|
||||
scored = rerank([old, new], weights={"vector": 1.0}, now=NOW)
|
||||
assert scored[0].chunk_id == 1 # 新鲜度权重为 0，旧的反而名次靠前
|
||||
|
||||
|
||||
def test_stable_ordering_and_top_k_truncation() -> None:
|
||||
rows = [_row(i, vec_rank=i) for i in (30, 10, 20, 40)]
|
||||
scored = rerank(rows, now=NOW, top_k=2)
|
||||
assert [c.chunk_id for c in scored] == [10, 20]
|
||||
|
||||
|
||||
def test_equal_final_scores_break_tie_by_chunk_id() -> None:
|
||||
rows = [_row(90, kw_rank=1), _row(10, kw_rank=1)]
|
||||
scored = rerank(rows, now=NOW)
|
||||
assert [c.chunk_id for c in scored] == [10, 90]
|
||||
|
||||
|
||||
def test_empty_input_returns_empty() -> None:
|
||||
assert rerank([], now=NOW) == []
|
||||
@@ -0,0 +1,179 @@
|
||||
"""RetrievalService 编排逻辑：repo 层打桩，不连库（编排正确性与 DB 无关）."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
import pytest
|
||||
|
||||
from packages.retrieval import repo
|
||||
from packages.retrieval import service as service_mod
|
||||
from packages.retrieval.rerank import ScoredChunk
|
||||
from packages.retrieval.service import RetrievalService, UserContext
|
||||
|
||||
|
||||
class FakeEmbedder:
|
||||
"""满足 EmbeddingProvider Protocol 的最小桩：记录调用，返回固定向量."""
|
||||
|
||||
model_name = "fake"
|
||||
version = "v1"
|
||||
dimensions = 4
|
||||
|
||||
def __init__(self) -> None:
|
||||
self.calls: list[list[str]] = []
|
||||
|
||||
async def embed(self, texts: list[str]) -> list[list[float]]:
|
||||
self.calls.append(list(texts))
|
||||
return [[0.25, 0.25, 0.25, 0.25] for _ in texts]
|
||||
|
||||
|
||||
class FakeSession:
|
||||
def __init__(self) -> None:
|
||||
self.commits = 0
|
||||
self.rollbacks = 0
|
||||
|
||||
async def commit(self) -> None:
|
||||
self.commits += 1
|
||||
|
||||
async def rollback(self) -> None:
|
||||
self.rollbacks += 1
|
||||
|
||||
|
||||
def _scored(chunk_id: int = 1) -> ScoredChunk:
|
||||
return ScoredChunk(
|
||||
chunk_id=chunk_id,
|
||||
entity_id=100,
|
||||
chunk_type="text",
|
||||
text="chunk",
|
||||
vec_score=1.0,
|
||||
kw_score=0.0,
|
||||
rule_score=0.0,
|
||||
freshness_score=1.0,
|
||||
final_score=0.55,
|
||||
)
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def stubbed_repo(monkeypatch: pytest.MonkeyPatch) -> dict[str, Any]:
|
||||
"""把 repo 的两个 IO 函数换成记录桩，service 逻辑照常执行."""
|
||||
|
||||
calls: dict[str, Any] = {"hybrid_search": None, "gaps": [], "results": []}
|
||||
|
||||
async def fake_hybrid_search(
|
||||
session: Any, query_vec: Any, query_text: str, **kwargs: Any
|
||||
) -> list[ScoredChunk]:
|
||||
calls["hybrid_search"] = {"query_vec": query_vec, "query_text": query_text, **kwargs}
|
||||
return list(calls["results"])
|
||||
|
||||
async def fake_record_gap(session: Any, query_text: str, filter_ctx: Any) -> None:
|
||||
calls["gaps"].append((query_text, filter_ctx))
|
||||
|
||||
monkeypatch.setattr(repo, "hybrid_search", fake_hybrid_search)
|
||||
monkeypatch.setattr(repo, "record_gap", fake_record_gap)
|
||||
return calls
|
||||
|
||||
|
||||
async def test_search_with_hits_returns_results_without_gap(stubbed_repo: dict[str, Any]) -> None:
|
||||
stubbed_repo["results"] = [_scored(1), _scored(2)]
|
||||
embedder = FakeEmbedder()
|
||||
session = FakeSession()
|
||||
svc = RetrievalService(session, embedding=embedder)
|
||||
|
||||
outcome = await svc.search("面试穿什么", user_ctx=UserContext(body_shape="apple"))
|
||||
|
||||
assert outcome.degraded is False
|
||||
assert [c.chunk_id for c in outcome.results] == [1, 2]
|
||||
assert stubbed_repo["gaps"] == []
|
||||
assert session.commits == 0 # 有结果的路径不写库，事务留给调用方
|
||||
assert embedder.calls == [["面试穿什么"]] # embed 的输入就是 query 原文
|
||||
|
||||
|
||||
async def test_search_forwards_user_context_to_hybrid(stubbed_repo: dict[str, Any]) -> None:
|
||||
stubbed_repo["results"] = [_scored()]
|
||||
svc = RetrievalService(FakeSession(), embedding=FakeEmbedder())
|
||||
|
||||
await svc.search(
|
||||
"婚礼穿什么",
|
||||
user_ctx=UserContext(
|
||||
body_shape="pear",
|
||||
occasion="wedding",
|
||||
entity_types=("item", "style"),
|
||||
rule_boost={42: 0.8},
|
||||
),
|
||||
)
|
||||
|
||||
seen = stubbed_repo["hybrid_search"]
|
||||
assert seen is not None
|
||||
assert seen["query_text"] == "婚礼穿什么"
|
||||
assert seen["body_shape"] == "pear"
|
||||
assert seen["occasion"] == "wedding"
|
||||
assert seen["entity_types"] == ("item", "style")
|
||||
assert seen["rule_boost"] == {42: 0.8}
|
||||
|
||||
|
||||
async def test_empty_entity_types_is_forwarded_as_none(stubbed_repo: dict[str, Any]) -> None:
|
||||
stubbed_repo["results"] = []
|
||||
svc = RetrievalService(FakeSession(), embedding=FakeEmbedder())
|
||||
|
||||
await svc.search("随便看看", user_ctx=UserContext())
|
||||
|
||||
seen = stubbed_repo["hybrid_search"]
|
||||
assert seen is not None
|
||||
assert seen["entity_types"] is None # 空元组 = 不限类型，不是匹配空集合
|
||||
|
||||
|
||||
async def test_no_results_records_gap_and_degrades(stubbed_repo: dict[str, Any]) -> None:
|
||||
stubbed_repo["results"] = []
|
||||
session = FakeSession()
|
||||
svc = RetrievalService(session, embedding=FakeEmbedder())
|
||||
|
||||
outcome = await svc.search(
|
||||
"不存在的知识点", user_ctx=UserContext(body_shape="apple", entity_types=("item",))
|
||||
)
|
||||
|
||||
assert outcome.degraded is True
|
||||
assert outcome.results == []
|
||||
assert session.commits == 1 # gap 埋点立即提交：检索本身只读，别拖住调用方事务
|
||||
assert stubbed_repo["gaps"] == [
|
||||
(
|
||||
"不存在的知识点",
|
||||
{"body_shape": "apple", "occasion": None, "entity_types": ["item"]},
|
||||
)
|
||||
]
|
||||
|
||||
|
||||
async def test_gap_failure_degrades_but_does_not_raise(
|
||||
stubbed_repo: dict[str, Any], monkeypatch: pytest.MonkeyPatch
|
||||
) -> None:
|
||||
"""埋点失败不该把"检索空结果"变成异常 —— 空结果本身是合法结局."""
|
||||
|
||||
async def broken_gap(session: Any, query_text: str, filter_ctx: Any) -> None:
|
||||
raise RuntimeError("db down")
|
||||
|
||||
monkeypatch.setattr(repo, "record_gap", broken_gap)
|
||||
stubbed_repo["results"] = []
|
||||
session = FakeSession()
|
||||
svc = RetrievalService(session, embedding=FakeEmbedder())
|
||||
|
||||
outcome = await svc.search("anything")
|
||||
|
||||
assert outcome.degraded is True
|
||||
assert session.rollbacks == 1
|
||||
|
||||
|
||||
async def test_default_context_when_user_ctx_omitted(stubbed_repo: dict[str, Any]) -> None:
|
||||
stubbed_repo["results"] = []
|
||||
svc = RetrievalService(FakeSession(), embedding=FakeEmbedder())
|
||||
|
||||
outcome = await svc.search("no ctx")
|
||||
|
||||
assert outcome.degraded is True
|
||||
assert stubbed_repo["gaps"] == [
|
||||
("no ctx", {"body_shape": None, "occasion": None, "entity_types": []})
|
||||
]
|
||||
|
||||
|
||||
def test_service_module_reexports_for_dependency_injection() -> None:
|
||||
"""service 与 repo 共享同一模块对象：monkeypatch 打桩路径就是生产调用路径."""
|
||||
|
||||
assert service_mod.repo is repo
|
||||
Reference in New Issue
Block a user