Hướng dẫn Promptfoo: Thực hành đánh giá LLM từng bước

Hầu hết các tính năng LLM thường được kiểm tra theo cùng một cách: thử vài đầu vào, nhìn lướt đầu ra, rồi triển khai.

Bạn đã làm vậy với một công cụ viết email. Năm đầu vào trong cửa sổ chat, đầu ra trông ổn. Một tuần sau, một nửa email giọng điệu thân mật của bạn nghe như được viết bởi một luật sư công ty. Không ai phát hiện vì không có cách nào để phát hiện. Prompt đã thay đổi, nhưng năm bài kiểm tra thủ công đó không đi cùng bạn.

Promptfoo là một CLI mã nguồn mở thay thế quy trình đó bằng các đánh giá có cấu trúc và có thể lặp lại. Bạn định nghĩa thế nào là đầu ra tốt, chọn mô hình, và chạy tự động mọi kết hợp. 

OpenAI mua lại dự án vào tháng 3/2026, và dự án vẫn theo giấy phép MIT với hỗ trợ cho hàng chục nhà cung cấp. Hơn 350.000 nhà phát triển sử dụng, bao gồm các đội ngũ tại hơn 25% công ty Fortune 500.

Hướng dẫn này sẽ dẫn bạn thiết lập Promptfoo và xây dựng bộ đánh giá đầu tiên từ con số 0. Chúng ta sẽ dùng ví dụ xuyên suốt là công cụ viết email, kiểm thử trên GPT-5 và Claude Sonnet 4.6, và kết nối tất cả vào GitHub Actions ở cuối.

Đánh giá LLM trong 60 giây

Trước khi đi vào công cụ, bạn cần biết cách kiểm thử LLM hoạt động ra sao. Nó khác với kiểm thử mã thông thường.

Nếu từng kiểm thử một hàm, bạn biết cách làm: đưa vào một đầu vào, kiểm tra đầu ra có khớp kỳ vọng. Đầu ra LLM thì không như vậy. Cùng một prompt có thể tạo ra văn bản khác nhau mỗi lần chạy, nên bạn không thể kiểm tra khớp tuyệt đối.

Thay vào đó, bạn kiểm tra các thuộc tính của đầu ra:

• Nó có chứa đúng thông tin không?
• Giọng điệu có phù hợp không?
• Phản hồi có đủ nhanh không?

Đó là điều một đánh giá LLM thực hiện. Nó chạy prompt của bạn với một tập đầu vào và kiểm tra từng đầu ra theo các quy tắc bạn định nghĩa. Hãy coi nó là bộ kiểm thử cho prompt thay vì cho mã.

Bốn thuật ngữ sẽ xuất hiện xuyên suốt bài viết:

• Provider là API mô hình bạn đang kiểm thử, như GPT-5.4 hoặc Claude Opus 4.6.
• Test case là một đầu vào đi kèm với hành vi bạn kỳ vọng ở đầu ra.
• Assertion là một quy tắc đơn lẻ mà đầu ra phải vượt qua, như "chứa từ Friday" hoặc "phản hồi dưới 30 giây".
• Rubric là hướng dẫn chấm điểm bằng ngôn ngữ tự nhiên bạn đưa cho một LLM khác khi kiểm tra quá chủ quan để so khớp chuỗi, như email có thực sự nghe thân mật hay không.

Không có assertion, bạn lại quay về kiểu "trông ổn với tôi". Có assertion, bạn có định nghĩa "đúng" chạy y hệt mỗi lần.

Promptfoo là gì?

Giờ bạn đã biết eval là gì, đây là cách Promptfoo làm với nó.

Bạn đưa cho Promptfoo ba thứ:

• Các mẫu prompt của bạn
• Các mô hình bạn muốn kiểm thử
• Các test case với assertion

Nó chạy mọi prompt với mọi mô hình cho mỗi test case và chấm điểm kết quả. Một lệnh promptfoo eval chạy toàn bộ.

Giả sử bạn có một prompt viết email, hai mô hình (GPT-5 và Claude Sonnet 4), và ba test case (thân mật, trang trọng, khẩn cấp). Promptfoo chạy cả sáu kết hợp và cho bạn biết cái nào đạt, cái nào trượt. Không còn việc thử thủ công từng cái nữa.

Toàn bộ eval nằm trong một tệp YAML duy nhất tên promptfooconfig.yaml mà bạn quản lý phiên bản cùng với mã. Promptfoo chạy trên máy của bạn: cấu hình, kết quả, và bộ nhớ đệm đều ở cục bộ. Các cuộc gọi bên ngoài duy nhất là tới API mô hình như OpenAI hay Anthropic, vốn bạn sẽ gọi dù có hay không có Promptfoo.

Có những công cụ khác trong lĩnh vực này, như DeepEval (thuần Python, kiểu pytest), LangSmith (giám sát vận hành cho LangChain), và Braintrust (bảng điều khiển nhóm). Promptfoo là điểm khởi đầu tốt nhất vì miễn phí, chạy cục bộ, và giúp bạn từ con số 0 đến một eval chạy được nhanh hơn bất kỳ cái nào.

Thiết lập môi trường Promptfoo

Cài Promptfoo toàn cục và khởi tạo dự án mới:

npm install -g promptfoo
mkdir email-writer-eval
cd email-writer-eval
promptfoo initĐược hỗ trợ bởi

Lệnh init hướng dẫn bạn qua phần thiết lập tương tác. Nó hỏi bạn muốn làm gì (chọn "Not sure yet") và dùng nhà cung cấp mô hình nào (chọn "[OpenAI] GPT 5, GPT 4.1, ...").

Khi hoàn tất, bạn sẽ có hai tệp: một promptfooconfig.yaml mẫu và một README.md.

Tiếp theo, thiết lập khóa API. Bạn cần ít nhất một khóa để chạy eval (cần cả hai để theo dõi trọn vẹn hướng dẫn này):

• OpenAI: Lấy khóa trong bảng điều khiển OpenAI
• Anthropic: Lấy khóa trong bảng điều khiển Anthropic

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...Được hỗ trợ bởi

Nếu bạn chỉ đặt ANTHROPIC_API_KEY và bỏ qua OpenAI, Promptfoo sẽ tự động dùng Claude làm nhà cung cấp chấm điểm cho các assertion hỗ trợ bởi mô hình như llm-rubric.

Mở tệp promptfooconfig.yaml được tạo. Mọi cấu hình Promptfoo có ba khối xây dựng:

• prompts là nơi đặt các mẫu prompt của bạn. Placeholder ngoặc kép kép như {{variable}} được điền từ từng test case. 

• providers liệt kê các mô hình bạn muốn kiểm thử. 

• tests định nghĩa đầu vào và các assertion quyết định mỗi đầu ra đạt hay trượt.

prompts:
  - \"Your prompt template with {{variable}}\"
...
 
providers:
  - openai:chat:gpt-5
...
 
tests:
  - vars:
      variable: \"test input\"
    assert:
      - type: contains
        value: \"expected substring\"Được hỗ trợ bởi

Cấu hình mẫu này là điểm khởi đầu. Phần tiếp theo sẽ thay thế nó bằng một đánh giá thực tế và giải thích chi tiết cấu trúc YAML.

Xây dựng đánh giá đầu tiên của bạn

Nhiệm vụ như sau: dựa trên các gạch đầu dòng và một giọng điệu (thân mật, trang trọng, hoặc khẩn cấp), viết một email. Bạn sẽ xây dựng một eval kiểm thử điều này trên hai mô hình.

Toàn bộ cấu hình có sẵn dưới dạng Gist nếu bạn muốn xem một lần. Chúng ta sẽ xây dựng từng phần bên dưới.

Prompt và providers

Xóa mẫu được tạo và tạo mới promptfooconfig.yaml. Bắt đầu với prompt và providers:

description: \"Email writer evaluation\"
 
prompts:
  - |
    Draft an email based on these bullet points.
    Match the specified tone throughout the email.
 
    Bullet points:
    {{bullet_points}}
 
    Tone: {{tone}}
 
providers:
  - id: openai:chat:gpt-5
    label: \"GPT-5\"
  - id: anthropic:messages:claude-sonnet-4-6
    label: \"Claude Sonnet 4.6\"Được hỗ trợ bởi

Mẫu prompt có hai placeholder: {{bullet_points}} và {{tone}}. Mỗi test case điền chúng bằng giá trị khác nhau. Trường label trên mỗi provider giúp bạn có tiêu đề cột dễ đọc trong phần kết quả thay vì ID mô hình thô.

Khối defaultTest

Tiếp theo, thêm khối defaultTest. Các assertion trong defaultTest áp dụng cho mọi test case tự động, nên bạn không phải lặp lại:

defaultTest:
  assert:
    - type: latency
      threshold: 30000Được hỗ trợ bởi

Điều này sẽ đánh trượt mọi phản hồi chậm hơn 30 giây. Các mô hình tiên tiến như GPT-5 có thể mất 10–20 giây mỗi yêu cầu do token suy luận, nên ngưỡng cần dư địa. Bạn đặt một lần là áp dụng cho mọi test.

Test case

Giờ thêm các test case. Mỗi cái cung cấp đầu vào khác nhau và assertion riêng:

tests:
  - vars:
      bullet_points: |
        - Recap of the design review decisions
        - Next steps: finalize mockups by Thursday
        - Ask if anyone has questions
      tone: \"casual\"
    assert:
      - type: icontains
        value: \"mockups\"
      - type: llm-rubric
        value: \"The email uses a casual tone with contractions and short sentences\"
 
  - vars:
      bullet_points: |
        - Q1 revenue exceeded targets by 12%
        - New enterprise client onboarded
        - Hiring plan for Q2 approved
      tone: \"formal\"
    assert:
      - type: icontains
        value: \"Q1\"
      - type: llm-rubric
        value: \"The email maintains a formal, professional tone throughout\"
 
  - vars:
      bullet_points: |
        - API migration deadline is Friday at 5pm
        - Three endpoints still need updating
        - Downtime window is Saturday 2-6am
      tone: \"urgent\"
    assert:
      - type: icontains
        value: \"Friday\"
      - type: llm-rubric
        value: \"The email conveys urgency with direct language and clear action items\"Được hỗ trợ bởi

Mỗi test case ghép đôi hai loại assertion. 

icontains là kiểm tra chuỗi đơn giản: đầu ra có chứa "mockups" không, không phân biệt hoa thường? Nhanh, miễn phí, không gọi API. 

llm-rubric gửi đầu ra đến một LLM khác và yêu cầu chấm theo rubric của bạn. Tốn token, nhưng bắt được những thứ so khớp chuỗi không thể, như email có thực sự nghe thân mật hay không.

Đánh giá

Chạy đánh giá:

promptfoo evalĐược hỗ trợ bởi

Sau đó mở kết quả trong trình duyệt:

promptfoo viewĐược hỗ trợ bởi

Giao diện web hiển thị provider theo cột và test case theo hàng. Mỗi ô hiển thị đạt/trượt cho từng assertion, và bạn có thể nhấp vào bất kỳ ô nào để xem đầy đủ đầu ra và chi tiết chấm điểm. 

Promptfoo mặc định lưu đệm phản hồi API xuống đĩa (TTL 14 ngày), nên chạy lại cùng eval sẽ không tốn phí. Dùng --no-cache khi bạn muốn phản hồi mới.

Viết assertion

Eval đầu tiên dùng icontains và llm-rubric. Đó là hai trong số nhiều loại assertion mà Promptfoo hỗ trợ. Phần này đi qua các nhóm chính, và chúng ta sẽ tiếp tục thêm assertion vào cấu hình viết email khi đi tiếp.

Assertion tất định

Chúng chạy cục bộ, không tốn phí, và trả kết quả tức thì.

Bạn đã dùng icontains và latency. Hãy thêm not-contains vào test case thân mật. Nếu mô hình mặc định dùng ngôn ngữ trang trọng, nó có thể bắt đầu bằng "Dear" thay vì điều gì đó thân mật như "Hey." Bắt lỗi đó chỉ bằng một dòng:

- type: not-contains
  value: \"Dear\"Được hỗ trợ bởi

Thêm dòng này vào danh sách assert của test case thân mật và chạy lại. Cả hai mô hình đều nên đạt: GPT-5 thường mở đầu bằng "Hey team," và Claude Sonnet 4 cũng vậy. Nếu mô hình nào mở đầu bằng "Dear Colleagues," assertion này sẽ gắn cờ ngay lập tức. 

Mỗi loại assertion cũng hỗ trợ tiền tố not-: not-regex, not-equals, v.v.

Assertion có hỗ trợ mô hình

Những assertion này tốn token, nhưng có thể đánh giá những điều so khớp chuỗi không thể. Bạn đã dùng llm-rubric ở eval đầu tiên. Rubric bạn viết là yếu tố quyết định.

Một rubric mơ hồ như "Email nghe chuyên nghiệp" không cho người chấm điều gì hữu ích. Một rubric cụ thể cho họ thứ để đo:

- type: llm-rubric
  value: \"The email uses a casual tone: contractions like 'we'll' and 'don't',
    sentences under 20 words, no corporate jargon like 'synergy' or 'circle back',
    and opens with a greeting like 'Hey' or 'Hi team'\"Được hỗ trợ bởi

Khi bạn chạy lại eval với rubric này, đầu ra của bộ chấm cũng cụ thể:

• Claude Sonnet 4.6: "Email áp dụng giọng điệu thân mật ('Hey team,' 'shoot over'), dùng rút gọn ('we're,' 'let's,' 'don't')."
• GPT-5: "Giọng điệu thân mật (ví dụ, 'Hey team,' 'Just shout.'), dùng rút gọn ('We're,' 'I'll')."

Rubric càng cụ thể, việc chấm điểm càng nhất quán và hữu ích.

Promptfoo cũng cung cấp answer-relevance (đầu ra có trả lời đúng câu hỏi không?) và similar (độ tương đồng cosin với tham chiếu qua embeddings), đều hữu ích cho RAG và các ứng dụng tìm kiếm.

Assertion Python tùy chỉnh

Khi các loại dựng sẵn không bao phủ được logic của bạn, hãy tự viết. Với công cụ viết email, bạn có thể muốn kiểm tra đầu ra giữ trong độ dài hợp lý. Đây là assertion nội tuyến vượt nếu email từ 50 đến 200 từ:

- type: python
  value: \"50 <= len(output.split()) <= 200\"Được hỗ trợ bởi

Thêm vào test case thân mật và chạy lại. Trong lần chạy của tôi, cả hai mô hình đều đạt: GPT-5 khoảng 54 từ, Claude Sonnet 4 khoảng 187. Nhưng hãy nhớ assertion này cho phần tiếp theo, vì nó không đạt ở mọi nơi.

Với kiểm tra phức tạp hơn, đặt logic trong tệp riêng:

# assert_length.py
def get_assert(output, context):
    word_count = len(output.split())
    in_range = 50 <= word_count <= 200
    return {
        \"pass\": in_range,
        \"score\": 1.0 if in_range else 0.0,
        \"reason\": f\"Word count: {word_count} (target: 50-200)\"
    }Được hỗ trợ bởi

Tham chiếu trong cấu hình với type: python và value: file://assert_length.py. Trường reason hiển thị trong UI kết quả, để bạn thấy chính xác vì sao test đạt hay trượt.

Khi một test nên trượt

Đây là trông như thế nào khi lỗi thực sự xảy ra.

Thêm assertion đếm từ bằng Python vào cả ba test case và chạy toàn bộ eval trên cả hai mô hình. Trong trường hợp của tôi, năm trên sáu kết hợp đạt. Claude Sonnet 4.6 không đạt ở test case khẩn cấp (điều này có thể có hoặc không xảy ra trên máy bạn, do hành vi không tất định của LLM).

Trong lần đó, đầu ra dài 207 từ, hơn giới hạn bảy từ. llm-rubric thực ra đạt, xác nhận email dùng "ngôn ngữ khẩn cấp, trực tiếp" với "hành động rõ ràng." icontains cũng đạt, vì "Friday" có trong đầu ra.

Nhưng assertion đếm từ bằng Python trượt. Claude thêm phần bình luận dẫn nhập ("Here is a draft email based on your bullet points with an urgent tone:") trước email thực sự, đẩy số từ vượt 200.

Đây là kiểu lỗi bạn khó mà bắt bằng mắt thường. Bản thân email đọc ổn: đúng giọng điệu, đúng nội dung. Nhưng đầu ra quá dài vì mô hình thêm văn bản không thuộc email. Một assertion đã bắt được, và eval gắn cờ cả test case.

Cách sửa có thể theo hai hướng: chỉnh prompt để yêu cầu mô hình không thêm lời mở đầu, hoặc nâng giới hạn từ. Dù cách nào, bạn chạy lại eval và kiểm tra đạt.

Chấm điểm có trọng số

Lúc này, test case thân mật có bốn assertion: icontains, not-contains, llm-rubric, và đếm từ bằng Python. Không phải cái nào cũng quan trọng như nhau. Trường weight cho phép bạn thể hiện điều đó:

assert:
  - type: icontains
    value: \"mockups\"
    weight: 1
  - type: not-contains
    value: \"Dear\"
    weight: 1
  - type: llm-rubric
    value: \"The email uses a casual tone with contractions and short sentences\"
    weight: 2
  - type: python
    value: \"50 <= len(output.split()) <= 200\"
    weight: 0.5
threshold: 0.7Được hỗ trợ bởi

Điểm của mỗi assertion được nhân với trọng số của nó, và bài kiểm tra tính trung bình có trọng số. threshold đặt mức điểm tối thiểu để đạt. Ở đây, rubric về giọng điệu tính gấp đôi so với kiểm tra từ khóa, và đếm từ tính một nửa.

Chạy lại test thân mật với các trọng số này, cả hai mô hình đạt 1.0 và vượt. Nhưng nếu llm-rubric trượt (trọng số 2) trong khi đếm từ đạt (trọng số 0.5), điểm trung bình có trọng số sẽ xuống dưới ngưỡng 0.7, và test sẽ trượt. Trọng số cho phép bạn nói với Promptfoo điều bạn thực sự quan tâm nhất.

So sánh mô hình cạnh nhau

Cấu hình đã có hai provider, nên promptfoo eval kiểm thử GPT-5 và Claude Sonnet 4 trong một lần. Mở promptfoo view và bạn sẽ thấy chúng là các cột riêng trong kết quả, với mỗi test case được chấm độc lập trên từng mô hình.

Trong lần chạy eval của chúng ta, GPT-5 vượt qua cả sáu assertion trên ba test case. Claude Sonnet 4 vượt năm cái nhưng trượt đếm từ ở email khẩn cấp. 

Đó là kiểu khác biệt bạn khó nhận ra khi thử vài prompt thủ công, nhưng hiện rõ ngay trong lưới. Bạn đang so sánh điểm theo cùng assertion trên cùng đầu vào, không phải ký ức xem mô hình nào "có vẻ tốt hơn" lần trước.

Tuy nhiên, đầu ra LLM không tất định. Cùng một prompt có thể cho kết quả khác nhau ở các lần chạy liên tiếp, và một lần chạy sẽ không cho biết mô hình có đáng tin hay chỉ may mắn. Cờ --repeat giải quyết điều này:

promptfoo eval --repeat 3Được hỗ trợ bởi

Lệnh này chạy mỗi test case ba lần trên mỗi provider. Nếu một mô hình vượt assertion về giọng điệu hai lần nhưng trượt ở lần thứ ba, đó là tín hiệu về độ ổn định mà bạn sẽ bỏ lỡ nếu chỉ chạy một lần.

Từ kiểm thử cục bộ đến CI/CD

Chạy eval cục bộ phù hợp khi phát triển, nhưng phụ thuộc vào việc người sửa prompt nhớ chạy. Promptfoo có GitHub Action chính thức loại bỏ phụ thuộc đó bằng cách chạy bộ eval trên mọi pull request và đăng kết quả dưới dạng bình luận.

Để thiết lập, tạo tệp workflow trong repo của bạn:

mkdir -p .github/workflowsĐược hỗ trợ bởi

Sau đó tạo .github/workflows/prompt-eval.yml với nội dung sau:

name: 'Prompt Evaluation'
on:
  pull_request:
    paths:
      - 'prompts/**'
jobs:
  evaluate:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
 
      - name: Set up promptfoo cache
        uses: actions/cache@v4
        with:
          path: |
            ~/.promptfoo/cache
            .promptfoo-cache
          key: ${{ runner.os }}-promptfoo-${{ hashFiles('prompts/**') }}-${{ github.sha }}
          restore-keys: |
            ${{ runner.os }}-promptfoo-${{ hashFiles('prompts/**') }}-
            ${{ runner.os }}-promptfoo-
 
      - name: Run promptfoo evaluation
        uses: promptfoo/promptfoo-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          config: 'promptfooconfig.yaml'
          cache-path: '.promptfoo-cache'Được hỗ trợ bởi

Trước khi hoạt động, bạn cần thêm OPENAI_API_KEY (và tùy chọn ANTHROPIC_API_KEY) làm secret của repository trong GitHub repo dưới Settings > Secrets and variables > Actions.

Bộ lọc paths nghĩa là action chỉ kích hoạt khi ai đó thay đổi tệp trong prompts/. Bước checkout là bắt buộc vì action dùng git nội bộ để so khác tệp prompt giữa các nhánh. Nó chạy toàn bộ bộ eval và đăng bình luận PR với kết quả và liên kết tới trình xem web.

Để kiểm soát logic đạt/trượt chi tiết hơn, bạn có thể phân tích trực tiếp đầu ra JSON:

promptfoo eval -c config.yaml -o results.json
FAILURES=$(jq '.results.stats.failures' results.json)
if [ \"$FAILURES\" -gt 0 ]; then exit 1; fiĐược hỗ trợ bởi

Quy trình làm việc từ đây: 

1. Thay đổi một prompt
2. Mở PR
3. CI chạy eval
4. Kết quả xuất hiện dưới dạng bình luận PR
5. Sửa nếu có gì trượt
6. Hợp nhất khi mọi thứ đạt. 

Thay đổi prompt nhận cùng chế độ kiểm thử-trước-khi-hợp-nhất như thay đổi mã.

Kết luận

Công cụ viết email ở phần mở đầu vẫn có vấn đề về giọng điệu, nhưng giờ đã có bài kiểm tra để bắt trước khi người dùng gặp. Bạn bắt đầu với một tệp YAML trống và kết thúc với một bộ eval chạy trên hai mô hình trong CI.

Cách tiếp cận tương tự áp dụng cho bất kỳ tính năng LLM nào bạn xây dựng, dù là chatbot, tóm tắt, hay pipeline phân loại. Miễn là bạn có thể viết assertion cho "đầu ra tốt" nghĩa là gì, bạn có thể kiểm thử tự động thay vì nhìn lướt.

Khi sẵn sàng đi xa hơn, tài liệu Promptfoo bao quát vài mảng đáng xem:

• Red teaming: promptfoo redteam run quét tiêm prompt và jailbreak qua hàng chục plugin tấn công

• Python provider tùy chỉnh: Bọc bất kỳ mô hình nội bộ hoặc endpoint fine-tune nào với file://my_provider.py

• Dữ liệu kiểm thử CSV: Mở rộng bộ kiểm thử với file://tests.csv khi YAML nội tuyến trở nên cồng kềnh

Nếu bạn muốn cải thiện các prompt đang kiểm thử, khóa học Prompt Engineering with the OpenAI API của chúng tôi bao gồm nhiều kỹ thuật quan trọng có thể áp dụng cho mọi loại phát triển AI.