Docs
文档目录

文档与摄取

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

各语言调用示例

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

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 })(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)

语雀个人授权与团队同步

个人语雀授权和导入需要当前控制台用户身份,不能用项目 API 密钥或普通终端用户会话替代。目标环境须配置语雀授权能力;仅支持特定企业语雀域名,请向环境管理员确认。

以下示例使用 Console Python SDK。请使用对目标项目有知识库写权限的控制台用户会话签发的短期 JWT,并确认该会话仍有效;客户端指定目标项目、admin 模式和该 JWT,不同时附带其他已生效的 Cookie。首次授权时按提示在浏览器完成授权;会话、项目、知识库和用户须保持一致。启用版本管理时填写实际草稿 ID,未启用时设为空字符串。

from getpass import getpass
from agentbase_console.client import Client
from agentbase_console.services.knowledge_bases import KnowledgeBases

client = (Client().set_endpoint('<ENDPOINT>/v1').set_project('<PROJECT_ID>')
          .set_mode('admin').set_jwt(getpass('Console user JWT: ')))
kb = KnowledgeBases(client)
knowledge_base_id = '<KNOWLEDGE_BASE_ID>'
draft_version_id = '<DRAFT_VERSION_ID>'

authorization = kb.create_yuque_o_auth_session(knowledge_base_id=knowledge_base_id)
if not authorization['authorized']:
    print(authorization['authorizeUrl'])
    input('Complete authorization in your browser, then press Enter: ')

session = kb.get_yuque_o_auth_session(
    knowledge_base_id=knowledge_base_id, session_id=authorization['sessionId'])
if not session['authorized']:
    raise RuntimeError('Yuque authorization is not complete')
result = kb.create_yuque_documents(
    knowledge_base_id=knowledge_base_id, session_id=authorization['sessionId'],
    urls=['<SUPPORTED_YUQUE_DOCUMENT_URL>'], version_id=draft_version_id or None)
for item in result.results:
    print(item.url, item.status, item.error or '')
if result.failed:
    raise RuntimeError(f'{int(result.failed)} document(s) failed to import')

团队数据源同步

以下示例使用已创建的团队数据源和具有 knowledgebases.write 权限的服务端客户端 kb。请替换实际知识库、数据源和草稿 ID;未启用版本管理时将 draftVersionId 设为空字符串,或在 REST 请求中省略 versionId。

const knowledgeBaseId = '<knowledgeBaseId>';
const dataSourceId = '<dataSourceId>';
const draftVersionId = '<DRAFT_VERSION_ID>';
const sync = await kb.createDataSourceSync({
    knowledgeBaseId,
    dataSourceId,
    ...(draftVersionId ? { versionId: draftVersionId } : {})
});

全量重建

改库级解析配置不会重写历史 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 });
}