Evidence Sieve · 证据筛

面向 Agent 的本地证据筛选小工具：保守归组 + 差异保护 MMR，保留来源、按版本和对象过滤，通过 CLI / MCP / Skill 使用，不需要修改 Agent 源码。

适合这样的场景：多个文档反复描述同一个事实，直接 Top-K 被重复段落占满，真正的限制条件和互补信息进不了上下文。

v0.2 默认使用 sieve_mmr、λ=.7。 它针对标准 MMR 的两个问题：高相关副本仍可能反复占位，以及不同数值、否定、条件可能被当成冗余压低。MMR 原理与实现来源。

本版同时公开开发集调参、未用于调参的 NFCorpus 测试、旧 SciFact 回归及消融，并保留“精确归组＋MMR”强基线。没有运行下游生成模型，不宣称提高最终回答正确率或节省总 token。

以下为文档 Recall；标准 MMR 的 λ 来自独立开发集，不在测试集挑参数。

结论有限：优于本次调参的标准 MMR，但没有超过精确去重＋相关性排序强基线。 消融未发现语义归组额外提高 Recall/事实覆盖；新规则增加筛选耗时，来源列表增加 token。旧 12 个同义场景中，同 λ=.7 的事实覆盖为 94.44% 对 86.11%；但 MMR λ=.3 也能达到 100%，该集合不属于独立盲测。

置信区间、消融、成本和逐题记录见 v0.2 完整实验报告。v0.1 历史结果 保留可查。

它做什么

flowchart LR
    A[Agent 的问题] --> B[本地文档检索]
    B --> C[严格过滤版本和对象]
    C --> D[广召回候选]
    D --> E[保守去重与来源归组]
    E --> F[差异保护 MMR 与预算选择]
    F --> G[返回证据包给 Agent]

同义段落只显示一个代表原文，同时保留组内来源 ID。遇到规则能识别的数字、否定、单位、条件、代码标识符、版本和对象差异，会拒绝语义合并。随后进行 MMR 选择；对不能安全合并的证据对，排序时不施加相似度惩罚。低于相关性下限的条目不会入选。这仍是启发式规则，不能保证找出所有重要差异。

提供六种策略：topk、mmr、naive_dedup（仅向量阈值）、exact（精确去重）、sieve（保守去重后按相关性补位）和 sieve_mmr（默认）。它们共用检索编码器、过滤和预算。若需要原来的选择策略，显式传 --method sieve；原样复现 v0.1 则使用历史提交。

Related MCP server: RAG In A Box MCP Server

安装和第一次查询

要求 Python 3.11+。项目目前从 GitHub 安装，尚未发布到 PyPI。

Windows PowerShell：

git clone https://github.com/2gg-bit/evidence-sieve.git
cd evidence-sieve
python -m venv .venv
.venv/Scripts/python.exe -m pip install -e ".[semantic]"
.venv/Scripts/python.exe -m evidence_sieve.cli search --corpus examples/corpus.jsonl --encoder semantic --query "备份保留多久，维护期间执行吗？" --version 2 --scope atlas

macOS / Linux：

git clone https://github.com/2gg-bit/evidence-sieve.git
cd evidence-sieve
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[semantic]"
.venv/bin/python -m evidence_sieve.cli search --corpus examples/corpus.jsonl --encoder semantic --query '备份保留多久，维护期间执行吗？' --version 2 --scope atlas

语义模式使用本机 CPU，无 API Key。首次运行从 Hugging Face 下载 多语言 MiniLM 模型，也会下载 tiktoken 编码文件；后续可复用缓存。安装 [semantic] 会包含 PyTorch 等较大的依赖。

若只想先验证接入，可安装 pip install -e . 并省略 --encoder semantic，使用默认 tfidf。TF-IDF 是词面检索，不等同于语义去重能力。 本项目实验也保留了该模式的负结果。

下面的短命令假设已激活虚拟环境；未激活时请使用上面的 python -m evidence_sieve.cli 形式。

evidence-sieve search --corpus examples/corpus.jsonl --encoder semantic --query "备份策略" --budget 1500 --k 4
evidence-sieve search --corpus examples/corpus.jsonl --encoder semantic --query "备份策略" --method mmr
evidence-sieve expand --corpus examples/corpus.jsonl --id retention
evidence-sieve serve --corpus examples/corpus.jsonl --encoder semantic

serve 会等待 MCP 客户端通过标准输入输出通信，直接启动后看似没有输出是正常现象。

准备自己的文档

方式一：Markdown 文件夹。 传 --corpus /absolute/path/docs，按空行切段，来源保留相对路径和行号。它不解析标题层级、front matter、PDF 或 Word，不自动推断版本。

方式二：JSONL。 每行一个 UTF-8 JSON 对象，推荐在需要版本/对象过滤时使用：

{"id":"backup-v2-a","text":"备份保留 7 天。","source":"kb-a/backup.md#L12","version":"2","scope":"atlas","claim_key":"backup.retention","claim_value":"7 days"}
{"id":"backup-v2-b","text":"维护期间暂停自动备份。","source":"kb-b/operations.md#L8","version":"2","scope":"atlas"}

可把不同知识库的段落合并到一个 JSONL，保持 ID 唯一、来源清楚。不要把 scope 仅作为文件夹名随意填写：它会阻止跨 scope 合并，也影响严格查询过滤。

--version 2 只匹配元数据恰好为 "2" 的条目，缺少版本的条目会被排除。conflicts 只比较已选证据中、显式填写的 claim 元数据，不是通用自然语言矛盾检测器。

输出与参数

输出 JSON 的 evidence 每项包含代表原文、相似度、版本/对象和 sources；合并来源的 ID 仍可用 expand 查看。不会生成摘要或修改原文。stats.duplicates_collapsed 是整个候选池中归组的数量，不表示这些组最终都被选中。

预算包括原文、所有来源和冲突信息，不含 MCP 外层包装、宿主提示和后续展开请求。不同宿主模型 tokenizer 不同，因此不能把这个上限当作实际账单。过长段落整个跳过，不偷偷截断；若来源列表过长，也可能导致整组无法装入预算。

接入 Claude Code / Codex / OpenCode / Pi

查看 完整接入说明，含绝对路径配置、Skill、环境变量、提示词示例和故障排查。标准 MCP 提供 search_evidence、expand_evidence 两个工具。Pi 等可调用 CLI。

只筛选经本工具查询的资料，不会自动替换 Agent 的全部文件读取或搜索。 只有候选仍留在服务内部、筛选结果才进入会话时，才可能改善上下文利用。

已有检索系统怎么复用

Python API 可以对自己的候选及向量进行筛选，无需重新构建一个知识库：

from evidence_sieve import Document, EvidenceSieve, SearchOptions

# candidate_vectors 与 query_vector 必须由同一编码模型生成；行顺序与 documents 一致。
documents = [Document(id="a", text="备份保留 7 天。", source="kb/a.md", version="2")]
engine = EvidenceSieve(documents, vectors=candidate_vectors)
packet = engine.search("备份保留多久？", SearchOptions(version="2"), query_vector=query_vector)

示例中的两个向量变量由调用方提供。当前没有内置 Qdrant、Milvus、云知识库连接器，也没有重排模型。

实验和开发

查看 v0.2 实验报告、协议及开发补充记录 和 原始结果。包含 24 个旧中英文机制场景、SciFact 回归、新 NFCorpus 留出测试、多组消融、配对置信区间。开发集包含 SciFact train 全部 809 题、NFCorpus dev 全部 324 题。实验脚本不把 gold/qrels 输入算法。

python -m pip install -e ".[semantic,benchmark,dev]"
python -m pytest -q
python -m ruff check .
python -m ruff format --check .
python -m build
python benchmarks/check_mmr_reference.py
python benchmarks/mmr_study.py dev
python benchmarks/mmr_study.py test
python benchmarks/mmr_study.py controlled
python benchmarks/controlled_grid.py
python benchmarks/report_v2.py
python benchmarks/provenance_v2.py

只复核已发布参数时可跳过 dev，使用仓库已有的 selected.json；若算法 hash 不一致，脚本会要求重新选择参数。公开数据从 BEIR 官方 Hugging Face 固定 revision 镜像下载，数据与 embedding 缓存在忽略的 work/，模型在 Hugging Face 缓存中。时间指标受硬件、缓存和负载影响，完整开发网格需要较长时间。

当前边界

• 原型通过本地 CLI 和真实 MCP 协议测试；未做各 Agent 宿主的完整模型任务评测。

• 守护规则覆盖有限，中文数字、实体关系、复杂条件等可能误判；高相似度不是含义相同的证明。

• 默认语义模型最多编码 128 个模型 token，长段落尾部可能无法参与相似度计算；返回的原文仍是完整段落。推荐自行准备短且语义完整的切块。

• 内存内全量索引，没有增量更新、持久化向量库或大规模性能保证。TF-IDF 使用稠密矩阵，大语料可能占用大量内存。

• 不自动判定来源权威性、不推断哪个版本最新、不消除自然语言冲突。

• 目前没有下游生成模型对比，不能宣称减少幻觉、提高答案正确率或降低总成本。来源元数据和补充事实可能使返回 token 增加。

MIT 开源。外部模型和数据各自遵循原许可证；公开 SciFact、NFCorpus 文本不随本仓库分发。数据来源与许可见 实验报告。