问答集评测与 CLI 调优闭环

将企业题库程序化导入为不可变版本、绑定为知识库标准答案源,并用 apemind CLI 驱动「改配置 → 跑固定题集 → 对比归因 → 留出验证」的持续调优闭环。完整接口参数见 API 参考。

权限与并发契约(ETag / If-Match)

问答集接口挂在 /api/v2/datasets 下。集成前先确认两条硬性契约:

两步批量导入(Preview → Commit)与发布

大批量 CSV / JSONL / Excel 题库通过「上传预演 + 令牌确认」写入草稿,确保写入前先发现格式错误和重复 external_id:

  1. 读取部署上限

    先调用 GET /api/v2/datasets/capabilities 获取当前部署的文件大小(默认 10 MiB)、单集最大题数(5,000 题)与版本上限(50 个)。

  2. 上传预览并校验行级结果

    上传原件后调用预览端点(支持 mode: "append" | "upsert_by_external_id" | "replace_all"),拿到 preview_id 与冲突/错误汇总。未确认的原件与预览 24 小时过期。

  3. 携带 If-Match 提交确认,并发布版本

    确认无阻断错误后携带当前 ETag 与 preview_id 提交导入;全部调整完成后调用 POST /api/v2/datasets/{dataset_id}/versions 发布不可变快照。

单题新增没有通用幂等键,网络超时结果不明时应先回读 GET /api/v2/datasets/{dataset_id}/items 核对,避免重复写入。

绑定为知识库的问答源(QA Source)

已发布版本的问答集可直接绑定到同组织知识库作为高优先标准答案库(POST /api/v2/collections/{kb_id}/qa-bindings):

外部评测运行与过程指标回传

除了由 ApeMind 平台直接代答(driver=system),也可以在外部评测管线中拉取固定版本题库,再把外部模型或自有 Agent 的回答与过程指标写回 ApeMind 统一生成对比报告与公开分享页:

metrics 键 类型 含义
tool_calls / tool_errors 整数 总工具调用次数 / 报错次数
tool_rounds 整数 「思考 → 调用工具 → 读取结果」循环轮数
total_tokens 整数 该题所有模型调用输入输出 Token 之和
sources_seen / sources_read 整数 召回候选片段数 / 实际展开核对的片段数
queue_ms 整数 提交后排队等待耗时(毫秒)
tools_by_name 对象 工具名 → 调用次数映射
trace 数组 前 60 次调用摘要,每项 {tool, summary, error}

评测完成后,可通过 POST /api/v2/datasets/{dataset_id}/evaluations/{run_id}/report/share 生成冻结的免登录报告链接(支持 scope: "full" | "summary",summary 自动剥离题目原文、答案与内部 ID);归档问答集会同步撤销名下全部报告分享链接。

基于 apemind CLI 的 Agent 调优闭环

借助官方命令行工具(tools/apemind-cli),可以把 Agent 配置变更、固定题集评测与结果归因接入自动化脚本或 CI 流水线。CLI 负责安全读写与阻塞等待,持续迭代策略与留出集验证由你的编排脚本控制。

  1. 跑出基线评测(固定版本)

    使用 --wait 阻塞直到评测进入终态;超时返回非零退出码但不会中止服务端运行,重新执行 dataset eval get ... --wait 即可续等。注意评测期间不要改动目标 Agent,否则 configs[] 会记录多份配置摘要。

    # 发起基线评测并等待完成(省略 --version 时使用最新已发布版本)
    BASE_RUN_ID=$(apemind dataset eval create "${DATASET_ID}" \
      --bot "${AGENT_ID}" \
      --workspace "${APEMIND_ORG_ID}" \
      --confirm --wait --timeout 30m --json | jq -r '.id')
    
    # 筛出失败题与低分题及其 turn_id,定位根因
    apemind dataset eval get "${DATASET_ID}" "${BASE_RUN_ID}" \
      --workspace "${APEMIND_ORG_ID}" --json \
      --jq '.results[] | select(.status=="failed" or (.judgement.answers.correct.noul // 1) < 0.5) | {item_id, status, error, turn_id}'
  2. 读取声明式配置并预演候选修改

    导出当前 Agent 声明(或只写一份局部 merge-patch 文件),先用 --dry-run 核对 changes、grants 与 status.conditions,再加 --confirm 应用:

    # 方式 A:局部修改(推荐,只传改动字段)
    apemind agent update "${AGENT_ID}" \
      --input candidate-patch.json \
      --workspace "${APEMIND_ORG_ID}" --dry-run
    
    apemind agent update "${AGENT_ID}" \
      --input candidate-patch.json \
      --workspace "${APEMIND_ORG_ID}" --confirm
    
    # 方式 B:整份导出、修改并按 revision 安全回写
    apemind agent get "${AGENT_ID}" --workspace "${APEMIND_ORG_ID}" > agent.json
    # 编辑 agent.json 后:
    apemind agent apply --input agent.json --workspace "${APEMIND_ORG_ID}" --confirm
  3. 对候选配置发起复测并做归因对比

    对同一固定题集版本发起新评测,然后用 dataset eval compare 一次查看逐题升降与配置差异:

    # 对候选配置跑同一题集版本
    CANDIDATE_RUN_ID=$(apemind dataset eval create "${DATASET_ID}" \
      --bot "${AGENT_ID}" \
      --workspace "${APEMIND_ORG_ID}" \
      --confirm --wait --timeout 30m --json | jq -r '.id')
    
    # 对比基线与候选(检查 config_changes 确认差异可归因于本次配置改动)
    apemind dataset eval compare "${DATASET_ID}" "${BASE_RUN_ID}" "${CANDIDATE_RUN_ID}" \
      --workspace "${APEMIND_ORG_ID}" --json

    对比结果中的 config_changes 会列出两次运行发生变化的模块(如 agent.completion、tools、skills);若任一侧运行中途混用了多份配置,config_changes 为 null,此时不应将分数变化归因于配置改动。如果仅有个别题目因网络抖动失败,可用 apemind dataset eval retry "${DATASET_ID}" "${CANDIDATE_RUN_ID}" --failed --confirm --wait 补跑。

  4. 单题深度复现与留出验证

    若需对某道边界题做快速回归,直接通过 CLI 阻塞等待单轮 Turn(apemind turn wait "${TURN_ID}" --chat-id "${CHAT_ID}" --workspace "${APEMIND_ORG_ID}" --timeout 10m)。切勿只在同一开发集上反复拟合——选定最终候选后,务必在独立留出题集上再跑一次 dataset eval create --wait 验收,并将运行 ID、题集版本、决策模型与配置差异一并归档。

自动评分与留出纪律

创建评测时默认 auto_judge=true:省略 --decision-model 会采用目标 Agent 配置的决策模型,若 Agent 未配置则会返回 422 decision_model_required。自动化调优脚本只应修改候选 Agent 配置,绝不允许修改评分标准或留出题集,也不要把含敏感客户数据的完整原始响应写入公开日志。

下一步