astron-eval 0.0.1

package/skills/model-evaluation/references//350/257/204/346/265/213/346/234/215/345/212/241/346/216/245/345/217/243/350/257/264/346/230/216.md

@@ -0,0 +1,455 @@
+---
+name: eval-service-api
+description: Use when needing to understand evaluation service API endpoints for dataset management and task execution
+---
+
+# 评测服务接口说明
+
+本文档定义评测服务的 API 接口，包括评测集管理和评测任务管理。
+
+---
+
+## 快速参考
+
+| 接口 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| 上传评测集 | POST | `/open/api/v1/evalset` | 上传评测数据 |
+| 下载评测集 | GET | `/open/api/v1/evalset/:id` | 分批下载评测数据 |
+| 查询评测集数量 | GET | `/open/api/v1/evalset/:id/count` | 查询条目总数 |
+| 提交评测任务 | POST | `/open/api/v1/eval/tasks` | 创建评测任务 |
+| 查询任务列表 | GET | `/open/api/v1/eval/tasks` | 分页查询任务 |
+| 查询任务详情 | GET | `/open/api/v1/eval/tasks/:id` | 获取任务状态和产物 |
+| 取消任务 | DELETE | `/open/api/v1/eval/tasks/:id` | 取消运行中任务 |
+| 查询任务产物 | GET | `/open/api/v1/eval/tasks/:id/artifacts` | 获取产物列表 |
+| 查询评测报告 | GET | `/open/api/v1/eval/tasks/:id/report` | 获取报告摘要 |
+
+---
+
+## 1. 概述
+
+### 1.1 统一响应格式
+
+所有接口返回 JSON 格式：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {}
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `code` | `int` | 业务状态码。`0` 表示成功，非 `0` 表示失败 |
+| `message` | `string` | 状态描述信息 |
+| `data` | `object` | 业务数据（仅成功时返回） |
+
+### 1.2 分页响应格式
+
+分页列表接口增加 `total` 字段：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": [],
+  "total": 100
+}
+```
+
+**分页请求参数**：
+
+| 参数 | 类型 | 必填 | 默认值 | 约束 | 说明 |
+|------|------|------|--------|------|------|
+| `page` | `int` | 否 | `1` | `≥ 1` | 页码 |
+| `page_size` | `int` | 否 | `20` | `1 ~ 100` | 每页数量 |
+
+### 1.3 认证方式
+
+| Header | 必填 | 说明 |
+|--------|------|------|
+| `Authorization` | 是 | `Bearer <access_token>` |
+| `Content-Type` | 是 | `application/json` |
+
+**认证失效处理**：
+
+```json
+{
+  "code": 10002,
+  "message": "鉴权Token已失效，请重新登录授权"
+}
+```
+
+### 1.4 错误码
+
+#### 通用错误码 (10000-19999)
+
+| 错误码 | HTTP状态码 | 说明 |
+|--------|------------|------|
+| `10000` | 500 | 内部服务错误 |
+| `10001` | 400 | 请求参数无效 |
+| `10002` | 401 | 未授权 |
+| `10003` | 403 | 权限不足 |
+| `10004` | 404 | 资源不存在 |
+
+#### 评测集错误码 (80000-89999)
+
+| 错误码 | HTTP状态码 | 说明 |
+|--------|------------|------|
+| `80001` | 400 | 评测集参数无效 |
+| `80002` | 500 | 评测集上传失败 |
+| `80003` | 500 | 评测集下载失败 |
+| `80004` | 500 | 评测集数量查询失败 |
+
+#### 评测任务错误码 (90000-99999)
+
+| 错误码 | HTTP状态码 | 说明 |
+|--------|------------|------|
+| `90001` | 400 | 任务定义无效 |
+| `90002` | 500 | 任务提交失败 |
+| `90003` | 404 | 任务不存在 |
+| `90004` | 500 | 任务停止失败 |
+| `90005` | 404 | 任务产物不存在 |
+| `90007` | 409 | 已有运行中任务，需稍后提交 |
+
+---
+
+## 2. 评测集接口
+
+评测集（Evalset）是评测任务的数据源，包含需要评测的对话条目。
+
+### 2.1 上传评测集
+
+**接口URL**：`POST /open/api/v1/evalset`
+
+**请求参数**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `evalset_id` | `string` | 否 | 评测集唯一标识（不传则自动生成） |
+| `items` | `array[EvalsetItem]` | 是 | 评测数据条目列表（1-500条） |
+
+**EvalsetItem 定义**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `case_id` | `string` | 是 | 用例唯一标识 |
+| `model` | `string` | 是 | 模型标识 |
+| `question` | `string` | 是 | 用户问题 |
+| `answer` | `string` | 是 | 模型回答 |
+| `system` | `string` | 否 | 系统提示词 |
+| `history` | `string` | 否 | 历史对话（JSON字符串） |
+| `context` | `string` | 否 | 上下文信息 |
+| `category` | `string` | 否 | 分类标签 |
+| `reference` | `string` | 否 | 参考答案 |
+| `keypoint` | `string` | 否 | 评测点列表（JSON字符串数组） |
+| `extends` | `object` | 否 | 自定义扩展字段 |
+| `metainfo` | `object` | 否 | 元信息 |
+
+**请求示例**：
+
+```json
+{
+  "evalset_id": "my-evalset-001",
+  "items": [
+    {
+      "case_id": "case-001",
+      "model": "gpt-4",
+      "question": "什么是大语言模型？",
+      "answer": "大语言模型是...",
+      "reference": "参考答案"
+    }
+  ]
+}
+```
+
+**响应参数**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data.received` | `int` | 实际接收的条目数量 |
+
+---
+
+### 2.2 下载评测集
+
+**接口URL**：`GET /open/api/v1/evalset/:id`
+
+**路径参数**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | `string` | 是 | 评测集标识 |
+
+**查询参数**：
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `offset` | `int` | 否 | `0` | 起始偏移量 |
+| `limit` | `int` | 否 | `300` | 返回条目数（1-500） |
+
+**请求示例**：`GET /open/api/v1/evalset/my-evalset-001?offset=0&limit=100`
+
+---
+
+### 2.3 查询评测集数量
+
+**接口URL**：`GET /open/api/v1/evalset/:id/count`
+
+**响应参数**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data.count` | `int` | 评测集条目总数 |
+
+---
+
+## 3. 评测任务接口
+
+评测任务（Eval Task）是评测的执行单元。
+
+### 3.1 提交评测任务
+
+**接口URL**：`POST /open/api/v1/eval/tasks`
+
+**请求参数**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `apiVersion` | `string` | 是 | 工作流模版版本（如 `v1`） |
+| `models` | `array[TaskModel]` | 否 | 参与评测的模型列表 |
+| `agents` | `array[TaskAgent]` | 否 | 评委列表 |
+| `spec` | `object(TaskSpec)` | 是 | 任务执行步骤定义 |
+
+**TaskModel 定义**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | `string` | 否 | 模型唯一标识 |
+| `name` | `string` | 否 | 模型显示名称 |
+| `type` | `string` | 否 | 模型类型（如 `openai`） |
+| `api_key` | `string` | 否 | API密钥 |
+| `api_url` | `string` | 否 | API地址 |
+| `model` | `string` | 否 | 模型名称 |
+| `concurrency` | `int` | 否 | 并发调用数 |
+| `params` | `object` | 否 | 模型推理参数 |
+
+**TaskAgent 定义**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | `string` | 否 | 评委唯一标识 |
+| `name` | `string` | 否 | 评委显示名称 |
+| `type` | `string` | 否 | 评委类型 |
+| `api_key` | `string` | 否 | API密钥 |
+| `api_url` | `string` | 否 | API地址 |
+| `flow_id` | `string` | 否 | 关联流程ID |
+| `concurrency` | `int` | 否 | 并发调用数 |
+| `params` | `object` | 否 | 评委参数 |
+
+**TaskSpec 定义**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `templates` | `array[TaskTemplate]` | 是 | 步骤模版列表（至少1个`evaluation`类型） |
+
+**TaskTemplate 定义**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | `string` | 是 | 步骤显示名称 |
+| `type` | `string` | 是 | 步骤类型 |
+| `parameters` | `object` | 否 | 步骤参数 |
+
+**TaskTemplate.type 枚举**：
+
+| 类型 | 必填 | 说明 |
+|------|------|------|
+| `evalset` | 否 | 评测集准备步骤 |
+| `evaluation` | 是 | 模型评测步骤（必需） |
+| `report-upload` | 否 | 报告上传步骤 |
+| `database` | 否 | 数据入库步骤 |
+
+**EvalItem 定义**（evaluation步骤的parameters.eval字段）：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | `string` | 否 | 评测项名称 |
+| `type` | `string` | 否 | 评测类型（`llm-score`/`agent-score`/`builtin`） |
+| `judge_id` | `string` | 否 | 评委ID |
+| `params` | `object` | 否 | 评测参数 |
+| `prompt` | `object` | 否 | 提示词配置 |
+| `weight` | `float64` | 否 | 权重 |
+| `func` | `string` | 否 | 评测函数（builtin类型时必填） |
+
+**Prompt 定义**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `role` | `string` | 角色设定 |
+| `definition` | `string` | 维度定义 |
+| `instruct` | `string` | 评分标准 |
+| `step` | `string` | 评测步骤 |
+| `body` | `object` | 用例级评测字段注入配置，如 `{"keypoint": true, "context": true}` |
+
+**请求示例**：
+
+```json
+{
+  "apiVersion": "v1",
+  "models": [
+    {
+      "id": "ID_AJ001",
+      "name": "DeepSeek-R1",
+      "type": "api-openai",
+      "model": "xdeepseekr1",
+      "concurrency": 50,
+      "params": {
+        "max_tokens": 16384,
+        "temperature": 0
+      }
+    }
+  ],
+  "spec": {
+    "templates": [
+      {
+        "name": "模型评测",
+        "type": "evaluation",
+        "parameters": {
+          "evalset": "eval-bw7adghvb",
+          "eval": [
+            {
+              "name": "相关性",
+              "type": "llm-score",
+              "judge_id": "ID_AJ001",
+              "weight": 0.3,
+              "prompt": {
+                "definition": "助手响应是否和用户问题强相关",
+                "instruct": "5分：内容紧扣核心主题...",
+                "step": "请遵循下面的步骤进行评判..."
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+### 3.2 查询任务列表
+
+**接口URL**：`GET /open/api/v1/eval/tasks`
+
+**查询参数**：
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `page` | `int` | 否 | `1` | 页码 |
+| `page_size` | `int` | 否 | `20` | 每页数量 |
+| `status` | `string` | 否 | - | 按状态筛选 |
+
+**任务状态枚举**：
+
+| 状态值 | 说明 |
+|--------|------|
+| `Pending` | 待执行 |
+| `Running` | 运行中 |
+| `Succeeded` | 已成功 |
+| `Failed` | 已失败 |
+| `Cancelled` | 已取消 |
+
+---
+
+### 3.3 查询任务详情
+
+**接口URL**：`GET /open/api/v1/eval/tasks/:id`
+
+**路径参数**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | `string` | 是 | 评测任务标识 |
+
+**TaskResponse 定义**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | `string` | 任务唯一标识 |
+| `name` | `string` | 任务名称 |
+| `status` | `string` | 任务状态 |
+| `progress` | `string` | 执行进度（如 `2/4`） |
+| `message` | `string` | 状态描述 |
+| `duration` | `int64` | 执行耗时（秒） |
+| `step_status` | `array[StepStatus]` | 步骤状态列表 |
+| `artifacts` | `array[Artifact]` | 产物列表 |
+| `created_at` | `string` | 创建时间 |
+| `updated_at` | `string` | 更新时间 |
+
+**StepStatus 定义**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | `string` | 步骤名称 |
+| `type` | `string` | 步骤类型 |
+| `phase` | `string` | 执行阶段（Pending/Running/Succeeded/Failed） |
+| `message` | `string` | 状态描述 |
+| `started_at` | `string` | 开始时间 |
+| `finished_at` | `string` | 结束时间 |
+
+**Artifact 定义**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | `int64` | 产物唯一标识 |
+| `type` | `string` | 产物类型 |
+| `name` | `string` | 产物名称 |
+| `url` | `string` | 访问地址 |
+| `metadata` | `object` | 产物元数据 |
+| `expires_at` | `string` | 过期时间 |
+| `created_at` | `string` | 创建时间 |
+
+**Artifact.type 枚举**：
+
+| 类型 | 说明 |
+|------|------|
+| `report_file` | 评测报告文件 |
+| `platform_page` | 平台报告页面 |
+| `raw_data` | 原始评测数据 |
+| `inference_result` | 推理结果数据 |
+
+---
+
+### 3.4 取消任务
+
+**接口URL**：`DELETE /open/api/v1/eval/tasks/:id`
+
+---
+
+### 3.5 查询任务产物列表
+
+**接口URL**：`GET /open/api/v1/eval/tasks/:id/artifacts`
+
+**查询参数**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `type` | `string` | 否 | 按产物类型筛选 |
+
+---
+
+### 3.6 查询评测报告摘要
+
+**接口URL**：`GET /open/api/v1/eval/tasks/:id/report`
+
+**TaskReportResponse 定义**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `task_id` | `string` | 任务标识 |
+| `status` | `string` | 任务状态 |
+| `artifacts` | `array[ArtifactBrief]` | 产物简要信息 |
+| `summary` | `object` | 评测结果摘要 |

package/skills/model-evaluation/references//350/257/204/346/265/213/347/273/264/345/272/246/350/257/264/346/230/216.md

@@ -0,0 +1,171 @@
+---
+name: dimension-config
+description: Use when creating or modifying evaluation dimension configurations
+---
+
+# 评测维度配置说明
+
+本文档说明评测维度配置的格式规范与设计方法。
+
+---
+
+## 1. 评测类型选择
+
+type 字段决定评测类型，是配置的核心决策点。
+
+### 主观评测 vs 客观评测
+
+| 维度 | 主观评测（llm-score/llm-judge） | 客观评测（builtin） |
+|------|-------------------------------|-------------------|
+| 评测方式 | 评委模型打分或判断 | 内置算法计算指标 |
+| 结果形式 | 分数（1-5）或通过/不通过 | 数值指标（如 0.85） |
+| 适用场景 | 语义理解、创意质量、用户体验 | 翻译质量、文本相似度、格式校验 |
+
+### 选择决策
+
+| 场景特征 | 推荐 type | 说明 |
+|----------|-----------|------|
+| 评估语义理解深度 | llm-score | "回答是否准确理解用户意图" |
+| 评估创意或质量 | llm-score | "文案是否有创意、吸引人" |
+| 判断是否符合规范 | llm-judge | "回答是否包含有害内容" |
+| 翻译/摘要质量 | builtin | 使用 BLEU、ROUGE 等标准指标 |
+| 格式正确性校验 | builtin | 使用 EQUAL、JSONFORMAT |
+
+### 常见场景推荐
+
+| 评测场景 | 推荐维度 | 推荐类型 |
+|----------|----------|----------|
+| 知识问答 | 准确性、完整性、相关性 | llm-score |
+| 内容创作 | 创意性、流畅性、风格契合 | llm-score |
+| 翻译任务 | BLEU、COMET | builtin |
+| 对话系统 | 帮助性、安全性、流畅性 | llm-score + llm-judge |
+| 格式转换 | EQUAL、JSONFORMAT | builtin |
+
+---
+
+## 2. 字段填充规则
+
+### 字段决策表
+
+| 字段 | llm-score | llm-judge | builtin |
+|------|-----------|-----------|---------|
+| name | 必填 | 必填 | 必填 |
+| type | `"llm-score"` | `"llm-judge"` | `"builtin"` |
+| judge_id | 必填，从 eval-judge.json 读取 | 必填，从 eval-judge.json 读取 | **不需要此字段** |
+| func | `""` | `""` | 必填 |
+| weight | 必填，[0, 1] | 必填，[0, 1] | 必填，[0, 1] |
+| prompt | 必填 | 必填 | 可填空对象 |
+| params | 可选，默认见下方 | 可选 | 可选 |
+
+**params 默认值**：`{"answer": "answer", "reference": "reference"}`
+
+### 内置函数（func）
+
+| func | 适用场景 |
+|------|----------|
+| BLEU | 机器翻译，基于 n-gram 精确度 |
+| ROUGE | 文本摘要，基于最长公共子序列 |
+| BERTScore | 语义相似度，基于 BERT |
+| COMET | 翻译质量，上下文感知模型 |
+| TER | 翻译错误率，基于编辑距离 |
+| Cosine | 余弦相似度，基于句子嵌入 |
+| EQUAL | 精确匹配 |
+| JSONFORMAT | JSON 格式校验 |
+
+### prompt 字段（主观评测必填）
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| role | 否 | 角色背景，可填 `""` |
+| definition | 是 | 维度定义，清晰描述"评测什么" |
+| instruct | 是 | 评价标准，如"5分：... 3分：... 1分：..." |
+| step | 是 | 评测步骤，3-5 步 |
+| body | 否 | 用例级评测字段注入配置，如 `{"keypoint": true, "context": true}` |
+
+**instruct 设计模板**：
+- llm-score：`5分：{最高标准} 3分：{中等标准} 1分：{最低标准}`
+- llm-judge：`通过：{通过条件} 不通过：{不通过条件}`
+
+---
+
+## 3. 配置文件格式
+
+```json
+{
+    "name": "{评测场景名称}",
+    "description": "{评测场景描述}",
+    "evals": [
+        { "维度对象1" },
+        { "维度对象2" }
+    ]
+}
+```
+
+**根节点字段**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| name | String | 是 | 评测场景名称 |
+| description | String | 否 | 评测场景描述 |
+| evals | Array | 是 | 评测维度数组 |
+
+---
+
+## 4. 配置示例
+
+**完整示例（多维度混合）**：
+
+```json
+{
+    "name": "知识问答",
+    "description": "开放问答场景评测",
+    "evals": [
+        {
+            "name": "准确性",
+            "type": "llm-score",
+            "judge_id": "ID_AJ001",
+            "func": "",
+            "weight": 0.5,
+            "prompt": {
+                "role": "",
+                "definition": "回答内容是否准确无误",
+                "instruct": "5分：完全准确无错误\n3分：基本准确有少量瑕疵\n1分：存在关键错误",
+                "step": "1. 识别关键信息点\n2. 验证各点准确性\n3. 检查遗漏或错误\n4. 给出评分"
+            }
+        },
+        {
+            "name": "完整性",
+            "type": "llm-score",
+            "judge_id": "ID_AJ001",
+            "func": "",
+            "weight": 0.3,
+            "prompt": {
+                "role": "",
+                "definition": "回答是否覆盖问题的所有要点",
+                "instruct": "5分：完全覆盖\n3分：覆盖主要要点\n1分：严重缺失",
+                "step": "1. 提取问题要点\n2. 检查覆盖情况\n3. 给出评分"
+            }
+        },
+        {
+            "name": "格式规范",
+            "type": "builtin",
+            "func": "JSONFORMAT",
+            "weight": 0.2,
+            "prompt": {}
+        }
+    ]
+}
+```
+
+---
+
+## 5. 生成配置检查清单
+
+- [ ] 根节点包含 `name`、`description`、`evals` 字段
+- [ ] `evals` 数组为扁平结构，无 `config` 嵌套
+- [ ] 主观评测的 `judge_id` 已从 `eval-judge.json` 读取
+- [ ] 主观评测的 `func` 为空字符串 `""`
+- [ ] 客观评测无 `judge_id` 字段
+- [ ] 客观评测的 `func` 已填写具体函数名
+- [ ] 所有维度的 `weight` 总和为 1.0
+- [ ] 主观评测的 `prompt` 包含 `definition`、`instruct`、`step`

package/skills/model-evaluation/scripts/cfg/eval-auth.cfg

@@ -0,0 +1,16 @@
+# 认证服务配置
+auth_init_url: "https://in.iflyaicloud.com/astron/bifrost-heimdallr/api/auth/init"
+token_url: "https://in.iflyaicloud.com/astron/bifrost-heimdallr/api/oauth/token"
+
+# 客户端标识
+# callback_client_id: 回调模式使用（自动接收授权码）
+# oob_client_id: 手动模式使用（OOB 模式）
+callback_client_id: "eval_skill_prod_callback"
+oob_client_id: "eval_skill_prod"
+
+# 回调模式配置
+# 注意：使用回调模式时，redirect_uri 由脚本动态生成
+# 服务端需要将 loopback 地址加入白名单，如：
+# - http://127.0.0.1:51943/callback
+# - http://127.0.0.1:8080/callback
+callback_port: 51943

package/skills/model-evaluation/scripts/cfg/eval-server.cfg

@@ -0,0 +1 @@
+base_url: "https://public-in.pro-api.iflyaicloud.com/maas"

package/skills/model-evaluation/scripts/clients/__init__.py

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+"""
+客户端模块
+
+包含所有与外部服务交互的客户端组件：
+- BaseHttpClient: HTTP 基类
+- AuthClient: 认证服务客户端
+- ApiClient: 评测服务 API 客户端
+- TokenManager: Token 管理
+- OAuthCallbackServer: OAuth 回调服务器
+"""
+
+from .http_client import BaseHttpClient
+from .auth_client import AuthClient
+from .api_client import ApiClient
+from .token_manager import TokenManager
+from .oauth_callback import (
+    generate_pkce_pair,
+    generate_state_token,
+    OAuthCallbackServer,
+    run_callback_server,
+)
+
+__all__ = [
+    'BaseHttpClient',
+    'AuthClient',
+    'ApiClient',
+    'TokenManager',
+    'generate_pkce_pair',
+    'generate_state_token',
+    'OAuthCallbackServer',
+    'run_callback_server',
+]