概述

Judgeval 是一个用于代理行为监控的开源 Python SDK。它为由 LLM 驱动的应用程序提供追踪、评估和在线监控功能，使您能够实时捕捉故障，并基于生产数据改进代理。

要开始使用，请尝试下面的 教程 之一，或深入阅读 文档。

为什么选择 Judgeval

基于 OpenTelemetry 的追踪 -- 使用 @Tracer.observe() 装饰任何函数。自动捕获输入、输出以及 LLM 的 token 使用情况。基于 OpenTelemetry 构建，与现有可观测性堆栈完全兼容。

托管与自定义评估 -- 可以针对 Judgment 托管的评分器（如忠实度、答案相关性、指令遵循等）运行评估，也可以定义自己的 Judge 类，支持二元、数值或分类类型的响应。

在线监控 -- 使用 Tracer.async_evaluate() 异步对实时生产流量进行评分。在服务器端运行，不会影响延迟。可配置 Slack 告警以应对失败情况。

自定义评分器托管 -- 将任意 Python 评分器上传至安全的 Firecracker 微虚拟机中运行。任何可以用 Python 表达的逻辑——例如将 LLM 用作评判者、代码检查、多步骤流水线等——都可以作为托管评分器运行。

数据集管理和提示版本控制 -- 存储黄金评估集，使用 {{variable}} 语法为提示模板添加版本号，并为生产/预发布工作流打上标签。

广泛的集成支持 -- 自动化对 OpenAI、Anthropic、Google GenAI 和 Together AI 的插桩。同时支持 LangGraph、OpenLit 和 Claude Agent SDK 等框架。

快速入门

安装 SDK：

pip install judgeval

设置您的凭据（如果您没有密钥，请创建一个免费账户）：

export JUDGMENT_API_KEY=...
export JUDGMENT_ORG_ID=...

追踪

只需两行代码即可为您的代理添加可观测性：

from judgeval import Tracer, wrap
from openai import OpenAI

Tracer.init(project_name="my-project")
client = wrap(OpenAI())

@Tracer.observe(span_type="tool")
def search(query: str) -> str:
    results = vector_db.search(query)
    return results

@Tracer.observe(span_type="agent")
def run_agent(question: str) -> str:
    context = search(question)
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": f"{context}\n\n{question}"}],
    )
    return response.choices[0].message.content

run_agent("美国的首都是哪里？")

所有追踪数据都会被发送到您的 Judgment 控制台：

在线监控

可以在任何已追踪的函数内部异步对实时流量进行评分。评估将在 span 完成后在服务器端运行：

@Tracer.observe(span_type="agent")
def run_agent(question: str) -> str:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": question}],
    )
    answer = response.choices[0].message.content

    Tracer.async_evaluate(
        "answer_relevancy",
        {"input": question, "actual_output": answer},
    )

    return answer

离线评估

使用 Judgeval 客户端对托管评分器执行批量评估：

from judgeval import Judgeval
from judgeval.data import Example

client = Judgeval(project_name="my-project")
evaluation = client.evaluation.create()

results = evaluation.run(
    examples=[
        Example.create(
            input="2+2 等于多少？",
            actual_output="4",
            expected_output="4",
        ),
    ],
    scorers=["faithfulness", "answer_relevancy"],
    eval_run_name="nightly-eval",
)

结果将以 ScoringResult 对象的形式返回，并显示在控制台中。

自定义评判者

通过继承 Judge 类并指定响应类型来定义您自己的评估逻辑：

from judgeval.judges import Judge
from judgeval.hosted.responses import BinaryResponse
from judgeval.data import Example

class CorrectnessJudge(Judge[BinaryResponse]):
    async def score(self, data: Example) -> BinaryResponse:
        correct = data["expected_output"].lower() in data["actual_output"].lower()
        return BinaryResponse(
            value=correct,
            reason="包含预期答案" if correct else "缺少预期答案",
        )

目前有三种响应类型可供选择：

类型	值	使用场景
BinaryResponse	bool	通过/不通过检查
NumericResponse	float	连续分数（0.0 — 1.0）
CategoricalResponse	str	分类到预定义类别

使用 CLI 搭建并上传

judgeval scorer init -t binary -n CorrectnessJudge
judgeval scorer upload correctness_judge.py -p my-project

上传完成后，您的评判者将在安全的 Firecracker 微虚拟机中运行，并可通过 Tracer.async_evaluate() 用于在线监控。

数据集

通过平台管理黄金评估集：

from judgeval import Judgeval
from judgeval.data import Example

client = Judgeval(project_name="my-project")

dataset = client.datasets.create(
    name="golden-set",
    examples=[
        Example.create(input="2+2 等于多少？", expected_output="4"),
        Example.create(input="法国的首都是哪里？", expected_output="巴黎"),
    ],
)

dataset = client.datasets.get(name="golden-set")

数据集支持从 JSON/YAML 导入、批量追加和导出。

提示模板版本控制

使用 {{variable}} 占位符对提示模板进行版本管理和标记：

client = Judgeval(project_name="my-project")

prompt = client.prompts.create(
    name="system-prompt",
    prompt="你是一位针对{{product}}的助手。请用{{language}}作答。",
    tags=["production"],
)

prompt = client.prompts.get(name="system-prompt", tag="production")
compiled = prompt.compile(product="Acme Search", language="English")

集成

大模型提供商

使用 wrap() 包装任何受支持的客户端，即可自动创建追踪跨度并跟踪 token 数量与成本：

from judgeval import wrap

client = wrap(OpenAI())          # OpenAI
client = wrap(Anthropic())       # Anthropic
client = wrap(genai.Client())    # Google GenAI
client = wrap(Together())        # Together AI

框架

框架	设置
LangGraph	from judgeval.integrations import Langgraph; Langgraph.initialize()
OpenLit	from judgeval.integrations import Openlit; Openlit.initialize()
Claude Agent SDK	from judgeval.integrations import setup_claude_agent_sdk; setup_claude_agent_sdk()

说明书

主题	笔记本	描述
在线 A/B 测试	Research Agent	监控生产环境中的代理行为
自定义评分器	HumanEval	为你的代理构建自定义评估工具

浏览完整的说明书仓库，或观看视频教程。

链接

• 文档
• Judgment 平台
• 自托管指南
• 自定义评分器指南
• 在线评估指南
• 说明书仓库
• 视频教程

---

Judgeval 由 Judgment Labs 创建并维护。

Judgeval 快速上手指南

Judgeval 是一个开源的 Python SDK，专为监控和评估 LLM 驱动的智能体（Agent）行为而设计。它支持基于 OpenTelemetry 的链路追踪、在线/离线评估以及自定义评分逻辑，帮助开发者实时发现故障并优化生产环境中的 Agent 表现。

环境准备

• 系统要求：Python 3.8 及以上版本。
• 前置依赖：
  • 已注册的 Judgment Labs 账户（用于获取 API 密钥）。
  • 常用的 LLM 客户端库（如 openai, anthropic 等，根据实际需求安装）。
• 网络提示：由于 Judgment Labs 服务托管在海外，国内开发者使用时请确保网络环境能够访问 app.judgmentlabs.ai 及相关 API 端点。目前官方暂未提供中国镜像源。

安装步骤

1. 使用 pip 安装 Judgeval SDK：

pip install judgeval

2. 配置环境变量。请登录 Judgment Cloud 注册免费账户并获取 API Key 和 Organization ID，然后在终端执行：

export JUDGMENT_API_KEY=your_api_key_here
export JUDGMENT_ORG_ID=your_org_id_here

基本使用

1. 链路追踪 (Tracing)

只需两行代码即可为现有的 LLM 调用添加可观测性，自动捕获输入、输出及 Token 消耗情况。

from judgeval import Tracer, wrap
from openai import OpenAI

# 初始化项目
Tracer.init(project_name="my-project")

# 包装 LLM 客户端以自动追踪
client = wrap(OpenAI())

@Tracer.observe(span_type="tool")
def search(query: str) -> str:
    # 模拟向量数据库搜索
    return "Context information related to " + query

@Tracer.observe(span_type="agent")
def run_agent(question: str) -> str:
    context = search(question)
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": f"{context}\n\n{question}"}],
    )
    return response.choices[0].message.content

# 运行智能体
run_agent("What is the capital of the United States?")

执行后，所有追踪数据将自动同步至您的 Judgment Dashboard 进行可视化分析。

2. 在线监控 (Online Monitoring)

在 traced 函数中异步运行评估，对生产环境的实时流量进行打分，且不会增加请求延迟。

@Tracer.observe(span_type="agent")
def run_agent(question: str) -> str:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": question}],
    )
    answer = response.choices[0].message.content

    # 异步评估答案相关性
    Tracer.async_evaluate(
        "answer_relevancy",
        {"input": question, "actual_output": answer},
    )

    return answer

3. 离线评估 (Offline Evaluation)

使用 Judgeval 客户端针对预设数据集批量运行评估（例如使用内置的“忠实度”或“答案相关性”评分器）。

from judgeval import Judgeval
from judgeval.data import Example

client = Judgeval(project_name="my-project")
evaluation = client.evaluation.create()

results = evaluation.run(
    examples=[
        Example.create(
            input="What is 2+2?",
            actual_output="4",
            expected_output="4",
        ),
    ],
    scorers=["faithfulness", "answer_relevancy"],
    eval_run_name="nightly-eval",
)

4. 自定义评分器 (Custom Judges)

您可以定义自己的评估逻辑。以下是一个简单的二元（通过/失败）评分器示例：

from judgeval.judges import Judge
from judgeval.hosted.responses import BinaryResponse
from judgeval.data import Example

class CorrectnessJudge(Judge[BinaryResponse]):
    async def score(self, data: Example) -> BinaryResponse:
        correct = data["expected_output"].lower() in data["actual_output"].lower()
        return BinaryResponse(
            value=correct,
            reason="Contains expected answer" if correct else "Missing expected answer",
        )

定义完成后，可通过 CLI 工具上传至云端安全沙箱运行：

judgeval scorer init -t binary -n CorrectnessJudge
judgeval scorer upload correctness_judge.py -p my-project