知识库 API
富文档 RAG 知识库全链路接口:知识库 CRUD、文档摄取(Storage 文件登记 + 解析/切片/Embedding 流水线)、切片(chunk)级维护、数据源(data source)连接与同步、单库/跨库语义检索、重建索引与管理观测。
服务与资源边界
知识库(KnowledgeBases)与词库(Lexicons)模块构成 Agentbase 平台的企业级多源 RAG 与查询改写核心引擎:
全链路 RAG 生命周期:覆盖知识库(
{knowledgeBaseId},如kb_enterprise_support)创建、Storage 文件/外部数据源摄取、结构化解析切片(Chunking)、向量化(如dashscope-prod的text-embedding-v31024 维模型)、单库/跨库混合检索与重排(qwen3.7-text-rerank)。项目级词库(Lexicons)协同:支持在项目内创建与维护同义词(
synonym)、扩展词(expansion)与停用词(stop)词条,并通过绑定接口挂载至知识库(/v1/knowledgebases/{knowledgeBaseId}/lexicons)或智能体工作台(/v1/agent-runtime/project/lexicons),在查询预处理与 GraphRAG 图谱构建阶段自动完成术语对齐与停用词拦截。派生索引与版本治理协同:知识库之上的 Wiki 自动编译、GraphRAG 知识图谱与 RAPTOR 层次聚类索引详见 Wiki 与索引治理 API;知识库不可变版本封存(Seal)、发布(Publish)与回滚详见 知识库版本管理 API。
文档定位参数中,仅创建支持 sectionCode;检索与列表通过 documentTag、subProductId 过滤,不接受独立的 sectionCode 过滤参数。
资源与基础路径
Base URL:
https://<your-endpoint>/v1,路径前缀/knowledgebases。层级:知识库
{knowledgeBaseId}→ 文档{documentId}→ 切片{chunkId};旁路资源:数据源{dataSourceId}、同步{syncId}、摄取{ingestionId}。源文件存放于 Storage:每个知识库有默认桶;登记文档时引用已上传文件的
fileId(见 storage)。
认证与权限
认证与请求头约定见 通用约定。本域 scope:knowledgebases.read(查询、检索、管理摘要)、knowledgebases.write(全部写操作)。Embedding / Rerank 经 LLM Gateway 执行(provider 引用格式 project:<providerId> 或 trial:<bindingId>,见 llm-gateway)。
端点总览
本页涵盖两大核心路径前缀:/v1/knowledgebases(知识库、文档、切片、摄取、数据源与检索)与 /v1/lexicons(项目词库、词条、导入导出、改写预览与资源引用)。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
GET /knowledgebases | 列出知识库 |
POST /knowledgebases | 创建知识库 |
GET /knowledgebases/{knowledgeBaseId} | 获取知识库 |
PATCH /knowledgebases/{knowledgeBaseId} | 更新知识库 |
DELETE /knowledgebases/{knowledgeBaseId} | 删除知识库 |
POST /knowledgebases/search | 跨库检索(1–10 库) |
POST /knowledgebases/{knowledgeBaseId}/search | 单库检索 |
GET /knowledgebases/{knowledgeBaseId}/management | 管理摘要(最近摄取/trace/评分) |
POST /knowledgebases/{knowledgeBaseId}/reindex | 有界批量重建索引 |
GET /knowledgebases/{knowledgeBaseId}/documents | 列出文档 |
POST /knowledgebases/{knowledgeBaseId}/documents | 登记文档;摄取需另行发起 |
POST /knowledgebases/{knowledgeBaseId}/documents/batch | 批量登记(最多 50 文件) |
DELETE /knowledgebases/{knowledgeBaseId}/documents | 批量删除文档(最多 50 个,预检原子) |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId} | 获取文档 |
PATCH /knowledgebases/{knowledgeBaseId}/documents/{documentId} | 更新文档 |
DELETE /knowledgebases/{knowledgeBaseId}/documents/{documentId} | 删除文档 |
POST /knowledgebases/{knowledgeBaseId}/documents/{documentId}/process | 触发(重)处理 |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/source | 下载原始源文件 |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks | 列出切片 |
POST /knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks | 手工建切片 |
GET|PATCH|DELETE .../chunks/{chunkId} | 切片读改删 |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions | 摄取任务列表 |
POST /knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions | 发起摄取 |
GET|DELETE .../ingestions/{ingestionId} | 摄取详情/取消 |
GET /knowledgebases/{knowledgeBaseId}/datasources | 列出数据源 |
POST /knowledgebases/{knowledgeBaseId}/datasources | 创建外部数据源(语雀团队空间) |
GET|PATCH|DELETE .../datasources/{dataSourceId} | 数据源读改删 |
POST .../datasources/yuque/repos、POST .../datasources/yuque/docs | 枚举语雀团队仓库与文档清单 |
POST .../datasources/{dataSourceId}/documents | 从数据源 URL 导入单篇 |
POST .../datasources/{dataSourceId}/documents/batch | 批量导入(最多 20 URL) |
GET|POST .../datasources/{dataSourceId}/syncs、GET .../syncs/{syncId} | 数据源同步与状态轮询 |
GET /knowledgebases/{knowledgeBaseId}/version-adoptions | 列出采纳操作(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/version-adoptions | 启动版本采纳(异步)(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId} | 获取采纳操作(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId}/cancel | 请求取消采纳(异步)(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/version-delete-operations/{operationId} | 查询版本删除操作(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/versions | 列出版本(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/versions | 创建工作副本(异步)(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/versions/{versionId} | 获取版本(见 版本管理) |
DELETE /knowledgebases/{knowledgeBaseId}/versions/{versionId} | 请求不可逆删除版本(异步)(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/publish | 发布 READY 版本为当前版本(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/versions/{versionId}/readiness | 版本就绪摘要(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/rollback | 回滚到保留的回滚目标(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/seal | 封存 DRAFT 为 READY(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/working-copy-operations | 列出工作副本操作(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId} | 获取工作副本操作(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}/cancel | 请求取消工作副本操作(见 版本管理) |
GET /lexicons | 列出项目词库 |
POST /lexicons | 创建项目词库 |
GET /lexicons/{lexiconId} | 获取词库详情 |
PATCH /lexicons/{lexiconId} | 更新词库元数据与权限 |
DELETE /lexicons/{lexiconId} | 删除未绑定的词库 |
GET /lexicons/{lexiconId}/entries | 列出词库词条(支持按 entryType 过滤) |
POST /lexicons/{lexiconId}/entries | 创建词条(synonym / expansion / stop) |
GET|PATCH|DELETE /lexicons/{lexiconId}/entries/{entryId} | 词条详情/更新/删除 |
POST /lexicons/{lexiconId}/preview | 预览查询改写与停用词命中效果 |
POST /lexicons/{lexiconId}/import | 批量导入词条(JSON / CSV / XLSX,支持 dryRun) |
GET /lexicons/{lexiconId}/export | 导出词库词条文件(JSON / CSV / XLSX) |
GET /lexicons/{lexiconId}/references | 查询绑定了该词库的知识库与智能体列表 |
GET|PUT /knowledgebases/{knowledgeBaseId}/lexicons | 查询/整体替换知识库绑定的词库列表 |
GET|PUT /agent-runtime/project/lexicons | 查询/整体替换当前项目智能体工作台绑定的词库列表 |
GET|PATCH /knowledgebases/{knowledgeBaseId}/index-capabilities*、POST|GET .../index-operations* | GraphRAG / RAPTOR / LLM Wiki 索引能力治理与构建任务(见 Wiki 与索引治理) |
GET /knowledgebases/{knowledgeBaseId}/graph*、GET|POST .../wiki/* | 知识图谱、实体邻居、社区报告与 LLM Wiki 治理(见 Wiki 与索引治理) |
端点详解
词库修订号(
revision)与事务锁:每次增删改词条或批量导入(dryRun=false)时,词库主文档的revision原子递增;在绑定词库至知识库或构建 GraphRAG 索引快照时,服务端通过行锁保证词条快照一致性。词条去重与配额上限:单个词库最多容纳
1,000条词条(LexiconService::MAX_ENTRIES = 1000),且内置基于规则类型与归一化词项的dedupeKey唯一性校验;被知识库或智能体引用的词库在解绑前禁止直接删除(返回409 general_conflict)。
请求与响应
以下按资源域逐端点给出输入、输出与可复制的调用/响应示例。通用约定:
认证:所有请求携带
X-Appwrite-Project: <YOUR_PROJECT_ID>与X-Appwrite-Key: <YOUR_API_KEY>;scopeknowledgebases.read覆盖查询/检索/管理摘要,knowledgebases.write覆盖全部写操作。异步任务(登记后的摄取
202、重处理202、reindex202、数据源同步202)一律通过对应的GET详情端点轮询终态;摄取任务另支持 RealtimetrackingChannels订阅。示例中的资源 ID(
kb_product_docs、doc_manual_v2、chk_0042、ds_yuque_team)请替换为实际值。Embedding 与重排经 LLM Gateway 执行,provider 引用格式
project:<providerId>或trial:<bindingId>(见 llm-gateway)。
知识库管理
GET /v1/knowledgebases
SDK:KnowledgeBases.list · scope:knowledgebases.read
列出当前项目全部知识库,可按 ID/名称搜索。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
search | query | string | 否 | 默认 "" | 按知识库 ID 或名称过滤,最长 256 字符。 |
输出:
200,返回模型 Models.KnowledgeBaseList。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 匹配查询的知识库总数。 |
knowledgeBases* | object[] | 知识库列表。 |
$id* | string | 知识库 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
name* | string | 知识库名称。 |
description* | string | 知识库描述。 |
embeddingModel* | string | 建库时固定的 Embedding 模型 ID。 |
embeddingProviderRef* | string | 钉定的 Embedding provider 来源(project:<providerId> / trial:<bindingId>),空表示自动路由。 |
embeddingDimension* | integer | Embedding 向量维度,与模型输出一致,建库后不可改。 |
parserId* | string | 默认切片策略:general / title / smart / regex / faq。 |
parserConfig* | object | 默认解析/切片配置(动态对象,字段见创建端点)。 |
retrievalDefaults* | object | 检索默认值(如 similarityThreshold、vectorWeight、限流)。 |
vectorsdbDatabaseId* | string | Backing 的 VectorsDB 库 ID,provision 完成前为 null。 |
vectorsdbCollectionId* | string | Backing 的 VectorsDB 集合 ID,provision 完成前为 null。 |
bucketId* | string | 默认 Storage 桶 ID(文档源文件存放处),provision 完成前为 null。 |
iconFileId* | string | 头像/图标文件 ID,未设置时为 null。 |
ingestRoutes* | object | 已废弃的 MIME→Function 映射,仅为兼容保留。 |
documentCount* | integer | 库内文档总数。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases?search=产品手册" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 2,
"knowledgeBases": [
{
"$id": "kb_product_docs",
"$createdAt": "2026-08-30T09:00:00.000+00:00",
"$updatedAt": "2026-09-14T02:01:12.000+00:00",
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"embeddingModel": "text-embedding-v3",
"embeddingProviderRef": "",
"embeddingDimension": 1024,
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
},
"retrievalDefaults": {
"similarityThreshold": 0.5,
"vectorWeight": 0.7
},
"vectorsdbDatabaseId": "vdb_kb_docs",
"vectorsdbCollectionId": "col_kb_docs",
"bucketId": "bkt_kb_docs",
"iconFileId": "",
"ingestRoutes": {},
"documentCount": 2
}
]
}POST /v1/knowledgebases
SDK:KnowledgeBases.create · scope:knowledgebases.write
创建知识库:钉定 Embedding 模型并自动 provision 专用 VectorsDB 库/集合与 Storage 桶。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | body | string | 是 | 知识库 ID:自定义或 ID.unique() 生成。 | |
name | body | string | 是 | 知识库名称。 | |
description | body | string | 否 | 知识库描述。 | |
embeddingModel | body | string | 是 | Embedding 模型 ID;创建时对 LLM Gateway 探测一次得出向量维度,建库后模型与维度不可改。 | |
embeddingProviderRef | body | string | 否 | 钉定 Embedding provider(project:<providerId> / trial:<bindingId>);省略走自动路由。 | |
embeddingDimension | body | integer | 否 | 1–65535 | 显式向量维度(2.9.0):对所选模型探测校验,与模型输出维度不符则创建失败(400)。 |
tracingEnabled | body | boolean | 否 | 默认 false | 摄取追踪开关(2.9.0):记录解析 / 分块中间产物供「知识库解析评估」使用;依赖平台管理员全局开关,开启后需重新摄取才有完整证据。 |
parserId(或 chunkingStrategy) | body | string | 否 | 枚举:general / title / smart / regex / faq / sheet | 库级默认分块策略(Chunking Strategy),未覆盖的文档按此切分。 |
parser | body | string | 否 | 枚举:text / mineru / vlm / office | 库级默认文档解析器简写(等价于 parserConfig.documentParser)。 |
parserConfig | body | object | 否 | 库级默认解析/分块与多模态配置(子字段见下)。 | |
parserConfig.chunkTokenNum | body | integer | 否 | 每个切片的 token 预算:general/smart 默认 512,title/regex 默认 256,范围 64–4096。 | |
parserConfig.overlapPercent | body | integer | 否 | 默认 10 | general/smart 切片器的相邻切片 token 重叠百分比,默认 10(0–50)。 |
parserConfig.delimiter | body | string | 否 | 超长 title/regex 切片的降级切分分隔符;默认 title 为 \n。;!?,regex 为 \n。.;;!!??。 | |
parserConfig.titleLevel | body | integer | 否 | 默认 3 | title 切片器拆分的 Markdown 标题层级上限(1–6,默认 3 即拆至 ###)。 |
parserConfig.minChunkTokens | body | integer | 否 | 默认 128 | smart 切片器最小切片大小,默认 128,不得超过 chunkTokenNum。 |
parserConfig.regexPattern | body | string | 否 | 默认 "[.!?]+\\s*" | regex 切片器使用的 PCRE 正则表达式,默认 [.!?]+\s*。 |
parserConfig.documentParser | body | string | 否 | 枚举:text / mineru / vlm / office | 文档解析引擎:text(纯文本/源码解析)、mineru(复杂版面 PDF/表格与公式结构化解析)、vlm(视觉大模型整页解析)、office(Word/Excel/PPT 原生样式与表头提取)。 |
parserConfig.visionModel | body | string | 否 | documentParser=vlm 时使用的视觉大模型(如 qwen-vl-max)。 | |
parserConfig.visionProviderRef | body | string | 否 | 视觉模型的钉定 provider 引用(如 project:dashscope-prod)。 | |
parserConfig.imageUnderstanding(或顶层 imageUnderstanding) | body | object | 否 | 多模态图片理解配置:enabled(boolean,是否开启插图提取与语义转写)、providerRef(string,必填如 "project:dashscope-prod")、model(string,必填如 "qwen-vl-max")、maxConcurrency(integer,并发度 1–8,默认 4)、prompt(string,自定义视觉理解提示词)、maxImagesPerDocument(integer,单文档图片上限,默认 20)、maxDescriptionChars(integer,单图描述字数上限,默认 800)。 | |
retrievalDefaults | body | object | 否 | 检索默认值(如 similarityThreshold、vectorWeight)。 | |
ingestRoutes | body | object | 否 | 已废弃的 MIME→Function 映射,仅为兼容保留。 |
Provision 异步进行:响应中 vectorsdbDatabaseId / vectorsdbCollectionId / bucketId 可能短暂为 null,稍后重新 GET 确认。
输出:
201,返回模型 Models.KnowledgeBase。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 知识库 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
name* | string | 知识库名称。 |
description* | string | 知识库描述。 |
embeddingModel* | string | 建库时固定的 Embedding 模型 ID。 |
embeddingProviderRef* | string | 钉定的 Embedding provider 来源(project:<providerId> / trial:<bindingId>),空表示自动路由。 |
embeddingDimension* | integer | Embedding 向量维度,与模型输出一致,建库后不可改。 |
parserId* | string | 默认切片策略:general / title / smart / regex / faq。 |
parserConfig* | object | 默认解析/切片配置(动态对象,字段见创建端点)。 |
retrievalDefaults* | object | 检索默认值(如 similarityThreshold、vectorWeight、限流)。 |
vectorsdbDatabaseId* | string | Backing 的 VectorsDB 库 ID,provision 完成前为 null。 |
vectorsdbCollectionId* | string | Backing 的 VectorsDB 集合 ID,provision 完成前为 null。 |
bucketId* | string | 默认 Storage 桶 ID(文档源文件存放处),provision 完成前为 null。 |
iconFileId* | string | 头像/图标文件 ID,未设置时为 null。 |
ingestRoutes* | object | 已废弃的 MIME→Function 映射,仅为兼容保留。 |
documentCount* | integer | 库内文档总数。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"knowledgeBaseId": "kb_product_docs",
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"embeddingModel": "text-embedding-v3",
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
},
"retrievalDefaults": {
"similarityThreshold": 0.5,
"vectorWeight": 0.7
},
"ingestRoutes": {}
}'响应示例:
{
"$id": "kb_product_docs",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"embeddingModel": "text-embedding-v3",
"embeddingProviderRef": "",
"embeddingDimension": 1024,
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
},
"retrievalDefaults": {
"similarityThreshold": 0.5,
"vectorWeight": 0.7
},
"vectorsdbDatabaseId": "vdb_kb_docs",
"vectorsdbCollectionId": "col_kb_docs",
"bucketId": "bkt_kb_docs",
"iconFileId": "",
"ingestRoutes": {},
"documentCount": 12
}GET /v1/knowledgebases/{knowledgeBaseId}
SDK:KnowledgeBases.get · scope:knowledgebases.read
按 ID 获取知识库(含 provision 状态与文档计数)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 |
输出:
200,返回模型 Models.KnowledgeBase。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 知识库 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
name* | string | 知识库名称。 |
description* | string | 知识库描述。 |
embeddingModel* | string | 建库时固定的 Embedding 模型 ID。 |
embeddingProviderRef* | string | 钉定的 Embedding provider 来源(project:<providerId> / trial:<bindingId>),空表示自动路由。 |
embeddingDimension* | integer | Embedding 向量维度,与模型输出一致,建库后不可改。 |
parserId* | string | 默认切片策略:general / title / smart / regex / faq。 |
parserConfig* | object | 默认解析/切片配置(动态对象,字段见创建端点)。 |
retrievalDefaults* | object | 检索默认值(如 similarityThreshold、vectorWeight、限流)。 |
vectorsdbDatabaseId* | string | Backing 的 VectorsDB 库 ID,provision 完成前为 null。 |
vectorsdbCollectionId* | string | Backing 的 VectorsDB 集合 ID,provision 完成前为 null。 |
bucketId* | string | 默认 Storage 桶 ID(文档源文件存放处),provision 完成前为 null。 |
iconFileId* | string | 头像/图标文件 ID,未设置时为 null。 |
ingestRoutes* | object | 已废弃的 MIME→Function 映射,仅为兼容保留。 |
documentCount* | integer | 库内文档总数。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "kb_product_docs",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"embeddingModel": "text-embedding-v3",
"embeddingProviderRef": "",
"embeddingDimension": 1024,
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
},
"retrievalDefaults": {
"similarityThreshold": 0.5,
"vectorWeight": 0.7
},
"vectorsdbDatabaseId": "vdb_kb_docs",
"vectorsdbCollectionId": "col_kb_docs",
"bucketId": "bkt_kb_docs",
"iconFileId": "",
"ingestRoutes": {},
"documentCount": 12
}PATCH /v1/knowledgebases/{knowledgeBaseId}
SDK:KnowledgeBases.update · scope:knowledgebases.write
更新知识库名称、默认解析配置或检索默认值(只改传入字段)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
name | body | string | 否 | 新名称。 | |
description | body | string | 否 | 新描述。 | |
embeddingProviderRef | body | string | 否 | 钉定 Embedding provider;旧库仅可设置一次。 | |
parserId | body | string | 否 | 枚举:general / title / smart / regex / faq | 库级默认切片策略。 |
parserConfig | body | object | 否 | 库级默认解析/切片配置(子字段见下)。 | |
parserConfig.chunkTokenNum | body | integer | 否 | 每个切片的 token 预算:general/smart 默认 512,title/regex 默认 256。 | |
parserConfig.overlapPercent | body | integer | 否 | 默认 10 | general 切片器的 token 重叠百分比,默认 10。 |
parserConfig.delimiter | body | string | 否 | 超长 title/regex 切片的分隔符;默认 title 为 \n。;!?,regex 为 \n。.;;!!??。 | |
parserConfig.titleLevel | body | integer | 否 | 默认 3 | title 切片器使用的 Markdown 标题级别,默认 3。 |
parserConfig.minChunkTokens | body | integer | 否 | 默认 128 | smart 切片器最小切片大小,默认 128,不得超过 chunkTokenNum。 |
parserConfig.regexPattern | body | string | 否 | 默认 "[.!?]+\\s*" | regex 切片器使用的 PCRE 表达式,默认 [.!?]+\s*。 |
parserConfig.documentParser | body | string | 否 | 枚举:text / vlm / mineru | 文档解析器:text(纯文本)/ vlm(视觉模型)/ mineru;MinerU 部署与凭证不属于本 API。 |
parserConfig.visionModel | body | string | 否 | documentParser=vlm 时使用的视觉模型。 | |
parserConfig.visionProviderRef | body | string | 否 | 视觉模型的钉定 provider 引用。 | |
parserConfig.imageUnderstanding | body | object | 否 | 图片解读配置(动态对象):enabled=true 时 model 与 providerRef 必填;另含 prompt、maxImagesPerDocument(默认 20)、maxDescriptionChars(默认 800)、maxConcurrency(默认 4)。 | |
retrievalDefaults | body | object | 否 | 检索默认值。 | |
ingestRoutes | body | object | 否 | 已废弃字段,仅为兼容保留。 | |
iconFileId | body | string | 否 | 头像图片的文件 ID(须已上传到本库默认桶);传空串清除头像。 |
输出:
200,返回模型 Models.KnowledgeBase。embeddingModel 与 embeddingDimension 建库后固定,不可经本端点修改。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 知识库 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
name* | string | 知识库名称。 |
description* | string | 知识库描述。 |
embeddingModel* | string | 建库时固定的 Embedding 模型 ID。 |
embeddingProviderRef* | string | 钉定的 Embedding provider 来源(project:<providerId> / trial:<bindingId>),空表示自动路由。 |
embeddingDimension* | integer | Embedding 向量维度,与模型输出一致,建库后不可改。 |
parserId* | string | 默认切片策略:general / title / smart / regex / faq。 |
parserConfig* | object | 默认解析/切片配置(动态对象,字段见创建端点)。 |
retrievalDefaults* | object | 检索默认值(如 similarityThreshold、vectorWeight、限流)。 |
vectorsdbDatabaseId* | string | Backing 的 VectorsDB 库 ID,provision 完成前为 null。 |
vectorsdbCollectionId* | string | Backing 的 VectorsDB 集合 ID,provision 完成前为 null。 |
bucketId* | string | 默认 Storage 桶 ID(文档源文件存放处),provision 完成前为 null。 |
iconFileId* | string | 头像/图标文件 ID,未设置时为 null。 |
ingestRoutes* | object | 已废弃的 MIME→Function 映射,仅为兼容保留。 |
documentCount* | integer | 库内文档总数。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/knowledgebases/kb_product_docs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"parserId": "smart",
"parserConfig": {},
"retrievalDefaults": {},
"ingestRoutes": {}
}'响应示例:
{
"$id": "kb_product_docs",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"embeddingModel": "text-embedding-v3",
"embeddingProviderRef": "",
"embeddingDimension": 1024,
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
},
"retrievalDefaults": {
"similarityThreshold": 0.5,
"vectorWeight": 0.7
},
"vectorsdbDatabaseId": "vdb_kb_docs",
"vectorsdbCollectionId": "col_kb_docs",
"bucketId": "bkt_kb_docs",
"iconFileId": "",
"ingestRoutes": {},
"documentCount": 12
}DELETE /v1/knowledgebases/{knowledgeBaseId}
SDK:KnowledgeBases.delete · scope:knowledgebases.write
删除知识库,级联删除数据源(含同步历史)、文档与摄取记录,并异步回收 VectorsDB 资源。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
deleteBucket | body | boolean | 否 | 为 true 时连同默认 Storage 桶及桶内全部文件一起删除;缺省保留桶与文件。 |
输出:
204,无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/knowledgebases/kb_product_docs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"deleteBucket": true
}'GET /v1/knowledgebases/{knowledgeBaseId}/management
SDK:KnowledgeBases.getManagement · scope:knowledgebases.read
读取知识库的内容无关处理与观测摘要(最近摄取、trace、评分)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
limit | query | integer | 否 | 默认 10 | 最近摄取/trace/评分各包含的最大条数,默认 10。 |
from | query | string | 否 | 默认 "" | 观测时间窗起点(ISO 8601)。 |
to | query | string | 否 | 默认 "" | 观测时间窗终点(ISO 8601)。 |
输出:
200,返回宽类型 JSON 对象(spec 未固定 schema)。典型包含:最近摄取任务摘要(状态/阶段/耗时)、检索 trace 摘要与评分记录;字段以实际部署返回为准,此处给出示意骨架。
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/management?limit=10&from=2026-09-01T00:00:00Z&to=2026-09-14T00:00:00Z" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"recentIngestions": [
{
"$id": "ing_3301",
"documentId": "doc_manual_v2",
"status": "ready",
"stage": "embedding"
}
],
"recentTraces": [
{
"traceId": "4c9f2ab1",
"operation": "search",
"durationMs": 210
}
],
"recentScores": [
{
"documentId": "doc_manual_v2",
"score": 0.91,
"ratedAt": "2026-09-14T08:00:00.000+00:00"
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/reindex
SDK:KnowledgeBases.createReindex · scope:knowledgebases.write
把就绪文档有界分批地重新入队摄取(改库级解析配置后生效用)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
limit | body | integer | 否 | 本批最多入队的就绪文档数。 | |
cursor | body | string | 否 | 上一批响应返回的文档游标。 | |
idempotencyKey | body | string | 否 | 批量幂等键,防止重复入队。 |
输出:
202,返回模型 Models.KnowledgeBaseReindex;nextCursor 非 null 时携带它继续调用下一批。
| 字段 | 类型 | 说明 |
|---|---|---|
queued* | integer | 本批成功入队重摄取的就绪文档数。 |
skipped* | integer | 因已有活跃摄取而跳过的文档数。 |
failed* | integer | 本批入队失败的文档数。 |
nextCursor* | string | 下一批游标;null 表示全部完成。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/reindex" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"limit": 50,
"cursor": "cur_doc_0086",
"idempotencyKey": "idem-reindex-01"
}'响应示例:
{
"queued": 12,
"skipped": 0,
"failed": 0,
"nextCursor": null
}语义检索
POST /v1/knowledgebases/{knowledgeBaseId}/search
SDK:KnowledgeBases.createSearch · scope:knowledgebases.read
单库向量 / 全文 / 混合检索,可经 LLM Gateway 重排,返回带评分与出处的切片。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
query | body | string | 是 | 查询文本。 | |
limit | body | integer | 否 | 默认 10 | 最终返回条数,范围 1–100。 |
searchMode | body | string | 否 | 默认 hybrid;枚举:vector / fulltext / hybrid | 检索模式。 |
rerank | body | boolean | 否 | 默认 false | 为 true 时先扩大召回再经 LLM Gateway 对候选重排,最后截断到 limit。 |
recallLimit | body | integer | 否 | rerank 时省略默认 min(100, max(limit×4, 20));显式值 1–100 且不得小于 limit | 启用 rerank 时的召回宽度;关闭 rerank 时不使用。 |
rerankModel | body | string | 否 | 显式 rerank 模型 ID;启用 rerank 时覆盖自动选择。 | |
rerankProviderRef | body | string | 否 | 钉定 rerank provider:project:<providerId> 或 trial:<bindingId>;不要用 providerType:providerId 形式。 | |
similarityThreshold | body | number | 否 | 向量最低相似度阈值(作用于向量与 hybrid 的向量分支);省略用库 retrievalDefaults.similarityThreshold。 | |
vectorWeight | body | number | 否 | hybrid 向量分支权重(全文取 1 - vectorWeight);省略用库 retrievalDefaults.vectorWeight。 | |
useKnowledgeGraph | body | boolean | 否 | 默认 false | true 时加入当前可用的 GraphRAG 检索结果。 |
useWiki | body | boolean | 否 | 默认 false | true 时加入当前可用的 Wiki 检索结果。 |
graphOptions | body | object | 否 | 默认 {} | 有界 GraphRAG 检索选项;仅在 useKnowledgeGraph=true 时使用。 |
wikiOptions | body | object | 否 | 默认 {} | Wiki 检索选项,包括路由模式、topK、minK、向量与有界链接扩展;仅在 useWiki=true 时使用。 |
allowDegraded | body | boolean | 否 | 默认 true | 增强检索遇到可降级错误时,是否返回普通检索结果并列出 degradedCapabilities;设为 false 时错误向上返回。 |
answer | body | boolean | 否 | 默认 false | 答案合成(2.9.0):true 时用知识库 indexingDefaults 的 chat 模型对合并证据做接地合成(最多 12 行证据、答案 ≤1024 tokens),响应带 answer 对象。 |
documentTag | body | string | 否 | 文档定位标识精确匹配(2.10.0):{subProductId}_{sectionCode}_{fileKey};收窄切片、GraphRAG 与 Wiki 召回范围。 | |
subProductId | body | string | 否 | 子产品编码过滤(2.10.0):按 metadata.subProductId(或 documentTag 首段)收窄召回;与 documentTag 同为 AND 语义。 | |
metadataFilter | body | object | 否 | 文档元数据过滤(2.10.0):先筛文档再召回切片,未命中文档的切片被排除。 | |
versionId | body | string | 否 | 省略时版本化知识库默认当前 READY 版本 | 可选版本 ID;检索针对选定版本执行。 |
输出:
200,返回模型 Models.KnowledgeBaseSearchResultList:results[] 含命中切片、score(重排分或检索分)与可选 imageContexts;reranked 指示重排是否成功。本端点受库级 retrievalDefaults.rateLimit/rateLimitPeriod 与项目限流双重约束。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 返回的结果条数。 |
results* | object[] | 检索结果列表。 |
$id* | string | 命中的切片文档 ID。 |
content* | string | 命中切片正文。 |
sourceId* | string | 切片所属的知识库文档 ID。 |
source* | object | 来源文档描述与受保护源 URI(动态对象)。 |
locator* | object | 切片的章节/原文定位器(动态对象)。 |
metadata* | object | 切片元数据(剔除内部溯源字段)。 |
imageContexts* | object[] | 切片内已解读图片的关联投影(仅响应,不改切片)。 |
score* | number | 最终排序得分:重排成功用 reranker 分数,否则用初始检索分。 |
indexSource* | string | 结果来源:rag、raptor、graphrag 或 wiki。 |
resultType* | string | 结果类型:chunk、raptor_summary、graph_context 或 wiki_page。 |
resultGeneration | string / null | 派生索引结果代;普通 RAG 切片为 null。 |
reranked* | boolean | 是否经 LLM Gateway 重排成功;自动 rerank 失败降级时为 false。 |
resolvedVersionId | string / null | 本次搜索实际使用的版本;未启用版本化读取时为 null。 |
capabilities* | object | RAPTOR、GraphRAG 与 Wiki 的状态、耗时、结果代、结果及脱敏错误。 |
degradedCapabilities* | object[] | 明确发生降级的增强能力;未降级时为空数组。 |
answer | object / null | 答案合成结果(2.9.0):状态 / 文本 / 模型 / 延迟;未请求答案合成时为 null。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/search" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"query": "早餐机首次使用要注意什么",
"limit": 5,
"searchMode": "hybrid",
"rerank": false,
"similarityThreshold": 0.5,
"vectorWeight": 0.7
}'响应示例:
{
"total": 2,
"results": [
{
"$id": "chk_0042",
"content": "早餐机首次使用前请用温水清洗内胆,并空烧一次完成除味。",
"sourceId": "doc_manual_v2",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 12
},
"metadata": {
"page": 17
},
"imageContexts": [],
"score": 0.91
},
{
"$id": "chk_0043",
"content": "清洗后首次空烧时若有轻微气味属正常现象,通风放置即可。",
"sourceId": "doc_manual_v2",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 13
},
"metadata": {
"page": 17
},
"imageContexts": [
{
"chunkReferenceIndex": 0,
"url": "/v1/storage/bkt_kb_docs/files/file_img_01/view",
"description": "早餐机正面部件示意图:内胆、蒸汽阀与控制面板位置标注。"
}
],
"score": 0.86
}
],
"reranked": false
}POST /v1/knowledgebases/search
SDK:KnowledgeBases.createMultiSearch · scope:knowledgebases.read
跨库检索(1–10 个库):各库独立召回 → RRF 合并 → 统一重排一次,全局排序返回。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseIds | body | string[] | 是 | 知识库 ID 数组,1–10 个且不重复。 | |
query | body | string | 是 | 查询文本。 | |
limit | body | integer | 否 | 全局 TopK(所有库合并后的最终条数)。 | |
searchMode | body | string | 否 | 枚举:vector / fulltext / hybrid | 检索模式:vector / fulltext / hybrid。 |
rerank | body | boolean | 否 | 为 true 时各库独立召回候选,服务端先跨库 RRF 合并,再仅对合并候选池执行一次 rerank。 | |
recallLimit | body | integer | 否 | 全局召回宽度,上限 100,且必须 ≥ limit 且 ≥ 所选知识库数量。 | |
rerankModel | body | string | 否 | 显式 rerank 模型 ID。 | |
rerankProviderRef | body | string | 否 | 钉定 rerank provider(project: / trial: 前缀)。 | |
similarityThreshold | body | number | 否 | 作用于每个库的最低相似度;省略用各库默认。 | |
vectorWeight | body | number | 否 | 作用于每个库的 hybrid 向量权重;省略用各库默认。 | |
documentTag | body | string | 否 | 文档定位标识精确匹配(2.10.0):逐库作用于切片召回。 | |
subProductId | body | string | 否 | 子产品编码过滤(2.10.0):逐库收窄召回范围。 | |
metadataFilter | body | object | 否 | 文档元数据过滤(2.10.0):按知识库 ID 分键,可带 "*" 键兜底作用于未单独配置的库;先筛文档再召回。 | |
offset | body | integer | 否 | 0 | 融合排序后跳过的结果条数(2.10.0),与 limit 组合分页。 |
输出:
200,返回模型 Models.KnowledgeBaseMultiSearchResultList,每条结果额外携带 knowledgeBaseId。严格失败语义:任一库不存在/未 provision/被限流/检索失败则整个请求失败;自动 rerank 失败降级为 RRF 顺序并置 reranked=false。preflight、召回、全局 rerank 与序列化共享 30 秒请求级总时限,超时返回 408。响应头 X-RateLimit-Limit/Remaining 取各库最小值,X-RateLimit-Reset 取最晚值,X-AppBase-Trace-Id 为本次跨库请求的统一关联 ID。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 返回的结果条数。 |
results* | object[] | 全局排序的结果列表。 |
$id* | string | 命中的切片文档 ID。 |
knowledgeBaseId* | string | 该切片所在的知识库 ID;跨库稳定标识用 (knowledgeBaseId, $id)。 |
content* | string | 命中切片正文。 |
sourceId* | string | 切片所属的知识库文档 ID。 |
source* | object | 来源文档描述与受保护源 URI(动态对象)。 |
locator* | object | 切片的章节/原文定位器(动态对象)。 |
metadata* | object | 切片元数据(剔除内部溯源字段)。 |
imageContexts* | object[] | 切片内已解读图片的关联投影(仅响应,不改切片)。 |
score* | number | 最终得分:全局重排成功用 reranker 分数,否则用跨库 RRF 分数。 |
reranked* | boolean | 合并结果是否经一次 LLM Gateway 重排成功。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/search" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"knowledgeBaseIds": [
"kb_product_docs",
"kb_faq"
],
"query": "早餐机保修多久",
"limit": 8,
"searchMode": "hybrid",
"rerank": true,
"similarityThreshold": 0,
"vectorWeight": 0
}'响应示例:
{
"total": 2,
"results": [
{
"$id": "chk_0042",
"knowledgeBaseId": "kb_product_docs",
"content": "早餐机首次使用前请用温水清洗内胆,并空烧一次完成除味。",
"sourceId": "doc_manual_v2",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 12
},
"metadata": {
"page": 17
},
"imageContexts": [],
"score": 0.91
},
{
"$id": "chk_faq_007",
"knowledgeBaseId": "kb_faq",
"content": "早餐机整机保修 12 个月,加热元件保修 24 个月。",
"sourceId": "doc_faq_v1",
"source": {
"documentId": "doc_faq_v1",
"uri": "/v1/knowledgebases/kb_faq/documents/doc_faq_v1/source"
},
"locator": {
"generation": "gen_1",
"chapter": 2,
"order": 3
},
"metadata": {},
"imageContexts": [],
"score": 0.84
}
],
"reranked": false
}文档管理
GET /v1/knowledgebases/{knowledgeBaseId}/documents
SDK:KnowledgeBases.listDocuments · scope:knowledgebases.read
列出知识库内文档,可按 status/stage/enabled 过滤或用 queries 高级查询。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
status | query | string | 否 | 默认 "" | 按处理状态过滤:uploaded / processing / ready / failed。 |
stage | query | string | 否 | 默认 "" | 按处理阶段过滤。 |
enabled | query | boolean | 否 | 按启用状态过滤。 | |
documentTag | query | string | 否 | 按文档定位标识精确过滤(2.10.0)。 | |
subProductId | query | string | 否 | 按子产品编码精确过滤(2.10.0)。 | |
queries | query | string[] | 否 | 默认 [] | Appbase Query 高级查询串数组,最多 100 条、单条 4096 字符。 |
输出:
200,返回模型 Models.KnowledgeBaseDocumentList。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 匹配查询的文档总数。 |
documents* | object[] | 文档列表。 |
$id* | string | 文档 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 所属知识库 ID。 |
name* | string | 文档显示名。 |
bucketId* | string | 源文件所在 Storage 桶 ID。 |
fileId* | string | 源文件 Storage 文件 ID。 |
mimeType* | string | 源文件 MIME 类型。 |
source* | string | 来源:manual 手工上传,datasource:{id} 数据源同步,yuque:personal 个人语雀导入。 |
externalItemId* | string | 外部系统条目 ID,数据源同步据此去重更新。 |
parserId* | string | 文档级切片策略覆盖,空为继承库默认。 |
parserConfig* | object | 文档级解析/切片配置覆盖。 |
metadata* | object | 业务元数据。 |
status* | string | 处理状态:uploaded 已登记 / processing 处理中 / ready 就绪 / failed 失败。 |
enabled* | boolean | 是否参与检索;false 时切片保留但不进检索结果。 |
stage* | string | 当前/最近一次摄取的流水线阶段镜像。 |
activeIngestionId* | string | 当前或最近一次摄取任务 ID。 |
activeGeneration* | string | 检索可见代数(generation),仅 status=ready 时有效。 |
processingStartedAt* | string | 最近一次触发处理的时间。 |
chunksTotal* | integer | 预期切片总数(已知后填充)。 |
chunkCount* | integer | 活跃代数中的切片数。 |
error* | string | 最近一次处理错误信息,正常为空串。 |
lastExecutionId* | string | 已废弃的旧 Function 执行 ID。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents?status=ready&stage=embedding&enabled=true" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 2,
"documents": [
{
"$id": "doc_manual_v2",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-01T08:00:31.000+00:00",
"kbId": "kb_product_docs",
"name": "产品使用手册 v2.pdf",
"bucketId": "bkt_kb_docs",
"fileId": "file_9a11cc",
"mimeType": "application/pdf",
"source": "manual",
"externalItemId": "",
"parserId": "",
"parserConfig": {},
"metadata": {
"edition": "v2"
},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3301",
"activeGeneration": "gen_3",
"processingStartedAt": "2026-09-01T08:00:01.000+00:00",
"chunksTotal": 86,
"chunkCount": 86,
"error": "",
"lastExecutionId": ""
},
{
"$id": "doc_faq_v1",
"$createdAt": "2026-09-02T09:00:00.000+00:00",
"$updatedAt": "2026-09-02T09:00:40.000+00:00",
"kbId": "kb_product_docs",
"name": "售后 FAQ.docx",
"bucketId": "bkt_kb_docs",
"fileId": "file_9b22aa",
"mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"source": "manual",
"externalItemId": "",
"parserId": "faq",
"parserConfig": {},
"metadata": {},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3312",
"activeGeneration": "gen_1",
"processingStartedAt": "2026-09-02T09:00:05.000+00:00",
"chunksTotal": 21,
"chunkCount": 21,
"error": "",
"lastExecutionId": ""
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/documents
SDK:KnowledgeBases.createDocument · scope:knowledgebases.write
把已上传到 Storage 的文件登记为文档(登记本身不触发摄取,需再调摄取端点)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
bucketId | body | string | 否 | 源文件所在桶 ID;缺省用库默认桶。 | |
fileId | body | string | 是 | 已上传源文件的 Storage 文件 ID(必填)。 | |
name | body | string | 否 | 文档显示名,缺省用源文件名。 | |
source | body | string | 否 | 文档来源标记,默认 manual。 | |
externalItemId | body | string | 否 | 来自外部数据源时的条目 ID(同步去重用)。 | |
documentTag | body | string | 否 | 文档定位标识(2.10.0):{subProductId}_{sectionCode}_{fileKey}(subProductId 字母/数字、sectionCode 数字、fileKey 必填 32 位无连字符 hex),存入 metadata.documentTag。 | |
subProductId | body | string | 否 | 子产品编码(2.10.0,1–64 位字母/数字),存入 metadata.subProductId;同时提交非空 documentTag 并省略或清空本字段时,仍从定位标识首段派生。召回接口使用独立字段或定位标识首段过滤。 | |
sectionCode | body | string | 否 | 章节编码(2.10.0,1–64 位数字);documentTag 省略时嵌入自动生成的定位标识。 | |
parserId(或 chunkingStrategy) | body | string | 否 | 枚举:general / title / smart / regex / faq / sheet | 文档级分块策略覆盖(省略时继承知识库默认策略)。 |
parser | body | string | 否 | 枚举:text / mineru / vlm / office | 文档级解析引擎简写覆盖(等价于 parserConfig.documentParser)。 |
parserConfig | body | object | 否 | 文档级解析/分块与多模态配置覆盖(子字段见下)。 | |
parserConfig.chunkTokenNum | body | integer | 否 | 每个切片的 token 预算:general/smart 默认 512,title/regex 默认 256。 | |
parserConfig.overlapPercent | body | integer | 否 | 默认 10 | general/smart 切片器的 token 重叠百分比,默认 10。 |
parserConfig.delimiter | body | string | 否 | 超长 title/regex 切片的分隔符;默认 title 为 \n。;!?,regex 为 \n。.;;!!??。 | |
parserConfig.titleLevel | body | integer | 否 | 默认 3 | title 切片器使用的 Markdown 标题级别,默认 3。 |
parserConfig.minChunkTokens | body | integer | 否 | 默认 128 | smart 切片器最小切片大小,默认 128,不得超过 chunkTokenNum。 |
parserConfig.regexPattern | body | string | 否 | 默认 "[.!?]+\\s*" | regex 切片器使用的 PCRE 表达式,默认 [.!?]+\s*。 |
parserConfig.documentParser | body | string | 否 | 枚举:text / mineru / vlm / office | 文档解析引擎:text(纯文本)/ mineru(MinerU 复杂版面与表格解析)/ vlm(视觉大模型整页解析)/ office(Office 结构化提取)。 |
parserConfig.visionModel | body | string | 否 | documentParser=vlm 时使用的视觉模型(如 qwen-vl-max)。 | |
parserConfig.visionProviderRef | body | string | 否 | 视觉模型的钉定 provider 引用(如 project:dashscope-prod)。 | |
parserConfig.imageUnderstanding(或顶层 imageUnderstanding) | body | object | 否 | 多模态图片理解配置:enabled(boolean)、providerRef(string,如 "project:dashscope-prod")、model(string,如 "qwen-vl-max")、maxConcurrency(integer,默认 4)、prompt(string)、maxImagesPerDocument(默认 20)、maxDescriptionChars(默认 800)。 | |
metadata | body | object | 否 | 业务元数据。 |
登记后调用 POST .../ingestions(或 POST .../process)触发解析 → 切片 → Embedding 流水线。
输出:
201,返回模型 Models.KnowledgeBaseDocument(初始 status=uploaded)。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 文档 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 所属知识库 ID。 |
name* | string | 文档显示名。 |
bucketId* | string | 源文件所在 Storage 桶 ID。 |
fileId* | string | 源文件 Storage 文件 ID。 |
mimeType* | string | 源文件 MIME 类型。 |
source* | string | 来源:manual 手工上传,datasource:{id} 数据源同步,yuque:personal 个人语雀导入。 |
externalItemId* | string | 外部系统条目 ID,数据源同步据此去重更新。 |
parserId* | string | 文档级切片策略覆盖,空为继承库默认。 |
parserConfig* | object | 文档级解析/切片配置覆盖。 |
metadata* | object | 业务元数据。 |
status* | string | 处理状态:uploaded 已登记 / processing 处理中 / ready 就绪 / failed 失败。 |
enabled* | boolean | 是否参与检索;false 时切片保留但不进检索结果。 |
stage* | string | 当前/最近一次摄取的流水线阶段镜像。 |
activeIngestionId* | string | 当前或最近一次摄取任务 ID。 |
activeGeneration* | string | 检索可见代数(generation),仅 status=ready 时有效。 |
processingStartedAt* | string | 最近一次触发处理的时间。 |
chunksTotal* | integer | 预期切片总数(已知后填充)。 |
chunkCount* | integer | 活跃代数中的切片数。 |
error* | string | 最近一次处理错误信息,正常为空串。 |
lastExecutionId* | string | 已废弃的旧 Function 执行 ID。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"fileId": "file_9a11cc",
"name": "产品使用手册 v2.pdf",
"source": "ops-console",
"parserId": "smart",
"parserConfig": {},
"metadata": {
"edition": "v2"
}
}'多解析器与分块/多模态图片理解高级调用示例(SIT 基准环境 kb_enterprise_support):
curl -X POST "https://appbuild-sit.oceanbase.com/v1/knowledgebases/kb_enterprise_support/documents" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"bucketId": "kb_enterprise_docs",
"fileId": "file_ob_arch_v43",
"name": "OceanBase-V4.3-高可用架构白皮书.pdf",
"source": "manual",
"documentTag": "oceanbase_4301_8f9a2b3c4d5e6f708192a3b4c5d6e7f8",
"subProductId": "oceanbase",
"sectionCode": "4301",
"parser": "mineru",
"chunkingStrategy": "smart",
"parserId": "smart",
"parserConfig": {
"documentParser": "mineru",
"chunkTokenNum": 600,
"minChunkTokens": 150,
"overlapPercent": 15,
"imageUnderstanding": {
"enabled": true,
"providerRef": "project:dashscope-prod",
"model": "qwen-vl-max",
"maxConcurrency": 4,
"maxImagesPerDocument": 20,
"maxDescriptionChars": 800,
"prompt": "请提取架构图与故障排查流程图中的核心组件、数据流向与告警阈值,输出结构化文字说明。"
}
},
"imageUnderstanding": {
"enabled": true,
"providerRef": "project:dashscope-prod",
"model": "qwen-vl-max",
"maxConcurrency": 4,
"prompt": "请提取架构图与故障排查流程图中的核心组件、数据流向与告警阈值,输出结构化文字说明。"
},
"metadata": {
"department": "DBA支持中心",
"version": "4.3"
}
}'响应示例:
{
"$id": "doc_manual_v2",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"name": "产品使用手册 v2.pdf",
"bucketId": "bkt_kb_docs",
"fileId": "file_9a11cc",
"mimeType": "application/pdf",
"source": "manual",
"externalItemId": "",
"parserId": "",
"parserConfig": {},
"metadata": {
"edition": "v2"
},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3301",
"activeGeneration": "gen_3",
"processingStartedAt": "2026-09-01T08:00:01.000+00:00",
"chunksTotal": 86,
"chunkCount": 86,
"error": "",
"lastExecutionId": ""
}POST /v1/knowledgebases/{knowledgeBaseId}/documents/batch
SDK:KnowledgeBases.createDocumentsBatch · scope:knowledgebases.write
批量登记文档(1–50 个文件,先整体校验再创建)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
fileIds | body | string[] | 是 | Storage 文件 ID 数组,1–50 个且不重复。 | |
bucketId | body | string | 否 | 文件所在桶;缺省用库默认桶,全部文件须同桶。 | |
source | body | string | 否 | 所有文档的来源标记,默认 manual。 | |
parserId | body | string | 否 | 枚举:general / title / smart / regex / faq | 文档级切片策略覆盖(对本批生效)。 |
parserConfig | body | object | 否 | 文档级解析/切片配置覆盖(对本批生效,子字段见下)。 | |
parserConfig.chunkTokenNum | body | integer | 否 | 每个切片的 token 预算:general/smart 默认 512,title/regex 默认 256。 | |
parserConfig.overlapPercent | body | integer | 否 | 默认 10 | general 切片器的 token 重叠百分比,默认 10。 |
parserConfig.delimiter | body | string | 否 | 超长 title/regex 切片的分隔符;默认 title 为 \n。;!?,regex 为 \n。.;;!!??。 | |
parserConfig.titleLevel | body | integer | 否 | 默认 3 | title 切片器使用的 Markdown 标题级别,默认 3。 |
parserConfig.minChunkTokens | body | integer | 否 | 默认 128 | smart 切片器最小切片大小,默认 128,不得超过 chunkTokenNum。 |
parserConfig.regexPattern | body | string | 否 | 默认 "[.!?]+\\s*" | regex 切片器使用的 PCRE 表达式,默认 [.!?]+\s*。 |
parserConfig.documentParser | body | string | 否 | 枚举:text / vlm / mineru | 文档解析器:text(纯文本)/ vlm(视觉模型)/ mineru;MinerU 部署与凭证不属于本 API。 |
parserConfig.visionModel | body | string | 否 | documentParser=vlm 时使用的视觉模型。 | |
parserConfig.visionProviderRef | body | string | 否 | 视觉模型的钉定 provider 引用。 | |
parserConfig.imageUnderstanding | body | object | 否 | 图片解读配置(动态对象):enabled=true 时 model 与 providerRef 必填;另含 prompt、maxImagesPerDocument(默认 20)、maxDescriptionChars(默认 800)、maxConcurrency(默认 4)。 | |
metadata | body | object | 否 | 本批文档共享的业务元数据。 |
输出:
201,返回模型 Models.KnowledgeBaseDocumentList;随后需逐文档发起摄取。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 匹配查询的文档总数。 |
documents* | object[] | 文档列表。 |
$id* | string | 文档 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 所属知识库 ID。 |
name* | string | 文档显示名。 |
bucketId* | string | 源文件所在 Storage 桶 ID。 |
fileId* | string | 源文件 Storage 文件 ID。 |
mimeType* | string | 源文件 MIME 类型。 |
source* | string | 来源:manual 手工上传,datasource:{id} 数据源同步,yuque:personal 个人语雀导入。 |
externalItemId* | string | 外部系统条目 ID,数据源同步据此去重更新。 |
parserId* | string | 文档级切片策略覆盖,空为继承库默认。 |
parserConfig* | object | 文档级解析/切片配置覆盖。 |
metadata* | object | 业务元数据。 |
status* | string | 处理状态:uploaded 已登记 / processing 处理中 / ready 就绪 / failed 失败。 |
enabled* | boolean | 是否参与检索;false 时切片保留但不进检索结果。 |
stage* | string | 当前/最近一次摄取的流水线阶段镜像。 |
activeIngestionId* | string | 当前或最近一次摄取任务 ID。 |
activeGeneration* | string | 检索可见代数(generation),仅 status=ready 时有效。 |
processingStartedAt* | string | 最近一次触发处理的时间。 |
chunksTotal* | integer | 预期切片总数(已知后填充)。 |
chunkCount* | integer | 活跃代数中的切片数。 |
error* | string | 最近一次处理错误信息,正常为空串。 |
lastExecutionId* | string | 已废弃的旧 Function 执行 ID。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/batch" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"fileIds": [
"file_9a11cc",
"file_9a12dd"
],
"source": "manual",
"parserId": "smart",
"parserConfig": {},
"metadata": {
"topic": "早餐店经营"
}
}'响应示例:
{
"total": 2,
"documents": [
{
"$id": "doc_manual_v2",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-01T08:00:31.000+00:00",
"kbId": "kb_product_docs",
"name": "产品使用手册 v2.pdf",
"bucketId": "bkt_kb_docs",
"fileId": "file_9a11cc",
"mimeType": "application/pdf",
"source": "manual",
"externalItemId": "",
"parserId": "",
"parserConfig": {},
"metadata": {
"edition": "v2"
},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3301",
"activeGeneration": "gen_3",
"processingStartedAt": "2026-09-01T08:00:01.000+00:00",
"chunksTotal": 86,
"chunkCount": 86,
"error": "",
"lastExecutionId": ""
},
{
"$id": "doc_faq_v1",
"$createdAt": "2026-09-02T09:00:00.000+00:00",
"$updatedAt": "2026-09-02T09:00:40.000+00:00",
"kbId": "kb_product_docs",
"name": "售后 FAQ.docx",
"bucketId": "bkt_kb_docs",
"fileId": "file_9b22aa",
"mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"source": "manual",
"externalItemId": "",
"parserId": "faq",
"parserConfig": {},
"metadata": {},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3312",
"activeGeneration": "gen_1",
"processingStartedAt": "2026-09-02T09:00:05.000+00:00",
"chunksTotal": 21,
"chunkCount": 21,
"error": "",
"lastExecutionId": ""
}
]
}GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}
SDK:KnowledgeBases.getDocument · scope:knowledgebases.read
按 ID 获取文档(含处理状态、代数与切片计数)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 |
输出:
200,返回模型 Models.KnowledgeBaseDocument。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 文档 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 所属知识库 ID。 |
name* | string | 文档显示名。 |
bucketId* | string | 源文件所在 Storage 桶 ID。 |
fileId* | string | 源文件 Storage 文件 ID。 |
mimeType* | string | 源文件 MIME 类型。 |
source* | string | 来源:manual 手工上传,datasource:{id} 数据源同步,yuque:personal 个人语雀导入。 |
externalItemId* | string | 外部系统条目 ID,数据源同步据此去重更新。 |
parserId* | string | 文档级切片策略覆盖,空为继承库默认。 |
parserConfig* | object | 文档级解析/切片配置覆盖。 |
metadata* | object | 业务元数据。 |
status* | string | 处理状态:uploaded 已登记 / processing 处理中 / ready 就绪 / failed 失败。 |
enabled* | boolean | 是否参与检索;false 时切片保留但不进检索结果。 |
stage* | string | 当前/最近一次摄取的流水线阶段镜像。 |
activeIngestionId* | string | 当前或最近一次摄取任务 ID。 |
activeGeneration* | string | 检索可见代数(generation),仅 status=ready 时有效。 |
processingStartedAt* | string | 最近一次触发处理的时间。 |
chunksTotal* | integer | 预期切片总数(已知后填充)。 |
chunkCount* | integer | 活跃代数中的切片数。 |
error* | string | 最近一次处理错误信息,正常为空串。 |
lastExecutionId* | string | 已废弃的旧 Function 执行 ID。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "doc_manual_v2",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"name": "产品使用手册 v2.pdf",
"bucketId": "bkt_kb_docs",
"fileId": "file_9a11cc",
"mimeType": "application/pdf",
"source": "manual",
"externalItemId": "",
"parserId": "",
"parserConfig": {},
"metadata": {
"edition": "v2"
},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3301",
"activeGeneration": "gen_3",
"processingStartedAt": "2026-09-01T08:00:01.000+00:00",
"chunksTotal": 86,
"chunkCount": 86,
"error": "",
"lastExecutionId": ""
}PATCH /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}
SDK:KnowledgeBases.updateDocument · scope:knowledgebases.write
更新文档名称、切片覆盖配置、元数据或启用状态(只改传入字段)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 | |
name | body | string | 否 | 文档显示名。 | |
parserId | body | string | 否 | 枚举:general / title / smart / regex / faq / (空,表示不限) | 文档级切片策略覆盖;传空串清除覆盖、回退库默认。 |
parserConfig | body | object | 否 | 文档级解析/切片配置覆盖(子字段见下)。 | |
parserConfig.chunkTokenNum | body | integer | 否 | 每个切片的 token 预算:general/smart 默认 512,title/regex 默认 256。 | |
parserConfig.overlapPercent | body | integer | 否 | 默认 10 | general 切片器的 token 重叠百分比,默认 10。 |
parserConfig.delimiter | body | string | 否 | 超长 title/regex 切片的分隔符;默认 title 为 \n。;!?,regex 为 \n。.;;!!??。 | |
parserConfig.titleLevel | body | integer | 否 | 默认 3 | title 切片器使用的 Markdown 标题级别,默认 3。 |
parserConfig.minChunkTokens | body | integer | 否 | 默认 128 | smart 切片器最小切片大小,默认 128,不得超过 chunkTokenNum。 |
parserConfig.regexPattern | body | string | 否 | 默认 "[.!?]+\\s*" | regex 切片器使用的 PCRE 表达式,默认 [.!?]+\s*。 |
parserConfig.documentParser | body | string | 否 | 枚举:text / vlm / mineru | 文档解析器:text(纯文本)/ vlm(视觉模型)/ mineru;MinerU 部署与凭证不属于本 API。 |
parserConfig.visionModel | body | string | 否 | documentParser=vlm 时使用的视觉模型。 | |
parserConfig.visionProviderRef | body | string | 否 | 视觉模型的钉定 provider 引用。 | |
parserConfig.imageUnderstanding | body | object | 否 | 图片解读配置(动态对象):enabled=true 时 model 与 providerRef 必填;另含 prompt、maxImagesPerDocument(默认 20)、maxDescriptionChars(默认 800)、maxConcurrency(默认 4)。 | |
metadata | body | object | 否 | 业务元数据。 | |
documentTag | body | string | 否 | 更新文档定位标识(2.10.0,格式同创建);空字符串清除。 | |
subProductId | body | string | 否 | 更新子产品编码(2.10.0);同时提交非空 documentTag 并省略或清空本字段时仍派生首段。未同时提交非空标签时,空字符串删除独立字段,但有效过滤值仍会回退到已有标签首段;要移除二者须同时清空两个字段。 | |
enabled | body | boolean | 否 | 置 false 后文档切片保留但不参与检索结果。 | |
status | body | string | 否 | 处理状态(仅 API Key 可改的遗留修正字段)。 | |
stage | body | string | 否 | 处理阶段(仅 API Key 可改的遗留修正字段)。 | |
chunksTotal | body | integer | 否 | 切片总数(仅 API Key 可改的遗留修正字段)。 | |
chunkCount | body | integer | 否 | 切片数(仅 API Key 可改的遗留修正字段)。 | |
error | body | string | 否 | 错误信息(仅 API Key 可改的遗留修正字段)。 |
输出:
200,返回模型 Models.KnowledgeBaseDocument。存在排队/运行/取消中的摄取时不可改 parserId/parserConfig。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 文档 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 所属知识库 ID。 |
name* | string | 文档显示名。 |
bucketId* | string | 源文件所在 Storage 桶 ID。 |
fileId* | string | 源文件 Storage 文件 ID。 |
mimeType* | string | 源文件 MIME 类型。 |
source* | string | 来源:manual 手工上传,datasource:{id} 数据源同步,yuque:personal 个人语雀导入。 |
externalItemId* | string | 外部系统条目 ID,数据源同步据此去重更新。 |
parserId* | string | 文档级切片策略覆盖,空为继承库默认。 |
parserConfig* | object | 文档级解析/切片配置覆盖。 |
metadata* | object | 业务元数据。 |
status* | string | 处理状态:uploaded 已登记 / processing 处理中 / ready 就绪 / failed 失败。 |
enabled* | boolean | 是否参与检索;false 时切片保留但不进检索结果。 |
stage* | string | 当前/最近一次摄取的流水线阶段镜像。 |
activeIngestionId* | string | 当前或最近一次摄取任务 ID。 |
activeGeneration* | string | 检索可见代数(generation),仅 status=ready 时有效。 |
processingStartedAt* | string | 最近一次触发处理的时间。 |
chunksTotal* | integer | 预期切片总数(已知后填充)。 |
chunkCount* | integer | 活跃代数中的切片数。 |
error* | string | 最近一次处理错误信息,正常为空串。 |
lastExecutionId* | string | 已废弃的旧 Function 执行 ID。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "产品使用手册 v2.pdf",
"parserId": "general",
"parserConfig": {},
"metadata": {
"topic": "早餐店经营"
},
"enabled": true,
"chunksTotal": 0,
"chunkCount": 0
}'响应示例:
{
"$id": "doc_manual_v2",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"name": "产品使用手册 v2.pdf",
"bucketId": "bkt_kb_docs",
"fileId": "file_9a11cc",
"mimeType": "application/pdf",
"source": "manual",
"externalItemId": "",
"parserId": "",
"parserConfig": {},
"metadata": {
"edition": "v2"
},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3301",
"activeGeneration": "gen_3",
"processingStartedAt": "2026-09-01T08:00:01.000+00:00",
"chunksTotal": 86,
"chunkCount": 86,
"error": "",
"lastExecutionId": ""
}DELETE /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}
SDK:KnowledgeBases.deleteDocument · scope:knowledgebases.write
删除文档:级联删除其全部切片(VectorsDB)、摄取记录并递减库文档计数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 |
输出:
204,无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"POST /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/process
SDK:KnowledgeBases.createDocumentProcess · scope:knowledgebases.write
以当前配置对既有文档触发一次(重)处理,等价于默认参数创建摄取。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 |
输出:
202,返回模型 Models.KnowledgeBaseIngestion。异步任务:轮询 GET .../ingestions/{ingestionId} 直至终态(ready / failed / cancelled),或订阅响应中 trackingChannels 的 Realtime 频道。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 摄取任务 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 知识库 ID。 |
documentId* | string | 文档 ID。 |
status* | string | 任务状态:queued / running / ready / failed / cancelling / cancelled。 |
stage* | string | 当前流水线阶段(解析 → 切片 → Embedding)。 |
generation* | string | 本次摄取写入的代数。 |
progress* | object | 进度对象:completed / total / unit。 |
effectiveConfig* | object | 本次摄取冻结生效的配置快照。 |
configHash* | string | effectiveConfig 哈希,用于比对配置是否变化。 |
retryOf* | string | 重试时指向的前次摄取 ID。 |
attemptId* | string | 本次尝试的 fencing token。 |
idempotencyKey* | string | 请求方幂等键。 |
error* | string | failed 时的错误信息。 |
startedAt* | string | worker 开始处理时间。 |
finishedAt* | string | 摄取结束时间。 |
trackingChannels* | object | Realtime 订阅频道:ingestion(本任务)与 document(父文档)。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/process" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "ing_3301",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"documentId": "doc_manual_v2",
"status": "running",
"stage": "embedding",
"generation": "gen_3",
"progress": {
"completed": 60,
"total": 86,
"unit": "chunks"
},
"effectiveConfig": {
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
}
},
"configHash": "blake3:9f2ca7",
"retryOf": "",
"attemptId": "att_b7d2",
"idempotencyKey": "idem-20260914-0001",
"error": "",
"startedAt": "2026-09-01T08:00:01.000+00:00",
"finishedAt": "",
"trackingChannels": {
"ingestion": "ingestion:ing_3301",
"document": "document:doc_manual_v2"
}
}GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/source
SDK:KnowledgeBases.getDocumentSource · scope:knowledgebases.read
下载文档的原始源文件(二进制流,非 JSON)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 |
用 -o 保存文件,不要按 JSON 解析。
输出:
200,File 二进制内容(Content-Type 为源文件 MIME),供归档或人工核对。
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"切片(Chunk)
GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks
SDK:KnowledgeBases.listChunks · scope:knowledgebases.read
列出文档当前活跃代数的切片,支持内容关键词搜索与高级查询。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 | |
search | query | string | 否 | 默认 "" | 在切片正文内做关键词搜索。 |
queries | query | string[] | 否 | 默认 [] | Appbase Query 高级查询串数组,最多 100 条。 |
输出:
200,返回模型 Models.KnowledgeBaseChunkList。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 匹配查询的切片总数。 |
chunks* | object[] | 切片列表。 |
$id* | string | 切片 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
documentId* | string | 所属文档 ID。 |
content* | string | 切片正文。 |
ingestVersion* | string | 切片所属的摄取代数。 |
source* | object | 权威来源文档描述与受保护的源 URI(动态对象)。 |
locator* | object | 版本化的章节与原文定位器(动态对象)。 |
metadata* | object | 切片元数据,内部溯源字段被剔除。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/chunks?search=首次使用" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 2,
"chunks": [
{
"$id": "chk_0042",
"$createdAt": "2026-09-01T08:00:31.000+00:00",
"$updatedAt": "2026-09-01T08:00:31.000+00:00",
"documentId": "doc_manual_v2",
"content": "早餐机首次使用前请用温水清洗内胆,并空烧一次完成除味。",
"ingestVersion": "gen_3",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 12
},
"metadata": {
"page": 17
}
},
{
"$id": "chk_0043",
"$createdAt": "2026-09-01T08:00:31.000+00:00",
"$updatedAt": "2026-09-01T08:00:31.000+00:00",
"documentId": "doc_manual_v2",
"content": "清洗后首次空烧时若有轻微气味属正常现象,通风放置即可。",
"ingestVersion": "gen_3",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 13
},
"metadata": {
"page": 17
}
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks
SDK:KnowledgeBases.createChunk · scope:knowledgebases.write
绕过解析流水线直接为文档手工建切片(embedding 由 LLM Gateway 计算)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 | |
content | body | string | 是 | 切片正文(必填)。 | |
metadata | body | object | 否 | 任意切片元数据。 |
输出:
201,返回模型 Models.KnowledgeBaseChunk;文档 chunkCount/chunksTotal 随之递增。要求文档已有活跃代数(即完成过一次摄取)。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 切片 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
documentId* | string | 所属文档 ID。 |
content* | string | 切片正文。 |
ingestVersion* | string | 切片所属的摄取代数。 |
source* | object | 权威来源文档描述与受保护的源 URI(动态对象)。 |
locator* | object | 版本化的章节与原文定位器(动态对象)。 |
metadata* | object | 切片元数据,内部溯源字段被剔除。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/chunks" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"content": "保修政策:自购买之日起整机保修 12 个月。",
"metadata": {
"section": "售后"
}
}'响应示例:
{
"$id": "chk_0042",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"documentId": "doc_manual_v2",
"content": "早餐机首次使用前请用温水清洗内胆,并空烧一次完成除味。",
"ingestVersion": "gen_3",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 12
},
"metadata": {
"page": 17
}
}GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}
SDK:KnowledgeBases.getChunk · scope:knowledgebases.read
按 ID 获取单个切片。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 | |
chunkId | path | string | 是 | 目标切片 ID。 |
输出:
200,返回模型 Models.KnowledgeBaseChunk。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 切片 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
documentId* | string | 所属文档 ID。 |
content* | string | 切片正文。 |
ingestVersion* | string | 切片所属的摄取代数。 |
source* | object | 权威来源文档描述与受保护的源 URI(动态对象)。 |
locator* | object | 版本化的章节与原文定位器(动态对象)。 |
metadata* | object | 切片元数据,内部溯源字段被剔除。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/chunks/chk_0042" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "chk_0042",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"documentId": "doc_manual_v2",
"content": "早餐机首次使用前请用温水清洗内胆,并空烧一次完成除味。",
"ingestVersion": "gen_3",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 12
},
"metadata": {
"page": 17
}
}PATCH /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}
SDK:KnowledgeBases.updateChunk · scope:knowledgebases.write
更新切片正文或元数据;改 content(或图片描述类 metadata)会重算 embedding 向量。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 | |
chunkId | path | string | 是 | 目标切片 ID。 | |
content | body | string | 否 | 新正文;传入即触发向量重算(连同已持久化的图片描述)。 | |
metadata | body | object | 否 | 切片元数据;仅当图片描述变化时才重算向量。 |
输出:
200,返回模型 Models.KnowledgeBaseChunk。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 切片 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
documentId* | string | 所属文档 ID。 |
content* | string | 切片正文。 |
ingestVersion* | string | 切片所属的摄取代数。 |
source* | object | 权威来源文档描述与受保护的源 URI(动态对象)。 |
locator* | object | 版本化的章节与原文定位器(动态对象)。 |
metadata* | object | 切片元数据,内部溯源字段被剔除。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/chunks/chk_0042" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"content": "保修政策:自购买之日起整机保修 24 个月(2026 年更新)。",
"metadata": {
"topic": "早餐店经营"
}
}'响应示例:
{
"$id": "chk_0042",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"documentId": "doc_manual_v2",
"content": "早餐机首次使用前请用温水清洗内胆,并空烧一次完成除味。",
"ingestVersion": "gen_3",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 12
},
"metadata": {
"page": 17
}
}DELETE /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}
SDK:KnowledgeBases.deleteChunk · scope:knowledgebases.write
删除单个切片,父文档 chunkCount/chunksTotal 相应递减。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 | |
chunkId | path | string | 是 | 目标切片 ID。 |
输出:
204,无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/chunks/chk_0042" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"摄取(Ingestion)
GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions
SDK:KnowledgeBases.listIngestions · scope:knowledgebases.read
列出文档的摄取任务历史,可用 queries 过滤排序。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 | |
queries | query | string[] | 否 | 默认 [] | Appbase Query 高级查询串数组,最多 100 条。 |
输出:
200,返回模型 Models.KnowledgeBaseIngestionList。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 匹配查询的摄取任务总数。 |
ingestions* | object[] | 摄取任务列表。 |
$id* | string | 摄取任务 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 知识库 ID。 |
documentId* | string | 文档 ID。 |
status* | string | 任务状态:queued / running / ready / failed / cancelling / cancelled。 |
stage* | string | 当前流水线阶段(解析 → 切片 → Embedding)。 |
generation* | string | 本次摄取写入的代数。 |
progress* | object | 进度对象:completed / total / unit。 |
effectiveConfig* | object | 本次摄取冻结生效的配置快照。 |
configHash* | string | effectiveConfig 哈希,用于比对配置是否变化。 |
retryOf* | string | 重试时指向的前次摄取 ID。 |
attemptId* | string | 本次尝试的 fencing token。 |
idempotencyKey* | string | 请求方幂等键。 |
error* | string | failed 时的错误信息。 |
startedAt* | string | worker 开始处理时间。 |
finishedAt* | string | 摄取结束时间。 |
trackingChannels* | object | Realtime 订阅频道:ingestion(本任务)与 document(父文档)。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/ingestions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 2,
"ingestions": [
{
"$id": "ing_3301",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-01T08:00:31.000+00:00",
"kbId": "kb_product_docs",
"documentId": "doc_manual_v2",
"status": "ready",
"stage": "embedding",
"generation": "gen_3",
"progress": {
"completed": 86,
"total": 86,
"unit": "chunks"
},
"effectiveConfig": {
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
}
},
"configHash": "blake3:9f2ca7",
"retryOf": "",
"attemptId": "att_b7d2",
"idempotencyKey": "idem-20260914-0001",
"error": "",
"startedAt": "2026-09-01T08:00:01.000+00:00",
"finishedAt": "2026-09-01T08:00:31.000+00:00",
"trackingChannels": {
"ingestion": "ingestion:ing_3301",
"document": "document:doc_manual_v2"
}
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions
SDK:KnowledgeBases.createIngestion · scope:knowledgebases.write
为文档发起一次摄取(解析 → 切片 → Embedding),202 异步执行。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 | |
idempotencyKey | body | string | 否 | 幂等键:同键重试返回既有摄取,不会重复入队。 | |
retryOf | body | string | 否 | 要重试的前次失败摄取 ID。 | |
persistToDocument | body | boolean | 否 | 为 true 时摄取完成后把本次 overrides 固化为文档级配置。 | |
overrides | body | object | 否 | 仅本次摄取生效的解析覆盖;embedding 相关字段会被拒绝(子字段见下)。 | |
overrides.parserId | body | string | 否 | 枚举:general / title / smart / regex / faq | 本次摄取的切片策略覆盖。 |
overrides.parserConfig | body | object | 否 | 本次摄取的解析/切片配置覆盖,子字段同 parserConfig(见知识库创建端点);embedding 字段会被拒绝。 |
输出:
202,返回模型 Models.KnowledgeBaseIngestion(初始 status=queued)。轮询方式:每 2–3 秒 GET .../ingestions/{ingestionId},status 到 ready/failed/cancelled 终态即止;也可订阅 trackingChannels 频道拿实时进度。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 摄取任务 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 知识库 ID。 |
documentId* | string | 文档 ID。 |
status* | string | 任务状态:queued / running / ready / failed / cancelling / cancelled。 |
stage* | string | 当前流水线阶段(解析 → 切片 → Embedding)。 |
generation* | string | 本次摄取写入的代数。 |
progress* | object | 进度对象:completed / total / unit。 |
effectiveConfig* | object | 本次摄取冻结生效的配置快照。 |
configHash* | string | effectiveConfig 哈希,用于比对配置是否变化。 |
retryOf* | string | 重试时指向的前次摄取 ID。 |
attemptId* | string | 本次尝试的 fencing token。 |
idempotencyKey* | string | 请求方幂等键。 |
error* | string | failed 时的错误信息。 |
startedAt* | string | worker 开始处理时间。 |
finishedAt* | string | 摄取结束时间。 |
trackingChannels* | object | Realtime 订阅频道:ingestion(本任务)与 document(父文档)。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/ingestions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"idempotencyKey": "idem-ingest-01",
"retryOf": "ing_3298",
"persistToDocument": false,
"overrides": {
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 384
}
}
}'响应示例:
{
"$id": "ing_3301",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"documentId": "doc_manual_v2",
"status": "running",
"stage": "embedding",
"generation": "gen_3",
"progress": {
"completed": 60,
"total": 86,
"unit": "chunks"
},
"effectiveConfig": {
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
}
},
"configHash": "blake3:9f2ca7",
"retryOf": "",
"attemptId": "att_b7d2",
"idempotencyKey": "idem-20260914-0001",
"error": "",
"startedAt": "2026-09-01T08:00:01.000+00:00",
"finishedAt": "",
"trackingChannels": {
"ingestion": "ingestion:ing_3301",
"document": "document:doc_manual_v2"
}
}GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions/{ingestionId}
SDK:KnowledgeBases.getIngestion · scope:knowledgebases.read
查询单个摄取任务的状态、阶段、进度与错误。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 | |
ingestionId | path | string | 是 | 目标摄取任务 ID。 |
输出:
200,返回模型 Models.KnowledgeBaseIngestion(异步任务的轮询入口,含 Realtime trackingChannels)。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 摄取任务 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 知识库 ID。 |
documentId* | string | 文档 ID。 |
status* | string | 任务状态:queued / running / ready / failed / cancelling / cancelled。 |
stage* | string | 当前流水线阶段(解析 → 切片 → Embedding)。 |
generation* | string | 本次摄取写入的代数。 |
progress* | object | 进度对象:completed / total / unit。 |
effectiveConfig* | object | 本次摄取冻结生效的配置快照。 |
configHash* | string | effectiveConfig 哈希,用于比对配置是否变化。 |
retryOf* | string | 重试时指向的前次摄取 ID。 |
attemptId* | string | 本次尝试的 fencing token。 |
idempotencyKey* | string | 请求方幂等键。 |
error* | string | failed 时的错误信息。 |
startedAt* | string | worker 开始处理时间。 |
finishedAt* | string | 摄取结束时间。 |
trackingChannels* | object | Realtime 订阅频道:ingestion(本任务)与 document(父文档)。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/ingestions/ing_3301" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "ing_3301",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"documentId": "doc_manual_v2",
"status": "running",
"stage": "embedding",
"generation": "gen_3",
"progress": {
"completed": 60,
"total": 86,
"unit": "chunks"
},
"effectiveConfig": {
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
}
},
"configHash": "blake3:9f2ca7",
"retryOf": "",
"attemptId": "att_b7d2",
"idempotencyKey": "idem-20260914-0001",
"error": "",
"startedAt": "2026-09-01T08:00:01.000+00:00",
"finishedAt": "",
"trackingChannels": {
"ingestion": "ingestion:ing_3301",
"document": "document:doc_manual_v2"
}
}DELETE /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions/{ingestionId}
SDK:KnowledgeBases.deleteIngestion · scope:knowledgebases.write
取消摄取:排队/运行中的任务转入 cancelling,终态任务保持不变(幂等)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 | |
ingestionId | path | string | 是 | 目标摄取任务 ID。 |
输出:
202,返回模型 Models.KnowledgeBaseIngestion(当前状态);本操作不删除记录。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 摄取任务 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 知识库 ID。 |
documentId* | string | 文档 ID。 |
status* | string | 任务状态:queued / running / ready / failed / cancelling / cancelled。 |
stage* | string | 当前流水线阶段(解析 → 切片 → Embedding)。 |
generation* | string | 本次摄取写入的代数。 |
progress* | object | 进度对象:completed / total / unit。 |
effectiveConfig* | object | 本次摄取冻结生效的配置快照。 |
configHash* | string | effectiveConfig 哈希,用于比对配置是否变化。 |
retryOf* | string | 重试时指向的前次摄取 ID。 |
attemptId* | string | 本次尝试的 fencing token。 |
idempotencyKey* | string | 请求方幂等键。 |
error* | string | failed 时的错误信息。 |
startedAt* | string | worker 开始处理时间。 |
finishedAt* | string | 摄取结束时间。 |
trackingChannels* | object | Realtime 订阅频道:ingestion(本任务)与 document(父文档)。 |
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/ingestions/ing_3301" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "ing_3301",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"documentId": "doc_manual_v2",
"status": "cancelling",
"stage": "embedding",
"generation": "gen_3",
"progress": {
"completed": 60,
"total": 86,
"unit": "chunks"
},
"effectiveConfig": {
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
}
},
"configHash": "blake3:9f2ca7",
"retryOf": "",
"attemptId": "att_b7d2",
"idempotencyKey": "idem-20260914-0001",
"error": "",
"startedAt": "2026-09-01T08:00:01.000+00:00",
"finishedAt": "",
"trackingChannels": {
"ingestion": "ingestion:ing_3301",
"document": "document:doc_manual_v2"
}
}数据源与同步
GET /v1/knowledgebases/{knowledgeBaseId}/datasources
SDK:KnowledgeBases.listDataSources · scope:knowledgebases.read
列出知识库连接的数据源,可按 type/status 过滤。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
type | query | string | 否 | 默认 "" | 按数据源类型过滤(当前 yuque)。 |
status | query | string | 否 | 默认 "" | 按状态过滤:active / disabled / error。 |
输出:
200,返回模型 Models.KnowledgeBaseDataSourceList。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 匹配查询的数据源总数。 |
dataSources* | object[] | 数据源列表。 |
$id* | string | 数据源 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 绑定的知识库 ID。 |
type* | string | 数据源类型(当前枚举:yuque)。 |
name* | string | 数据源名称。 |
config* | object | 非敏感配置(如 repoNamespaces、syncSchedule)。 |
credentials* | object | 凭证元数据;密文永不回显。 |
status* | string | 状态:active / disabled / error。 |
lastSyncAt* | string | 最近一次同步完成时间。 |
lastSyncStatus* | string | 最近一次同步状态。 |
lastCursor* | string | 增量同步游标。 |
error* | string | 最近一次数据源错误信息。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources?type=yuque&status=active" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 2,
"dataSources": [
{
"$id": "ds_yuque_team",
"$createdAt": "2026-08-30T10:00:00.000+00:00",
"$updatedAt": "2026-09-14T02:01:12.000+00:00",
"kbId": "kb_product_docs",
"type": "yuque",
"name": "语雀团队空间",
"config": {
"repoNamespaces": [
"acme/manuals"
],
"syncSchedule": "0 2 * * *"
},
"credentials": {},
"status": "active",
"lastSyncAt": "2026-09-14T02:01:12.000+00:00",
"lastSyncStatus": "ready",
"lastCursor": "yq-2026-09-14T02:00:00Z",
"error": ""
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/datasources
SDK:KnowledgeBases.createDataSource · scope:knowledgebases.write
为知识库接入外部数据源(当前支持语雀团队空间),可选注册周期同步。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
name | body | string | 是 | 数据源名称。 | |
type | body | string | 否 | 枚举:yuque | 数据源类型;当前枚举仅 yuque。 |
config | body | object | 否 | 非敏感配置对象(语雀:repoNamespaces、syncSchedule cron 等)。 | |
credentials | body | object | 否 | 凭证对象(如语雀团队令牌);落库加密,响应永不回显。 | |
status | body | string | 否 | 枚举:active / disabled | active / disabled;active 且配置了 config.syncSchedule 时自动注册周期同步。 |
triggerSync | body | boolean | 否 | 为 true(默认)且 status=active 时,创建后立即排队一次全量同步。 |
输出:
201,返回模型 Models.KnowledgeBaseDataSource。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 数据源 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 绑定的知识库 ID。 |
type* | string | 数据源类型(当前枚举:yuque)。 |
name* | string | 数据源名称。 |
config* | object | 非敏感配置(如 repoNamespaces、syncSchedule)。 |
credentials* | object | 凭证元数据;密文永不回显。 |
status* | string | 状态:active / disabled / error。 |
lastSyncAt* | string | 最近一次同步完成时间。 |
lastSyncStatus* | string | 最近一次同步状态。 |
lastCursor* | string | 增量同步游标。 |
error* | string | 最近一次数据源错误信息。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "语雀团队空间",
"type": "yuque",
"config": {
"repoNamespaces": [
"acme/manuals"
],
"syncSchedule": "0 2 * * *"
},
"credentials": {
"teamToken": "yq_team_token_xxx"
},
"status": "active",
"triggerSync": true
}'响应示例:
{
"$id": "ds_yuque_team",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"type": "yuque",
"name": "语雀团队空间",
"config": {
"repoNamespaces": [
"acme/manuals"
],
"syncSchedule": "0 2 * * *"
},
"credentials": {},
"status": "active",
"lastSyncAt": "2026-09-14T02:00:00.000+00:00",
"lastSyncStatus": "ready",
"lastCursor": "yq-2026-09-14T02:00:00Z",
"error": ""
}GET /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}
SDK:KnowledgeBases.getDataSource · scope:knowledgebases.read
按 ID 获取数据源(凭证不回显)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
dataSourceId | path | string | 是 | 目标数据源 ID。 |
输出:
200,返回模型 Models.KnowledgeBaseDataSource。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 数据源 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 绑定的知识库 ID。 |
type* | string | 数据源类型(当前枚举:yuque)。 |
name* | string | 数据源名称。 |
config* | object | 非敏感配置(如 repoNamespaces、syncSchedule)。 |
credentials* | object | 凭证元数据;密文永不回显。 |
status* | string | 状态:active / disabled / error。 |
lastSyncAt* | string | 最近一次同步完成时间。 |
lastSyncStatus* | string | 最近一次同步状态。 |
lastCursor* | string | 增量同步游标。 |
error* | string | 最近一次数据源错误信息。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "ds_yuque_team",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"type": "yuque",
"name": "语雀团队空间",
"config": {
"repoNamespaces": [
"acme/manuals"
],
"syncSchedule": "0 2 * * *"
},
"credentials": {},
"status": "active",
"lastSyncAt": "2026-09-14T02:00:00.000+00:00",
"lastSyncStatus": "ready",
"lastCursor": "yq-2026-09-14T02:00:00Z",
"error": ""
}PATCH /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}
SDK:KnowledgeBases.updateDataSource · scope:knowledgebases.write
更新数据源名称、配置、凭证或状态;凭证按键合并而非整体替换。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
dataSourceId | path | string | 是 | 目标数据源 ID。 | |
name | body | string | 否 | 数据源名称。 | |
config | body | object | 否 | 非敏感配置对象。 | |
credentials | body | object | 否 | 增量合并到已存凭证的键值对。 | |
status | body | string | 否 | 枚举:active / disabled / error / (空,表示不限) | active / disabled / error;改 status 或 config.syncSchedule 会重算周期同步计划。 |
输出:
200,返回模型 Models.KnowledgeBaseDataSource。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 数据源 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 绑定的知识库 ID。 |
type* | string | 数据源类型(当前枚举:yuque)。 |
name* | string | 数据源名称。 |
config* | object | 非敏感配置(如 repoNamespaces、syncSchedule)。 |
credentials* | object | 凭证元数据;密文永不回显。 |
status* | string | 状态:active / disabled / error。 |
lastSyncAt* | string | 最近一次同步完成时间。 |
lastSyncStatus* | string | 最近一次同步状态。 |
lastCursor* | string | 增量同步游标。 |
error* | string | 最近一次数据源错误信息。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"config": {
"repoNamespaces": [
"acme/manuals",
"acme/faq"
],
"syncSchedule": "0 */6 * * *"
},
"credentials": {},
"status": "active"
}'响应示例:
{
"$id": "ds_yuque_team",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"type": "yuque",
"name": "语雀团队空间",
"config": {
"repoNamespaces": [
"acme/manuals"
],
"syncSchedule": "0 2 * * *"
},
"credentials": {},
"status": "active",
"lastSyncAt": "2026-09-14T02:00:00.000+00:00",
"lastSyncStatus": "ready",
"lastCursor": "yq-2026-09-14T02:00:00Z",
"error": ""
}DELETE /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}
SDK:KnowledgeBases.deleteDataSource · scope:knowledgebases.write
删除数据源及其同步历史与周期计划;已生成的知识库文档不受影响。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
dataSourceId | path | string | 是 | 目标数据源 ID。 |
输出:
204,无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"POST /v1/knowledgebases/{knowledgeBaseId}/datasources/yuque/repos
SDK:KnowledgeBases.listYuqueRepos · scope:knowledgebases.write
用团队令牌枚举语雀团队可达仓库,供创建数据源前挑选 repoNamespaces(令牌即用即弃、不落库)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
teamId | body | string | 是 | 语雀团队 ID。 | |
teamToken | body | string | 是 | 语雀开放 API 团队令牌;仅本次查询使用,不会被存储。 |
输出:
200,返回宽类型 JSON 对象:语雀团队仓库清单(namespace、名称等),用于填充数据源 config.repoNamespaces。
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/yuque/repos" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"teamId": "acme",
"teamToken": "yq_team_token_xxx"
}'响应示例:
{
"repos": [
{
"namespace": "acme/manuals",
"name": "产品手册"
},
{
"namespace": "acme/faq",
"name": "常见问题"
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/datasources/yuque/docs
SDK:KnowledgeBases.listYuqueDocs · scope:knowledgebases.write
枚举选定仓库下可导入的语雀文档列表。请求体传入临时团队令牌,接口不保存该令牌。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
teamId | body | string | 是 | 语雀团队 ID。 | |
teamToken | body | string | 是 | 语雀开放 API 团队令牌(不存储)。 | |
repoNamespaces | body | string[] | 否 | 仓库 namespace 数组;空数组列全团队仓库的文档。 |
输出:
200,返回宽类型 JSON 对象:各仓库下可导入文档清单(URL/标题等),供批量导入选择。
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/yuque/docs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"teamId": "acme",
"teamToken": "yq_team_token_xxx",
"repoNamespaces": [
"acme/manuals"
]
}'响应示例:
{
"docs": [
{
"namespace": "acme/manuals",
"title": "早餐机快速上手",
"url": "<YUQUE_DOCUMENT_URL_1>"
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/documents
SDK:KnowledgeBases.createDataSourceDocument · scope:knowledgebases.write
从数据源按 URL 导入单篇文档:URL 仅用于定位,服务端不直接抓取该 URL。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
dataSourceId | path | string | 是 | 目标数据源 ID。 | |
url | body | string | 是 | 语雀文档 URL;仅接受受支持语雀 HTTPS 域名与精确 {group}/{book}/{slug} 路径。 | |
idempotencyKey | body | string | 否 | 幂等键。 |
输出:
202 新建/有更新(入队摄取)或 200 内容未变(文档已 processing/ready),返回模型 Models.KnowledgeBaseDocument。409 与活跃摄取冲突;503 语雀暂不可用。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 文档 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 所属知识库 ID。 |
name* | string | 文档显示名。 |
bucketId* | string | 源文件所在 Storage 桶 ID。 |
fileId* | string | 源文件 Storage 文件 ID。 |
mimeType* | string | 源文件 MIME 类型。 |
source* | string | 来源:manual 手工上传,datasource:{id} 数据源同步,yuque:personal 个人语雀导入。 |
externalItemId* | string | 外部系统条目 ID,数据源同步据此去重更新。 |
parserId* | string | 文档级切片策略覆盖,空为继承库默认。 |
parserConfig* | object | 文档级解析/切片配置覆盖。 |
metadata* | object | 业务元数据。 |
status* | string | 处理状态:uploaded 已登记 / processing 处理中 / ready 就绪 / failed 失败。 |
enabled* | boolean | 是否参与检索;false 时切片保留但不进检索结果。 |
stage* | string | 当前/最近一次摄取的流水线阶段镜像。 |
activeIngestionId* | string | 当前或最近一次摄取任务 ID。 |
activeGeneration* | string | 检索可见代数(generation),仅 status=ready 时有效。 |
processingStartedAt* | string | 最近一次触发处理的时间。 |
chunksTotal* | integer | 预期切片总数(已知后填充)。 |
chunkCount* | integer | 活跃代数中的切片数。 |
error* | string | 最近一次处理错误信息,正常为空串。 |
lastExecutionId* | string | 已废弃的旧 Function 执行 ID。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"url": "<YUQUE_DOCUMENT_URL_1>",
"idempotencyKey": "idem-ds-01"
}'响应示例:
{
"$id": "doc_manual_v2",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"name": "产品使用手册 v2.pdf",
"bucketId": "bkt_kb_docs",
"fileId": "file_9a11cc",
"mimeType": "application/pdf",
"source": "datasource:ds_yuque_team",
"externalItemId": "acme/manuals/breakfast-quickstart",
"parserId": "",
"parserConfig": {},
"metadata": {
"edition": "v2"
},
"status": "processing",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3301",
"activeGeneration": "gen_3",
"processingStartedAt": "2026-09-01T08:00:01.000+00:00",
"chunksTotal": 86,
"chunkCount": 86,
"error": "",
"lastExecutionId": ""
}POST /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/documents/batch
SDK:KnowledgeBases.createDataSourceDocumentsBatch · scope:knowledgebases.write
从数据源批量按 URL 导入文档(最多 20 条,逐项返回结果)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
dataSourceId | path | string | 是 | 目标数据源 ID。 | |
urls | body | string[] | 是 | 语雀文档 URL 数组,最多 20 条、不重复。 | |
idempotencyKey | body | string | 否 | 批量幂等键前缀。 |
输出:
200 全部 accepted/unchanged,207 存在 failed;返回模型 Models.KnowledgeBaseDataSourceDocumentImportBatch(results[] 与请求顺序一致,需逐项检查)。空列表/超 20 条/重复 URL/数据源非 active 返回 400。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 本次处理的 URL 条数。 |
accepted* | integer | 新建/更新文档并入队摄取的 URL 数。 |
unchanged* | integer | 远端内容已处于 processing/ready 而未动的 URL 数。 |
failed* | integer | 校验或导入失败的 URL 数。 |
results* | object[] | 按请求顺序排列的逐 URL 结果。 |
url* | string | 请求的语雀文档地址。 |
status* | string | 每个地址的导入结果:accepted、unchanged 或 failed。 |
document | object | 成功或未变更时返回的知识库文档。 |
error | string | 失败时的错误详情。 |
errorType | string | 失败时可供程序识别的异常类型。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/documents/batch" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"<YUQUE_DOCUMENT_URL_1>",
"<YUQUE_DOCUMENT_URL_2>"
],
"idempotencyKey": "idem-ds-batch-01"
}'响应示例:
{
"total": 2,
"accepted": 0,
"unchanged": 0,
"failed": 0,
"results": [
{
"url": "",
"status": "available",
"document": {},
"error": "",
"errorType": ""
},
{
"url": "",
"status": "available",
"document": {},
"error": "",
"errorType": ""
}
]
}GET /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/syncs
SDK:KnowledgeBases.listDataSourceSyncs · scope:knowledgebases.read
列出数据源同步记录(按创建时间倒序),可按 status 过滤。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
dataSourceId | path | string | 是 | 目标数据源 ID。 | |
status | query | string | 否 | 默认 "" | 按同步状态过滤:queued / running / ready / failed。 |
输出:
200,返回模型 Models.KnowledgeBaseDataSourceSyncList。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 匹配查询的同步记录总数。 |
syncs* | object[] | 同步记录列表(按创建时间倒序)。 |
$id* | string | 同步记录 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
datasourceId* | string | 数据源 ID。 |
kbId* | string | 知识库 ID。 |
status* | string | 同步状态:queued / running / ready / failed。 |
cursorStart* | string | 同步起始游标。 |
cursorEnd* | string | 同步产出的新游标。 |
stats* | object | 同步统计(动态对象:扫描/导入/跳过/失败计数等)。 |
error* | string | failed 时的错误信息。 |
startedAt* | string | worker 开始处理时间。 |
finishedAt* | string | 同步结束时间。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/syncs?status=ready" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 2,
"syncs": [
{
"$id": "sync_771f",
"$createdAt": "2026-09-14T02:00:00.000+00:00",
"$updatedAt": "2026-09-14T02:01:12.000+00:00",
"datasourceId": "ds_yuque_team",
"kbId": "kb_product_docs",
"status": "ready",
"cursorStart": "yq-2026-09-13T02:00:00Z",
"cursorEnd": "yq-2026-09-14T02:00:00Z",
"stats": {
"scanned": 40,
"imported": 3,
"unchanged": 36,
"failed": 1
},
"error": "",
"startedAt": "2026-09-14T02:00:01.000+00:00",
"finishedAt": "2026-09-14T02:01:12.000+00:00"
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/syncs
SDK:KnowledgeBases.createDataSourceSync · scope:knowledgebases.write
触发一次数据源同步;已有 queued/running 同步时返回既有记录,不重复排队。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
dataSourceId | path | string | 是 | 目标数据源 ID。 | |
versionId | body | string | 否 | 启用版本管理时必填,填写要写入的草稿版本 ID。 |
输出:
202,返回模型 Models.KnowledgeBaseDataSourceSync。异步任务:轮询 GET .../syncs/{syncId} 至 ready/failed。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 同步记录 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
datasourceId* | string | 数据源 ID。 |
kbId* | string | 知识库 ID。 |
status* | string | 同步状态:queued / running / ready / failed。 |
cursorStart* | string | 同步起始游标。 |
cursorEnd* | string | 同步产出的新游标。 |
stats* | object | 同步统计(动态对象:扫描/导入/跳过/失败计数等)。 |
error* | string | failed 时的错误信息。 |
startedAt* | string | worker 开始处理时间。 |
finishedAt* | string | 同步结束时间。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/syncs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"启用版本管理时,在请求正文中传入实际草稿 ID:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/syncs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" -d '{"versionId":"<DRAFT_VERSION_ID>"}'响应示例:
{
"$id": "sync_771f",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"datasourceId": "ds_yuque_team",
"kbId": "kb_product_docs",
"status": "ready",
"cursorStart": "yq-2026-09-13T02:00:00Z",
"cursorEnd": "yq-2026-09-14T02:00:00Z",
"stats": {
"scanned": 40,
"imported": 3,
"unchanged": 36,
"failed": 1
},
"error": "",
"startedAt": "2026-09-14T02:00:01.000+00:00",
"finishedAt": "2026-09-14T02:01:12.000+00:00"
}GET /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/syncs/{syncId}
SDK:KnowledgeBases.getDataSourceSync · scope:knowledgebases.read
查询单次同步的状态、游标推进与统计。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
dataSourceId | path | string | 是 | 目标数据源 ID。 | |
syncId | path | string | 是 | 目标同步记录 ID。 |
输出:
200,返回模型 Models.KnowledgeBaseDataSourceSync。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 同步记录 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
datasourceId* | string | 数据源 ID。 |
kbId* | string | 知识库 ID。 |
status* | string | 同步状态:queued / running / ready / failed。 |
cursorStart* | string | 同步起始游标。 |
cursorEnd* | string | 同步产出的新游标。 |
stats* | object | 同步统计(动态对象:扫描/导入/跳过/失败计数等)。 |
error* | string | failed 时的错误信息。 |
startedAt* | string | worker 开始处理时间。 |
finishedAt* | string | 同步结束时间。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/syncs/sync_771f" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "sync_771f",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"datasourceId": "ds_yuque_team",
"kbId": "kb_product_docs",
"status": "ready",
"cursorStart": "yq-2026-09-13T02:00:00Z",
"cursorEnd": "yq-2026-09-14T02:00:00Z",
"stats": {
"scanned": 40,
"imported": 3,
"unchanged": 36,
"failed": 1
},
"error": "",
"startedAt": "2026-09-14T02:00:01.000+00:00",
"finishedAt": "2026-09-14T02:01:12.000+00:00"
}词库(Lexicons)与绑定管理
GET /v1/lexicons
SDK:Lexicons.list · scope:lexicons.read
分页列出当前项目下可见的全部词库。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
limit | query | integer | 否 | 默认 25 | 单页返回数量,范围 1–100。 |
offset | query | integer | 否 | 默认 0 | 分页偏移量,范围 0–1000000。 |
输出:200 OK,返回 lexiconList 模型(total + lexicons[])。
调用示例:
curl -X GET "https://appbuild-sit.oceanbase.com/v1/lexicons?limit=25&offset=0" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>"响应示例:
{
"total": 2,
"lexicons": [
{
"$id": "lex_enterprise_synonyms",
"$createdAt": "2026-10-21T08:00:00.000+00:00",
"$updatedAt": "2026-10-22T03:15:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"name": "企业智能客服同义词与扩展词典",
"description": "统一 OceanBase、AI 网关与智能客服业务术语标准表达",
"tokenizerProfile": "unicode-v1",
"revision": 4
},
{
"$id": "lex_support_stopwords",
"$createdAt": "2026-10-21T08:10:00.000+00:00",
"$updatedAt": "2026-10-21T09:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"name": "客服检索与对话停用词词典",
"description": "过滤口语冗余词与违规阻断词",
"tokenizerProfile": "unicode-v1",
"revision": 2
}
]
}POST /v1/lexicons
SDK:Lexicons.create · scope:lexicons.write
在项目内创建新词库。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
lexiconId | body | string | 否 | 默认 "unique()" | 自定义词库 ID(如 lex_enterprise_synonyms)或传 "unique()"。 |
name | body | string | 是 | — | 词库名称,长度 1–128 字符。 |
description | body | string | 否 | 默认 "" | 词库用途说明,最长 4096 字符。 |
permissions | body | string[] | 否 | 默认 null | 资源级权限数组(仅允许 read、update、delete 动作)。 |
输出:201 Created,返回 lexicon 模型。
调用示例:
curl -X POST "https://appbuild-sit.oceanbase.com/v1/lexicons" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"lexiconId": "lex_enterprise_synonyms",
"name": "企业智能客服同义词与扩展词典",
"description": "统一 OceanBase、AI 网关与智能客服业务术语标准表达"
}'GET /v1/lexicons/{lexiconId}、PATCH /v1/lexicons/{lexiconId}、DELETE /v1/lexicons/{lexiconId}
SDK:Lexicons.get / Lexicons.update / Lexicons.delete · scope:lexicons.read / lexicons.write
| 方法 + 路径 | 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|---|
GET /v1/lexicons/{lexiconId} | lexiconId | path | string | 是 | 按 ID 获取词库详情(含当前 revision 与 tokenizerProfile)。 |
PATCH /v1/lexicons/{lexiconId} | lexiconId | path | string | 是 | 目标词库 ID。 |
PATCH /v1/lexicons/{lexiconId} | name | body | string | 否 | 更新后的词库名称(1–128 字符)。 |
PATCH /v1/lexicons/{lexiconId} | description | body | string | 否 | 更新后的词库说明(最长 4096 字符)。 |
PATCH /v1/lexicons/{lexiconId} | permissions | body | string[] | 否 | 资源级权限数组(更新后原子递增 revision)。 |
DELETE /v1/lexicons/{lexiconId} | lexiconId | path | string | 是 | 删除词库及其全部词条(返回 204);若仍绑定在任何知识库或智能体上,返回 409 general_conflict。 |
调用示例:
# 1. 获取词库详情
curl -X GET "https://appbuild-sit.oceanbase.com/v1/lexicons/lex_enterprise_synonyms" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>"
# 2. 更新词库名称与描述
curl -X PATCH "https://appbuild-sit.oceanbase.com/v1/lexicons/lex_enterprise_synonyms" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "企业智能客服同义词与扩展词典(v2)",
"description": "覆盖 OceanBase V4.3、LLM Gateway 与智能体专有术语"
}'
# 3. 删除已解绑词库
curl -X DELETE "https://appbuild-sit.oceanbase.com/v1/lexicons/lex_temp_test" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>"GET /v1/lexicons/{lexiconId}/entries 与 POST /v1/lexicons/{lexiconId}/entries
SDK:Lexicons.listEntries / Lexicons.createEntry · scope:lexicons.read / lexicons.write
管理词库内的结构化词条規則。
创建词条(POST /v1/lexicons/{lexiconId}/entries)输入参数:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
lexiconId | path | string | 是 | — | 目标词库 ID。 |
entryId | body | string | 否 | 默认 "unique()" | 词条 ID。 |
entryType | body | string | 是 | 枚举 synonym, expansion, stop | 规则类型:synonym(双向等价同义词)、expansion(单向下位扩展词)、stop(停用词/拦截词)。 |
terms | body | string[] | 是 | — | 触发词项数组(1–100 项,单项 1–256 字符);synonym 时首项为标准词(Canonical Term)。 |
expansions | body | string[] | 否 | 默认 [] | 仅当 entryType="expansion" 时必填,填写展开后的目标词数组。 |
position | body | integer | 否 | 默认 0 | 规则匹配排序优先级(0–2147483647,越小越优先)。 |
调用示例:
curl -X POST "https://appbuild-sit.oceanbase.com/v1/lexicons/lex_enterprise_synonyms/entries" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"entryId": "unique()",
"entryType": "synonym",
"terms": ["OceanBase", "OB数据库", "蚂蚁分布式数据库"],
"expansions": [],
"position": 10
}'响应示例(201 Created):
{
"$id": "ent_ob_syn_01",
"$createdAt": "2026-10-22T03:15:00.000+00:00",
"$updatedAt": "2026-10-22T03:15:00.000+00:00",
"lexiconId": "lex_enterprise_synonyms",
"entryType": "synonym",
"terms": ["OceanBase", "OB数据库", "蚂蚁分布式数据库"],
"expansions": [],
"position": 10
}POST /v1/lexicons/{lexiconId}/preview、POST /v1/lexicons/{lexiconId}/import、GET /v1/lexicons/{lexiconId}/export、GET /v1/lexicons/{lexiconId}/references
SDK:Lexicons.preview / Lexicons.import / Lexicons.export / Lexicons.listReferences · scope:lexicons.read / lexicons.write
| 端点 | 核心参数 | 返回模型 / 格式 | 说明 |
|---|---|---|---|
POST /v1/lexicons/{lexiconId}/preview | query(body, string, 必填) | Models.LexiconRewrite | 预览单句查询经该词库改写后的归一化文本、同义词替换、扩展词展开与停用词命中详情。 |
POST /v1/lexicons/{lexiconId}/import | format(json/csv/xlsx)、mode(merge/overwrite)、dryRun(boolean,默认 true)、content / entries | Models.LexiconImportResult | 批量导入词条(先以 dryRun: true 校验去重与 1,000 条配额,再传 dryRun: false 正式落库并递增 revision)。 |
GET /v1/lexicons/{lexiconId}/export | format(query: json/csv/xlsx) | 文件流 / JSON | 导出指定词库的全部词条规则。 |
GET /v1/lexicons/{lexiconId}/references | lexiconId(path, string, 必填) | Models.LexiconReferenceList | 查询当前绑定了该词库的 knowledgebases 与 agents 资源引用清单。 |
调用示例(改写预览 POST /v1/lexicons/{lexiconId}/preview):
curl -X POST "https://appbuild-sit.oceanbase.com/v1/lexicons/lex_enterprise_synonyms/preview" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"query": "请问OB数据库向量索引报错怎么排查"
}'响应示例(200 OK):
{
"originalQuery": "请问OB数据库向量索引报错怎么排查",
"rewrittenQuery": "OceanBase 向量索引报错怎么排查",
"expandedTerms": [
"OceanBase",
"OB数据库",
"HNSW索引",
"IVF索引"
],
"removedStopwords": [
"请问"
],
"matchedEntries": [
{
"entryId": "ent_ob_syn_01",
"entryType": "synonym",
"matchedTerm": "OB数据库",
"canonicalTerm": "OceanBase"
}
]
}GET /v1/knowledgebases/{knowledgeBaseId}/lexicons 与 PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons
SDK:Lexicons.getKnowledgeBaseBindings / Lexicons.updateKnowledgeBaseBindings · scope:lexicons.read / lexicons.write
查询或整体替换指定知识库(如 kb_enterprise_support)绑定的词库列表及启用状态。
PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons 输入参数:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | — | 目标知识库 ID。 |
enabled | body | boolean | 否 | 默认 false | 是否对该知识库的检索与预处理启用词库改写。 |
bindings | body | object[] | 是 | — | 有序绑定数组(最多 100 项),每项格式为 {"lexiconId": "<id>", "priority": <int>}。 |
调用示例:
curl -X PUT "https://appbuild-sit.oceanbase.com/v1/knowledgebases/kb_enterprise_support/lexicons" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"bindings": [
{"lexiconId": "lex_enterprise_synonyms", "priority": 1},
{"lexiconId": "lex_support_stopwords", "priority": 2}
]
}'# 查询知识库当前绑定的词库列表(GET /v1/knowledgebases/{kbId}/lexicons)
curl -X GET "https://appbuild-sit.oceanbase.com/v1/knowledgebases/kb_enterprise_support/lexicons" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>"响应示例(200 OK):
{
"enabled": true,
"stopIntercept": false,
"stopReply": "",
"bindings": [
{
"lexiconId": "lex_enterprise_synonyms",
"priority": 1
},
{
"lexiconId": "lex_support_stopwords",
"priority": 2
}
]
}说明:当前项目智能体工作台(Agent Runtime Workbench)支持通过同构端点
GET /v1/agent-runtime/project/lexicons与PUT /v1/agent-runtime/project/lexicons(额外支持stopIntercept: true与stopReply阻断话术配置)绑定同一套项目词库,详见 Agent Runtime API。
错误与边界
知识库/文档/切片/数据源/同步/摄取不存在:
404+knowledge_base_not_found等对应类型;重复 ID:409。embeddingModel在建库时固定:修改需重建库重新摄取;文档级parserId覆盖可在摄取时以overrides再覆盖。向量化和重排依赖 LLM Gateway:模型供应商不可用或配额耗尽时,摄取或检索会返回依赖失败错误;请检查 LLM Gateway 中的供应商状态。
批量导入上限:文件 50 / URL 20;
207多状态响应需逐项检查结果,不能假定有成功项。enabled=false的文档从检索结果中排除但保留切片;删除文档级联删除切片与向量。语雀团队令牌与 OAuth 凭证属敏感凭证:
credentials写入后不回显;OAuth 会话过期后需重新创建。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
KnowledgeBases.list / create / get / update / delete | /knowledgebases CRUD |
KnowledgeBases.createSearch / createMultiSearch | POST .../{id}/search、POST /knowledgebases/search |
KnowledgeBases.getManagement / createReindex | GET .../management、POST .../reindex |
KnowledgeBases.listDocuments / createDocument / createDocumentsBatch / getDocument / updateDocument / deleteDocument | /knowledgebases/{id}/documents* |
KnowledgeBases.createDocumentProcess / getDocumentSource | POST .../process、GET .../source |
KnowledgeBases.listChunks / createChunk / getChunk / updateChunk / deleteChunk | .../chunks* |
KnowledgeBases.listIngestions / createIngestion / getIngestion / deleteIngestion | .../ingestions* |
KnowledgeBases.listDataSources / createDataSource / getDataSource / updateDataSource / deleteDataSource | .../datasources* |
KnowledgeBases.listYuqueRepos / listYuqueDocs | POST .../datasources/yuque/repos|docs |
KnowledgeBases.createDataSourceDocument / createDataSourceDocumentsBatch / listDataSourceSyncs / createDataSourceSync / getDataSourceSync | .../datasources/{dataSourceId}/documents*、syncs* |
Lexicons.list / create / get / update / delete | /v1/lexicons CRUD |
Lexicons.listEntries / createEntry / getEntry / updateEntry / deleteEntry | /v1/lexicons/{lexiconId}/entries* |
Lexicons.preview / import / export / listReferences | /v1/lexicons/{lexiconId}/preview|import|export|references |
Lexicons.getKnowledgeBaseBindings / updateKnowledgeBaseBindings | GET|PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons |