Promptfoo 評価

概要

このスキルは、LLM の出力をテストおよび比較するためのオープンソース CLI ツールである Promptfoo を使用した LLM 評価の設定と実行に関するガイダンスを提供します。

クイックスタート

# 新しい評価プロジェクトを初期化
npx promptfoo@latest init

# 評価を実行
npx promptfoo@latest eval

# ブラウザで結果を表示
npx promptfoo@latest view

設定構造

典型的な Promptfoo プロジェクト構造：

project/
├── promptfooconfig.yaml    # メイン設定
├── prompts/
│   ├── system.md           # システムプロンプト
│   └── chat.json           # チャット形式プロンプト
├── tests/
│   └── cases.yaml          # テストケース
└── scripts/
    └── metrics.py          # カスタム Python アサーション

コア設定 (promptfooconfig.yaml)

# yaml-language-server: $schema=https://promptfoo.dev/config-schema.json
description: "My LLM Evaluation"

# テスト対象のプロンプト
prompts:
  - file://prompts/system.md
  - file://prompts/chat.json

# 比較対象のモデル
providers:
  - id: anthropic:messages:claude-sonnet-4-6
    label: Claude-Sonnet-4.6
  - id: openai:gpt-4.1
    label: GPT-4.1

# テストケース
tests: file://tests/cases.yaml

# 並行処理の制御 (commandLineOptions の下に配置、トップレベルではない)
commandLineOptions:
  maxConcurrency: 2

# すべてのテストのデフォルトアサーション
defaultTest:
  assert:
    - type: python
      value: file://scripts/metrics.py:custom_assert
    - type: llm-rubric
      value: |
        レスポンスの品質を 0-1 スケールで評価します。
      threshold: 0.7

# 出力パス
outputPath: results/eval-results.json

プロンプト形式

テキストプロンプト (system.md)

あなたは親切なアシスタントです。

タスク: {{task}}
コンテキスト: {{context}}

チャット形式 (chat.json)

[
  {"role": "system", "content": "{{system_prompt}}"},
  {"role": "user", "content": "{{user_input}}"}
]

Few-Shot パターン

プロンプト内に直接例を埋め込むか、アシスタントメッセージを含むチャット形式を使用します：

[
  {"role": "system", "content": "{{system_prompt}}"},
  {"role": "user", "content": "Example input: {{example_input}}"},
  {"role": "assistant", "content": "{{example_output}}"},
  {"role": "user", "content": "Now process: {{actual_input}}"}
]

テストケース (tests/cases.yaml)

- description: "テストケース 1"
  vars:
    system_prompt: file://prompts/system.md
    user_input: "Hello world"
    # ファイルからコンテンツをロード
    context: file://data/context.txt
  assert:
    - type: contains
      value: "期待するテキスト"
    - type: python
      value: file://scripts/metrics.py:custom_check
      threshold: 0.8

Python カスタムアサーション

カスタムアサーション用の Python ファイルを作成します (例: scripts/metrics.py)：

def get_assert(output: str, context: dict) -> dict:
    """デフォルトアサーション関数。"""
    vars_dict = context.get('vars', {})

    # テスト変数にアクセス
    expected = vars_dict.get('expected', '')

    # 結果を返す
    return {
        "pass": expected in output,
        "score": 0.8,
        "reason": "期待するコンテンツを含む",
        "named_scores": {"relevance": 0.9}
    }

def custom_check(output: str, context: dict) -> dict:
    """カスタム名前付きアサーション。"""
    word_count = len(output.split())
    passed = 100 <= word_count <= 500

    return {
        "pass": passed,
        "score": min(1.0, word_count / 300),
        "reason": f"単語数: {word_count}"
    }

重要なポイント：

• デフォルト関数名は get_assert
• file://path.py:function_name で関数を指定
• bool、float (スコア)、または pass/score/reason を含む dict を返す
• context['vars'] 経由で変数にアクセス

LLM-as-Judge (llm-rubric)

assert:
  - type: llm-rubric
    value: |
      レスポンスを以下に基づいて評価します：
      1. 情報の正確性
      2. 説明の明確性
      3. 完全性

      0.0-1.0 でスコア付けします (0.7 以上は合格)。
    threshold: 0.7
    provider: openai:gpt-4.1  # オプション: グレーダーモデルをオーバーライド

リレー/プロキシ API を使用する場合、各 llm-rubric アサーションには apiBaseUrl を含む独自の provider 設定が必要です。そうしないとグレーダーがデフォルトの Anthropic/OpenAI エンドポイントにフォールバックし、401 エラーが発生します：

assert:
  - type: llm-rubric
    value: |
      品質を 0-1 スケールで評価します。
    threshold: 0.7
    provider:
      id: anthropic:messages:claude-sonnet-4-6
      config:
        apiBaseUrl: https://your-relay.example.com/api

ベストプラクティス：

• 明確なスコア基準を提供
• threshold で最小合格スコアを設定
• デフォルトグレーダーは利用可能な API キーを使用 (OpenAI → Anthropic → Google)
• リレー/プロキシを使用する場合: すべての llm-rubric には apiBaseUrl を含む独自の provider が必要です。メインプロバイダーの apiBaseUrl は継承されません

一般的なアサーションタイプ

タイプ	用途	例
contains	部分文字列チェック	value: "hello"
icontains	大文字小文字を区別しない	value: "HELLO"
equals	完全一致	value: "42"
regex	パターンマッチ	value: "\\d{4}"
python	カスタムロジック	value: file://script.py
llm-rubric	LLM グレーディング	value: "Is professional"
latency	レスポンス時間	threshold: 1000

ファイルリファレンス

すべての file:// パスは promptfooconfig.yaml の位置を基準に解決されます (参照を含む YAML ファイルではありません)。tests: が別の YAML ファイルを参照する場合、そのテストファイル内の file:// パスは依然として設定ルートから解決されるため、これが一般的な落とし穴です。

# ファイルコンテンツを変数として読み込む
vars:
  content: file://data/input.txt

# ファイルからプロンプトを読み込む
prompts:
  - file://prompts/main.md

# ファイルからテストケースを読み込む
tests: file://tests/cases.yaml

# Python アサーションを読み込む
assert:
  - type: python
    value: file://scripts/check.py:validate

評価の実行

# 基本的な実行
npx promptfoo@latest eval

# 特定の設定を指定
npx promptfoo@latest eval --config path/to/config.yaml

# ファイルに出力
npx promptfoo@latest eval --output results.json

# テストをフィルタリング
npx promptfoo@latest eval --filter-metadata category=math

# 結果を表示
npx promptfoo@latest view

リレー / プロキシ API 設定

Anthropic/OpenAI エンドポイントへの直接接続の代わりに API リレーまたはプロキシを使用する場合：

providers:
  - id: anthropic:messages:claude-sonnet-4-6
    label: Claude-Sonnet-4.6
    config:
      max_tokens: 4096
      apiBaseUrl: https://your-relay.example.com/api  # Promptfoo は自動的に /v1/messages を追加

# 重要: maxConcurrency は commandLineOptions の下に配置 (トップレベルではない)
commandLineOptions:
  maxConcurrency: 1  # リレーのレート制限を考慮

重要なルール：

• apiBaseUrl は providers[].config に配置します。Promptfoo は自動的に /v1/messages を追加
• maxConcurrency は commandLineOptions: の下に配置する必要があります。トップレベルに配置するとサイレントに無視されます
• リレーで LLM-as-judge を使用する場合、maxConcurrency: 1 に設定して並行リクエスト制限を回避します (生成とグレーディングは同じプールを共有)
• ANTHROPIC_API_KEY 環境変数としてリレートークンを渡す

トラブルシューティング

Python が見つからない：

export PROMPTFOO_PYTHON=python3

大きな出力が切り詰められる： 30000 文字を超える出力は切り詰められます。アサーションで head_limit を使用します。

ファイルが見つからないエラー： すべての file:// パスは promptfooconfig.yaml の位置を基準に解決されます。

maxConcurrency が無視される (「最大 N 個を同時実行」と表示)： maxConcurrency は commandLineOptions: の下に配置する必要があり、YAML のトップレベルではありません。これは一般的な間違いです。

LLM-as-judge がリレー API で 401 を返す： 各 llm-rubric アサーションには apiBaseUrl を含む独自の provider が必要です。メインプロバイダー設定はグレーダーアサーションに継承されません。

モデル出力の HTML タグがメトリクスを増加させる： モデルは構造化コンテンツで <br>、<b> などを出力する場合があります。測定の前に Python アサーション内で HTML をストリップします：

import re
clean_text = re.sub(r'<[^>]+>', '', raw_text)

Echo プロバイダー (プレビューモード)

echo プロバイダー を使用して、API 呼び出しを行わずにレンダリングされたプロンプトをプレビューします：

# promptfooconfig-preview.yaml
providers:
  - echo  # プロンプトを出力として返す、API 呼び出しなし

tests:
  - vars:
      input: "test content"

ユースケース：

• 高コストの API 呼び出しの前にプロンプトレンダリングをプレビュー
• Few-shot の例が正しくロードされていることを確認
• 変数置換の問題をデバッグ
• プロンプト構造を検証

# プレビューモードを実行
npx promptfoo@latest eval --config promptfooconfig-preview.yaml

コスト： 無料 - API トークンは消費されません。

高度な Few-Shot 実装

マルチターン会話パターン

完全な例を使用した複雑な few-shot 学習の場合：

[
  {"role": "system", "content": "{{system_prompt}}"},

  // Few-shot 例 1
  {"role": "user", "content": "Task: {{example_input_1}}"},
  {"role": "assistant", "content": "{{example_output_1}}"},

  // Few-shot 例 2 (オプション)
  {"role": "user", "content": "Task: {{example_input_2}}"},
  {"role": "assistant", "content": "{{example_output_2}}"},

  // 実際のテスト
  {"role": "user", "content": "Task: {{actual_input}}"}
]

テストケース設定：

tests:
  - vars:
      system_prompt: file://prompts/system.md
      # Few-shot 例
      example_input_1: file://data/examples/input1.txt
      example_output_1: file://data/examples/output1.txt
      example_input_2: file://data/examples/input2.txt
      example_output_2: file://data/examples/output2.txt
      # 実際のテスト
      actual_input: file://data/test1.txt

ベストプラクティス：

• 1～3 個の few-shot 例を使用 (多すぎるとメリットが損なわれる場合があります)
• 例がタスク形式と完全に一致していることを確認
• 保守性を向上させるためにファイルから例を読み込む
• 構造を検証するために最初に echo プロバイダーを使用

長いテキストの処理

中国語や長文形式のコンテンツ評価 (10k+ 文字)：

設定：

providers:
  - id: anthropic:messages:claude-sonnet-4-6
    config:
      max_tokens: 8192  # 長い出力に対応させるために増加

defaultTest:
  assert:
    - type: python
      value: file://scripts/metrics.py:check_length

テキストメトリクス用の Python アサーション：

import re

def strip_tags(text: str) -> str:
    """HTML タグを削除して純粋なテキストを取得。"""
    return re.sub(r'<[^>]+>', '', text)

def check_length(output: str, context: dict) -> dict:
    """出力の長さの制約をチェック。"""
    raw_input = context['vars'].get('raw_input', '')

    input_len = len(strip_tags(raw_input))
    output_len = len(strip_tags(output))

    reduction_ratio = 1 - (output_len / input_len) if input_len > 0 else 0

    return {
        "pass": 0.7 <= reduction_ratio <= 0.9,
        "score": reduction_ratio,
        "reason": f"削減率: {reduction_ratio:.1%} (目標: 70-90%)",
        "named_scores": {
            "input_length": input_len,
            "output_length": output_len,
            "reduction_ratio": reduction_ratio
        }
    }

実例

プロジェクト： 長いトランスクリプトから中国語短動画コンテンツをキュレーション

構造：

tiaogaoren/
├── promptfooconfig.yaml          # 本番設定
├── promptfooconfig-preview.yaml  # プレビュー設定 (echo プロバイダー)
├── prompts/
│   ├── tiaogaoren-prompt.json   # few-shot を含むチャット形式
│   └── v4/system-v4.md          # システムプロンプト
├── tests/cases.yaml              # 3 つのテストサンプル
├── scripts/metrics.py            # カスタムメトリクス (削減率など)
├── data/                         # 5 つのサンプル (2 つは few-shot、3 つは評価)
└── results/

参照： 完全な実装については ./tiaogaoren/ (プロジェクトルートの例) を参照してください。

リソース

詳細な API リファレンスと高度なパターンについては、references/promptfoo_api.md を参照してください。