AgentbaseDocs
文档目录

文档与摄取

文档登记、摄取管线、图片理解、语雀数据源同步与全量重建的各语言调用示例;概念、参数与边界口径见知识库。

各语言调用示例

摄取文档(登记 → 摄取 → 轮询)

createDocument 登记源文件,createIngestion 异步入队并返回 HTTP 202(表示任务已受理,不代表立即可检索)。轮询 getIngestion 至 ready,并确认 Document 的 status=ready、activeGeneration 与该 ingestion 的 generation 一致后,再按新代检索;ingestion 409 表示同文档已有进行中任务。Web 面无摄取能力。

const doc = await kb.createDocument({ knowledgeBaseId: base.$id, fileId: '<storageFileId>' });
// 批量登记:kb.createDocumentsBatch(单批最多 50 个文件)
await kb.createIngestion({ knowledgeBaseId: base.$id, documentId: doc.$id });   // 异步入队,可带幂等键

// 轮询:状态机 queued → running → ready | failed | cancelled
const ing = await kb.getIngestion({ knowledgeBaseId: base.$id, documentId: doc.$id, ingestionId: '<ingestionId>' });

图片理解(可选)

在 parserConfig.imageUnderstanding 配置,是解析后的独立步骤:为有信息量的图片生成描述并加入检索文本,不修改原始 chunk 的 content / span / locator;enabled=true 时 model 与 providerRef 必填。maxImagesPerDocument 传 null 或省略表示不限制图片理解数量。Web 面无此能力。

await kb.createDocument({
    knowledgeBaseId: base.$id,
    fileId: '<storageFileId>',
    parserConfig: {
        imageUnderstanding: {
            enabled: true,
            model: '<visionModelId>',             // 项目视觉模型 ID
            providerRef: 'project:<providerId>',  // 项目 Provider 引用
            prompt: '用中文概括图片中的关键信息',    // ≤4000 字符,空值用内置提示词
            maxImagesPerDocument: 20,             // 1–20,默认 20
            maxDescriptionChars: 800,             // 1–800,默认 800
            maxConcurrency: 4                     // 1–8,默认 4
        }
    }
});

Excel 工作表解析(2.7.0)

parserId 新增 sheet:仅适用于 Excel .xls / .xlsx,为每个非空工作表生成一个完整 chunk,并保存 sheetName / sheetIndex / sheetPages。Excel 文档直接支持 faq 或 sheet,smart 在摄取时自动解析为 sheet;general / title / regex 对具体 Excel 摄取返回 400。documentParser 仍可叠加:text 保留单元格结构化文本,vlm / mineru 把每个目标 Sheet 单独渲染成临时 PDF(适合图表与图片)。空输出 Sheet 不入库;工作簿 Sheet 数、解压量、压缩比、单元格矩形与渲染输入都有硬限制。Web 面无此能力,本卡不设 Web 页签。

import { ParserId, KnowledgeBaseDocumentParser } from 'agentbase-node-sdk';

// 库级默认或文档级覆盖都可用 sheet;文档级 parserConfig 非空时整体替换 KB 默认
await kb.createDocument({
    knowledgeBaseId: base.$id,
    fileId: '<xlsxFileId>',
    parserId: ParserId.Sheet,
    parserConfig: { documentParser: KnowledgeBaseDocumentParser.Text },   // 逐 Sheet 提取结构化文本
});
// 图表密集型工作簿:documentParser 用 Vlm / Mineru(每个目标 Sheet 渲染为临时 PDF)

批量删除文档(2.8.0)

knowledgeBases.deleteDocuments({ knowledgeBaseId, documentIds, versionId? }) 一次请求删除多个文档,单批最多 50 个;成功返回 204。请求先做预检:所有 ID 必须属于该库(传入 versionId 时须属于该可写 DRAFT 版本),预检失败则一个都不会删。删除按请求顺序执行;若中途外部存储或并发失败,重新拉取列表、仅重试仍存在的 ID。需要 knowledgebases.write scope。版本化激活后写路径必须携带 versionId。

await kb.deleteDocuments({
    knowledgeBaseId: base.$id,
    documentIds: ['doc_001', 'doc_002']   // 单批最多 50 个
});

索引输出语言与嵌入输入上限(2.7.0)

语雀数据源(Web OAuth → 服务端同步)

OAuth 授权用 Web SDK(用户 Session),枚举与数据源同步在服务端完成,复用同一 ingestion 管线。

// 方法名见上文「使用骨架」;各方法参数对象以 SDK 源码与 API 参考为准
await kb.createYuqueOAuthSession({ /* OAuth 会话参数 */ });
const repos = await kb.listYuqueRepos({ /* ... */ });
const docs = await kb.listYuqueDocs({ /* ... */ });
await kb.createDataSource({ knowledgeBaseId: base.$id /*, 数据源参数 */ });
await kb.createDataSourceSync({ knowledgeBaseId: base.$id, dataSourceId: '<dataSourceId>' });

全量重建

改库级解析配置不会重写历史 chunk;把全部就绪文档有界分批重新入队摄取用 createReindex(返回 202,不改变 embeddingModel),nextCursor 非 null 时携带游标继续下一批。Web 面无此能力。

let res = await kb.createReindex({ knowledgeBaseId: base.$id, limit: 50 });
while (res.nextCursor) {   // 有界分批:继续入队直至 nextCursor 为 null
    res = await kb.createReindex({ knowledgeBaseId: base.$id, limit: 50, cursor: res.nextCursor });
}