Evaluations：モデル品質のためのXCTest（iOS 27）

通常のユニットテストは add(2, 2) が 4 を返すことをアサートし、そうでなければビルドは赤くなります。ところがAI機能は、最初の一行でその契約を破ってしまうのです。同じプロンプトでも実行のたびに異なる文章が生成され、しかも「違う」ことは「間違い」を意味しないからです。モデルに対して #expect(summary == "the expected summary") と書くことはできません。期待される文字列がただ一つに定まらないためです。測定できるのは、自分で定義した基準に照らして、出力が十分に良いか、そしてそれが十分な頻度で起きているか、という点です。Appleの新しい Evaluations フレームワークは、開発ワークフローの一部として実行できる型安全なSwift APIを備えた、その測定ハーネスを提供します¹。27リリースで新登場し、Appleの全プラットフォーム（iOS、iPadOS、macOS、visionOS、watchOS）で利用できます。アプリ内に組み込んで出荷するランタイム機能ではなく、テスト時に、通常はMac上で実行する開発ツールです¹。

テストを書いたことがあれば、その形には馴染みを感じるでしょう。データセットを定義し、モデルの応答を生成し、メトリクスを適用し、結果を集計します。そして、どのアプローチが最も良い成績だったか、個々の応答がどこで基準に届かなかったかを読み取ります¹。メンタルモデルとしては、モデル品質のためのXCTestです。ループは同じ（ケースを用意し、実行し、何かをアサートする）でありながら、アサーションが異なります（等価判定ではなく、採点されたメトリクス）。

セッション298でAppleは、この中核となる問題をこう位置づけています。生成AI機能は、ソフトウェアテストにとって根本的な契約を破ってしまう。同じ入力が異なる出力を生み出しうるため、ユニットテストでは不十分なのだ、と²⁵。

TL;DR / 要点

• Evaluations フレームワークは27リリースでAppleの全プラットフォーム（iOS、iPadOS、macOS、visionOS、watchOS）に新登場した、インテリジェンスを活用した機能を測定するための開発ツール層であり、テストワークフローの一部として（通常はMac上で）実行します¹。
• Evaluator はインラインで書けるクロージャベースの評価器です。Evaluation プロトコルは、テスト対象システムをデータセットに対して実行し、評価器を適用するために実装する型です²³。
• Metric は名前付きの結果をファクトリメソッド（passing、failing、scoring、ignore）を通じて運び、ScoreDimension はモデルを審査員とする評価器のために採点軸に名前を付けます⁴⁵。
• ModelSample は汎用の評価サンプルです。SampleGenerator は言語モデルから非同期ストリームとしてサンプルを生成するアクターで、結果は responseColumn を含む型付きカラムを備えた DataFrame に格納されます⁶⁷⁸。
• ToolCallEvaluator はエージェント的なツール呼び出しを TrajectoryExpectation に照らして検証し、ArgumentMatcher が各引数の検証方法を定義します⁹¹⁰¹¹。
• EvaluationTrait はテストの内部で評価を実行し、その結果をアタッチメントとして記録します。これが Swift Testing の実行へとつながる橋渡しとなります¹²。

本稿ではAPIの全体像をたどり、各要素がなぜ存在するのかを説明し、それが採点対象とする Foundation Models のツール呼び出しの仕事へと結びつけていきます。Appleが正確なシグネチャを公開していない呼び出しを示す箇所では、説明のための例であると明記し、ドキュメントで確認するよう注記します。

評価器のモデル

このフレームワークの中核となる問いは「この出力はどれだけ良かったか」であり、それに小さな語彙で答えます。評価器が判断し、メトリクスが記録し、スコアディメンションが採点し、結果が集計するのです。

Evaluation プロトコルは、評価を定義するために実装する型です。これはテスト対象システムをデータセットに対して実行し、評価器を適用してパフォーマンスを測定します³。宣言は最小限です。

// 27.0 beta (all Apple platforms)
protocol Evaluation : Sendable

このプロトコルが Sendable なのは、評価が並行処理だからです。多数のサンプルを並列で実行します。Swift Testing がデフォルトでテストケースを並列実行するのと同じやり方です¹³。再利用可能で名前の付いた評価が欲しいときには、このプロトコルを実装します。手早く済ませたいときには、代わりに Evaluator に手を伸ばします。Appleはこれを、カスタム型を定義せずインラインで使えるクロージャベースの評価器と説明しています²。

// 27.0 beta (all Apple platforms)
struct Evaluator<Input> where Input : SampleProtocol,
    Input.ExpectedValue : Decodable,
    Input.ExpectedValue : Encodable,
    Input.ExpectedValue : Sendable

Appleの解説によれば、クロージャは入力サンプルと応答を受け取り、.value と .transcript の両方にアクセスできます²。.value はモデルの型付き出力であり、.transcript はそこに至るまでの記録です。インライン評価器は、モデル品質のための一行の #expect ブロックのようなものです。サブクラスは不要で、判断そのものをクロージャとして書くだけです。次の呼び出しの形は説明のための例です。イニシャライザはAppleのドキュメントで確認してください。

import Evaluations

// Illustrative call shape — confirm against Apple's docs.
let nonEmpty = Evaluator<ModelSample<String>> { input, response in
    response.value.isEmpty ? .failing("empty output") : .passing()
}

クロージャが返すのは Metric です。Appleは Metric を、結果値を運ぶ名前付きメトリクスと説明し、ファクトリメソッドを明示しています。passing、failing、scoring、ignore はそれぞれ、結果を内部に保持した新しい Metric を返します⁴。

// 27.0 beta (all Apple platforms)
struct Metric

4つのファクトリは、AI機能が必要とする判断の種類に対応します。要約器は必須の事実を含めるか含めないかのどちらかなので、passing か failing を得ます。トーンを採点するルーブリックは1から5まであるので、scoring を得ます。集計から外したいサンプル（不正な入力や、既知の不良フィクスチャ）には ignore を与えます。これは行をデータセットに残しつつ、統計を汚さずに済ませてくれます。passing から採点される scoring までの幅こそ、このフレームワークが約束するものです。すなわち、単純な合否チェックから、モデルを審査員とするパターンによる詳細な採点までです¹。

その幅の採点側で ScoreDimension がその真価を発揮します。Appleはこれを、モデル審査員の評価器のための名前付き採点ディメンションと定義しています。各ディメンションは、名前（DataFrameのカラムとして使われます）、任意の説明、そして各スコアが何を意味するかの定義を持ちます⁵。

// 27.0 beta (all Apple platforms)
struct ScoreDimension

一つの出力が、ある軸では良くても別の軸では悪いということがあります。下書きのメールが、事実としては正しくてもトーンとしては誤っていることもあります。ScoreDimension はそうした軸（正確さ、トーン、簡潔さ）を別々に採点させてくれるので、集計は単に全体の品質が下がったことだけでなく、どのディメンションが下がったかまで教えてくれます。ディメンション名はカラムになります。つまりスコアは、延々と続く散文の壁ではなく、並べ替えて比較できる構造化されたテーブルに格納されるのです。

そのテーブルが EvaluationResult です。Appleはこれを、モデル評価の実行結果と説明しています。評価実行のサマリーと詳細な結果を含む構造体です¹⁴。

// 27.0 beta (all Apple platforms)
struct EvaluationResult

サマリーと詳細という二層構造こそ、評価を実行可能なものにしてくれます。サマリーは「このプロンプトは前のものより良かったか」に答えます。詳細は「どのサンプルが基準に届かなかったか」に答え、最も悪い行を開いてモデルが何を生成したかを読み取れるようにします¹。

サンプルと生成

評価には実行対象となるケースが必要で、フレームワークにおけるケースの単位がサンプルです。ModelSample はその汎用版です。Appleはこれを、文字列ベースのプロンプトと指示を受け付ける汎用の言語モデル評価サンプルと説明しています⁶。

// 27.0 beta (all Apple platforms)
struct ModelSample<ExpectedValue> where ExpectedValue : Decodable,
    ExpectedValue : Encodable,
    ExpectedValue : Sendable

ジェネリックな ExpectedValue は型付きの期待値です。自由記述のタスクなら文字列、既知の答えがあるタスクなら構造化された Codable 型になります。Codable と Sendable の制約は Evaluator の Input.ExpectedValue と一致します。期待値が結果テーブルへとシリアライズされ、並列実行中に並行処理の境界を越えなければならないためです。マルチモーダルなプロンプトについては、カスタムの準拠を作るか、あらかじめ構築されたプロンプトを使うイニシャライザを用いる、とAppleは注記しています⁶。

すべてのサンプルを手書きするのはスケールしません。だからこそ SampleGenerator が存在します。言語モデルを使って評価サンプルを生成するアクターです⁷。

// 27.0 beta (all Apple platforms)
actor SampleGenerator<SampleType> where SampleType : ModelSampleProtocol

これが actor なのは、変更可能な生成状態（受理されたサンプルと拒否されたサンプル）を所有し、非同期イテレーションがその状態を変更するからです。アクターの隔離は、その状態に対するデータ競合を防ぐSwiftの安全装置です。Appleのワークフローはこうです。ジェネレーターを作り、そのプロパティを設定し、それを呼び出して新しいサンプルを非同期ストリームとして生成する。イテレーションの後で、生成されたすべてのサンプル、あるいはバリデーターが拒否したものにアクセスできます⁷。立ち止まる価値があるのは、拒否されたサンプルの方です。不良サンプルを黙って捨ててしまうジェネレーターは、自身の失敗率を隠してしまうでしょう。拒否されたものを露わにすることで、手書きのフィクスチャを監査するのと同じようにデータセットを監査できます。

サンプルを実行すると、応答は型付きのカラム記述子を備えた DataFrame に格納されるので、文字列頼みの検索なしにテーブルを読み取れます。Appleは応答カラムをまさにこう名付けています。responseColumn、詳細な DataFrame におけるモデル応答のための型付きカラム記述子です⁸。

// 27.0 beta (all Apple platforms)
var responseColumn: ResultColumn<Self.Subject> { get }

カラムを型付きにしているのは ResultColumn<Value> というジェネリックです。これは DataFrame のカラムの記述子で、保持する値によってパラメータ化されています¹⁵。responseColumn と並んで、フレームワークは入力サンプルのための inputColumn と、期待値のための expectedColumn を公開しており、それぞれが型付きの ResultColumn です¹⁶¹⁷。型付きのカラムは、Swift Testing の式キャプチャと同じ発想です。型のない袋から値を取り出してキャストが通ることを祈るのではなく、自分の型を知っている記述子を通じて読み取るのです。平均、中央値、標準偏差を求めるために結果を MetricsAggregator に渡すとき、このカラムこそが、キーを推測せずにデータを指し示す手段となります¹⁸。

ツールと軌跡のチェック

テストが最も難しいAI機能は、エージェント的なものです。正しさが文字列ではなく、一連のアクションだからです。Foundation Models のセッションが OCRTool、次に BarcodeReaderTool、そして自前のカタログ検索を呼び出すとき、問われるのは「最終的な文が一致したか」ではなく「モデルは正しい経路をたどったか」です¹⁹。ToolCallEvaluator はその経路を直接採点します。Appleはこれを、エージェント的なツール呼び出しを期待される軌跡に照らして検証する評価器と説明しています⁹。

// 27.0 beta (all Apple platforms)
struct ToolCallEvaluator<Input> where Input : ModelSampleProtocol,
    Input.Expectation == TrajectoryExpectation

where 句が肝心の部分です。入力の期待値は TrajectoryExpectation でなければなりません。Appleはこの型を、評価における期待されるツール呼び出しのパターンと説明しており、3つの軸にわたって指定されます¹⁰。

// 27.0 beta (all Apple platforms)
struct TrajectoryExpectation

Appleによれば、ToolCallEvaluator は順序付きシーケンス、順序を問わない期待、禁止ツールのチェック、そしてグループステップをサポートし、単一の評価パスから厳密な結果と部分的な結果の両方を生み出します⁹。それぞれが現実のエージェントの失敗に対応します。順序付きシーケンスは、正しいツールを誤った順序で呼び出すモデルを捕らえます。順序を問わない期待は「これらの呼び出しは、順序はともかく必ず起きなければならない」と言います。禁止ツールのチェックは、決して触れてはならないツールに手を伸ばすモデルを捕らえます（安全性の事例として、読み取り専用にとどまるべきエージェントが破壊的なツールを呼び出す場合などです）。グループステップは「これらのうちのいずれか一つ」を表現し、複数の経路が許容される分岐に対応します。

厳密と部分という対は、エージェント的な品質が実際に劣化していく様子に合致します。新しいプロンプトが機能を完璧から完全な破綻へと一気に変えることはまれです。むしろ「毎回正しい軌跡」から「ほとんどの場合は正しい軌跡だが、一つの呼び出しだけ順序が狂う」へと変えるのです。厳密な結果だけを返すと、それを一律の失敗として報告し、モデルがどれだけ惜しかったかについては何も教えてくれません。部分的な結果はその惜しい失敗を定量化します。これこそチューニングの拠り所となるシグナルです。

呼び出しごとの正しさは、もう一段下の引数に宿ります。モデルは正しいツールを誤った値で呼び出すこともあり、ArgumentMatcher が各引数の検証方法を定義します。Appleはこれを、ツール呼び出しの引数をどう検証するかを定義する値と説明しています¹¹。

// 27.0 beta (all Apple platforms)
enum ArgumentMatcher

Appleの解説は検証ルールを列挙しています。厳密な値を要求する、キーの存在を検証する、範囲をチェックする、パターンに照合する、あるいは意味的な照合のために言語モデルを使う、というものです¹¹。意味的な照合の事例こそ、単純な等価アサーションでは表現できないものです。ツール引数が自由記述のクエリであれば、二つの異なる文字列が等しく正しいということがあり、通常の == なら申し分ない呼び出しを不合格にしてしまうでしょう。その引数をモデルを審査員とする照合に委ねることは、ScoreDimension が出力レベルで提供するのと同じ逃げ道を、引数レベルに適用したものです。ケースの綴りはAppleの列挙に由来します。次は説明のための例なので、ドキュメントで確認してください。

import Evaluations

// Illustrative — confirm shapes against Apple's docs.
let expectation = TrajectoryExpectation(/* ordered / unordered / disallowed steps */)
let evaluator = ToolCallEvaluator<ModelSample<String>>(/* expectation */)

ここでのエージェント的なループは、Foundation Models のツール呼び出しに関する記事がランタイム側から説明しているものと同じです。そちらでは GenerationOptions.ToolCallingMode が、オンデバイスモデルがどれだけ積極的にツールに手を伸ばすかを左右し、フレームワークは最初の呼び出しの後にモードを切り替えて、リクエストのツール活動を抑制できます¹⁹。ToolCallEvaluator はその同じ振る舞いの測定側です。ランタイムで呼び出しの姿勢を設定し、その後テスト時に軌跡を採点して、その姿勢が意図した経路を生み出したことを確認します。ランタイムのつまみとテスト時の評価器は、一つの機能の両端なのです。

ワークフローへの組み込み方

評価は、四半期に一度実行する別個の儀式ではありません。テストの隣、同じループの中、同じMac上に居場所があります。フレームワークがそのループへとつなぐ橋が EvaluationTrait です。Appleはこれを、評価を実行し、その結果をアタッチメントとして記録するテストトレイトと説明しています¹²。

// 27.0 beta (all Apple platforms)
struct EvaluationTrait

「トレイト」という言葉は意図的なものです。Swift Testing の設定モデルそのものが、@Test や @Suite の宣言に適用されるトレイトです。.enabled(if:)、.disabled(_:)、.tags(...) などです¹³。EvaluationTrait は評価をその語彙へと組み込むので、評価はテストと同じように、同じ swift test の呼び出しのもとで、同じ並列性で実行されます。結果をアタッチメントとして記録することは、Swift Testing がすでに持つカスタムアタッチメントの仕組みを再利用するので、評価の詳細な結果が、収集するテストレポートやCIアーティファクトに付随して運ばれます¹³。フレームワークはさらに EvaluationContext を公開しており、テストスコープ内のコードが評価完了後に結果を読み取れるようにしています²⁰。

そのトレイトが「評価はどこに居るのか」に答えてくれます。評価はテストターゲットの中、ユニットテストの隣に居て、同じトレイトでゲートされます。.tags(.evals) というアノテーションは、.tags(.regression) がリグレッション実行の範囲を限定するのと同じやり方で、プロンプト変更の後にモデル品質チェックだけを実行します¹³。速いユニットスタイルのテストは編集のたびにグリーンを保ち、より遅いモデル駆動の評価は、モデルに触れるプロンプトやツール定義に対して実行されます。

評価とテストの分担は、エージェント的ワークフローの記事が描くランタイムとツールの分担を映し出しています。そこではアプリが出荷するオンデバイスモデルと、開発者がアプリを書くために実行するツールモデルとの間に線が引かれています²¹。Evaluations はその線のビルド側に位置します。反復作業の最中に実行する27サイクルの開発ツールであり、出荷するランタイム機能が十分に良いかどうかを測定します¹。XCTest を出荷しないのと同じく、Evaluations フレームワークをユーザーに出荷することはありません。出荷するのは、それが生み出す確信です。

フレームワークはまた、どのモデルを採点するかについて開かれたままです。Appleは、コードから利用できるあらゆるモデルで動作すると注記しており、データセット側は Loader を通じて供給されます。これはデータセットを供給する型のためのプロトコルで、組み込みの具象型を使うか、自前のソースのためにカスタムの準拠を実装します¹²²。モデルを審査員とする採点では、ModelJudgeEvaluator がクエリ、応答、そして任意の参照データを審査員モデルに送り、それが一つ以上のディメンションのスコアを返します²³。審査員のプロンプトは ModelJudgePrompt を通じて設定でき、これは指示、応答の提示方法、参照データの注入を一つの合成可能な値にまとめます²⁴。スタックがすでに信頼しているモデルがそれであれば、自前のコードパスを通じて Claude を審査員に使ってください。フレームワークは一つのモデルに縛りつけることはありません。

FAQ

Evaluations フレームワークとは何で、どのプラットフォームで動作しますか？

Evaluations フレームワークは、開発ワークフローに統合される型安全なSwift APIを使って、アプリのインテリジェンスを活用した機能の品質を測定します¹。27リリースでiOS、iPadOS、macOS、visionOS、watchOS にわたって新登場した、テスト時に（通常はMac上で）実行する開発ツールのフレームワークであり、アプリ内に組み込んで出荷するランタイム機能ではありません¹。データセットを定義し、モデルの応答を生成し、メトリクスを適用し、結果を集計します。そして、どのアプローチが最も良い成績だったか、個々の応答がどこで基準に届かなかったかを読み取ります¹。

なぜAI機能にXCTestやSwift Testingの等価アサーションを使えないのですか？

等価アサーションには期待される値が一つ必要ですが、非決定的なモデルにはそれがありません。同じプロンプトが実行のたびに異なる妥当な出力を生み出しうるからです。Evaluations は等価判定を採点された判断で置き換えます。Metric は passing、failing、scoring、ignore の結果を記録し、ScoreDimension は名前付きの軸で出力を採点します⁴⁵。評価は依然としてテストの中で、EvaluationTrait を通じて実行するので、他のテストと同じターゲット、同じ swift test のループの中に居ます¹²。

フレームワークはエージェント的なツール呼び出しの振る舞いをどう評価しますか？

ToolCallEvaluator を通じてです。これはエージェント的なツール呼び出しを期待される軌跡に照らして検証します⁹。経路を3つの軸にわたる TrajectoryExpectation として記述します。評価器は順序付きシーケンス、順序を問わない期待、禁止ツールのチェック、グループステップをサポートし、一つのパスから厳密な結果と部分的な結果の両方を生み出します⁹¹⁰。引数ごとの検証には ArgumentMatcher を使います（厳密な値、キーの存在、範囲、パターン、あるいはモデルベースの意味的照合）¹¹。

Evaluator と Evaluation プロトコルの違いは何ですか？

Evaluator は、カスタム型を定義せずインラインで使えるクロージャベースの評価器です。そのクロージャは入力サンプルと応答を受け取り、.value と .transcript にアクセスできます²。Evaluation プロトコルは、テスト対象システムをデータセットに対して実行し、評価器を適用する、再利用可能で名前の付いた評価を定義するために実装する型です³。手早いインラインのチェックには Evaluator を、構造化された反復可能なものには Evaluation プロトコルに手を伸ばしてください。

生成されたサンプルと結果はどこに居ますか？

SampleGenerator は、言語モデルから非同期ストリームとしてサンプルを生成するアクターです。イテレーションの後、受理されたサンプル、あるいはバリデーターが拒否したものを読み取れます⁷。結果は型付きの ResultColumn 記述子を備えた DataFrame に格納されます。responseColumn、inputColumn、expectedColumn です^8161715。MetricsAggregator がそのデータについて平均、中央値、標準偏差を計算します¹⁸。

Apple Ecosystem クラスター全体はこちらです。Foundation Models フレームワークの解説、ランタイムとツールのLLMの区別、このフレームワークが採点するiOS 27 のツール呼び出し制御、そして EvaluationTrait が組み込まれるトレイトモデルを持つSwift Testing と XCTest。ハブはApple Ecosystem シリーズにあります。AIエージェントを伴うiOSのより広い文脈については、iOS Agent Development ガイドをご覧ください。