Promptfoo 첫 평가(Eval) 시작하기

Promptfoo 첫 평가(Eval) 시작하기

Promptfoo의 평가는 promptfooconfig.yaml 설정 파일 하나로 시작해요. 프롬프트와 모델, 테스트 케이스를 YAML로 선언하면, 여러 모델에 같은 입력을 넣어 출력을 나란히 비교하거나 자동으로 점수를 매길 수 있죠. 이 글에서는 예제 실행부터 직접 설정 파일을 짜서 평가를 돌리고 결과를 확인하는 흐름까지 차근차근 따라가 볼게요.

출처: Promptfoo 공식 문서 - Getting started

예제로 시작하기

설치를 마쳤다면, 아래 명령으로 미리 만들어진 예제 설정 파일을 생성할 수 있어요. npx, npm, brew 중 편한 방법을 쓰면 돼요.

npx promptfoo@latest init --example getting-started

npm install -g promptfoo
promptfoo init --example getting-started

brew install promptfoo
promptfoo init --example getting-started

이 명령은 번역 프롬프트를 여러 모델에 걸쳐 테스트하는 기본 예제가 담긴 디렉터리를 만들어요. 예제에는 프롬프트·모델·테스트 케이스가 들어 있는 promptfooconfig.yaml과, 예제 동작 방식을 설명하는 README.md가 포함돼 있죠.

대부분의 모델 제공자는 인증이 필요해요. OpenAI 기준으로는 이렇게 API 키를 환경 변수로 지정하면 됩니다.

export OPENAI_API_KEY=sk-abc123

그다음 예제 디렉터리로 이동해 평가를 실행하고 결과를 열어보세요.

cd getting-started
npx promptfoo@latest eval
npx promptfoo@latest view

CLI로 처음부터 설정하기

예제 없이 처음부터 시작하려면 promptfoo init가 대화형 CLI 안내를 통해 설정 파일을 만들어 줘요.

npx promptfoo@latest init

웹 UI로 설정하기

화면을 보면서 만들고 싶다면 promptfoo eval setup을 실행하면 브라우저 기반 설정 화면이 열려 프롬프트 작성, 모델 선택, 테스트 케이스 추가를 단계별로 도와줘요.

npx promptfoo@latest eval setup

설정 파일 채우기

초기 설정을 만들었다면 promptfooconfig.yaml에 내 프롬프트와 모델, 테스트 케이스를 직접 넣어 봐요.

1. 프롬프트 설정 — 변수 자리는 이중 중괄호로 표기해요. {{variable_name}}처럼 쓰죠.

prompts:
  - 'Convert the following English text to {{language}}: {{input}}'

2. 모델(provider) 추가 — providers에 테스트할 AI 모델을 지정해요. Promptfoo는 60개 이상의 모델 제공자를 지원하고, OpenAI·Anthropic·Google을 비롯한 클라우드 API부터 Ollama 같은 로컬 모델, 나만의 Python·JavaScript 코드까지 가능해요.

providers:
  - openai:chat:gpt-5.4
  - openai:chat:gpt-5.4-mini
  - anthropic:messages:claude-opus-4-6
  - google:gemini-3.8-flash
  # Or use your own custom provider
  - file://path/to/custom/provider.py

3. 테스트 입력 추가 — 프롬프트에 넣을 예시 입력을 tests에 적어요. 필요하면 assert로 출력 요구사항을 지정해 자동 검사할 수도 있어요.

tests:
  - vars:
      language: French
      input: Hello world
    assert:
      - type: contains
        value: 'Bonjour le monde'
  - vars:
        language: Spanish
        input: Where is the library?
      assert:
        - type: icontains
          value: 'Dónde está la biblioteca'

테스트 케이스를 쓸 땐 핵심 사용 사례와, 프롬프트가 제대로 다루길 바라는 잠재적 실패 지점을 함께 떠올리는 게 좋아요.

4. 평가 실행 — promptfooconfig.yaml이 있는 디렉터리에서 실행합니다. 그러면 프롬프트·모델·테스트 케이스 전체 조합을 검사해요.

npx promptfoo@latest eval

5. 결과 확인 — 평가가 끝나면 웹 뷰어를 열어 출력을 비교해 보세요.

npx promptfoo@latest view

어서션(Assert)

YAML 설정은 각 프롬프트를 일련의 테스트 케이스로 돌리면서, 출력이 지정한 어서션을 충족하는지 확인해요. 어서션은 선택사항이라, 수동으로 출력을 검토하는 데만 써도 충분히 가치가 있어요. 웹 UI가 그런 수동 검토를 돕죠.

평가 예제들

아래 예제들은 프롬프트 품질, 모델 품질, RAG 품질, 에이전트 품질이라는 네 가지 흔한 평가 패턴을 보여줘요.

프롬프트 품질

이 예제는 어시스턴트 봇의 성격에 형용사를 추가하는 것이 응답에 영향을 주는지 평가해요. npx promptfoo@latest init --example eval-self-grading으로 바로 구성할 수 있어요.

예제의 핵심 설정은 이렇게 돼요. LLM 루브릭(채점 기준) 어서션과 JavaScript 어서션을 함께 쓴답니다.

# yaml-language-server: $schema=https://promptfoo.dev/config-schema.json
description: Automatic response evaluation using LLM rubric scoring

# Load prompts
prompts:
  - file://prompts.txt
providers:
  - openai:chat:gpt-5.4
defaultTest:
  assert:
    - type: llm-rubric
      value: Do not mention that you are an AI or chat assistant
    - type: javascript
      # Shorter is better
      value: Math.max(0, Math.min(1, 1 - (output.length - 100) / 900));

모델 품질

이 예제는 같은 프롬프트에 대한 GPT-5.4와 GPT-5.4 Mini의 출력 차이를 평가해요. npx promptfoo@latest init --example compare-openai-models로 구성할 수 있고, 설정에는 비용·지연 시간 임계값 어서션도 넣을 수 있어요.

description: Comparing OpenAI flagship and mini models performance on riddles

prompts:
  - 'Solve this riddle: {{riddle}}'

providers:
  - openai:chat:gpt-5.4
  - openai:chat:gpt-5.4-mini

defaultTest:
  assert:
    # Inference should always cost less than this (USD)
    - type: cost
      threshold: 0.002
    # Inference should always be faster than this (milliseconds)
    - type: latency
      threshold: 3000

참고로 모델은 커맨드라인에서 직접 덮어쓸 수 있어요. 아래처럼 실행하면 설정 속 GPT 모델 대신 Gemini 모델로 비교 표가 만들어져요.

npx promptfoo@latest eval -r google:gemini-3.8-flash google:gemini-3.5-flash-lite

비슷한 방식으로 GPT-5.4의 reasoning effort 비교, 온도(temperature) 비교, 오픈소스 모델 비교, RAG 파이프라인 비교도 할 수 있어요.

RAG 품질

이 예제는 RAG 출력이 검색된 컨텍스트에 사실적·관련성 있게 근거하고 있는지 평가해요. npx promptfoo@latest init --example eval-rag로 구성하고, 사실성(factuality)·답변 관련성(answer relevance)·컨텍스트 재현(recall)·관련성·충실성(faithfulness) 기준으로 점수를 매겨요.

에이전트 품질

이 예제는 OpenAI Agents SDK 워크플로를 평가해요. npm install 후 npx promptfoo@latest eval로 다중 턴 시나리오에서 도구 사용과 응답 품질을 테스트하죠.

다음 단계

더 알아보기