AI Agent 不該只靠感覺驗收：DeepEval 如何把 LLM 評估帶進 pytest 工作流

AI 應用最難維護的部分，往往不是把模型呼叫起來，而是回答品質在 prompt、模型、工具與檢索資料改動後悄悄漂移。傳統單元測試可以檢查函式回傳值，卻很難回答「這個答案是否忠實」、「Agent 是否真的完成任務」或「工具是否用對」。

DeepEval 的定位，是一套開源 LLM 評估框架。官方將它描述為「專門測試 LLM 應用的 pytest」：開發者以測試案例描述輸入、實際輸出、期望輸出與檢索脈絡，再用可設定門檻的 metrics 判斷一次改動是否值得合併。這個設計讓評估從一次性的人工抽查，變成可以放進開發流程的品質閘門。

本文不把 DeepEval 當成單純的 metrics 清單，而是從它的使用介面與官方原始碼說明，拆解一條可落地的路徑：先測黑箱輸出，再追蹤 Agent 軌跡，最後把資料集、指標與 CI 整合成可重複的回歸測試。

為什麼一般測試不足以驗收 AI 應用

LLM 應用的輸出不是穩定的固定字串。即使輸入相同，模型也可能因版本、取樣設定、工具回應或上下文變化而產生不同措辭。因此，這類測試通常不應只比較字串相等，而要把品質拆成可解釋的判準：

正確性：答案是否符合期望答案。
相關性：回答有沒有直接處理使用者問題。
忠實性：RAG 回答是否能由檢索到的內容支持。
任務完成度：Agent 是否真的達成目標，而不只是產生看似合理的文字。
工具正確性：是否呼叫正確工具，以及參數是否正確。
步驟效率：是否繞了不必要的路徑，浪費模型與工具成本。

這些判準仍然需要接受評估模型或其他 NLP／統計方法的判斷，所以它們不是「絕對正解」。真正的工程重點，是固定測試資料、保存評估結果，並用 threshold 把團隊對可接受品質的共識寫進程式碼。

DeepEval 的核心模型：Test Case 加上 Metric

DeepEval 的基本資料結構是 LLMTestCase。最小案例可以包含 input 與 actual_output；若要做更有意義的比較，則再加入 expected_output 與 retrieval_context。Metric 負責定義如何評分，threshold 負責定義通過線。

以下是官方 README 的最小化概念範例，使用 GEval 判斷實際答案是否符合期望答案：

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


def test_customer_support_answer():
    correctness = 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,
    )

    case = LLMTestCase(
        input="What if these shoes do not fit?",
        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(case, [correctness])

這段程式有三個值得注意的邊界。第一，actual_output 應該來自真正的應用程式，而不是在測試裡重新寫一個理想答案。第二，criteria 是產品品質定義的一部分，越具體越容易讓團隊理解失敗原因。第三，threshold=0.5 不是框架替你決定的真理，而是目前這個產品情境的接受門檻；正式導入前應用代表性資料集校準它。

從黑箱測試開始，而不是一開始就重寫應用程式

DeepEval 的黑箱測試方式適合已經存在的 chatbot 或 RAG pipeline。你不必先把整個程式改成特定框架，只要在測試案例中餵入真實輸入，呼叫應用程式，然後把輸出交給 metrics。

安裝與執行方式如下：

python -m pip install -U deepeval
export OPENAI_API_KEY="在本機環境設定"
deepeval test run test_chatbot.py

OPENAI_API_KEY 只是官方 quickstart 使用的 provider 範例；DeepEval README 也說明可以改用自訂 LLM，或使用在本機執行的 NLP 模型與其他評估方法。不要把金鑰寫入測試檔或 CI log，應交給 secret manager 或環境變數管理。

實務上，可以把測試分成三層：

Smoke eval：少量固定案例，在每個 pull request 執行，快速捕捉 prompt 或工具介面破壞。
Regression eval：較完整的 golden dataset，在合併或發布前執行，觀察多個 metrics 是否退化。
Offline／production review：把匿名化的真實失敗案例加入資料集，定期檢查資料漂移與新型錯誤。

這樣的分層比「所有案例每次都跑」更容易控制成本，也能把阻塞式檢查與較慢的深度評估分開。

RAG 不只要看答案，還要看它依據什麼

RAG 系統常見的錯誤，是答案讀起來流暢，卻沒有被檢索內容支持。只測 actual_output 會漏掉這個問題，因此測試案例應保存 retrieval_context，再搭配不同面向的 metrics：

Answer Relevancy 檢查回答是否回應問題。
Faithfulness 檢查回答是否與檢索脈絡一致。
Contextual Recall 檢查必要資訊是否被取回。
Contextual Precision 檢查相關節點是否排在較前面。
Contextual Relevancy 檢查整體檢索脈絡是否與問題相關。

這種拆分能把「生成錯」與「檢索錯」分開。若 faithfulness 下降，優先檢查 chunking、metadata filter 與 retriever；若 context precision 下降，則應檢查排序與召回策略，而不是先改 prompt。

Agent 評估的關鍵是整條軌跡

對 Agent 來說，最後一句文字不是完整結果。Agent 可能先查資料、呼叫工具、重試、轉交子 Agent，最後才產生回覆。DeepEval README 提供 observe、update_current_span 與 trace 等 tracing 介面，讓這些中間步驟可以被收集，再用 trajectory-based metrics 評估完整路徑。

概念上可以這樣分工：

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


@observe()
def retrieve_customer_policy(question: str) -> str:
    result = "policy result"
    update_current_span(
        test_case=LLMTestCase(input=question, actual_output=result)
    )
    return result


@observe()
def support_agent(question: str) -> str:
    policy = retrieve_customer_policy(question)
    return f"Answer based on: {policy}"


# 在 dataset.evals_iterator(metrics=[TaskCompletionMetric()]) 中執行 support_agent。

對應的評估問題就不再只是「回答像不像人」，而是：

Agent 有沒有完成使用者目標？
是否呼叫了正確工具？
工具參數是否符合預期？
是否走了不必要的步驟？
是否遵守預先定義的計畫？

官方列出的 agentic metrics 包含 Task Completion、Tool Correctness、Goal Accuracy、Step Efficiency、Plan Adherence、Plan Quality、Tool Use 與 Argument Correctness。團隊不需要一次全部採用，應先針對最昂貴或最危險的失敗模式建立一到兩個指標。

評估模型本身也要被治理

LLM-as-a-judge 能快速把主觀品質轉成分數，但它會帶來新的偏差：評估模型可能偏好較長答案、對某種語氣有偏好，或在特定領域知識不足。因此，DeepEval 應被視為測試執行器與框架，不是品質真相的自動販賣機。

導入時建議做四件事：

用人工標註的小型資料集校準 metric 分數與 threshold。
對高風險案例保留人工審核，不用單一自動分數放行。
固定評估模型、提示與資料版本，讓不同批次結果可比較。
把失敗案例與評估理由寫回報告，避免只看平均分數。

DeepEval 支援使用自訂 LLM，也提供本機模型與統計／NLP 方法的路徑。這讓敏感資料不必全部送到外部服務，但仍要自行驗證本機 evaluator 的準確度與成本。

如何放進 CI，而不是停在開發者筆電

一個可行的 CI 閘門可以是：

name: llm-eval

on: [pull_request]

jobs:
  eval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: python -m pip install -U deepeval
      - run: deepeval test run tests/evals/test_chatbot.py
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

這個範例只展示流程，實際設定還需要處理資料集版本、網路重試、評估成本與敏感輸入遮罩。更穩健的做法是讓 pull request 執行小型 deterministic／低成本集合，夜間或發布候選版本再執行完整 trajectory eval。

CI 結果也不應只有 pass／fail。至少要保存每個 metric 的分數、threshold、使用的模型與 dataset commit，才能回答「這次是答案品質下降，還是 evaluator 改了」這類回溯問題。

什麼情況適合採用 DeepEval

DeepEval 特別適合以下情境：

已有 RAG、chatbot 或 Agent，開始需要回歸測試。
團隊想把模型、prompt、retriever 的改動放進同一套品質流程。
需要針對工具呼叫、Agent trajectory 或 MCP 使用方式建立檢查。
希望以 Python 測試檔與 CLI 接入現有 pytest／CI 習慣。

但它不是資料標註平台的替代品，也不是 observability 系統的完整替代品。若團隊尚未定義「什麼是好答案」，先整理失敗案例與人工標註規則，比立刻安裝更多 metrics 更重要。

結語：讓 AI 品質成為可回歸的工程資產

DeepEval 最有價值的地方，不只是提供一長串評估指標，而是把 LLM 應用品質接到開發者熟悉的測試心智模型：用 LLMTestCase 描述案例，用 metric 表達品質，用 threshold 形成閘門，再用 tracing 看見 Agent 的完整行為。

從一個正確性案例開始，接著補上 RAG 的 faithfulness 與 context 指標，最後才加入任務完成度與工具正確性，這條漸進路徑比一次建立巨型評估平台更容易維護。當每次 prompt、模型或架構變更都能產生可比較的證據，AI 應用才真正擁有接近一般軟體工程的回歸能力。

延伸閱讀與來源

> 研究快照：GitHub API 查詢於 2026-09-02。當時專案為 Apache-2.0 授權，約 18,048 顆 stars，最近推送時間為 2026-09-02。版本與功能可能隨後續提交變動，採用前請以官方 repository 與文件為準。