27. 案例研究（一）：客服 RAG 从 0 到上线的 90 天评估剧本

// rag-eval/types.ts —— 被测物与测试集的类型契约（无需联网）
// 评估瞄准的是"观测点"而不是裸文本：检索这一步必须显式暴露出来

export interface RagTrace {
  answer: string;              // 最终回答
  refused: boolean;            // 是否拒答（超纲问题）
  retrieved: string[];         // 检索到的文本块，按相似度降序
  retrievedIds: string[];      // 对应的知识库文档 id
  latencyMs: number;
  costUsd: number;             // 本次会话的 token 成本
}

export interface RagCase {
  id: string;
  question: string;
  expected: string;            // 参考答案要点（人工标注）
  goldenContextIds: string[];  // 标注"这道题该检索到哪些文档"
  category: "退款" | "物流" | "发票" | "账户" | "超纲";
  source: "public" | "human" | "reflow" | "synthetic"; // 4 来源，见第 24 章
  difficulty: "easy" | "medium" | "hard";
}

// 被测物：你的 RAG 系统必须以这个签名暴露出来
export type RagApp = (question: string) => Promise<RagTrace>;

// rag-eval/anchors.ts —— 30 条锚点的前 3 条示例（结构完整，可直接扩展）
import type { RagCase } from "./types.ts";

export const anchors: RagCase[] = [
  {
    id: "cs-001",
    question: "我想退我上周买的耳机",
    expected: "先询问订单号与购买渠道，再告知 7 天无理由退换流程",
    goldenContextIds: ["doc-refund-1", "doc-refund-2"],
    category: "退款",
    source: "human",
    difficulty: "easy",
  },
  {
    id: "cs-002",
    question: "耳机用了 5 天发现有问题能退吗？",
    expected: "在 7 天无理由期内，可走质量问题退货，需提供订单号",
    goldenContextIds: ["doc-refund-1"],
    category: "退款",
    source: "human",
    difficulty: "medium",
  },
  {
    id: "cs-003",
    question: "我的耳机是赠品，能退吗？",
    expected: "赠品不支持单独退款，需随主商品一起退回",
    goldenContextIds: ["doc-refund-3"],
    category: "退款",
    source: "human",
    difficulty: "hard",
  },
  // …… 共 30 条，覆盖退款/物流/发票/账户四类 + 2 条超纲拒答
];

// rag-eval/dedupe.ts —— 测试集入库前的归一化去重（本地运行，无需联网）
// 运行：npx tsx rag-eval/dedupe.ts data/cases.jsonl

import { readFileSync, writeFileSync } from "node:fs";

function normalize(q: string): string {
  return q
    .toLowerCase()
    .replace(/\s+/g, "")            // 去空白
    .replace(/[？?！!。，,.]/g, ""); // 去标点
}

const raw = readFileSync(process.argv[2] ?? "data/cases.jsonl", "utf-8")
  .trim().split("\n").map((l) => JSON.parse(l));

const seen = new Map<string, string>();
const kept: unknown[] = [];
let dropped = 0;

for (const c of raw) {
  const key = normalize(c.question);
  if (seen.has(key)) { dropped++; continue; }  // 归一化后相同 → 视为重复
  seen.set(key, c.id);
  kept.push(c);
}

writeFileSync("data/cases.deduped.jsonl", kept.map((c) => JSON.stringify(c)).join("\n"));
console.log(`kept=${kept.length} dropped=${dropped}`);
// 期望输出示例：kept=487 dropped=13

// rag-eval/metrics.ts —— 确定性指标：检索层与拒答（本地运行，无需联网）
import type { RagCase, RagTrace } from "./types.ts";

// 检索召回：金标文档命中的比例（用 goldenContextIds，不需要判官）
export function contextRecall(c: RagCase, t: RagTrace): number {
  if (c.goldenContextIds.length === 0) return 1;
  const hit = c.goldenContextIds.filter((id) => t.refused || t.retrievedIds.includes(id)).length;
  return hit / c.goldenContextIds.length;
}

// 检索精准：相关文档排名越靠前分越高（1/(rank+1) 的调和权重）
export function contextPrecision(c: RagCase, t: RagTrace): number {
  const ranks = c.goldenContextIds
    .map((id) => t.retrievedIds.indexOf(id))
    .filter((r) => r >= 0);
  if (ranks.length === 0) return 0;
  return ranks.reduce((s, r) => s + 1 / (r + 1), 0) / Math.max(c.goldenContextIds.length, t.retrievedIds.length);
}

// 拒答正确率：超纲题应当拒答，纲内题不应当拒答（确定性，0 LLM 成本）
export function rejectionAccuracy(cases: RagCase[], traces: Map<string, RagTrace>): number {
  const rows = cases.map((c) => {
    const t = traces.get(c.id);
    if (!t) return null;
    const shouldRefuse = c.category === "超纲";
    return t.refused === shouldRefuse;
  }).filter((r): r is boolean => r !== null);
  return rows.filter(Boolean).length / rows.length;
}

// rag-eval/judge.ts —— 语义指标：逐论断核验的 faithfulness（需联网 + API 费用）
// 运行前提：export OPENAI_API_KEY=sk-你的密钥；npx tsx rag-eval/judge.ts
import OpenAI from "openai";

if (!process.env.OPENAI_API_KEY) {
  throw new Error("请先设置环境变量 OPENAI_API_KEY");
}
const openai = new OpenAI(); // SDK 默认读取环境变量

// 判官 prompt 三要素（第 5 章）：rubric 显式、长度中立声明、结构化输出
const FAITHFUL_PROMPT = (answer: string, contexts: string[]) => `你是严格的审计员。判断下面的"回答"中每一条事实性论断是否被"检索内容"支持。
评分与回答长度、格式、语气无关，只看论断是否有出处。
只输出 JSON：{"supported": 数字, "total": 数字}

检索内容：
${contexts.join("\n---\n")}

回答：
${answer}`;

export async function faithfulness(answer: string, contexts: string[]): Promise<number> {
  const res = await openai.chat.completions.create({
    model: "gpt-4o-mini", // 便宜模型先筛；贴线样本升级强模型，见第 20 章 17.8
    temperature: 0,        // 评估必须可复现
    messages: [{ role: "user", content: FAITHFUL_PROMPT(answer, contexts) }],
  });
  try {
    const j = JSON.parse(res.choices[0].message.content ?? "{}");
    return j.total > 0 ? j.supported / j.total : 0;
  } catch {
    return 0; // 判官输出解析失败按 0 分计，并计入判官错误率（第 20 章 17.7.2）
  }
}

// rag-eval/calibrate.ts —— 判官一致率校准（需联网；50 条人工标注）
// 运行：npx tsx rag-eval/calibrate.ts data/anchor-50.jsonl
import { readFileSync } from "node:fs";

function wilson(p: number, n: number): [number, number] {
  const z = 1.96;
  const denom = 1 + (z * z) / n;
  const center = (p + (z * z) / (2 * n)) / denom;
  const half = (z * Math.sqrt((p * (1 - p)) / n + (z * z) / (4 * n * n))) / denom;
  return [center - half, center + half];
}

// gold: 人工 0/1 标注；judge: 判官对同批样本的 0/1 判定
const gold = readFileSync(process.argv[2], "utf-8").trim().split("\n").map(JSON.parse);
const judge = new Map(gold.map((g) => [g.id, g.judgeScore]));
const rows = gold.filter((g) => judge.has(g.id));
const agree = rows.filter((g) => judge.get(g.id) === g.human).length;
const [lo, hi] = wilson(agree / rows.length, rows.length);

console.log(`一致率=${(agree / rows.length).toFixed(3)} ci95=[${lo.toFixed(3)}, ${hi.toFixed(3)}] n=${rows.length}`);
console.log(lo >= 0.8 ? "→ 判官可上岗" : "→ 一致率区间下界低于 0.8，先修 rubric 再校准");
// 判官配置（模型/prompt 版本）变更后必须重跑本脚本——写进团队规范

L4 坏例（日均 ~20 条）
  → 周会聚类归并（相似问题合并成 1 个簇，打 category + difficulty 标签）
  → 人工确认"答案唯一且正确"（30 分钟/周）
  → 入 vNext 测试集 + 记录来源与日期

// rag-eval/canary.ts —— 灰度档位判定（需联网；跑 200 条固定灰度样本）
// 运行：npx tsx rag-eval/canary.ts
interface CanaryVerdict { promote: boolean; reasons: string[]; }

export function judgeCanary(
  treatment: { dislikeRate: number; p95Ms: number; faithfulness: number },
  control:   { dislikeRate: number; p95Ms: number },
): CanaryVerdict {
  const reasons: string[] = [];
  // 每个条件独立记录，报告里能看清"挂在哪一条"
  if (treatment.dislikeRate > control.dislikeRate * 1.5)
    reasons.push(`差评率 ${treatment.dislikeRate.toFixed(3)} 超过基线 1.5 倍`);
  if (treatment.p95Ms > control.p95Ms * 1.5 || treatment.p95Ms > 3000)
    reasons.push(`P95 延迟 ${treatment.p95Ms}ms 超预算`);
  if (treatment.faithfulness < 0.95)
    reasons.push(`在线 faithfulness ${treatment.faithfulness.toFixed(3)} 低于阈值 0.95`);
  return { promote: reasons.length === 0, reasons };
}