diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ea7e4e7..8a1ccf9 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -5,6 +5,7 @@ on: branches: - main - master + - 1.4.x paths: - "docs/**" - ".github/workflows/docs.yml" diff --git a/.gitignore b/.gitignore index 28bec66..06374c2 100644 --- a/.gitignore +++ b/.gitignore @@ -63,4 +63,11 @@ attachments # mvn flatten .flattened-pom.xml -.dump \ No newline at end of file +.dump + +# github pages +docs/.bundle +docs/.jekyll-cache +docs/_site +docs/vendor +docs/Gemfile.lock \ No newline at end of file diff --git a/docs/Gemfile b/docs/Gemfile index 6ce6ed4..44ddcef 100644 --- a/docs/Gemfile +++ b/docs/Gemfile @@ -1,10 +1,7 @@ source "https://rubygems.org" -gem "jekyll", "~> 4.3" -gem "just-the-docs", "~> 0.10" -gem "sass-embedded", "~> 1.69" # 锁定兼容版本，避免 1.100.0 原生扩展编译问题 +gem "just-the-docs" group :jekyll_plugins do - # 如需添加插件，在此处声明 -end - + gem "jekyll-seo-tag" +end \ No newline at end of file diff --git a/docs/_config.yml b/docs/_config.yml index 9a6291c..e2bb287 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -4,7 +4,13 @@ baseurl: "/evalkit-framework" url: "https://zendodx.github.io" # just-the-docs 主题 -remote_theme: just-the-docs/just-the-docs@v0.10.0 +theme: just-the-docs + +# 导航：默认展开所有子菜单，不折叠 +nav_fold: false + +# 页内目录（右侧 TOC）：自动为 h2/h3 标题生成锚点 +heading_anchors: true # 全文搜索 search_enabled: true @@ -58,6 +64,10 @@ kramdown: block: line_numbers: false +# Jekyll 插件 +plugins: + - jekyll-seo-tag + # 排除不需要渲染的目录 exclude: - "*.gemspec" diff --git a/docs/changelog.md b/docs/changelog.md index c419b33..9915f5c 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -6,7 +6,7 @@ nav_order: 4 # ChangeLog -## [1.3.1] - 2026-06-02 +## [1.4.0] - 2026-06-04 ### Added diff --git a/docs/dev-guide/delta-eval.md b/docs/dev-guide/delta-eval.md index 84ed20d..535c393 100644 --- a/docs/dev-guide/delta-eval.md +++ b/docs/dev-guide/delta-eval.md @@ -3,6 +3,7 @@ layout: default title: 增量评测技术说明 parent: 开发指南 nav_order: 1 +has_toc: true --- # 增量评测技术说明 diff --git a/docs/dev-guide/github-pages.md b/docs/dev-guide/github-pages.md new file mode 100644 index 0000000..ffd115e --- /dev/null +++ b/docs/dev-guide/github-pages.md @@ -0,0 +1,57 @@ +Github Pages使用方法 + +## 配置 + +(1) 在docs目录下创建Gemfile文件 + +```text +source "https://rubygems.org" + +gem "just-the-docs" + +group :jekyll_plugins do + gem "jekyll-seo-tag" +end +``` + +## 本地调试流程 + +(1)进入docs目录 +```shell +cd docs +``` + +(2)安装依赖 +```shell +bundle install --path vendor/bundle +``` + +如果一直卡在安装步骤,需要配置国内镜像源 + +```text +# 使用腾讯云镜像 +bundle config mirror.https://rubygems.org https://gems.ruby-china.com + +# 或者直接修改 Gemfile，第一行改为： +source "https://gems.ruby-china.com" +``` + +(3) 执行预览 + +```shell +bundle exec jekyll serve --livereload +``` + +LiveReload address: http://127.0.0.1:35729 + +Server address: http://127.0.0.1:4000/evalkit-framework/ + +## Github Actions执行流程 + +(1) 增加文档配置文件 + +```text +.github/workflow/docs.yml +``` + + diff --git a/docs/index.md b/docs/index.md index 79eb865..779f794 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,7 +8,7 @@ nav_order: 1 > 基于 Java 的自动化 AI 评测框架，以 DAG 工作流为核心，快速完成对大模型或 AI 业务接口的自动化评测。 -[快速开始](./user-guide/overview){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } +[快速开始]({{ site.baseurl }}/user-guide/overview){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } [查看 GitHub](https://github.com/zendodx/evalkit-framework){: .btn .fs-5 .mb-4 .mb-md-0 } --- @@ -25,8 +25,8 @@ nav_order: 1 ## 快速导航 -- 📖 [用户指南](./user-guide/) — 框架各模块完整使用说明 -- 🛠️ [开发指南](./dev-guide/) — 框架内部设计与扩展开发 -- 📋 [ChangeLog](./changelog) — 版本更新记录 -- 🤝 [贡献指南](./contribute) — 提交规范与贡献流程 +- 📖 [用户指南]({{ site.baseurl }}/user-guide/) — 框架各模块完整使用说明 +- 🛠️ [开发指南]({{ site.baseurl }}/dev-guide/) — 框架内部设计与扩展开发 +- 📋 [ChangeLog]({{ site.baseurl }}/changelog) — 版本更新记录 +- 🤝 [贡献指南]({{ site.baseurl }}/contribute) — 提交规范与贡献流程 diff --git a/docs/user-guide/api-completion-wrapper.md b/docs/user-guide/api-completion-wrapper.md index 36dc136..5ef5d73 100644 --- a/docs/user-guide/api-completion-wrapper.md +++ b/docs/user-guide/api-completion-wrapper.md @@ -3,13 +3,13 @@ layout: default title: 接口结果装饰器（ApiCompletionWrapper） parent: 用户指南 nav_order: 9 +has_toc: true --- # 接口结果装饰器（ApiCompletionWrapper） 接口结果装饰器在**接口调用完成后、评估器执行前**运行，用于对 `ApiCompletionResult` 进行转化、清洗或补充，将接口原始输出变换为评估器所需的格式。 ---- ## 体系结构 @@ -18,7 +18,6 @@ ApiCompletionWrapper（抽象基类） └── LLMBasedApiCompletionWrapper（抽象） 使用大模型转化接口输出 ``` ---- ## ApiCompletionWrapper（基类） @@ -73,7 +72,6 @@ protected void wrapper(DataItem dataItem) { } ``` ---- ## LLMBasedApiCompletionWrapper @@ -121,7 +119,6 @@ LLMBasedApiCompletionWrapper wrapper = new LLMBasedApiCompletionWrapper( }; ``` ---- ## 在工作流中使用 @@ -142,7 +139,6 @@ new WorkflowBuilder() .execute(); ``` ---- ## 注意事项 diff --git a/docs/user-guide/api-completion.md b/docs/user-guide/api-completion.md index 8af13a3..57a23da 100644 --- a/docs/user-guide/api-completion.md +++ b/docs/user-guide/api-completion.md @@ -3,13 +3,13 @@ layout: default title: 接口调用器（ApiCompletion） parent: 用户指南 nav_order: 8 +has_toc: true --- # 接口调用器（ApiCompletion） 接口调用器负责对每条测试数据**调用被测的业务接口**，并将返回结果存入 `DataItem` 的 `apiCompletionResult` 字段，供后续评估器使用。 ---- ## 体系结构 @@ -19,7 +19,6 @@ ApiCompletion（抽象基类） └── OrderedApiCompletion（抽象） 保证同一会话内的请求按序执行 ``` ---- ## ApiCompletion（基类） @@ -107,7 +106,6 @@ public ScorerResult eval(DataItem dataItem) { } ``` ---- ## HttpApiCompletion @@ -181,7 +179,6 @@ HttpApiCompletion httpApiCompletion = new HttpApiCompletion( }; ``` ---- ## OrderedApiCompletion @@ -244,7 +241,6 @@ OrderedApiCompletion orderedApiCompletion = new OrderedApiCompletion( | 并发方式 | 所有数据完全并行 | 不同会话并行，同会话串行 | | 需实现方法 | `invoke()` | `invoke()` + `prepareOrderKey()` + `prepareComparator()` | ---- ## 注意事项 diff --git a/docs/user-guide/checker.md b/docs/user-guide/checker.md index f66579c..bce1d57 100644 --- a/docs/user-guide/checker.md +++ b/docs/user-guide/checker.md @@ -3,13 +3,13 @@ layout: default title: 检查器（Checker） parent: 用户指南 nav_order: 11 +has_toc: true --- # 检查器（Checker） 检查器是 `MultiCheckerBasedScorer` 的内部组件，负责对评测数据进行**单个维度的细粒度检查**，每个检查器包含若干个**检查项（CheckItem）**，最终分数由所有检查项的结果汇总而来。 ---- ## 核心概念 @@ -28,7 +28,6 @@ MultiCheckerBasedScorer - `Checker`（检查器）包含多个 `CheckItem`（检查项） - `CheckItem` 是最小的打分单元 ---- ## CheckItem（检查项） @@ -91,7 +90,6 @@ CheckItem llmItem = CheckItem.builder() .build(); ``` ---- ## Checker 接口 @@ -108,7 +106,6 @@ public interface Checker { } ``` ---- ## AbstractChecker（抽象基类） @@ -133,7 +130,6 @@ public interface Checker { | `MinCheckItemScoreMergeStrategy` | 取最小检查项得分 | | 自定义 | 实现 `CheckItemScoreMergeStrategy` 接口 | ---- ## 示例：规则检查器 @@ -211,7 +207,6 @@ public class RequiredFieldsChecker extends AbstractChecker { } ``` ---- ## 示例：LLM 检查器 @@ -279,7 +274,6 @@ public class QualityChecker extends LLMBasedChecker { } ``` ---- ## 多轮对话检查（LLMBasedChecker 高级用法） @@ -316,7 +310,6 @@ public class MultiTurnChecker extends LLMBasedChecker { } ``` ---- ## 完整示例：组合多个检查器 diff --git a/docs/user-guide/counter.md b/docs/user-guide/counter.md index b98f9f1..1253c02 100644 --- a/docs/user-guide/counter.md +++ b/docs/user-guide/counter.md @@ -3,13 +3,13 @@ layout: default title: 统计器（Counter） parent: 用户指南 nav_order: 12 +has_toc: true --- # 统计器（Counter） 统计器在所有评估器执行完毕后运行，负责对所有数据的评测结果进行**汇总统计**，并将统计结果存入上下文，供 Reporter 使用。 ---- ## 体系结构 @@ -21,7 +21,6 @@ Counter（抽象基类） └── AttributeCounterV2 LLM归因分析 V2（带类别、情感极性、置信度） ``` ---- ## BasicCounter @@ -72,7 +71,6 @@ BasicCounter counter = new BasicCounter(); 就这一行！无需任何配置，把它放在所有 Scorer 之后即可。 ---- ## MetricCounter @@ -111,7 +109,6 @@ MetricCounter metricCounter = new MetricCounter() { }; ``` ---- ## AttributeCounter（归因分析 V1） @@ -152,7 +149,6 @@ AttributeCounter attributeCounter = new AttributeCounter(myLLMService); } ``` ---- ## AttributeCounterV2（归因分析 V2） @@ -208,7 +204,6 @@ AttributeCounterV2 attributeCounterV2 = new AttributeCounterV2(myLLMService); } ``` ---- ## 自定义统计器 @@ -238,7 +233,6 @@ Counter customCounter = new Counter() { }; ``` ---- ## 典型用法：组合多个统计器 diff --git a/docs/user-guide/data-generator.md b/docs/user-guide/data-generator.md index c5404e2..19cab32 100644 --- a/docs/user-guide/data-generator.md +++ b/docs/user-guide/data-generator.md @@ -3,6 +3,7 @@ layout: default title: 数据生成器（DataGenerator） parent: 用户指南 nav_order: 7 +has_toc: true --- # 数据生成器（DataGenerator） @@ -15,7 +16,6 @@ nav_order: 7 `DataGenerator` 继承自 `DataLoader`，也是工作流中的一个节点，它在执行时**生成数据**并将结果注入到工作流上下文，后续节点（如评估器）可以直接使用这些数据。 ---- ## 类继承关系 @@ -28,7 +28,6 @@ DataLoader（数据加载器） └── MultiDataGenerator 多源数据生成器（组合多个生成器） ``` ---- ## 公共配置（`DataGeneratorConfig`） @@ -42,7 +41,6 @@ DataLoader（数据加载器） | `genDataExporterList` | `List` | `[ExcelGenDataExporter]` | 导出器列表，默认导出 Excel | | `threadNum` | Integer | 1 | 并发生成的线程数 | ---- ## 数据导出器（GenDataExporter） @@ -69,7 +67,6 @@ DataGeneratorConfig config = EvalCaseDataGeneratorConfig.builder() .build(); ``` ---- ## 内置实现详解 @@ -168,7 +165,6 @@ public class HotelEvalCaseGenerator extends EvalCaseDataGenerator { } ``` ---- ### 2. LoaderBasedDataGenerator — 基于数据加载器的生成器（抽象类） @@ -217,7 +213,6 @@ public class ProductQueryGenerator extends LoaderBasedDataGenerator { } ``` ---- ### 3. KGBasedQueryGenerator — 基于知识图谱的数据生成器 @@ -402,7 +397,6 @@ Workflow workflow = Workflow.builder() .build(); ``` ---- ### 4. MultiDataGenerator — 多源数据生成器 @@ -420,7 +414,6 @@ MultiDataGeneratorConfig config = MultiDataGeneratorConfig.builder() MultiDataGenerator generator = new MultiDataGenerator(config); ``` ---- ## 数据生成器 vs 数据加载器 @@ -431,7 +424,6 @@ MultiDataGenerator generator = new MultiDataGenerator(config); | 是否依赖外部存储 | 是（文件、数据库等） | 否（可完全通过代码生成） | | 支持断点续评 | 不直接支持 | 不直接支持（需配合 `DeltaEvalFacade`） | ---- ## 完整流程示例：自动构建评测数据集 diff --git a/docs/user-guide/dataloader-wrapper.md b/docs/user-guide/dataloader-wrapper.md index 720d827..3f49f4e 100644 --- a/docs/user-guide/dataloader-wrapper.md +++ b/docs/user-guide/dataloader-wrapper.md @@ -3,30 +3,27 @@ layout: default title: 数据装饰器（DataLoaderWrapper） parent: 用户指南 nav_order: 4 +has_toc: true --- # 数据装饰器（DataLoaderWrapper） 数据装饰器用于在数据加载后、接口调用前，对测试数据进行**增强或变换**。典型用途包括： -- **Mock 数据替换**：把数据中的 `{{holiday}}`、`{{city}}` 等占位符替换成真实随机值 +- **Mock 数据替换**：把数据中的占位符（格式：`双花括号包裹规则名和参数`，如 `holiday`、`city 四川省`）替换成真实随机值 - **LLM 润色**：用大模型把原始 query 改写成更自然、口语化的表达 - **自定义增强**：在每条数据上追加字段、调用外部接口补充信息等 ---- - ## 体系结构 ``` DataLoaderWrapper（抽象基类） -├── MockDataLoaderWrapper 替换 {{占位符}} 为随机值 +├── MockDataLoaderWrapper 替换 占位符 为随机值 ├── PromptDataLoaderWrapper（抽象） 用 LLM Prompt 增强数据 │ └── PolishDataLoaderWrapper（抽象） 专门做口语润色 └── （自定义继承 DataLoaderWrapper） ``` ---- - ## DataLoaderWrapper（基类） 最通用的装饰器基类，实现 `wrapper(DataItem)` 方法即可。 @@ -54,11 +51,9 @@ DataLoaderWrapper wrapper = new DataLoaderWrapper( }; ``` ---- - ## MockDataLoaderWrapper -用于替换数据中的**占位符**（格式：`{{规则名 参数}}`），框架内置了多种 Mock 数据生成规则。 +用于替换数据中的**占位符**，框架内置了多种 Mock 数据生成规则，详细规则见 [mocker.md](./mocker)。 ### 配置项 @@ -85,67 +80,63 @@ MockDataLoaderWrapper mockWrapper = new MockDataLoaderWrapper() { ``` // 数据中 query 字段的值： -"{{future_date 3 7}}从北京去{{city}}，帮我订{{holiday}}特价机票" +"future_date 3 7从北京去city，帮我订holiday特价机票" // 替换后示例结果： "2026-06-03从北京去广州，帮我订端午节特价机票" ``` ---- - ## 内置 Mock 规则详解 ### DateMocker（日期） | 规则 | 说明 | 示例 | |------|------|------| -| `{{date}}` | 当前时间（默认格式 `yyyy-MM-dd HH:mm:ss`） | `2026-05-26 10:30:00` | -| `{{date yyyy/MM/dd}}` | 当前时间（自定义格式） | `2026/05/26` | -| `{{future_date 7}}` | 未来 0~7 天内随机日期 | `2026-05-29` | -| `{{future_date 3 14}}` | 未来 3~14 天内随机日期 | `2026-06-03` | -| `{{future_date 3 14 yyyy/MM/dd}}` | 未来 3~14 天内随机日期（自定义格式） | `2026/06/03` | -| `{{past_date 7}}` | 过去 0~7 天内随机日期 | `2026-05-20` | -| `{{past_date 14 365}}` | 过去 14~365 天内随机日期 | `2026-01-15` | +| `date` | 当前时间（默认格式 `yyyy-MM-dd HH:mm:ss`） | `2026-05-26 10:30:00` | +| `date yyyy/MM/dd` | 当前时间（自定义格式） | `2026/05/26` | +| `future_date 7` | 未来 0~7 天内随机日期 | `2026-05-29` | +| `future_date 3 14` | 未来 3~14 天内随机日期 | `2026-06-03` | +| `future_date 3 14 yyyy/MM/dd` | 未来 3~14 天内随机日期（自定义格式） | `2026/06/03` | +| `past_date 7` | 过去 0~7 天内随机日期 | `2026-05-20` | +| `past_date 14 365` | 过去 14~365 天内随机日期 | `2026-01-15` | ### HolidayMocker（节假日） | 规则 | 说明 | |------|------| -| `{{holiday}}` | 随机返回一个公历或农历节假日名称 | -| `{{local_holiday}}` | 随机公历节假日（元旦、春节、清明…） | -| `{{chinese_holiday}}` | 随机农历节假日 | -| `{{future_holiday}}` | 将来的某个节假日 | -| `{{future_holiday 20250815}}` | 2025-08-15 之后的节假日 | -| `{{past_holiday}}` | 过去的某个节假日 | -| `{{between_holiday 20250101 20251231}}` | 2025 年内的某个节假日 | +| `holiday` | 随机返回一个公历或农历节假日名称 | +| `local_holiday` | 随机公历节假日（元旦、春节、清明…） | +| `chinese_holiday` | 随机农历节假日 | +| `future_holiday` | 将来的某个节假日 | +| `future_holiday 20250815` | 2025-08-15 之后的节假日 | +| `past_holiday` | 过去的某个节假日 | +| `between_holiday 20250101 20251231` | 2025 年内的某个节假日 | ### ChinaAddressMocker（中国行政区划） | 规则 | 说明 | 示例 | |------|------|------| -| `{{province}}` | 随机省份 | `广东省` | -| `{{city}}` | 随机地级市 | `成都市` | -| `{{city 四川省}}` | 四川省下辖某个市 | `绵阳市` | -| `{{area}}` | 随机区/县 | `天府新区` | -| `{{area 四川省 成都市}}` | 成都市下辖某个区 | `武侯区` | -| `{{street}}` | 随机街道/乡镇 | `九眼桥街道` | -| `{{street 四川省 成都市 武侯区}}` | 武侯区下辖某个街道 | `望江路街道` | +| `province` | 随机省份 | `广东省` | +| `city` | 随机地级市 | `成都市` | +| `city 四川省` | 四川省下辖某个市 | `绵阳市` | +| `area` | 随机区/县 | `天府新区` | +| `area 四川省 成都市` | 成都市下辖某个区 | `武侯区` | +| `street` | 随机街道/乡镇 | `九眼桥街道` | +| `street 四川省 成都市 武侯区` | 武侯区下辖某个街道 | `望江路街道` | ### ChinaPOIMocker（景区） | 规则 | 说明 | 示例 | |------|------|------| -| `{{scenic}}` | 随机景区名称 | `故宫博物院` | -| `{{scenic 四川省}}` | 四川省某景区 | `九寨沟风景区` | -| `{{scenic 四川省 成都市}}` | 成都市某景区 | `大熊猫繁育研究基地` | +| `scenic` | 随机景区名称 | `故宫博物院` | +| `scenic 四川省` | 四川省某景区 | `九寨沟风景区` | +| `scenic 四川省 成都市` | 成都市某景区 | `大熊猫繁育研究基地` | ### NumberMocker（数字） | 规则 | 说明 | 示例 | |------|------|------| -| `{{int 1 10}}` | 1~10 之间的随机整数 | `7` | -| `{{float 0.5 5.0}}` | 0.5~5.0 之间的随机小数 | `3.14` | - ---- +| `int 1 10` | 1~10 之间的随机整数 | `7` | +| `float 0.5 5.0` | 0.5~5.0 之间的随机小数 | `3.14` | ## PromptDataLoaderWrapper @@ -174,8 +165,6 @@ PromptDataLoaderWrapper promptWrapper = new PromptDataLoaderWrapper( }; ``` ---- - ## PolishDataLoaderWrapper 专门用于把 query 字段改写成**更自然、口语化**的表达，继承自 `PromptDataLoaderWrapper`。 @@ -216,8 +205,6 @@ PolishDataLoaderWrapper polishWrapper = new PolishDataLoaderWrapper( "我明天要去上海出差，能帮我查下从北京出发的高铁，最好早上出发的" ``` ---- - ## 自定义 Mock 规则 如果内置的 Mock 规则不满足需求，可以实现 `Mocker` 接口自定义规则： @@ -258,24 +245,22 @@ MockDataLoaderWrapper mockWrapper = new MockDataLoaderWrapper() { }; // 使用示例： -// 输入： "帮我查{{flight}}航班的剩余座位" +// 输入： "帮我查flight航班的剩余座位" // 输出： "帮我查CA7823航班的剩余座位" ``` ---- - ## 同名占位符 sameMock 当一条数据中出现多个**相同规则**的占位符时，可以控制它们是生成**不同值**还是**同一个值**： ``` // 场景：往返机票，出发地和目的地的城市不能相同 -// query = "帮我订从{{city}}到{{city}}的机票" +// query = "帮我订从city到city的机票" -// sameMock=false（默认）：两个 {{city}} 分别独立 Mock，可能生成两个不同城市 +// sameMock=false（默认）：两个 city 分别独立 Mock，可能生成两个不同城市 // 输出： "帮我订从北京到上海的机票" ✓ -// sameMock=true：两个 {{city}} 生成同一个城市 +// sameMock=true：两个 city 生成同一个城市 // 输出： "帮我订从北京到北京的机票" ✗（不合理） ``` diff --git a/docs/user-guide/dataloader.md b/docs/user-guide/dataloader.md index 1b24f43..00aa967 100644 --- a/docs/user-guide/dataloader.md +++ b/docs/user-guide/dataloader.md @@ -3,13 +3,13 @@ layout: default title: 数据加载器（DataLoader） parent: 用户指南 nav_order: 3 +has_toc: true --- # 数据加载器（DataLoader） 数据加载器负责将评测数据加载到工作流上下文中，是整个评测流程的第一个数据节点。 ---- ## 体系结构 @@ -24,7 +24,6 @@ DataLoader（抽象基类） └── MultiDataLoader 聚合多个加载器 ``` ---- ## DataLoader（基类） @@ -81,7 +80,6 @@ DataLoader dataLoader = new JsonFileDataLoader( ); ``` ---- ## ExcelDataLoader @@ -127,7 +125,6 @@ ExcelDataLoader loader3 = new ExcelDataLoader( ); ``` ---- ## CsvDataLoader @@ -159,7 +156,6 @@ CsvDataLoader loader = new CsvDataLoader( ); ``` ---- ## JsonFileDataLoader @@ -196,7 +192,6 @@ JsonFileDataLoader loader2 = new JsonFileDataLoader( ); ``` ---- ## JsonTextDataLoader @@ -221,7 +216,6 @@ JsonTextDataLoader loader = new JsonTextDataLoader() { }; ``` ---- ## ApiDataLoader @@ -279,7 +273,6 @@ ApiDataLoader loader = new ApiDataLoader( }; ``` ---- ## JdbcDataLoader @@ -321,7 +314,6 @@ JdbcDataLoader loader = new JdbcDataLoader( }; ``` ---- ## MultiDataLoader @@ -345,7 +337,6 @@ MultiDataLoader multiLoader = new MultiDataLoader( ); ``` ---- ## 常见问题 diff --git a/docs/user-guide/debugger.md b/docs/user-guide/debugger.md index 2e6deb6..b01967b 100644 --- a/docs/user-guide/debugger.md +++ b/docs/user-guide/debugger.md @@ -3,6 +3,7 @@ layout: default title: 调试器（Debugger） parent: 用户指南 nav_order: 15 +has_toc: true --- # 调试器（Debugger） @@ -18,7 +19,6 @@ nav_order: 15 - 你想修改统计逻辑后重新统计，但不想再次调用耗时的接口 - 此时用 `JsonFileDebugger` 加载上次的结果，直接跳到统计和上报步骤即可 ---- ## 类继承关系 @@ -29,7 +29,6 @@ WorkflowNode（工作流节点） └── JsonStringDebugger 从 JSON 字符串加载数据并注入上下文 ``` ---- ## 核心机制 @@ -40,7 +39,6 @@ WorkflowNode（工作流节点） 3. 将数据注入到工作流上下文（`WorkflowContext`）中 4. 后续节点（如统计器、上报器）直接使用注入的数据，无需再走数据加载和接口调用 ---- ## 调试器参数说明 @@ -57,7 +55,6 @@ WorkflowNode（工作流节点） - **`true`（默认）**：保留 JSON 数据中已有的评测结果，适合"只重新统计、不重新评测"的场景 - **`false`**：清空 JSON 数据中的评测结果，重新初始化一个空的 `EvalResult`，适合"数据已有接口调用结果，需要重新评测打分"的场景 ---- ## 内置实现 @@ -104,7 +101,6 @@ new FullEvalFacade(config).run(); > 💡 **最佳实践**：通常将调试器直接放在 `evalWorkflow` 的第一个节点，它会覆盖 `loadData()` 阶段加载的数据，或者更简单地，专门构建一个只含调试器和后续处理节点的工作流。 ---- ### 2. JsonStringDebugger — 从 JSON 字符串加载 @@ -172,7 +168,6 @@ public void testBasicCounter() { } ``` ---- ## 调试数据的 JSON 格式 @@ -219,7 +214,6 @@ public void testBasicCounter() { } ``` ---- ## 典型使用场景 @@ -294,7 +288,6 @@ public void testPromptBasedScorer() { } ``` ---- ## 调试器 vs 数据加载器 @@ -306,7 +299,6 @@ public void testPromptBasedScorer() { | **是否包含评测结果** | 可以包含（可配置） | 通常不包含 | | **推荐使用场景** | 调试、单元测试、重新统计 | 正式评测 | ---- ## 注意事项 diff --git a/docs/user-guide/facade.md b/docs/user-guide/facade.md index 9433789..f0af250 100644 --- a/docs/user-guide/facade.md +++ b/docs/user-guide/facade.md @@ -3,6 +3,7 @@ layout: default title: 评测门面（EvalFacade） parent: 用户指南 nav_order: 14 +has_toc: true --- # 评测门面（EvalFacade） @@ -13,7 +14,6 @@ nav_order: 14 你只需要配置好评测门面，调用 `run()` 方法，框架就会自动完成所有步骤。 ---- ## 三种评测模式 @@ -23,7 +23,6 @@ nav_order: 14 | **增量评测** | `DeltaEvalFacade` | 数据量大、需要断点续评、支持周期上报进度 | | **有序增量评测** | `OrderedDeltaEvalFacade` | 在增量评测基础上，保证同组数据（如同一会话）按顺序处理 | ---- ## 通用生命周期 @@ -50,7 +49,6 @@ run() └── afterExecute() 执行后钩子 ``` ---- ## 公共基础配置（`EvalConfig`） @@ -73,7 +71,6 @@ run() > 💡 **环境变量覆盖**：所有配置参数都可以通过 JVM 系统属性覆盖，例如 `-DthreadNum=8 -DpassScore=0.7`，方便在不修改代码的情况下动态调整配置。 ---- ## 模式一：全量评测（FullEvalFacade） @@ -140,7 +137,6 @@ FullEvalConfig config = FullEvalConfig.builder() new FullEvalFacade(config).run(); ``` ---- ## 模式二：增量评测（DeltaEvalFacade） @@ -253,7 +249,6 @@ eval_cache_data/ └── {taskNameUuid}.db # SQLite数据库文件 ``` ---- ## 模式三：有序增量评测（OrderedDeltaEvalFacade） @@ -318,7 +313,6 @@ DeltaEvalConfig config = DeltaEvalConfig.builder() new OrderedHotelEvalFacade(config).run(); ``` ---- ## 三种模式选择指南 @@ -336,7 +330,6 @@ new OrderedHotelEvalFacade(config).run(); → 使用 DeltaEvalFacade ``` ---- ## 进度监控 @@ -362,7 +355,6 @@ new Thread(() -> { deltaFacade.run(); ``` ---- ## 注意事项 diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md index 04f1dce..8ecc18f 100644 --- a/docs/user-guide/index.md +++ b/docs/user-guide/index.md @@ -8,7 +8,7 @@ permalink: /user-guide/ # EvalKit Framework 用户指南 -> 版本：1.2.x | 语言：Java 8+ | 构建：Maven 3.6+ +> 版本：1.4.x | 语言：Java 8+ | 构建：Maven 3.6+ ## 文档目录 @@ -16,41 +16,41 @@ permalink: /user-guide/ | 文档 | 说明 | |------|------| -| [概述与快速开始](./overview.md) | 框架简介、Maven 引入、整体架构、Hello World 示例 | -| [大模型服务（LLMService）](./llm-service.md) | 接入 LLM，配置模型参数、重试策略、Token 计费 | +| [概述与快速开始](./overview) | 框架简介、Maven 引入、整体架构、Hello World 示例 | +| [大模型服务（LLMService）](./llm-service) | 接入 LLM，配置模型参数、重试策略、Token 计费 | ### 数据准备 | 文档 | 说明 | |------|------| -| [数据加载器（DataLoader）](./dataloader.md) | 从 Excel/CSV/JSON/JDBC/API 加载评测数据 | -| [数据装饰器（DataLoaderWrapper）](./dataloader-wrapper.md) | Mock 占位符替换、Prompt 润色、数据增强 | -| [Mock 规则引擎（Mocker）](./mocker.md) | 内置 6 种 Mocker 完整规则详解：精确日期、模糊日期、节假日、行政区划、景区 POI、数字；自定义 Mocker | -| [Query 生成器（QueryGenerator）](./querygen.md) | 生成测试 Query，支持 Mock 规则和 LLM 生成 | -| [数据生成器（DataGenerator）](./data-generator.md) | 自动生成多轮对话评测数据集，含知识图谱驱动方式（KGBased） | +| [数据加载器（DataLoader）](./dataloader) | 从 Excel/CSV/JSON/JDBC/API 加载评测数据 | +| [数据装饰器（DataLoaderWrapper）](./dataloader-wrapper) | Mock 占位符替换、Prompt 润色、数据增强 | +| [Mock 规则引擎（Mocker）](./mocker) | 内置 6 种 Mocker 完整规则详解：精确日期、模糊日期、节假日、行政区划、景区 POI、数字；自定义 Mocker | +| [Query 生成器（QueryGenerator）](./querygen) | 生成测试 Query，支持 Mock 规则和 LLM 生成 | +| [数据生成器（DataGenerator）](./data-generator) | 自动生成多轮对话评测数据集，含知识图谱驱动方式（KGBased） | ### 评测核心 | 文档 | 说明 | |------|------| -| [接口调用器（ApiCompletion）](./api-completion.md) | 调用被测业务接口，支持 HTTP、有序多轮调用 | -| [接口结果装饰器（ApiCompletionWrapper）](./api-completion-wrapper.md) | 在评估前对接口返回结果进行转化、清洗或 LLM 二次处理 | -| [评估器（Scorer）](./scorer.md) | 对接口返回结果进行打分，内置向量相似度、LLM 评分等多种策略 | -| [检查器（Checker）](./checker.md) | 细粒度规则检查，配合 MultiCheckerBasedScorer 使用 | +| [接口调用器（ApiCompletion）](./api-completion) | 调用被测业务接口，支持 HTTP、有序多轮调用 | +| [接口结果装饰器（ApiCompletionWrapper）](./api-completion-wrapper) | 在评估前对接口返回结果进行转化、清洗或 LLM 二次处理 | +| [评估器（Scorer）](./scorer) | 对接口返回结果进行打分，内置向量相似度、LLM 评分等多种策略 | +| [检查器（Checker）](./checker) | 细粒度规则检查，配合 MultiCheckerBasedScorer 使用 | ### 结果处理 | 文档 | 说明 | |------|------| -| [统计器（Counter）](./counter.md) | 汇总评测指标，含 LLM 驱动的问题归因分析 | -| [上报器（Reporter）](./reporter.md) | 将评测结果输出到文件（Excel/CSV/JSON/HTML）、数据库或远程 API | +| [统计器（Counter）](./counter) | 汇总评测指标，含 LLM 驱动的问题归因分析 | +| [上报器（Reporter）](./reporter) | 将评测结果输出到文件（Excel/CSV/JSON/HTML）、数据库或远程 API | ### 进阶使用 | 文档 | 说明 | |------|------| -| [评测门面（EvalFacade）](./facade.md) | 全量评测、增量断点续评、有序增量评测三种模式详解 | -| [调试器（Debugger）](./debugger.md) | 注入已有数据跳过部分节点，加速开发调试和重新统计 | +| [评测门面（EvalFacade）](./facade) | 全量评测、增量断点续评、有序增量评测三种模式详解 | +| [调试器（Debugger）](./debugger) | 注入已有数据跳过部分节点，加速开发调试和重新统计 | --- @@ -82,15 +82,15 @@ Counter → Reporter **我需要...** -- 加载 Excel/CSV 数据集 → [DataLoader](./dataloader.md) -- 自动生成测试数据 → [DataGenerator](./data-generator.md) -- 查询 Mock 占位符规则 → [Mocker](./mocker.md) -- 调用被测接口 → [ApiCompletion](./api-completion.md) -- 转化接口返回格式 → [ApiCompletionWrapper](./api-completion-wrapper.md) -- 打分评估接口质量 → [Scorer](./scorer.md) -- 细粒度检查多个条件 → [Checker](./checker.md) -- 统计通过率、错误归因 → [Counter](./counter.md) -- 保存/输出评测报告 → [Reporter](./reporter.md) -- 运行完整评测任务 → [EvalFacade](./facade.md) -- 快速调试，不想重跑接口 → [Debugger](./debugger.md) +- 加载 Excel/CSV 数据集 → [DataLoader](./dataloader) +- 自动生成测试数据 → [DataGenerator](./data-generator) +- 查询 Mock 占位符规则 → [Mocker](./mocker) +- 调用被测接口 → [ApiCompletion](./api-completion) +- 转化接口返回格式 → [ApiCompletionWrapper](./api-completion-wrapper) +- 打分评估接口质量 → [Scorer](./scorer) +- 细粒度检查多个条件 → [Checker](./checker) +- 统计通过率、错误归因 → [Counter](./counter) +- 保存/输出评测报告 → [Reporter](./reporter) +- 运行完整评测任务 → [EvalFacade](./facade) +- 快速调试，不想重跑接口 → [Debugger](./debugger) diff --git a/docs/user-guide/llm-service.md b/docs/user-guide/llm-service.md index 45dc3c8..4025b6d 100644 --- a/docs/user-guide/llm-service.md +++ b/docs/user-guide/llm-service.md @@ -3,13 +3,13 @@ layout: default title: 大模型服务（LLMService） parent: 用户指南 nav_order: 2 +has_toc: true --- # 大模型服务（LLMService） `LLMService` 是框架中调用大模型的统一接口，凡是需要 LLM 能力的节点（`PromptBasedScorer`、`AttributeCounter`、`PromptBasedQueryGenerator` 等）都依赖它。 ---- ## 接口定义 @@ -23,7 +23,6 @@ public interface LLMService { } ``` ---- ## 内置实现 @@ -35,7 +34,6 @@ public interface LLMService { | DeepSeek | `LLMServiceFactory.createDeepSeekService(...)` | | 自定义（任意 HTTP） | 实现 `LLMService` 接口 | ---- ## 配置参数（LLMServiceConfig） @@ -54,7 +52,6 @@ public interface LLMService { | `inPrice` | 输入 Token 价格（每百万 Token） | 0.0 | | `outPrice` | 输出 Token 价格（每百万 Token） | 0.0 | ---- ## 使用示例 @@ -121,7 +118,6 @@ public class MyPrivateLLMService implements LLMService { } ``` ---- ## Token 计费统计 @@ -143,7 +139,6 @@ public class MyPrivateLLMService implements LLMService { } ``` ---- ## 注意事项 diff --git a/docs/user-guide/mocker.md b/docs/user-guide/mocker.md index 3b969f9..8e82de4 100644 --- a/docs/user-guide/mocker.md +++ b/docs/user-guide/mocker.md @@ -3,22 +3,17 @@ layout: default title: Mock 规则引擎（Mocker） parent: 用户指南 nav_order: 5 +has_toc: true --- # Mock 规则引擎（Mocker） ## 概述 -`MockDataLoaderWrapper` 通过**占位符替换**对数据进行增强，占位符格式统一为： - -``` -{{规则名 参数1 参数2 ...}} -``` +`MockDataLoaderWrapper` 通过**占位符替换**对数据进行增强，占位符格式统一为 `双花括号 + 规则名 + 空格分隔的参数`，例如 `date yyyy-MM-dd`、`future_date 3 14`、`city 四川省`。 框架内置 6 种 Mocker，全部在 `SpelMockRuleEngine` 中自动注册，**开箱即用**，无需额外配置。 ---- - ## 内置 Mocker 总览 | Mocker 类名 | 触发规则名 | 说明 | @@ -30,39 +25,37 @@ nav_order: 5 | `ChinaPoiMocker` | `scenic`（精确匹配） | 中国景区 POI | | `NumberMocker` | 含 `int` 或 `float` | 随机数字 | ---- - ## 一、DateMocker — 精确日期 > 类名：`DateMocker`，触发条件：规则名包含 `date`（大小写不敏感，但不含 `fuzzy_date`） -### 1.1 当前时间 `{{date}}` +### 1.1 当前时间 `date` | 规则 | 说明 | 示例结果 | |---|---|---| -| `{{date}}` | 当前时间，默认格式 `yyyy-MM-dd HH:mm:ss` | `2026-05-26 10:30:00` | -| `{{date yyyy/MM/dd}}` | 当前时间，自定义格式 | `2026/05/26` | -| `{{date HH:mm}}` | 当前时间，只取时分 | `10:30` | +| `date` | 当前时间，默认格式 `yyyy-MM-dd HH:mm:ss` | `2026-05-26 10:30:00` | +| `date yyyy/MM/dd` | 当前时间，自定义格式 | `2026/05/26` | +| `date HH:mm` | 当前时间，只取时分 | `10:30` | -### 1.2 未来日期 `{{future_date}}` +### 1.2 未来日期 `future_date` | 规则 | 说明 | 示例结果 | |---|---|---| -| `{{future_date}}` | 未来 0~7 天内随机日期（默认） | `2026-05-29 10:30:00` | -| `{{future_date 14}}` | 未来 0~14 天内随机日期 | `2026-06-05 10:30:00` | -| `{{future_date 3 14}}` | 未来 3~14 天内随机日期 | `2026-06-03 10:30:00` | -| `{{future_date 14 yyyy-MM-dd}}` | 未来 0~14 天内，自定义格式 | `2026-06-05` | -| `{{future_date 3 14 yyyy/MM/dd}}` | 未来 3~14 天内，自定义格式 | `2026/06/03` | +| `future_date` | 未来 0~7 天内随机日期（默认） | `2026-05-29 10:30:00` | +| `future_date 14` | 未来 0~14 天内随机日期 | `2026-06-05 10:30:00` | +| `future_date 3 14` | 未来 3~14 天内随机日期 | `2026-06-03 10:30:00` | +| `future_date 14 yyyy-MM-dd` | 未来 0~14 天内，自定义格式 | `2026-06-05` | +| `future_date 3 14 yyyy/MM/dd` | 未来 3~14 天内，自定义格式 | `2026/06/03` | -### 1.3 过去日期 `{{past_date}}` +### 1.3 过去日期 `past_date` | 规则 | 说明 | 示例结果 | |---|---|---| -| `{{past_date}}` | 过去 0~7 天内随机日期（默认） | `2026-05-20 10:30:00` | -| `{{past_date 30}}` | 过去 0~30 天内随机日期 | `2026-05-01 10:30:00` | -| `{{past_date 14 365}}` | 过去 14~365 天内随机日期 | `2026-01-15 10:30:00` | -| `{{past_date 7 yyyy-MM-dd}}` | 过去 0~7 天内，自定义格式 | `2026-05-20` | -| `{{past_date 14 365 yyyy/MM/dd}}` | 过去 14~365 天内，自定义格式 | `2026/01/15` | +| `past_date` | 过去 0~7 天内随机日期（默认） | `2026-05-20 10:30:00` | +| `past_date 30` | 过去 0~30 天内随机日期 | `2026-05-01 10:30:00` | +| `past_date 14 365` | 过去 14~365 天内随机日期 | `2026-01-15 10:30:00` | +| `past_date 7 yyyy-MM-dd` | 过去 0~7 天内，自定义格式 | `2026-05-20` | +| `past_date 14 365 yyyy/MM/dd` | 过去 14~365 天内，自定义格式 | `2026/01/15` | ### 1.4 参数解析规则 @@ -77,8 +70,6 @@ nav_order: 5 | `[数字] [格式字符串]` | 最多天数，自定义格式 | | `[数字] [数字] [格式字符串]` | 最少~最多天数，自定义格式 | ---- - ## 二、ChinaFuzzyDateMocker — 模糊日期 > 类名：`ChinaFuzzyDateMocker`，触发条件：规则名为 `fuzzy_date`（精确匹配） @@ -87,9 +78,7 @@ nav_order: 5 ### 2.1 参数说明 -``` -{{fuzzy_date [类型] [方向]}} -``` +规则名 `fuzzy_date`，可选追加类型和方向参数： - **类型**（可选）：`day`、`week`、`month`、`year`、`season`、`human`，不填表示随机所有类型 - **方向**（可选）：`future`（未来）、`past`（过去），不填表示随机混合 @@ -98,23 +87,21 @@ nav_order: 5 | 规则 | 可能的结果 | |---|---| -| `{{fuzzy_date}}` | `下周` / `月底` / `去年` / `近日` | -| `{{fuzzy_date future}}` | `明年` / `下周` / `月末` / `过两天` | -| `{{fuzzy_date past}}` | `上周` / `去年` / `前两三天` / `近日` | -| `{{fuzzy_date day future}}` | `不日` / `即日` / `改日` / `来日` / `当日` | -| `{{fuzzy_date day past}}` | `近日` / `近来` / `最近` / `日前` / `昔日` / `往日` | -| `{{fuzzy_date week future}}` | `本周` / `下周` / `周末` / `未来一周` / `未来二周` | -| `{{fuzzy_date week past}}` | `上周` / `上上周` / `大上周` / `过去一周` / `过去二周` | -| `{{fuzzy_date month future}}` | `月初` / `月中` / `月末` / `上旬` / `中旬` / `下旬` / `未来一月` | -| `{{fuzzy_date month past}}` | `上月` / `过去一月` / `过去二月` / `过去三月` | -| `{{fuzzy_date year future}}` | `今年` / `明年` / `后年` / `年初` / `年中` / `年底` / `下半年` / `来年` | -| `{{fuzzy_date year past}}` | `去年` / `前年` / `往年` / `往年同期` / `历年` / `上半年` | -| `{{fuzzy_date human future}}` | `过两天` / `等会儿` / `回头` / `赶明儿` | -| `{{fuzzy_date human past}}` | `前两三天` / `前几天` | - -> `season` 类型：`春天` / `夏天` / `秋天` / `冬天` / `春节前后` / `暑假` 等季节相关表达，方向参数对 season 不生效。 - ---- +| `fuzzy_date` | `下周` / `月底` / `去年` / `近日` | +| `fuzzy_date future` | `明年` / `下周` / `月末` / `过两天` | +| `fuzzy_date past` | `上周` / `去年` / `前两三天` / `近日` | +| `fuzzy_date day future` | `即日` / `改日` / `他日` / `来日` / `当日` | +| `fuzzy_date day past` | `近日` / `近来` / `最近` | +| `fuzzy_date week future` | `本周` / `下周` / `周末` / `未来一周` / `未来二周` | +| `fuzzy_date week past` | `上周` / `上上周` / `大上周` / `过去一周` / `过去二周` | +| `fuzzy_date month future` | `月初` / `月中` / `月末` / `上旬` / `中旬` / `下旬` / `未来一月` | +| `fuzzy_date month past` | `上月` / `过去一月` / `过去二月` / `过去三月` | +| `fuzzy_date year future` | `今年` / `明年` / `后年` / `年初` / `年中` / `年底` / `下半年` / `来年` | +| `fuzzy_date year past` | `去年` / `前年` / `往年` / `往年同期` / `历年` / `上半年` | +| `fuzzy_date human future` | `过两天` / `等会儿` / `回头` / `赶明儿` | +| `fuzzy_date human past` | `前两三天` / `前几天` | + +> `season` 类型：该参数被框架接受，但当前版本未配置独立的季节词汇列表，实际行为等同于不传类型参数（随机所有类型）。 ## 三、ChinaHolidayMocker — 节假日 @@ -124,81 +111,79 @@ nav_order: 5 | 规则 | 说明 | 示例结果 | |---|---|---| -| `{{holiday}}` | 随机公历或农历节假日 | `端午节` | -| `{{local_holiday}}` | 随机公历节假日 | `国庆节` | -| `{{chinese_holiday}}` | 随机农历节假日 | `腊八节` | -| `{{solr_term_holiday}}` | 随机二十四节气 | `清明` | +| `holiday` | 随机公历或农历节假日 | `端午节` | +| `local_holiday` | 随机公历节假日 | `国庆节` | +| `chinese_holiday` | 随机农历节假日 | `腊八节` | +| `solr_term_holiday` | 随机二十四节气 | `清明` | ### 3.2 未来节假日 | 规则 | 说明 | 示例结果 | |---|---|---| -| `{{future_holiday}}` | 当前时间之后的公历或农历节假日 | `中秋节` | -| `{{future_local_holiday}}` | 当前时间之后的公历节假日 | `国庆节` | -| `{{future_chinese_holiday}}` | 当前时间之后的农历节假日 | `七夕节` | -| `{{future_holiday 20261231}}` | 指定日期（`yyyyMMdd`）之后的节假日 | `春节` | -| `{{future_local_holiday 20260901}}` | 指定日期之后的公历节假日 | `国庆节` | -| `{{future_chinese_holiday 20260815}}` | 指定日期之后的农历节假日 | `中元节` | +| `future_holiday` | 当前时间之后的公历或农历节假日 | `中秋节` | +| `future_local_holiday` | 当前时间之后的公历节假日 | `国庆节` | +| `future_chinese_holiday` | 当前时间之后的农历节假日 | `七夕节` | +| `future_holiday 20261231` | 指定日期（`yyyyMMdd`）之后的节假日 | `春节` | +| `future_local_holiday 20260901` | 指定日期之后的公历节假日 | `国庆节` | +| `future_chinese_holiday 20260815` | 指定日期之后的农历节假日 | `中元节` | ### 3.3 过去节假日 | 规则 | 说明 | |---|---| -| `{{past_holiday}}` | 当前时间之前的公历或农历节假日 | -| `{{past_local_holiday}}` | 当前时间之前的公历节假日 | -| `{{past_chinese_holiday}}` | 当前时间之前的农历节假日 | -| `{{past_holiday 20260101}}` | 指定日期（`yyyyMMdd`）之前的节假日 | -| `{{past_local_holiday 20260601}}` | 指定日期之前的公历节假日 | -| `{{past_chinese_holiday 20260601}}` | 指定日期之前的农历节假日 | +| `past_holiday` | 当前时间之前的公历或农历节假日 | +| `past_local_holiday` | 当前时间之前的公历节假日 | +| `past_chinese_holiday` | 当前时间之前的农历节假日 | +| `past_holiday 20260101` | 指定日期（`yyyyMMdd`）之前的节假日 | +| `past_local_holiday 20260601` | 指定日期之前的公历节假日 | +| `past_chinese_holiday 20260601` | 指定日期之前的农历节假日 | ### 3.4 区间节假日 | 规则 | 说明 | |---|---| -| `{{between_holiday 20260101 20261231}}` | 指定日期区间内的公历或农历节假日 | -| `{{between_local_holiday 20260101 20261231}}` | 指定区间内的公历节假日 | -| `{{between_chinese_holiday 20260101 20261231}}` | 指定区间内的农历节假日 | +| `between_holiday 20260101 20261231` | 指定日期区间内的公历或农历节假日 | +| `between_local_holiday 20260101 20261231` | 指定区间内的公历节假日 | +| `between_chinese_holiday 20260101 20261231` | 指定区间内的农历节假日 | > 日期参数格式均为 `yyyyMMdd`，如 `20261001`。 ---- - ## 四、ChinaAddressMocker — 中国行政区划 > 类名：`ChinaAddressMocker`，触发条件：规则名为 `province` / `city` / `area` / `street`（精确匹配） 支持层级：**省 → 市 → 区/县 → 街道/乡镇**，不支持村级别。香港、澳门、台湾不支持街道级别。 -### 4.1 省份 `{{province}}` +### 4.1 省份 `province` | 规则 | 说明 | 示例结果 | |---|---|---| -| `{{province}}` | 随机省份（含自治区、直辖市、特别行政区） | `广东省` | +| `province` | 随机省份（含自治区、直辖市、特别行政区） | `广东省` | -### 4.2 城市 `{{city}}` +### 4.2 城市 `city` | 规则 | 说明 | 示例结果 | |---|---|---| -| `{{city}}` | 随机地级市 | `成都市` | -| `{{city 四川省}}` | 四川省下辖的随机城市 | `绵阳市` | -| `{{city 内蒙古}}` | 支持省份简称（自动转全称） | `呼和浩特市` | +| `city` | 随机地级市 | `成都市` | +| `city 四川省` | 四川省下辖的随机城市 | `绵阳市` | +| `city 内蒙古` | 支持省份简称（自动转全称） | `呼和浩特市` | -### 4.3 区/县 `{{area}}` +### 4.3 区/县 `area` | 规则 | 说明 | 示例结果 | |---|---|---| -| `{{area}}` | 随机区/县 | `武侯区` | -| `{{area 四川省}}` | 四川省下辖的随机区/县 | `天府新区` | -| `{{area 四川省 成都市}}` | 成都市下辖的随机区/县 | `锦江区` | +| `area` | 随机区/县 | `武侯区` | +| `area 四川省` | 四川省下辖的随机区/县 | `天府新区` | +| `area 四川省 成都市` | 成都市下辖的随机区/县 | `锦江区` | -### 4.4 街道/乡镇 `{{street}}` +### 4.4 街道/乡镇 `street` | 规则 | 说明 | 示例结果 | |---|---|---| -| `{{street}}` | 随机街道/乡镇 | `九眼桥街道` | -| `{{street 四川省}}` | 四川省下辖的随机街道 | `双桂街道` | -| `{{street 四川省 成都市}}` | 成都市下辖的随机街道 | `望江路街道` | -| `{{street 四川省 成都市 武侯区}}` | 武侯区下辖的随机街道 | `玉林街道` | +| `street` | 随机街道/乡镇 | `九眼桥街道` | +| `street 四川省` | 四川省下辖的随机街道 | `双桂街道` | +| `street 四川省 成都市` | 成都市下辖的随机街道 | `望江路街道` | +| `street 四川省 成都市 武侯区` | 武侯区下辖的随机街道 | `玉林街道` | ### 4.5 省份简称映射 @@ -214,57 +199,51 @@ nav_order: 5 | `香港` | `香港特别行政区` | | `澳门` | `澳门特别行政区` | ---- - ## 五、ChinaPoiMocker — 中国景区 POI > 类名：`ChinaPoiMocker`，触发条件：规则名为 `scenic`（精确匹配） | 规则 | 说明 | 示例结果 | |---|---|---| -| `{{scenic}}` | 随机中国景区 | `故宫博物院` | -| `{{scenic 四川省}}` | 四川省随机景区 | `九寨沟风景区` | -| `{{scenic 四川省 成都市}}` | 成都市随机景区 | `大熊猫繁育研究基地` | - ---- +| `scenic` | 随机中国景区 | `故宫博物院` | +| `scenic 四川省` | 四川省随机景区 | `九寨沟风景区` | +| `scenic 四川省 成都市` | 成都市随机景区 | `大熊猫繁育研究基地` | ## 六、NumberMocker — 数字 > 类名：`NumberMocker`，触发条件：规则名包含 `int` 或 `float`（大小写不敏感） -### 6.1 整数 `{{int}}` +### 6.1 整数 `int` 默认范围：0~100。 | 规则 | 说明 | 示例结果 | |---|---|---| -| `{{int}}` | 0~100 内随机整数（默认） | `42` | -| `{{int 10}}` | 10~100 内随机整数 | `73` | -| `{{int 1 10}}` | 1~10 内随机整数 | `7` | -| `{{int 100 999}}` | 100~999 内随机整数 | `528` | +| `int` | 0~100 内随机整数（默认） | `42` | +| `int 10` | 10~100 内随机整数 | `73` | +| `int 1 10` | 1~10 内随机整数 | `7` | +| `int 100 999` | 100~999 内随机整数 | `528` | -### 6.2 小数 `{{float}}` +### 6.2 小数 `float` 默认范围：0.0~100.0。 | 规则 | 说明 | 示例结果 | |---|---|---| -| `{{float}}` | 0.0~100.0 内随机小数（默认） | `37.82` | -| `{{float 0.5}}` | 0.5~100.0 内随机小数 | `62.14` | -| `{{float 0.5 5.0}}` | 0.5~5.0 内随机小数 | `3.14` | -| `{{float 1.0 10.0}}` | 1.0~10.0 内随机小数 | `6.78` | +| `float` | 0.0~100.0 内随机小数（默认） | `37.82` | +| `float 0.5` | 0.5~100.0 内随机小数 | `62.14` | +| `float 0.5 5.0` | 0.5~5.0 内随机小数 | `3.14` | +| `float 1.0 10.0` | 1.0~10.0 内随机小数 | `6.78` | > **类型自动推断**：两个参数均为整数时输出整数，任一参数含小数点时输出小数。 ---- - ## 七、综合使用示例 ``` // 多种 Mocker 混合使用的 query 模板： -"{{future_date 3 14 yyyy-MM-dd}} 从 {{city 四川省}} 到 {{city 广东省}}， -帮我订 {{holiday}} 前后的机票， -价格 {{int 300 2000}} 元左右，{{fuzzy_date week future}}出发" +"future_date 3 14 yyyy-MM-dd 从 city 四川省 到 city 广东省， +帮我订 holiday 前后的机票， +价格 int 300 2000 元左右，fuzzy_date week future出发" // 示例替换结果： "2026-06-05 从 绵阳市 到 广州市， @@ -272,8 +251,6 @@ nav_order: 5 价格 856 元左右，下周出发" ``` ---- - ## 八、sameMock — 同名占位符控制 当同一条数据中出现**多个相同规则**的占位符时，通过 `sameMock` 控制是否生成相同值： @@ -294,15 +271,13 @@ MockDataLoaderWrapper mockWrapper = new MockDataLoaderWrapper( ``` // sameMock=false（默认，推荐往返场景）： -// 输入： "帮我订从{{city}}到{{city}}的机票" +// 输入： "帮我订从city到city的机票" // 输出： "帮我订从北京到上海的机票" ✓ 两个城市不同 // sameMock=true： // 输出： "帮我订从北京到北京的机票" ✗ 两个城市相同（通常不合理） ``` ---- - ## 九、自定义 Mocker 实现 `Mocker` 接口，在 `MockDataLoaderWrapper` 中注册即可： @@ -312,7 +287,7 @@ public class FlightMocker implements Mocker { @Override public boolean support(String ruleName, List ruleParams) { - return "flight".equals(ruleName); // 响应 {{flight}} 和 {{flight 参数}} 规则 + return "flight".equals(ruleName); // 响应 flight 和 flight 参数 规则 } @Override @@ -342,7 +317,7 @@ MockDataLoaderWrapper mockWrapper = new MockDataLoaderWrapper() { }; // 使用： -// 输入： "帮我查{{flight}}航班的剩余座位" +// 输入： "帮我查flight航班的剩余座位" // 输出： "帮我查CA7823航班的剩余座位" ``` @@ -352,31 +327,29 @@ MockDataLoaderWrapper mockWrapper = new MockDataLoaderWrapper() { mockWrapper.addMockers(new FlightMocker(), new HotelBrandMocker(), new CuisineMocker()); ``` ---- - ## 十、快速规则速查 | 分类 | 规则 | 示例结果 | |---|---|---| -| **精确日期** | `{{date}}` | `2026-05-26 10:30:00` | -| | `{{date yyyy-MM-dd}}` | `2026-05-26` | -| | `{{future_date 3 14}}` | `2026-06-05 10:30:00` | -| | `{{future_date 3 14 yyyy-MM-dd}}` | `2026-06-05` | -| | `{{past_date 14 365}}` | `2026-01-15 10:30:00` | -| **模糊日期** | `{{fuzzy_date}}` | `下周` | -| | `{{fuzzy_date week future}}` | `下周` / `周末` | -| | `{{fuzzy_date year past}}` | `去年` / `前年` | -| | `{{fuzzy_date human future}}` | `过两天` / `赶明儿` | -| **节假日** | `{{holiday}}` | `端午节` | -| | `{{future_holiday}}` | `中秋节` | -| | `{{between_holiday 20260101 20261231}}` | `元宵节` | -| | `{{solr_term_holiday}}` | `清明` | -| **行政区划** | `{{province}}` | `广东省` | -| | `{{city}}` / `{{city 四川省}}` | `成都市` | -| | `{{area 四川省 成都市}}` | `武侯区` | -| | `{{street 四川省 成都市 武侯区}}` | `玉林街道` | -| **景区** | `{{scenic}}` | `故宫博物院` | -| | `{{scenic 四川省 成都市}}` | `大熊猫繁育研究基地` | -| **数字** | `{{int 1 100}}` | `42` | -| | `{{float 0.5 5.0}}` | `3.14` | +| **精确日期** | `date` | `2026-05-26 10:30:00` | +| | `date yyyy-MM-dd` | `2026-05-26` | +| | `future_date 3 14` | `2026-06-05 10:30:00` | +| | `future_date 3 14 yyyy-MM-dd` | `2026-06-05` | +| | `past_date 14 365` | `2026-01-15 10:30:00` | +| **模糊日期** | `fuzzy_date` | `下周` | +| | `fuzzy_date week future` | `下周` / `周末` | +| | `fuzzy_date year past` | `去年` / `前年` | +| | `fuzzy_date human future` | `过两天` / `赶明儿` | +| **节假日** | `holiday` | `端午节` | +| | `future_holiday` | `中秋节` | +| | `between_holiday 20260101 20261231` | `元宵节` | +| | `solr_term_holiday` | `清明` | +| **行政区划** | `province` | `广东省` | +| | `city` / `city 四川省` | `成都市` | +| | `area 四川省 成都市` | `武侯区` | +| | `street 四川省 成都市 武侯区` | `玉林街道` | +| **景区** | `scenic` | `故宫博物院` | +| | `scenic 四川省 成都市` | `大熊猫繁育研究基地` | +| **数字** | `int 1 100` | `42` | +| | `float 0.5 5.0` | `3.14` | diff --git a/docs/user-guide/overview.md b/docs/user-guide/overview.md index dbda529..bd42962 100644 --- a/docs/user-guide/overview.md +++ b/docs/user-guide/overview.md @@ -3,6 +3,7 @@ layout: default title: 概述与快速开始 parent: 用户指南 nav_order: 1 +has_toc: true --- # 概述与快速开始 @@ -38,7 +39,6 @@ EvalKit Framework 是一个基于 Java 的 **自动化 AI 评测框架**，以 D > 最新版本见 [发版历史](../changelog.md) ---- ## 整体架构 @@ -56,7 +56,6 @@ Begin（全局配置） └─ End（收尾操作） ``` ---- ## 快速开始 @@ -205,7 +204,6 @@ public class QuickStartDemo { {"passRate":1.0,"avgScore":1.0,"completionSuccessRate":1.0,...} ``` ---- ## 节点连接规则 diff --git a/docs/user-guide/querygen.md b/docs/user-guide/querygen.md index ef292bc..53ebda1 100644 --- a/docs/user-guide/querygen.md +++ b/docs/user-guide/querygen.md @@ -3,6 +3,7 @@ layout: default title: Query 生成器（QueryGenerator） parent: 用户指南 nav_order: 6 +has_toc: true --- # Query 生成器（QueryGenerator） @@ -19,7 +20,6 @@ List generate(); 调用后返回一批生成好的 Query 字符串列表。 ---- ## 接口定义 @@ -29,7 +29,6 @@ public interface QueryGenerator { } ``` ---- ## 内置实现 @@ -89,7 +88,6 @@ EvalCaseDataGenerator generator = new EvalCaseDataGenerator(config); | `genCount` | int | 1 | 每次生成 Query 的数量 | | `fillEmptyStringOnMockFail` | boolean | false | Mock 规则执行失败时，是否用空字符串填充（false 则抛异常） | ---- ### 2. PromptBasedQueryGenerator（基于大模型生成） @@ -140,7 +138,6 @@ QueryGenerator queryGenerator = new PromptBasedQueryGenerator(config); - 不得出现符号、emoji - 输出纯文本，一行一条，不加序号 ---- ## 自定义 QueryGenerator @@ -184,7 +181,6 @@ public class FileBasedQueryGenerator implements QueryGenerator { } ``` ---- ## 使用场景对比 @@ -194,7 +190,6 @@ public class FileBasedQueryGenerator implements QueryGenerator { | `PromptBasedQueryGenerator` | 需要语义自然、贴近真实用户的 Query | 质量高，但需要调用 LLM，耗时较长 | | 自定义实现 | 从现有数据集中采样，或有特殊生成逻辑 | 灵活，完全自定义 | ---- ## 完整使用示例 diff --git a/docs/user-guide/reporter.md b/docs/user-guide/reporter.md index 4fcbdfc..4023a38 100644 --- a/docs/user-guide/reporter.md +++ b/docs/user-guide/reporter.md @@ -3,6 +3,7 @@ layout: default title: 结果上报器（Reporter） parent: 用户指南 nav_order: 13 +has_toc: true --- # 结果上报器（Reporter） @@ -13,7 +14,6 @@ nav_order: 13 `Reporter` 是 EvalKit 框架工作流中的最后一个处理节点，负责将评测结果以各种形式输出：打印到控制台、写入文件（Excel/CSV/JSON/HTML）、存入数据库、或发送到远程 API。 ---- ## 类继承关系 @@ -29,7 +29,6 @@ Reporter（抽象基类） └── ApiReporter（抽象） HTTP API 上报基类 ``` ---- ## 生命周期钩子 @@ -44,7 +43,6 @@ Reporter（抽象基类） > ⚠️ 重要：上报过程中抛出的异常**不会阻塞**整个工作流的运行，框架会记录错误日志后继续执行。 ---- ## 上报数据结构（ReportData） @@ -55,7 +53,6 @@ Reporter（抽象基类） | `dataItems` | `List` | 所有评测数据项，包含输入、接口返回结果、评分等 | | `countResultMap` | `Map` | 各统计器的输出结果，key 为统计器名称，value 为 JSON 字符串 | ---- ## 内置实现详解 @@ -83,7 +80,6 @@ Workflow reportWorkflow = Workflow.builder() .build(); ``` ---- ### 2. ExcelReporter — Excel 文件上报 @@ -118,7 +114,6 @@ Workflow reportWorkflow = Workflow.builder() .build(); ``` ---- ### 3. CsvReporter — CSV 文件上报 @@ -140,7 +135,6 @@ new CsvReporter("my_eval_report", "\t", "output/"); | `delimiter` | 分隔符 | `,`（逗号） | | `parentDir` | 输出文件夹路径 | `attachments` | ---- ### 4. JsonReporter — JSON 文件上报 @@ -164,7 +158,6 @@ new JsonReporter("my_eval_report", "output/json"); > 💡 `JsonReporter` 的输出格式与 `JsonFileDebugger` 的输入格式完全匹配，可以配合使用实现"生产数据→保存→调试重播"的工作流。 ---- ### 5. HtmlReporter — HTML 可视化报告 @@ -202,7 +195,6 @@ Workflow reportWorkflow = Workflow.builder() .build(); ``` ---- ### 6. JdbcReport — 数据库上报（抽象类） @@ -243,7 +235,6 @@ public class MyMysqlReporter extends JdbcReport { } ``` ---- ### 7. ApiReporter — HTTP API 上报（抽象类） @@ -296,7 +287,6 @@ public class MyApiReporter extends ApiReporter { } ``` ---- ## 自定义上报器 @@ -335,7 +325,6 @@ public class MyCustomReporter extends Reporter { } ``` ---- ## 多个上报器同时使用 @@ -350,7 +339,6 @@ Workflow reportWorkflow = Workflow.builder() .build(); ``` ---- ## 与统计器（Counter）配合使用 @@ -365,7 +353,6 @@ Workflow reportWorkflow = Workflow.builder() .build(); ``` ---- ## 文件输出路径说明 diff --git a/docs/user-guide/scorer.md b/docs/user-guide/scorer.md index b2f3c68..e4dd308 100644 --- a/docs/user-guide/scorer.md +++ b/docs/user-guide/scorer.md @@ -3,13 +3,13 @@ layout: default title: 评估器（Scorer） parent: 用户指南 nav_order: 10 +has_toc: true --- # 评估器（Scorer） 评估器是框架的核心节点，负责对接口返回结果进行**打分**。多个评估器可以并行执行，最终分数由 `Begin` 节点配置的打分策略汇总。 ---- ## 体系结构 @@ -25,7 +25,6 @@ Scorer（抽象基类） └── DifyWorkflowScorer（抽象） 调用 Dify 工作流打分 ``` ---- ## Scorer（基类） @@ -100,7 +99,6 @@ Scorer keywordScorer = new Scorer( }; ``` ---- ## VectorSimilarityScorer @@ -137,7 +135,6 @@ VectorSimilarityScorer similarityScorer = new VectorSimilarityScorer( }; ``` ---- ## PromptBasedScorer @@ -199,7 +196,6 @@ PromptBasedScorer customLLMScorer = new PromptBasedScorer( }; ``` ---- ## AnswerRelevancyScorer @@ -235,7 +231,6 @@ AnswerRelevancyScorer relevancyScorer = new AnswerRelevancyScorer( - 0.5~0.7 分：基本回应但有冗余 - 0.8~1.0 分：精准、无冗余 ---- ## SemanticConsistencyScorer @@ -267,7 +262,6 @@ SemanticConsistencyScorer consistencyScorer = new SemanticConsistencyScorer( }; ``` ---- ## SecurityScorer @@ -294,7 +288,6 @@ SecurityScorer securityScorer = new SecurityScorer( }; ``` ---- ## GSBScorer @@ -332,7 +325,6 @@ GSBScorer gsbScorer = new GSBScorer( }; ``` ---- ## DifyWorkflowScorer @@ -384,7 +376,6 @@ DifyWorkflowScorer difyScorer = new DifyWorkflowScorer( }; ``` ---- ## RubricBasedScorer @@ -597,7 +588,6 @@ RubricBasedScorerConfig config = RubricBasedScorerConfig.builder() | `criteria_reasonings` | `Map` | 各维度 CoT 推理过程 | | `merge_strategy` | `String` | 本次使用的合并策略名 | ---- ## MultiCheckerBasedScorer @@ -621,7 +611,6 @@ MultiCheckerBasedScorer multiChecker = new MultiCheckerBasedScorer( }; ``` ---- ## 打分策略 @@ -664,7 +653,6 @@ Scorer safetyScorer = new Scorer( .build() ) { ... }; ---- ## RubricBasedScorer（量规评估器） diff --git a/docs/user-guide/summary.md b/docs/user-guide/summary.md index c7a11bf..a87bf00 100644 --- a/docs/user-guide/summary.md +++ b/docs/user-guide/summary.md @@ -7,8 +7,6 @@ nav_order: 16 # EvalKit Framework 全模块汇总导览 -> 版本：1.4.x | 最后更新：2026-06-04 - --- ## 一、框架全景 @@ -43,7 +41,7 @@ QueryGenerator | | `JdbcDataLoader` | 从 MySQL 等数据库加载（抽象） | | | | `MultiDataLoader` | 合并多个加载器的数据 | | | **数据装饰器** | `DataLoaderWrapper` | 数据加载后的增强处理基类 | [dataloader-wrapper.md](./dataloader-wrapper.md) | -| | `MockDataLoaderWrapper` | 替换 `{{占位符}}` 为随机 Mock 值 | | +| | `MockDataLoaderWrapper` | 替换 `占位符` 为随机 Mock 值 | | | | `PromptDataLoaderWrapper` | 用 LLM 对字段进行增强（抽象） | | | | `PolishDataLoaderWrapper` | 将 query 改写为口语化表达（抽象） | | | **Query 生成器** | `QueryGenerator`（接口） | 生成测试用 Query 字符串 | [querygen.md](./querygen.md) | @@ -248,31 +246,31 @@ JsonFileDebugger（注入上次结果） ## 六、内置 Mocker 规则速查 -框架内置 6 种 Mocker，占位符格式统一为 `{{规则名 参数1 参数2 ...}}`，详细规则说明见 [mocker.md](./mocker.md)。 +框架内置 6 种 Mocker，占位符格式为`双花括号包裹规则名和参数`，下表中规则列省略花括号，实际使用时需加上。详细规则说明见 [mocker.md](./mocker)。 | 分类 | 常用规则示例 | 示例结果 | |---|---|---| -| **精确日期** | `{{date}}` | `2026-05-26 10:30:00` | -| | `{{date yyyy-MM-dd}}` | `2026-05-26` | -| | `{{future_date 3 14}}` | `2026-06-03 10:30:00` | -| | `{{future_date 3 14 yyyy-MM-dd}}` | `2026-06-03` | -| | `{{past_date 14 365}}` | `2026-01-15 10:30:00` | -| **模糊日期** | `{{fuzzy_date}}` | `下周` / `月底` / `去年` | -| | `{{fuzzy_date week future}}` | `下周` / `周末` / `未来一周` | -| | `{{fuzzy_date year past}}` | `去年` / `前年` / `往年` | -| | `{{fuzzy_date human future}}` | `过两天` / `赶明儿` | -| **节假日** | `{{holiday}}` | `端午节` | -| | `{{future_holiday}}` | `中秋节` | -| | `{{solr_term_holiday}}` | `清明` | -| | `{{between_holiday 20260101 20261231}}` | `元宵节` | -| **行政区划** | `{{province}}` | `广东省` | -| | `{{city}}` / `{{city 四川省}}` | `成都市` | -| | `{{area 四川省 成都市}}` | `武侯区` | -| | `{{street 四川省 成都市 武侯区}}` | `玉林街道` | -| **景区 POI** | `{{scenic}}` | `故宫博物院` | -| | `{{scenic 四川省 成都市}}` | `大熊猫繁育研究基地` | -| **数字** | `{{int 1 100}}` | `42` | -| | `{{float 0.5 5.0}}` | `3.14` | +| **精确日期** | `date` | `2026-05-26 10:30:00` | +| | `date yyyy-MM-dd` | `2026-05-26` | +| | `future_date 3 14` | `2026-06-03 10:30:00` | +| | `future_date 3 14 yyyy-MM-dd` | `2026-06-03` | +| | `past_date 14 365` | `2026-01-15 10:30:00` | +| **模糊日期** | `fuzzy_date` | `下周` / `月底` / `去年` | +| | `fuzzy_date week future` | `下周` / `周末` / `未来一周` | +| | `fuzzy_date year past` | `去年` / `前年` / `往年` | +| | `fuzzy_date human future` | `过两天` / `赶明儿` | +| **节假日** | `holiday` | `端午节` | +| | `future_holiday` | `中秋节` | +| | `solr_term_holiday` | `清明` | +| | `between_holiday 20260101 20261231` | `元宵节` | +| **行政区划** | `province` | `广东省` | +| | `city` / `city 四川省` | `成都市` | +| | `area 四川省 成都市` | `武侯区` | +| | `street 四川省 成都市 武侯区` | `玉林街道` | +| **景区 POI** | `scenic` | `故宫博物院` | +| | `scenic 四川省 成都市` | `大熊猫繁育研究基地` | +| **数字** | `int 1 100` | `42` | +| | `float 0.5 5.0` | `3.14` | ---