astron-eval 0.0.1

package/skills/model-evaluation/references//344/270/255/351/227/264/344/272/247/347/211/251/350/257/264/346/230/216.md

@@ -0,0 +1,340 @@
+---
+name: intermediate-files
+description: Use when needing to understand the format and fields of intermediate files generated during evaluation workflow
+---
+
+# 中间产物说明
+
+本文档定义评测流程中产生的中间文件格式和字段。
+
+---
+
+## 快速参考
+
+| 阶段 | 文件名 | 说明 |
+|------|--------|------|
+| 初始化 | `auth.json` | 鉴权Token缓存 |
+| | `state.json` | OAuth授权状态 |
+| | `env.cfg` | 环境配置缓存 |
+| 构建 | `eval-dimension.json` | 评测维度配置 |
+| | `eval-judge.json` | 评委模型配置 |
+| | `evalset-structure.json` | 评测集结构分析 |
+| | `evalset-fields-mapping.json` | 字段映射配置 |
+| | `evalset-prepared.{ext}` | 待标准化评测集（流程产物） |
+| | `evalset-standard.jsonl` | 标准化评测集 |
+| | `evalset-meta.json` | 评测集元信息 |
+| 执行 | `evaltask-meta.json` | 任务元信息 |
+| | `evaltask-result.json` | 评测结果JSON |
+| | `evaltask-result.md` | 评测报告Markdown |
+| | `eval-progress.json` | 任务进度信息 |
+
+---
+
+## 1. 初始化阶段文件
+
+### auth.json
+
+**路径**：`{work-dir}/.eval/auth.json`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `access_token` | `string` | 访问令牌 |
+| `expires_in` | `int` | 有效时长（秒） |
+| `created_at` | `string` | 创建时间（ISO 8601） |
+| `expires_at` | `string` | 过期时间（ISO 8601） |
+
+### state.json
+
+**路径**：`{work-dir}/.eval/state.json`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `state_token` | `string` | 授权状态标识（UUID） |
+
+### env.cfg
+
+**路径**：`{work-dir}/.eval/env.cfg`
+
+| 字段 | 说明 |
+|------|------|
+| `python_cmd` | Python命令（`python` 或 `python3`） |
+| `deps_required` | 必需依赖列表 |
+| `deps_optional` | 可选依赖列表 |
+| `created_at` | 创建时间 |
+
+---
+
+## 2. 构建阶段文件
+
+### 评测集文件关系
+
+```
+评测集来源（任务4步骤1）
+    │
+    ├─► 流程3：解析评测集 ──► evalset-prepared.{ext}
+    │                              │
+    │                              ▼
+    ├─► 流程2：补充答案 ──► evalset-prepared.jsonl
+    │                              │
+    │                              ▼
+    ├─► 流程1：生成评测集 ──► evalset-prepared.jsonl
+    │                              │
+    └──────────────────────────────┘
+                                   │
+                                   ▼
+                          任务4步骤2：标准化转换
+                                   │
+                                   ▼
+                          evalset-standard.jsonl
+                                   │
+                                   ▼
+                          任务4步骤3：上传评测集
+                                   │
+                                   ▼
+                          evalset-meta.json
+```
+
+**文件生成流程**：
+1. **流程1（生成评测集）**：AI生成 → 预览确认 → 字段映射 → 任务4步骤2
+2. **流程2（补充答案）**：获取文件 → 验证 → AI补充答案 → 预览确认 → 字段映射 → 任务4步骤2
+3. **流程3（解析评测集）**：下载/复制 → 解析字段映射 → 用户确认 → 任务4步骤2
+
+---
+
+### eval-dimension.json
+
+**路径**：`{work-dir}/.eval/{session-id}/eval-dimension.json`
+
+字段定义见 [评测维度说明.md](./评测维度说明.md) 第2-3节。
+
+### eval-judge.json
+
+**路径**：`{work-dir}/.eval/{session-id}/eval-judge.json`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `models` | `array` | 是 | LLM评委列表 |
+
+**models[].LLMJudge**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | `string` | 是 | 模型标识（用于填充judge_id） |
+| `name` | `string` | 否 | 模型名称 |
+| `type` | `string` | 否 | 类型 |
+| `concurrency` | `int` | 是 | 并发数 |
+
+> **注意**：`api_key` 和 `api_url` 为空是正常现象，仅在使用自定义评委时需要配置。
+
+### evalset-structure.json
+
+**路径**：`{work-dir}/.eval/{session-id}/evalset/evalset-structure.json`
+
+**说明**：由 `eval_set.py analysis` 命令生成的评测集结构文件，用于字段映射生成。
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `file` | `string` | 文件路径 |
+| `format` | `string` | 文件格式（json/jsonl/csv/xlsx） |
+| `total_rows` | `int` | 总行数 |
+| `fields` | `object` | 字段信息，key 为字段名，value 包含 type 字段 |
+
+**示例**：
+
+```json
+{
+  "file": "dataset/sample-evalset.jsonl",
+  "format": "jsonl",
+  "total_rows": 100,
+  "fields": {
+    "question": {"type": "str"},
+    "answer": {"type": "str"},
+    "model": {"type": "str"},
+    "id": {"type": "int"}
+  }
+}
+```
+
+### evalset-standard.jsonl
+
+**路径**：`{work-dir}/.eval/{session-id}/evalset/evalset-standard.jsonl`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `question` | `string` | 是 | 评测问题 |
+| `answer` | `string` | 是 | 模型回答 |
+| `model` | `string` | 是 | 模型标识（默认 `default`） |
+| `case_id` | `string` | 是 | 用例标识（见下方说明） |
+| `system` | `string` | 否 | 系统提示词 |
+| `context` | `string` | 否 | 上下文信息 |
+| `category` | `string` | 否 | 分类标签 |
+| `reference` | `string` | 否 | 参考答案 |
+| `keypoint` | `string` | 否 | 评测点列表（JSON字符串数组） |
+
+**case_id 字段说明**：
+
+`case_id` 用于唯一标识评测问题，在多模型横评场景下有重要作用。
+
+| 场景 | case_id 生成规则 |
+|------|-----------------|
+| 源数据有 case_id 字段 | 直接使用源数据的值 |
+| 源数据无 case_id 字段 | 根据 question 字段分组，相同问题生成相同 case_id |
+
+**多模型横评示例**：
+
+假设评测两个模型（A和B）对两个问题的回答：
+
+| seq_id | case_id | model | question | answer |
+|--------|---------|-------|----------|--------|
+| 0 | case-0001 | A | 亚运会在哪个城市举行? | 杭州 |
+| 1 | case-0001 | B | 亚运会在哪个城市举行? | 杭州 |
+| 2 | case-0002 | A | 上海科技馆由哪几个主要展馆组成？ | 五个展馆 |
+| 3 | case-0002 | B | 上海科技馆由哪几个主要展馆组成？ | 三个展馆 |
+
+- `case_id`：问题的唯一标识，同一问题的不同模型回答共享相同 case_id
+- `seq_id`：行的唯一标识（内部序号）
+
+### evalset-prepared.jsonl / evalset-prepared.{ext}
+
+**路径**：`{work-dir}/.eval/{session-id}/evalset/evalset-prepared.{ext}`
+
+**说明**：各流程产出的待标准化评测集文件，统一由任务4步骤2进行标准化转换。
+
+| 来源流程 | 文件名 | 说明 |
+|----------|--------|------|
+| 流程1：生成评测集 | `evalset-prepared.jsonl` | AI 生成的评测集，包含问题和答案 |
+| 流程2：补充答案 | `evalset-prepared.jsonl` | 用户问题 + AI 补充答案 |
+| 流程3：解析评测集 | `evalset-prepared.{ext}` | 用户提供的原始评测集（保留原格式） |
+
+**字段说明**（流程1/2产物）：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `question` | `string` | 是 | 问题内容 |
+| `answer` | `string` | 是 | 答案内容 |
+| `model` | `string` | 是 | 模型标识（`generated` 或 `user-provided`） |
+| `case_id` | `string` | 是 | 用例标识 |
+| `category` | `string` | 否 | 分类标签 |
+| `reference` | `string` | 否 | 参考信息 |
+
+**流程1示例（AI生成）**：
+
+```jsonl
+{"case_id": "case-0001", "model": "generated", "question": "请为我推荐一个适合周末短途旅行的目的地。", "answer": "根据您的需求，我推荐苏州、杭州等周边城市...", "category": "旅游推荐"}
+{"case_id": "case-0002", "model": "generated", "question": "如何规划一个三口之家的日本七日游？", "answer": "以下是为您规划的七日游行程...", "category": "行程规划"}
+```
+
+**流程2示例（补充答案）**：
+
+```jsonl
+{"case_id": "case-001", "model": "user-provided", "question": "什么是大语言模型？", "answer": "大语言模型（Large Language Model，LLM）是一种基于深度学习的自然语言处理模型..."}
+{"case_id": "case-002", "model": "user-provided", "question": "如何提高代码质量？", "answer": "提高代码质量可以从以下几个方面入手：1. 遵循编码规范...", "category": "编程"}
+```
+
+### evalset-meta.json
+
+**路径**：`{work-dir}/.eval/{session-id}/evalset/evalset-meta.json`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `dataset` | `string` | 评测集标识（evalset_id） |
+| `dataset_size` | `int` | 评测集大小 |
+
+### evalset-fields-mapping.json
+
+**路径**：`{work-dir}/.eval/{session-id}/evalset/evalset-fields-mapping.json`
+
+**格式**：
+
+```json
+{
+  "question": {"source_field": "question", "default": null},
+  "answer": {"source_field": "answer", "default": null},
+  "model": {"source_field": null, "default": "deepseek-r1"},
+  "case_id": {"source_field": "id", "default": null}
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `{目标字段}.source_field` | `string` | 源数据中的字段名，为 null 表示无对应字段 |
+| `{目标字段}.default` | `string` | 默认值，当源数据无对应字段时使用 |
+
+**处理规则**：
+
+| source_field | default | 处理方式 |
+|--------------|---------|----------|
+| 有值且源数据有该字段 | - | 使用源数据值 |
+| 有值但源数据无该字段 | 有值 | 使用 default 值 |
+| null | 有值 | 使用 default 值 |
+| null | null | 使用内置默认值（model 为 `default`，case_id 自动生成） |
+
+> **注意**：`case_id` 字段不使用 `default` 值。有 `source_field` 时使用源数据值，无则根据 question 分组自动生成。
+
+**必填字段**：question、answer、model、case_id
+
+**可选字段**：system、context、category、reference、keypoint
+
+**字段匹配规则**：见 [evalset-parse-process.md](../processes/evalset-parse-process.md#32-匹配字段)。
+
+---
+
+## 3. 执行阶段文件
+
+### evaltask-meta.json
+
+**路径**：`{work-dir}/.eval/{session-id}/evaltask/evaltask-meta.json`
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `task_id` | `string` | 是 | 评测任务标识 |
+| `evalset_id` | `string` | 否 | 关联的评测集标识 |
+
+### evaltask-result.json
+
+**路径**：`{work-dir}/.eval/{session-id}/evaltask/evaltask-result.json`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `result` | `array` | 评测结果原始数据 |
+| `metric` | `object` | 评测指标数据 |
+| `usage` | `object` | Token使用统计 |
+| `summary` | `Summary` | 评测摘要（需解析展示） |
+
+**Summary 对象**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `type` | `string` | 报告类型 |
+| `meta` | `object` | 报告元信息 |
+| `content` | `array` | 报告详情列表 |
+
+### eval-progress.json
+
+**路径**：`{work-dir}/.eval/{session-id}/evaltask/eval-progress.json`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `evaltask_id` | `string` | 评测任务ID |
+| `status` | `string` | 任务状态 |
+| `progress` | `ProgressInfo` | 进度信息 |
+| `current_stage` | `string` | 当前阶段描述 |
+| `estimated_remaining_time` | `string` | 预估剩余时间 |
+| `started_at` | `string` | 开始时间 |
+| `updated_at` | `string` | 更新时间 |
+| `result_url` | `string` | 结果页面URL（完成时） |
+| `error` | `ErrorInfo` | 错误信息（失败时） |
+
+**ProgressInfo 对象**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `completed` | `int` | 已完成数量 |
+| `total` | `int` | 总数量 |
+| `percentage` | `int` | 完成百分比（0-100） |
+
+### evaltask-result.md
+
+**路径**：`{work-dir}/.eval/{session-id}/evaltask/evaltask-result.md`
+
+由脚本从 `evaltask-result.json` 渲染生成的可读报告。

package/skills/model-evaluation/references//345/206/205/347/275/256/346/250/241/346/235/277/350/257/264/346/230/216.md

@@ -0,0 +1,149 @@
+---
+name: builtin-templates
+description: Use when selecting expert templates or dimension templates for evaluation scenarios
+---
+
+# 内置模板说明
+
+本文档说明评测系统中内置的专家模板和维度配置模板。
+
+---
+
+## 1. 专家模板
+
+专家模板是针对特定评测场景预配置的完整评测方案，分为以下两类：
+
+### 1.1 通用维度级评测
+
+适合对场景化能力的宏观全面覆盖，如有效性、相关性、连贯性等通用评测维度。
+
+| 模板名称 | 适用场景 | 模板位置 |
+|----------|----------|----------|
+| 内容创造 | 文章创作、文案生成、创意写作 | `assets/experts/content-generation.json` |
+| 企业流程自动化 | 工具调用、API编排、业务流程自动化、Text2SQL | `assets/experts/business-process-automation.json` |
+| 内容匹配 | 标准问答、选择题、简答题（精确匹配） | `assets/experts/content-match.json` |
+| 个性化规划与推荐 | 旅游规划、学习计划、购物推荐 | `assets/experts/personalized-planning.json` |
+| 信息聚合分析 | 数据分析、报告生成、竞品分析、市场研究 | `assets/experts/information-analysis.json` |
+| 文本翻译 | 机器翻译、多语言内容转换 | `assets/experts/text-translation.json` |
+| 旅游出行 | 旅游攻略生成、行程规划、景点推荐 | `assets/experts/tourism-travel.json` |
+
+### 1.2 定制用例级评测
+
+适合对场景化能力的细节偏好对齐，针对每条用例有定制的评测要点。
+
+| 模板名称 | 适用场景 | 模板位置 |
+|----------|----------|----------|
+| 营销数字人 | 虚拟人多轮对话有效性评测 | `assets/experts/marketing-digital-human.json` |
+
+**使用方式**：直接复制专家模板至会话目录，按需调整维度权重。
+
+---
+
+## 2. 维度配置模板
+
+维度配置模板是可复用的单一评测维度定义，可灵活组合。分为以下两类：
+
+### 2.1 通用维度级评测模板
+
+适合对场景化能力的宏观全面覆盖，不依赖评测要点，可直接应用于整个评测集。
+
+#### 通用维度
+
+| 维度名称 | 适用场景 | 模板位置 |
+|----------|----------|----------|
+| 相关性 | 评估回答与问题的相关程度 | `assets/dimensions/相关性维度.json` |
+| 有效性 | 评估回答是否有效解决问题 | `assets/dimensions/有效性维度.json` |
+| 逻辑连贯性 | 评估内容组织和推理逻辑 | `assets/dimensions/逻辑连贯性维度.json` |
+| 完整性 | 评估是否覆盖所有需求点 | `assets/dimensions/完整性维度.json` |
+| 创意性/吸引性 | 评估创意性和吸引力 | `assets/dimensions/创意性-吸引性维度.json` |
+| 创新性 | 评估新颖洞察和独特视角 | `assets/dimensions/创新性维度.json` |
+
+#### 流程自动化维度
+
+| 维度名称 | 适用场景 | 模板位置 |
+|----------|----------|----------|
+| 准确性 | 工具调用准确性、输出结果准确性 | `assets/dimensions/准确性维度.json` |
+| 有效性-流程自动化 | 流程执行完整性和目标达成度 | `assets/dimensions/有效性维度-流程自动化.json` |
+| 指令遵循 | 输出格式、字段要求、特殊约束 | `assets/dimensions/指令遵循维度.json` |
+| 逻辑连贯性-流程自动化 | 多步骤编排合理性 | `assets/dimensions/逻辑连贯性维度-流程自动化.json` |
+
+#### 内容匹配维度
+
+| 维度名称 | 适用场景 | 模板位置 |
+|----------|----------|----------|
+| 内容精确 | 精确匹配（EQUAL函数） | `assets/dimensions/内容精确维度.json` |
+| 格式遵循 | JSON格式校验（JSONFORMAT函数） | `assets/dimensions/格式遵循维度.json` |
+
+#### 个性化规划维度
+
+| 维度名称 | 适用场景 | 模板位置 |
+|----------|----------|----------|
+| 准确性-个性化规划 | 推荐项信息准确可靠 | `assets/dimensions/准确性维度-个性化规划.json` |
+| 相关性-个性化规划 | 推荐内容与需求相关 | `assets/dimensions/相关性维度-个性化规划.json` |
+| 有效性-个性化规划 | 方案实际可执行性 | `assets/dimensions/有效性维度-个性化规划.json` |
+| 逻辑连贯性-个性化规划 | 时间、路线、顺序合理性 | `assets/dimensions/逻辑连贯性维度-个性化规划.json` |
+
+#### 信息分析维度
+
+| 维度名称 | 适用场景 | 模板位置 |
+|----------|----------|----------|
+| 准确性-信息分析 | 数据准确性、引用正确性 | `assets/dimensions/准确性维度-信息分析.json` |
+| 有效性-信息分析 | 分析结论的实际价值 | `assets/dimensions/有效性维度-信息分析.json` |
+| 完整性-信息分析 | 维度覆盖完整性 | `assets/dimensions/完整性维度-信息分析.json` |
+| 逻辑连贯性-信息分析 | 分析过程逻辑性 | `assets/dimensions/逻辑连贯性维度-信息分析.json` |
+
+#### 翻译维度（builtin类型）
+
+| 维度名称 | 函数 | 模板位置 |
+|----------|------|----------|
+| 精确性-BLEU | BLEU | `assets/dimensions/精确性-BLEU维度.json` |
+| 相似度-ROUGE | ROUGE | `assets/dimensions/相似度-ROUGE维度.json` |
+| 相似度-BERTScore | BERTScore | `assets/dimensions/相似度-BERTScore维度.json` |
+| 相似度-Cosine | Cosine | `assets/dimensions/相似度-Cosine维度.json` |
+| 精确性-COMET | COMET | `assets/dimensions/精确性-COMET维度.json` |
+| 文本差异度-TER | TER | `assets/dimensions/文本差异度-TER维度.json` |
+
+#### 旅游出行维度
+
+| 维度名称 | 适用场景 | 模板位置 |
+|----------|----------|----------|
+| 形式相关性 | 响应形式是否为旅游攻略 | `assets/dimensions/形式相关性维度.json` |
+| 内容相关性 | 时间、路线、途经点匹配度 | `assets/dimensions/内容相关性维度.json` |
+| 核心元素 | 交通、景点、住宿、饮食覆盖 | `assets/dimensions/核心元素维度.json` |
+| 逻辑合理性 | 时间合理、路线可执行、行程闭环 | `assets/dimensions/逻辑合理性维度.json` |
+| 准确性-旅游出行 | 景点信息、交通价格准确性 | `assets/dimensions/准确性维度-旅游出行.json` |
+| 特色亮点 | 地域独特性和情感价值 | `assets/dimensions/特色亮点维度.json` |
+| 忠诚度 | 引用链接、来源标识 | `assets/dimensions/忠诚度维度.json` |
+
+### 2.2 定制用例级评测模板
+
+适合对场景化能力的细节偏好对齐，依赖评测要点（keypoint），需针对每条用例配置评测要点后使用。
+
+| 维度名称 | 适用场景 | 模板位置 |
+|----------|----------|----------|
+| 有效性（用例级） | 多轮对话场景下，基于评测要点评估回复有效性 | `assets/dimensions/用例级评测维度模板.json` |
+
+**特点说明**：
+- 模板中 `body.keypoint` 设置为 `true`，表示依赖评测要点
+- 模板中 `body.context` 和 `body.history` 设置为 `true`，表示需要上下文和对话历史
+- 适用于营销数字人等需要针对每条用例定制评测要点的场景
+
+---
+
+## 3. 维度类型说明
+
+| 类型 | 说明 | 输出形式 |
+|------|------|----------|
+| llm-score | LLM评委打分 | 1-5分 |
+| llm-judge | LLM评委判断 | 通过/不通过 |
+| agent-score | Agent评委打分（需外部数据源） | 1-5分 |
+| builtin | 内置函数计算 | 数值指标 |
+
+---
+
+## 4. 使用注意事项
+
+- 同名维度在不同场景下有不同的定义和评分标准，使用时请注意区分
+- Agent类型维度需配置外部数据源
+- Builtin类型维度依赖评测服务支持对应函数
+- 自定义评测方案时，维度权重总和应为1.0