权限与并发契约(ETag / If-Match)
问答集接口挂在 /api/v2/datasets 下。集成前先确认两条硬性契约:
- 独立权限集:API Key 的
scope.tools或 OAuth scope 需要显式包含dataset.read/dataset.write/dataset.publish/dataset.archive/dataset.export(拥有知识库权限不代表拥有问答集权限;归档和删除均要求dataset.archive)。 - 乐观锁强制校验:读取目录、草稿题目与写入响应都会返回
ETag: "ds:<ID>:r<REVISION>"。所有草稿/目录修改、删除、发布与导入确认都必须携带对应的If-Match:缺少返回428,版本冲突返回412(冲突时须重读合并或重新预览,不要盲目覆盖)。 - 消费固定发布版本:草稿随时可变,且分页游标
next_cursor在 revision 变更后会失效;评测与问答源绑定只消费不可变的已发布版本(v1、v2…)。
两步批量导入(Preview → Commit)与发布
大批量 CSV / JSONL / Excel 题库通过「上传预演 + 令牌确认」写入草稿,确保写入前先发现格式错误和重复 external_id:
-
读取部署上限
先调用
GET /api/v2/datasets/capabilities获取当前部署的文件大小(默认 10 MiB)、单集最大题数(5,000 题)与版本上限(50 个)。 -
上传预览并校验行级结果
上传原件后调用预览端点(支持
mode: "append" | "upsert_by_external_id" | "replace_all"),拿到preview_id与冲突/错误汇总。未确认的原件与预览 24 小时过期。 -
携带
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):
- 版本策略:
version_policy: "pinned"锁定指定发布版本;"latest"在问答集发布新版本后自动重建问答向量并切换。 - 检索生效条件:绑定状态进入
ready后,MCP 工具search_knowledge会把命中的标准答案放入qa_items;词面命中直接查版本快照表,无需额外同步。 - 删除保护:问答集仍有任意知识库绑定时,
DELETE /api/v2/datasets/{dataset_id}返回409 dataset_bound_to_collections。先通过GET /api/v2/datasets/{dataset_id}/collection-bindings查清依赖并逐一解绑后再删除。
外部评测运行与过程指标回传
除了由 ApeMind 平台直接代答(driver=system),也可以在外部评测管线中拉取固定版本题库,再把外部模型或自有 Agent 的回答与过程指标写回 ApeMind 统一生成对比报告与公开分享页:
- 通过
PUT /api/v2/datasets/{dataset_id}/evaluations/{run_id}/results/{item_id}回传答案、latency_ms与可选的metrics对象。 - 只要
metrics包含下列标准键之一,评测报告(GET .../report或?format=json)就会自动渲染「解题过程」分析面板:
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 负责安全读写与阻塞等待,持续迭代策略与留出集验证由你的编排脚本控制。
-
跑出基线评测(固定版本)
使用
--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}' -
读取声明式配置并预演候选修改
导出当前 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 -
对候选配置发起复测并做归因对比
对同一固定题集版本发起新评测,然后用
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补跑。 -
单题深度复现与留出验证
若需对某道边界题做快速回归,直接通过 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 配置,绝不允许修改评分标准或留出题集,也不要把含敏感客户数据的完整原始响应写入公开日志。