confident-ai--deepeval/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

LLM 评估框架

文档 | 指标与功能 | 快速开始 | 集成 | Confident AI

Deutsch | Español | français | 日本語 | 한국어 | Português | Русский | 中文

DeepEval 是一个简单易用的开源 LLM 评估框架，用于评估大语言模型系统。它类似于 Pytest，但专门用于对 LLM 应用进行单元测试。DeepEval 融入了最新研究，可通过 G-Eval、任务完成度（task completion）、答案相关性（answer relevancy）、幻觉（hallucination）等指标运行评估，这些指标使用 LLM-as-a-judge 以及可在你本地机器上运行的其他 NLP 模型。

无论你是在构建 AI 智能体、RAG 流水线还是聊天机器人，无论通过 LangChain 还是 OpenAI 实现，DeepEval 都能满足你的需求。借助它，你可以轻松确定最优的模型、提示词和架构，以提升 AI 质量、防止提示词漂移（prompt drifting），甚至自信地从 OpenAI 迁移到 Claude。

Important

需要为你的 DeepEval 测试数据找个安身之所 🏡❤️？注册 Confident AI，比较你的 LLM 应用各次迭代、生成并分享测试报告，等等。

想讨论 LLM 评估、需要帮忙选择指标，或者只想打个招呼？来加入我们的 Discord。

🔥 指标与功能

• 📐 大量开箱即用的 LLM 评估指标（均附带说明），由你选择的任意 LLM、统计方法或在你本地机器上运行的 NLP 模型驱动，覆盖所有使用场景：

  • 自定义通用指标：

    • G-Eval — 基于研究的 LLM-as-a-judge 指标，可按任意自定义标准评估，具备接近人类的准确度
    • DAG — DeepEval 基于图结构的确定性 LLM-as-a-judge 指标构建器
  • 智能体指标

    • Task Completion — 评估智能体是否完成了其目标
    • Tool Correctness — 检查是否以正确参数调用了正确的工具
    • Goal Accuracy — 衡量智能体达成预期目标的准确程度
    • Step Efficiency — 评估智能体是否采取了不必要的步骤
    • Plan Adherence — 检查智能体是否遵循了预期计划
    • Plan Quality — 评估智能体计划的质量
    • Tool Use — 衡量工具使用的质量
    • Argument Correctness — 验证工具调用参数的正确性
  • RAG 指标

    • Answer Relevancy — 衡量 RAG 流水线输出与输入的相关程度
    • Faithfulness — 评估 RAG 流水线输出是否在事实上与检索上下文一致
    • Contextual Recall — 衡量 RAG 流水线检索上下文与预期输出的匹配程度
    • Contextual Precision — 评估 RAG 流水线检索上下文中相关节点是否排名更高
    • Contextual Relevancy — 衡量 RAG 流水线检索上下文与输入的整体相关程度
    • RAGAS — 答案相关性、忠实度、上下文精确度与上下文召回率的平均值
  • 多轮对话指标

    • Knowledge Retention — 评估聊天机器人在整个对话过程中是否保留事实信息
    • Conversation Completeness — 衡量聊天机器人在整个对话过程中是否满足用户需求
    • Turn Relevancy — 评估聊天机器人在整个对话过程中是否持续生成相关回复
    • Turn Faithfulness — 检查聊天机器人在各轮对话中的回复是否在事实上基于检索上下文
    • Role Adherence — 评估聊天机器人在整个对话过程中是否恪守其指定角色
  • MCP 指标

    • MCP Task Completion — 评估基于 MCP 的智能体完成任务的有效性
    • MCP Use — 衡量智能体使用其可用 MCP 服务器的有效性
    • Multi-Turn MCP Use — 评估跨对话轮次的 MCP 服务器使用情况

• 多模态指标（Multimodal Metrics）

  • 文生图（Text to Image） — 基于语义一致性和感知质量评估图像生成质量
  • 图像编辑（Image Editing） — 基于语义一致性和感知质量评估图像编辑质量
  • 图像连贯性（Image Coherence） — 衡量图像与其伴随文本的对齐程度
  • 图像有用性（Image Helpfulness） — 评估图像对用户理解文本的有效贡献程度
  • 图像引用（Image Reference） — 评估伴随文本对图像的引用或解释是否准确
• 其他指标（Other Metrics）

  • 幻觉（Hallucination） — 检查 LLM 是否根据提供的上下文生成事实正确的信息
  • 摘要（Summarization） — 评估摘要是否事实正确并包含必要细节
  • 偏见（Bias） — 检测 LLM 输出中的性别、种族或政治偏见
  • 毒性（Toxicity） — 评估 LLM 输出中的毒性
  • JSON 正确性（JSON Correctness） — 检查输出是否符合预期的 JSON schema
  • 提示对齐（Prompt Alignment） — 衡量输出是否与提示模板中的指令一致

• 🎯 同时支持端到端和组件级 LLM 评估。

• 🧩 构建你自己的自定义指标，并自动集成到 DeepEval 生态系统中。

• 🔮 生成用于评估的单轮和多轮合成数据集。

• 🔗 可与任意 CI/CD 环境无缝集成。

• 🧬 根据评估结果自动优化提示词。

• 🏆 轻松在热门 LLM 基准测试上评测任意 LLM，仅需不到 10 行代码。, 包括 MMLU、HellaSwag、DROP、BIG-Bench Hard、TruthfulQA、HumanEval、GSM8K。

🔌 集成

DeepEval 可接入任意 LLM 框架——OpenAI Agents、LangChain、CrewAI 等。若要在团队中扩展评估规模，或让任何人无需编写代码即可运行评估，Confident AI 提供原生平台集成。

框架

• OpenAI — 通过客户端包装器评估并追踪 OpenAI 应用
• OpenAI Agents — 在一分钟内端到端评估 OpenAI Agents
• LangChain — 使用回调处理器评估 LangChain 应用
• LangGraph — 使用回调处理器评估 LangGraph 智能体
• Pydantic AI — 使用类型安全验证评估 Pydantic AI 智能体
• CrewAI — 评估 CrewAI 多智能体系统
• Anthropic — 通过客户端包装器评估并追踪 Claude 应用
• AWS AgentCore — 评估部署在 Amazon AgentCore 上的智能体
• LlamaIndex — 评估使用 LlamaIndex 构建的 RAG 应用

☁️ 平台与生态

Confident AI 是与 DeepEval 原生集成的全合一平台。

• 在同一平台上管理数据集、追踪 LLM 应用、运行评估并监控生产环境中的响应。
• 不需要 UI？Confident AI 也可作为数据持久化层——运行评估、拉取数据集，并通过 Confident AI 的 MCP server. 直接从 claude code、cursor 中检查追踪记录

🤖 Vibe-Coder 快速入门

希望你的编程智能体为你添加评估并修复失败项？安装 DeepEval skill，将其指向你的智能体、RAG 流水线或聊天机器人，然后让它生成数据集、编写评估套件、运行 deepeval test run，并对失败的指标进行迭代。

从 5 分钟 vibe-coder 指南开始.

🚀 人工快速入门

假设你的 LLM 应用是一个基于 RAG 的客户支持聊天机器人；下面介绍 DeepEval 如何帮助你测试所构建的内容。

安装

Deepeval 适用于 Python>=3.9+。

pip install -U deepeval

创建账户（强烈推荐）

使用 deepeval 平台可让你在云端生成可分享的测试报告。它免费、无需额外代码即可设置，我们强烈建议你试一试。

要登录，请运行：

deepeval login

按照 CLI 中的说明创建账户、复制 API 密钥并将其粘贴到 CLI 中。所有测试用例将自动记录（有关数据隐私的更多信息请见此处).

编写你的第一个测试用例

创建测试文件：

touch test_chatbot.py

打开 test_chatbot.py 并编写你的第一个测试用例，使用 DeepEval 运行端到端评估，将 LLM 应用视为黑盒：

import pytest
from deepeval import assert_test
from deepeval.metrics import GEval
from deepeval.test_case import LLMTestCase, SingleTurnParams

def test_case():
    correctness_metric = GEval(
        name="Correctness",
        criteria="Determine if the 'actual output' is correct based on the 'expected output'.",
        evaluation_params=[SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT],
        threshold=0.5
    )
    test_case = LLMTestCase(
        input="What if these shoes don't fit?",
        # Replace this with the actual output from your LLM application
        actual_output="You have 30 days to get a full refund at no extra cost.",
        expected_output="We offer a 30-day full refund at no extra costs.",
        retrieval_context=["All customers are eligible for a 30 day full refund at no extra costs."]
    )
    assert_test(test_case, [correctness_metric])

将你的 OPENAI_API_KEY 设置为环境变量（你也可以使用自己的自定义模型进行评估，更多详情请访问我们文档的这一部分):

export OPENAI_API_KEY="..."

最后，在 CLI 中运行 test_chatbot.py：

deepeval test run test_chatbot.py

恭喜！你的测试用例应该已通过 ✅ 让我们来分解一下发生了什么。

• 变量 input 模拟用户输入，actual_output 是根据该输入你的应用应输出的内容的占位符。
• 变量 expected_output 表示给定 input 的理想答案，GEval 是 deepeval 提供的、基于研究的指标，可让你以接近人类的准确度在任何自定义场景上评估 LLM 输出。
• 在此示例中，指标 criteria 是基于所提供的 expected_output 的 actual_output 正确性。
• 所有指标得分范围为 0 - 1，threshold=0.5 阈值最终决定你的测试是否通过。

阅读我们的文档 了解更多信息！

具备完整可追溯性的评估（Evals）

使用 evals_iterator() 在你的应用中用同一数据集运行评估，无论你采用手动埋点还是通过 DeepEval 的某一框架集成。

下面是手动埋点的示例：

from deepeval.tracing import observe, update_current_span
from deepeval.test_case import LLMTestCase
from deepeval.metrics import TaskCompletionMetric

@observe()
def inner_component(input: str):
    output = "result"
    update_current_span(test_case=LLMTestCase(input=input, actual_output=output))
    return output

@observe()
def app(input: str):
    return inner_component(input)

# This metric will be run on your trace end to end.
for golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):
    app(golden.input)

OpenAI

from deepeval.openai import OpenAI
from deepeval.tracing import trace
from deepeval.metrics import TaskCompletionMetric

client = OpenAI()

# This metric will be run on your trace end to end.
for golden in dataset.evals_iterator():
    with trace(metrics=[TaskCompletionMetric()]):
        client.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": golden.input}],
        )

OpenAI Agents

from agents import Runner
from deepeval.metrics import TaskCompletionMetric

# This metric will be run on your trace end to end.
for golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):
    Runner.run_sync(agent, golden.input)

Anthropic

from deepeval.anthropic import Anthropic
from deepeval.tracing import trace
from deepeval.metrics import TaskCompletionMetric

client = Anthropic()

# This metric will be run on your trace end to end.
for golden in dataset.evals_iterator():
    with trace(metrics=[TaskCompletionMetric()]):
        client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": golden.input}],
        )

LangChain

from deepeval.integrations.langchain import CallbackHandler
from deepeval.metrics import TaskCompletionMetric

# This metric will be run on your trace end to end.
for golden in dataset.evals_iterator():
    llm.invoke(
        golden.input,
        config={"callbacks": [CallbackHandler(metrics=[TaskCompletionMetric()])]},
    )

LangGraph

from deepeval.integrations.langchain import CallbackHandler
from deepeval.metrics import TaskCompletionMetric

# This metric will be run on your trace end to end.
for golden in dataset.evals_iterator():
    agent.invoke(
        {"messages": [{"role": "user", "content": golden.input}]},
        config={"callbacks": [CallbackHandler(metrics=[TaskCompletionMetric()])]},
    )

Pydantic AI

from deepeval.metrics import TaskCompletionMetric

# This metric will be run on your trace end to end.
for golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):
    agent.run_sync(golden.input)

CrewAI

from deepeval.integrations.crewai import instrument_crewai
from deepeval.metrics import TaskCompletionMetric

instrument_crewai()

# This metric will be run on your trace end to end.
for golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):
    crew.kickoff({"input": golden.input})

AWS AgentCore

from deepeval.integrations.agentcore import instrument_agentcore
from deepeval.metrics import TaskCompletionMetric

instrument_agentcore()

# This metric will be run on your trace end to end.
for golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):
    invoke({"prompt": golden.input})

LlamaIndex

import asyncio
from deepeval.evaluate.configs import AsyncConfig
from deepeval.metrics import TaskCompletionMetric

# This metric will be run on your trace end to end.
for golden in dataset.evals_iterator(
    async_config=AsyncConfig(run_async=True),
    metrics=[TaskCompletionMetric()],
):
    task = asyncio.create_task(agent.run(golden.input))
    dataset.evaluate(task)

Google ADK

import asyncio
from deepeval.evaluate.configs import AsyncConfig
from deepeval.integrations.google_adk import instrument_google_adk
from deepeval.metrics import TaskCompletionMetric

instrument_google_adk()

# This metric will be run on your trace end to end.
for golden in dataset.evals_iterator(
    async_config=AsyncConfig(run_async=True),
    metrics=[TaskCompletionMetric()],
):
    task = asyncio.create_task(run_agent(golden.input))
    dataset.evaluate(task)

Strands

from deepeval.integrations.strands import instrument_strands
from deepeval.metrics import TaskCompletionMetric

instrument_strands()

# This metric will be run on your trace end to end.
for golden in dataset.evals_iterator(metrics=[TaskCompletionMetric()]):
    agent(golden.input)

了解更多组件级评估信息，请点击此处。

不使用 Pytest 集成的评估方式

或者，你也可以在不使用 Pytest 的情况下进行评估，这种方式更适合 notebook 环境。

from deepeval import evaluate
from deepeval.metrics import AnswerRelevancyMetric
from deepeval.test_case import LLMTestCase

answer_relevancy_metric = AnswerRelevancyMetric(threshold=0.7)
test_case = LLMTestCase(
    input="What if these shoes don't fit?",
    # Replace this with the actual output from your LLM application
    actual_output="We offer a 30-day full refund at no extra costs.",
    retrieval_context=["All customers are eligible for a 30 day full refund at no extra costs."]
)
evaluate([test_case], [answer_relevancy_metric])

使用独立指标（Metrics）

DeepEval 具有极高的模块化程度，任何人都能轻松使用我们的任一指标。接续上一个示例：

from deepeval.metrics import AnswerRelevancyMetric
from deepeval.test_case import LLMTestCase

answer_relevancy_metric = AnswerRelevancyMetric(threshold=0.7)
test_case = LLMTestCase(
    input="What if these shoes don't fit?",
    # Replace this with the actual output from your LLM application
    actual_output="We offer a 30-day full refund at no extra costs.",
    retrieval_context=["All customers are eligible for a 30 day full refund at no extra costs."]
)

answer_relevancy_metric.measure(test_case)
print(answer_relevancy_metric.score)
# All metrics also offer an explanation
print(answer_relevancy_metric.reason)

请注意，部分指标适用于 RAG 流水线，另一些则适用于微调（fine-tuning）。请务必查阅我们的文档，为你的使用场景选择合适的指标。

关于环境变量（.env / .env.local）的说明

DeepEval 会在导入时从当前工作目录自动加载 .env.local，随后加载 .env。 优先级： 进程环境变量 -> .env.local -> .env。 可使用 DEEPEVAL_DISABLE_DOTENV=1 选择退出。

cp .env.example .env.local
# then edit .env.local (ignored by git)

将 DeepEval 与 Confident AI 配合使用

Confident AI 是一个一体化平台，用于管理数据集、追踪 LLM 应用，并在生产环境中运行评估。通过 CLI 登录即可开始使用：

deepeval login

然后像往常一样运行测试——结果会自动同步到平台：

deepeval test run test_chatbot.py

想一直待在 IDE 里？通过 Confident AI 的 MCP server 作为持久层来运行评测、拉取数据集并检查 trace，无需离开编辑器即可使用 DeepEval。

Confident AI 上的全部内容可在此处.

贡献

请阅读 CONTRIBUTING.md，了解我们的行为准则以及向我们提交 Pull Request 的流程详情。

路线图

功能特性：

• 与 Confident AI 集成
• 实现 G-Eval
• 实现 RAG 指标
• 实现对话（Conversational）指标
• 评测数据集创建
• 红队测试（Red-Teaming）
• DAG 自定义指标
• Guardrails（护栏）

作者

由 Confident AI 创始人打造。如有任何咨询，请联系 jeffreyip@confident-ai.com。

许可证

DeepEval 采用 Apache 2.0 许可证——详见 LICENSE.md 文件。