第三方工具更新 2026.11.20

Promptfoo 教學:Windows 安裝、第一次 eval 與 exit 100 解法

在 Windows 安裝 Promptfoo,使用完整 YAML 檢查退款答案,重現 exit 100、修正後全通過,並解決 libsql 原生依賴問題。

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。

訂閱 AI 工具精選與使用建議

有值得推薦的新工具、實測發現或重要更新時,寄到你的信箱。

訂閱後先寄給你一份每月更新的 AI 工具與 Skill 清單。有值得推薦的工具、實測發現或重要更新時才寄信,隨時可以退訂。隱私權說明

快完成了,請到信箱收確認信點信裡的按鈕確認訂閱,就會收到工具清單的下載連結。沒看到的話,看一下垃圾郵件或「促銷內容」分頁。

看過去幾期

也可以在這些平台追蹤: