judgeval

环境要求

• Python 环境（可通过 pip 安装依赖）
• OpenAI API 可用（示例使用 gpt-4o-mini，需自行配置访问凭证）
• 从 Judgment Labs 获取 JUDGMENT_API_KEY
• 从 Judgment Labs 获取 JUDGMENT_ORG_ID

安装与启动步骤

1. 1安装 SDK

   在终端执行 pip 安装 judgeval，建议在独立虚拟环境中安装以避免依赖冲突。

   pip install judgeval

   复制

2. 2设置凭证

   从 Judgment Labs 控制台获取 API Key 与组织 ID，写入环境变量，供 SDK 自动读取。

   export JUDGMENT_API_KEY=sk-xxxxxxxx
   export JUDGMENT_ORG_ID=your-org-id

   复制

3. 3初始化 Tracer

   在代码入口调用 Tracer.init 并指定项目名，所有追踪数据会归到该项目下。

   from judgeval import Tracer
   
   Tracer.init(project_name="my-project")

   复制

4. 4包装 OpenAI 客户端

   用 wrap 包装 OpenAI 客户端，SDK 会自动采集模型调用、输入输出与 token 用量。

   from openai import OpenAI
   from judgeval import wrap
   
   client = wrap(OpenAI())

   复制

5. 5装饰业务函数

   用 @Tracer.observe 装饰需要观测的函数，并用 span_type 标明它是工具还是 Agent。

   @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

   复制

6. 6运行并上报追踪

   执行一次 Agent 调用，数据会自动上报到平台，可在仪表盘中查看运行轨迹。

   run_agent("What is the capital of the United States?")

   复制

关键配置

如何确认成功

运行 run_agent 后无报错返回结果，并能在 Judgment Labs 仪表盘对应项目下看到该次运行的追踪记录。

常见问题

注意事项

• README 中的 export 写法为占位符，请替换为真实密钥与组织 ID，不要提交到代码仓库。
• 示例用 vector_db 是未定义的占位变量，实际使用时需替换为你自己的检索实现。
• Tracer.init 建议只调用一次，重复调用可能产生非预期的项目归属。
• 更多用法请查阅官方文档 docs.judgmentlabs.ai。