知识库入库与检索编排

将企业文档程序化同步到 ApeMind 知识库,可靠跟踪解析与多通道索引状态机,并完成失败重建、检索验收与归档导出。所有参数字典见 API 参考。

创建与更新知识库

知识库的创建与配置修改统一走声明式配置接口(路径 /api/v2/workspaces/{org_id}/knowledge-bases/config);文档上传、状态查询、检索与重建继续使用历史兼容路径 /api/v2/collections/{kb_id}/...。

KB_ID=$(curl -fsS \
  -X POST "${APEMIND_BASE_URL}/api/v2/workspaces/${APEMIND_ORG_ID}/knowledge-bases/config" \
  -H "Authorization: Bearer ${APEMIND_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {"title": "制度与合同知识库", "description": "合规与业务流程文档"},
    "spec": {
      "enable_vector": true,
      "enable_fulltext": true,
      "enable_knowledge_graph": true,
      "enable_summary": false
    }
  }' | jq -r '.metadata.id')

创建前确认组织已在模型用途中配置 collection_embedding(向量)与 collection_completion(图谱/摘要),且组织配额有余量。

两步上传确认 vs 批量上传

ApeMind 提供两种上传模式,按文件数量与控制粒度选择:

模式 核心端点 适用场景与语义
两步暂存 + 确认(推荐大批量) POST /api/v2/collections/{kb_id}/documents/upload
POST /api/v2/collections/{kb_id}/documents/confirm
先逐文件上传到暂存态(不立即触发解析与扣费),全部传完并校验无误后一次 confirm 批量进入索引队列
单步直接创建 POST /api/v2/collections/{kb_id}/documents 小批量脚本或实时同步单篇文档,上传后立即入队解析与索引

两步上传示例:

# 1. 暂存上传(返回 document_id)
DOC_ID=$(curl -fsS \
  -X POST "${APEMIND_BASE_URL}/api/v2/collections/${KB_ID}/documents/upload" \
  -H "Authorization: Bearer ${APEMIND_API_KEY}" \
  -F "file=@./handbook.pdf" | jq -r '.document_id')

# 2. 确认入库,触发解析与多通道索引
curl -fsS \
  -X POST "${APEMIND_BASE_URL}/api/v2/collections/${KB_ID}/documents/confirm" \
  -H "Authorization: Bearer ${APEMIND_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["'"${DOC_ID}"'"]}'

文档与多通道索引状态机

文档确认后进入异步管线,调用方按 GET /api/v2/collections/{kb_id}/documents/{doc_id} 做有上限的退避轮询。不要只看整篇文档状态——每个已启用的索引通道都有独立状态字段:

字段 终态 / 关键值 判定规则
status PENDING → RUNNING → COMPLETE / FAILED 整篇文档入库汇总状态;单通道已 ACTIVE 时该通道即可提前检索
vector_index_status ACTIVE / FAILED 向量索引;未启用时为空,切勿把空值当失败
fulltext_index_status ACTIVE / FAILED 全文倒排索引
graph_index_status ACTIVE / FAILED 知识图谱索引;附带渐进字段 extraction_status:partial(高优窗口已可查)→ complete(全量完成),completed_windows / total_windows 仅作进度展示
summary_index_status / vision_index_status ACTIVE / FAILED 摘要与图片视觉索引(仅启用时有效)

失败重建编排

当上游模型瞬时抖动或解析服务恢复后,可针对单篇文档的指定通道,或整个知识库的全部失败通道发起重建:

# 仅重建单篇文档的指定通道(可选 VECTOR / FULLTEXT / GRAPH / SUMMARY / VISION)
curl -fsS \
  -X POST "${APEMIND_BASE_URL}/api/v2/collections/${KB_ID}/documents/${DOC_ID}/rebuild_indexes" \
  -H "Authorization: Bearer ${APEMIND_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"index_types": ["VECTOR", "FULLTEXT"]}'

# 批量重建整个知识库中所有失败的索引
curl -fsS \
  -X POST "${APEMIND_BASE_URL}/api/v2/collections/${KB_ID}/rebuild_failed_indexes" \
  -H "Authorization: Bearer ${APEMIND_API_KEY}"

不要在未排查根因的情况下无限重试重建——若是模型未绑定、配额超限或解析服务不可用,请先查看 failure_reason 或在平台管理「运维 › 索引死信」处理根因。

底层检索与问答源绑定

索引进入 ACTIVE 后,可通过底层检索接口直接验证召回质量(items: [] 表示检索成功但无命中,不同于鉴权或索引错误):

curl -fsS \
  -X POST "${APEMIND_BASE_URL}/api/v2/collections/${KB_ID}/searches" \
  -H "Authorization: Bearer ${APEMIND_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "合同解除条件是什么?",
    "vector_search": {"topk": 5},
    "fulltext_search": {"topk": 5},
    "save_to_history": false
  }'

如果希望知识库对高频关键问题直接命中人工审核的标准答案,可将同组织内已发布版本的问答集绑定为知识库的问答源(QA Source)(POST /api/v2/collections/{kb_id}/qa-bindings,支持 version_policy: "latest" | "pinned")。绑定进入 ready 后,MCP 工具 search_knowledge 会自动在 qa_items 中返回标准答案。详细约束见问答集评测与 CLI 调优闭环。

异步导出知识库(ZIP 归档)

知识库备份或跨环境迁移通过异步导出任务完成:

# 1. 提交异步导出任务
TASK_ID=$(curl -fsS \
  -X POST "${APEMIND_BASE_URL}/api/v2/collections/${KB_ID}/export" \
  -H "Authorization: Bearer ${APEMIND_API_KEY}" | jq -r '.export_task_id')

# 2. 轮询直到 status 变为 COMPLETED(可能状态:PENDING / PROCESSING / COMPLETED / FAILED / EXPIRED)
curl -fsS \
  -H "Authorization: Bearer ${APEMIND_API_KEY}" \
  "${APEMIND_BASE_URL}/api/v2/export-tasks/${TASK_ID}"

# 3. 下载归档 ZIP
curl -fsS -L -o kb-export.zip \
  -H "Authorization: Bearer ${APEMIND_API_KEY}" \
  "${APEMIND_BASE_URL}/api/v2/export-tasks/${TASK_ID}/download"

知识市场发布与订阅的边界提醒

通过 POST / DELETE /api/v2/collections/{kb_id}/sharing 发布或撤销知识库市场共享时,有两条关键行为必须在集成侧提前处理:

下一步