Evaluations: XCTest para la calidad de los modelos (iOS 27)

Una prueba unitaria normal afirma que add(2, 2) devuelve 4, y si no lo hace, la compilación se marca en rojo. Una función de IA rompe ese contrato desde la primera línea, porque el mismo prompt puede producir una oración distinta en cada ejecución, y “distinto” no es lo mismo que “incorrecto”. No puedes escribir #expect(summary == "the expected summary") contra un modelo, porque no existe una única cadena esperada. Lo que sí puedes medir es si la salida es lo suficientemente buena, con la frecuencia suficiente, frente a criterios que tú defines. El nuevo framework Evaluations de Apple te da ese arnés de medición, con API de Swift con seguridad de tipos que se ejecutan como parte de tu flujo de trabajo de desarrollo¹. Es una novedad de la versión 27 y está disponible en todas las plataformas de Apple (iOS, iPadOS, macOS, visionOS y watchOS): una herramienta de desarrollo que ejecutas en tiempo de prueba, normalmente en tu Mac, no una función de tiempo de ejecución que distribuyes dentro de una app¹.

La forma te resultará familiar si has escrito pruebas. Defines un conjunto de datos, generas respuestas del modelo, aplicas métricas y agregas los resultados; luego lees qué enfoque tuvo el mejor desempeño y dónde se quedaron cortas las respuestas individuales¹. El modelo mental es XCTest para la calidad de los modelos: el mismo ciclo (preparar un caso, ejecutarlo, afirmar algo), pero con una afirmación distinta (una métrica con calificación en lugar de una igualdad).

En la sesión 298, Apple plantea el problema central así: las funciones de IA generativa rompen un contrato fundamental para las pruebas de software, porque la misma entrada puede producir salidas diferentes, lo que hace insuficientes las pruebas unitarias²⁵.

TL;DR / Puntos clave

• El framework Evaluations es una novedad de la versión 27 en todas las plataformas de Apple (iOS, iPadOS, macOS, visionOS, watchOS), una capa de herramientas de desarrollo para medir las funciones impulsadas por inteligencia, que se ejecuta como parte de tu flujo de trabajo de pruebas (normalmente en una Mac)¹.
• Evaluator es un evaluador basado en closures que escribes en línea; el protocolo Evaluation es el tipo que implementas para ejecutar un sistema bajo prueba contra un conjunto de datos y aplicar evaluadores²³.
• Metric transporta un resultado con nombre a través de métodos de fábrica (passing, failing, scoring, ignore), y ScoreDimension nombra un eje calificado para un evaluador de modelo como juez⁴⁵.
• ModelSample es una muestra de evaluación de propósito general; SampleGenerator es un actor que genera muestras a partir de un modelo de lenguaje como un flujo asíncrono; los resultados quedan en un DataFrame con columnas tipadas, incluida una responseColumn⁶⁷⁸.
• ToolCallEvaluator verifica las llamadas a herramientas de un agente contra una TrajectoryExpectation, donde ArgumentMatcher define cómo se valida cada argumento⁹¹⁰¹¹.
• EvaluationTrait ejecuta una evaluación dentro de una prueba y registra el resultado como adjuntos, que es el puente hacia una ejecución de Swift Testing¹².

Esta publicación recorre la superficie de la API, explica por qué existe cada pieza y la conecta de vuelta con el trabajo de tool-calling de Foundation Models que califica. Donde muestro una llamada cuya firma exacta Apple no ha publicado, la marco como ilustrativa y te indico que la confirmes contra la documentación.

El modelo del evaluador

La pregunta central del framework es “qué tan buena fue esta salida”, y la responde con un vocabulario reducido: un evaluador decide, una métrica registra, una dimensión de puntuación califica y un resultado agrega.

El protocolo Evaluation es el tipo que implementas para definir una evaluación, que ejecuta tu sistema bajo prueba contra un conjunto de datos y aplica evaluadores para medir el desempeño³. La declaración es mínima:

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

El protocolo es Sendable porque la evaluación es trabajo concurrente: muchas muestras, ejecutadas en paralelo, de la misma manera en que Swift Testing ejecuta los casos de prueba en paralelo de forma predeterminada¹³. Implementas el protocolo cuando quieres una evaluación reutilizable y con nombre. Cuando quieres algo rápido, recurres a Evaluator, que Apple describe como un evaluador basado en closures para uso en línea sin definir un tipo personalizado²:

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

La explicación de Apple señala que el closure recibe la muestra de entrada y la respuesta, con acceso tanto a .value como a .transcript². El .value es la salida tipada del modelo; el .transcript es el registro de cómo llegó a ella. Un evaluador en línea es un bloque #expect de una sola línea para la calidad del modelo: sin subclase, solo el criterio expresado como un closure. La siguiente forma de llamada es ilustrativa; confirma el inicializador contra la documentación de 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()
}

Lo que el closure devuelve es un Metric. Apple describe Metric como una métrica con nombre que transporta un valor de resultado, y nombra los métodos de fábrica de forma explícita: passing, failing, scoring e ignore devuelven cada uno un nuevo Metric con el resultado almacenado dentro⁴:

// 27.0 beta (all Apple platforms)
struct Metric

Las cuatro fábricas se corresponden con los tipos de criterio que necesita una función de IA. Un resumidor incluye el dato requerido o no lo hace, así que obtiene passing o failing. Una rúbrica que califica el tono va del 1 al 5, así que obtiene scoring. Una muestra que quieres dejar fuera del agregado (entrada mal formada, un caso de prueba conocido como erróneo) obtiene ignore, que mantiene la fila en el conjunto de datos sin contaminar las estadísticas. El rango que va desde passing hasta el scoring calificado es lo que promete el framework: desde verificaciones simples de aprobado o reprobado hasta puntuaciones detalladas con patrones de modelo como juez¹.

El extremo calificado de ese rango es donde ScoreDimension se gana su lugar. Apple lo define como una dimensión de puntuación con nombre para un evaluador de modelo como juez, donde cada dimensión define un nombre (usado como la columna del DataFrame), una descripción opcional y una definición de lo que significa cada puntuación⁵:

// 27.0 beta (all Apple platforms)
struct ScoreDimension

Una sola salida puede ser buena en un eje y mala en otro. Un correo redactado puede ser factualmente correcto y tonalmente equivocado. ScoreDimension te permite puntuar esos ejes por separado (corrección, tono, concisión) para que el agregado te diga qué dimensión bajó, no solo que la calidad general bajó. El nombre de la dimensión se convierte en una columna, lo que significa que las puntuaciones quedan en una tabla estructurada que puedes ordenar y comparar, no en un muro de texto.

Esa tabla es un EvaluationResult. Apple lo describe como los resultados de ejecutar una evaluación de modelo, una estructura que contiene el resumen y los resultados detallados de una ejecución de evaluación¹⁴:

// 27.0 beta (all Apple platforms)
struct EvaluationResult

La forma de dos niveles (resumen más detalle) es lo que hace accionables las evaluaciones. El resumen responde “¿este prompt rindió mejor que el anterior?”. El detalle responde “¿qué muestras se quedaron cortas?”, para que puedas abrir las peores filas y leer lo que produjo el modelo¹.

Muestras y generación

Una evaluación necesita casos contra los cuales ejecutarse, y la unidad de un caso en el framework es una muestra. ModelSample es la de propósito general. Apple la describe como una muestra de evaluación de modelo de lenguaje de propósito general que acepta prompts e instrucciones basados en cadenas⁶:

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

El genérico ExpectedValue es la expectativa tipada: una cadena para una tarea de texto libre, un tipo estructurado Codable para una con respuesta conocida. Las restricciones Codable más Sendable coinciden con el Input.ExpectedValue de Evaluator, porque la expectativa tiene que serializarse en la tabla de resultados y cruzar los límites de concurrencia durante una ejecución en paralelo. Para prompts multimodales, Apple señala que creas una conformidad personalizada o usas un inicializador con un prompt preconstruido⁶.

Escribir a mano cada muestra no escala, por lo que existe SampleGenerator, un actor que genera muestras de evaluación usando un modelo de lenguaje⁷:

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

Es un actor porque posee un estado de generación mutable (muestras aceptadas y rechazadas) que la iteración asíncrona modifica, y el aislamiento de actores es la salvaguarda de Swift contra las condiciones de carrera sobre ese estado. El flujo de trabajo de Apple: creas un generador, configuras sus propiedades y luego lo invocas para producir nuevas muestras como un flujo asíncrono; tras la iteración, accedes a todas las muestras generadas, o a cualquiera que el validador haya rechazado⁷. El cubo de las rechazadas es el detalle en el que vale la pena detenerse. Un generador que descartara silenciosamente las muestras malas ocultaría su propia tasa de fallo; exponer las rechazadas te permite auditar el conjunto de datos como auditarías casos de prueba escritos a mano.

Una vez que las muestras se ejecutan, las respuestas quedan en un DataFrame con descriptores de columna tipados, de modo que lees la tabla sin búsquedas basadas en cadenas. Apple nombra la columna de respuesta de forma exacta: responseColumn, un descriptor de columna tipado para las respuestas del modelo en el DataFrame detallado⁸:

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

El genérico ResultColumn<Value> es lo que hace que la columna sea tipada: un descriptor para una columna del DataFrame, parametrizado por el valor que contiene¹⁵. Junto a responseColumn, el framework expone una inputColumn para las muestras de entrada y una expectedColumn para los valores esperados, cada una un ResultColumn tipado¹⁶¹⁷. Las columnas tipadas responden al mismo instinto que la captura de expresiones de Swift Testing: en lugar de sacar un valor de una bolsa sin tipo y confiar en que la conversión funcione, lo lees a través de un descriptor que conoce su tipo. Cuando alimentas los resultados a MetricsAggregator para la media, la mediana y la desviación estándar, las columnas son la manera de direccionar los datos sin adivinar las claves¹⁸.

Verificación de herramientas y trayectorias

La función de IA más difícil de probar es la de un agente, porque la corrección no es una cadena, es una secuencia de acciones. Cuando una sesión de Foundation Models llama a OCRTool, luego a BarcodeReaderTool y después a tu propia consulta de catálogo, la pregunta no es “¿la oración final coincidió?”, sino “¿el modelo tomó el camino correcto?”¹⁹. ToolCallEvaluator califica ese camino directamente. Apple lo describe como un evaluador que verifica las llamadas a herramientas de un agente contra una trayectoria esperada⁹:

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

La cláusula where es la parte que sostiene todo: la expectativa de la entrada debe ser una TrajectoryExpectation. Apple describe ese tipo como el patrón esperado de llamadas a herramientas para una evaluación, especificado a lo largo de tres ejes¹⁰:

// 27.0 beta (all Apple platforms)
struct TrajectoryExpectation

Apple indica que ToolCallEvaluator admite secuencias ordenadas, expectativas sin orden, verificaciones de herramientas no permitidas y pasos agrupados, y produce un resultado tanto estricto como parcial a partir de una sola pasada de evaluación⁹. Cada uno se corresponde con un fallo real de un agente. Las secuencias ordenadas detectan un modelo que llama a las herramientas correctas en el orden equivocado. Las expectativas sin orden dicen “estas llamadas deben ocurrir, sin importar el orden”. Las verificaciones de herramientas no permitidas detectan un modelo que recurre a una herramienta que jamás debería tocar (el caso de seguridad: un agente que llama a una herramienta destructiva cuando debió haberse mantenido en solo lectura). Los pasos agrupados expresan “cualquiera de estos”, para ramas donde más de un camino es aceptable.

El par estricto más parcial encaja con la forma en que la calidad de un agente realmente se degrada. Un prompt nuevo rara vez lleva una función de perfecta a rota; la lleva de “trayectoria correcta siempre” a “trayectoria correcta la mayoría de las veces, con una llamada fuera de orden”. Un resultado solo estricto reporta eso como un fallo plano y no te dice nada sobre qué tan cerca estuvo el modelo. El resultado parcial cuantifica los casi aciertos, que es la señal contra la que ajustas.

La corrección de cada llamada vive un nivel más abajo, en los argumentos. Un modelo puede llamar a la herramienta correcta con los valores equivocados, y ArgumentMatcher define cómo se valida cada argumento. Apple lo describe como los valores que definen cómo validar un argumento de una llamada a herramienta¹¹:

// 27.0 beta (all Apple platforms)
enum ArgumentMatcher

La explicación de Apple enumera las reglas de validación: exigir valores exactos, verificar la presencia de una clave, comprobar rangos, hacer coincidir patrones o usar un modelo de lenguaje para una coincidencia semántica¹¹. El caso de coincidencia semántica es el que una afirmación de igualdad simple no puede expresar. Si un argumento de herramienta es una consulta de texto libre, dos cadenas distintas pueden ser igualmente correctas, y un == normal reprobaría una llamada perfectamente buena. Delegar ese argumento a una coincidencia de modelo como juez es la misma vía de escape que ScoreDimension ofrece a nivel de salida, aplicada a nivel de argumento. La escritura de los casos proviene de la enumeración de Apple; lo siguiente es ilustrativo, así que confírmalo contra la documentación:

import Evaluations

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

El ciclo del agente aquí es el mismo que la publicación sobre tool-calling de Foundation Models describe desde el lado del tiempo de ejecución. Allí, GenerationOptions.ToolCallingMode gobierna con cuánta agresividad el modelo en el dispositivo recurre a las herramientas, y el framework puede cambiar el modo después de la primera llamada para acotar la actividad de herramientas de una solicitud¹⁹. ToolCallEvaluator es el lado de medición de ese mismo comportamiento: fijas la postura de llamada en tiempo de ejecución y luego calificas la trayectoria en tiempo de prueba para confirmar que la postura produjo el camino que pretendías. La perilla de tiempo de ejecución y el evaluador de tiempo de prueba son los dos extremos de una misma función.

Cómo encaja esto en un flujo de trabajo

Las evaluaciones no son un ritual aparte que ejecutas cada trimestre. Pertenecen junto a tus pruebas, en el mismo ciclo, ejecutadas en la misma Mac. El puente del framework hacia ese ciclo es EvaluationTrait. Apple lo describe como un trait de prueba que ejecuta una evaluación y registra el resultado como adjuntos¹²:

// 27.0 beta (all Apple platforms)
struct EvaluationTrait

La palabra “trait” es deliberada. Todo el modelo de configuración de Swift Testing son traits aplicados a las declaraciones @Test y @Suite: .enabled(if:), .disabled(_:), .tags(...) y los demás¹³. EvaluationTrait inserta una evaluación dentro de ese vocabulario, de modo que una evaluación se ejecuta como se ejecuta una prueba, bajo la misma invocación swift test, con el mismo paralelismo. Registrar el resultado como adjuntos reutiliza el mecanismo que Swift Testing ya tiene para adjuntos personalizados, así que el resultado detallado de una evaluación viaja en el informe de pruebas y en los artefactos de CI que recopilas¹³. El framework también expone un EvaluationContext para que el código dentro del ámbito de la prueba pueda leer el resultado una vez que la evaluación se completa²⁰.

Ese trait responde a “dónde viven las evaluaciones”. Viven en tu target de pruebas, junto a tus pruebas unitarias, controladas por los mismos traits. Una anotación .tags(.evals) ejecuta solo las verificaciones de calidad del modelo después de un cambio de prompt, de la misma forma en que .tags(.regression) acota una ejecución de regresión¹³. Las pruebas rápidas, al estilo unitario, se mantienen en verde en cada edición; las evaluaciones más lentas, impulsadas por el modelo, se ejecutan sobre los prompts y las definiciones de herramientas que tocan el modelo.

La división evaluación-frente-a-prueba refleja la división tiempo-de-ejecución-frente-a-herramientas de la publicación sobre flujos de trabajo de agentes, que traza la línea entre el modelo en el dispositivo que la app distribuye y el modelo de herramientas que el desarrollador ejecuta para escribir la app²¹. Evaluations se sitúa del lado de la compilación de esa línea: una herramienta de desarrollo del ciclo 27, ejecutada durante la iteración, que mide si la función de tiempo de ejecución que distribuyes es lo suficientemente buena¹. No distribuyes el framework Evaluations a los usuarios, igual que no distribuyes XCTest. Distribuyes la confianza que produce.

El framework también se mantiene abierto respecto a qué modelo calificas. Apple señala que funciona con cualquier modelo disponible para tu código, y el lado del conjunto de datos se alimenta a través de un Loader, un protocolo para tipos que suministran un conjunto de datos, con tipos concretos integrados o una conformidad personalizada para tus propias fuentes¹²². Para la calificación de modelo como juez, ModelJudgeEvaluator envía la consulta, la respuesta y datos de referencia opcionales a un modelo juez que devuelve puntuaciones para una o más dimensiones²³, con el prompt del juez configurable a través de ModelJudgePrompt, que agrupa las instrucciones, la presentación de la respuesta y la inyección de datos de referencia en un único valor componible²⁴. Usa Claude a través de tu propio camino de código para el juez si ese es el modelo en el que tu stack ya confía; el framework no te ata a uno solo.

Preguntas frecuentes

¿Qué es el framework Evaluations y en qué plataforma se ejecuta?

El framework Evaluations mide la calidad de las funciones impulsadas por inteligencia de tu app usando API de Swift con seguridad de tipos que se integran en tu flujo de trabajo de desarrollo¹. Es una novedad de la versión 27 en iOS, iPadOS, macOS, visionOS y watchOS: un framework de herramientas de desarrollo que ejecutas en tiempo de prueba (normalmente en una Mac), no una función de tiempo de ejecución distribuida dentro de una app¹. Defines conjuntos de datos, generas respuestas del modelo, aplicas métricas y agregas resultados; luego lees qué enfoque tuvo el mejor desempeño y dónde se quedaron cortas las respuestas individuales¹.

¿Por qué no puedo usar las afirmaciones de igualdad de XCTest o Swift Testing para funciones de IA?

Una afirmación de igualdad necesita un único valor esperado, y un modelo no determinista no lo tiene: el mismo prompt puede producir una salida válida distinta en cada ejecución. Evaluations reemplaza la igualdad por un criterio calificado. Un Metric registra un resultado passing, failing, scoring o ignore, y un ScoreDimension califica una salida en un eje con nombre⁴⁵. Aun así ejecutas las evaluaciones dentro de una prueba, a través de EvaluationTrait, de modo que viven en el mismo target y en el mismo ciclo swift test que tus otras pruebas¹².

¿Cómo evalúa el framework el comportamiento de tool-calling de un agente?

A través de ToolCallEvaluator, que verifica las llamadas a herramientas de un agente contra una trayectoria esperada⁹. Describes el camino como una TrajectoryExpectation a lo largo de tres ejes; el evaluador admite secuencias ordenadas, expectativas sin orden, verificaciones de herramientas no permitidas y pasos agrupados, y produce resultados tanto estrictos como parciales en una sola pasada⁹¹⁰. La validación por argumento usa ArgumentMatcher (valores exactos, presencia de clave, rangos, patrones o coincidencia semántica basada en un modelo)¹¹.

¿Cuál es la diferencia entre un Evaluator y el protocolo Evaluation?

Evaluator es un evaluador basado en closures para uso en línea sin definir un tipo personalizado; su closure recibe la muestra de entrada y la respuesta, con acceso a .value y .transcript². El protocolo Evaluation es el tipo que implementas para definir una evaluación reutilizable y con nombre que ejecuta tu sistema bajo prueba contra un conjunto de datos y aplica evaluadores³. Recurre a Evaluator para una verificación rápida en línea, y al protocolo Evaluation para una estructurada y repetible.

¿Dónde viven las muestras generadas y los resultados?

SampleGenerator es un actor que produce muestras a partir de un modelo de lenguaje como un flujo asíncrono; tras la iteración lees las muestras aceptadas o las que el validador rechazó⁷. Los resultados quedan en un DataFrame con descriptores ResultColumn tipados: responseColumn, inputColumn y expectedColumn^8161715. MetricsAggregator calcula la media, la mediana y la desviación estándar sobre esos datos¹⁸.

El clúster completo del Ecosistema Apple: el explicador del framework Foundation Models; la distinción entre LLM de tiempo de ejecución y de herramientas; el control de tool-calling de iOS 27 que este framework califica; y Swift Testing frente a XCTest, en cuyo modelo de traits se conecta EvaluationTrait. El hub está en la Serie del Ecosistema Apple. Para un contexto más amplio sobre iOS con agentes de IA, consulta la guía de Desarrollo de Agentes en iOS.