AI機能のための評価を書く：実際の30件から始める
多くのチームがAI機能を作りますが、測るチームは少数です。この記事は、実際の30件を読み、失敗を分類してから評価（evals）を書く方法を、ハメル・フセインとシュレヤ・シャンカールの手引きに沿って示し、記録シート、3回の午後の計画、よくある間違いを添えます。
言語モデルで機能を作る人のための記事で、初心者も対象です。技術用語には短い説明を付けます。
方法と数字（30、100、100〜200サンプル）は、ハメル・フセインとシュレヤ・シャンカールの手引きに拠ります（ページの前半は直接読みましたが、全部ではなく、後ろの約3分の1は未読です）。実務家の手引きで、標準ではありません。お店「ホン」の例と表の数字は、作り直した例です。
先に要点#
- AI機能を測ることは、実際のデータを読むことから始まります。基盤を作ることからではありません。
- 約30件を手で読み、何が悪かったかを書き、メモを失敗の分類にまとめて数えます。
- 想像した失敗ではなく、実際に見た失敗について評価を書きます。
- 明確な規則があるところは通常のコードによる検査を使います。審査役のモデルは、判断が要るときだけ使い、人の採点者と照らし合わせます。
- 段階評価でなく、合格か不合格で採点します。
- 3回の午後でできます。
むずかしい言葉をやさしく#
| 用語 | やさしい意味 |
|---|---|
| Evals（評価） | AI機能の品質を測るテスト。 |
| トレース | 1回の完全な実行：利用者の入力、システムが取った手順、出力。 |
| エラー分析 | ケースを読み、何が悪かったかを書き、分類にまとめること。 |
| オープンコーディング | 各ケースを読み、まとめる前に、悪かった点を自由にメモすること。 |
| 軸足コーディング | メモを失敗の分類にまとめ、それぞれを数えること。 |
| LLMジャッジ | 別のモデルを使い、合格か不合格を採点すること。 |
| 二値 | 結果は2つだけ：合格か不合格。 |
1. なぜ必要で、なぜ難しいか#
通常のソフトウェアには、たいてい正しい答えがあります：2つの数を足す関数は合計を返します。AI機能は違います：同じ質問に、モデルはいろいろな答え方ができ、「良い」は判断です。だから多くのチームは測ることを省き、顧客が不満を言って初めて失敗を知ります。
フセインとシャンカールの手引きは、はっきり言います：基盤ではなく、エラー分析から始める。つまり、ツールを買う、ダッシュボードを作る、審査役を書く前に、座って実際の出力を読むのです。退屈に聞こえますが、最も大事な問いに答えます：私の機能は、どこで壊れているのか？
この記事はAIを鵜呑みにしてはいけない理由につながります：モデルは流暢でも間違えうるので、感覚以外で測る方法が要ります。そしてAIアプリのOWASP Top 10にも：自分のアプリを攻撃してみることも、テストの一種です。
2. 段階1：読む30件を用意する#
手引きによると、多様な約100件から始め、少なくとも最初の30件は手で注釈します。私は30を、実践上の出発点として使います。1回の午後でできるくらい小さい数です。
すでに実際の利用者がいるなら： 実際の会話や依頼を取り、多様なもの（易しい、難しい、変わったもの）を選び、個人情報を除きます。
まだ実際のデータがないなら、手引きは、モデルに「テストの質問を書いて」と頼むだけでなく、構造のある合成データを勧めています：
- いくつかの次元を選ぶ（たとえば問題の種類、顧客の気分、複雑さ）。
- 約20の値の組を手で書く（次元ごとに1つの値）。
- 別の段階で、モデルに各組を自然な質問にしてもらう。
- その質問を本物のシステムに通し、結果を読む。
合成データでは、現実にどの失敗が多いかは分かりません。実際のデータが手に入ったら比べてください。
3. 段階2：読んで注釈する、1件ずつ#
各ケースについて、その分野の知識を持つ人（誰でもよいわけではありません）が、何が悪かったかを自由にメモし、見えた最初の失敗に集中します。これがオープンコーディングです。
手引きからのいくつかの助言：
- 読む前に基準を書かない。 基準は読むうちに変わるので、後から下書きします。
- モデルのせいでない問題も記録する。 たとえば、足りない機能や壊れたリンク。
- 新しい種類の失敗が出なくなるまで読み続ける。 100件後もまだ学べるなら、さらに読みます。
- 分野の知識のない人に任せない。 手引きは、これをよくある間違いに挙げています。
記録シート（私の提案）：
| # | 入力 | システムの出力 | 合格？ | 最初の失敗のメモ |
|---|---|---|---|---|
| 1 | 「シャツのサイズを変えたい」 | 返金ポリシーを示す | 不合格 | 意図を読み違え、別の話に答えた |
| 2 | 「注文はいつ届きますか」 | 正しい配達日を示す | 合格 |
4. 段階3：まとめて数える#
メモから、似た失敗を分類にまとめ、それぞれを数えます。手引きはこれを軸足コーディングと呼び、最も重要な段階とします。何を先に直すか、どの失敗に評価を書く価値があるかが分かるからです。
例（作り直した数字）：お店「ホン」には、顧客対応のアシスタントがあります。 30件を読んだ後：
| 失敗の分類 | 件数 | 対処の案 |
|---|---|---|
| 意図を読み違え、別の話に答えた | 9 | プロンプトを直し、例を足す |
| 情報をでっち上げた（配達日、価格） | 6 | 注文システムから取ることを強制し、コードで検査 |
| 口調が硬すぎ、顧客が怒っていても謝らない | 5 | 審査役を使えるが、人との比較が要る |
| 答えは正しいが長すぎる | 4 | 長さをコードで検査 |
| 必要なときに人に引き継がない | 3 | 明確な規則、コードで検査 |
| その他 | 3 | 引き続き見守る |
この表だけで、直して測る最初の3つが分かります。だから、データを読むことから始めるのです。
5. 段階4：実際の失敗に評価を書く#
失敗の分類ごとに、検査の種類を選びます：
| 種類 | 使うとき | 例 |
|---|---|---|
| 通常のコードによる検査 | 規則が書けるとき | 出力が有効なJSON、全項目がある、120語未満、配達日がシステムと一致 |
| LLMジャッジ | 失敗が、人のような判断を要するとき | 「顧客が怒っているとき、アシスタントは謝っているか」 |
手引きによると：審査役を作る前に、コードの規則でできないか確かめる。審査役には本物の保守費用があるからです。審査役はそれぞれ1種類の失敗を担当し、1人に多くを同時に捉えさせないでください。
合格か不合格を使います。 手引きは理由を挙げます：段階評価（1〜5など）は、段の間隔が一貫せず、より大きな標本が要り、真ん中に付けがちです。少しずつの進歩を追うには、小さな二値の検査をいくつかに分けます。たとえば「必要な5点のうち4点がある」。
6. 段階5：確かめる前に審査役を信じない#
モデルを審査役にするなら、審査役を他のものと同じように確かめます。手引きによると：
- 失敗の種類ごとに約100〜200サンプルにラベルを付ける。最低でも、合格約50、不合格約50。
- データを分ける：一部をプロンプトの例にし、残りを開発用の集合と、取っておく検証用の集合に分ける。
- 本物の失敗を捉える率（審査役が本物の失敗をどれだけ捉えるか）と、良いサンプルを正しく通す率を測る。
- 審査役のプロンプトを調整する前に、審査役と人が食い違うケースを見る。
- 検証用の集合の得点が、開発用よりずっと悪いなら、審査役を1つの集合にきつく合わせすぎたかもしれません。
この部分は手間がかかるので、急がないでください。私は手引きの前半しか読んでおらず、数字を再確認していないので、実務家の出発点として扱ってください。
7. 3回の午後の計画#
| 午後 | 作業 | 成果物 |
|---|---|---|
| 1 | 30件を集める（実際のもの、または構造のある合成）。本物のシステムに通す | 入力と出力のある30行のシート |
| 2 | 各ケースを読み、合格か不合格を付け、最初の失敗をメモする | メモのシート |
| 3 | まとめて数え、最大の3分類を選び、3つの検査を書く（コード優先） | 失敗の分類表と、動く3つの検査 |
3回の後、あなたには：多い順の失敗の一覧、3つの自動検査、そして習慣があります：大きな変更のたびに、約30分かけて20〜50件の結果を読む。手引きが最低限として示しているものです。
8. よくある間違い#
手引きによると：
- エラー分析を飛ばし、「役に立つ度」のような汎用の指標を使う。
- 見た失敗ではなく、想像した失敗の評価を書く。
- 1つの審査役に多くの失敗を同時に捉えさせる。
- 人と照らし合わせずに審査役を信じる。
- 合格100%を追う。 手引きは、合格率が約70%なら、評価が適度に難しい印かもしれないと示唆しています。
- 分野の知識のない人にエラー分析を任せる。
9. バランスの取れた見方#
- これは実務家の手引きです。 30、100、100〜200という数字は出発点で、広く検証された標準ではありません。
- 手引きを全部は読んでいません。 ページの後ろの約3分の1は未読なので、この記事は網羅的ではありません。
- evalsは手間がかかります。 使い捨ての試作なら、まだ要らないかもしれません。機能に実際の利用者や、無視できないリスクがあるときにやってください。
- 自動検査は、読むことの代わりになりません。 手引きは、実際のデータを見ることを強調しています。自動化は、学んだことが再び壊れないよう保つだけです。
- お店「ホン」は例です。 イメージしやすいよう、私が作った数字です。
10. 結論#
AI機能を測ることは、ツールから始まりません。実際の30件を読む午後と1本のペンから始まります。そこから、機能がどこで壊れるかが分かり、それから、正しい場所に評価を書きます。
今日の小さな一歩：作っているAI機能の直近の30件の出力を取り、1件ずつ読み、それぞれで何が悪かったかを1行書いてください。それから数えます。
参考資料#
よくある質問
- evalsとは何ですか
- 顧客に答えるアシスタントのように、言語モデルで作った機能の品質を測るテストです。通常のソフトウェアテストと違い、モデルの出力は変わり、唯一の正解がないので、専用の採点の仕方が要り、たいてい実際のケースを読むことから始めます。
- 始めるのに何件必要ですか
- ハメル・フセインとシュレヤ・シャンカールの手引きによると、多様な約100件から始め、少なくとも最初の30件は自分で手で注釈し、新しい種類の失敗が出なくなるまで読み続けます。30は実践上の出発点で、科学的な閾値ではありません。
- 段階評価と、合格か不合格では、どちらがよいですか
- その手引きは、合格か不合格を勧めています。段階評価は、段の間隔が一貫せず、より大きな標本が要り、真ん中に付けがちだからです。少しずつの進歩を追いたいなら、小さな二値の検査をいくつかに分けます。
- モデルを審査役に使うべきですか
- 失敗が、人のような判断を要し、決まった規則で捉えられないときだけです。審査役は1種類の失敗を担当し、合格例と不合格例の両方がある集合で、人のラベルと照らし合わせなければなりません。そうしないと、信じてよいか分かりません。