跳到正文
ZHX NEXUS Studio
返回

改善提案查重评测笔记

编辑页面

此前搭了一套「改善提案知识库」:FastGPT,3562 条,走开放 API,员工提交提案前做查重提示。库上线后一直有个说不清的问题——它到底查得准不准?哪些重复查得出来、会不会误伤全新提案、命中的是不是同一条、阈值该怎么定。

这篇笔记记录我当时做查重评测的思路和一套 Python 评测脚本,留着给自己复盘。

适用边界:查重应用在 FastGPT 上绑定了改善提案知识库,开启引用(quote)返回;评测脚本走开放 API 调同一个应用,保证评测环境和生产提交前查重完全一致。


一、目录结构

当时用的结构,仅供参考:

proposal_dedup_eval/
├── data/
│   ├── golden_set/
│   │   ├── golden_set_v1.xlsx          # 标准测试集(人工构建)
│   │   └── golden_set_v1.json          # 备份
│   ├── results/
│   │   ├── eval_v1.0_20260917.xlsx
│   │   ├── eval_v1.1_20260920.xlsx
│   │   └── comparison_report.md
│   └── kb_snapshot/
│       └── kb_id_title_map_20260917.csv # 知识库"ID↔标题"快照(用于 expected_match_id 校验)
├── scripts/
│   ├── build_golden_set.py             # 辅助构建/脱敏测试集(可选)
│   ├── dedup_client.py                 # FastGPT 查重 API 封装
│   ├── metrics.py                      # 指标计算(查全/查准/F1/匹配准确率/阈值敏感度)
│   ├── run_eval.py                     # 主评测脚本
│   └── generate_report.py              # 报告生成
├── config/
│   └── config.yaml                     # API Key、模型、阈值、库快照路径
├── requirements.txt
└── README.md

二、标准测试集(Golden Set)设计

2.1 字段规范

字段名类型必填说明
idstr是GS-001
proposal_textstr是提交的提案内容(建议”标题 + 换行 + 正文”与原提交表单一致)
expected_verdictstr是duplicate / similar / not_duplicate
expected_match_idstr否期望命中的已有提案 ID(duplicate/similar 时必填)
expected_match_titlestr否期望命中的标题(辅助校验,防 ID 漂移)
question_typestr是见 2.2
difficultystr是easy / medium / hard
ground_truth_excerptstr否被期望命中的那条提案的原文片段(用于判定”命中对象是否真的是同一条”)
tagsstr否业务标签(车间/工序/改善类型)
notesstr否备注

注意:expected_match_id 必须来自评测当天的知识库快照(kb_snapshot/)。库是增量更新的,三个月前的 ID 可能已合并/删除,导致”系统明明对了却被判错”。

2.2 问题类型与覆盖比例(建议 200 条起步)

question_type含义占比期望 verdict
exact与库中某条字面几乎一致(同标题同正文)15%duplicate
semantic改写但核心改善点相同(换说法、调语序、拆句)30%similar
evasion规避式改写(改数字/同义词/加无关修饰,试图绕过查重)10%similar 或 duplicate
partial部分重叠(解决同一痛点但范围/对象不同,如 A 车间 vs B 车间)15%similar(需谨慎,见踩坑④)
cross_dept同名不同义(多个车间都有”5S整顿""降低能耗”,但内容无关)15%not_duplicate
not_dup全新提案(库里确实没有)15%not_duplicate

初期 200 条即可覆盖主要类型;稳定后扩到 400–500 条,并按车间/改善类型分层抽样。

2.3 示例

idproposal_textexpected_verdictexpected_match_idquestion_typedifficulty
GS-001降低 xx 车间焊接工序焊丝损耗:通过优化电流参数与回收余料,预计月省 800 元duplicateP-10233exacteasy
GS-002焊丝浪费怎么省?我们焊接线把电流调小还收余料,一个月能省大概八百块similarP-10233semanticmedium
GS-003把焊接电流调低、余料回收,每月节省约 800 元(原案是 820,这里写 800 规避)similarP-10233evasionhard
GS-004降低 yy 车间装配线螺丝损耗:优化扭矩参数与回收not_duplicate—cross_deptmedium
GS-005员工餐补线上申领流程优化:接入企微审批自动核算not_duplicate—not_dupeasy

三、核心实现(参考)

3.1 config/config.yaml

fastgpt:
  api_key: "fastgpt-xxxxxxxx"
  base_url: "https://api.fastgpt.in/api/v1/chat/completions"  # 或私有化地址
  app_id: "xxxx"                 # 查重应用 ID(若有)
  user: "eval_user"
  detail: true                   # 关键:返回 quote(命中的知识库条目)
  stream: false

eval:
  # 判定"命中"的相似度阈值;run_eval 会做阈值扫描
  similarity_threshold: 0.6
  timeout: 30
  # 查重应限定在改善提案体系内(见踩坑⑧),不跨其他知识库
  restrict_to_proposal_kb: true

paths:
  golden_set: "data/golden_set/golden_set_v1.xlsx"
  results_dir: "data/results"
  kb_snapshot: "data/kb_snapshot/kb_id_title_map_20260917.csv"

3.2 scripts/dedup_client.py(FastGPT 查重接口封装)

import time
import httpx
from typing import Dict, Any, Optional, List

class DedupClient:
    """封装 FastGPT 查重:发送提案文本,返回命中的已有提案列表(quote)。"""
    def __init__(self, api_key: str, base_url: str, user: str = "eval_user",
                 detail: bool = True, timeout: float = 30.0):
        self.api_key = api_key
        self.base_url = base_url.rstrip("/")
        self.user = user
        self.detail = detail
        self.timeout = timeout
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

    def check(self, proposal_text: str, conversation_id: Optional[str] = None) -> Dict[str, Any]:
        """
        返回结构:
        {
          "success": bool,
          "answer": str,            # FastGPT 生成的查重提示文本
          "matches": [              # 命中的已有提案(来自 quote)
             {"id": str, "title": str, "score": float, "content": str}, ...
          ],
          "latency": float,
          "usage": dict,
          "error": str
        }
        """
        payload = {
            "chatId": conversation_id or "",
            "stream": False,
            "detail": self.detail,
            "messages": [{"role": "user", "content": proposal_text}]
        }
        start = time.time()
        try:
            with httpx.Client(timeout=self.timeout) as client:
                resp = client.post(self.base_url, headers=self.headers, json=payload)
                resp.raise_for_status()
                data = resp.json()
        except Exception as e:
            return {"success": False, "answer": "", "matches": [],
                    "latency": time.time() - start, "usage": {}, "error": str(e)}

        latency = time.time() - start

        # 解析 quote:FastGPT detail=true 时,data.data[0].quote 是命中知识库条目
        matches: List[Dict] = []
        try:
            quotes = data.get("data", [{}])[0].get("quote", []) or []
            for q in quotes:
                matches.append({
                    "id": str(q.get("id", "")),
                    "title": q.get("sourceName") or q.get("q") or "",
                    "score": float(q.get("score") or 0.0),
                    "content": (q.get("a") or q.get("content") or "")[:300]
                })
        except Exception:
            pass

        return {
            "success": True,
            "answer": data.get("answer", ""),
            "matches": matches,
            "latency": latency,
            "usage": data.get("usage", {}) or {},
            "error": ""
        }

对接要点:我们是”开放 API + 提交前查重提示”,逻辑就是”把提案文本丢给 FastGPT 查重应用,它返回相似提案”。detail=true 能拿到 quote(命中的知识库条目),这是判定的黄金信号。若用的是 FastGPT 的 dataset/search 接口(直接检索而非对话),把 check() 换成对应请求、解析 data 数组即可,结构一致。

3.3 scripts/metrics.py(指标计算)

查重本质是一个检索 + 分类问题,核心看”该查出来的查出来没、不该查的误伤没、查的对象对不对”。

from typing import List, Dict, Optional

class DedupMetrics:
    # —— 单条判定 ——
    def is_hit(self, matches: List[Dict], expected_id: Optional[str],
               threshold: float) -> bool:
        """在 matches 中是否找到 expected_id 且分数 >= 阈值。"""
        if not expected_id:
            return False
        for m in matches:
            if str(m.get("id", "")).strip() == str(expected_id).strip() \
               and float(m.get("score", 0.0)) >= threshold:
                return True
        return False

    # —— 集合指标(一轮跑完汇总)——
    def summarize(self, rows: List[Dict], threshold: float) -> Dict[str, float]:
        """
        rows: 每条评测结果,字段含
          expected_verdict, expected_match_id, matches(列表),
          should_flag(bool=是否应命中), is_dup_family(bool=duplicate/similar/evasion)
        """
        total = len(rows)
        # 该命中(dup家族)的题
        should_flag = [r for r in rows if r["should_flag"]]
        # 不该命中(not_dup / cross_dept)的题
        should_not_flag = [r for r in rows if not r["should_flag"]]

        tp = sum(1 for r in should_flag if self.is_hit(r["matches"], r["expected_match_id"], threshold))
        fn = len(should_flag) - tp                      # 漏报
        fp = sum(1 for r in should_not_flag if r["matches"])  # 误报(返回了任何命中)
        tn = len(should_not_flag) - fp

        recall = tp / len(should_flag) if should_flag else 1.0
        precision = tp / (tp + fp) if (tp + fp) else 1.0
        f1 = (2 * precision * recall / (precision + recall)) if (precision + recall) else 0.0
        false_negative_rate = fn / len(should_flag) if should_flag else 0.0
        false_positive_rate = fp / len(should_not_flag) if should_not_flag else 0.0

        # 匹配准确率:在"命中且应命中"的题里,返回的 ID 是不是真等于 expected
        match_acc_denom = [r for r in should_flag if self.is_hit(r["matches"], r["expected_match_id"], threshold)]
        match_acc = 0.0
        if match_acc_denom:
            correct = sum(1 for r in match_acc_denom
                          if any(str(m.get("id",""))==str(r["expected_match_id"]) for m in r["matches"]))
            match_acc = correct / len(match_acc_denom)

        return {
            "total": total,
            "recall": recall,                 # 查全率(该查的查出来没)
            "precision": precision,           # 查准率(查出来的真该查吗)
            "f1": f1,
            "match_accuracy": match_acc,      # 命中对象对不对
            "false_negative_rate": false_negative_rate,  # 漏报率
            "false_positive_rate": false_positive_rate,  # 误报率
        }

    def threshold_sweep(self, rows: List[Dict], thresholds: List[float]) -> List[Dict]:
        """扫描不同阈值,帮你定最佳 similarity_threshold。"""
        out = []
        for t in thresholds:
            m = self.summarize(rows, t)
            m["threshold"] = t
            out.append(m)
        return out

3.4 scripts/run_eval.py(主评测脚本)

import yaml
import pandas as pd
from pathlib import Path
from datetime import datetime
from dedup_client import DedupClient
from metrics import DedupMetrics

DUP_FAMILY = {"duplicate", "similar", "evasion"}

def load_config():
    with open("config/config.yaml", encoding="utf-8") as f:
        return yaml.safe_load(f)

def main():
    cfg = load_config()
    client = DedupClient(
        api_key=cfg["fastgpt"]["api_key"],
        base_url=cfg["fastgpt"]["base_url"],
        user=cfg["fastgpt"]["user"],
        detail=cfg["fastgpt"]["detail"],
        timeout=cfg["eval"]["timeout"],
    )
    threshold = float(cfg["eval"]["similarity_threshold"])

    df = pd.read_excel(cfg["paths"]["golden_set"])
    rows = []
    for idx, r in df.iterrows():
        print(f"评测 {r['id']} ({idx+1}/{len(df)}) 类型={r['question_type']}")
        resp = client.check(str(r["proposal_text"]))

        should_flag = str(r["expected_verdict"]).lower() in DUP_FAMILY
        rows.append({
            "id": r["id"],
            "question_type": r["question_type"],
            "difficulty": r["difficulty"],
            "expected_verdict": r["expected_verdict"],
            "expected_match_id": str(r.get("expected_match_id", "")).strip(),
            "should_flag": should_flag,
            "matches": resp.get("matches", []),
            "success": resp.get("success", False),
            "latency": round(resp.get("latency", 0), 3),
            "error": resp.get("error", ""),
            "pred_match_ids": ",".join(str(m.get("id","")) for m in resp.get("matches", [])),
        })

    calc = DedupMetrics()
    summary = calc.summarize(rows, threshold)

    # 阈值扫描(可选,跑慢但有用)
    sweep = calc.threshold_sweep(rows, [0.4, 0.5, 0.6, 0.7, 0.8])

    # 落盘
    out_df = pd.DataFrame(rows)
    ts = datetime.now().strftime("%Y%m%d")
    version = "v1.0"
    out_path = Path(cfg["paths"]["results_dir"]) / f"eval_{version}_{ts}.xlsx"
    out_path.parent.mkdir(parents=True, exist_ok=True)
    out_df.to_excel(out_path, index=False)

    print("\n===== 评测汇总(阈值=%.2f)=====" % threshold)
    for k, v in summary.items():
        print(f"{k}: {v}")
    print(f"结果已保存: {out_path}")
    print("\n阈值扫描:")
    for s in sweep:
        print(f"  t={s['threshold']} recall={s['recall']:.2%} precision={s['precision']:.2%} f1={s['f1']:.2%} FNR={s['false_negative_rate']:.2%} FPR={s['false_positive_rate']:.2%}")

if __name__ == "__main__":
    main()

3.5 scripts/generate_report.py(报告生成)

读取多次评测 Excel,计算各版本均值,生成 Markdown(结构同原方案第四节),重点放:

报告结构建议:

# 改善提案查重评测报告

## 1. 执行摘要
- 知识库规模:3562 条;测试集:200 条
- 查全率 78% → 93%,误报率 12% → 4%,匹配准确率 85% → 96%
- 平均响应:1.6s

## 2. 版本对比表
| 版本 | 查全率 | 查准率 | F1 | 匹配准确率 | 误报率 | 平均耗时 | 失败率 |
|------|--------|--------|----|------------|--------|----------|--------|
| v1.0 | 78%    | 88%    |0.83| 85%        | 12%    | 1.9s     | 2%     |
| v1.1 | 93%    | 95%    |0.94| 96%        | 4%     | 1.6s     | 1%     |

## 3. 分类型表现
...

## 4. 典型失败案例
...

## 5. 阈值建议
...

## 6. 改进建议
...

四、与 FastGPT 的对接方式

  1. 查重应用:在 FastGPT 建一个”查重专用”应用,绑定改善提案知识库,开”引用/quote 返回”。
  2. 调用方式:评测脚本走开放 API(/api/v1/chat/completions,detail=true)。
  3. 限定范围(重要):查重必须限定在「改善提案体系内」——只检改善提案库,不跨其他知识库误命中(见踩坑⑧)。
  4. 一致性:评测用的 app 配置(检索参数、top_k、相似度阈值)必须与生产提交前查重完全一致,否则评测结果不能代表线上。
  5. 知识库快照:评测当天导出 kb_id_title_map.csv(ID + 标题 + 入库时间),Golden Set 的 expected_match_id 以此为准。

五、落地节奏(当时排的)

阶段时间关键动作产出
Day 1-2构建 Golden Set抽样 3562 条 + 人工写 150–200 条(含脱敏,见踩坑①)golden_set_v1.xlsx + kb_snapshot
Day 3跑通脚本调通 FastGPT API + quote 解析 + 基础指标能跑完一轮
Day 4第一轮基线记录当前查重能力eval_v1.0_xxx.xlsx + 简报
Day 5-7优化 + 再评测调检索参数/top_k/阈值/提示词对比报告(如 78%→93%)
后续常态化每次重大变更(知识库增量、检索策略调整)都跑评测版本化记录

六、额外建议(让体系更完整)

  1. 专项集:单独准备 30–50 条”库里真没有”的题,专看误报率。
  2. 成本计算:按 token 单价把 usage 转金额,评估每次提交查重的成本。
  3. 人工抽检:每轮随机抽 20 条人工复核,校准”LLM/规则判分”的偏差。
  4. 库内自重复检测:3562 条本身可能已有重复,先跑一遍”库 vs 库”自查,把库自身的重复作为已知问题隔离,避免污染评测预期。
  5. 权限测试:用不同权限 Key 跑同一套集,验证查重范围过滤是否生效。

七、踩过的坑(12 条)

这些是我实际踩过或预判的坑,逐条对照能少走弯路。

① 测试集泄漏 / 脱敏

② 知识库是活的,expected_match_id 会漂移

③ 字面相同 ≠ 语义相同,反之亦然

④ partial(部分重叠)的判定边界模糊

⑤ 阈值(similarity_threshold)是核心旋钮,必须扫描

⑥ 评测集规模与分层抽样

⑦ 接口限流 / 超时 / 不稳定

⑧ 查重范围必须限定”改善提案体系内”

⑨ 判分信号来源要可信

⑩ 库本身有重复会污染预期

⑪ 数字/单位/全半角干扰

⑫ 评测结论要落到”业务动作”


上面代码是按我们 FastGPT 实际返回结构写的,换环境时以 quote 里的结构化 id 为准(见踩坑⑨),其余按实际微调。评测集与库快照必须配套版本化管理,否则指标不可复现。


编辑页面
分享这篇文章:

上一篇
企业级知识库落地,不能把所有文档都塞进 RAG
下一篇
AI 考试笔记 · 知识图谱