LLM evaluation in .NET: testare la qualità delle risposte con Microsoft.Extensions.AI.Evaluation

services:
  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama-models:/root/.ollama
    healthcheck:
      test: ["CMD", "ollama", "list"]
      interval: 10s
      timeout: 5s
      retries: 10

  # scarica llama3.1 nel volume condiviso, poi esce
  ollama-init:
    image: ollama/ollama:latest
    depends_on:
      ollama:
        condition: service_healthy
    environment:
      OLLAMA_HOST: http://ollama:11434
    entrypoint: ["/bin/sh", "-c", "ollama pull llama3.1"]
    restart: "no"

volumes:
  ollama-models:

$ dotnet new sln -n LlmEvalDemo
$ dotnet new classlib -n SupportAssistant -o src/SupportAssistant -f net8.0
$ dotnet new xunit -n SupportAssistant.Evaluation.Tests \
    -o tests/SupportAssistant.Evaluation.Tests -f net8.0
$ dotnet sln add src/SupportAssistant tests/SupportAssistant.Evaluation.Tests

# la class library vede solo le astrazioni
$ dotnet add src/SupportAssistant package Microsoft.Extensions.AI.Abstractions

# tutta l'evaluation sta nel progetto di test
$ cd tests/SupportAssistant.Evaluation.Tests
$ dotnet add reference ../../src/SupportAssistant
$ dotnet add package Microsoft.Extensions.AI
$ dotnet add package Microsoft.Extensions.AI.Evaluation
$ dotnet add package Microsoft.Extensions.AI.Evaluation.Quality
$ dotnet add package Microsoft.Extensions.AI.Evaluation.Reporting
$ dotnet add package OllamaSharp

# il tool aieval per il report
$ cd ../.. && dotnet new tool-manifest
$ dotnet tool install Microsoft.Extensions.AI.Evaluation.Console

using Microsoft.Extensions.AI;

namespace SupportAssistant;

// Il sistema sotto test: un assistente che risponde SOLO dal contesto
// fornito — esattamente il comportamento che il GroundednessEvaluator
// verifichera' nella suite.
public class SupportAssistantService(IChatClient chat)
{
    private const string SystemPrompt =
        "You are the support assistant of a software product. " +
        "Answer using ONLY the information in the provided context. " +
        "If the context does not contain the answer, say you don't know " +
        "and suggest contacting support. " +
        "Keep the answer under 80 words and reply in the same language " +
        "as the question.";

    // Restituisce messaggi + risposta: gli evaluator giudicano la
    // risposta rispetto all'intera conversazione, non da sola.
    public async Task<(IList<ChatMessage> Messages, ChatResponse Response)> AskAsync(
        string question,
        string context,
        CancellationToken ct = default)
    {
        IList<ChatMessage> messages =
        [
            new(ChatRole.System, SystemPrompt),
            new(ChatRole.User, $"Context:\n{context}\n\nQuestion: {question}")
        ];

        ChatOptions options = new() { Temperature = 0f };
        ChatResponse response = await chat.GetResponseAsync(messages, options, ct);
        return (messages, response);
    }
}

using Microsoft.Extensions.AI;
using Microsoft.Extensions.AI.Evaluation;
using Microsoft.Extensions.AI.Evaluation.Quality;
using Microsoft.Extensions.AI.Evaluation.Reporting;
using Microsoft.Extensions.AI.Evaluation.Reporting.Storage;
using Microsoft.Extensions.Configuration;
using OllamaSharp;

namespace SupportAssistant.Evaluation.Tests;

public static class EvalSetup
{
    private static readonly IConfigurationRoot Config =
        new ConfigurationBuilder()
            .AddJsonFile("appsettings.tests.json", optional: false)
            .AddEnvironmentVariables()
            .Build();

    // L'assistente sotto test usa il modello SUT...
    public static IChatClient CreateSutClient() =>
        new OllamaApiClient(new Uri(Config["Ollama:Endpoint"]!), Config["Ollama:SutModel"]!);

    // ...gli evaluator LLM-as-judge usano il modello giudice: due voci
    // di config, cosi' il giudice puo' diventare piu' grande senza toccare codice.
    private static ChatConfiguration CreateJudgeConfiguration() =>
        new(new OllamaApiClient(new Uri(Config["Ollama:Endpoint"]!), Config["Ollama:JudgeModel"]!));

    // Un ExecutionName per run: nel report i risultati sono raggruppati per corsa.
    private static string ExecutionName { get; } = $"{DateTime.Now:yyyyMMddTHHmmss}";

    public static ReportingConfiguration Reporting { get; } =
        DiskBasedReportingConfiguration.Create(
            storageRootPath: FindReportsPath(),   // <repo>/TestReports
            evaluators:
            [
                new RelevanceEvaluator(),
                new CoherenceEvaluator(),
                new GroundednessEvaluator(),
                new AnswerLengthEvaluator()
            ],
            chatConfiguration: CreateJudgeConfiguration(),
            enableResponseCaching: true,
            executionName: ExecutionName);
}

using System.Text.RegularExpressions;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.AI.Evaluation;

namespace SupportAssistant.Evaluation.Tests;

// Metrica deterministica, zero LLM: conta le parole e boccia le risposte
// fuori budget. E' il gate duro ideale per la CI.
public class AnswerLengthEvaluator : IEvaluator
{
    public const string MetricName = "Answer Length";

    private const int MinWords = 3;
    private const int MaxWords = 100;

    public IReadOnlyCollection<string> EvaluationMetricNames => [MetricName];

    public ValueTask<EvaluationResult> EvaluateAsync(
        IEnumerable<ChatMessage> messages,
        ChatResponse modelResponse,
        ChatConfiguration? chatConfiguration = null,
        IEnumerable<EvaluationContext>? additionalContext = null,
        CancellationToken cancellationToken = default)
    {
        int words = Regex.Matches(modelResponse.Text ?? "", @"\b\w+\b").Count;

        NumericMetric metric = new(
            MetricName,
            value: words,
            reason: $"The response contains {words} words (budget: {MinWords}-{MaxWords}).");

        metric.Interpretation = words >= MinWords && words <= MaxWords
            ? new EvaluationMetricInterpretation(
                EvaluationRating.Good,
                reason: "The response respects the word budget.")
            : new EvaluationMetricInterpretation(
                EvaluationRating.Unacceptable,
                failed: true,
                reason: "The response is empty, too short or over the word budget.");

        return new ValueTask<EvaluationResult>(new EvaluationResult(metric));
    }
}

public record EvalCase(string Name, string Question, string Context)
{
    public override string ToString() => Name;
}

public class SupportAssistantEvalTests(ITestOutputHelper output)
{
    private static bool Strict =>
        Environment.GetEnvironmentVariable("EVAL_STRICT") == "1";

    public static TheoryData<EvalCase> Cases => new()
    {
        new EvalCase("PasswordReset", "How do I reset my password?", AccountFaq),
        new EvalCase("InvoiceDownload", "Dove scarico le fatture in PDF?", BillingFaq),
        new EvalCase("OutOfScope", "Can I pay my invoices with Bitcoin?", BillingFaq)
    };

    [Theory]
    [MemberData(nameof(Cases))]
    public async Task Answer_quality_is_evaluated_and_reported(EvalCase evalCase)
    {
        // await using: alla dispose i risultati vengono persistiti su disco.
        await using ScenarioRun scenario =
            await EvalSetup.Reporting.CreateScenarioRunAsync(
                $"SupportAssistant.{evalCase.Name}");

        SupportAssistantService assistant = new(EvalSetup.CreateSutClient());
        (IList<ChatMessage> messages, ChatResponse response) =
            await assistant.AskAsync(evalCase.Question, evalCase.Context);

        // Il contesto dell'assistente e' anche il grounding context del giudice.
        EvaluationResult result = await scenario.EvaluateAsync(
            messages,
            response,
            additionalContext: [new GroundednessEvaluatorContext(evalCase.Context)]);

        // Gate deterministico: sempre attivo.
        NumericMetric length = result.Get<NumericMetric>(AnswerLengthEvaluator.MetricName);
        Assert.False(length.Interpretation!.Failed, length.Interpretation.Reason);

        // Metriche del giudice: loggate sempre, bloccanti solo in strict mode.
        foreach (string name in new[]
        {
            RelevanceEvaluator.RelevanceMetricName,
            CoherenceEvaluator.CoherenceMetricName,
            GroundednessEvaluator.GroundednessMetricName
        })
        {
            // Un giudice piccolo puo' non produrre un punteggio parseabile:
            // TryGetValue, cosi' la metrica mancante e' un dato nel report,
            // non un'eccezione nella suite.
            if (!result.Metrics.TryGetValue(name, out EvaluationMetric? raw)
                || raw is not NumericMetric metric)
            {
                output.WriteLine($"  {name}: no score produced by the judge");
                continue;
            }

            output.WriteLine($"  {name}: {metric.Value} — {metric.Reason}");

            if (Strict)
                Assert.True(
                    metric.Interpretation?.Failed != true,
                    $"{name} failed: {metric.Interpretation?.Reason}");
        }
    }
}

$ git clone https://github.com/fscamuzzi/llm-eval-dotnet-ollama.git
$ cd llm-eval-dotnet-ollama

# dipendenze in Docker (Ollama + pull di llama3.1)
$ docker compose up -d
$ docker compose logs -f ollama-init   # attendi il pull

# la suite di valutazione
$ dotnet test

# il report HTML
$ dotnet tool restore
$ dotnet tool run aieval report --path TestReports --output report.html