AI Agent可观测性与评估实践：基于OpenTelemetry的追踪与监控

1. 项目概述：为什么我们需要一个AI Agent的“行车记录仪”

如果你正在开发基于大语言模型的AI应用，无论是智能客服、代码助手还是复杂的多步骤工作流Agent，那么下面这个场景你一定不陌生：线上用户反馈“回答不准确”，你打开日志，看到的只有孤零零的输入和输出，中间发生了什么？模型“思考”了多久？调用了哪些工具？哪个环节出的错？你两眼一抹黑，只能靠猜。更头疼的是评估，每次迭代新Prompt或调整Agent逻辑，你都得手动跑一堆测试用例，既耗时又难以保证覆盖率和一致性。

这就是JudgmentLabs/judgeval要解决的问题。你可以把它理解为你AI Agent的“行车记录仪”和“随车教练”二合一系统。它基于OpenTelemetry标准，能无侵入式地追踪Agent执行的每一个步骤（轨迹），记录下所有的输入、输出、耗时和成本。更重要的是，它内置了一套强大的评估框架，让你可以像设置交通规则一样，为Agent的行为定义评分标准（比如“回答是否相关”、“是否遵循指令”），并在线上流量中异步执行这些评估，一旦“违规”就触发告警。无论是想实时监控生产环境Agent的健康状况，还是想系统化地评估和迭代你的Prompt与Agent逻辑，这个开源SDK都提供了一个从追踪、评估到监控的完整解决方案。

2. 核心设计思路：从“黑盒”到“白盒”的Agent治理

在深入代码之前，理解judgeval的设计哲学至关重要。它并非又一个简单的日志库，而是围绕可观测性、可评估性和可操作性构建的治理平台。

2.1 基于OpenTelemetry的标准化追踪

很多团队最初会用print语句或自定义日志来追踪Agent，但这很快会变得难以维护和查询。judgeval选择拥抱OpenTelemetry（OTel）这个云原生可观测性的行业标准。这意味着：

1. 标准化数据模型：每一次函数调用、每一次LLM请求都被建模为一个“Span”（跨度），包含开始时间、结束时间、属性（键值对）、事件和链接。这为复杂工作流的分析提供了统一的基础。
2. 无缝集成现有生态：因为基于OTel，judgeval产生的追踪数据可以轻松导出到任何兼容OTel的后端，如Jaeger、Zipkin、Datadog、New Relic等。你不需要被锁定在某个特定平台。
3. 自动化的上下文传播：在复杂的异步或分布式Agent调用链中，OTel能自动处理上下文传递，确保你能完整地看到从用户输入到最终输出的整条“轨迹”，而不是一堆散落的片段。

judgeval的@Tracer.observe()装饰器就是这一思想的体现。它自动将函数转化为一个OTel Span，捕获所有参数（输入）和返回值（输出）。对于LLM调用，它通过包装客户端（如wrap(OpenAI())）进一步捕获令牌使用量、模型名称和估算成本。这让你对Agent的“内部燃烧”一目了然。

2.2 解耦的评估架构：在线与离线双模式

评估Agent性能是个多维度的挑战。judgeval将其清晰地分为两种模式，对应不同的场景：

1. 在线监控：在真实的生产流量中运行评估。关键在于不能影响用户体验。因此，Tracer.async_evaluate()被设计为异步操作。它只将评估所需的数据（如输入和输出）发送到judgeval的服务端，评估逻辑在远端安全执行，结果稍后返回并用于触发告警（如Slack通知）。这让你能实时发现生产环境中的退化问题，比如最近一次模型更新导致“回答相关性”分数普遍下降。
2. 离线评估：在开发、测试或定期回归测试中运行。使用Judgeval客户端的evaluation.run()方法，针对一个预设的“黄金数据集”运行批量评估。这用于系统性地比较不同Prompt版本、不同模型或不同Agent架构的效果，为迭代决策提供数据支持。

这两种模式共享同一套“评估器”定义，确保了评估标准的一致性。

2.3 安全且灵活的自定义评估器

预置的评估器（如忠实度、相关性）很好，但每个业务都有独特的需求。judgeval允许你定义任何Python函数作为评估器，并通过其CLI工具上传。最值得称道的是其安全模型：你的自定义代码运行在隔离的Firecracker微虚拟机中。这意味着：

• 安全性：你的评估逻辑与judgeval的核心服务隔离，即使你的代码有bug或安全漏洞，也不会影响平台稳定性或其他用户。
• 灵活性：你可以实现任何复杂逻辑：调用另一个LLM进行“LLM即裁判”评估、执行代码检查、运行数据库查询、调用外部API进行计算等。只要能用Python写，就能作为评估器运行。

通过继承Judge基类并定义BinaryResponse、NumericResponse或CategoricalResponse，你可以标准化评估器的输出，便于平台进行统一的统计、可视化和告警。

3. 从零开始：环境配置与核心功能上手实操

理论讲完了，我们动手搭一个环境，把核心流程跑通。假设我们正在构建一个“旅游助手”Agent。

3.1 初始设置与基础追踪

首先，安装并配置基础环境。

# 安装SDK pip install judgeval # 设置环境变量（先去 https://app.judgmentlabs.ai/register 注册获取） export JUDGMENT_API_KEY='your_api_key_here' export JUDGMENT_ORG_ID='your_org_id_here'

接下来，我们创建一个简单的Agent，它先搜索信息，再让LLM总结。

# travel_agent.py import os from judgeval import Tracer, wrap from openai import OpenAI # 1. 初始化Tracer，指定项目名。所有该项目的追踪数据都会归集在一起。 Tracer.init(project_name="travel-assistant-v1") # 2. 包装OpenAI客户端。这是关键一步，它自动为每次LLM调用创建Span并记录token和成本。 client = wrap(OpenAI(api_key=os.getenv("OPENAI_API_KEY"))) # 模拟一个搜索工具 def mock_search(query: str) -> list: # 这里模拟向量数据库搜索 knowledge_base = { "巴黎": "巴黎是法国首都，以埃菲尔铁塔、卢浮宫和塞纳河闻名，被誉为光之城。", "东京": "东京是日本首都，融合传统与现代，有浅草寺、东京塔和丰富的动漫文化。", "七月": "七月是北半球的夏季，许多欧洲城市天气温暖，适合户外活动。" } return [knowledge_base.get(query, "未找到相关信息。")] # 3. 使用装饰器追踪工具函数。span_type="tool"帮助平台在UI中正确分类和展示。 @Tracer.observe(span_type="tool") def search_attractions(city: str) -> str: print(f"[Tool Call] 搜索城市: {city}") results = mock_search(city) return "\n".join(results) # 4. 追踪主要的Agent函数。 @Tracer.observe(span_type="agent") def travel_agent(user_question: str) -> str: print(f"[Agent] 处理问题: {user_question}") # 简单解析用户问题，提取城市（实际中可用更复杂的NLP） if "巴黎" in user_question: city = "巴黎" elif "东京" in user_question: city = "东京" else: city = "未知" # 调用工具 context = search_attractions(city) # 调用LLM生成回答。这次调用会被自动追踪。 response = client.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": "你是一个专业的旅游助手，根据提供的信息回答问题。"}, {"role": "user", "content": f"背景信息：{context}\n\n用户问题：{user_question}"} ], temperature=0.7, ) answer = response.choices[0].message.content print(f"[Agent] 生成回答: {answer[:50]}...") # 打印前50字符 return answer # 运行Agent if __name__ == "__main__": answer = travel_agent("请问巴黎有什么好玩的？") print(f"最终答案: {answer}")

运行这个脚本后，打开 Judgment平台 ，在“Traces”或“Trajectories”页面，你应该能看到一条名为travel_agent的轨迹。点进去，可以看到一个清晰的树状结构：一个agent类型的根Span，下面嵌套着一个tool类型的子Span（search_attractions）和一个llm类型的子Span（OpenAI调用）。每个Span都详细记录了输入、输出、开始/结束时间以及LLM调用的token和成本估算。

实操心得：span_type参数虽然看起来只是个标签，但在后期分析时极其有用。你可以通过筛选span_type:llm快速找出所有昂贵的模型调用进行分析，或者通过span_type:tool检查工具调用的成功率。建议从一开始就规划好你的Span类型体系（如agent,tool,llm,knowledge_base,decision等）。

3.2 接入在线监控：为Agent设置“质量关卡”

现在，我们的Agent能跑了，也能看到内部过程了。但怎么知道它的回答质量好不好呢？我们引入在线评估。

修改上面的travel_agent函数，在返回答案前，添加异步评估。

@Tracer.observe(span_type="agent") def travel_agent_with_monitoring(user_question: str) -> str: print(f"[Agent] 处理问题: {user_question}") # ... (前面的搜索和LLM调用逻辑保持不变) ... answer = response.choices[0].message.content # 关键步骤：添加异步评估 Tracer.async_evaluate( scorer_name="answer_relevancy", # 使用平台预置的“回答相关性”评估器 data={ "input": user_question, "actual_output": answer, # 有些评估器可能需要额外上下文，按需提供 # "context": context } ) # 可以同时添加多个评估 Tracer.async_evaluate( scorer_name="faithfulness", # 使用“忠实度”评估器，检查回答是否基于提供的上下文 data={ "input": user_question, "actual_output": answer, "context": context # 忠实度评估需要原始上下文 } ) print(f"[Agent] 已提交评估请求") return answer

这里的Tracer.async_evaluate是关键。它不会阻塞你Agent的返回，用户体验零延迟。评估任务被推送到judgeval云端，在后台执行。执行完成后，你可以在平台的“Evaluations”或“Monitoring”面板看到这次调用的得分（例如，answer_relevancy: 0.92,faithfulness: 0.85）。

注意事项：在线评估是“尽力而为”的，可能因为网络或服务端队列问题稍有延迟。它主要用于监控和告警，而不是实时决策。切勿在业务逻辑中同步等待评估结果。

3.3 配置告警：当Agent“犯错”时得到通知

光有评估分数还不够，我们需要在分数过低时主动获知。这需要在Judgment平台上进行配置。

1. 登录Judgment平台，进入你的项目（travel-assistant-v1）。
2. 导航到“Alerts”或“Monitoring”部分。
3. 创建告警规则：
   • 规则名称：Low Relevancy Alert
   • 评估器：answer_relevancy
   • 条件：score < 0.7（当相关性分数低于0.7时触发）
   • 聚合方式：可以选择在5分钟内超过3次才触发，避免单次波动误报。
   • 通知渠道：集成Slack、Webhook或邮件。配置一个Slack频道，让团队能第一时间看到。

配置完成后，下次你的Agent给出一个与问题完全无关的回答（比如用户问巴黎，Agent答东京），相关性评分可能会很低，从而触发告警，一条消息就会发送到你的Slack频道：“[Alert] Low Relevancy Alert triggered in travel-assistant-v1. Score: 0.45. Check trace: [链接]”。你点击链接就能直接跳转到有问题的具体轨迹进行分析。

4. 构建自定义评估器：打造专属的Agent“评分标准”

预置评估器覆盖了通用场景，但真正的业务需求往往更具体。比如，对于旅游助手，我们可能想评估“回答是否包含了必打卡景点”，或者“推荐的开销是否合理”。我们来创建一个自定义的“景点覆盖度”评估器。

4.1 定义评估器逻辑

创建一个名为attraction_coverage_judge.py的文件。

# attraction_coverage_judge.py from judgeval.judges import Judge from judgeval.hosted.responses import NumericResponse # 使用数值型响应，给出0-1的分数 from judgeval.data import Example from typing import Dict, Any class AttractionCoverageJudge(Judge[NumericResponse]): """ 评估旅游助手的回答是否覆盖了目标城市的标志性景点。 这是一个示例，实际中你可能需要更复杂的NLP或知识库查询。 """ # 定义一个简单的景点知识库 LANDMARKS = { "巴黎": ["埃菲尔铁塔", "卢浮宫", "塞纳河", "凯旋门", "巴黎圣母院"], "东京": ["东京塔", "浅草寺", "涩谷十字路口", "皇居", "秋叶原"], } async def score(self, data: Example) -> NumericResponse: """ 核心评分函数。 data: 包含input, actual_output等字段的字典。 """ user_input: str = data.get("input", "") agent_output: str = data.get("actual_output", "") # 1. 从用户输入中提取城市（这里用简单关键词匹配，生产环境应用NER模型） target_city = None for city in self.LANDMARKS.keys(): if city in user_input: target_city = city break if not target_city: # 如果无法识别城市，返回一个中性分数或根据业务逻辑处理 return NumericResponse(value=0.5, reason="未识别到目标城市，无法评估景点覆盖度。") # 2. 获取该城市的必去景点列表 required_attractions = self.LANDMARKS[target_city] # 3. 检查Agent回答中包含了多少个必去景点 found_count = 0 found_items = [] for attraction in required_attractions: if attraction in agent_output: found_count += 1 found_items.append(attraction) # 4. 计算覆盖率分数 coverage_score = found_count / len(required_attractions) # 5. 构建返回结果 reason = f"目标城市「{target_city}」的{len(required_attractions)}个标志性景点中，提到了{found_count}个：{', '.join(found_items)}。" return NumericResponse(value=coverage_score, reason=reason) # 注意：异步函数`score`是必须的，即使你的逻辑是同步的，也需要用`async def`定义。 # 如果内部是同步逻辑，直接返回即可，平台会正确处理。

4.2 上传与部署评估器

使用judgevalCLI工具将评估器上传到云端。

# 1. 初始化一个评估器脚手架（可选，但有助于理解结构） # judgeval scorer init -t numeric -n AttractionCoverageJudge # 2. 上传评估器文件到指定项目 judgeval scorer upload attraction_coverage_judge.py -p travel-assistant-v1

上传成功后，在Judgment平台的“Scorers”页面，你应该能看到一个名为AttractionCoverageJudge（或根据你类名自动生成的名称）的评估器，状态为“Active”。

4.3 在代码中调用自定义评估器

现在，你可以像使用预置评估器一样，在在线监控或离线评估中使用它。

在线监控中调用：

@Tracer.observe(span_type="agent") def travel_agent_with_custom_monitoring(user_question: str) -> str: # ... 原有的Agent逻辑 ... answer = ... Tracer.async_evaluate( scorer_name="AttractionCoverageJudge", # 使用自定义评估器的名称 data={ "input": user_question, "actual_output": answer, } ) return answer

离线评估中调用：

from judgeval import Judgeval from judgeval.data import Example client = Judgeval(project_name="travel-assistant-v1") evaluation = client.evaluation.create() results = evaluation.run( examples=[ Example.create( input="请介绍下巴黎的旅游景点。", actual_output="巴黎有埃菲尔铁塔和塞纳河，非常浪漫。", # 只提到了两个 expected_output="", # 自定义评估器可能不需要expected_output ), Example.create( input="东京有什么好玩的地方？", actual_output="推荐你去浅草寺感受传统，再去秋叶原体验动漫文化，还有东京塔俯瞰全城。", expected_output="", ), ], scorers=["AttractionCoverageJudge", "answer_relevancy"], # 混合使用自定义和预置评估器 eval_run_name="custom-judge-test", ) for result in results: print(f"输入: {result.example.input}") for score in result.scores: print(f" - {score.scorer_name}: {score.value} (理由: {score.reason})")

运行离线评估后，你会得到详细的评分结果。对于第一个例子（巴黎），因为5个景点只提到2个，AttractionCoverageJudge的得分可能是0.4；第二个例子（东京）提到了3个，得分可能是0.6。同时，answer_relevancy会评估回答的整体相关性。

避坑技巧：自定义评估器的score方法必须是async。即使你的逻辑完全是同步的，也需要用async def定义。这是因为平台在微VM中运行时，可能采用异步调度。如果你的评估逻辑中有网络I/O（如调用另一个API），务必使用异步库（如aiohttp）以提高性能。

5. 高级工作流：数据集管理与Prompt版本控制

当Agent项目进入迭代阶段，你会面临两个核心问题：1）用什么数据来评估？2）如何管理不断变化的Prompt？judgeval提供了数据集和Prompt版本管理来应对。

5.1 创建与管理黄金数据集

黄金数据集是你的“标准答案”库，用于离线评估和回归测试。

from judgeval import Judgeval from judgeval.data import Example client = Judgeval(project_name="travel-assistant-v1") # 1. 创建一个数据集 dataset = client.datasets.create( name="travel-qa-golden-v1", examples=[ Example.create( input="巴黎最著名的博物馆是什么？", expected_output="卢浮宫是巴黎最著名、也是世界上最大的博物馆之一。", # 可以添加元数据，方便筛选 metadata={"category": "culture", "difficulty": "easy"} ), Example.create( input="在东京哪里可以看城市全景？", expected_output="可以登上东京塔或东京晴空塔观看城市全景。", metadata={"category": "viewpoint", "difficulty": "easy"} ), Example.create( input="七月去欧洲旅行，天气如何？需要带什么？", expected_output="七月是欧洲夏季，天气普遍温暖晴朗。建议携带防晒霜、太阳镜、轻便衣物和一件薄外套以备傍晚凉爽。", metadata={"category": "weather", "difficulty": "medium"} ), ], description="旅游助手V1版黄金测试集" ) print(f"数据集创建成功: {dataset.id}") # 2. 获取数据集用于评估 dataset_for_eval = client.datasets.get(name="travel-qa-golden-v1") # 3. 运行批量评估 evaluation = client.evaluation.create() results = evaluation.run( examples=dataset_for_eval.examples, # 直接使用数据集中的例子 scorers=["answer_relevancy", "faithfulness", "AttractionCoverageJudge"], eval_run_name="regression-test-v1.2", ) # 4. 分析结果：可以计算平均分，或找出不及格的案例 failed_examples = [] for result in results: low_scores = [s for s in result.scores if s.value < 0.7] if low_scores: failed_examples.append((result.example.input, low_scores)) print(f"本次回归测试发现 {len(failed_examples)} 个低分回答。")

平台UI上，你可以可视化每次评估运行的结果，对比不同版本Agent在同一个数据集上的表现折线图，清晰看到迭代是进步了还是退步了。

5.2 实现Prompt版本控制与A/B测试

Prompt是Agent的灵魂，但直接修改代码中的Prompt字符串是危险的，也难于追踪。judgeval的Prompt版本化功能提供了解决方案。

# 1. 创建并版本化一个系统Prompt client = Judgeval(project_name="travel-assistant-v1") # 第一个版本 - 通用助手 prompt_v1 = client.prompts.create( name="system-prompt", prompt="你是一个友好的旅游助手，请热情地回答用户关于旅行的问题。", tags=["v1", "baseline"] ) # 第二个版本 - 更专业、强调提供结构化信息 prompt_v2 = client.prompts.create( name="system-prompt", prompt="你是一个专业的旅游顾问。请以清晰、结构化的方式回答，优先列出关键景点、交通方式和注意事项。回答语言：{{language}}。", tags=["v2", "structured"] ) # 2. 在代码中获取并使用特定版本的Prompt def get_agent_response(question: str, prompt_tag: str = "v1", language: str = "中文"): client = Judgeval(project_name="travel-assistant-v1") # 获取指定标签的Prompt prompt_obj = client.prompts.get(name="system-prompt", tag=prompt_tag) # 编译Prompt，替换变量 compiled_system_prompt = prompt_obj.compile(language=language) # 使用编译后的Prompt调用LLM wrapped_client = wrap(OpenAI()) response = wrapped_client.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": compiled_system_prompt}, {"role": "user", "content": question} ] ) return response.choices[0].message.content # 3. 结合数据集进行A/B测试 dataset = client.datasets.get(name="travel-qa-golden-v1") for example in dataset.examples[:3]: # 取前3个例子测试 answer_v1 = get_agent_response(example.input, prompt_tag="v1") answer_v2 = get_agent_response(example.input, prompt_tag="v2", language="中文") # 对两个答案分别进行评估 eval_v1 = client.evaluation.create().run( examples=[Example.create(input=example.input, actual_output=answer_v1)], scorers=["answer_relevancy", "faithfulness"], eval_run_name=f"ab-test-prompt-v1-{example.metadata.get('id')}" ) eval_v2 = client.evaluation.create().run( examples=[Example.create(input=example.input, actual_output=answer_v2)], scorers=["answer_relevancy", "faithfulness"], eval_run_name=f"ab-test-prompt-v2-{example.metadata.get('id')}" ) # 比较 eval_v1 和 eval_v2 的分数...

通过将Prompt存储在平台并打上标签，你可以：

• 轻松回滚：如果新Prompt（v2）效果不好，立即切回v1。
• 精准对比：在相同测试集上，公平地比较不同Prompt版本的效果。
• 团队协作：Prompt的修改历史清晰可见，方便团队评审。

注意事项：Prompt版本化功能对于管理复杂的、多变量的Prompt模板特别有效。但注意，频繁编译和获取远程Prompt可能会引入微小延迟。对于超低延迟场景，可以考虑在服务启动时加载Prompt并缓存。

6. 集成与扩展：融入现有技术栈

很少有项目是从零开始的。judgeval在设计上考虑了与主流LLM应用开发生态的集成。

6.1 与LangGraph集成

如果你用LangGraph构建复杂的多Agent工作流，集成非常简单。

from judgeval.integrations import Langgraph from langgraph.graph import StateGraph, END from typing import TypedDict import operator # 初始化judgeval的LangGraph集成（必须在创建图之前调用） Langgraph.initialize(project_name="travel-assistant-v1") class AgentState(TypedDict): question: str context: str answer: str def search_node(state: AgentState): # 这个函数会被自动追踪！ # ... 搜索逻辑 ... return {"context": "找到的信息..."} def llm_node(state: AgentState): # 包装过的LLM客户端在这里也会被自动追踪 client = wrap(OpenAI()) # ... LLM调用逻辑 ... return {"answer": "生成的回答..."} # 构建图 workflow = StateGraph(AgentState) workflow.add_node("search", search_node) workflow.add_node("llm", llm_node) workflow.set_entry_point("search") workflow.add_edge("search", "llm") workflow.add_edge("llm", END) app = workflow.compile() # 运行工作流，整个执行过程会被记录为一条轨迹 result = app.invoke({"question": "巴黎天气如何？"})

集成后，LangGraph中每个节点的执行都会成为一个独立的Span，并且它们之间的依赖关系会体现在轨迹的树形结构中，让你能清晰看到工作流的执行路径和每个节点的性能。

6.2 与其他框架和提供商的集成

对于其他框架，集成方式类似：

# 对于Claude Agent SDK from judgeval.integrations import setup_claude_agent_sdk setup_claude_agent_sdk(project_name="my-project") # 对于OpenLit（另一个OTel兼容的LLM观测库） from judgeval.integrations import Openlit Openlit.initialize(project_name="my-project") # 之后OpenLit追踪的数据也会统一到judgeval的视图中

对于LLM提供商，wrap()函数是通用钥匙：

from anthropic import Anthropic from google import genai from together import Together client_anthropic = wrap(Anthropic()) client_google = wrap(genai.Client()) client_together = wrap(Together())

实操心得：当混合使用多个被包装的客户端时，确保它们都使用同一个project_name初始化的Tracer上下文。这样，即使一个请求中调用了不同厂商的模型，这些调用也会被关联到同一次Agent执行的轨迹下，方便进行成本分析和性能对比。

7. 生产环境部署与问题排查指南

将judgeval用于生产环境监控，需要考虑一些工程细节。

7.1 配置与最佳实践

1. 环境变量管理：不要将JUDGMENT_API_KEY硬编码在代码中。使用.env文件或Kubernetes Secrets、AWS Secrets Manager等安全管理。

   # .env 文件 JUDGMENT_API_KEY=sk_live_... JUDGMENT_ORG_ID=org_... OPENAI_API_KEY=sk-...

   # 在Python中加载 from dotenv import load_dotenv load_dotenv()

2. Tracer初始化位置：在Web服务（如FastAPI）或长期运行的后台Worker中，确保Tracer.init()只在应用启动时调用一次，而不是每次请求都调用。

   # FastAPI 示例 from fastapi import FastAPI from judgeval import Tracer app = FastAPI() @app.on_event("startup") async def startup_event(): Tracer.init(project_name="production-assistant", enable_online_monitoring=True) @app.get("/chat") async def chat_endpoint(question: str): # ... 处理逻辑，函数已用@Tracer.observe装饰 ... return {"answer": response}

3. 采样率控制：在生产中，可能不需要追踪100%的请求，尤其是高流量场景。judgeval目前文档未明确提及采样率配置，但通常可以通过在Tracer.init中设置相关参数（如sampling_rate=0.1用于10%采样）或结合OpenTelemetry的采样器来实现。如果SDK未直接暴露，可以考虑在装饰器层面添加条件逻辑。

7.2 常见问题与排查

即使设计得再好，在实际运行中也可能遇到问题。下面是一些常见场景及其排查思路。

调试技巧：启用详细日志是排查问题最快的方式。在代码开头添加：

import logging logging.basicConfig(level=logging.DEBUG)

这会将judgevalSDK内部的HTTP请求、数据发送等日志打印出来，帮助你定位是配置错误、网络问题还是逻辑问题。

8. 总结与进阶思考

经过以上几个部分的拆解，你应该对judgeval的能力有了全面的了解。它本质上提供了一个三层治理框架：观测层（Tracing）让你看清Agent内部；评估层（Evaluation）让你定义好坏标准；行动层（Monitoring/Alerts）让你在出问题时能快速响应。

在实际项目中引入judgeval，我建议采用渐进式策略：

1. 第一阶段（可视化）：先只接入追踪（Tracing）。不用改多少代码，就能获得LLM调用成本、耗时和流程可视化的巨大价值。这能立刻帮你发现性能瓶颈和异常调用。
2. 第二阶段（质量监控）：针对核心场景，添加1-2个关键的在线评估（如answer_relevancy）。配置好Slack告警，先解决“回答完全跑偏”这类严重问题。
3. 第三阶段（迭代优化）：建立一个小型的黄金数据集，开始定期运行离线评估。每次修改Prompt或Agent逻辑后，都跑一遍评估，用数据说话，避免凭感觉迭代。
4. 第四阶段（深度定制）：根据业务痛点，开发自定义评估器。例如，电商客服Agent可以评估“是否准确提取了订单号”，代码生成Agent可以评估“编译通过率”。

最后，一个常被忽略但至关重要的点是：评估标准本身需要评估。你定义的“相关性”、“忠实度”甚至自定义的评估器，是否真的对应业务成功指标？需要定期将评估分数与真实业务结果（如用户满意度评分、工单解决率）进行关联分析，持续校准你的评估体系。judgeval提供了数据和基础设施，但如何定义“好”的Agent，始终是需要你结合业务深入思考的核心问题。