AgentbaseDocs
文档目录

文档与摄取管理

文档与摄取(Documents & Ingestion) 是知识库(如 kb_enterprise_support)将原始非结构化文件转化为高质量可检索分块(Chunks)与向量的核心生产车间。通过知识库详情页的 文档(Documents) 页签,用户可以批量上传或绑定存储桶文件、灵活配置文档解析器(text / vlm / mineru)与五种分块策略(general / title / smart / regex / faq)、管理层级分类标签与精确定位标识(documentTag、subProductId)、跟踪异步摄取状态机(202 排队 -> processing -> ready),并对生成的分块进行在线审阅、编辑与图片理解结果核验。


功能概述与核心场景

高质量的 RAG 问答效果取决于“解析准不准、分块合不合理、标签细不细”。Agentbase v2.10.0 在文档与摄取模块提供了精细化的全生命周期控制能力:

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。


核心概念与架构

文档异步摄取与分块向量化状态机

flowchart TB
    subgraph Input["1. 文档输入与元数据绑定"]
        Upload["本地批量上传 (<= 50 文件/批)\n或绑定 Storage Bucket (kb_enterprise_docs)"]
        Meta["写入文档元数据\n• 层级标签 (tags: ['运维手册/OceanBase'])\n• 定位标识 (documentTag: 'ob_12_4a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d')\n• 子产品编码 (subProductId: 'ob')"]
    end

    subgraph AsyncQueue["2. 异步摄取调度 (HTTP 202 Accepted)"]
        Queued["状态: queued\n生成唯一 ingestionId"]
        Processing["状态: processing\nWorker 拉取文件并初始化追踪 (Ingestion Tracing)"]
    end

    subgraph ParseAndChunk["3. 多模态解析与结构化分块"]
        DocParse["文档解析器 (Document Parser)\n• text: Markdown/纯文本提取\n• vlm: qwen-vl-max 视觉解析\n• mineru: PDF 版面/表格/公式还原"]
        ImgEnhance["图片理解增强 (Image Understanding)\nqwen-vl-max 并发提取图片语义摘要"]
        Chunking["分块解析器 (Chunking Parser)\ngeneral / title / smart / regex / faq\n(chunkTokenNum=512, overlapPercent=10)"]
    end

    subgraph VectorStore["4. 向量化与落库就绪"]
        EmbedCall["调用 LLM Gateway 向量模型\ntext-embedding-v3 (1024 维, 校验 maxInputTokens)"]
        OBWrite["写入 OceanBase Shared V2\n向量索引 + 全文倒排索引 + 分块元数据"]
        ReadyState["状态: ready\n可供混合检索与 GraphRAG/RAPTOR/Wiki 构建使用"]
        FailedState["状态: failed\n记录明确错误原因 (如 Embedding 输入超限)"]
    end

    Upload --> Meta --> Queued --> Processing --> DocParse
    DocParse --> ImgEnhance --> Chunking --> EmbedCall
    EmbedCall -->|成功| OBWrite --> ReadyState
    EmbedCall -->|异常/超限| FailedState

解析器与分块器核心概念表

组件维度可选类型适用文档场景与核心逻辑
**文档解析器 (documentParser)**text适用于结构清晰的 .md、.txt、.docx、.html 及常规电子版文档,解析速度最快、零额外视觉模型开销。
**文档解析器 (documentParser)**vlm调用项目已注册的视觉大模型(如 dashscope-prod 下的 qwen-vl-max)逐页识别复杂排版、扫描件、手写批注与架构流程图。
**文档解析器 (documentParser)**mineru针对学术论文、技术白皮书与复杂财务报表 PDF,精准识别多栏排版、跨页表格与 LaTeX 公式并转换为结构化 Markdown。
**分块解析器 (chunkingParser)**general通用滑动窗口分块。按固定的 chunkTokenNum(默认 512)与 overlapPercent(默认 10%)切分,适用无明显标题结构的长文本。
**分块解析器 (chunkingParser)**title按文档标题层级(titleLevel,默认 3 即 ###)切分章节,并将父级标题路径自动注入分块上下文,非常适合架构白皮书与排障手册。
**分块解析器 (chunkingParser)**smart综合段落边界、语义连贯性与最小分块阈值(minChunkTokens,默认 128)动态合并碎片段落、切分超长段落。
**分块解析器 (chunkingParser)**regex按用户指定的正则表达式(regexPattern)切分文档,适用于日志归档、特定格式法条或标准化条目文件。
**分块解析器 (chunkingParser)**faq专门针对「问:... 答:...」或雙列问答表格,确保每一对 Q&A 完整保留在同一个独立分块中,不被截断。

功能入口与权限矩阵

控制台入口、REST API、SDK 方法与权限矩阵

控制台入口 / 功能模块前端路由路径对应 REST API 端点Server SDK 方法(Node.js / Python)所需 RBAC 角色 / API Key Scope跨模块依赖关系
**文档列表、目录树与 documentTag 筛选**/console/project-default-enterprise-ai-hub-210/knowledge-base/kb-kb_enterprise_support/documentsGET /v1/knowledgebases/{kbId}/documentsknowledgeBase.listDocuments() / list_documents()角色:owner、admin、developer、member(只读)<br/>Scope:knowledgebases.read支持按层级 tags、documentTag、subProductId 过滤
批量上传文档或绑定存储桶文件/console/.../kb-kb_enterprise_support/documents(点击「上传文档 Upload documents」)POST /v1/knowledgebases/{kbId}/documentsknowledgeBase.createDocument() / create_document()角色:owner、admin、developer<br/>Scope:knowledgebases.write源文件持久化至 kb_enterprise_docs 存储桶;异步返回 HTTP 202
查询异步摄取进度与触发重摄取文档列表状态徽章与行操作「重新摄取(Re-ingest)」POST /v1/knowledgebases/{kbId}/documents/{docId}/ingestions<br/>GET .../ingestions/{ingestionId}knowledgeBase.createIngestion()<br/>knowledgeBase.getIngestion()角色:owner、admin、developer<br/>Scope:knowledgebases.write / read依赖 dashscope-prod 的 text-embedding-v3(1024 维)与 qwen-vl-max(详见 知识库设置)
编辑文档标签与定位标识文档行操作「编辑标签(Edit tags)」PATCH /v1/knowledgebases/{kbId}/documents/{docId}knowledgeBase.updateDocument()角色:owner、admin、developer<br/>Scope:knowledgebases.writedocumentTag 联动 混合检索、知识图谱 与 Wiki 冲突工作台
分块(Chunks)透明审阅与在线热修/console/.../kb-kb_enterprise_support/documents/{docId}GET /v1/knowledgebases/{kbId}/documents/{docId}/chunks<br/>PATCH .../chunks/{chunkId}knowledgeBase.listChunks()<br/>knowledgeBase.updateChunk()角色:owner、admin、developer(只读成员仅查看)<br/>Scope:knowledgebases.write编辑分块后自动重算 1024 维向量并将 高级知识索引 标记为 stale (chunk_updated)
导入语雀 URL 与外部数据源同步文档页「导入语雀 URL」或 数据源 页签POST /v1/knowledgebases/{kbId}/datasources/{id}/syncknowledgeBase.syncDataSource()角色:owner、admin、developer<br/>Scope:knowledgebases.write完整 OAuth2 与个人令牌同步指南详见 外部数据源接入与语雀增量同步

功能详解与操作指南

一、上传企业知识文档并配置分块参数

在标杆知识库 kb_enterprise_support 中,我们摄取了 4 篇核心生产文档。以下是具体操作步骤:

参数名称字段标识推荐配置值取值范围与说明
立即开始摄取autoIngesttrue(开启)上传完成后立即创建异步摄取任务(返回 202)
文档解析器documentParsertext(PDF 选 mineru 或 vlm)可选 text / vlm / mineru
分块解析器chunkingParsertitle可选 general / title / smart / regex / faq
目标分块 Token 数chunkTokenNum512建议范围 128~2048,须小于 Embedding 模型的 maxInputTokens
分块重叠比例(%)overlapPercent10相邻分块保留 10% 的重叠上下文,防止跨块语义断裂
标题切分层级titleLevel3仅 title 模式生效,按 H1/H2/H3 标题切分章节
最小分块 Token 数minChunkTokens128低于该阈值的短小章节自动与相邻同级段落合并
开启图片理解imageUnderstanding.enabledtrue调用 qwen-vl-max(并发度 1–8,推荐 4)生成图片文字解读

二、管理层级标签与定位标识(documentTag & subProductId)

为了在海量文档中实现毫秒级定向检索与目录治理,Agentbase 支持两套互补的标签机制:

1. 层级目录标签(Hierarchical Tags)

2. 文档定位标识(documentTag 与 subProductId)

自 v2.10.0 起,每篇文档均可绑定结构化的定位标识 documentTag 与子产品编码 subProductId:

# 1. 为文档写入 documentTag 与层级标签
curl -X PATCH "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/documents/doc_ob_troubleshooting" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "documentTag": "ob_12_4a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
    "subProductId": "ob",
    "tags": ["技术支持/数据库/OceanBase", "核心排障"]
  }'

# 2. 触发单文档重新摄取(返回 HTTP 202 Accepted 与 ingestionId)
curl -i -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/documents/doc_ob_troubleshooting/ingestions" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

# 3. 轮询摄取任务状态直至变为 ready
curl -X GET "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/documents/doc_ob_troubleshooting/ingestions/ing_9f8e7d6c5b4a3210" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

三、审阅与编辑分块(Chunks)及整库重建(Reindex)


外部数据源(Data Sources)与语雀同步管理

一、配置语雀(Yuque)数据源连接

在 kb_enterprise_support 知识库中接入企业语雀技术文档空间,支持 OAuth 2.0 授权接入 与 Access Token 接入 两种方式:

步骤 1:打开新建数据源向导

步骤 2:完成身份认证与空间绑定

根据企业安全规范填写数据源连接参数:

配置项参数名标杆配置示例说明与校验规则
数据源名称name企业技术支持语雀知识库知识库内可读名称,便于区分不同团队的语雀空间
数据源类型typeyuque当前内置支持语雀知识库连接器
认证方式authTypeoauth 或 token推荐使用 OAuth 一键跳转授权;自动化流水线可使用语雀 Personal Access Token
语雀服务地址baseUrlhttps://www.yuque.com(或企业专属语雀域名)自动通过服务端安全 URL 白名单与 DNS 校验
访问令牌accessToken<YUQUE_ACCESS_TOKEN>落库时加密存储,读取接口永不回显明文
目标知识空间标识namespace / repoIdob-support/kb-handbook格式为 团队或个人Login/知识库Slug 或语雀 Book 数字 ID
默认标签前缀defaultTags["语雀同步/技术支持"]同步入库的文档自动打上该层级标签,便于在文档目录树中归类
默认子产品编码subProductIdob为同步进入的文档自动关联子产品标识

点击 测试连接并保存(Test & Create),系统会验证远端空间读取权限并生成唯一的 dataSourceId(如 ds_yuque_enterprise_01)。


二、从外部数据源选择性批量导入文档

如果您只需要将语雀空间中的部分核心文档(例如《智能客服SOP标准作业手册》与《AI网关模型路由与限流计费规范》)导入知识库,可使用交互式目录树导入功能:


三、触发增量同步作业(Sync Runs)与状态监控

当远端语雀知识库中的排障指南或 SOP 发生日常修订时,可通过控制台或 API 触发数据源同步作业:

1. 控制台触发与监控

同步状态状态标识含义说明
排队中queued同步请求已被接受,正在等待后台同步 Worker 调度
同步中running正在拉取远端语雀目录、比对文档修订版本并触发变更文档的重新摄取
已完成completed全部新增与变更文档均已成功拉取并提交摄取流水线
部分失败partial_failed大部分文档同步成功,个别文档因远端权限受限或格式异常失败(可查看错误明细并重试)
已失败failed远端 Token 失效、网络不可达或空间被删除导致同步中断

2. 通过 REST API 管理数据源与触发同步

后端研发或 CI/CD 定时流水线可通过以下标准接口自动化触发增量同步:

# 1. 查询知识库已挂载的数据源列表
curl -X GET "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/datasources" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

# 2. 触发指定数据源的增量同步作业 (POST /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/syncs)
curl -X POST "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/datasources/ds_yuque_enterprise_01/syncs" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "syncMode": "incremental",
    "triggerIngest": true
  }'

# 3. 查询同步作业运行记录与变更统计
curl -X GET "https://appbuild.oceanbase.com/v1/knowledgebases/kb_enterprise_support/datasources/ds_yuque_enterprise_01/syncs" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>"

验证结果:


上传与摄取文档

文档与分块管理

截图未公开:原图可能包含账号或资源标识。

界面参考:沿用已登记的历史截图,演示数据与当前项目可能不同;本次未重新取图。

常见问题与排障(FAQ)

Q1:文档摄取状态变成 failed,报错提示 Embedding 输入超限,该如何排查与解决?

Q2:扫描版 PDF 或包含大量架构图的文档,使用默认 text 解析器提取不出文字怎么办?

Q3:documentTag 的格式有什么校验要求?如果格式不合法会怎样?

Q4:Excel 表格上传后是如何被切分和向量化的?


相关文档