知识库 API
富文档 RAG 知识库全链路接口:知识库 CRUD、文档摄取(Storage 文件登记 + 解析/切片/Embedding 流水线)、切片(chunk)级维护、数据源(data source)连接与同步、单库/跨库语义检索、重建索引与管理观测。
资源与基础路径
- 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)。
端点清单
| 方法 + 路径 | 用途 | ||
|---|---|---|---|
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 个,预检原子) | ||
POST /knowledgebases/{knowledgeBaseId}/documents/yuque | 经 OAuth 会话导入个人语雀文档 | ||
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 / .../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 | 请求取消工作副本操作(见 版本管理) | ||
POST /knowledgebases/{knowledgeBaseId}/yuque/oauth/sessions | 创建语雀 OAuth 会话 | ||
GET .../yuque/oauth/sessions/{sessionId} | 查询 OAuth 会话状态 | ||
DELETE .../yuque/oauth/credentials/current | 删除当前用户存储的语雀凭证 |
请求与响应
以下按资源域逐端点给出输入、输出与可复制的调用/响应示例。通用约定:
- 认证:所有请求携带
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>);省略走自动路由。 | |
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 | 否 | 检索默认值(如 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 | 否 | 最终返回条数。 | |
searchMode | body | string | 否 | 枚举:vector / fulltext / hybrid | 检索模式:vector / fulltext / hybrid。 |
rerank | body | boolean | 否 | 为 true 时先扩大召回再经 LLM Gateway 对候选重排,最后截断到 limit。 | |
recallLimit | body | integer | 否 | 启用 rerank 时的召回宽度,默认 max(limit×4, 20)。 | |
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。 |
输出:
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 分数,否则用初始检索分。 |
reranked* | boolean | 是否经 LLM Gateway 重排成功;自动 rerank 失败降级时为 false。 |
调用示例:
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,
"recallLimit": 0,
"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 向量权重;省略用各库默认。 |
输出:
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,
"recallLimit": 0,
"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 | 否 | 按启用状态过滤。 | |
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(同步去重用)。 | |
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 | 否 | 业务元数据。 |
登记后调用 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"
}
}'响应示例:
{
"$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": ""
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/documents/yuque
SDK:KnowledgeBases.createYuqueDocuments · scope:knowledgebases.write
经 OAuth 会话导入当前用户的个人语雀文档(无需团队数据源)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
sessionId | body | string | 是 | createYuqueOAuthSession 返回的 OAuth 会话 ID。 | |
urls | body | string[] | 是 | 语雀文档 URL 数组,最多 20 条;仅接受受支持的语雀 HTTPS 域名与精确 {group}/{book}/{slug} 路径。 | |
idempotencyKey | body | string | 否 | 批量幂等键前缀。 |
输出:
200 全部成功 / 207 部分失败,返回模型 Models.KnowledgeBaseDataSourceDocumentImportBatch。文档归属 source=yuque:personal。凭证缺失/本地取消/语雀侧吊销或返回 401/403 时报 knowledge_base_yuque_oauth_reauth_required(HTTP 401),需重新授权。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 本次处理的 URL 条数。 |
accepted* | integer | 新建/更新文档并入队摄取的 URL 数。 |
unchanged* | integer | 远端内容已处于 processing/ready 而未动的 URL 数。 |
failed* | integer | 校验或导入失败的 URL 数。 |
results* | object[] | 按请求顺序排列的逐 URL 结果。 |
url* | string | Requested Yuque document URL. |
status* | string | Per-URL import outcome: accepted, unchanged, or failed. |
document | object | Imported knowledge base document when status is accepted or unchanged. |
error | string | Human-readable failure detail when status is failed. |
errorType | string | Machine-readable AppBase exception type when status is failed. |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/yuque" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "yqs_a1b2c3",
"urls": [
"https://www.yuque.com/acme/manuals/breakfast-quickstart"
],
"idempotencyKey": "idem-yq-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}/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 | 否 | 业务元数据。 | |
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": "https://www.yuque.com/acme/manuals/breakfast-quickstart"
}
]
}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": "https://www.yuque.com/acme/manuals/breakfast-quickstart",
"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 | Requested Yuque document URL. |
status* | string | Per-URL import outcome: accepted, unchanged, or failed. |
document | object | Imported knowledge base document when status is accepted or unchanged. |
error | string | Human-readable failure detail when status is failed. |
errorType | string | Machine-readable AppBase exception type when status is failed. |
调用示例:
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": [
"https://www.yuque.com/acme/manuals/breakfast-quickstart",
"https://www.yuque.com/acme/manuals/warranty"
],
"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。 |
输出:
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": "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"
}语雀个人导入(OAuth)
POST /v1/knowledgebases/{knowledgeBaseId}/yuque/oauth/sessions
SDK:KnowledgeBases.createYuqueOAuthSession · scope:knowledgebases.write
为当前登录用户创建短期语雀 OAuth 会话,用于导入个人文档。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
force | body | boolean | 否 | 为 true 时忽略已存凭证重新发起授权;新回调成功前旧凭证仍可用。 |
输出:
201,返回宽类型 JSON 对象:已授权时 authorized=true 且 authorizeUrl=null(不重复走 OAuth);否则返回 authorizeUrl 供用户完成授权。首次授权需项目已配置 OAuth Client ID/Secret。回调 state 一次性:一次回调尝试后须新建会话再重试。
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/yuque/oauth/sessions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"force": false
}'响应示例:
{
"sessionId": "yqs_a1b2c3",
"authorized": false,
"authorizeUrl": "https://www.yuque.com/oauth/authorize?client_id=xxx&state=yqs_a1b2c3"
}GET /v1/knowledgebases/{knowledgeBaseId}/yuque/oauth/sessions/{sessionId}
SDK:KnowledgeBases.getYuqueOAuthSession · scope:knowledgebases.write
轮询语雀 OAuth 会话状态;授权成功后即可发起个人文档导入。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
sessionId | path | string | 是 | OAuth 会话 ID。 |
输出:
200,返回宽类型 JSON 对象:仅含公开状态 authorized 与 scope,不含 access token。回调成功后的首次受保护轮询会把令牌转入加密私有存储并从 Redis 会话移除。
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/yuque/oauth/sessions/yqs_a1b2c3" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"sessionId": "yqs_a1b2c3",
"authorized": true,
"scope": "repo:read doc:read"
}DELETE /v1/knowledgebases/{knowledgeBaseId}/yuque/oauth/credentials/current
SDK:KnowledgeBases.deleteYuqueOAuthCredential · scope:knowledgebases.write
删除当前用户在本项目存储的语雀 OAuth 凭证(幂等;不撤销语雀侧授权)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 |
输出:
204,无响应体;不存在凭证时同样返回 204。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/yuque/oauth/credentials/current" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"错误与边界
- 知识库/文档/切片/数据源/同步/摄取不存在:
404+knowledge_base_not_found等对应类型;重复 ID:409。 embeddingModel在建库时固定:修改需重建库重新摄取;文档级parserId覆盖可在摄取时以overrides再覆盖。- Embedding/重排依赖 LLM Gateway:provider 不可用或配额耗尽时摄取/检索返回依赖失败错误——检查 llm-gateway 的 provider 健康状态。
- 批量导入上限:文件 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 / createYuqueDocuments / 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* | |
KnowledgeBases.createYuqueOAuthSession / getYuqueOAuthSession / deleteYuqueOAuthCredential | .../yuque/oauth/* |
事实源
- Server API spec:
agentbase-sdksv2.6.0specs/open-api3-latest-server.json(/knowledgebases域 42 个端点、knowledgeBase*模型、parser/rerank 枚举)。 - Server SDK 生成物:
server-nodejs/server-javav2.6.0KnowledgeBasesservice。 - 语义深度参考:
skills/ob-agentbase/references/knowledge-bases.md。