✅ 评估与测试

class EvaluatorCallbackHandler(BaseTracer):
    """运行时评估的桥：把评估器挂成 tracer。

    每个 run 结束时自动用挂载的 evaluators 评估。
    _persist_run (:205) 在 run 完成后用线程池跑 evaluators。
    max_concurrency (:93)：并发评估数。
    """

# 本质是"追踪即评估"：
# - 普通 tracer 只记录 run（上报 LangSmith）
# - 这个 tracer 额外对 run 做【评估打分】
# - 评估结果也上报，形成"执行+评估"的完整闭环

# langchain_tests 包：每个集成继承对应基类即获一致性测试
# base.py:4 BaseStandardTests —— 根基类

# 按类型分的标准测试：
# chat_models.py:194 ChatModelIntegrationTests
#   - test_invoke (:767)
#   - test_stream (:822)
#   - test_stream_events_v3 (:937)
#   - test_batch (:1130)
#   ... 覆盖所有标准行为

# unit_tests/：单元测试（不需真实 API）
# _langsmith_plugin.py：pytest 插件，自动注入 tracing tags

# 用法：你的 ChatModel 集成继承 ChatModelIntegrationTests
class TestMyChatModel(ChatModelIntegrationTests):
    @pytest.fixture
    def chat_model_class(self):
        return MyChatModel
    # 自动获得几十个标准测试，保证你的实现符合规范

# pip install langchain langchain-openai pydantic
from langchain_openai import ChatOpenAI
from pydantic import BaseModel, Field
from typing import Literal

judge_model = ChatOpenAI(model="gpt-4o", temperature=0)  # 评判用更强模型，温度0保证稳定

# ============ 定义三个评估维度的打分 schema ============
class FaithfulnessScore(BaseModel):
    """忠实度：答案是否完全基于上下文（有无幻觉）。"""
    score: Literal[0, 1] = Field(description="1=忠实 0=有幻觉")
    reasoning: str = Field(description="判断理由")

class RelevanceScore(BaseModel):
    """相关性：答案是否回答了问题。"""
    score: Literal[0, 1] = Field(description="1=相关 0=跑题")
    reasoning: str

class CorrectnessScore(BaseModel):
    """正确性：答案是否事实正确（对照标准答案）。"""
    score: Literal[0, 1] = Field(description="1=正确 0=错误")
    reasoning: str

# ============ 评估函数 ============
def evaluate_faithfulness(answer: str, context: str) -> FaithfulnessScore:
    """评估忠实度：答案的每个声明是否都能在 context 找到支持。"""
    return judge_model.with_structured_output(FaithfulnessScore).invoke(
        f"上下文：{context}\n答案：{answer}\n"
        f"答案中的每个陈述是否都能从上下文推导出？只回 JSON。"
    )

def evaluate_relevance(answer: str, question: str) -> RelevanceScore:
    return judge_model.with_structured_output(RelevanceScore).invoke(
        f"问题：{question}\n答案：{answer}\n答案是否切题回答了问题？"
    )

def evaluate_correctness(answer: str, ground_truth: str) -> CorrectnessScore:
    return judge_model.with_structured_output(CorrectnessScore).invoke(
        f"标准答案：{ground_truth}\n待评答案：{answer}\n两者意思是否一致？"
    )

# ============ 评估数据集（离线评估）============
eval_dataset = [
    {
        "question": "LCEL 是什么？",
        "context": "LCEL 是 LangChain 的表达式语言，用 | 组合组件...",
        "ground_truth": "LCEL 是 LangChain 的管道组合语法",
    },
    # ... 更多评估样本
]

# ============ 运行评估 ============
def run_evaluation(agent, dataset):
    results = []
    for item in dataset:
        answer = agent.invoke(item["question"])  # 被评估 Agent 的输出
        results.append({
            "faithfulness": evaluate_faithfulness(answer, item["context"]).score,
            "relevance": evaluate_relevance(answer, item["question"]).score,
            "correctness": evaluate_correctness(answer, item["ground_truth"]).score,
        })

    # 汇总
    n = len(results)
    print(f"=== 评估报告（{n} 个样本）===")
    print(f"忠实度: {sum(r['faithfulness'] for r in results)/n:.1%}")
    print(f"相关性: {sum(r['relevance'] for r in results)/n:.1%}")
    print(f"正确性: {sum(r['correctness'] for r in results)/n:.1%}")

# 改 prompt / 换模型 / 调 RAG 策略后，重跑评估对比分数
# 这就是 Agent 的"回归测试"