企业官网建设流程全解析

• AI Agent
• AI 应用
• 后端
• 前端
• 大模型
• RAG

评测集（Evaluation Set）是 Nexent 智能体评估体系的基石——一组结构化的测试用例，用于驱动对 Agent 的自动化评测。本文面向使用 Nexent 的开发者与评测工程师，系统讲解如何在智能体开发 > 智能体评估的评测集页签中完成 Excel 批量导入、AI 辅助用例生成、用例的增删改查与导出，并结合仓库源码解析导入解析、异步生成、数据校验与并发保护等底层实现，帮助读者快速搭建并长期维护高质量、可复用的 Agent 基准测试集。

评测集的核心概念与数据模型

在 Nexent 中，一条评测用例（case）至少必须包含一个问题（query）——即发送给智能体的用户输入。参考答案（answer）在数据层面是可选的，但对于答案准确性（Answer Accuracy）、回答完整性（Answer Completeness）和事实准确性（Factual Accuracy）这三类评估器而言至关重要，建议为需要精确打分的用例补齐参考答案。

从源码看，评测集与用例在数据库中由两张表承载（见 db_models.py）：

• evaluation_set_t（评测集元数据）：记录评测集名称、描述、来源文件名（source_filename）、用例总数（case_count）以及 AI 生成状态（generation_status：IDLE / GENERATING / DONE / FAILED）与进度（generation_progress，0-100）；
• evaluation_set_case_t（评测用例）：以 JSONB 存储inputs（用户输入）与label（参考答案等标签），并保存order_no（集内顺序）、session_id（多轮会话标识）与turn_order（会话内轮次，从 1 开始）。

用例在服务层被规范化为统一的字典结构（见 evaluation_set_service.py 中_build_normalized_case的实现）：

{ "inputs": {"query": "用户问题", "session_id": "s1", "request_id": "1"}, "label": {"answer": "参考答案"}, "session_id": "s1", "turn_order": "1", }

从 Excel 批量导入用例

操作路径

1. 进入智能体开发 > 智能体评估，打开评测集页签；
2. 点击上传，填写评测集名称（2～64 个字符）和可选描述；
3. 选择.xlsx或.xls文件上传；也可以先点击下载模板，用模板填写数据后再上传。

后端上传接口位于 evaluation_set_app.py 的POST /evaluation-sets/upload：支持一次上传多个文件，每个文件先校验扩展名（仅接受.xlsx/.xls）与大小（默认单文件不超过 20 MB，通过环境变量MAX_EVALUATION_SET_FILE_SIZE_MB可调，见 const.py），随后统一解析并落库。

支持的列名与中英文表头

导入文件支持以下四个字段，中英文表头均可：

从 evaluation_set_excel_utils.py 的表头别名映射表可以确认解析器实际接受的写法远比文档更宽容：

• session_id：还接受sessionid、会话id、会话ID；
• request_id：还接受turn_order、turnorder、turn、请求顺序；
• query：还接受问题；
• answer：还接受reference_output、referenceoutput、expected_output、expectedoutput、答案。

此外，ASCII 表头大小写不敏感（如SESSION_ID、Query），表头末尾带必填标记*也会被自动容忍（如query*）。这些行为均有对应的单元测试覆盖（见 test_evaluation_set_excel_utils.py）。

模板与示例数据

下载模板（GET /evaluation-sets/template）生成的.xlsx文件布局为：

• 第 1 行：字段填写说明（中文模板注明「问题（必填*）」与各字段的选填/必填语义）；
• 第 2 行：中英文表头（会话ID | 请求顺序 | 问题 | 答案）；
• 第 3 行起：多轮会话示例数据，例如：

模板生成逻辑见 evaluation_set_excel_utils.py，其中「问题/query」列会被浅橙色高亮以提示必填。

解析规则与多轮会话要求

• 单轮用例：session_id与request_id留空即可；
• 多轮用例：同一会话内请求顺序必须连续递增（从 1 开始），系统会在创建评测集时校验，若顺序不连续将直接拒绝导入（见 evaluation_set_service.py）；
• 空行自动跳过，但任一数据行的query为空会报错（Row N: query is required）；
• 文件没有任何数据行或找不到表头行时导入失败；
• 数字单元格中的整数值会按整数解析（1不会变成1.0），详见 evaluation_set_excel_utils.py。

使用 AI 生成评测集

当没有现成测试数据时，可以让 AI 基于业务场景自动生成评测用例：

1. 在评测集页签中点击AI 生成评测集；
2. 填写场景描述并选择生成模型；
3. 选择将结果追加到已有评测集，或输入名称创建新的评测集；
4. 设置**生成数量（1～200 条）**并开始生成。

可选上下文：知识库 / Agent / 参考文档

为了让生成的用例更贴合真实业务，可提供以下上下文：

• 知识库：系统会先检索知识库内容作为素材，生成的用例会围绕知识库中的概念、术语和场景展开；
• Agent：将 Agent 的配置、工具、技能和子智能体等信息注入上下文，让用例覆盖 Agent 的真实能力面；
• 一个.docx参考文档：作为业务素材补充。

从 evaluation_set_service.py 的_do_kb_search可以看到知识库检索的完整链路：先解析知识库名称 → 调用 LLM 规划检索 query（evaluation_plan_kb_queries模板）→ 对每个 query 执行向量检索（ES 模式使用cosineSimilarity脚本打分，命中结果归一化为 0-1 后格式化）→ 将检索结果组装进生成提示词。若检索失败则优雅降级：仅凭场景描述和 Agent 配置继续生成，不会中断任务。

异步生成与状态流转

生成任务在后台异步执行，评测集列表会显示生成中（Generating）、就绪（Ready）或失败（Failed）状态。其底层实现要点（见 evaluation_set_app.py 与 evaluation_set_service.py）：

• 入口为POST /evaluation-sets/generate-cases-async，通过config_thread_manager提交到后台线程池执行；
• 生成流程：知识库检索（进度 0→8）→ 组装上下文与提示词（10）→ 调用 LLM 生成并解析（50）→ 逐条入库并上报进度（70→99）→ 完成后置为DONE（100）；
• LLM 输出按 JSON 数组解析（兼容 markdown 代码块包裹），缺inputs.query或label.answer的脏数据会被过滤；
• 若返回数量超过请求数量，只保留前count条；
• 生成失败时：新建的评测集会被整体清理删除，追加模式则只回滚本次生成追加的用例，不影响原有数据（_handle_generation_failure）；
• 服务重启后，处于GENERATING状态的“半成品”评测集会由 evaluation_set_db.py 的recover_interrupted_generations自动标记为FAILED并回滚追加用例。

AI 生成的提示词模板见 generate_cases_system_zh.yaml，其中约定了三类可评测的 answer 形态：标准答案（纯文本）、评分标准检查清单（【评分标准】+- [ ]逐项判定）和过程判定（【过程判定】+Step → 工具调用链路），并要求至少 30% 为应用或推理类问题。

重要提示：AI 生成的问题和参考答案可能存在遗漏或错误。在将其作为正式基准集使用前，请务必进行人工抽查与修正。

查看与维护用例

打开评测集的查看操作，可以：

• 按问题搜索用例（模糊匹配inputs.query字段，对应接口GET /evaluation-sets/{id}/cases?query=...）；
• 添加单条用例；
• 编辑问题、答案、会话 ID 和请求顺序；
• 删除单条或批量删除用例；
• 导出为 Excel（GET /evaluation-sets/{id}/export，导出格式与导入模板一致，可再次导入实现“导出→修改→回传”的往返维护）。

多轮会话的强一致性校验

维护多轮用例时，系统会强制保证会话内轮次连续：

• 新增用例时，turn_order必须等于该会话当前最大轮次 + 1，否则报错；
• 编辑用例时，若改动涉及session_id或turn_order，同样会校验连续性；
• 删除多轮用例只能从会话尾部删起（先删最后一轮），批量删除后剩余轮次也必须保持从 1 开始的连续序列，否则拒绝删除。

这些校验逻辑见 evaluation_set_service.py（add_evaluation_set_case_impl）、L311-L373（_validate_turn_continuity）与 L395-L473（删除及批量删除），对应的错误码包括AGENT_EVALUATION_TURN_ORDER_MISMATCH、AGENT_EVALUATION_TURN_DELETE_NOT_LAST和AGENT_EVALUATION_TURN_DELETE_NOT_CONTIGUOUS。

活跃评测任务对评测集的保护

如果评测集正被运行中（PENDING / RUNNING）的评估任务引用，系统会限制可能影响任务一致性的修改操作——增删改用例、追加生成用例乃至删除整个评测集都会被拦截，并返回AGENT_EVALUATION_SET_IN_USE（参见 evaluation_set_service.py 的count_active_runs_using_set与_check_set_not_in_use）。已完成（COMPLETED / FAILED）的任务不在此列，不会阻碍后续维护。

因此，对于需要长期维护、持续演进的基准集，建议：

1. 复制评测集或导出 Excel 备份后再进行大规模修改；
2. 用备份副本运行“变更验证”，确认新旧用例并存时的评测结果可对比；
3. 将基准集与临时实验集分开管理，避免实验性修改污染长期基准。

数据限制速查

以下是评测集相关的硬性限制（官方文档与 evaluation_limits.py、const.py 中的常量一一对应）：

从评测集到正式评估任务

评测集就绪后，即可在评估页中创建评估任务（任务创建、评估器配置与结果分析的完整流程，可参考同目录文档 create-task.md、evaluators.md 与 results.md）。评测集的价值在于复用与沉淀：通过 Excel 标准化导入与导出实现团队间共享，通过 AI 生成快速扩充覆盖面，再配合人工复核形成可信的基准资产，最终驱动 Agent 能力的可量化迭代。

• AI Agent
• AI 应用
• 后端
• 前端
• 大模型
• RAG