6. golden セットを引用しているコーパスを報告する。ただし引用 1 件では報告しない

• Status: accepted
• Date: 2026-08-15
• Deciders: project owner
• Applies to: v0.24.0

背景と課題

kb-mcp eval は golden query セットに対して retrieval を測る。測定対象の ナレッジベースが、その持ち主がノートを書く場所でもある場合 — 個人やチームの KB では普通のこと — golden query の文面を逐語で引用したノートは、その query に対する 最強の一致になる。上位を占め、ラベル付けされた正解を押し下げる。

参照コーパスで実際に観測された: ある query の文面を引用した当日書かれたノートが 1 位を取り、expected の文書を 4 位まで落とした。集計 recall は保たれたので何も 失敗せず、原因が分かったのは人がたまたま per-query の行を読んでいたからである。 評価について書くほど評価は通りにくくなるのに、それを知らせるものが無い。

厄介なのは、この観測には原因が 2 つあり、見分けがつかないことだ。query を逐語で 含む文書は、テストについて書いたノートか、そうでなければ query の出典である。 後者ならその文書はその query の expected に入るべきで、間違っているのは golden ファイルの方になる。区別できるのは golden を書いた本人だけである。

判断基準

• 健全なコーパスで発火する警告は、警告が無いより悪い。読み手に「読み飛ばす」ことを 学習させ、本物が出たときもそこに居るだけになる。
• eval の exit code には既に意味がある (--fail-on-regression)。何を報告するに せよ、それと exit code を奪い合ってはならない。
• 2 つの原因のどちらなのか分かっていない、ということについて正直でなければならない。
• コストは eval が 1 run で既に払っているものの範囲に収める。

検討した選択肢

各案を参照コーパス (662 文書 / 26 golden query、既知の混入は上記のノート 1 件のみ) で測った。指標は「健全なコーパスで何件発火するか」である。

1. embedding 類似度: query 文面と高類似 かつ expected でない hit を報告する。
2. 逐語引用・1 件で報告・top_k のみ: top_k の hit の本文が query 文面を 逐語で含んでいたら報告する。
3. 逐語引用・1 件で報告・コーパス全体: 同じ判定を、検索結果ではなく索引済みの 全文書に対して行う。
4. 逐語引用・distinct な query 2 件以上・コーパス全体。

決定

案 4。

案 1 は引くべき閾値が存在しない。上位 hit はどれも query と高類似であり — それが retrieval というものである — 条件は「検索結果を報告する」にほぼ等しい。

案 3 は 8 件を検出し、全部が偽陽性だった。理由は調整の問題ではなく構造的である: golden query はしばしばトピック名そのもの (cross-encoder / torch.compile / Qwen3.5-Omni) であり、トピック名はそのトピックを解説する文書に逐語で出てくる。 逐語一致 1 件は「そのトピックについての文書」の形である。

案 2 は 0 件だった。top_k に絞っても偽陽性は減らない (構造上それらは上位 hit である) 一方、規則だけが弱くなる。同じコーパスでの実測では、唯一実際に混入 していたノートは、引用している 2 つの query のうち片方の top_k には入り、 もう片方では 1〜10 位すべてが単一文書の chunk で埋まっていて入らなかった。

案 4 は ちょうど 1 件を検出し、それは実際に golden セットを記述していたノート だった — golden query の設計を説明しながら query 文字列をバッククォートで引用して いる文書である。複数の golden query を引用するのは「テストについてのノート」の 形であり、案 3 を使い物にならなくした母集団ときれいに分離できる。

所見は示唆する原因ではなく測った事実で名付け (golden-queries-quoted)、 メッセージには 2 つの原因を両方書く。これは kb-mcp doctor と同じ規律である: 観測を報告し、直し方を挙げ、何も変更しない。

影響

• 各 eval run は索引済み chunk 本文を 1 パス走査する。検索と同じ read スナップショットの中で走るので、指標を出したのと同じ index について報告する。 約 9.4k chunk の 1 パスは、run が既に行っている embedding と検索に比べれば無視できる。
• 所見は stderr に警告として、--format json には findings として出る。 exit code は変えない。引用が混入なのかラベル漏れなのかは kb-mcp が決められる ことではないので、ビルドを落とす根拠にはならない。
• findings は JSON に常に存在し、何も無ければ空配列になる。消費側が 「検査して 0 件」と「検査以前の出力」を区別できるようにするため。rank_in_top_k を key 不在ではなく null にするのも同じ理由 — top_k に居ないことは 欠測ではなく測った結果である。
• 所見は EvalRun に載るので run 履歴にも書かれる。そして ConfigFingerprint の外に意図的に置く。記録済み corpus と同じ理由で、fingerprint に入るものは 変化したときに diff を無効化するため、何かを報告した run だけが baseline を 失うことになってしまう。
• 空白正規化後 12 文字未満の query は照合しない。短い query は偶然多数の文書に 含まれ、この規則が依存している件数を汚すだけである。実測がこの値を両側から 挟んでいる: 参照コーパスでは 8 でも 12 でも結果が同じで、16 にすると真陽性が 消える (golden query は短いものに偏っているため)。
• 照合は索引されたテキストフィールド 1 つの中で行い、走査するフィールドの 集合は全文検索が索引している列とちょうど一致させる (見出し・パンくず・本文)。 この一致こそが選定規則であり、schema が動いても真であり続ける唯一の規則でもある: 走査が探しているのは「ラベル付けされた正解を押しのけ得るテキスト」なので、 その力を持つテキストを過不足なく覆う必要がある。3 つはいずれも他の 2 つに 現れないテキストを持つ — parser は見出し行を本文の外へ移し (かつ検索は見出しを 本文より重く索引し)、パンくずは frontmatter かファイル名由来の title で始まる。 何も連結しない: フィールドや chunk を繋ぐと、継ぎ目の両側にある無関係な文が 1 つの引用として読めてしまう。繋がない代償 (継ぎ目をまたぐ引用が見つからない) の方が安い。
• ある query の expected に挙がっている文書は、その query については数えない。 それが正解だからその文面を含んでいる。免除は entry が heading を指していても 文書全体に及ぶ。ラベル付けされた章だけに狭めると、「そのトピックについての 文書の別の章にトピック名が出ている」を数え始めることになり — それは 1 件規則を 使い物にならなくした母集団そのものである — さらに、所見も 2 件閾値も文書単位 なのに免除だけ章単位になって規則の粒度が揃わなくなる。代償は、同じ query に 答える文書の別の章にある本物の引用が報告されないこと。
• 別の一致で説明が付く一致は、独立した証拠として数えない。 片方の golden query がもう片方を含んでいると (cross-encoder reranking と how does cross-encoder reranking work?)、長い方を 1 回引用しただけで両方に 一致するので、一致した needle をそのまま数えると 1 回の引用が 2 件閾値を 満たしてしまう。同じ文書の他の一致の部分文字列になっている一致は落とす。 出現位置を持たない以上、「短い方が別の場所で本当に引用されていた」場合も 一緒に落ちるが、少なく数える側に倒すのは 2 件閾値そのものと同じ取引である。
• 正規化後に同じ文面になる golden entry は、数える前に 1 件に畳む。 golden loader は query 文の重複を弾かないので、ほぼ同一の entry を別々に 数えると、1 回の引用だけで 2 件閾値を満たせてしまう — この閾値が防ぐために 存在している偽陽性を、こちらから作り出すことになる。畳んだ query は、その文面を 持つ entry のどれか 1 つでもその文書を正解にしていれば免除する。文面が 同じなら「この文書はこの言い回しの正解である」は等しく成り立つ。
• 意図的な引用を黙らせる手段は用意しない。報告のコストが stderr の数行でしか ない以上、allow リストは主に実際の混入を恒久化する手段になる。ノイズが 実在すると分かれば、後から互換性を壊さずに追加できる。
• この検査に見えないもの: golden query をちょうど 1 件だけ引用しているコーパス。 これは精度のために承知の上で払う代償である — 代替案は 1 run あたり 8 件の 誤報として実測されている。