informat.knowledgebase 知识库文档操作

概述

使用 informat.knowledgebase 可以在当前应用的知识库模块中创建脚本文档、覆盖写入 Markdown 正文，并查询文档的异步摄入状态。

典型调用流程如下：

1. 使用 createDocument 创建一个空文档并取得文档 ID；
2. 使用 writeDocument 写入完整正文并取得摄入任务 ID；
3. 在后续脚本或业务流程中使用 getIngestTaskStatus 查询处理结果。

使用限制

• moduleId 必须是当前应用中已发布的知识库模块 ID，不支持使用模块标识符（module key）。
• 脚本只能写入通过 informat.knowledgebase.createDocument 创建的文档，不能覆盖用户上传的 PDF、Word 或其他文档。
• writeDocument 是全量覆盖操作，不是追加写入。
• 文档正文不能为空，UTF-8 编码后的大小不能超过 15MB。

createDocument

在目标知识库模块中创建一个空的脚本文档，并返回文档 ID。文档创建后状态为 PENDING，调用 writeDocument 写入正文后才会开始摄入。

informat.knowledgebase.createDocument(moduleId, document);

参数	类型	描述
moduleId	String	当前应用中知识库模块的真实 ID
document	Object	文档配置

document 支持以下属性：

属性	类型	必填	描述
name	String	是	文档名称
category	String	否	文档分类
description	String	否	文档描述
documentType	String	否	文档类型，默认为 MARKDOWN
chunkConfig	Object	否	自定义分块配置；不传时使用文档类型的推荐配置

documentType 支持以下值：

值	适用内容
DEFAULT	通用文本
CODE	代码文档
API	API 文档
MARKDOWN	Markdown 文档
FAQ	常见问题
ARTICLE	文章
TABLE	表格型文本
EXCEL	Excel 转换后的文本
CUSTOM	使用自定义分隔符的文本

chunkConfig 支持以下属性：

属性	类型	默认值	描述
parentMaxLen	Integer	1500	父分块最大字符数
childMaxLen	Integer	400	子分块最大字符数
childMinLen	Integer	80	子分块最小字符数
childOverlapLen	Integer	50	相邻子分块重叠字符数
enableOverlap	Boolean	true	是否启用子分块重叠
parentSeparator	String	\\n\\n	父块分隔符，仅 CUSTOM 类型使用
childSeparator	String	\\n	子块分隔符，仅 CUSTOM 类型使用

返回值

文档 ID，类型为 String。

示例

const documentId = informat.knowledgebase.createDocument('knowledgeModuleId', {
    name: '产品接口说明',
    category: '技术文档',
    description: '由应用脚本自动维护',
    documentType: 'MARKDOWN',
    chunkConfig: {
        parentMaxLen: 1500,
        childMaxLen: 400,
        childMinLen: 80,
        childOverlapLen: 50,
        enableOverlap: true,
    },
});

调用账号需要拥有目标知识库模块的新增权限。

writeDocument

全量覆盖目标脚本文档的正文，并提交异步摄入任务。

informat.knowledgebase.writeDocument(moduleId, documentId, content);

参数	类型	描述
moduleId	String	当前应用中知识库模块的真实 ID
documentId	String	createDocument 返回的文档 ID
content	String	完整的 Markdown 正文

返回值

返回值类型为 Object，包含以下属性：

属性	类型	描述
docId	String	文档 ID
taskId	String	异步摄入任务 ID

示例

const result = informat.knowledgebase.writeDocument(
    'knowledgeModuleId',
    documentId,
    `# 产品接口说明

## 创建订单

调用创建订单接口前，需要先取得访问令牌。`,
);

informat.console.log(`文档ID：${result.docId}`);
informat.console.log(`任务ID：${result.taskId}`);

调用账号需要拥有目标知识库模块的更新权限。同一文档处于 PROCESSING 状态时不能再次覆盖，等待当前任务完成或失败后再重新写入。

数据一致性

写入操作会协调源文件替换、旧分块清理和摄入任务创建。数据库事务失败时，新文件和 Redis 任务会执行补偿清理；事务提交后，旧源文件才会删除。

getIngestTaskStatus

查询异步摄入任务状态。

informat.knowledgebase.getIngestTaskStatus(moduleId, taskId);

参数	类型	描述
moduleId	String	任务所属知识库模块的真实 ID
taskId	String	writeDocument 返回的任务 ID

返回值

返回值类型为 Object，包含以下属性：

属性	类型	描述
taskId	String	任务 ID
docId	String	文档 ID
status	String	任务状态
totalChunks	Integer	总子分块数
processedChunks	Integer	已处理子分块数
progress	Number	处理进度百分比
errorMessage	String	失败原因；任务未失败时为空
startTime	String	ISO-8601 格式的开始时间
endTime	String	ISO-8601 格式的结束时间；任务未结束时为空
duration	Long	执行时长，单位为毫秒

status 可能为以下值：

状态	描述
PENDING	任务已创建，等待执行
PROCESSING	正在分块并生成向量数据
COMPLETED	摄入完成，文档可以用于检索
FAILED	摄入失败，可通过 errorMessage 查看原因

示例

const task = informat.knowledgebase.getIngestTaskStatus(
    'knowledgeModuleId',
    taskId,
);

if (task.status === 'COMPLETED') {
    informat.console.log(`摄入完成，共生成 ${task.totalChunks} 个子分块`);
} else if (task.status === 'FAILED') {
    throw new Error(task.errorMessage || '知识库文档摄入失败');
} else {
    informat.console.log(`当前进度：${task.progress}%`);
}

调用账号需要拥有目标知识库模块的查询权限。任务记录在 Redis 中保存 7 天，过期后不能再通过任务 ID 查询。

不要在脚本中忙等待

摄入任务在后台异步执行。不要使用循环持续查询任务状态，否则会长时间占用脚本执行线程。可以在后续自动化、定时任务或其他业务入口中查询处理结果。

服务重启与任务恢复

摄入任务的状态、租户上下文和待处理正文都保存在 Redis 中，不依赖服务进程内存。服务重启后，系统会定期扫描 PENDING 和 PROCESSING 任务并恢复执行。

• 恢复任务使用任务级分布式锁，避免多个服务节点重复处理同一任务；
• 已经完整写入数据库的父分块会作为续传断点，不会从头重复写入；
• Redis 不可用时，任务创建会直接失败并回滚，不会降级为仅保存在内存中的任务；
• 状态为 FAILED 的任务不会自动重试。排除错误后，可以再次调用 writeDocument 创建新的摄入任务。

服务刚恢复时，任务可能短暂保持 PENDING 或 PROCESSING，通常会在下一次恢复扫描后继续执行。

完整示例

export function publishGuide(moduleId, markdown) {
    const documentId = informat.knowledgebase.createDocument(moduleId, {
        name: '应用使用指南',
        category: '产品文档',
        description: '由发布脚本维护',
        documentType: 'MARKDOWN',
    });

    return informat.knowledgebase.writeDocument(
        moduleId,
        documentId,
        markdown,
    );
}

export function getPublishStatus(moduleId, taskId) {
    return informat.knowledgebase.getIngestTaskStatus(moduleId, taskId);
}

常见问题

提示模块不存在或不是知识库模块

确认传入的是当前应用中已发布知识库模块的真实 ID，而不是模块名称或模块标识符。

提示只能写入 informat.knowledgebase 创建的文档

writeDocument 不能覆盖通过界面上传或其他入口创建的文档。请先调用 createDocument，再使用返回的文档 ID 写入正文。

文档长时间保持 PENDING

检查 Redis、向量模型和知识库模块配置是否可用。服务重启或异步线程池繁忙时，任务会由恢复扫描重新调度。

任务状态为 FAILED

查看 errorMessage，检查向量模型配置、网络连接和正文分块配置。修复问题后再次调用 writeDocument。