09 · 标注体系怎么设计

   一条真实工单：
   「我下单三天了还没发货，我要投诉，另外这单我不想要了要退款」

   在【互斥 32 类】体系下，三个标注员给出三个答案：
     标注员 A → 物流异常     （他抓的是"事实是什么"）
     标注员 B → 投诉         （他抓的是"情绪最强的诉求"）
     标注员 C → 退款申请     （他抓的是"最终要办的事"）

   ⭐ 三个人都没错。错的是"必须选一个"这件事本身。
   这条样本进训练集之后，它教给模型的是：这三个类可以互相替代。

   ① 自己先标 50 条真实样本
      有几条你想勾两个？>5% → 它不是互斥问题

   ② 能不能造出"两者都是"的合法例子？
      造得出来 → 不是互斥。造不出来才是。
      ⚠️ 别用想象的例子，从真实数据里翻

   ③ 看「其他」类的占比
      >10% → 体系没盖住现实，缺类别
      >20% → 体系需要重做，不是加一个类的问题  ⭐

def taxonomy_smell_test(df, label_col, multi_col=None, other_label="其他"):
    """三个测试的量化版：跑在试标注的前 200 条上"""
    n = len(df)
    other_rate = float((df[label_col] == other_label).mean())
    r = {"其他类占比": round(other_rate, 4),
         "结论_其他类": "OK" if other_rate <= 0.10 else ("缺类别" if other_rate <= 0.20 else "体系需重做")}
    if multi_col is not None:                      # multi_col: 标注员"想勾多个"的标记列
        want_multi = float(df[multi_col].fillna(False).astype(bool).mean())
        r["想勾多个的比例"] = round(want_multi, 4)
        # ⭐ 超过 5% 就不该做成互斥单标签
        r["结论_互斥性"] = "可以互斥" if want_multi <= 0.05 else "应改为多标签"
    r["样本量"] = n
    return r

   ① 试标注里的分歧样本   ← 最主要来源，见第四节
   ② 线上模型的低置信样本 ← 模型犹豫的地方，人也在犹豫
   ③ 质检打回的样本       ← 每一条都自带"为什么错"

   ❌ 按类别组织                    ✅ 按类别对组织  ⭐
   ────────────────────           ──────────────────────────
   投诉：边界样例 12 条            投诉 ↔ 退款申请：8 条
   退款申请：边界样例 9 条          投诉 ↔ 咨询-情绪：5 条
   咨询：边界样例 7 条              物流异常 ↔ 投诉：6 条
   ...（标注员不知道去哪找）        其他类别对：无分歧，不用写

import json

BOUNDARY_SCHEMA = {
    "pair": ["投诉", "退款申请"],          # ⭐ 按类别对索引，不按单类别
    "text": "我不想要了，退钱吧",
    "label": "退款申请",
    "why": "只有退款诉求，未指出服务/商品问题，也未要求平台介入",
    "contrast": {"text": "发错货了，退钱并且给我个说法", "label": "投诉",
                 "why": "指出了商品问题 + 要求平台介入"},
    "source": "pilot_r2_dispute",          # 来源：试标注R2的分歧样本
    "added_in": "guideline_v1.3",          # ⭐ 每条边界样例都要知道是哪版加的
}

def lint_guideline(defs: dict, boundaries: list):
    """指南体检：定义字数 vs 边界样例字数、类别对覆盖"""
    def_chars = sum(len(v) for v in defs.values())
    bd_chars = sum(len(b["text"]) + len(b["why"]) for b in boundaries)
    pairs = {tuple(sorted(b["pair"])) for b in boundaries}
    thin = [p for p in pairs if sum(1 for b in boundaries if tuple(sorted(b["pair"])) == p) < 5]
    return {"定义字数": def_chars, "边界样例字数": bd_chars,
            # ⭐ 低于 3 倍，说明指南还停在"定义阶段"
            "倍数": round(bd_chars / max(def_chars, 1), 2),
            "覆盖的类别对": len(pairs), "样例不足5条的类别对": thin}

print(json.dumps(lint_guideline({"投诉": "用户明确指出问题并要求平台介入"},
                                [BOUNDARY_SCHEMA]), ensure_ascii=False))

   R1  抽 100~200 条 → 3~5 人独立标 → 算一致性
        ↓
   分歧会：⭐ 不讨论"谁对"，只讨论"指南哪一句没说清"
        ↓
   改指南（新增边界样例 / 补排除项 / 拆类别 / 合并类别）
        ↓
   R2  ⚠️ 换一批新样本 再来一遍
        ↓
   R3  ...   直到收敛

   ① Kappa 相比上一轮提升 < 0.05
   ② 新增争议条目 < 3 条 / 轮

   ⭐ 只看 ① 会被"标注员记住了上一批答案"骗到
   ⭐ 只看 ② 会在类别本身太难时假收敛

from typing import Sequence

def pilot_converged(kappas: Sequence[float], new_disputes: Sequence[int],
                    k_gain: float = 0.05, dispute_max: int = 3):
    """试标注收敛判据：⭐ 两条必须同时满足"""
    if len(kappas) < 2:
        return False, "至少要两轮"
    gain = kappas[-1] - kappas[-2]
    ok = (gain < k_gain) and (new_disputes[-1] < dispute_max)
    return ok, {"最新Kappa": kappas[-1], "本轮提升": round(gain, 3),
                "新增争议": new_disputes[-1],
                # ⚠️ Kappa 还很低却"收敛"了 = 任务本身定义有问题，不是标注员问题
                "警告": "Kappa<0.6 却收敛，说明类别体系需要重做" if ok and kappas[-1] < 0.6 else ""}

print(pilot_converged([0.41, 0.63, 0.71], [37, 12, 3]))
# (False, {'最新Kappa': 0.71, '本轮提升': 0.08, '新增争议': 3, '警告': ''})
# ⭐ 争议条目已经降到 3 条，但提升还有 0.08 ≥ 0.05 —— 判定【未收敛】，该再来一轮 R4

   ① 分歧是【集中】在少数几对类别，还是【均匀】撒开？
      集中在 1~3 对 → 指南问题（那几对的定义重叠了）  ⭐
      均匀撒开     → 可能是任务太难 / 培训不足

   ② 多数标注员是不是【朝同一个方向】错？
      是 → 一定是指南问题（系统性偏移，大家都按同一种误读在标）
      否 → 才可能是个体问题

   ③ 换一批全新标注员重标，分歧模式一样吗？
      一样 → 100% 是指南问题  ⭐⭐  这是最硬的判据
      不一样 → 前一批人的培训或态度有问题

import pandas as pd

def annotator_health(df, ann="annotator", label="label", secs="seconds", gold="gold_label"):
    """按标注员拆开看：⭐ 总体质检指标会把个别问题平均掉"""
    out = []
    for a, g in df.groupby(ann):
        runs, cur, best = 1, g[label].iloc[0], 1          # 最长连续相同标签游程
        for v in g[label].iloc[1:]:
            runs = runs + 1 if v == cur else 1
            cur, best = v, max(best, runs)
        row = {"标注员": a, "条数": len(g),
               "中位耗时秒": round(float(g[secs].median()), 1),
               "秒杀比例(<2s)": round(float((g[secs] < 2).mean()), 3),
               "最长同标签游程": best}
        if gold in g.columns:                              # ⭐ catch trial 通过率
            m = g[gold].notna()
            row["检验题通过率"] = round(float((g.loc[m, label] == g.loc[m, gold]).mean()), 3) if m.any() else None
        out.append(row)
    return pd.DataFrame(out)

import math

def sample_size(defect_rate, conf=0.95):
    """⭐ 抽多少条才能以 conf 的把握至少发现一条缺陷率为 defect_rate 的错误"""
    return math.ceil(math.log(1 - conf) / math.log(1 - defect_rate))

def error_upper_bound(n, conf=0.95):
    """抽 n 条全对时，真实错误率的单侧上限（规则三的一般形式）"""
    return 1 - (1 - conf) ** (1 / n)

print(sample_size(0.05), sample_size(0.02), sample_size(0.01))   # 59 149 299
print(round(error_upper_bound(200) * 100, 2), "%")               # 1.49 %

   系统：客服工单自动分派模型
   体系：32 个意图，互斥单标签
   指南：4 页，只有标签定义和各 2 条例子，0 条边界样例
   流程：⚠️ 没有试标注，直接外包 8 人标 12 万条，3 周交付

   「投诉」   ：用户对服务或商品表达不满的工单
   「退款申请」：用户要求退回已支付款项的工单

   ⭐ 问题在于："我不想要了，退钱"        → 两条都不完全命中
                "发错货了，退钱并给个说法" → 两条都命中
   而指南里没有一个字说明这时候该怎么办。

   ① 没做试标注
      第一次计算标注一致性，是在事故发生【之后】的复盘会上
      💀 这个项目在花完 12 万条的钱之前，从来没量过一次一致性

   ② 验收只看"完成率"和"抽检准确率"，抽检准确率 96%
      但抽检的判定依据【也是那份有歧义的指南】
      质检员和标注员碰巧理解一致 → 判"对"
      💀 用同一把歪尺子量自己，量出来永远是直的  ⭐

   ③ 离线评测：意图=投诉 的 F1 = 0.88，很好看
      因为评测集和训练集【由同一批标注员、按同一份有歧义的指南】标注
      模型完美学会了这批人的随机习惯，评测集也按同样的随机习惯打分
      ⭐⭐ 评测集继承了同样的歧义，所以它永远测不出这个问题

   事后抽 500 条由 2 名资深标注员 + 1 名仲裁重标：
     「投诉 ↔ 退款申请」这一对的原始标注一致率只有 51%
     这两类合计占全部工单的 21%

   上线之后：
     真实投诉的线上召回   0.42   （离线 F1 是 0.88）
     投诉工单没进人工优先队列
     投诉平均首响时长     8 分钟  →  3.7 小时
     客诉升级（二次投诉 + 监管投诉）  月均 62 件  →  340 件

   直接成本：
     重标 2.6 万条                    18 万元
     3 人 × 2 周 重做指南 + 重训       23 万元
     ⭐ 合计 41 万元，上线延期 5 周

   guideline/
     v1.0.md      初版
     v1.1.md      + 投诉↔退款 8 条边界样例       影响：已标 0 条
     v1.2.md      「紧急」定义加入排除项          影响：已标 3.1 万条 ⚠️ 需重标 4,200 条
     v1.3.md      拆分「物流异常」为两类          影响：已标 12 万条 💀 需全量重标该类
     CHANGELOG.md 每次改动 + 受影响范围 + 是否重标