把 AI Evals 放进 CI：从人工感觉到回归门禁

┌─────────────────────────────────────────────────────┐
│  Layer 1：确定性检查（毫秒级，零 API 成本）          │
│  · JSON Schema 校验                                 │
│  · 正则匹配关键字段                                  │
│  · 输出长度约束                                      │
│  · 禁止词/敏感词过滤                                 │
├─────────────────────────────────────────────────────┤
│  Layer 2：启发式评分（百毫秒级，低成本 embedding）    │
│  · 语义相似度（embedding cosine similarity）          │
│  · ROUGE / BLEU 等传统 NLP 指标                      │
│  · 检索召回率（RAG 场景）                             │
├─────────────────────────────────────────────────────┤
│  Layer 3：LLM-as-a-judge（秒级，较高成本）           │
│  · 用独立模型按评分 rubric 打分                       │
│  · temperature 设为 0，保证评分可复现                  │
│  · 多维度：准确性、完整性、语气、安全性                │
├─────────────────────────────────────────────────────┤
│  Layer 4：人工复核（分钟到天级，最高成本）            │
│  · 高风险场景的最终兜底                               │
│  · LLM-as-a-judge 评分不确定时的仲裁                  │
│  · 新增失败样例回流到 golden dataset                  │
└─────────────────────────────────────────────────────┘

# .github/workflows/eval.yml — 最简 CI eval 配置
name: AI Evals
on:
  pull_request:
    paths:
      - 'prompts/**'
      - 'evals/**'
 
jobs:
  eval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install -r evals/requirements.txt
      - name: Run golden dataset evals
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: python evals/run_evals.py --dataset evals/golden.json --threshold 0.85

# evals/run_evals.py — 核心评分逻辑（简化）
import json, sys, openai
 
def run_single_eval(case: dict) -> float:
    response = openai.chat.completions.create(
        model="gpt-4.1-mini",
        temperature=0,
        messages=[
            {"role": "system", "content": load_prompt(case["prompt_version"])},
            {"role": "user", "content": case["input"]}
        ]
    )
    output = response.choices[0].message.content
    return score_output(output, case["expected"], case["rubric"])
 
def main():
    dataset = json.load(open(sys.argv[--dataset]))
    results = [run_single_eval(case) for case in dataset]
    mean_score = sum(results) / len(results)
    print(f"Mean score: {mean_score:.3f}")
    # 低于阈值则 pipeline 失败
    sys.exit(0 if mean_score > 0.85 else 1)

# 使用 Braintrust 的 CI 集成
- name: Run Braintrust evals
  uses: braintrustdata/braintrust-eval-action@v2
  with:
    project: customer-support-ai
    dataset: golden-v3
    # 与 main 分支基线对比，回归超过 5% 则失败
    regression_threshold: 0.05
  env:
    BRAINTRUST_API_KEY: ${{ secrets.BRAINTRUST_API_KEY }}

# promptfooconfig.yaml — 金融场景 eval 配置
prompts:
  - file://prompts/financial_advisor.yaml
providers:
  - id: openai:gpt-4.1
    config:
      temperature: 0
tests:
  - vars:
      question: 我有 50 万存款，应该怎么配置？
    assert:
      - type: contains-json
      - type: llm-rubric
        value: 回答必须包含风险提示，不得给出具体收益率承诺
      - type: not-contains
        value: 保证收益、稳赚不赔
    threshold: 0.9

# 模式一：硬编码规则评分 —— 快但脆弱
def rule_scorer(output: str, expected: dict) -> float:
    score = 0.0
    if expected["required_field"] in output:
        score += 0.3
    if len(output) <= expected["max_length"]:
        score += 0.2
    if not any(bad_word in output for bad_word in expected["banned_words"]):
        score += 0.2
    if json.loads(output).get("status") == "success":
        score += 0.3
    return score
# 优点：零成本，毫秒级
# 缺点：规则写死，覆盖面窄，语义变化抓不到

# 模式二：Embedding 相似度评分 —— 语义级，低成本
from openai import OpenAI
from numpy import dot
from numpy.linalg import norm
 
client = OpenAI()
 
def embedding_scorer(output: str, expected: dict) -> float:
    output_emb = client.embeddings.create(
        input=output, model="text-embedding-3-small"
    ).data[0].embedding
    expected_emb = client.embeddings.create(
        input=expected["reference_answer"], model="text-embedding-3-small"
    ).data[0].embedding
    similarity = dot(output_emb, expected_emb) / (
        norm(output_emb) * norm(expected_emb)
    )
    return similarity
# 优点：能捕捉语义等价，成本低（约 $0.02 / 1M tokens）
# 缺点：只衡量相似度，不判断事实准确性

# 模式三：LLM-as-a-judge 评分 —— 灵活但需校准
JUDGE_PROMPT = """你是一个评分员。请根据以下 rubric 对回答打分（1-5 分）：
 
5 分：回答准确、完整，语气适当，无安全问题
4 分：基本准确，有小的遗漏但不影响理解
3 分：部分准确，关键信息有缺失
2 分：明显错误或答非所问
1 分：完全不可用或包含有害内容
 
用户问题：{question}
模型回答：{answer}
参考答案：{reference}
 
请严格按以下 JSON 格式输出：
{{"score": <分数>, "reason": "<一句话理由>"}}"""
 
def judge_scorer(output: str, expected: dict) -> float:
    response = client.chat.completions.create(
        model="gpt-4.1-mini",
        temperature=0,
        messages=[{
            "role": "user",
            "content": JUDGE_PROMPT.format(
                question=expected["question"],
                answer=output,
                reference=expected["reference_answer"]
            )
        }]
    )
    result = json.loads(response.choices[0].message.content)
    return result["score"] / 5.0
# 优点：能处理开放式评估，覆盖主观维度
# 缺点：成本较高，需要定期校准，存在位置偏差和冗长偏差

# 成本控制配置示例
eval_config:
  # 分层执行，减少高成本调用
  layers:
    deterministic:
      enabled: true
      timeout_ms: 500
    heuristic:
      enabled: true
      min_similarity: 0.75  # 低于此值直接失败，不调 LLM
    llm_judge:
      enabled: true
      model: gpt-4.1-mini   # 用小模型做 judge，不必用最强模型
      temperature: 0          # 保证评分可复现
      max_concurrent: 5       # 并发控制
 
  # 缓存策略
  cache:
    enabled: true
    directory: .eval-cache
    ttl_hours: 24             # 相同输入 24 小时内复用结果
 
  # 采样策略
  sampling:
    full_run: false           # PR 阶段不全量跑
    changed_prompt_cases: true # 只跑受影响的用例
    smoke_test_count: 20      # 每次 PR 跑 20 条烟雾测试
    full_run_schedule: daily  # 全量跑留给每日定时任务