Evaluations: o XCTest para qualidade de modelo (iOS 27)

Um teste de unidade comum afirma que add(2, 2) retorna 4 e, se não retornar, o build fica vermelho. Um recurso de IA quebra esse contrato logo na primeira linha, porque o mesmo prompt pode produzir uma frase diferente a cada execução, e “diferente” não é “errado”. Você não consegue escrever #expect(summary == "o resumo esperado") contra um modelo, porque não existe uma única string esperada. O que você pode medir é se a saída é boa o suficiente, com frequência suficiente, segundo critérios que você mesmo define. O novo framework Evaluations da Apple oferece exatamente esse aparato de medição, com APIs Swift type-safe que rodam como parte do seu fluxo de desenvolvimento¹. Ele é novidade no release 27 e está disponível em todas as plataformas da Apple (iOS, iPadOS, macOS, visionOS e watchOS): uma ferramenta de desenvolvedor que você executa em tempo de teste, normalmente no seu Mac, e não um recurso de tempo de execução que você embarca dentro de um app¹.

O formato vai parecer familiar para quem já escreveu testes. Você define um conjunto de dados, gera respostas do modelo, aplica métricas e agrega resultados; depois, lê qual abordagem teve o melhor desempenho e onde respostas individuais ficaram aquém¹. O modelo mental é o XCTest para qualidade de modelo: o mesmo ciclo (preparar um caso, executá-lo, afirmar algo), com uma asserção diferente (uma métrica graduada em vez de igualdade).

Na sessão 298, a Apple enquadra o problema central assim: recursos de IA generativa quebram um contrato fundamental para os testes de software, porque a mesma entrada pode produzir saídas diferentes, o que torna os testes de unidade insuficientes²⁵.

TL;DR / Principais conclusões

• O framework Evaluations é novidade no release 27 em todas as plataformas da Apple (iOS, iPadOS, macOS, visionOS, watchOS), uma camada de ferramental de desenvolvedor para medir recursos movidos a inteligência, executada como parte do seu fluxo de testes (normalmente em um Mac)¹.
• Evaluator é um avaliador baseado em closure que você escreve inline; o protocolo Evaluation é o tipo que você implementa para rodar um sistema sob teste contra um conjunto de dados e aplicar avaliadores²³.
• Metric carrega um resultado nomeado por meio de métodos de fábrica (passing, failing, scoring, ignore), e ScoreDimension nomeia um eixo graduado para um avaliador no modelo-como-juiz⁴⁵.
• ModelSample é uma amostra de avaliação de uso geral; SampleGenerator é um actor que gera amostras a partir de um modelo de linguagem como um stream assíncrono; os resultados caem em um DataFrame com colunas tipadas, incluindo uma responseColumn⁶⁷⁸.
• ToolCallEvaluator verifica chamadas de ferramentas agênticas contra uma TrajectoryExpectation, com o ArgumentMatcher definindo como cada argumento é validado⁹¹⁰¹¹.
• EvaluationTrait roda uma avaliação dentro de um teste e registra o resultado como anexos, o que é a ponte para uma execução de Swift Testing¹².

O post percorre a superfície da API, explica por que cada peça existe e a conecta de volta ao trabalho de chamada de ferramentas do Foundation Models que ela avalia. Sempre que eu mostrar uma chamada cuja assinatura exata a Apple não publicou, eu a marco como ilustrativa e oriento você a confirmar na documentação.

O modelo do Evaluator

A pergunta central do framework é “quão boa foi esta saída”, e ele a responde com um vocabulário enxuto: um avaliador decide, uma métrica registra, uma dimensão de pontuação gradua e um resultado agrega.

O protocolo Evaluation é o tipo que você implementa para definir uma avaliação, que roda seu sistema sob teste contra um conjunto de dados e aplica avaliadores para medir o desempenho³. A declaração é mínima:

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

O protocolo é Sendable porque avaliação é trabalho concorrente: muitas amostras, executadas em paralelo, do mesmo jeito que o Swift Testing roda casos de teste em paralelo por padrão¹³. Você implementa o protocolo quando quer uma avaliação reutilizável e nomeada. Quando quer algo rápido, recorre ao Evaluator, que a Apple descreve como um avaliador baseado em closure para uso inline sem definir um tipo próprio²:

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

A discussão da Apple afirma que a closure recebe a amostra de entrada e a resposta, com acesso tanto a .value quanto a .transcript². O .value é a saída tipada do modelo; o .transcript é o registro de como ele chegou lá. Um avaliador inline é um bloco #expect de uma linha para qualidade de modelo: nada de subclasse, apenas o julgamento como uma closure. O formato de chamada a seguir é ilustrativo; confirme o inicializador na documentação da 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()
}

O que a closure retorna é uma Metric. A Apple descreve Metric como uma métrica nomeada que carrega um valor de resultado, e nomeia os métodos de fábrica explicitamente: passing, failing, scoring e ignore retornam, cada um, uma nova Metric com o resultado armazenado dentro⁴:

// 27.0 beta (all Apple platforms)
struct Metric

As quatro fábricas mapeiam os tipos de julgamento de que um recurso de IA precisa. Um resumidor ou inclui o fato exigido ou não inclui, então recebe passing ou failing. Um critério de avaliação de tom vai de 1 a 5, então recebe scoring. Uma amostra que você quer fora da agregação (entrada malformada, uma fixture sabidamente ruim) recebe ignore, que mantém a linha no conjunto de dados sem poluir as estatísticas. A faixa que vai de passing até o scoring graduado é exatamente o que o framework promete: de simples verificações de passou ou falhou até pontuação detalhada com padrões de modelo-como-juiz¹.

É na ponta graduada dessa faixa que ScoreDimension conquista seu lugar. A Apple o define como uma dimensão de pontuação nomeada para um avaliador com modelo juiz, em que cada dimensão define um nome (usado como coluna do DataFrame), uma descrição opcional e uma definição do que cada pontuação significa⁵:

// 27.0 beta (all Apple platforms)
struct ScoreDimension

Uma única saída pode ser boa em um eixo e ruim em outro. Um e-mail rascunhado pode estar factualmente correto e tonalmente errado. ScoreDimension permite pontuar esses eixos separadamente (correção, tom, concisão), de modo que a agregação diga qual dimensão caiu, não apenas que a qualidade geral caiu. O nome da dimensão vira uma coluna, o que significa que as pontuações caem em uma tabela estruturada, que dá para ordenar e comparar, em vez de uma parede de prosa.

Essa tabela é um EvaluationResult. A Apple o descreve como o resultado da execução de uma avaliação de modelo, uma estrutura que contém o resumo e os resultados detalhados de uma execução de avaliação¹⁴:

// 27.0 beta (all Apple platforms)
struct EvaluationResult

O formato em dois níveis (resumo mais detalhe) é o que torna as evals acionáveis. O resumo responde “este prompt se saiu melhor do que o anterior”. O detalhe responde “quais amostras ficaram aquém”, para você abrir as piores linhas e ler o que o modelo produziu¹.

Amostras e geração

Uma avaliação precisa de casos contra os quais rodar, e a unidade de caso do framework é uma amostra. ModelSample é a de uso geral. A Apple a descreve como uma amostra de avaliação de modelo de linguagem de uso geral que aceita prompts e instruções baseados em string⁶:

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

O genérico ExpectedValue é a expectativa tipada: uma string para uma tarefa de texto livre, um tipo Codable estruturado para uma com resposta conhecida. As restrições Codable mais Sendable casam com o Input.ExpectedValue do Evaluator, porque a expectativa precisa serializar para a tabela de resultados e cruzar fronteiras de concorrência durante uma execução paralela. Para prompts multimodais, a Apple observa que você cria uma conformidade própria ou usa um inicializador com um prompt pré-montado⁶.

Escrever cada amostra à mão não escala, e é por isso que existe o SampleGenerator, um actor que gera amostras de avaliação usando um modelo de linguagem⁷:

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

Ele é um actor porque detém estado mutável de geração (amostras aceitas e rejeitadas) que a iteração assíncrona altera, e o isolamento de actor é a proteção do Swift contra data races nesse estado. O fluxo da Apple: você cria um gerador, configura suas propriedades e então o chama para produzir novas amostras como um stream assíncrono; após a iteração, você acessa todas as amostras geradas ou quaisquer que o validador tenha rejeitado⁷. O balde dos rejeitados é o detalhe em que vale a pena parar. Um gerador que descartasse silenciosamente as amostras ruins esconderia sua própria taxa de falha; expor os rejeitados permite auditar o conjunto de dados do mesmo jeito que você auditaria fixtures escritas à mão.

Assim que as amostras rodam, as respostas caem em um DataFrame com descritores de coluna tipados, então você lê a tabela sem buscas por string. A Apple nomeia a coluna de resposta com precisão: responseColumn, um descritor de coluna tipado para as respostas do modelo no DataFrame detalhado⁸:

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

O genérico ResultColumn<Value> é o que torna a coluna tipada: um descritor para uma coluna de DataFrame, parametrizado pelo valor que ela guarda¹⁵. Ao lado de responseColumn, o framework expõe uma inputColumn para as amostras de entrada e uma expectedColumn para os valores esperados, cada uma uma ResultColumn tipada¹⁶¹⁷. Colunas tipadas seguem o mesmo instinto da captura de expressões do Swift Testing: em vez de tirar um valor de um saco sem tipo e torcer para o cast funcionar, você o lê por meio de um descritor que conhece o próprio tipo. Quando você alimenta os resultados no MetricsAggregator para média, mediana e desvio padrão, as colunas são como você endereça os dados sem adivinhar chaves¹⁸.

Verificação de ferramentas e trajetórias

O recurso de IA mais difícil de testar é o agêntico, porque correção não é uma string, é uma sequência de ações. Quando uma sessão do Foundation Models chama OCRTool, depois BarcodeReaderTool, depois sua própria consulta de catálogo, a pergunta não é “a frase final bateu”, mas “o modelo seguiu o caminho certo”¹⁹. ToolCallEvaluator avalia esse caminho diretamente. A Apple o descreve como um avaliador que verifica chamadas de ferramentas agênticas contra uma trajetória esperada⁹:

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

A cláusula where é a parte que sustenta tudo: a expectativa da entrada precisa ser uma TrajectoryExpectation. A Apple descreve esse tipo como o padrão esperado de chamadas de ferramentas para uma avaliação, especificado em três eixos¹⁰:

// 27.0 beta (all Apple platforms)
struct TrajectoryExpectation

A Apple afirma que ToolCallEvaluator dá suporte a sequências ordenadas, expectativas não ordenadas, verificações de ferramentas proibidas e passos em grupo, e produz tanto um resultado estrito quanto um parcial a partir de uma única passada de avaliação⁹. Cada um corresponde a uma falha real de agente. Sequências ordenadas pegam um modelo que chama as ferramentas certas na ordem errada. Expectativas não ordenadas dizem “estas chamadas precisam acontecer, ordem à parte”. Verificações de ferramentas proibidas pegam um modelo que recorre a uma ferramenta na qual nunca deveria tocar (o caso de segurança: um agente chamando uma ferramenta destrutiva quando deveria ter permanecido somente leitura). Passos em grupo expressam “qualquer um destes”, para ramificações em que mais de um caminho é aceitável.

A dupla estrito-mais-parcial encaixa no modo como a qualidade agêntica de fato se degrada. Um prompt novo raramente leva um recurso do perfeito ao quebrado; ele o leva de “trajetória certa toda vez” para “trajetória certa na maioria das vezes, com uma chamada fora de ordem”. Um resultado só estrito reporta isso como uma falha seca e não diz nada sobre o quão perto o modelo chegou. O resultado parcial quantifica os quase-acertos, que é o sinal contra o qual você ajusta.

A correção por chamada vive um nível abaixo, nos argumentos. Um modelo pode chamar a ferramenta certa com os valores errados, e o ArgumentMatcher define como cada argumento é validado. A Apple o descreve como os valores que definem como validar um argumento de chamada de ferramenta¹¹:

// 27.0 beta (all Apple platforms)
enum ArgumentMatcher

A discussão da Apple lista as regras de validação: exigir valores exatos, verificar a presença de uma chave, checar intervalos, casar padrões ou usar um modelo de linguagem para correspondência semântica¹¹. O caso da correspondência semântica é aquele que uma simples asserção de igualdade não consegue expressar. Se um argumento de ferramenta é uma consulta de texto livre, duas strings diferentes podem estar igualmente corretas, e um == comum reprovaria uma chamada perfeitamente boa. Delegar esse argumento a uma correspondência por modelo-como-juiz é a mesma saída de emergência que ScoreDimension oferece no nível da saída, só que aplicada no nível do argumento. As grafias dos casos vêm da enumeração da Apple; o que segue é ilustrativo, então confirme na documentação:

import Evaluations

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

O ciclo agêntico aqui é o mesmo que o post sobre chamada de ferramentas do Foundation Models descreve pelo lado do tempo de execução. Lá, GenerationOptions.ToolCallingMode governa com que agressividade o modelo on-device recorre a ferramentas, e o framework pode trocar o modo após a primeira chamada para limitar a atividade de ferramentas de uma requisição¹⁹. ToolCallEvaluator é o lado da medição desse mesmo comportamento: você define a postura de chamada em tempo de execução e depois avalia a trajetória em tempo de teste para confirmar que a postura produziu o caminho que você pretendia. O botão de tempo de execução e o avaliador de tempo de teste são duas pontas de um mesmo recurso.

Como isso se encaixa em um fluxo de trabalho

Evals não são um ritual à parte que você roda trimestralmente. Elas ficam ao lado dos seus testes, no mesmo ciclo, rodando no mesmo Mac. A ponte do framework para esse ciclo é o EvaluationTrait. A Apple o descreve como um trait de teste que roda uma avaliação e registra o resultado como anexos¹²:

// 27.0 beta (all Apple platforms)
struct EvaluationTrait

A palavra “trait” é deliberada. Todo o modelo de configuração do Swift Testing é feito de traits aplicados a declarações @Test e @Suite: .enabled(if:), .disabled(_:), .tags(...) e o resto¹³. EvaluationTrait encaixa uma avaliação nesse vocabulário, de modo que uma eval roda do jeito que um teste roda, sob a mesma invocação swift test, com o mesmo paralelismo. Registrar o resultado como anexos reutiliza o mecanismo que o Swift Testing já tem para anexos personalizados, então o resultado detalhado de uma eval segue junto no relatório de teste e nos artefatos de CI que você coleta¹³. O framework também expõe um EvaluationContext para que o código dentro do escopo do teste possa ler o resultado depois que a avaliação termina²⁰.

Esse trait responde “onde as evals vivem”. Elas vivem no seu target de teste, ao lado dos seus testes de unidade, condicionadas pelos mesmos traits. Uma anotação .tags(.evals) roda apenas as verificações de qualidade de modelo após uma mudança de prompt, do jeito que .tags(.regression) delimita uma execução de regressão¹³. Testes rápidos, no estilo de unidade, ficam verdes a cada edição; as evals mais lentas, movidas a modelo, rodam nos prompts e nas definições de ferramentas que tocam o modelo.

A separação eval-versus-teste espelha a separação tempo-de-execução-versus-ferramental do post sobre fluxo agêntico, que traça a linha entre o modelo on-device que o app embarca e o modelo de ferramental que o desenvolvedor roda para escrever o app²¹. Evaluations fica do lado de build dessa linha: uma ferramenta de desenvolvedor do ciclo 27, executada durante a iteração, que mede se o recurso de tempo de execução que você embarca é bom o suficiente¹. Você não embarca o framework Evaluations para os usuários, assim como não embarca o XCTest. Você embarca a confiança que ele produz.

O framework também permanece aberto quanto a qual modelo você avalia. A Apple observa que ele funciona com qualquer modelo disponível ao seu código, e o lado do conjunto de dados é alimentado por um Loader, um protocolo para tipos que fornecem um conjunto de dados, com tipos concretos embutidos ou uma conformidade própria para suas próprias fontes¹²². Para avaliação no modelo-como-juiz, ModelJudgeEvaluator envia a consulta, a resposta e dados de referência opcionais a um modelo juiz que retorna pontuações para uma ou mais dimensões²³, com o prompt do juiz configurável por meio de ModelJudgePrompt, que reúne instruções, apresentação da resposta e injeção de dados de referência em um único valor componível²⁴. Use o Claude pelo seu próprio caminho de código como juiz, se for esse o modelo em que sua stack já confia; o framework não prende você a um só.

Perguntas frequentes

O que é o framework Evaluations e em qual plataforma ele roda?

O framework Evaluations mede a qualidade dos recursos do seu app movidos a inteligência usando APIs Swift type-safe que se integram ao seu fluxo de desenvolvimento¹. Ele é novidade no release 27 em iOS, iPadOS, macOS, visionOS e watchOS: um framework de ferramental de desenvolvedor que você executa em tempo de teste (normalmente em um Mac), e não um recurso de tempo de execução embarcado dentro de um app¹. Você define conjuntos de dados, gera respostas do modelo, aplica métricas e agrega resultados; depois, lê qual abordagem teve o melhor desempenho e onde respostas individuais ficaram aquém¹.

Por que não posso usar as asserções de igualdade do XCTest ou do Swift Testing para recursos de IA?

Uma asserção de igualdade precisa de um único valor esperado, e um modelo não determinístico não tem um: o mesmo prompt pode produzir uma saída válida diferente a cada execução. Evaluations substitui igualdade por julgamento graduado. Uma Metric registra um resultado passing, failing, scoring ou ignore, e uma ScoreDimension avalia uma saída em um eixo nomeado⁴⁵. Você ainda roda as evals dentro de um teste, por meio do EvaluationTrait, então elas vivem no mesmo target e no mesmo ciclo swift test que os seus outros testes¹².

Como o framework avalia o comportamento agêntico de chamada de ferramentas?

Por meio do ToolCallEvaluator, que verifica chamadas de ferramentas agênticas contra uma trajetória esperada⁹. Você descreve o caminho como uma TrajectoryExpectation em três eixos; o avaliador dá suporte a sequências ordenadas, expectativas não ordenadas, verificações de ferramentas proibidas e passos em grupo, produzindo tanto resultados estritos quanto parciais em uma passada⁹¹⁰. A validação por argumento usa o ArgumentMatcher (valores exatos, presença de chave, intervalos, padrões ou correspondência semântica baseada em modelo)¹¹.

Qual é a diferença entre um Evaluator e o protocolo Evaluation?

Evaluator é um avaliador baseado em closure para uso inline sem definir um tipo próprio; sua closure recebe a amostra de entrada e a resposta, com acesso a .value e .transcript². O protocolo Evaluation é o tipo que você implementa para definir uma avaliação reutilizável e nomeada que roda seu sistema sob teste contra um conjunto de dados e aplica avaliadores³. Recorra ao Evaluator para uma verificação inline rápida e ao protocolo Evaluation para uma estruturada e repetível.

Onde vivem as amostras geradas e os resultados?

SampleGenerator é um actor que produz amostras a partir de um modelo de linguagem como um stream assíncrono; após a iteração, você lê as amostras aceitas ou as que o validador rejeitou⁷. Os resultados caem em um DataFrame com descritores ResultColumn tipados: responseColumn, inputColumn e expectedColumn^8161715. MetricsAggregator calcula média, mediana e desvio padrão sobre esses dados¹⁸.

O cluster completo do Apple Ecosystem: o explicador do framework Foundation Models; a distinção entre LLM de tempo de execução e de ferramental; o controle de chamada de ferramentas do iOS 27 que este framework avalia; e Swift Testing vs. XCTest, em cujo modelo de traits o EvaluationTrait se conecta. O hub fica na série Apple Ecosystem. Para um contexto mais amplo de iOS com agentes de IA, veja o guia de Desenvolvimento de Agentes para iOS.