AgentbaseDocs
文档目录

知识库 API

富文档 RAG 知识库全链路接口:知识库 CRUD、文档摄取(Storage 文件登记 + 解析/切片/Embedding 流水线)、切片(chunk)级维护、数据源(data source)连接与同步、单库/跨库语义检索、重建索引与管理观测。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。本域 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手工建切片
`GETPATCHDELETE .../chunks/{chunkId}`切片读改删
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions摄取任务列表
POST /knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions发起摄取
`GETDELETE .../ingestions/{ingestionId}`摄取详情/取消
GET /knowledgebases/{knowledgeBaseId}/datasources列出数据源
POST /knowledgebases/{knowledgeBaseId}/datasources创建数据源
`GETPATCHDELETE .../datasources/{dataSourceId}`数据源读改删
POST .../datasources/yuque/repos / .../yuque/docs枚举语雀团队仓库/文档
POST .../datasources/{dataSourceId}/documents从数据源 URL 导入单篇
POST .../datasources/{dataSourceId}/documents/batch批量导入(最多 20 URL)
`GETPOST .../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删除当前用户存储的语雀凭证

请求与响应

以下按资源域逐端点给出输入、输出与可复制的调用/响应示例。通用约定:

知识库管理

GET /v1/knowledgebases

SDK:KnowledgeBases.list · scope:knowledgebases.read

列出当前项目全部知识库,可按 ID/名称搜索。

输入:

参数位置类型必填默认/枚举说明
searchquerystring否默认 ""按知识库 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*integerEmbedding 向量维度,与模型输出一致,建库后不可改。
parserId*string默认切片策略:general / title / smart / regex / faq。
parserConfig*object默认解析/切片配置(动态对象,字段见创建端点)。
retrievalDefaults*object检索默认值(如 similarityThreshold、vectorWeight、限流)。
vectorsdbDatabaseId*stringBacking 的 VectorsDB 库 ID,provision 完成前为 null。
vectorsdbCollectionId*stringBacking 的 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 桶。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdbodystring是知识库 ID:自定义或 ID.unique() 生成。
namebodystring是知识库名称。
descriptionbodystring否知识库描述。
embeddingModelbodystring是Embedding 模型 ID;创建时对 LLM Gateway 探测一次得出向量维度,建库后模型与维度不可改。
embeddingProviderRefbodystring否钉定 Embedding provider(project:<providerId> / trial:<bindingId>);省略走自动路由。
embeddingDimensionbodyinteger否1–65535显式向量维度(2.9.0):对所选模型探测校验,与模型输出维度不符则创建失败(400)。
tracingEnabledbodyboolean否默认 false摄取追踪开关(2.9.0):记录解析 / 分块中间产物供「知识库解析评估」使用;依赖平台管理员全局开关,开启后需重新摄取才有完整证据。
parserIdbodystring否枚举:general / title / smart / regex / faq库级默认切片策略,未覆盖的文档按此解析。
parserConfigbodyobject否库级默认解析/切片配置(子字段见下)。
parserConfig.chunkTokenNumbodyinteger否每个切片的 token 预算:general/smart 默认 512,title/regex 默认 256。
parserConfig.overlapPercentbodyinteger否默认 10general 切片器的 token 重叠百分比,默认 10。
parserConfig.delimiterbodystring否超长 title/regex 切片的分隔符;默认 title 为 \n。;!?,regex 为 \n。.;;!!??。
parserConfig.titleLevelbodyinteger否默认 3title 切片器使用的 Markdown 标题级别,默认 3。
parserConfig.minChunkTokensbodyinteger否默认 128smart 切片器最小切片大小,默认 128,不得超过 chunkTokenNum。
parserConfig.regexPatternbodystring否默认 "[.!?]+\\s*"regex 切片器使用的 PCRE 表达式,默认 [.!?]+\s*。
parserConfig.documentParserbodystring否枚举:text / vlm / mineru文档解析器:text(纯文本)/ vlm(视觉模型)/ mineru;MinerU 部署与凭证不属于本 API。
parserConfig.visionModelbodystring否documentParser=vlm 时使用的视觉模型。
parserConfig.visionProviderRefbodystring否视觉模型的钉定 provider 引用。
parserConfig.imageUnderstandingbodyobject否图片解读配置(动态对象):enabled=true 时 model 与 providerRef 必填;另含 prompt、maxImagesPerDocument(默认 20)、maxDescriptionChars(默认 800)、maxConcurrency(默认 4)。
retrievalDefaultsbodyobject否检索默认值(如 similarityThreshold、vectorWeight)。
ingestRoutesbodyobject否已废弃的 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*integerEmbedding 向量维度,与模型输出一致,建库后不可改。
parserId*string默认切片策略:general / title / smart / regex / faq。
parserConfig*object默认解析/切片配置(动态对象,字段见创建端点)。
retrievalDefaults*object检索默认值(如 similarityThreshold、vectorWeight、限流)。
vectorsdbDatabaseId*stringBacking 的 VectorsDB 库 ID,provision 完成前为 null。
vectorsdbCollectionId*stringBacking 的 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 状态与文档计数)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 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*integerEmbedding 向量维度,与模型输出一致,建库后不可改。
parserId*string默认切片策略:general / title / smart / regex / faq。
parserConfig*object默认解析/切片配置(动态对象,字段见创建端点)。
retrievalDefaults*object检索默认值(如 similarityThreshold、vectorWeight、限流)。
vectorsdbDatabaseId*stringBacking 的 VectorsDB 库 ID,provision 完成前为 null。
vectorsdbCollectionId*stringBacking 的 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

更新知识库名称、默认解析配置或检索默认值(只改传入字段)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
namebodystring否新名称。
descriptionbodystring否新描述。
embeddingProviderRefbodystring否钉定 Embedding provider;旧库仅可设置一次。
parserIdbodystring否枚举:general / title / smart / regex / faq库级默认切片策略。
parserConfigbodyobject否库级默认解析/切片配置(子字段见下)。
parserConfig.chunkTokenNumbodyinteger否每个切片的 token 预算:general/smart 默认 512,title/regex 默认 256。
parserConfig.overlapPercentbodyinteger否默认 10general 切片器的 token 重叠百分比,默认 10。
parserConfig.delimiterbodystring否超长 title/regex 切片的分隔符;默认 title 为 \n。;!?,regex 为 \n。.;;!!??。
parserConfig.titleLevelbodyinteger否默认 3title 切片器使用的 Markdown 标题级别,默认 3。
parserConfig.minChunkTokensbodyinteger否默认 128smart 切片器最小切片大小,默认 128,不得超过 chunkTokenNum。
parserConfig.regexPatternbodystring否默认 "[.!?]+\\s*"regex 切片器使用的 PCRE 表达式,默认 [.!?]+\s*。
parserConfig.documentParserbodystring否枚举:text / vlm / mineru文档解析器:text(纯文本)/ vlm(视觉模型)/ mineru;MinerU 部署与凭证不属于本 API。
parserConfig.visionModelbodystring否documentParser=vlm 时使用的视觉模型。
parserConfig.visionProviderRefbodystring否视觉模型的钉定 provider 引用。
parserConfig.imageUnderstandingbodyobject否图片解读配置(动态对象):enabled=true 时 model 与 providerRef 必填;另含 prompt、maxImagesPerDocument(默认 20)、maxDescriptionChars(默认 800)、maxConcurrency(默认 4)。
retrievalDefaultsbodyobject否检索默认值。
ingestRoutesbodyobject否已废弃字段,仅为兼容保留。
iconFileIdbodystring否头像图片的文件 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*integerEmbedding 向量维度,与模型输出一致,建库后不可改。
parserId*string默认切片策略:general / title / smart / regex / faq。
parserConfig*object默认解析/切片配置(动态对象,字段见创建端点)。
retrievalDefaults*object检索默认值(如 similarityThreshold、vectorWeight、限流)。
vectorsdbDatabaseId*stringBacking 的 VectorsDB 库 ID,provision 完成前为 null。
vectorsdbCollectionId*stringBacking 的 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 资源。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
deleteBucketbodyboolean否为 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、评分)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
limitqueryinteger否默认 10最近摄取/trace/评分各包含的最大条数,默认 10。
fromquerystring否默认 ""观测时间窗起点(ISO 8601)。
toquerystring否默认 ""观测时间窗终点(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

把就绪文档有界分批地重新入队摄取(改库级解析配置后生效用)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
limitbodyinteger否本批最多入队的就绪文档数。
cursorbodystring否上一批响应返回的文档游标。
idempotencyKeybodystring否批量幂等键,防止重复入队。

输出:

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 重排,返回带评分与出处的切片。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
querybodystring是查询文本。
limitbodyinteger否最终返回条数。
searchModebodystring否枚举:vector / fulltext / hybrid检索模式:vector / fulltext / hybrid。
rerankbodyboolean否为 true 时先扩大召回再经 LLM Gateway 对候选重排,最后截断到 limit。
recallLimitbodyinteger否启用 rerank 时的召回宽度,默认 max(limit×4, 20)。
rerankModelbodystring否显式 rerank 模型 ID;启用 rerank 时覆盖自动选择。
rerankProviderRefbodystring否钉定 rerank provider:project:<providerId> 或 trial:<bindingId>;不要用 providerType:providerId 形式。
similarityThresholdbodynumber否向量最低相似度阈值(作用于向量与 hybrid 的向量分支);省略用库 retrievalDefaults.similarityThreshold。
vectorWeightbodynumber否hybrid 向量分支权重(全文取 1 - vectorWeight);省略用库 retrievalDefaults.vectorWeight。
answerbodyboolean否默认 false答案合成(2.9.0):true 时用知识库 indexingDefaults 的 chat 模型对合并证据做接地合成(最多 12 行证据、答案 ≤1024 tokens),响应带 answer 对象。

输出:

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。
answerobject / 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,
    "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 合并 → 统一重排一次,全局排序返回。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdsbodystring[]是知识库 ID 数组,1–10 个且不重复。
querybodystring是查询文本。
limitbodyinteger否全局 TopK(所有库合并后的最终条数)。
searchModebodystring否枚举:vector / fulltext / hybrid检索模式:vector / fulltext / hybrid。
rerankbodyboolean否为 true 时各库独立召回候选,服务端先跨库 RRF 合并,再仅对合并候选池执行一次 rerank。
recallLimitbodyinteger否全局召回宽度,上限 100,且必须 ≥ limit 且 ≥ 所选知识库数量。
rerankModelbodystring否显式 rerank 模型 ID。
rerankProviderRefbodystring否钉定 rerank provider(project: / trial: 前缀)。
similarityThresholdbodynumber否作用于每个库的最低相似度;省略用各库默认。
vectorWeightbodynumber否作用于每个库的 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 高级查询。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
statusquerystring否默认 ""按处理状态过滤:uploaded / processing / ready / failed。
stagequerystring否默认 ""按处理阶段过滤。
enabledqueryboolean否按启用状态过滤。
queriesquerystring[]否默认 []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 的文件登记为文档(登记本身不触发摄取,需再调摄取端点)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
bucketIdbodystring否源文件所在桶 ID;缺省用库默认桶。
fileIdbodystring是已上传源文件的 Storage 文件 ID(必填)。
namebodystring否文档显示名,缺省用源文件名。
sourcebodystring否文档来源标记,默认 manual。
externalItemIdbodystring否来自外部数据源时的条目 ID(同步去重用)。
parserIdbodystring否枚举:general / title / smart / regex / faq文档级切片策略覆盖。
parserConfigbodyobject否文档级解析/切片配置覆盖(子字段见下)。
parserConfig.chunkTokenNumbodyinteger否每个切片的 token 预算:general/smart 默认 512,title/regex 默认 256。
parserConfig.overlapPercentbodyinteger否默认 10general 切片器的 token 重叠百分比,默认 10。
parserConfig.delimiterbodystring否超长 title/regex 切片的分隔符;默认 title 为 \n。;!?,regex 为 \n。.;;!!??。
parserConfig.titleLevelbodyinteger否默认 3title 切片器使用的 Markdown 标题级别,默认 3。
parserConfig.minChunkTokensbodyinteger否默认 128smart 切片器最小切片大小,默认 128,不得超过 chunkTokenNum。
parserConfig.regexPatternbodystring否默认 "[.!?]+\\s*"regex 切片器使用的 PCRE 表达式,默认 [.!?]+\s*。
parserConfig.documentParserbodystring否枚举:text / vlm / mineru文档解析器:text(纯文本)/ vlm(视觉模型)/ mineru;MinerU 部署与凭证不属于本 API。
parserConfig.visionModelbodystring否documentParser=vlm 时使用的视觉模型。
parserConfig.visionProviderRefbodystring否视觉模型的钉定 provider 引用。
parserConfig.imageUnderstandingbodyobject否图片解读配置(动态对象):enabled=true 时 model 与 providerRef 必填;另含 prompt、maxImagesPerDocument(默认 20)、maxDescriptionChars(默认 800)、maxConcurrency(默认 4)。
metadatabodyobject否业务元数据。

登记后调用 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 个文件,先整体校验再创建)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
fileIdsbodystring[]是Storage 文件 ID 数组,1–50 个且不重复。
bucketIdbodystring否文件所在桶;缺省用库默认桶,全部文件须同桶。
sourcebodystring否所有文档的来源标记,默认 manual。
parserIdbodystring否枚举:general / title / smart / regex / faq文档级切片策略覆盖(对本批生效)。
parserConfigbodyobject否文档级解析/切片配置覆盖(对本批生效,子字段见下)。
parserConfig.chunkTokenNumbodyinteger否每个切片的 token 预算:general/smart 默认 512,title/regex 默认 256。
parserConfig.overlapPercentbodyinteger否默认 10general 切片器的 token 重叠百分比,默认 10。
parserConfig.delimiterbodystring否超长 title/regex 切片的分隔符;默认 title 为 \n。;!?,regex 为 \n。.;;!!??。
parserConfig.titleLevelbodyinteger否默认 3title 切片器使用的 Markdown 标题级别,默认 3。
parserConfig.minChunkTokensbodyinteger否默认 128smart 切片器最小切片大小,默认 128,不得超过 chunkTokenNum。
parserConfig.regexPatternbodystring否默认 "[.!?]+\\s*"regex 切片器使用的 PCRE 表达式,默认 [.!?]+\s*。
parserConfig.documentParserbodystring否枚举:text / vlm / mineru文档解析器:text(纯文本)/ vlm(视觉模型)/ mineru;MinerU 部署与凭证不属于本 API。
parserConfig.visionModelbodystring否documentParser=vlm 时使用的视觉模型。
parserConfig.visionProviderRefbodystring否视觉模型的钉定 provider 引用。
parserConfig.imageUnderstandingbodyobject否图片解读配置(动态对象):enabled=true 时 model 与 providerRef 必填;另含 prompt、maxImagesPerDocument(默认 20)、maxDescriptionChars(默认 800)、maxConcurrency(默认 4)。
metadatabodyobject否本批文档共享的业务元数据。

输出:

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 会话导入当前用户的个人语雀文档(无需团队数据源)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
sessionIdbodystring是createYuqueOAuthSession 返回的 OAuth 会话 ID。
urlsbodystring[]是语雀文档 URL 数组,最多 20 条;仅接受受支持的语雀 HTTPS 域名与精确 {group}/{book}/{slug} 路径。
idempotencyKeybodystring否批量幂等键前缀。

输出:

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*stringRequested Yuque document URL.
status*stringPer-URL import outcome: accepted, unchanged, or failed.
documentobjectImported knowledge base document when status is accepted or unchanged.
errorstringHuman-readable failure detail when status is failed.
errorTypestringMachine-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 获取文档(含处理状态、代数与切片计数)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
documentIdpathstring是目标文档 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

更新文档名称、切片覆盖配置、元数据或启用状态(只改传入字段)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
documentIdpathstring是目标文档 ID。
namebodystring否文档显示名。
parserIdbodystring否枚举:general / title / smart / regex / faq / (空,表示不限)文档级切片策略覆盖;传空串清除覆盖、回退库默认。
parserConfigbodyobject否文档级解析/切片配置覆盖(子字段见下)。
parserConfig.chunkTokenNumbodyinteger否每个切片的 token 预算:general/smart 默认 512,title/regex 默认 256。
parserConfig.overlapPercentbodyinteger否默认 10general 切片器的 token 重叠百分比,默认 10。
parserConfig.delimiterbodystring否超长 title/regex 切片的分隔符;默认 title 为 \n。;!?,regex 为 \n。.;;!!??。
parserConfig.titleLevelbodyinteger否默认 3title 切片器使用的 Markdown 标题级别,默认 3。
parserConfig.minChunkTokensbodyinteger否默认 128smart 切片器最小切片大小,默认 128,不得超过 chunkTokenNum。
parserConfig.regexPatternbodystring否默认 "[.!?]+\\s*"regex 切片器使用的 PCRE 表达式,默认 [.!?]+\s*。
parserConfig.documentParserbodystring否枚举:text / vlm / mineru文档解析器:text(纯文本)/ vlm(视觉模型)/ mineru;MinerU 部署与凭证不属于本 API。
parserConfig.visionModelbodystring否documentParser=vlm 时使用的视觉模型。
parserConfig.visionProviderRefbodystring否视觉模型的钉定 provider 引用。
parserConfig.imageUnderstandingbodyobject否图片解读配置(动态对象):enabled=true 时 model 与 providerRef 必填;另含 prompt、maxImagesPerDocument(默认 20)、maxDescriptionChars(默认 800)、maxConcurrency(默认 4)。
metadatabodyobject否业务元数据。
enabledbodyboolean否置 false 后文档切片保留但不参与检索结果。
statusbodystring否处理状态(仅 API Key 可改的遗留修正字段)。
stagebodystring否处理阶段(仅 API Key 可改的遗留修正字段)。
chunksTotalbodyinteger否切片总数(仅 API Key 可改的遗留修正字段)。
chunkCountbodyinteger否切片数(仅 API Key 可改的遗留修正字段)。
errorbodystring否错误信息(仅 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)、摄取记录并递减库文档计数。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
documentIdpathstring是目标文档 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

以当前配置对既有文档触发一次(重)处理,等价于默认参数创建摄取。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
documentIdpathstring是目标文档 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*stringeffectiveConfig 哈希,用于比对配置是否变化。
retryOf*string重试时指向的前次摄取 ID。
attemptId*string本次尝试的 fencing token。
idempotencyKey*string请求方幂等键。
error*stringfailed 时的错误信息。
startedAt*stringworker 开始处理时间。
finishedAt*string摄取结束时间。
trackingChannels*objectRealtime 订阅频道: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)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
documentIdpathstring是目标文档 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

列出文档当前活跃代数的切片,支持内容关键词搜索与高级查询。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
documentIdpathstring是目标文档 ID。
searchquerystring否默认 ""在切片正文内做关键词搜索。
queriesquerystring[]否默认 []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 计算)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
documentIdpathstring是目标文档 ID。
contentbodystring是切片正文(必填)。
metadatabodyobject否任意切片元数据。

输出:

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 获取单个切片。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
documentIdpathstring是目标文档 ID。
chunkIdpathstring是目标切片 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 向量。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
documentIdpathstring是目标文档 ID。
chunkIdpathstring是目标切片 ID。
contentbodystring否新正文;传入即触发向量重算(连同已持久化的图片描述)。
metadatabodyobject否切片元数据;仅当图片描述变化时才重算向量。

输出:

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 相应递减。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
documentIdpathstring是目标文档 ID。
chunkIdpathstring是目标切片 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 过滤排序。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
documentIdpathstring是目标文档 ID。
queriesquerystring[]否默认 []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*stringeffectiveConfig 哈希,用于比对配置是否变化。
retryOf*string重试时指向的前次摄取 ID。
attemptId*string本次尝试的 fencing token。
idempotencyKey*string请求方幂等键。
error*stringfailed 时的错误信息。
startedAt*stringworker 开始处理时间。
finishedAt*string摄取结束时间。
trackingChannels*objectRealtime 订阅频道: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 异步执行。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
documentIdpathstring是目标文档 ID。
idempotencyKeybodystring否幂等键:同键重试返回既有摄取,不会重复入队。
retryOfbodystring否要重试的前次失败摄取 ID。
persistToDocumentbodyboolean否为 true 时摄取完成后把本次 overrides 固化为文档级配置。
overridesbodyobject否仅本次摄取生效的解析覆盖;embedding 相关字段会被拒绝(子字段见下)。
overrides.parserIdbodystring否枚举:general / title / smart / regex / faq本次摄取的切片策略覆盖。
overrides.parserConfigbodyobject否本次摄取的解析/切片配置覆盖,子字段同 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*stringeffectiveConfig 哈希,用于比对配置是否变化。
retryOf*string重试时指向的前次摄取 ID。
attemptId*string本次尝试的 fencing token。
idempotencyKey*string请求方幂等键。
error*stringfailed 时的错误信息。
startedAt*stringworker 开始处理时间。
finishedAt*string摄取结束时间。
trackingChannels*objectRealtime 订阅频道: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

查询单个摄取任务的状态、阶段、进度与错误。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
documentIdpathstring是目标文档 ID。
ingestionIdpathstring是目标摄取任务 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*stringeffectiveConfig 哈希,用于比对配置是否变化。
retryOf*string重试时指向的前次摄取 ID。
attemptId*string本次尝试的 fencing token。
idempotencyKey*string请求方幂等键。
error*stringfailed 时的错误信息。
startedAt*stringworker 开始处理时间。
finishedAt*string摄取结束时间。
trackingChannels*objectRealtime 订阅频道: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,终态任务保持不变(幂等)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
documentIdpathstring是目标文档 ID。
ingestionIdpathstring是目标摄取任务 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*stringeffectiveConfig 哈希,用于比对配置是否变化。
retryOf*string重试时指向的前次摄取 ID。
attemptId*string本次尝试的 fencing token。
idempotencyKey*string请求方幂等键。
error*stringfailed 时的错误信息。
startedAt*stringworker 开始处理时间。
finishedAt*string摄取结束时间。
trackingChannels*objectRealtime 订阅频道: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 过滤。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
typequerystring否默认 ""按数据源类型过滤(当前 yuque)。
statusquerystring否默认 ""按状态过滤: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

为知识库接入外部数据源(当前支持语雀团队空间),可选注册周期同步。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
namebodystring是数据源名称。
typebodystring否枚举:yuque数据源类型;当前枚举仅 yuque。
configbodyobject否非敏感配置对象(语雀:repoNamespaces、syncSchedule cron 等)。
credentialsbodyobject否凭证对象(如语雀团队令牌);落库加密,响应永不回显。
statusbodystring否枚举:active / disabledactive / disabled;active 且配置了 config.syncSchedule 时自动注册周期同步。
triggerSyncbodyboolean否为 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 获取数据源(凭证不回显)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
dataSourceIdpathstring是目标数据源 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

更新数据源名称、配置、凭证或状态;凭证按键合并而非整体替换。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
dataSourceIdpathstring是目标数据源 ID。
namebodystring否数据源名称。
configbodyobject否非敏感配置对象。
credentialsbodyobject否增量合并到已存凭证的键值对。
statusbodystring否枚举: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

删除数据源及其同步历史与周期计划;已生成的知识库文档不受影响。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
dataSourceIdpathstring是目标数据源 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(令牌即用即弃、不落库)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
teamIdbodystring是语雀团队 ID。
teamTokenbodystring是语雀开放 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

枚举选定仓库下可导入的语雀文档列表(令牌不存储)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
teamIdbodystring是语雀团队 ID。
teamTokenbodystring是语雀开放 API 团队令牌(不存储)。
repoNamespacesbodystring[]否仓库 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。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
dataSourceIdpathstring是目标数据源 ID。
urlbodystring是语雀文档 URL;仅接受受支持语雀 HTTPS 域名与精确 {group}/{book}/{slug} 路径。
idempotencyKeybodystring否幂等键。

输出:

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 条,逐项返回结果)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
dataSourceIdpathstring是目标数据源 ID。
urlsbodystring[]是语雀文档 URL 数组,最多 20 条、不重复。
idempotencyKeybodystring否批量幂等键前缀。

输出:

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*stringRequested Yuque document URL.
status*stringPer-URL import outcome: accepted, unchanged, or failed.
documentobjectImported knowledge base document when status is accepted or unchanged.
errorstringHuman-readable failure detail when status is failed.
errorTypestringMachine-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 过滤。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
dataSourceIdpathstring是目标数据源 ID。
statusquerystring否默认 ""按同步状态过滤: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*stringfailed 时的错误信息。
startedAt*stringworker 开始处理时间。
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 同步时直接返回既有记录,不重复排队。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
dataSourceIdpathstring是目标数据源 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*stringfailed 时的错误信息。
startedAt*stringworker 开始处理时间。
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

查询单次同步的状态、游标推进与统计。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是所属知识库 ID。
dataSourceIdpathstring是目标数据源 ID。
syncIdpathstring是目标同步记录 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*stringfailed 时的错误信息。
startedAt*stringworker 开始处理时间。
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 会话,用于导入个人文档。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
forcebodyboolean否为 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 会话状态;授权成功后即可发起个人文档导入。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 ID。
sessionIdpathstring是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 凭证(幂等;不撤销语雀侧授权)。

输入:

参数位置类型必填默认/枚举说明
knowledgeBaseIdpathstring是目标知识库 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>"

错误与边界

与 Server SDK 的对应

service.method端点
KnowledgeBases.list / create / get / update / delete/knowledgebases CRUD
KnowledgeBases.createSearch / createMultiSearchPOST .../{id}/search、POST /knowledgebases/search
KnowledgeBases.getManagement / createReindexGET .../management、POST .../reindex
KnowledgeBases.listDocuments / createDocument / createDocumentsBatch / createYuqueDocuments / getDocument / updateDocument / deleteDocument/knowledgebases/{id}/documents*
KnowledgeBases.createDocumentProcess / getDocumentSourcePOST .../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/reposdocs`
KnowledgeBases.createDataSourceDocument / createDataSourceDocumentsBatch / listDataSourceSyncs / createDataSourceSync / getDataSourceSync.../datasources/{dataSourceId}/documents*、syncs*
KnowledgeBases.createYuqueOAuthSession / getYuqueOAuthSession / deleteYuqueOAuthCredential.../yuque/oauth/*

事实源