BM25 检索 idf 兜底常数把「没见过的词」顶成 top1：df=0 的 log(0) 除零兜底如何静默毁掉相关性排序

== 2. 索引里按契约口径算好的 idf vs 检索侧真正用的权重 ==
  the        契约口径(索引) idf=0.492476 | 检索侧实际用=1.405465     ← 口径就不一样
  dumplings  契约口径(索引) idf=1.280934 | 检索侧实际用=2.098612     ← 口径就不一样
  zqxunseen  契约口径(索引) idf=0.000000 | 检索侧实际用=1.000000     ← 兜底常数

== 4. 每轮真正参与打分的查询词（决定性证据） ==
  round1 查询词=['zqxunseen'] 命中=[('d01.txt', 0.0), ('d02.txt', 0.0), ('d03.txt', 0.0)]
                                     ↑ zqxunseen 在语料里一个词都没命中（df = 0），
                                       这份文档凭什么被选出来？

BM25_K1=1.2
BM25_B=0.75
BM25_IDF_MODE=okapi     # idf 口径 = okapi：ln(1 + (N - df + 0.5)/(df + 0.5))

cd scenario/2026-10-06-0800
docker compose up -d --build

# 一键复现（问题态）
docker compose exec -T search bash ops/repro.sh

# 验收（问题态应为 PASS=3 FAIL=7 / RESULT: BAD）
docker compose exec -T search bash ops/verify.sh

== A. 权重与契约口径不一致的词数 ==        [FAIL] (期望=0 实际=95)
== B. 没见过的词 zqxunseen 的权重 ==       [FAIL] (期望=2.890371758 实际=1.000000000)
== B. 没见过的词权重 ≥ 语料内所有词 ==      [FAIL] (期望=yes 实际=no)
== C. 无依据的命中条数 ==                  [FAIL] (期望=0 实际=3)
== E. 口径失效时 health 退出码 ==          [FAIL] (期望=2 实际=0)
== G. 删掉 conf/bm25.env 后 health 退出码 ==[FAIL] (期望=3 实际=0)
== H. 外部探针判定 ==                       [FAIL] (期望=OK 实际=BAD)
PASS=3 FAIL=7
RESULT: BAD

idf_okapi(w) = ln( 1 + (N - df + 0.5) / (df + 0.5) )

term             df    问题态(算术)   契约(okapi)
the               5      1.405465      0.492476
hot               1      2.504077      1.791759
dumplings         2      2.098612      1.280934

def _idf(df, total):
    if df <= 0:
        return 1.0                                  # ← 兜底常数
    return math.log((total + 1) / (df + 1)) + 1.0

zqxunseen (df=0)：契约 okapi = ln(18) ≈ 2.890372（全局最大）
                  问题态兜底 = 1.000000

scored = sorted(((-self._score(query_terms, d), d) for d in self.order), ...)

def main(argv=None) -> int:
    print(json.dumps({"degraded": False, "issues": [],
                      "self_consistent": True, "ok": True}, ...))
    return EXIT_OK          # 退出码恒 0

self._frozen = {k[4:]: v for k, v in (payload.get("idf") or {}).items()
                if k.startswith("idf.")}

def weight(self, term: str) -> float:
    """检索侧真正用来排序的权重 —— 契约口径的唯一实现。"""
    self.idf_calls += 1
    frozen = self._frozen.get(term)
    if frozen is not None:
        return float(frozen)
    # 语料里没有这个词（df=0）：okapi 口径照样有确定取值（全局最大）
    return bm25.idf(0, self.total, self.idf_mode)

def search(self, query_terms):
    # 只有在文档里**真的命中查询词**的文档才是候选
    candidates = [d for d in self.order
                  if any(t in self.docs[d] for t in query_terms)]
    if not candidates:
        return []
    ...
        hits.append({"doc": doc, "score": -neg,
                     "matched_terms": sorted(t for t in set(query_terms)
                                             if t in self.docs[doc])})

if hits and all(h["matched_terms"] for h in hits):
    self.rounds_verified += 1          # 逐轮累加，不是抄总数
...
"self_consistent": out["rounds_verified"] == out["rounds_total"] and not out["errors"],
"ok": not out["errors"],

BAD_FIELDS = (("ok", True), ("rounds_total", None))   # 空表 = 关掉整个健康检查

# ① 索引里的冻结 idf 必须等于契约口径重算的结果（含 df=0 的词）
want = bm25.idf(df, loaded["total_docs"], bm25_conf["idf_mode"])
if abs(float(frozen[term]) - want) > 1e-9:
    issues.append("词 %s 的 idf 索引值 %r ≠ 契约口径 %r" % (term, got, want))
# ② 每一条命中都必须真的命中查询词
if not any(t in loaded["docs"][doc] for t in terms):
    issues.append("无依据的命中：查询=%s 第 %d 轮 文档=%s 无一查询词命中" % ...)
# ③ 索引登记的文档清单必须与语料目录一致

except contract.ContractError as exc:  return EXIT_CONTRACT   # 3
except index_store.IndexMissing as exc: return EXIT_BAD        # 2

docker compose exec -T search bash ops/apply_fix.sh --apply
docker compose exec -T search bash ops/verify.sh

  [PASS] 权重与契约口径不一致的词数(0=一致) (期望=0 实际=0)
  [PASS] 没见过的词 zqxunseen 的权重(契约 df=0 口径) (期望=2.890371758 实际=2.890371758)
  [PASS] 没见过的词权重 ≥ 语料内所有词(okapi 口径的自然结果) (期望=yes 实际=yes)
  [PASS] 无依据的命中条数(0=每条都真的命中查询词) (期望=0 实际=0)
  [PASS] top1 与契约口径重算不一致的轮次数(0=一致) (期望=0 实际=0)
  [PASS] 口径失效时 health 退出码(非 0=抓到问题) (期望=2 实际=2)
  [PASS] 自述被改坏但索引/语料完好时不应误报(0=不误报，仅作参考) (期望=0 实际=0)
  [PASS] 删掉 conf/bm25.env 后 health 退出码 (期望=3 实际=3)
  [PASS] 删掉 conf/bm25.env 后 demo.py 退出码 (期望=3 实际=3)
  [PASS] 外部探针判定 (期望=OK 实际=OK)
PASS=10 FAIL=0
RESULT: OK

== 2. 索引 vs 检索侧权重 ==
  the        契约口径(索引) idf=0.492476 | 检索侧实际用=0.492476      ← 一致
  dumplings  契约口径(索引) idf=1.280934 | 检索侧实际用=1.280934      ← 一致
  zqxunseen  契约口径(索引) idf=0.000000 | 检索侧实际用=2.890372      ← 契约 df=0 取值

== 4. round1 查询词=['zqxunseen'] 命中=[]        ← 零交集不再进 hits
== 6. RESULT: OK                                 ← 探针退出码 0

docker compose exec -T search bash ops/negative.sh

== 2. 索引里按契约口径算好的 idf vs 检索侧真正用的权重 ==
Traceback (most recent call last):
  File "<string>", line 10, in <module>
AttributeError: 'Ranker' object has no attribute 'frozen_idf'

-from app import contract, index_store, ranker
+from app import contract, index_store, ranker, reports
 r=ranker.Ranker(p, sc)
+frozen=reports.idf_table(p)          # 索引里冻结的契约口径 idf
 for t in ('the','dumplings','zqxunseen'):
-    print(... % (t, r.frozen_idf(t) or 0.0, r.weight(t)))
+    print(... % (t, frozen.get(t) or 0.0, r.weight(t)))

docker compose exec -T search bash -c '
cd /srv
mv conf/bm25.env conf/bm25.env.bak
python3 app/demo.py; echo "rc=$?"        # rc=3 [FATAL] 契约不可用
mv conf/bm25.env.bak conf/bm25.env'

docker compose exec -T search bash ops/verify.sh

docker compose exec -T search bash -c 'cd /srv && \
  rm -f index/*.json state/*.json && rm -rf app/__pycache__'