【第22篇】Evaluation Example

一、概述

1.1 项目定位

Spring AI Alibaba Evaluation Example 是一套基于 Spring AI 框架的 LLM（大语言模型）应用效果量化评估工具链示例。它并非简单的"打分工具"，而是一个覆盖准确性验证、性能观测、成本核算三维度的工程化评估体系，旨在解决 LLM 应用落地时的核心痛点：模型输出质量不可量化、API 延迟波动难观测、Token 消耗成本不透明。

1.2 系统架构设计

该项目的核心思想是管道化评估（Pipeline Evaluation）：将评估任务拆解为可插拔的指标计算节点，通过报告卡生成器聚合多维度结果。
输出层
核心评估引擎
输入层
指标计算模块
评估数据集

Dataset
模型配置

ModelConfig
评分标准

ScoringCriteria
AbstractEvaluator

抽象评估器
DocumentEvaluator

文档评估器
LatencyMetric

延迟指标
QualityMetrics

质量指标
CostMetric

成本指标
ReportCardGenerator

报告卡生成器
评估报告

EvaluationReport
时序数据库

TimeSeriesDB

可选

架构设计要点：

层级	职责	设计原则
输入层	管理评估数据集、模型参数、评分阈值	配置外部化，支持多环境切换
核心引擎	抽象评估逻辑，支持扩展新的评估器	模板方法模式（AbstractEvaluator）
指标模块	原子化指标计算，无状态设计	每个指标独立计算，便于单元测试
输出层	聚合多维度结果，生成可读报告	支持多格式适配（JSON/Markdown/HTML）

二、评估指标体系原理详解

2.1 指标三维分类模型

LLM 评估不能只看"对不对"，必须建立质量-性能-成本的三维平衡视角：
LLM评估

指标体系
准确性维度
ExactMatch
SemanticSimilarity
F1 Score
BLEU/ROUGE
性能维度
P50Latency
P95Latency
P99Latency
Throughput
成本维度
TokenInputCost
TokenOutputCost
CacheHitRate
BatchDiscount
业务维度
UserSatisfaction
ActionableInsights
SafetyScore

2.2 各指标计算原理

2.2.1 准确性指标：从字面匹配到语义理解

核心问题：LLM 的输出具有"语义等价但表述不同"的特性，传统的字符串精确匹配（Exact Match）会严重低估模型质量。

计算方式演进：

级别	方法	原理	适用场景
L1	精确匹配	`actual.equals(expected)`	代码生成、结构化输出
L2	包含匹配	`actual.contains(keyphrase)`	关键词提取、事实核查
L3	向量相似度	`cosine(embedding(actual), embedding(expected))`	开放式问答、摘要生成
L4	LLM-as-Judge	用更强的模型评判输出质量	复杂推理、创意写作

向量相似度计算原理 ：
similarity=A⃗⋅B⃗∥A⃗∥×∥B⃗∥=∑i=1nAiBi∑i=1nAi2∑i=1nBi2 \text{similarity} = \frac{\vec{A} \cdot \vec{B}}{\|\vec{A}\| \times \|\vec{B}\|} = \frac{\sum_{i=1}^{n} A_i B_i}{\sqrt{\sum_{i=1}^{n} A_i^2} \sqrt{\sum_{i=1}^{n} B_i^2}} similarity=∥A ∥×∥B ∥A ⋅B =∑i=1nAi2 ∑i=1nBi2 ∑i=1nAiBi

其中 A⃗\vec{A}A 和 B⃗\vec{B}B 分别是实际输出和期望输出的文本嵌入向量。通常当相似度 > 0.85 时，可认为语义等价。

2.2.2 延迟指标：为什么必须看 P95/P99 而非平均值

原理阐述 ：LLM API 的延迟分布呈现明显的长尾特征。平均值会被大量正常请求"拉平"，掩盖少数用户的极差体验。

P50（中位数）：50% 的请求快于此值，反映典型体验
P95：95% 的请求快于此值，反映绝大多数用户体验边界
P99：99% 的请求快于此值，用于发现系统瓶颈和异常

数学定义 ：对于有序延迟数组 L=[l1,l2,...,ln]L = [l_1, l_2, ..., l_n]L=[l1,l2,...,ln]，P95 的位置为：
index=⌈n×0.95⌉−1 \text{index} = \lceil n \times 0.95 \rceil - 1 index=⌈n×0.95⌉−1
P95=L[index] \text{P95} = L[\text{index}] P95=L[index]

关键洞察：在 LLM 应用中，P99 延迟往往比平均值高 3-5 倍，这是因为模型推理存在冷启动、批处理排队、长文本生成等长尾因素。

2.2.3 成本指标：Token 经济学的多维度视角

成本计算不是简单的 token数 × 单价，需要考虑：

TotalCost=∑i=1n(inputi×pin+outputi×pout)−CacheSavings−BatchDiscount \text{TotalCost} = \sum_{i=1}^{n} \left( \text{input}i \times p{\text{in}} + \text{output}i \times p{\text{out}} \right) - \text{CacheSavings} - \text{BatchDiscount} TotalCost=i=1∑n(inputi×pin+outputi×pout)−CacheSavings−BatchDiscount

成本因子	说明	优化空间
Input Tokens	提示词 + 上下文	提示词工程、RAG 压缩
Output Tokens	模型生成内容	限制 max_tokens、输出格式约束
Cache Hit	重复查询命中缓存	建立 Embedding 缓存层
Batch Discount	批量调用折扣	请求合并、异步批处理

三、核心组件深度解析与代码修正

3.1 ReportCardGenerator：评估报告生成器

❌ 原文问题诊断

原文中的 OriginalReportCard 存在两个层面的问题：

逻辑错误 ：actual.toString().equals(expected.toString()) 比较的是对象引用字符串，而非业务内容
设计缺陷：二值化结果（TRUE/FALSE）无法反映"部分正确"的灰色地带

✅ 修正与优化方案

优化思路 ：引入分级评分机制（0-5分制），结合多策略回退（Multi-Strategy Fallback）：

java 复制代码

/**
 * 改进后的报告卡生成器
 * 采用策略模式支持多种评估方式，按成本从低到高回退
 */
@Component
public class ImprovedReportCardGenerator {
    
    @Autowired
    private TextEmbeddingService embeddingService;
    
    /**
     * 语义相似度计算 - 核心改进点
     * 
     * 策略优先级：
     * 1. 精确匹配（成本最低）
     * 2. 关键词包含匹配（低成本）
     * 3. 向量余弦相似度（中等成本）
     * 4. LLM 评判（高成本，保留给关键场景）
     */
    public EvaluationScore calculateSimilarity(Answer actual, Answer expected) {
        String actualText = normalizeText(actual.text());
        String expectedText = normalizeText(expected.text());
        
        // 策略1：精确匹配（完全等价）
        if (actualText.equals(expectedText)) {
            return EvaluationScore.of(1.0, MatchLevel.EXACT, "精确匹配");
        }
        
        // 策略2：包含匹配（期望内容被实际输出涵盖）
        if (actualText.contains(expectedText) || expectedText.contains(actualText)) {
            return EvaluationScore.of(0.9, MatchLevel.SUBSET, "包含匹配");
        }
        
        // 策略3：向量语义相似度（容忍表述差异）
        try {
            double similarity = calculateCosineSimilarity(actualText, expectedText);
            
            if (similarity > 0.90) {
                return EvaluationScore.of(similarity, MatchLevel.SEMANTIC_HIGH, "高度语义相似");
            } else if (similarity > 0.75) {
                return EvaluationScore.of(similarity, MatchLevel.SEMANTIC_MEDIUM, "中度语义相似");
            } else if (similarity > 0.60) {
                return EvaluationScore.of(similarity, MatchLevel.SEMANTIC_LOW, "低度语义相似");
            }
        } catch (Exception e) {
            // 降级处理：向量服务不可用时记录日志
            log.warn("Embedding service unavailable, falling back to lexical match", e);
        }
        
        // 策略4：词级重叠度（最终兜底）
        double lexicalOverlap = calculateLexicalOverlap(actualText, expectedText);
        return EvaluationScore.of(lexicalOverlap, MatchLevel.LEXICAL, "词级重叠");
    }
    
    /**
     * 归一化处理：统一大小写、去除多余空白、标准化标点
     * 这是文本比较的前置必要步骤，原文完全遗漏
     */
    private String normalizeText(String text) {
        if (text == null) return "";
        return text.toLowerCase()
                   .replaceAll("\\s+", " ")      // 多个空白合并
                   .replaceAll("[，。？！]", ",") // 中文标点统一
                   .trim();
    }
    
    /**
     * 计算余弦相似度
     * 注意：实际生产环境建议使用 Hnswlib 或 Milvus 等向量库加速
     */
    private double calculateCosineSimilarity(String text1, String text2) {
        List<Double> embedding1 = embeddingService.embed(text1);
        List<Double> embedding2 = embeddingService.embed(text2);
        
        double dotProduct = 0.0;
        double norm1 = 0.0;
        double norm2 = 0.0;
        
        for (int i = 0; i < embedding1.size(); i++) {
            double v1 = embedding1.get(i);
            double v2 = embedding2.get(i);
            dotProduct += v1 * v2;
            norm1 += v1 * v1;
            norm2 += v2 * v2;
        }
        
        return dotProduct / (Math.sqrt(norm1) * Math.sqrt(norm2));
    }
    
    /**
     * 词级重叠度计算（Jaccard 系数的变体）
     */
    private double calculateLexicalOverlap(String text1, String text2) {
        Set<String> set1 = new HashSet<>(Arrays.asList(text1.split("\\s+")));
        Set<String> set2 = new HashSet<>(Arrays.asList(text2.split("\\s+")));
        
        Set<String> intersection = new HashSet<>(set1);
        intersection.retainAll(set2);
        
        Set<String> union = new HashSet<>(set1);
        union.addAll(set2);
        
        return union.isEmpty() ? 0.0 : (double) intersection.size() / union.size();
    }
}

/**
 * 评分结果值对象 - 替代原文简单的 TRUE/FALSE
 */
public record EvaluationScore(
    double score,           // 0.0 ~ 1.0 连续分值
    MatchLevel level,       // 匹配级别枚举
    String reason           // 评分理由，可解释性
) {
    public static EvaluationScore of(double score, MatchLevel level, String reason) {
        // 边界保护
        double normalizedScore = Math.max(0.0, Math.min(1.0, score));
        return new EvaluationScore(normalizedScore, level, reason);
    }
    
    public boolean isPassing(double threshold) {
        return this.score >= threshold;
    }
}

public enum MatchLevel {
    EXACT,          // 1.0
    SUBSET,         // 0.9
    SEMANTIC_HIGH,  // >0.90
    SEMANTIC_MEDIUM,// >0.75
    SEMANTIC_LOW,   // >0.60
    LEXICAL,        // 词级
    NONE            // 0.0
}

设计改进要点：

改进点	原文问题	优化方案	收益
评分粒度	二值化 TRUE/FALSE	0.0~1.0 连续分值 + 分级枚举	支持"部分正确"的精细评估
比较策略	单一字符串匹配	四级策略回退（精确→包含→向量→词级）	成本与精度平衡，服务降级能力
文本预处理	无归一化	统一大小写、空白、标点	消除格式差异导致的误判
可解释性	无原因输出	每个分数附带 reason 字段	便于人工复核和调试

3.2 LatencyMetric：延迟统计机制

❌ 原文严重问题诊断

原文的延迟统计代码存在多处致命错误：

错误1：数据结构误用

java 复制代码

// ❌ 致命错误：ConcurrentLinkedQueue 没有带初始容量的构造函数
private Queue<Long> queue = new ConcurrentLinkedQueue<>(100_000);

ConcurrentLinkedQueue 是无界队列，不支持指定容量。此代码无法编译。

错误2：P95 计算逻辑完全错误

java 复制代码

// ❌ 逻辑错误：sorted 是 Stream，不能调用 get() 或 lastElement()
var sorted = latencies.stream().sorted();
return ((double) (sorted.size() * 0.05)) < sorted.size() ? 
    sorted.get((int) (sorted.size() * 0.05)) : 
    sorted.lastElement();

问题：

Stream 接口没有 get() 和 lastElement() 方法
百分位计算逻辑混乱，P95 应该是 size * 0.95 而非 0.05
未处理空集合的边界情况

错误3：滑动窗口设计缺陷

原文使用 FIFO 移除旧数据，这会导致：

丢失时间序列信息，无法做趋势分析
无法区分"瞬时高峰"和"持续恶化"
多线程环境下 ArrayList 的 remove(0) 性能极差（O(n) 移位）

✅ 修正与优化方案

优化思路 ：引入时间窗口 + 指数加权移动平均（EWMA）+ 精确百分位的三层统计模型。

java 复制代码

/**
 * 高精度延迟跟踪器
 * 
 * 设计决策：
 * 1. 使用环形缓冲区（Ring Buffer）替代 FIFO 移除，O(1) 性能
 * 2. 维护两个视图：原始数据窗口（用于精确百分位）+ EWMA（用于实时趋势）
 * 3. 线程安全：使用 LongAdder 累积，避免 AtomicLong 竞争
 */
@Component
public class AdvancedLatencyMetric {
    
    private static final int DEFAULT_WINDOW_SIZE = 100_000;
    private static final double EWMA_ALPHA = 0.015; // 约等于 1 分钟半衰期（假设每秒采样）
    
    // 环形缓冲区：存储原始延迟数据用于精确百分位计算
    private final AtomicReferenceArray<Long> latencyRingBuffer;
    private final AtomicLong sequence = new AtomicLong(0);
    
    // 实时统计量（无锁累积）
    private final LongAdder totalLatency = new LongAdder();
    private final LongAdder count = new LongAdder();
    
    // EWMA 用于实时监控面板
    private final DoubleAdder ewmaLatency = new DoubleAdder();
    private volatile double lastEwma = 0.0;
    
    public AdvancedLatencyMetric() {
        this(DEFAULT_WINDOW_SIZE);
    }
    
    public AdvancedLatencyMetric(int windowSize) {
        this.latencyRingBuffer = new AtomicReferenceArray<>(windowSize);
    }
    
    /**
     * 记录延迟样本
     * 线程安全，支持高并发写入
     */
    public void record(long latencyMs) {
        if (latencyMs < 0) {
            throw new IllegalArgumentException("Latency cannot be negative");
        }
        
        // 1. 写入环形缓冲区（覆盖最旧数据）
        long seq = sequence.getAndIncrement();
        int index = (int) (seq % latencyRingBuffer.length());
        latencyRingBuffer.set(index, latencyMs);
        
        // 2. 累积总量（用于平均值）
        totalLatency.add(latencyMs);
        count.increment();
        
        // 3. 更新 EWMA（指数加权移动平均）
        updateEwma(latencyMs);
    }
    
    /**
     * EWMA 更新公式：S_t = α × X_t + (1-α) × S_{t-1}
     * 特点：对新数据更敏感，能更快反映近期趋势变化
     */
    private void updateEwma(long latencyMs) {
        double currentEwma = lastEwma;
        double newEwma = EWMA_ALPHA * latencyMs + (1 - EWMA_ALPHA) * currentEwma;
        lastEwma = newEwma;
        ewmaLatency.reset();
        ewmaLatency.add(newEwma);
    }
    
    /**
     * 计算精确百分位（P50/P95/P99）
     * 
     * 算法：Neareast Rank Method（最邻近秩法）
     * 公式：index = ceil(P/100 × N) - 1
     * 
     * 注意：此方法会复制窗口数据并排序，适合报告生成时调用，
     * 不适合高频实时查询。实时监控应使用 getEwma()。
     */
    public PercentileResult calculatePercentiles() {
        // 收集有效数据（排除未写入的槽位）
        long currentCount = Math.min(sequence.get(), latencyRingBuffer.length());
        if (currentCount == 0) {
            return PercentileResult.empty();
        }
        
        long[] samples = new long[(int) currentCount];
        for (int i = 0; i < currentCount; i++) {
            Long value = latencyRingBuffer.get(i);
            samples[i] = value != null ? value : 0L;
        }
        
        // 使用 Dual-Pivot Quicksort，平均 O(n log n)
        Arrays.sort(samples);
        
        return new PercentileResult(
            calculatePercentile(samples, 50),
            calculatePercentile(samples, 95),
            calculatePercentile(samples, 99),
            calculateAverage(),
            currentCount
        );
    }
    
    /**
     * 精确百分位计算
     * 
     * @param sorted 已排序数组
     * @param percentile 百分位值（50/95/99）
     */
    private long calculatePercentile(long[] sorted, int percentile) {
        if (sorted.length == 0) return 0L;
        
        // 最邻近秩法（Nearest Rank Method）
        double rank = (percentile / 100.0) * sorted.length;
        int index = (int) Math.ceil(rank) - 1;
        
        // 边界保护
        index = Math.max(0, Math.min(index, sorted.length - 1));
        return sorted[index];
    }
    
    /**
     * 平均值计算
     */
    public double calculateAverage() {
        long currentCount = count.sum();
        return currentCount == 0 ? 0.0 : (double) totalLatency.sum() / currentCount;
    }
    
    /**
     * 获取 EWMA 值（适合实时监控）
     */
    public double getEwma() {
        return ewmaLatency.sum();
    }
    
    /**
     * 获取当前窗口内的样本数量
     */
    public long getSampleCount() {
        return Math.min(sequence.get(), latencyRingBuffer.length());
    }
}

/**
 * 百分位结果值对象
 */
public record PercentileResult(
    long p50,
    long p95,
    long p99,
    double average,
    long sampleCount
) {
    public static PercentileResult empty() {
        return new PercentileResult(0L, 0L, 0L, 0.0, 0L);
    }
    
    @Override
    public String toString() {
        return String.format(
            "LatencyStats{samples=%d, avg=%.2fms, p50=%dms, p95=%dms, p99=%dms}",
            sampleCount, average, p50, p95, p99
        );
    }
}

关键改进对比：

维度	原文实现	优化实现	原理说明
数据结构	`ArrayList` + `remove(0)`	`AtomicReferenceArray` 环形缓冲区	O(1) 写入，无内存分配，线程安全
百分位算法	错误的 Stream 操作	最邻近秩法 + 数组排序	数学上准确的百分位定义
实时趋势	无	EWMA 指数加权移动平均	比简单移动平均更快反映变化，适合告警
并发性能	非线程安全	`LongAdder` + `AtomicReferenceArray`	高并发下减少伪共享（False Sharing）
边界处理	无	空集合保护、负值校验	生产级鲁棒性

EWMA 原理补充：

指数加权移动平均（Exponentially Weighted Moving Average）的核心思想是给近期数据更高的权重：

St=α⋅Xt+(1−α)⋅St−1 S_t = \alpha \cdot X_t + (1-\alpha) \cdot S_{t-1} St=α⋅Xt+(1−α)⋅St−1

其中 α∈(0,1)\alpha \in (0,1)α∈(0,1) 是平滑因子。α\alphaα 越大，对最新数据越敏感。在延迟监控中，EWMA 比简单移动平均（SMA）更适合，因为它不需要维护一个固定大小的窗口，且能更快捕捉到延迟的突变趋势（如模型服务冷启动导致的延迟飙升）。

3.3 CostMetric：成本计算机制

❌ 原文问题诊断

原文的成本计算存在以下问题：

模型价格硬编码 ：PRICE_PER_TOKEN 为常量，无法适应不同模型（qwen-max vs qwen-turbo 价差可达 10 倍）
忽略输出 Token：只计算 input，未计算 output（通常 output 更贵）
缺少批量折扣和缓存逻辑 ：伪代码 BatchCost::calculate 过于抽象，无实际实现参考
无成本归因：无法回答"哪个环节最花钱"

✅ 修正与优化方案

优化思路 ：建立多维成本分析模型（Multi-Dimensional Cost Analysis），将总成本拆解为可直接归因的细项。

java 复制代码

/**
 * 多维度成本分析器
 * 
 * 核心概念：
 * 1. CostLedger（成本台账）：记录每次调用的明细
 * 2. CostDimension（成本维度）：支持按模型、按场景、按时间切片分析
 * 3. SavingsEngine（节省引擎）：量化缓存和批量带来的收益
 */
@Component
public class AdvancedCostMetric {
    
    /**
     * 模型价格表（实际应从配置中心或数据库加载，支持动态更新）
     * 单位：元 / 千 Token
     */
    private final Map<String, ModelPricing> pricingTable = Map.of(
        "qwen-max",       new ModelPricing(0.02, 0.06),   // 输入/输出
        "qwen-plus",      new ModelPricing(0.008, 0.02),
        "qwen-turbo",     new ModelPricing(0.002, 0.006),
        "qwen-long",      new ModelPricing(0.0005, 0.002)
    );
    
    // 成本台账：记录每一次调用的明细
    private final List<CostLedger> ledgers = new CopyOnWriteArrayList<>();
    
    /**
     * 单次调用成本计算（基础版）
     */
    public CostLedger recordSingleCall(String modelName, TokenUsage usage) {
        ModelPricing pricing = pricingTable.getOrDefault(modelName, ModelPricing.DEFAULT);
        
        BigDecimal inputCost = BigDecimal.valueOf(usage.inputTokens())
            .multiply(pricing.inputPricePer1K())
            .divide(BigDecimal.valueOf(1000), 6, RoundingMode.HALF_UP);
            
        BigDecimal outputCost = BigDecimal.valueOf(usage.outputTokens())
            .multiply(pricing.outputPricePer1K())
            .divide(BigDecimal.valueOf(1000), 6, RoundingMode.HALF_UP);
        
        CostLedger ledger = new CostLedger(
            UUID.randomUUID().toString(),
            modelName,
            usage.inputTokens(),
            usage.outputTokens(),
            inputCost,
            outputCost,
            CostType.SINGLE_CALL,
            Instant.now()
        );
        
        ledgers.add(ledger);
        return ledger;
    }
    
    /**
     * 批量调用成本分摊计算
     * 
     * 原理：某些平台对批量 API 提供折扣（如 10% off）。
     * 此处的"批量"指逻辑上的请求合并，而非简单的 List 传入。
     */
    public List<CostLedger> recordBatchCall(String modelName, List<TokenUsage> usages, double discountRate) {
        ModelPricing pricing = pricingTable.getOrDefault(modelName, ModelPricing.DEFAULT);
        List<CostLedger> batchLedgers = new ArrayList<>();
        
        // 先计算原始总成本
        BigDecimal totalRawCost = usages.stream()
            .map(u -> calculateRawCost(u, pricing))
            .reduce(BigDecimal.ZERO, BigDecimal::add);
        
        // 应用批量折扣（如 9 折）
        BigDecimal discountFactor = BigDecimal.valueOf(1 - discountRate);
        BigDecimal totalDiscountedCost = totalRawCost.multiply(discountFactor);
        
        // 按各请求 Token 比例分摊折扣后的成本（公平分摊原则）
        BigDecimal cumulativeCost = BigDecimal.ZERO;
        for (int i = 0; i < usages.size(); i++) {
            TokenUsage usage = usages.get(i);
            BigDecimal rawCost = calculateRawCost(usage, pricing);
            
            // 按比例计算该请求的分摊成本
            BigDecimal share = rawCost.divide(totalRawCost, 10, RoundingMode.HALF_UP)
                .multiply(totalDiscountedCost);
            
            // 最后一个请求承担剩余部分（避免精度丢失）
            if (i == usages.size() - 1) {
                share = totalDiscountedCost.subtract(cumulativeCost);
            } else {
                cumulativeCost = cumulativeCost.add(share);
            }
            
            CostLedger ledger = new CostLedger(
                UUID.randomUUID().toString(),
                modelName,
                usage.inputTokens(),
                usage.outputTokens(),
                share.multiply(usage.inputTokens()).divide(usage.totalTokens(), 6, RoundingMode.HALF_UP),
                share.multiply(usage.outputTokens()).divide(usage.totalTokens(), 6, RoundingMode.HALF_UP),
                CostType.BATCH_CALL,
                Instant.now()
            );
            
            batchLedgers.add(ledger);
            ledgers.add(ledger);
        }
        
        return batchLedgers;
    }
    
    /**
     * 缓存节省计算
     * 
     * 原理：如果请求命中了 Embedding 缓存或 Prompt 缓存，
     * 实际消耗的 Token 可能为 0 或享受缓存价格（通常更便宜）。
     */
    public CostSavings calculateCacheSavings(String modelName, TokenUsage originalUsage, 
                                             TokenUsage cachedUsage, CacheTier tier) {
        ModelPricing pricing = pricingTable.getOrDefault(modelName, ModelPricing.DEFAULT);
        
        // 原始成本
        BigDecimal originalCost = calculateRawCost(originalUsage, pricing);
        
        // 缓存后成本（通常输入 Token 按缓存价计算，输出不变）
        BigDecimal cachedInputCost = BigDecimal.valueOf(cachedUsage.inputTokens())
            .multiply(tier.getDiscountedPrice(pricing.inputPricePer1K()))
            .divide(BigDecimal.valueOf(1000), 6, RoundingMode.HALF_UP);
        BigDecimal cachedOutputCost = BigDecimal.valueOf(cachedUsage.outputTokens())
            .multiply(pricing.outputPricePer1K())
            .divide(BigDecimal.valueOf(1000), 6, RoundingMode.HALF_UP);
        
        BigDecimal cachedCost = cachedInputCost.add(cachedOutputCost);
        BigDecimal savings = originalCost.subtract(cachedCost).max(BigDecimal.ZERO);
        
        return new CostSavings(
            originalCost,
            cachedCost,
            savings,
            tier,
            savings.divide(originalCost, 4, RoundingMode.HALF_UP).multiply(BigDecimal.valueOf(100)) // 节省百分比
        );
    }
    
    /**
     * 生成多维度成本报告
     */
    public CostReport generateReport() {
        // 按模型聚合
        Map<String, ModelCostSummary> byModel = ledgers.stream()
            .collect(Collectors.groupingBy(
                CostLedger::modelName,
                Collectors.collectingAndThen(Collectors.toList(), this::summarize)
            ));
        
        // 总成本
        BigDecimal totalCost = ledgers.stream()
            .map(CostLedger::totalCost)
            .reduce(BigDecimal.ZERO, BigDecimal::add);
        
        // 时间趋势（按小时）
        Map<String, BigDecimal> hourlyTrend = ledgers.stream()
            .collect(Collectors.groupingBy(
                l -> l.timestamp().truncatedTo(ChronoUnit.HOURS).toString(),
                Collectors.mapping(CostLedger::totalCost, Collectors.reducing(BigDecimal.ZERO, BigDecimal::add))
            ));
        
        return new CostReport(totalCost, byModel, hourlyTrend, ledgers.size());
    }
    
    private BigDecimal calculateRawCost(TokenUsage usage, ModelPricing pricing) {
        BigDecimal input = BigDecimal.valueOf(usage.inputTokens())
            .multiply(pricing.inputPricePer1K()).divide(BigDecimal.valueOf(1000), 6, RoundingMode.HALF_UP);
        BigDecimal output = BigDecimal.valueOf(usage.outputTokens())
            .multiply(pricing.outputPricePer1K()).divide(BigDecimal.valueOf(1000), 6, RoundingMode.HALF_UP);
        return input.add(output);
    }
    
    private ModelCostSummary summarize(List<CostLedger> ledgers) {
        long totalInput = ledgers.stream().mapToLong(CostLedger::inputTokens).sum();
        long totalOutput = ledgers.stream().mapToLong(CostLedger::outputTokens).sum();
        BigDecimal totalCost = ledgers.stream().map(CostLedger::totalCost).reduce(BigDecimal.ZERO, BigDecimal::add);
        return new ModelCostSummary(ledgers.get(0).modelName(), totalInput, totalOutput, totalCost, ledgers.size());
    }
}

/**
 * 模型定价配置
 */
public record ModelPricing(BigDecimal inputPricePer1K, BigDecimal outputPricePer1K) {
    public static final ModelPricing DEFAULT = new ModelPricing(BigDecimal.valueOf(0.01), BigDecimal.valueOf(0.03));
}

/**
 * 成本台账记录
 */
public record CostLedger(
    String ledgerId,
    String modelName,
    long inputTokens,
    long outputTokens,
    BigDecimal inputCost,
    BigDecimal outputCost,
    CostType costType,
    Instant timestamp
) {
    public BigDecimal totalCost() {
        return inputCost.add(outputCost);
    }
}

/**
 * 缓存层级及折扣
 */
public enum CacheTier {
    NO_CACHE(BigDecimal.ONE),
    MEMORY_CACHE(new BigDecimal("0.5")),   // 50% 价格
    DISK_CACHE(new BigDecimal("0.3")),     // 30% 价格
    CDN_CACHE(new BigDecimal("0.1"));      // 10% 价格（仅输入）
    
    private final BigDecimal priceMultiplier;
    
    CacheTier(BigDecimal multiplier) {
        this.priceMultiplier = multiplier;
    }
    
    public BigDecimal getDiscountedPrice(BigDecimal originalPrice) {
        return originalPrice.multiply(priceMultiplier);
    }
}

public record CostSavings(
    BigDecimal originalCost,
    BigDecimal actualCost,
    BigDecimal savingsAmount,
    CacheTier tier,
    BigDecimal savingsPercentage
) {}

public record CostReport(
    BigDecimal totalCost,
    Map<String, ModelCostSummary> byModel,
    Map<String, BigDecimal> hourlyTrend,
    int totalCalls
) {}

public record ModelCostSummary(
    String modelName,
    long totalInputTokens,
    long totalOutputTokens,
    BigDecimal totalCost,
    int callCount
) {}

public enum CostType {
    SINGLE_CALL,
    BATCH_CALL,
    RETRY_CALL,
    CACHE_HIT
}

成本分析维度可视化：
优化方向
成本归因
总成本分解
总成本
模型调用成本
缓存节省
批量折扣
重试浪费
按模型

qwen-max/turbo
按场景

RAG/Agent/Chat
按时间

小时/天/周
Prompt缓存
请求合并
超时控制

熔断降级

四、部署与运维指南修正

4.1 原文部署命令修正

原文部分命令存在不准确或安全隐患，修正如下：

步骤	原文	问题	修正
API Key 验证	`curl -X GET "https://dashscope.aliyuncs.com/authorization?api_key=xxx"`	URL 不存在，且 GET 请求带 API Key 会留痕在日志	使用实际对话接口测试，或通过 SDK 验证
JVM 参数	`java -jar target/*.jar -Xmx1024m`	`-Xmx` 放在 jar 之后会被当作 main 参数而非 JVM 参数	`java -Xmx1024m -jar target/*.jar`
Maven 内存	`export MAVEN_OPTS="-Xmx1024m"`	构建大项目可能不足	`export MAVEN_OPTS="-Xmx2g -Xms1g"`
日志查看	`tail -f target/*.log`	Spring Boot 默认输出到控制台，文件日志需配置	配置 `logging.file.name` 或使用 `journalctl`

4.2 生产级部署配置

yaml 复制代码

# application-prod.yml 生产环境配置
spring:
  ai:
    alibaba:
      api-key: ${ALIBABA_CLOUD_API_KEY:}  # 强制外部注入，禁止硬编码
      chat:
        options:
          model: qwen-max
          temperature: 0.7
          max-tokens: 2000
    evaluation:
      enabled: true
      concurrency: 5          # 评估并发度，防止打满模型限流
      timeout-seconds: 30     # 单条评估超时
      retry:
        max-attempts: 3
        backoff-delay-ms: 1000
      
  # 监控端点安全配置
  management:
    endpoints:
      web:
        exposure:
          include: health,metrics,prometheus
    endpoint:
      health:
        show-details: when_authorized

# 评估报告输出
evaluation:
  output:
    path: /var/evaluation/reports
    format: json              # 支持 json / markdown / html
    retention-days: 90        # 报告保留策略

# 日志配置
logging:
  file:
    name: /var/log/evaluation/app.log
  pattern:
    file: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n"
  logback:
    rollingpolicy:
      max-file-size: 100MB
      max-history: 30

4.3 容器化部署（补充原文缺失）

原文缺少容器化方案，现代 LLM 应用建议直接采用容器部署：

dockerfile 复制代码

# Dockerfile
FROM eclipse-temurin:17-jre-alpine

WORKDIR /app

# 安全：使用非 root 用户运行
RUN addgroup -S evaluation && adduser -S evaluation -G evaluation
USER evaluation

# 复制构建产物
COPY target/evaluation-demo.jar app.jar

# JVM 调优参数
ENV JAVA_OPTS="-XX:+UseG1GC \
               -XX:MaxRAMPercentage=75.0 \
               -XX:InitialRAMPercentage=50.0 \
               -Djava.security.egd=file:/dev/./urandom"

EXPOSE 8080

ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]

yaml 复制代码

# docker-compose.yml
version: '3.8'
services:
  evaluation:
    build: .
    ports:
      - "8080:8080"
    environment:
      - ALIBABA_CLOUD_API_KEY=${ALIBABA_CLOUD_API_KEY}
      - SPRING_PROFILES_ACTIVE=prod
    volumes:
      - ./reports:/var/evaluation/reports
      - ./logs:/var/log/evaluation
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 1G
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/actuator/health"]
      interval: 30s
      timeout: 10s
      retries: 3

五、完整评估流程设计

将上述组件串联，形成完整的评估流水线：
EmbeddingService LLM_API ReportCardGenerator CostMetric QualityMetrics LatencyMetric DocumentEvaluator 用户/CI系统 EmbeddingService LLM_API ReportCardGenerator CostMetric QualityMetrics LatencyMetric DocumentEvaluator 用户/CI系统性能观测阶段质量评估阶段 alt [未命中] 成本核算阶段 alt [命中缓存] 提交评估任务 (input, expectedOutput, modelConfig) startTimer() 发送请求返回结果 stopTimer() record(latencyMs) calculateSimilarity (actual, expected) 策略1: 精确匹配? 策略2: 向量相似度 embed(text) embedding[] cosineSimilarity() EvaluationScore recordUsage(model, tokenUsage) 查询价格表计算 input/output 成本 applyCacheDiscount() CostLedger submit(qualityScore, latencyStats, costLedger) 聚合多维度指标计算综合得分 weightedScore = α·quality + β·perf + γ·costEfficiency EvaluationReport (JSON/Markdown/HTML)

六、错误诊断与修订清单（完整版）

序号	问题位置	问题描述	影响等级	修复方案	验证方式
1	`ReportCardGenerator`	字符串精确匹配，忽略语义等价	🔴 高	引入四级策略回退（精确→包含→向量→词级）	同义句测试集通过率 > 85%
2	`LatencyMetric`	`ConcurrentLinkedQueue<>(100_000)` 编译错误	🔴 高	改用 `AtomicReferenceArray` 环形缓冲区	代码编译通过 + 单元测试
3	`LatencyMetric`	P95 计算逻辑错误（Stream 无 get 方法，公式错误）	🔴 高	最邻近秩法 + 数组排序	已知数据集百分位验证
4	`LatencyMetric`	`ArrayList.remove(0)` 性能 O(n)，非线程安全	🟡 中	环形缓冲区覆盖 + `LongAdder` 累积	JMH 基准测试，并发写入 10w/s
5	`CostMetric`	仅计算 input Token，忽略 output	🟡 中	分别计算 input/output，区分模型价格	与阿里云账单核对误差 < 1%
6	`CostMetric`	价格硬编码，无批量折扣/缓存逻辑	🟡 中	价格表外部化 + 批量分摊算法 + 缓存节省计算	多模型切换测试
7	部署文档	JVM 参数位置错误（`-Xmx` 在 jar 后）	🟢 低	修正为 `java -Xmx... -jar ...`	命令行执行验证
8	部署文档	API Key 验证 URL 不存在	🟢 低	改为 SDK 初始化验证或实际调用测试	网络连通性测试
9	全局	缺少置信度（Confidence）维度	🟢 低	在 `EvaluationScore` 中增加 uncertainty 字段	人工抽检一致性
10	全局	无容器化/健康检查配置	🟢 低	补充 Dockerfile + docker-compose + actuator 配置	容器启动测试

七、设计原则与最佳实践总结

7.1 核心设计理念

原则	说明	实践示例
语义优先于语法	LLM 输出评估应关注含义而非字面	向量相似度替代 `String.equals()`
尾延迟优于平均	用户体验由最慢的请求决定	监控 P95/P99，设置 SLO（如 P99 < 2s）
成本归因透明	每个 Token 的花费应可追溯	按模型/场景/时间多维拆解
可解释性嵌入	每个分数都应附带理由	`EvaluationScore.reason()` 字段
防御性设计	依赖服务降级时不影响核心流程	Embedding 失败时回退到词级匹配

7.2 LLM 评估防坑指南

不要迷信 Exact Match：在开放式问答中，Exact Match 通过率通常 < 30%，而人工判断准确率可能 > 90%。向量相似度是更合理的基线。
延迟监控要分层：
- 网络层：DNS 解析、TLS 握手、TCP 连接
- 应用层：JSON 序列化、请求排队
- 模型层：首 Token 延迟（Time To First Token, TTFT）、生成延迟
- 建议分别记录 ttftMs 和 totalMs
成本优化三板斧：
- 提示词压缩：使用摘要技术减少 input Token
- 模型路由：简单任务用 qwen-turbo，复杂任务用 qwen-max
- 缓存策略：对重复查询的 Embedding 结果建立本地缓存
评估本身也需要评估：定期用人工标注的"黄金数据集"校准自动评估指标，防止指标漂移。

八、总结

本文对 Spring AI Alibaba Evaluation Example 进行了系统性的工程化重构：

架构层面：明确了输入层-核心引擎-指标模块-输出层的职责边界，补充了架构图和时序图
代码层面 ：纠正了 ConcurrentLinkedQueue 误用、P95 计算错误等致命缺陷，提供了生产级实现
算法层面：引入了语义相似度分级、EWMA 趋势监控、多维成本归因等高级特性
运维层面：修正了部署命令错误，补充了容器化、健康检查、日志轮转等生产必需配置

最终形成的评估体系具备高并发处理能力 （环形缓冲区 + 无锁累积）、精确统计能力 （正确百分位算法）和成本透明能力（多维度归因），可直接用于生产环境的 LLM 应用效果量化评估。