# ai-model-evaluation

**Repository Path**: itmfc1/ai-model-evaluation

## Basic Information

- **Project Name**: ai-model-evaluation
- **Description**: AI模型评估模块
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-02
- **Last Updated**: 2026-05-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Model Evaluation Module

AI模型评估系统，支持**阿里云百炼平台**186+模型（qwen-plus、qwen3-6-plus、deepseek-r1等），通过**评估用例表**实现模型+指标+用例的**组合评估**。在math-500、MBPP、HumanEval等数据集上逐题评估，输出0-10分数据质量评分卡。

## 技术栈

- **框架**: Spring Boot 2.6.13
- **JDK**: Java 8
- **数据库**: MySQL 5.7
- **ORM**: MyBatis-Plus 3.5.3.1
- **连接池**: Druid 1.2.18
- **HTTP客户端**: OkHttp 4.11.0
- **JSON处理**: Fastjson2 2.0.42
- **缓存**: Caffeine

## 核心设计

### 评估用例表 (eval_case)

每道题是一条独立记录，支持多维度分类：

| 字段 | 说明 | 示例 |
|------|------|------|
| case_type | 用例类型 | math / code / qa / reasoning |
| category | 子分类 | algebra / geometry / list-processing |
| difficulty | 难度 | easy / medium / hard / expert |
| content | 题目内容 | "Solve: 2x + 5 = 13" |
| expected_answer | 标准答案 | "4" |
| expected_code | 参考代码 | def solve(): return 4 |
| test_cases | 测试用例 | [{"input":"[1,2]","expectedOutput":"3"}] |
| dataset_source | 数据来源 | math-500 / mbpp / humaneval |
| model_type | 适用模型类型 | chat / coder / ALL |

### 组合评估

评估任务支持**三维度自由组合**：

```
评估任务 = 模型(可选) × 指标(可选) × 用例(可选)
```

| 组合方式 | 说明 |
|----------|------|
| 指定模型+指定用例 | 评估qwen-plus在math-500上的表现 |
| 指定模型+指定类型 | 评估deepseek-r1在所有code题上的表现 |
| 指定用例+全部模型 | 对比186个模型在同一道题上的表现 |
| 不指定 | 使用默认模型+全部适用用例+全部指标 |

## 百炼平台对接 (阿里云DashScope)

### 支持的模型 (186+个)

| 模型名 | model_code | 类型 | 说明 |
|--------|-----------|------|------|
| qwen-plus | qwen-plus | chat | 通义千问Plus |
| qwen-max | qwen-max | chat | 通义千问Max |
| qwen3-6-plus | qwen3-6-plus | chat | Qwen3.6 Plus |
| qwen-coder-plus | qwen-coder-plus | coder | 代码生成 |
| qwen-math-plus | qwen-math-plus | chat | 数学推理 |
| qwq-32b-preview | qwq-32b-preview | chat | 推理模型 |
| deepseek-r1 | deepseek-r1 | chat | DeepSeek推理 |
| deepseek-v3 | deepseek-v3 | chat | DeepSeek通用 |
| llama3.1-70b | llama3.1-70b-instruct | chat | Llama 3.1 |
| gpt-4o | gpt-4o | chat | GPT-4o |
| bge-m3 | bge-m3 | embedding | 向量嵌入 |
| text-embedding-v3 | text-embedding-v3 | embedding | 文本向量 |
| gte-rerank | gte-rerank | reranker | 重排序 |

### API调用格式

```java
// 百炼平台OpenAI兼容格式
POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "model": "qwen-plus",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Solve: 2^3 + 3^2"}
  ],
  "max_tokens": 2048,
  "temperature": 0
}
```

## 快速开始

### 1. 初始化数据库

```bash
mysql -u root -p < db/init.sql
```

创建：
- 数据库: `ai_model_evaluation`
- 表: `model_info` (15个百炼模型), `eval_case` (30个评估用例), `eval_metric` (23个指标)
- 表: `eval_task`, `eval_case_result` (逐题结果), `eval_result` (指标聚合结果)

### 2. 配置百炼API Key

```sql
-- 在数据库中配置你的百炼API Key (建议AES加密存储)
UPDATE model_info 
SET api_key = 'sk-your-bailian-api-key' 
WHERE provider = 'Alibaba Cloud';
```

或在 `application-dev.yml` 中配置默认Key。

### 3. 编译运行

```bash
mvn clean package -DskipTests
java -jar target/ai-model-evaluation-1.0.0.jar
```

服务启动在 `http://localhost:8080/api`

## API接口

### 评估用例管理

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/cases` | 列出所有用例 |
| GET | `/api/cases/type/{type}` | 按类型筛选 (math/code) |
| GET | `/api/cases/category/{category}` | 按分类筛选 (algebra/list-processing) |
| GET | `/api/cases/difficulty/{difficulty}` | 按难度筛选 (easy/medium/hard) |
| GET | `/api/cases/source/{source}` | 按数据来源筛选 (math-500/mbpp) |
| POST | `/api/cases` | 添加新用例 |
| PUT | `/api/cases/{id}` | 更新用例 |
| DELETE | `/api/cases/{id}` | 删除用例 |

### 评估任务

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/tasks/execute` | **创建并执行组合评估** |
| GET | `/api/tasks/{id}` | 查看任务状态 |
| GET | `/api/tasks/{id}/case-results` | 查看**逐题评估结果** |
| GET | `/api/tasks/{id}/scorecard` | 查看评分卡(0-10分) |
| POST | `/api/tasks/{id}/rerun` | 重新执行评估 |

### 创建组合评估任务

```bash
# 1. 评估 qwen-plus 在 math-500 上的表现
curl -X POST http://localhost:8080/api/tasks/execute \
  -H "Content-Type: application/json" \
  -d '{
    "taskName": "qwen-plus math-500评估",
    "modelId": 1,
    "caseType": "math",
    "metricIds": [1, 2]
  }'

# 2. 评估 qwen-coder-plus 在 MBPP 上的表现
curl -X POST http://localhost:8080/api/tasks/execute \
  -H "Content-Type: application/json" \
  -d '{
    "taskName": "coder MBPP评估",
    "modelId": 5,
    "caseIds": [11, 12, 13, 14, 15],
    "metricIds": [10, 11]
  }'

# 3. 对比多个模型在同一道题上的表现
curl -X POST http://localhost:8080/api/tasks/execute \
  -H "Content-Type: application/json" \
  -d '{
    "taskName": "多模型对比-数学题001",
    "caseIds": [1]
  }'

# 4. 查看逐题结果
curl http://localhost:8080/api/tasks/1/case-results

# 5. 查看评分卡
curl http://localhost:8080/api/tasks/1/scorecard
```

### 评分卡响应示例

```json
{
  "code": 200,
  "data": {
    "taskId": 1,
    "taskName": "qwen-plus math-500评估",
    "modelName": "qwen-plus",
    "modelType": "chat",
    "overallScore": 8.50,
    "grade": "good",
    "gradeDesc": "Model performance is good",
    "dimensionScores": [
      {
        "dimension": "accuracy",
        "dimensionDesc": "Accuracy",
        "weight": 0.30,
        "score": 8.50,
        "weightedScore": 2.55,
        "targetValue": ">=8.5",
        "status": "pass"
      }
    ],
    "caseResults": [
      {
        "caseId": 1,
        "caseName": "math_001_power_sum",
        "score": 10.00,
        "isCorrect": 1,
        "responseTime": 850,
        "modelResponse": "The answer is \\boxed{17}"
      },
      {
        "caseId": 2,
        "caseName": "math_002_linear_eq",
        "score": 10.00,
        "isCorrect": 1,
        "responseTime": 920,
        "modelResponse": "x = 4"
      }
    ],
    "metricResults": [
      {
        "metricName": "exact_match",
        "dimension": "accuracy",
        "score": 8.50,
        "rawValue": 0.85,
        "isPass": 1
      }
    ],
    "summary": "Overall Score: 8.50/10 (Grade: good)\n\nCase Results: 8/10 correct..."
  }
}
```

## 数据库表结构

```
model_info        -- 模型信息 (15个百炼平台模型)
eval_case         -- 评估用例/题库 (30道题, math+code)
eval_metric       -- 评估指标 (23个, 5维度)
eval_task         -- 评估任务 (组合: 模型+指标+用例)
eval_case_result  -- 逐题评估结果 (每道题的模型回答和判分)
eval_result       -- 指标聚合结果 (各维度汇总得分)
```

### 评估流程

```
创建任务 (指定模型+指标+用例)
    ↓
逐题评估: 调用百炼API -> 记录模型回答 -> 对比标准答案 -> 判对错
    ↓
写入 eval_case_result (逐题明细)
    ↓
聚合指标: 计算准确率/响应时间/一致性
    ↓
写入 eval_result (维度汇总)
    ↓
生成评分卡: 加权五维度 -> 0-10分 -> 等级
```

## 测试用例

```bash
# 运行全部测试
mvn test

# 逐题评估测试
mvn test -Dtest=ScorecardServiceTest

# 百炼平台集成测试
mvn test -Dtest=BailianIntegrationTest

# 数据集加载测试
mvn test -Dtest=DatasetLoaderTest

# 数据质量评分卡验收测试
mvn test -Dtest=DataQualityScorecardIntegrationTest
```

| 测试类 | 数量 | 覆盖内容 |
|--------|------|----------|
| ScorecardServiceTest | 6 | 评分计算、等级判定、逐题明细 |
| BailianIntegrationTest | 7 | 百炼API调用、代码提取、分数转换 |
| DatasetLoaderTest | 7 | 数据集加载、用例完整性 |
| DataQualityScorecardIntegrationTest | 10 | 五维度验收标准 |
| EvalTaskServiceTest | 6 | 任务生命周期、组合评估 |
| ModelInfoControllerTest | 6 | REST API |
| EncryptUtilTest | 6 | AES加密 |

## 数据质量评分卡 (0-10分)

| 维度 | 权重 | 计算方式 | 目标值 |
|------|------|---------|--------|
| 完整性 | 25% | 用例覆盖完成率 × 10 | ≥8.0 |
| 准确性 | 30% | 正确题数/总题数 × 10 | ≥8.5 |
| 唯一性 | 15% | (1 - 重复回答率) × 10 | ≥9.0 |
| 及时性 | 10% | max(0, 10 - 平均响应ms/100) | ≥7.0 |
| 一致性 | 20% | 重复查询一致性率 × 10 | ≥8.0 |

## 项目结构

```
ai-model-evaluation/
|-- pom.xml                                    # Maven配置
|-- README.md                                  # 本文件
|-- db/
|   -- init.sql                                # 完整数据库脚本
|-- src/
    |-- main/
    |   |-- java/com/aieval/
    |   |   |-- AIEvalApplication.java          # 启动类
    |   |   |-- client/
    |   |   |   |-- ModelClient.java           # 百炼平台API调用
    |   |   |-- config/                        # 配置类
    |   |   |-- controller/                    # REST控制器
    |   |   |   |-- ModelInfoController.java
    |   |   |   |-- EvalTaskController.java    # 任务+逐题结果
    |   |   |   |-- EvalMetricController.java
    |   |   |   |-- EvalCaseController.java    # 用例管理(NEW)
    |   |   |-- dataset/                       # 数据集加载
    |   |   |   |-- DatasetItem.java
    |   |   |   |-- DatasetLoader.java
    |   |   |   |-- DatasetEvaluator.java
    |   |   |-- service/                       # 业务逻辑
    |   |   |   |-- ModelInfoService.java
    |   |   |   |-- EvalTaskService.java        # 组合评估
    |   |   |   |-- EvalCaseService.java       # 用例管理(NEW)
    |   |   |   |-- EvalMetricService.java
    |   |   |   |-- EvalExecuteEngine.java      # 逐题评估引擎(重写)
    |   |   |   |-- ScorecardService.java       # 评分卡计算
    |   |   |-- mapper/                        # MyBatis映射
    |   |   |   |-- EvalCaseMapper.java        # (NEW)
    |   |   |   |-- EvalCaseResultMapper.java  # (NEW)
    |   |   |   |-- ...
    |   |   |-- entity/                        # 实体类
    |   |   |   |-- EvalCase.java              # 评估用例(NEW)
    |   |   |   |-- EvalCaseResult.java        # 逐题结果(NEW)
    |   |   |   |-- EvalTask.java              # 增加case_ids
    |   |   |   |-- ...
    |   |   |-- dto/                           # DTO
    |   |   |-- enums/                         # 枚举
    |   |   |-- util/                          # 工具类
    |   |-- resources/
    |       |-- datasets/                      # 数据集JSON
    |       |-- mapper/                        # MyBatis XML
    |-- test/                                  # 测试类
```

## 关键配置

### application-dev.yml

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/ai_model_evaluation?useUnicode=true&characterEncoding=utf-8&useSSL=false
    username: root
    password: your_password

evaluation:
  engine:
    max-concurrent-tasks: 5
    default-timeout-seconds: 60
    max-retry-times: 3
  scorecard:
    completeness-weight: 0.25
    accuracy-weight: 0.30
    uniqueness-weight: 0.15
    timeliness-weight: 0.10
    consistency-weight: 0.20
```

## 验收标准

| 维度 | 验收项 | 目标 |
|------|--------|------|
| 完整性 | 用例覆盖率 | 100%题目有标准答案 |
| 准确性 | 评分计算 | 手动验证与系统结果100%一致 |
| 唯一性 | 模型+用例组合无重复 | 同一模型同一用例只保留最新 |
| 及时性 | 单题评估<60秒 | API响应+判分总时长 |
| 一致性 | 跨环境结果一致 | 同一配置重复评估偏差<1% |