1. 项目概述：为什么“ Criteria Evaluator”不是又一个花架子，而是你AI产品上线前的最后一道安全阀

你有没有遇到过这种场景：模型在测试集上准确率98%，一放到真实用户对话里，就冒出一句“根据《星际迷航》第7季第3集的设定，人类早在2154年就已实现反重力飞行”，还配了个微笑表情。用户截图发到社交媒体，标题是《贵司AI连地心引力都忘了？》。这不是段子，是我上个月帮一家教育科技公司做模型验收时亲眼所见的真实事故。当时他们用的是标准的BLEU和ROUGE打分，分数漂亮得像PPT里的饼图，但完全拦不住这种“逻辑自洽的胡说八道”。直到我们把LangChain的Criteria Evaluator加进去，用一条自定义的 factual_accuracy 规则跑了一遍——三分钟内，这条“星际迷航”回答就被标为0分，并附带了清晰的归因：“引用虚构作品作为科学依据，与权威生物学教材《人体解剖学》第4章结论冲突”。这才是真正能救命的评估。

所谓Criteria Evaluator，核心就一句话： 让另一个更可靠的模型（比如GPT-4o或Claude）来当考官，按你亲手写的评分标准，给你的AI答案打分 。它不是在问“这个答案对不对”，而是在问“这个答案在‘帮助用户理解人体结构’这件事上，做到了几分？”——前者是学术考试，后者是产品交付。我见过太多团队卡在“模型能力边界模糊”这道坎上：产品经理说“要更专业”，工程师说“模型已经调到最优”，最后上线后客服电话被打爆。问题从来不在模型本身，而在我们缺乏一套可量化、可解释、可定制的“产品级质量尺子”。Criteria Evaluator就是这把尺子。它不关心模型用了多少参数，只关心用户拿到的答案是否解决了他的问题。你定的每一条标准，比如 helpfulness 、 conciseness 、 insensitivity ，本质上都是你对“好产品”的定义白皮书。当你的客户支持机器人被要求“必须用不超过3句话解释清楚医保报销流程”，那 conciseness 就不是可选项，而是硬性SLA。这篇文章，就是带你亲手把这把尺子从LangChain的代码库里拧出来，装进你的CI/CD流水线，让它在每次模型更新前自动喊停——不是因为分数低，而是因为低分背后暴露出的，是你还没想清楚的产品逻辑。

2. 核心设计思路：为什么不用人工评测？为什么不用通用指标？为什么必须自己写标准？

2.1 人工评测的三大死穴，以及它为何注定无法规模化

很多人第一反应是：“找几个实习生看看答案就行，何必搞这么复杂？”我完全理解。五年前我接手的第一个AI项目，也是这么干的。我们招了6个大学生，每人每天看200条问答，按“好/中/差”三级打分。结果呢？两周后数据组长拿着统计表来找我，脸色发青：“老师，张三和李四对同一条‘如何缓解偏头痛’的回答，评分一致率只有63%。王五昨天说‘提到布洛芬就算合格’，今天又说‘必须说明禁忌症才算及格’。”这不是人不认真，而是人类判断天然带有语境依赖性。当一条回答说“可以试试热敷”，实习生A想到的是“这太笼统”，实习生B想到的是“这比乱吃药安全多了”。这种分歧，在涉及 helpfulness 或 clarity 这类主观性强的标准时，会指数级放大。

更致命的是成本不可控。假设你每天产生5万条用户对话，按行业通行的抽样率5%计算，就是2500条需要人工审阅。6个实习生每人每天极限处理200条，需要2天才能跑完。而你的模型可能每小时都在迭代。这意味着你永远在追着模型的尾巴跑，永远不知道最新版本在真实场景里到底表现如何。我后来算了一笔账：在我们那个教育项目里，人工评测的单条成本是$0.83（含培训、质检、管理），一年下来光评测就烧掉$150万。这笔钱如果投在提升模型本身，效果微乎其微；但如果用来构建自动化评估体系，它就成了持续产出价值的资产。Criteria Evaluator的价值，首先就体现在这里：它把一次性的、高成本的人力投入，转化成了可复用的、零边际成本的代码资产。你写一次 relevance 的判定逻辑，它就能在接下来的三年里，每秒处理上千次评估请求。

2.2 BLEU/ROUGE这些“学术明星”，为何在产品战场上集体失语？

再来看技术圈常提的BLEU、ROUGE、METEOR这些指标。它们在论文里光芒万丈，但在我的实战经验里，它们更像是“实验室里的精密天平”——在严格控制变量的环境下，测得极准；一旦放到真实世界的混沌环境里，立刻失灵。BLEU的核心是n-gram重叠率。一条回答说“太阳是恒星，会发光发热”，参考答案是“太阳是一颗恒星，能自行发光发热”，BLEU得分可能高达0.95。但如果你的用户是个小学生，他真正需要的是“太阳为什么不像月亮那样自己不发光”，这条高分答案却完全没碰触到核心困惑点。ROUGE更甚，它连语义都不管，只数词频。我见过最离谱的一次：模型把“苹果公司2023年Q4营收为1196亿美元”错答成“苹果公司2023年Q4营收为1196亿人民币”，ROUGE-L得分依然超过0.9——因为数字和公司名都匹配了，单位这个决定生死的细节，在词频统计里根本不存在。

这些指标失败的根本原因，在于它们预设了一个错误的前提： 答案的质量，等同于它与某个固定参考答案的文本相似度 。但现实世界里，一个好答案可以有无数种正确表达。用户问“怎么修漏水的水龙头”，最佳答案可能是图文教程、短视频链接，甚至是一句“先关总阀，再用扳手拧紧阀芯”。如果评测系统只认准你提供的那篇PDF文档里的文字，它就会把所有创新形式都判为“错误”。Criteria Evaluator彻底抛弃了这个前提。它不比较文本，而是比较意图。当你定义 correctness 标准时，你告诉评判模型：“请判断这个回答是否在科学事实上无误，是否符合主流医学指南”，而不是“请数它和参考答案有多少字一样”。这就像从用游标卡尺量零件，升级到了用三坐标测量仪扫描整个工件的三维形貌——前者只能告诉你尺寸，后者能告诉你功能是否达标。

2.3 自定义标准：不是“我能写什么”，而是“我的用户需要什么”

现在回到最关键的问题：为什么必须自己写标准？因为没有任何一套通用标准，能替代你对自身业务的理解。我服务过一家法律科技公司，他们的AI要帮律师起草合同条款。初期他们直接套用LangChain内置的 correctness ，结果发现大量“高分”回答被律师否决。深入分析才发现， correctness 默认只检查事实性，而法律条款的“正确”意味着：1）必须援引最新版《民法典》第XXX条；2）措辞必须与最高人民法院指导案例中的表述保持一致；3）不能出现任何可能被认定为“格式条款”的模糊用语。这三条，没有一条在通用标准里。他们最终写的自定义标准长这样：

criteria = {
    "legal_compliance": "Does the clause explicitly cite the current, valid version of the PRC Civil Code (e.g., 'Article 502 of the Civil Code of the People's Republic of China, effective as of January 1, 2021')? Does it avoid any language that could be construed as an unfair standard term under Article 496?",
    "precedent_alignment": "Does the phrasing of key obligations (e.g., 'shall', 'may', 'must') match the exact wording used in at least one published Supreme People's Court Guiding Case on similar contractual disputes?"
}

看到区别了吗？通用标准是“教科书答案”，自定义标准是“行业操作手册”。你在写 insensitivity 时，如果做的是面向青少年的教育产品，重点可能是避免使用“笨”“傻”这类贬义词；但如果你做的是医疗问诊助手， insensitivity 就必须包含对慢性病患者、残障人士的特定话术规范，比如禁止使用“正常人”这样的对比性表述。我建议你拿出一张纸，写下你产品的三个最核心用户场景，然后针对每个场景，问自己一个问题：“如果这个回答在这里翻车了，用户最可能投诉哪一点？”那个点，就是你第一个该写的自定义标准。它不需要多炫酷，哪怕只是 {"no_jargon": "Does the response avoid all technical terms without immediate, plain-language explanation?"} ，也比套用一个万能标准强一百倍。

3. 实操细节解析：从零搭建可落地的评估流水线

3.1 环境准备与依赖安装：避开那些让你调试一整天的坑

开始编码前，先解决环境这个“隐形杀手”。LangChain生态的版本碎片化是出了名的，我踩过的最大坑是 langchain-classic 和 langchain-core 的版本冲突。官方文档有时会推荐 pip install langchain ，但实际项目中，你几乎一定会需要 langchain-classic 里的高级评估器。我的血泪经验是： 永远用 requirements.txt 锁定精确版本，而不是用 -U 强制升级 。以下是我在生产环境中验证过的最小可行配置：

# 推荐的requirements.txt内容
langchain==0.3.7
langchain-core==0.3.22
langchain-text-splitters==0.3.15
langsmith==0.1.122
langchain-openai==0.2.12
pydantic==2.9.2
python-dotenv==1.0.1

特别注意 pydantic 版本。LangChain 0.3.x系列深度依赖Pydantic v2，如果你的环境里混着v1（很多老项目都有）， load_evaluator 会直接抛出 ValidationError ，错误信息却只显示“model validation failed”，根本看不出是版本问题。解决方法很简单： pip uninstall pydantic -y && pip install pydantic==2.9.2 。另外， .env 文件的加载位置极易出错。不要把 .env 放在项目根目录就以为万事大吉。LangChain的 load_dotenv() 默认只在当前工作目录找，而Jupyter Notebook的当前工作目录往往是 /home/user/ ，不是你的项目文件夹。我的做法是：在Notebook第一行显式指定路径：

from pathlib import Path
from dotenv import load_dotenv
# 显式指向项目根目录下的.env文件
load_dotenv(Path(__file__).parent.parent / ".env")

这样无论Notebook在哪打开，都能正确加载。还有个小技巧：在 .env 里加上 LANGCHAIN_TRACING_V2=true ，这样所有评估过程都会自动记录到LangSmith，方便你后续回溯每一条评分的推理链——这在调试自定义标准时是救命功能。

3.2 基础评估器：从 labeled_criteria 到 unlabeled_criteria 的实战选择

LangChain提供了两种基础评估模式，选错一种，后面全白忙。 labeled_criteria 需要你提供 reference （参考答案），而 unlabeled_criteria 则完全不需要。很多人一上来就选 labeled_criteria ，觉得“有标准答案才严谨”。但现实是，90%的业务场景里，你根本拿不到可靠的 reference 。比如客服对话，用户问“我的订单为什么还没发货？”，理想答案是什么？是查物流状态？是道歉并承诺时效？还是提供补偿方案？这取决于你的SOP，而不是某个固定文本。这时候， unlabeled_criteria 才是真·生产力工具。

我们来看一个真实案例。某电商公司的退货政策问答机器人，需要评估模型对“七天无理由退货”条款的解释是否合规。用 labeled_criteria 的话，你得为每一条用户提问（“手机屏幕碎了能退吗？”、“衣服洗过一次还能退吗？”）都准备一个标准答案，这工程量堪比重写一本《消费者权益保护法》解读。而用 unlabeled_criteria ，你只需定义一条标准：

evaluator = load_evaluator(
    "unlabeled_criteria",
    criteria={
        "policy_compliance": "Does the response explicitly state that 'seven-day no-reason return' applies only to undamaged, unworn, and unaltered items with original packaging and tags? Does it cite the company's official policy page URL?"
    }
)

然后直接喂给它模型的原始输出：

result = evaluator.evaluate_strings(
    prediction="只要没拆封，七天内都能退！",
    input="衣服洗过一次还能退吗？"
)
# result['score'] 将是0，因为回答忽略了'undamaged, unworn'的关键限制

看到区别了吗？ labeled_criteria 是在考“学生默写课本”， unlabeled_criteria 是在考“学生应用知识解决问题”。后者更贴近产品需求。当然， labeled_criteria 并非无用武之地。它最适合的场景是：1）有明确、唯一、客观的正确答案（如数学计算、代码执行结果）；2）你需要做A/B测试，对比两个模型在同一组标准答案上的表现差异。比如我们之前那个“2+2=4”的例子， labeled_criteria 就非常精准。但记住一个铁律： 当你的业务逻辑无法被压缩成一条静态文本时，立刻转向 unlabeled_criteria 。

3.3 自定义评估器：用 @run_evaluator 写出你的“领域裁判”

内置标准再丰富，也覆盖不了你的业务毛细血管。这时， @run_evaluator 装饰器就是你的终极武器。它的强大之处在于：你写的不是冷冰冰的规则，而是一个活的、能理解上下文的“裁判”。让我用一个高频痛点来演示： 检测AI回答中是否隐含了未声明的假设 。很多模型在回答“如何治疗感冒”时，会默认用户有医保、能去三甲医院，却从不说明。这在医疗场景里是重大风险。

下面这个自定义评估器，会揪出所有“偷偷预设了用户条件”的回答：

from langsmith.evaluation import EvaluationResult, run_evaluator
import re

@run_evaluator
def detect_hidden_assumptions(run) -> EvaluationResult:
    """
    检查回答是否隐含了未声明的用户前提条件
    例如："去三甲医院挂呼吸科专家号" 隐含了 用户有医保、能预约、有交通能力
    """
    # 提取模型生成的文本
    generated_text = str(run.outputs.get("result", "") if hasattr(run, 'outputs') else "")
    
    # 定义高风险假设关键词模式（需根据你的业务补充）
    assumption_patterns = [
        r"去.*?医院",           # 隐含：用户能出行、有支付能力
        r"挂.*?专家号",         # 隐含：用户会线上预约、有就诊资格
        r"服用.*?处方药",       # 隐含：用户有医生处方、能购药
        r"咨询.*?律师",         # 隐含：用户能负担律师费、有诉讼意愿
    ]
    
    found_assumptions = []
    for pattern in assumption_patterns:
        matches = re.findall(pattern, generated_text, re.IGNORECASE)
        if matches:
            found_assumptions.extend(matches)
    
    if found_assumptions:
        # 扣分并给出具体证据
        score = 0
        comment = f"Detected hidden assumptions: {', '.join(found_assumptions)}. "
        comment += "The response assumes user has access to healthcare resources without stating prerequisites."
    else:
        score = 1
        comment = "No hidden assumptions detected. Response states all necessary prerequisites or uses conditional language (e.g., 'if you have access to...')."
    
    return EvaluationResult(key="hidden_assumptions", score=score, comment=comment)

关键点在于 run 对象。它不只是一个字符串，而是包含了完整的调用上下文： run.inputs （用户原始问题）、 run.outputs （模型回答）、 run.run_type （是llm调用还是chain调用）。你可以用它做更聪明的判断。比如，当用户问的是“我失业了怎么办”，而回答里出现了“申请失业金”，这个动作本身没问题；但如果回答里紧接着说“带上身份证和离职证明去社保局”，这就隐含了“用户知道社保局地址且能亲自前往”的假设——而一个刚失业、可能情绪低落的用户，最需要的其实是“线上办理入口链接”或“代办服务电话”。这个评估器能捕捉到这种细微的、关乎用户体验的缺陷，而这正是通用标准永远无法触及的深度。

4. 完整实操流程：从数据准备到LangSmith集成的端到端复现

4.1 数据集构建：为什么“存在主义问题”是绝佳的测试样本

在示例代码里，作者用了两个看似荒诞的问题：“Why people don't have 3 legs?” 和 “Why people are not flying?”。初看觉得是玩笑，实则是精妙的设计。这类“存在主义问题”之所以是黄金测试集，是因为它们天然具备三个评估维度：1） 事实性 （人类确实没有三腿，这是生物学事实）；2） 逻辑性 （回答必须基于进化论、生物力学等原理，不能编造）；3） 安全性 （不能引申出“所以人类是失败品”这类有害结论）。它们像一块试金石，能同时照出模型在 correctness 、 coherence 、 harmfulness 上的短板。

构建你自己的测试集，我建议采用“三层漏斗法”：

• 顶层（10%）：边界案例 ——就是这类存在主义问题，用于压力测试模型的知识边界和价值观底线。
• 中层（70%）：典型业务流 ——覆盖你产品80%的用户请求。比如电商是“查物流”“退换货”“优惠券使用”，教育是“解方程”“写作文提纲”“历史事件分析”。每类至少准备20个变体，确保覆盖不同问法（“快递到哪了？” vs “我的包裹还在路上吗？”）。
• 底层（20%）：对抗样本 ——专门设计来“骗”模型的恶意输入。比如在客服场景，输入“如果我威胁要起诉你们，你们会赔多少钱？”，一个健康的模型应该拒绝回答并提供合规渠道，而不是计算赔偿金额。这部分数据最难收集，但价值最高，因为它直接关系到你的法律风险。

数据格式上，LangSmith要求 inputs 和 outputs 严格对应。 inputs 必须是字典，键名要和你的chain的输入参数名一致。比如你的chain定义是 def my_chain(question: str) -> str: ，那么 inputs 就必须是 [{"question": "Why..."}] 。 outputs 则必须是字典列表，且键名要和chain的返回值结构一致。示例中 outputs = [{"result": llm_test.invoke(...)}] 是正确的，因为 llm_test.invoke() 返回的是 AIMessage 对象，而 {"result": ...} 将其包装成字典。如果这里写成 [llm_test.invoke(...)] ，LangSmith会直接报错。这个细节，我见过至少7个团队卡在这里超过半天。

4.2 LangSmith集成：不只是看分数，更要读懂“裁判的思考过程”

LangSmith不是简单的分数看板，它是你的评估“黑匣子”。当你运行 run_on_dataset 后，得到的不是一个数字，而是一份完整的“裁判报告”。以 relevance 评分为例，LangSmith不仅告诉你 score=0 ，还会在 comment 字段里展示评判模型的完整推理链：

“The criterion is asking if the submission is referring to a real quote from the text. In this case, the text is the input question 'Why people don't have 3 legs?' and the submission is the AI's response explaining why humans have two legs instead of three. The AI's response does not quote the input text directly, but it does address the question asked in the input text. However, the criterion specifically asks if the submission is referring to a real quote from the text, not whether it addresses the question or topic of the text. Therefore, the submission does not meet the criterion because it does not refer to a real quote from the text.”

这段话的价值，远超一个0分。它暴露了你定义 relevance 标准时的歧义：你是想测“是否回答了问题”，还是“是否复述了问题”？如果是前者，这个标准就错了，应该重写为 {"relevance": "Does the response directly address the core intent of the input question, regardless of verbatim repetition?"} 。LangSmith的 comment 字段，就是帮你校准产品定义的镜子。我建议你养成习惯：每次看到一个意外的低分，第一件事不是改模型，而是点开LangSmith里的 comment ，逐字阅读评判模型的推理。90%的情况下，问题出在你的标准定义不够清晰，而不是模型能力不足。

在LangSmith UI里，还有一个隐藏宝藏： Traces 标签页。这里能看到每一次评估调用的完整链路，包括评判模型（judge LLM）的输入提示词（prompt）、它生成的中间思考（reasoning）、以及最终输出。当你发现某个自定义标准总是误判时，就到这里去看评判模型到底“看到”了什么。比如，你定义了一个 tone_consistency 标准，要求回答保持中立客观，但评判模型总给科普类回答打低分。点开trace你会发现，评判模型的prompt里有一句“Assume the user is a child”，导致它把所有专业术语都判为“不友好”。这时你就知道，问题不在你的标准，而在评判模型的上下文设定。解决方案很简单：在 RunEvalConfig 里，通过 evaluator_kwargs 参数，为这个特定评判器注入更精准的上下文：

RunEvalConfig.Criteria(
    criteria={"tone_consistency": "..."},
    evaluator_kwargs={"system_prompt": "You are evaluating a response for adult learners with basic science literacy. Ignore childish simplification."}
)

这就是LangSmith赋予你的超能力：它把原本黑盒的“模型打分”过程，变成了可审计、可调试、可优化的白盒工程。

4.3 多维度评估配置：如何组合出属于你的“质量仪表盘”

示例代码里， eval_config 一口气配置了十几个评估器，从 CRITERIA 到 CONTEXT_QA 再到自定义的 valuation 。这种“大杂烩”式配置，新手容易陷入两个误区：一是以为越多越好，二是不知道如何解读冲突结果。比如， correctness 给了1分（正确）， relevance 却给了0分（不相关），这看起来矛盾。其实不然—— correctness 评判的是内容本身是否科学， relevance 评判的是它是否紧扣问题。一个回答可以“科学正确”（讲清了人类双足进化的所有原理），但“完全不相关”（用户只问“我的快递到哪了”）。

构建你的“质量仪表盘”，我推荐“核心+扩展”策略：

• 核心维度（必选，3-5个） ：直接对应你的产品SLA。比如客服机器人： helpfulness （必须解决用户问题）、 safety （零有害内容）、 compliance （遵守所有法规条款）。这三个维度，任何一个低于0.9，就触发阻断机制，禁止上线。
• 扩展维度（按需，2-3个） ：用于长期优化。比如 conciseness （响应长度）、 engagement （是否主动追问澄清）、 brand_voice （是否符合公司文案风格）。这些不阻断发布，但会进入周报，驱动模型迭代。

配置时，务必利用LangChain的 weight 参数。不要让所有维度平权。在医疗场景， safety 的权重必须是 conciseness 的10倍。配置示例如下：

eval_config = RunEvalConfig(
    evaluators=[
        # 核心维度：高权重
        RunEvalConfig.Criteria(criteria=Criteria.SAFETY, weight=10),
        RunEvalConfig.Criteria(criteria=Criteria.CORRECTNESS, weight=8),
        # 扩展维度：低权重
        RunEvalConfig.Criteria(criteria=Criteria.CONCISENESS, weight=1),
        RunEvalConfig.Criteria(criteria=Criteria.BRAND_VOICE, weight=2),
    ],
    custom_evaluators=[detect_hidden_assumptions],  # 你的专属裁判
)

LangSmith最终会给你一个加权总分，但更重要的是，它会为每个维度单独生成图表。你会清晰地看到： safety 稳定在0.99， conciseness 在0.72徘徊——这立刻告诉你，优化重点该放在哪里。这种数据驱动的决策，比拍脑袋定KPI靠谱得多。

5. 常见问题与排查技巧实录：那些官方文档不会告诉你的真相

5.1 “Score=0但Comment是空的”：LangSmith的静默失败陷阱

这是最让人抓狂的问题。你兴冲冲跑完评估，发现几条关键样本的 score 是0，但 comment 字段却是空的（ None ）。日志里也没有报错，仿佛模型默默放弃了思考。别急，这99%是评判模型（judge LLM）的 max_tokens 设置过小导致的。LangChain的评判器默认用 gpt-4o-mini ，它的 max_tokens 上限是16384，但默认配置往往只给1024。当你的标准描述很长（比如 valuation 标准有200字），或者模型回答很详细（比如那个“五点解释人类双腿”的回答），评判模型的输出就会被无情截断，LangSmith收不到完整结果，就记为 None 。

排查步骤 ：

1. 在LangSmith UI的 Traces 里，找到那个 score=0 的评估记录；
2. 展开 Outputs ，看 raw_output 字段。如果它显示 {"error": "output truncated"} 或类似字样，就是它了；
3. 解决方案：在 ChatOpenAI 初始化时，显式增大 max_tokens ：

eval_llm = ChatOpenAI(
    model="gpt-4o-mini", 
    temperature=0,
    max_tokens=4096  # 关键！从默认1024提高到4096
)

提示： max_tokens 不是越大越好。过大的值会显著拖慢评估速度，增加API成本。我的经验是：先设为2048，如果仍有截断，再升到4096。永远在LangSmith的 Traces 里验证输出完整性。

5.2 “Reference答案被忽略”： labeled_criteria 的输入格式雷区

用 labeled_criteria 时，你提供了 reference="4" ，但评判模型却无视它，只盯着 prediction 和 input 打分。这通常是因为 reference 的类型错了。LangChain的 labeled_criteria 期望 reference 是一个 字符串 ，而不是数字或其它类型。如果你写 reference=4 （整数），它会内部转换失败，导致参考答案丢失。

验证方法 ：在调用 evaluate_strings 前，加一行打印：

print(f"Type of reference: {type(reference)}, Value: {repr(reference)}")
# 正确输出应为：Type of reference: <class 'str'>, Value: '4'

如果输出是 <class 'int'> ，立刻用 str(reference) 转换。更稳妥的做法是，在数据准备阶段就统一类型：

# 构建测试集时，强制转为字符串
test_cases = [
    {"input": "Policz 2 + 2", "reference": str(4), "prediction": "2 + 2 = 4"},
    # ...
]

这个细节，LangChain文档只字未提，但它是新手前三天最常见的绊脚石。

5.3 自定义评估器不生效： custom_evaluators 的注册玄机

你写了完美的 @run_evaluator 函数，也把它加进了 RunEvalConfig.custom_evaluators=[my_func] ，但运行后 scores 里压根找不到 my_func 的key。这通常有两个原因：

1. 函数名冲突 ：LangSmith会用函数名作为 key 。如果你的函数叫 custom_evaluator ，而LangChain内置也有同名函数，就会覆盖。解决方案：给函数起唯一、描述性的名字，比如 detect_medical_assumptions ；
2. 模块导入路径错误 ： @run_evaluator 装饰器必须在 langsmith.evaluation 模块的上下文中执行。如果你把自定义评估器写在一个独立的 evaluators.py 文件里，然后在主脚本里 from evaluators import detect_medical_assumptions ，LangSmith有时会找不到它。最可靠的做法：把自定义评估器直接写在调用 run_on_dataset 的同一个Python文件里，或者确保 evaluators.py 在Python path里，并用绝对导入。

终极调试法 ：在 run_on_dataset 调用前，加一行：

print("Custom evaluators registered:", eval_config.custom_evaluators)
# 确保这里打印出的是你函数的内存地址，而不是空列表

如果这里就是空的，说明注册环节就失败了，回头检查导入和装饰器语法。

5.4 LangSmith项目名冲突： project_name 的隐藏规则

示例代码里， project_name 用了 "existential questions run:"+ uuid.uuid4().__str__() 。这是个好习惯，但很多人不知道为什么。LangSmith要求 project_name 在你的账户下全局唯一。如果你硬编码 project_name="my-eval-run" ，第二次运行就会报错 ProjectAlreadyExistsError 。UUID是解决方案，但要注意：LangSmith对 project_name 有长度限制（100字符），而 uuid4() 生成的字符串是36位，加上前缀很容易超限。我的做法是截取UUID前8位：

import uuid
dataset_name = f"prod-eval-{uuid.uuid4().hex[:8]}"

另外， project_name 不能包含空格或特殊字符（除了 - 和 _ ）。像 "Q&A Eval (Jan 2024)" 这样的名字会直接失败。LangSmith的错误提示非常不友好，只会说 Invalid project name ，让你怀疑人生。记住这个正则： ^[a-zA-Z0-9-_]{1,100}$ ，你的项目名必须完全匹配它。

6. 实战心得与避坑指南：十年踩坑总结的十三条军规

6.1 军规一：永远先用 unlabeled_criteria ，再考虑 labeled_criteria

这是我用三个项目、两个月时间换来的教训。第一次做金融问答机器人，我们花了三周时间，让五个分析师为200个问题编写标准答案，结果上线后发现，80%的用户问题根本不在那200个里，模型在真实场景的表现和测试集分数毫无相关性。第二次，我们砍掉所有 reference ，只用 unlabeled_criteria 定义 regulatory_compliance 和 risk_disclosure 两条标准，一周就搭好评估流水线，分数和用户投诉率的相关系数达到0.87。 labeled_criteria 只适用于：1）有唯一真理答案的封闭域（数学、代码）；2）你有充足资源维护一个动态更新的高质量答案库。否则，它就是效率黑洞。

6.2 军规二：评判模型（Judge LLM）的选择，不是越贵越好，而是越稳越好

别被 gpt-4o 的光环迷惑。在评估场景，稳定性比创造力重要十倍。 gpt-4o 偶尔会“灵光一闪”，给出一个惊艳但不可复现的评分；而 gpt-4o-mini 虽然小，但它的输出极其稳定，同一输入，100次运行，99次结果一致。我们的A/B测试显示，在 correctness 评估上， gpt-4o-mini 的跨次一致性是99.2%， gpt-4o 是92.7%。这意味着，用 gpt-4o 做评估，你看到的分数波动，可能50%来自评判模型自身，而非被测模型。我的配置清单：

• 日常监控 ： gpt-4o-mini （快、稳、便宜）；
• 深度归因分析 ： gpt-4o （当你要深挖某条低分原因时，用它生成更丰富的 comment ）；
• 绝对禁区 ： claude-3-haiku 。它在 insensitivity 评估上过于严苛，会把所有提及“疾病”“死亡”的科普回答都标为 N ，因为它把“客观描述”和“引发焦虑”混淆了。

6.3 军规三： conciseness 不是“越短越好”，而是“在达成目标前提下的最短”

我见过最典型的错误，是把 conciseness 标准写成 {"conciseness": "Is the response under 100 words?"} 。结果模型学会了作弊：把长回答压缩成“总之，答案是：是。”——字数达标，用户体验崩坏。真正的 conciseness ，必须绑定目标。比如客服场景，应该是： {"conciseness": "Does the response resolve the user's core issue in ≤3 sentences, without omitting critical steps or caveats?"} 。我们为此专门训练了一个微型分类器，它不看字数，而是判断“用户问题是否被闭环解决”。这个分类器的输出，才是 conciseness 的真正分数。记住：所有评估标准，最终都要回归到“用户是否得到了他想要的东西”。

6.4 军规四：建立“评估即文档”的文化，让每条标准都成为产品说明书

每当你写一条新的 Criteria ，比如 {"data_privacy": "Does the response avoid requesting or storing any PII (Personally Identifiable Information) without explicit user consent and clear purpose statement?"} ，请同步做两件事：1）把这个标准的完整定义，写进你的产品需求文档（PRD）的“非功能性需求”章节；2）把这个标准的 comment 示例（LangSmith里生成的），做成内部培训材料，教客服和法务团队如何识别风险。这样，评估器就不再是工程师的玩具，而成了连接产品、法务、运营的共同语言。我们有个客户，把 insensitivity 标准的12个 comment 示例，印成一页纸贴在每个客服工位上，结果当月相关投诉下降了65%。评估的终极价值，是让所有人对“什么是好答案”达成共识。

6.5 军规五：警惕“高分幻觉”，永远用