Promptfoo 把 AI 回覆、測試資料與通過條件放進同一套可重跑的評估,適合需要在改提示詞或程式後檢查退步的開發者。如果只看一次回覆,手動確認就好。這篇從已儲存的退款答案開始,帶你找出兩個錯誤、修正資料,再只重跑一筆,不必先準備模型 API 金鑰。
Windows 安裝
先準備 Node.js 22.22.0 以上;官方安裝文件建議 Node 24。在開發資料夾開啟 PowerShell,建立專案內的安裝:
node --version
mkdir refund-evals
cd refund-evals
npm init -y
npm install --save-dev promptfoo@0.125.1
npx promptfoo --version
最後應顯示 0.125.1。將 package.json、package-lock.json 和測試設定一起保留,其他人才能重建相同版本。
這裡使用 CLI,不需要註冊 MCP。用 Codex、Claude Code 或 Cursor 開啟這個資料夾後,可直接請它修改 YAML 並執行同一組指令,例如:「保留故意寫錯的退款答案,執行 eval,先說明每個斷言為什麼失敗,再提修改建議。」
為了把這個專案的評估紀錄放在一起,每次開新 PowerShell 工作階段,先執行:
$env:PROMPTFOO_CONFIG_DIR = Join-Path $PWD '.promptfoo-local'
$env:PROMPTFOO_DISABLE_TELEMETRY = '1'
第一次 eval:JSON 合法,退款金額仍可能錯
在 refund-evals 建立 promptfooconfig.yaml,貼入以下完整內容。Provider 負責提供待評估的答案;這裡的官方 echo provider會原樣回傳已存的文字。Assertion(斷言)則決定這個答案合不合格。
description: Validate saved refund replies
prompts:
- '{{saved_answer}}'
providers:
- echo
tests:
- description: valid-refund
vars:
saved_answer: '{"category":"refund","amount":120}'
assert:
- type: is-json
- type: javascript
value: JSON.parse(output).category === "refund" && JSON.parse(output).amount > 0
- description: invalid-amount
vars:
saved_answer: '{"category":"refund","amount":-1}'
assert:
- type: is-json
- type: javascript
value: JSON.parse(output).amount > 0
- description: invalid-json
vars:
saved_answer: 'Refund approved'
assert:
- type: is-json
執行評估後,立刻讀取原生命令的退出碼:
npx promptfoo eval -c promptfooconfig.yaml -o results.json --no-cache --no-share
$LASTEXITCODE
預期是 1 passed、2 failed、0 errors,下一行顯示 100。這表示工具成功抓到我們放進去的兩個錯誤。用編輯器開啟 results.json,查看各筆回覆與斷言結果。
| 測試 | 結果 | 原因 |
|---|---|---|
valid-refund |
通過 | JSON 格式正確、分類是退款、金額大於零 |
invalid-amount |
失敗 | -1 是合法 JSON 值,卻不符合退款金額規則 |
invalid-json |
失敗 | Refund approved 是句子,不是 JSON |
我們在 Windows 看到了 Custom function returned false 與 Expected output to be valid JSON。因此只檢查 is-json 抓不到負數退款。另外,第三筆只檢查 JSON,沒有金額規則;各筆測試實際檢查什麼,要看它自己的 assert。
三個能直接使用的流程
1. 檢查回覆格式與業務規則有沒有退步
修改斷言後,保留錯誤樣本再跑一次:
npx promptfoo eval -c promptfooconfig.yaml -o contract-results.json --no-cache --no-share
仍應是一通過、兩失敗。如果負數突然也通過,先查規則,不要只因總分上升就接受結果。正式退款資料還應加上必填欄位、數值型別與允許分類;上面的入門範例不是完整的帳務 schema。
2. 只重跑正在除錯的一筆
npx promptfoo eval -c promptfooconfig.yaml --filter-pattern '^valid-refund$' -o one-case.json --no-cache --no-share
$LASTEXITCODE
預期一筆通過、退出碼 0。^valid-refund$ 限定完整測試描述,日後新增相近名稱時,這次執行也不會意外多選。把 description 寫成能辨識問題的名稱,後續追查會容易很多。
3. 驗證資料修正真的改變結果
將原設定複製為 fixed.yaml。只在副本把負數 -1 改成 80,並把 Refund approved 改成 {"category":"refund","amount":80};保留原檔與所有斷言。
npx promptfoo eval -c fixed.yaml -o fixed-results.json --no-cache --no-share
$LASTEXITCODE
應看到 3 passed、0 failed、0 errors,退出碼 0。對照前後的 JSON 報告,改的是答案、規則沒有消失。請 AI 修測試時,也應保留這個區別,避免它用刪掉檢查來換取全綠。
Windows 實際遇到的錯誤與解法
libsql 缺少 Windows 原生綁定
我們曾把 Linux 安裝的依賴拿來在 Windows 執行,出現 The libsql binding for "win32-x64-msvc" is missing,訊息指出缺少 @libsql/win32-x64-msvc。在 Windows 的新專案資料夾重新安裝即可走回正確平台依賴;跨系統帶設定與 lockfile,不要直接搬整個 node_modules。其他安裝方式見官方 libsql 排錯。
執行完出現 exit 100
先讀測試摘要。官方 CLI 文件將 100 定為預設的測試失敗碼,其他執行錯誤通常是 1。PowerShell 要在 eval 後立刻讀 $LASTEXITCODE;外層腳本正常結束,不代表裡面的原生命令成功。如果團隊已設定 PROMPTFOO_FAILED_TEST_EXIT_CODE,則以該環境的值為準。
JSON 明明合法仍失敗,或離線評估要求金鑰
前者先看其餘斷言:我們的負數是金額條件失敗,不是解析失敗。後者同時檢查 provider 與所有斷言;echo 只回傳既有文字,但 llm-rubric 這類模型評分仍可能呼叫另一個模型。本例的 is-json 與 JavaScript 規則都在本機執行。
編輯器終端機的 Node 版本不對
在真正執行 eval 的終端機內輸入 node --version。低於 22.22.0 就先更新該環境的 Node,再重開終端機安裝。另一個視窗的版本正確,不能證明 AI 工具使用的終端機也相同。
費用、限制與替代工具
Promptfoo CLI 採 MIT 授權。這組 echo 與確定性斷言不產生模型 token;加入模型 provider 或模型評分後,須另看該服務的存取與費用。準備評估真正生成結果時,可接著讀官方入門文件。
通過測試只代表符合你寫下的規則,不能推導成事實正確或判斷可靠。別人的設定含 JavaScript 時,應先檢查程式內容,因為斷言會執行程式碼。
需要修補壞掉的 JSON,可以用 JSON Repair;Promptfoo 負責找出問題,不會替每筆答案修好資料。要建立有狀態的代理流程,可看 LangGraph,再用評估套件檢查其輸出。如果只有幾個一般函式測試,也不需要比較提示詞或 provider,原有測試框架可能已足夠。
FAQ
Promptfoo 怎麼安裝在 Windows?
先安裝 Node 22.22.0 以上,再在專案內執行 npm install --save-dev promptfoo@0.125.1。以 npx promptfoo --version 確認版本。依賴應在 Windows 本機安裝,才能取得對應的原生資料庫綁定。
Promptfoo 一定要 OpenAI API 金鑰嗎?
不一定,echo 可以把已存在的答案交給本機斷言評估。這適合先驗證回覆格式與業務規則,再加入模型生成。選用 API provider 或模型評分後,需求就會不同。
Promptfoo 的 exit code 100 是什麼?
它是預設的測試失敗退出碼,表示有答案未通過斷言,或通過率未達設定門檻。應看報告找出案例,不是直接重裝。本例第一輪刻意有兩筆錯誤,所以出現 100 才符合預期。
Promptfoo dataset 應該放什麼?
放有代表性的輸入或已存答案、可辨識的描述,以及明確通過條件。除了正常案例,也要保留必須被拒絕的錯誤答案。否則規則被放寬時,分數可能變好,測試卻更沒有用。
我們測了什麼
團隊於 2026-11-16 透過 Codex CLI 在 Windows 原生執行 Promptfoo 0.125.1,另有 Linux 重跑。 真實 CLI 先得到一通過兩失敗/exit 100,修正後三通過/exit 0,篩選後一筆通過。 輸入為合成的既有答案,使用 echo;未測模型生成、模型評分、紅隊掃描、雲端分享與報告 UI。 官方安裝、echo 與 CLI 文件查閱日同為 2026-11-16。