AgentEvalTool/docs/data-models-v1.0.md

# AgentEvalTool 数据模型文档

**版本**: v1.0  
**日期**: 2026-07-09  
**状态**: 已发布  
**作者**: AgentEval Team

---

## 一、概述

本文档描述 AgentEvalTool V1 版本的核心数据模型。所有模型均使用 Pydantic/SQLModel 定义，支持数据验证和持久化。

## 二、核心模型

### 2.1 EvalTarget（评测对象）

评测对象代表被评估的智能体服务。

```python
class EvalTarget:
    id: str                          # 唯一标识符（UUID）
    name: str                        # 对象名称
    description: str                 # 对象描述
    platform: str                    # 平台类型："ai_digital_employee" | "ai_assistant"
    channel_type: str                # 通道类型："tutu-api"
    channel_config: dict             # 通道配置参数
    status: str                      # 状态："active" | "inactive" | "error"
    created_at: datetime             # 创建时间
    updated_at: datetime             # 更新时间
```

**channel_config 字段说明**（tutu-api）：
- `base_url`: API 基础地址
- `token`: JWT 认证令牌
- `tenant`: 租户标识
- `chat_channel_id`: 聊天通道 ID
- `chat_contact_id`: 聊天联系人 ID

### 2.2 Scenario（评测场景）

评测场景定义一组测试用例和评估规则。

```python
class Scenario:
    id: str                          # 唯一标识符（UUID）
    name: str                        # 场景名称
    description: str                 # 场景描述
    tags: List[str]                  # 标签列表
    cases: List[Case]                # 用例列表
    created_at: datetime             # 创建时间
    updated_at: datetime             # 更新时间
```

### 2.3 Case（评测用例）

评测用例定义具体的测试对话和期望结果。

```python
class Case:
    id: str                          # 用例标识符
    type: str                        # 用例类型："single" | "multi_turn"
    messages: List[str]              # 消息列表（单轮或多轮）
    expectations: Expectation        # 期望结果
    eval_rules: List[EvalRuleConfig] # 评估规则配置
```

### 2.4 EvalRun（评测执行记录）

评测执行记录跟踪一次完整的评测任务。

```python
class EvalRun:
    id: str                          # 唯一标识符（UUID）
    target_id: str                   # 评测对象 ID
    scenario_id: str                 # 评测场景 ID
    status: str                      # 状态："pending" | "running" | "completed" | "failed"
    started_at: datetime             # 开始时间
    completed_at: Optional[datetime] # 完成时间
    summary: Optional[dict]          # 执行摘要
```

### 2.5 Turn（对话轮次）

对话轮次记录单次消息发送和回复。

```python
class Turn:
    id: str                          # 唯一标识符（UUID）
    run_id: str                      # 所属执行记录 ID
    case_id: str                     # 所属用例 ID
    round_index: int                 # 轮次序号（从 1 开始）
    sent_message: dict               # 发送的消息内容
    sent_at: datetime                # 发送时间
    question_msg_id: Optional[str]   # 问题消息 ID（用于配对回复）
    reply: Optional[dict]            # 回复内容
    received_at: Optional[datetime]  # 接收时间
    latency_ms: Optional[int]        # 响应延迟（毫秒）
```

### 2.6 EvalResult（评估结果）

评估结果记录单条规则的评估结果。

```python
class EvalResult:
    id: str                          # 唯一标识符（UUID）
    run_id: str                      # 所属执行记录 ID
    case_id: str                     # 所属用例 ID
    turn_id: str                     # 所属轮次 ID
    rule_type: str                   # 规则类型："keyword_match" | "response_time" | "llm_score"
    passed: bool                     # 是否通过
    score: Optional[float]           # 得分（0.0-1.0）
    reason: str                      # 评估原因说明
```

## 三、数据库表结构

所有模型均持久化到 SQLite 数据库（`data/agenteval.db`）。

### 3.1 表名映射

| 模型 | 表名 |
|------|------|
| EvalTarget | `eval_targets` |
| Scenario | `scenarios` |
| EvalRun | `eval_runs` |
| Turn | `turns` |
| EvalResult | `eval_results` |

### 3.2 关系图

```
EvalTarget (1) ──< (N) EvalRun
Scenario (1) ──< (N) EvalRun
EvalRun (1) ──< (N) Turn
EvalRun (1) ──< (N) EvalResult
Turn (1) ──< (N) EvalResult
```

## 四、数据持久化

- **数据库**: SQLite（本地文件存储）
- **ORM**: SQLModel（基于 Pydantic + SQLAlchemy）
- **数据目录**: `data/`
  - `agenteval.db`: 主数据库
  - `scenarios/`: 场景 YAML 文件
  - `reports/`: 生成的报告文件

## 五、扩展性

当前数据模型设计预留了扩展点：

1. **多通道支持**: `EvalTarget.channel_type` 支持不同通道类型
2. **多规则支持**: `EvalResult.rule_type` 支持不同评估规则
3. **多平台支持**: `EvalTarget.platform` 支持不同平台类型
4. **场景扩展**: `Scenario.cases` 支持复杂的多轮对话场景