知识库 API
运行示例前,将 <APPBASE_ENDPOINT_WITH_V1> 替换为目标环境的 API 地址,并核对项目及凭据属于同一环境。
富文档 RAG 知识库全链路接口:知识库 CRUD、文档摄取(Storage 文件登记 + 解析/切片/Embedding 流水线)、切片(chunk)级维护、数据源(data source)连接与同步、单库/跨库语义检索、重建索引与管理观测。
服务与资源边界
知识库(KnowledgeBases)与词库(Lexicons)模块构成 Agentbase 平台的企业级多源 RAG 与查询改写核心引擎:
全链路 RAG 生命周期:覆盖知识库(
{knowledgeBaseId},如kb_enterprise_support)创建、Storage 文件/外部数据源摄取、结构化解析切片(Chunking)、向量化(如dashscope-prod的text-embedding-v31024 维模型)、单库/跨库混合检索与重排(qwen3.7-text-rerank)。项目级词库(Lexicons)协同:项目可维护同义词、扩展词和停止词,并将词库绑定到知识库或智能体工作台。知识库直接搜索忽略停止词;工作台要拦截停止词,须绑定词库并启用
stopIntercept。派生索引与版本治理协同:知识库之上的 Wiki 自动编译、GraphRAG 知识图谱与 RAPTOR 层次聚类索引详见 Wiki 与索引治理 API;知识库不可变版本封存(Seal)、发布(Publish)与回滚详见 知识库版本管理 API。
文档定位参数中,仅创建支持 sectionCode;检索与列表通过 documentTag、subProductId 过滤,不接受独立的 sectionCode 过滤参数。
资源与基础路径
Base URL:
https://<your-endpoint>/v1,路径前缀/knowledgebases。层级:知识库
{knowledgeBaseId}→ 文档{documentId}→ 切片{chunkId};旁路资源:数据源{dataSourceId}、同步{syncId}、摄取{ingestionId}。源文件存放于 Storage:每个知识库有默认桶;登记文档时引用已上传文件的
fileId(见 storage)。
认证与权限
认证与请求头约定见 通用约定。本域 scope:knowledgebases.read(查询、检索、管理摘要)、knowledgebases.write(全部写操作)。Embedding / Rerank 经 LLM Gateway 执行(provider 引用格式 project:<providerId> 或 trial:<bindingId>,见 llm-gateway)。
端点总览
本页涵盖两大核心路径前缀:/v1/knowledgebases(知识库、文档、切片、摄取、数据源与检索)与 /v1/lexicons(项目词库、词条、导入导出、改写预览与资源引用)。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
GET /knowledgebases | 列出知识库 |
POST /knowledgebases | 创建知识库 |
GET /knowledgebases/{knowledgeBaseId} | 获取知识库 |
PATCH /knowledgebases/{knowledgeBaseId} | 更新知识库 |
DELETE /knowledgebases/{knowledgeBaseId} | 删除知识库 |
POST /knowledgebases/search | 跨库检索(1–10 库) |
POST /knowledgebases/{knowledgeBaseId}/search | 单库检索 |
GET /knowledgebases/{knowledgeBaseId}/management | 管理摘要(最近摄取/trace/评分) |
POST /knowledgebases/{knowledgeBaseId}/reindex | 有界批量重建索引 |
GET /knowledgebases/{knowledgeBaseId}/documents | 列出文档 |
POST /knowledgebases/{knowledgeBaseId}/documents | 登记文档;摄取需另行发起 |
POST /knowledgebases/{knowledgeBaseId}/documents/batch | 批量登记(最多 50 文件) |
DELETE /knowledgebases/{knowledgeBaseId}/documents | 批量删除文档(最多 50 个,预检原子) |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId} | 获取文档 |
PATCH /knowledgebases/{knowledgeBaseId}/documents/{documentId} | 更新文档 |
DELETE /knowledgebases/{knowledgeBaseId}/documents/{documentId} | 删除文档 |
POST /knowledgebases/{knowledgeBaseId}/documents/{documentId}/process | 触发(重)处理 |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/source | 下载原始源文件 |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/content | 读取文档内容及截断状态 |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact | 查看当前解析产物状态 |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact/content | 读取解析后的 Markdown |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks | 列出切片 |
POST /knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks | 手工建切片 |
GET|PATCH|DELETE .../chunks/{chunkId} | 切片读改删 |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions | 摄取任务列表 |
POST /knowledgebases/{knowledgeBaseId}/documents/{documentId}/ingestions | 发起摄取 |
GET|DELETE .../ingestions/{ingestionId} | 摄取详情/取消 |
GET /knowledgebases/{knowledgeBaseId}/datasources | 列出数据源 |
POST /knowledgebases/{knowledgeBaseId}/datasources | 创建外部数据源(语雀团队空间) |
GET|PATCH|DELETE .../datasources/{dataSourceId} | 数据源读改删 |
POST .../datasources/yuque/repos、POST .../datasources/yuque/docs | 枚举语雀团队仓库与文档清单 |
POST .../datasources/{dataSourceId}/documents | 从数据源 URL 导入单篇 |
POST .../datasources/{dataSourceId}/documents/batch | 批量导入(最多 20 URL) |
GET|POST .../datasources/{dataSourceId}/syncs、GET .../syncs/{syncId} | 数据源同步与状态轮询 |
GET /knowledgebases/{knowledgeBaseId}/version-adoptions | 列出采纳操作(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/version-adoptions | 启动版本采纳(异步)(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId} | 获取采纳操作(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/version-adoptions/{adoptionId}/cancel | 请求取消采纳(异步)(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/version-delete-operations/{operationId} | 查询版本删除操作(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/versions | 列出版本(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/versions | 创建工作副本(异步)(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/versions/{versionId} | 获取版本(见 版本管理) |
DELETE /knowledgebases/{knowledgeBaseId}/versions/{versionId} | 请求不可逆删除版本(异步)(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/publish | 发布 READY 版本为当前版本(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/versions/{versionId}/readiness | 版本就绪摘要(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/rollback | 回滚到保留的回滚目标(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/versions/{versionId}/seal | 封存 DRAFT 为 READY(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/working-copy-operations | 列出工作副本操作(见 版本管理) |
GET /knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId} | 获取工作副本操作(见 版本管理) |
POST /knowledgebases/{knowledgeBaseId}/working-copy-operations/{operationId}/cancel | 请求取消工作副本操作(见 版本管理) |
GET /lexicons | 列出项目词库 |
POST /lexicons | 创建项目词库 |
GET /lexicons/{lexiconId} | 获取词库详情 |
PATCH /lexicons/{lexiconId} | 更新词库元数据与权限 |
DELETE /lexicons/{lexiconId} | 删除未绑定的词库 |
GET /lexicons/{lexiconId}/entries | 列出词库词条(支持按 entryType 过滤) |
POST /lexicons/{lexiconId}/entries | 创建词条(synonym / expansion / stop) |
GET|PATCH|DELETE /lexicons/{lexiconId}/entries/{entryId} | 词条详情/更新/删除 |
POST /lexicons/{lexiconId}/preview | 预览查询改写与停用词命中效果 |
POST /lexicons/{lexiconId}/import | 批量导入词条(JSON / CSV / XLSX,支持 dryRun) |
GET /lexicons/{lexiconId}/export | 导出词库词条文件(JSON / CSV / XLSX) |
GET /lexicons/{lexiconId}/references | 查询绑定了该词库的知识库与智能体列表 |
GET|PUT /knowledgebases/{knowledgeBaseId}/lexicons | 查询/整体替换知识库绑定的词库列表 |
GET|PUT /agent-runtime/project/lexicons | 查询/整体替换当前项目智能体工作台绑定的词库列表 |
GET|PATCH /knowledgebases/{knowledgeBaseId}/index-capabilities*、POST|GET .../index-operations* | GraphRAG / RAPTOR / LLM Wiki 索引能力治理与构建任务(见 Wiki 与索引治理) |
GET /knowledgebases/{knowledgeBaseId}/graph*、GET|POST .../wiki/* | 知识图谱、实体邻居、社区报告与 LLM Wiki 治理(见 Wiki 与索引治理) |
端点详解
词库修订号(
revision)与事务锁:每次增删改词条或批量导入(dryRun=false)时,词库主文档的revision原子递增;在绑定词库至知识库或构建 GraphRAG 索引快照时,服务端通过行锁保证词条快照一致性。词条去重与配额上限:单个词库最多容纳
1,000条词条(LexiconService::MAX_ENTRIES = 1000),且内置基于规则类型与归一化词项的dedupeKey唯一性校验;被知识库或智能体引用的词库在解绑前禁止直接删除(返回409 general_conflict)。
请求与响应
以下按资源域逐端点给出输入、输出与可复制的调用/响应示例。通用约定:
认证:所有请求携带
X-Appwrite-Project: <YOUR_PROJECT_ID>与X-Appwrite-Key: <YOUR_API_KEY>;scopeknowledgebases.read覆盖查询/检索/管理摘要,knowledgebases.write覆盖全部写操作。异步任务(登记后的摄取
202、重处理202、reindex202、数据源同步202)一律通过对应的GET详情端点轮询终态;摄取任务另支持 RealtimetrackingChannels订阅。示例中的资源 ID(
kb_product_docs、doc_manual_v2、chk_0042、ds_yuque_team)请替换为实际值。Embedding 与重排经 LLM Gateway 执行,provider 引用格式
project:<providerId>或trial:<bindingId>(见 llm-gateway)。
知识库管理
GET /v1/knowledgebases
SDK:KnowledgeBases.list · scope:knowledgebases.read
列出当前项目全部知识库,可按 ID/名称搜索。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
search | query | string | 否 | 默认 "" | 按知识库 ID 或名称过滤,最长 256 字符。 |
输出:
200,返回模型 Models.KnowledgeBaseList。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 匹配查询的知识库总数。 |
knowledgeBases* | object[] | 知识库列表。 |
$id* | string | 知识库 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
name* | string | 知识库名称。 |
description* | string | 知识库描述。 |
embeddingModel* | string | 建库时固定的 Embedding 模型 ID。 |
embeddingProviderRef* | string | 钉定的 Embedding provider 来源(project:<providerId> / trial:<bindingId>),空表示自动路由。 |
embeddingDimension* | integer | Embedding 向量维度,与模型输出一致,建库后不可改。 |
parserId* | string | 默认切片策略:general / title / smart / regex / faq。 |
parserConfig* | object | 默认解析/切片配置(动态对象,字段见创建端点)。 |
retrievalDefaults* | object | 检索默认值(如 similarityThreshold、vectorWeight、限流)。 |
vectorsdbDatabaseId* | string | Backing 的 VectorsDB 库 ID,provision 完成前为 null。 |
vectorsdbCollectionId* | string | Backing 的 VectorsDB 集合 ID,provision 完成前为 null。 |
bucketId* | string | 默认 Storage 桶 ID(文档源文件存放处),provision 完成前为 null。 |
iconFileId* | string | 头像/图标文件 ID,未设置时为 null。 |
ingestRoutes* | object | 已废弃的 MIME→Function 映射,仅为兼容保留。 |
documentCount* | integer | 库内文档总数。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases?search=产品手册" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 2,
"knowledgeBases": [
{
"$id": "kb_product_docs",
"$createdAt": "2026-08-30T09:00:00.000+00:00",
"$updatedAt": "2026-09-14T02:01:12.000+00:00",
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"embeddingModel": "text-embedding-v3",
"embeddingProviderRef": "",
"embeddingDimension": 1024,
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
},
"retrievalDefaults": {
"similarityThreshold": 0.5,
"vectorWeight": 0.7
},
"vectorsdbDatabaseId": "vdb_kb_docs",
"vectorsdbCollectionId": "col_kb_docs",
"bucketId": "bkt_kb_docs",
"iconFileId": "",
"ingestRoutes": {},
"documentCount": 2
}
]
}POST /v1/knowledgebases
SDK:KnowledgeBases.create · scope:knowledgebases.write
创建知识库:钉定 Embedding 模型并自动 provision 专用 VectorsDB 库/集合与 Storage 桶。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | body | string | 是 | 知识库 ID:自定义或 ID.unique() 生成。 | |
name | body | string | 是 | 知识库名称。 | |
description | body | string | 否 | 知识库描述。 | |
embeddingModel | body | string | 是 | Embedding 模型 ID;创建时对 LLM Gateway 探测一次得出向量维度,建库后模型与维度不可改。 | |
embeddingProviderRef | body | string | 否 | 钉定 Embedding provider(project:<providerId> / trial:<bindingId>);省略走自动路由。 | |
embeddingDimension | body | integer | 否 | 1–65535 | 显式向量维度(2.9.0):对所选模型探测校验,与模型输出维度不符则创建失败(400)。 |
tracingEnabled | body | boolean | 否 | 默认 false | 摄取追踪开关(2.9.0):记录解析 / 分块中间产物供「知识库解析评估」使用;依赖平台管理员全局开关,开启后需重新摄取才有完整证据。 |
parserId(或 chunkingStrategy) | body | string | 否 | 枚举:general / title / smart / regex / faq / sheet | 库级默认分块策略(Chunking Strategy),未覆盖的文档按此切分。 |
parser | body | string | 否 | 枚举:text / mineru / vlm / office | 库级默认文档解析器简写(等价于 parserConfig.documentParser)。 |
parserConfig | body | object | 否 | 库级默认解析/分块与多模态配置(子字段见下)。 | |
parserConfig.chunkTokenNum | body | integer | 否 | 每个切片的 token 预算:general/smart 默认 512,title/regex 默认 256,范围 64–4096。 | |
parserConfig.overlapPercent | body | integer | 否 | 默认 10 | general/smart 切片器的相邻切片 token 重叠百分比,默认 10(0–50)。 |
parserConfig.delimiter | body | string | 否 | 超长 title/regex 切片的降级切分分隔符;默认 title 为 \n。;!?,regex 为 \n。.;;!!??。 | |
parserConfig.titleLevel | body | integer | 否 | 默认 3 | title 切片器拆分的 Markdown 标题层级上限(1–6,默认 3 即拆至 ###)。 |
parserConfig.minChunkTokens | body | integer | 否 | 默认 128 | smart 切片器最小切片大小,默认 128,不得超过 chunkTokenNum。 |
parserConfig.regexPattern | body | string | 否 | 默认 "[.!?]+\\s*" | regex 切片器使用的 PCRE 正则表达式,默认 [.!?]+\s*。 |
parserConfig.documentParser | body | string | 否 | 枚举:text / mineru / vlm / office | 文档解析引擎:text(纯文本/源码解析)、mineru(复杂版面 PDF/表格与公式结构化解析)、vlm(视觉大模型整页解析)、office(Word/Excel/PPT 原生样式与表头提取)。 |
parserConfig.visionModel | body | string | 否 | documentParser=vlm 时使用的视觉大模型(如 qwen-vl-max)。 | |
parserConfig.visionProviderRef | body | string | 否 | 视觉模型的钉定 provider 引用(如 project:dashscope-prod)。 | |
parserConfig.imageUnderstanding(或顶层 imageUnderstanding) | body | object | 否 | 多模态图片理解配置:enabled(boolean,是否开启插图提取与语义转写)、providerRef(string,必填如 "project:dashscope-prod")、model(string,必填如 "qwen-vl-max")、maxConcurrency(integer,并发度 1–8,默认 4)、prompt(string,自定义视觉理解提示词)、maxImagesPerDocument(integer,单文档图片上限,默认 20)、maxDescriptionChars(integer,单图描述字数上限,默认 800)。 | |
retrievalDefaults | body | object | 否 | 检索默认值(如 similarityThreshold、vectorWeight)。 | |
ingestRoutes | body | object | 否 | 已废弃的 MIME→Function 映射,仅为兼容保留。 |
Provision 异步进行:响应中 vectorsdbDatabaseId / vectorsdbCollectionId / bucketId 可能短暂为 null,稍后重新 GET 确认。
输出:
201,返回模型 Models.KnowledgeBase。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 知识库 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
name* | string | 知识库名称。 |
description* | string | 知识库描述。 |
embeddingModel* | string | 建库时固定的 Embedding 模型 ID。 |
embeddingProviderRef* | string | 钉定的 Embedding provider 来源(project:<providerId> / trial:<bindingId>),空表示自动路由。 |
embeddingDimension* | integer | Embedding 向量维度,与模型输出一致,建库后不可改。 |
parserId* | string | 默认切片策略:general / title / smart / regex / faq。 |
parserConfig* | object | 默认解析/切片配置(动态对象,字段见创建端点)。 |
retrievalDefaults* | object | 检索默认值(如 similarityThreshold、vectorWeight、限流)。 |
vectorsdbDatabaseId* | string | Backing 的 VectorsDB 库 ID,provision 完成前为 null。 |
vectorsdbCollectionId* | string | Backing 的 VectorsDB 集合 ID,provision 完成前为 null。 |
bucketId* | string | 默认 Storage 桶 ID(文档源文件存放处),provision 完成前为 null。 |
iconFileId* | string | 头像/图标文件 ID,未设置时为 null。 |
ingestRoutes* | object | 已废弃的 MIME→Function 映射,仅为兼容保留。 |
documentCount* | integer | 库内文档总数。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"knowledgeBaseId": "kb_product_docs",
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"embeddingModel": "text-embedding-v3",
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
},
"retrievalDefaults": {
"similarityThreshold": 0.5,
"vectorWeight": 0.7
},
"ingestRoutes": {}
}'响应示例:
{
"$id": "kb_product_docs",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"embeddingModel": "text-embedding-v3",
"embeddingProviderRef": "",
"embeddingDimension": 1024,
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
},
"retrievalDefaults": {
"similarityThreshold": 0.5,
"vectorWeight": 0.7
},
"vectorsdbDatabaseId": "vdb_kb_docs",
"vectorsdbCollectionId": "col_kb_docs",
"bucketId": "bkt_kb_docs",
"iconFileId": "",
"ingestRoutes": {},
"documentCount": 12
}GET /v1/knowledgebases/{knowledgeBaseId}
SDK:KnowledgeBases.get · scope:knowledgebases.read
按 ID 获取知识库(含 provision 状态与文档计数)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 |
输出:
200,返回模型 Models.KnowledgeBase。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 知识库 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
name* | string | 知识库名称。 |
description* | string | 知识库描述。 |
embeddingModel* | string | 建库时固定的 Embedding 模型 ID。 |
embeddingProviderRef* | string | 钉定的 Embedding provider 来源(project:<providerId> / trial:<bindingId>),空表示自动路由。 |
embeddingDimension* | integer | Embedding 向量维度,与模型输出一致,建库后不可改。 |
parserId* | string | 默认切片策略:general / title / smart / regex / faq。 |
parserConfig* | object | 默认解析/切片配置(动态对象,字段见创建端点)。 |
retrievalDefaults* | object | 检索默认值(如 similarityThreshold、vectorWeight、限流)。 |
vectorsdbDatabaseId* | string | Backing 的 VectorsDB 库 ID,provision 完成前为 null。 |
vectorsdbCollectionId* | string | Backing 的 VectorsDB 集合 ID,provision 完成前为 null。 |
bucketId* | string | 默认 Storage 桶 ID(文档源文件存放处),provision 完成前为 null。 |
iconFileId* | string | 头像/图标文件 ID,未设置时为 null。 |
ingestRoutes* | object | 已废弃的 MIME→Function 映射,仅为兼容保留。 |
documentCount* | integer | 库内文档总数。 |
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"$id": "kb_product_docs",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"embeddingModel": "text-embedding-v3",
"embeddingProviderRef": "",
"embeddingDimension": 1024,
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
},
"retrievalDefaults": {
"similarityThreshold": 0.5,
"vectorWeight": 0.7
},
"vectorsdbDatabaseId": "vdb_kb_docs",
"vectorsdbCollectionId": "col_kb_docs",
"bucketId": "bkt_kb_docs",
"iconFileId": "",
"ingestRoutes": {},
"documentCount": 12
}PATCH /v1/knowledgebases/{knowledgeBaseId}
SDK:KnowledgeBases.update · scope:knowledgebases.write
更新知识库名称、默认解析配置或检索默认值(只改传入字段)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
name | body | string | 否 | 新名称。 | |
description | body | string | 否 | 新描述。 | |
embeddingProviderRef | body | string | 否 | 钉定 Embedding provider;旧库仅可设置一次。 | |
parserId | body | string | 否 | 枚举:general / title / smart / regex / faq | 库级默认切片策略。 |
parserConfig | body | object | 否 | 库级默认解析/切片配置(子字段见下)。 | |
parserConfig.chunkTokenNum | body | integer | 否 | 每个切片的 token 预算:general/smart 默认 512,title/regex 默认 256。 | |
parserConfig.overlapPercent | body | integer | 否 | 默认 10 | general 切片器的 token 重叠百分比,默认 10。 |
parserConfig.delimiter | body | string | 否 | 超长 title/regex 切片的分隔符;默认 title 为 \n。;!?,regex 为 \n。.;;!!??。 | |
parserConfig.titleLevel | body | integer | 否 | 默认 3 | title 切片器使用的 Markdown 标题级别,默认 3。 |
parserConfig.minChunkTokens | body | integer | 否 | 默认 128 | smart 切片器最小切片大小,默认 128,不得超过 chunkTokenNum。 |
parserConfig.regexPattern | body | string | 否 | 默认 "[.!?]+\\s*" | regex 切片器使用的 PCRE 表达式,默认 [.!?]+\s*。 |
parserConfig.documentParser | body | string | 否 | 枚举:text / vlm / mineru | 文档解析器:text(纯文本)/ vlm(视觉模型)/ mineru;MinerU 部署与凭证不属于本 API。 |
parserConfig.visionModel | body | string | 否 | documentParser=vlm 时使用的视觉模型。 | |
parserConfig.visionProviderRef | body | string | 否 | 视觉模型的钉定 provider 引用。 | |
parserConfig.imageUnderstanding | body | object | 否 | 图片解读配置(动态对象):enabled=true 时 model 与 providerRef 必填;另含 prompt、maxImagesPerDocument(默认 20)、maxDescriptionChars(默认 800)、maxConcurrency(默认 4)。 | |
retrievalDefaults | body | object | 否 | 检索默认值。 | |
ingestRoutes | body | object | 否 | 已废弃字段,仅为兼容保留。 | |
iconFileId | body | string | 否 | 头像图片的文件 ID(须已上传到本库默认桶);传空串清除头像。 |
输出:
200,返回模型 Models.KnowledgeBase。embeddingModel 与 embeddingDimension 建库后固定,不可经本端点修改。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 知识库 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
name* | string | 知识库名称。 |
description* | string | 知识库描述。 |
embeddingModel* | string | 建库时固定的 Embedding 模型 ID。 |
embeddingProviderRef* | string | 钉定的 Embedding provider 来源(project:<providerId> / trial:<bindingId>),空表示自动路由。 |
embeddingDimension* | integer | Embedding 向量维度,与模型输出一致,建库后不可改。 |
parserId* | string | 默认切片策略:general / title / smart / regex / faq。 |
parserConfig* | object | 默认解析/切片配置(动态对象,字段见创建端点)。 |
retrievalDefaults* | object | 检索默认值(如 similarityThreshold、vectorWeight、限流)。 |
vectorsdbDatabaseId* | string | Backing 的 VectorsDB 库 ID,provision 完成前为 null。 |
vectorsdbCollectionId* | string | Backing 的 VectorsDB 集合 ID,provision 完成前为 null。 |
bucketId* | string | 默认 Storage 桶 ID(文档源文件存放处),provision 完成前为 null。 |
iconFileId* | string | 头像/图标文件 ID,未设置时为 null。 |
ingestRoutes* | object | 已废弃的 MIME→Function 映射,仅为兼容保留。 |
documentCount* | integer | 库内文档总数。 |
调用示例:
curl -X PATCH "https://<your-endpoint>/v1/knowledgebases/kb_product_docs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"parserId": "smart",
"parserConfig": {},
"retrievalDefaults": {},
"ingestRoutes": {}
}'响应示例:
{
"$id": "kb_product_docs",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"name": "产品文档库",
"description": "产品手册与 FAQ 的检索库",
"embeddingModel": "text-embedding-v3",
"embeddingProviderRef": "",
"embeddingDimension": 1024,
"parserId": "smart",
"parserConfig": {
"chunkTokenNum": 512
},
"retrievalDefaults": {
"similarityThreshold": 0.5,
"vectorWeight": 0.7
},
"vectorsdbDatabaseId": "vdb_kb_docs",
"vectorsdbCollectionId": "col_kb_docs",
"bucketId": "bkt_kb_docs",
"iconFileId": "",
"ingestRoutes": {},
"documentCount": 12
}DELETE /v1/knowledgebases/{knowledgeBaseId}
SDK:KnowledgeBases.delete · scope:knowledgebases.write
删除知识库,级联删除数据源(含同步历史)、文档与摄取记录,并异步回收 VectorsDB 资源。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
deleteBucket | body | boolean | 否 | 为 true 时连同默认 Storage 桶及桶内全部文件一起删除;缺省保留桶与文件。 |
输出:
204,无响应体。
调用示例:
curl -X DELETE "https://<your-endpoint>/v1/knowledgebases/kb_product_docs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"deleteBucket": true
}'GET /v1/knowledgebases/{knowledgeBaseId}/management
SDK:KnowledgeBases.getManagement · scope:knowledgebases.read
读取知识库的内容无关处理与观测摘要(最近摄取、trace、评分)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
limit | query | integer | 否 | 默认 10 | 最近摄取/trace/评分各包含的最大条数,默认 10。 |
from | query | string | 否 | 默认 "" | 观测时间窗起点(ISO 8601)。 |
to | query | string | 否 | 默认 "" | 观测时间窗终点(ISO 8601)。 |
输出:
200,返回宽类型 JSON 对象(spec 未固定 schema)。典型包含:最近摄取任务摘要(状态/阶段/耗时)、检索 trace 摘要与评分记录;字段以实际部署返回为准,此处给出示意骨架。
调用示例:
curl -X GET "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/management?limit=10&from=2026-09-01T00:00:00Z&to=2026-09-14T00:00:00Z" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"recentIngestions": [
{
"$id": "ing_3301",
"documentId": "doc_manual_v2",
"status": "ready",
"stage": "embedding"
}
],
"recentTraces": [
{
"traceId": "4c9f2ab1",
"operation": "search",
"durationMs": 210
}
],
"recentScores": [
{
"documentId": "doc_manual_v2",
"score": 0.91,
"ratedAt": "2026-09-14T08:00:00.000+00:00"
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/reindex
SDK:KnowledgeBases.createReindex · scope:knowledgebases.write
把就绪文档有界分批地重新入队摄取(改库级解析配置后生效用)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
limit | body | integer | 否 | 本批最多入队的就绪文档数。 | |
cursor | body | string | 否 | 上一批响应返回的文档游标。 | |
idempotencyKey | body | string | 否 | 批量幂等键,防止重复入队。 |
输出:
202,返回模型 Models.KnowledgeBaseReindex;nextCursor 非 null 时携带它继续调用下一批。
| 字段 | 类型 | 说明 |
|---|---|---|
queued* | integer | 本批成功入队重摄取的就绪文档数。 |
skipped* | integer | 因已有活跃摄取而跳过的文档数。 |
failed* | integer | 本批入队失败的文档数。 |
nextCursor* | string | 下一批游标;null 表示全部完成。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/reindex" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"limit": 50,
"cursor": "cur_doc_0086",
"idempotencyKey": "idem-reindex-01"
}'响应示例:
{
"queued": 12,
"skipped": 0,
"failed": 0,
"nextCursor": null
}语义检索
POST /v1/knowledgebases/{knowledgeBaseId}/search
SDK:KnowledgeBases.createSearch · scope:knowledgebases.read
单库向量 / 全文 / 混合检索,可经 LLM Gateway 重排,返回带评分与出处的切片。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
query | body | string | 是 | 查询文本。 | |
limit | body | integer | 否 | 默认 10 | 最终返回条数,范围 1–100。 |
searchMode | body | string | 否 | 默认 hybrid;枚举:vector / fulltext / hybrid | 检索模式。 |
rerank | body | boolean | 否 | 默认 false | 为 true 时先扩大召回再经 LLM Gateway 对候选重排,最后截断到 limit。 |
recallLimit | body | integer | 否 | rerank 时省略默认 min(100, max(limit×4, 20));显式值 1–100 且不得小于 limit | 启用 rerank 时的召回宽度;关闭 rerank 时不使用。 |
rerankModel | body | string | 否 | 显式 rerank 模型 ID;启用 rerank 时覆盖自动选择。 | |
rerankProviderRef | body | string | 否 | 钉定 rerank provider:project:<providerId> 或 trial:<bindingId>;不要用 providerType:providerId 形式。 | |
similarityThreshold | body | number | 否 | 向量最低相似度阈值(作用于向量与 hybrid 的向量分支);省略用库 retrievalDefaults.similarityThreshold。 | |
vectorWeight | body | number | 否 | hybrid 向量分支权重(全文取 1 - vectorWeight);省略用库 retrievalDefaults.vectorWeight。 | |
useKnowledgeGraph | body | boolean | 否 | 默认 false | true 时加入当前可用的 GraphRAG 检索结果。 |
useWiki | body | boolean | 否 | 默认 false | true 时加入当前可用的 Wiki 检索结果。 |
graphOptions | body | object | 否 | 默认 {} | 有界 GraphRAG 检索选项;仅在 useKnowledgeGraph=true 时使用。 |
wikiOptions | body | object | 否 | 默认 {} | Wiki 检索选项,包括路由模式、topK、minK、向量与有界链接扩展;仅在 useWiki=true 时使用。 |
allowDegraded | body | boolean | 否 | 默认 true | 增强检索遇到可降级错误时,是否返回普通检索结果并列出 degradedCapabilities;设为 false 时错误向上返回。 |
answer | body | boolean | 否 | 默认 false | 答案合成(2.9.0):true 时用知识库 indexingDefaults 的 chat 模型对合并证据做接地合成(最多 12 行证据、答案 ≤1024 tokens),响应带 answer 对象。 |
documentTag | body | string | 否 | 文档定位标签;2.12.0 支持逗号分隔多个非空标签并按完整段匹配,收窄切片、GraphRAG 与 Wiki 召回范围。 | |
subProductId | body | string | 否 | 子产品编码过滤(2.10.0):优先按 metadata.subProductId 收窄召回;缺省时回退到第一个具有非空子产品段的可解析结构化标签的子产品段;与 documentTag 同为 AND 语义。 | |
metadataFilter | body | object | 否 | 文档元数据过滤(2.10.0):先筛文档再召回切片,未命中文档的切片被排除。 | |
versionId | body | string | 否 | 省略时版本化知识库默认当前 READY 版本 | 可选版本 ID;检索针对选定版本执行。 |
输出:
200,返回模型 Models.KnowledgeBaseSearchResultList:results[] 含命中切片、score(重排分或检索分)与可选 imageContexts;reranked 指示重排是否成功。本端点受库级 retrievalDefaults.rateLimit/rateLimitPeriod 与项目限流双重约束。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 返回的结果条数。 |
results* | object[] | 检索结果列表。 |
$id* | string | 命中的切片文档 ID。 |
content* | string | 命中切片正文。 |
sourceId* | string | 切片所属的知识库文档 ID。 |
source* | object | 来源文档描述与受保护源 URI(动态对象)。 |
locator* | object | 切片的章节/原文定位器(动态对象)。 |
metadata* | object | 切片元数据(剔除内部溯源字段)。 |
imageContexts* | object[] | 切片内已解读图片的关联投影(仅响应,不改切片)。 |
score* | number | 最终排序得分:重排成功用 reranker 分数,否则用初始检索分。 |
indexSource* | string | 结果来源:rag、raptor、graphrag 或 wiki。 |
resultType* | string | 结果类型:chunk、raptor_summary、graph_context 或 wiki_page。 |
resultGeneration | string / null | 派生索引结果代;普通 RAG 切片为 null。 |
reranked* | boolean | 是否经 LLM Gateway 重排成功;自动 rerank 失败降级时为 false。 |
resolvedVersionId | string / null | 本次搜索实际使用的版本;未启用版本化读取时为 null。 |
capabilities* | object | RAPTOR、GraphRAG 与 Wiki 的状态、耗时、结果代、结果及脱敏错误。 |
degradedCapabilities* | object[] | 明确发生降级的增强能力;未降级时为空数组。 |
answer | object / null | 答案合成结果(2.9.0):状态 / 文本 / 模型 / 延迟;未请求答案合成时为 null。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/search" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"query": "早餐机首次使用要注意什么",
"limit": 5,
"searchMode": "hybrid",
"rerank": false,
"similarityThreshold": 0.5,
"vectorWeight": 0.7
}'响应示例:
{
"total": 2,
"results": [
{
"$id": "chk_0042",
"content": "早餐机首次使用前请用温水清洗内胆,并空烧一次完成除味。",
"sourceId": "doc_manual_v2",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 12
},
"metadata": {
"page": 17
},
"imageContexts": [],
"score": 0.91
},
{
"$id": "chk_0043",
"content": "清洗后首次空烧时若有轻微气味属正常现象,通风放置即可。",
"sourceId": "doc_manual_v2",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 13
},
"metadata": {
"page": 17
},
"imageContexts": [
{
"chunkReferenceIndex": 0,
"url": "/v1/storage/bkt_kb_docs/files/file_img_01/view",
"description": "早餐机正面部件示意图:内胆、蒸汽阀与控制面板位置标注。"
}
],
"score": 0.86
}
],
"reranked": false
}POST /v1/knowledgebases/search
SDK:KnowledgeBases.createMultiSearch · scope:knowledgebases.read
跨库检索(1–10 个库):各库独立召回 → RRF 合并 → 统一重排一次,全局排序返回。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseIds | body | string[] | 是 | 知识库 ID 数组,1–10 个且不重复。 | |
query | body | string | 是 | 查询文本。 | |
limit | body | integer | 否 | 全局 TopK(所有库合并后的最终条数)。 | |
searchMode | body | string | 否 | 枚举:vector / fulltext / hybrid | 检索模式:vector / fulltext / hybrid。 |
rerank | body | boolean | 否 | 为 true 时各库独立召回候选,服务端先跨库 RRF 合并,再仅对合并候选池执行一次 rerank。 | |
recallLimit | body | integer | 否 | 全局召回宽度,上限 100,且必须 ≥ limit 且 ≥ 所选知识库数量。 | |
rerankModel | body | string | 否 | 显式 rerank 模型 ID。 | |
rerankProviderRef | body | string | 否 | 钉定 rerank provider(project: / trial: 前缀)。 | |
similarityThreshold | body | number | 否 | 作用于每个库的最低相似度;省略用各库默认。 | |
vectorWeight | body | number | 否 | 作用于每个库的 hybrid 向量权重;省略用各库默认。 | |
documentTag | body | string | 否 | 文档定位标签;2.12.0 支持多标签和按完整段匹配,逐库作用于切片召回。 | |
subProductId | body | string | 否 | 子产品编码过滤(2.10.0):逐库收窄召回范围。 | |
metadataFilter | body | object | 否 | 文档元数据过滤(2.10.0):按知识库 ID 分键,可带 "*" 键兜底作用于未单独配置的库;先筛文档再召回。 | |
offset | body | integer | 否 | 0 | 融合排序后跳过的结果条数(2.10.0),与 limit 组合分页。 |
输出:
200,返回模型 Models.KnowledgeBaseMultiSearchResultList,每条结果额外携带 knowledgeBaseId。严格失败语义:任一库不存在/未 provision/被限流/检索失败则整个请求失败;自动 rerank 失败降级为 RRF 顺序并置 reranked=false。preflight、召回、全局 rerank 与序列化共享 30 秒请求级总时限,超时返回 408。响应头 X-RateLimit-Limit/Remaining 取各库最小值,X-RateLimit-Reset 取最晚值,X-AppBase-Trace-Id 为本次跨库请求的统一关联 ID。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 返回的结果条数。 |
results* | object[] | 全局排序的结果列表。 |
$id* | string | 命中的切片文档 ID。 |
knowledgeBaseId* | string | 该切片所在的知识库 ID;跨库稳定标识用 (knowledgeBaseId, $id)。 |
content* | string | 命中切片正文。 |
sourceId* | string | 切片所属的知识库文档 ID。 |
source* | object | 来源文档描述与受保护源 URI(动态对象)。 |
locator* | object | 切片的章节/原文定位器(动态对象)。 |
metadata* | object | 切片元数据(剔除内部溯源字段)。 |
imageContexts* | object[] | 切片内已解读图片的关联投影(仅响应,不改切片)。 |
score* | number | 最终得分:全局重排成功用 reranker 分数,否则用跨库 RRF 分数。 |
reranked* | boolean | 合并结果是否经一次 LLM Gateway 重排成功。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/search" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"knowledgeBaseIds": [
"kb_product_docs",
"kb_faq"
],
"query": "早餐机保修多久",
"limit": 8,
"searchMode": "hybrid",
"rerank": true,
"similarityThreshold": 0,
"vectorWeight": 0
}'响应示例:
{
"total": 2,
"results": [
{
"$id": "chk_0042",
"knowledgeBaseId": "kb_product_docs",
"content": "早餐机首次使用前请用温水清洗内胆,并空烧一次完成除味。",
"sourceId": "doc_manual_v2",
"source": {
"documentId": "doc_manual_v2",
"uri": "/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/source"
},
"locator": {
"generation": "gen_3",
"chapter": 4,
"order": 12
},
"metadata": {
"page": 17
},
"imageContexts": [],
"score": 0.91
},
{
"$id": "chk_faq_007",
"knowledgeBaseId": "kb_faq",
"content": "早餐机整机保修 12 个月,加热元件保修 24 个月。",
"sourceId": "doc_faq_v1",
"source": {
"documentId": "doc_faq_v1",
"uri": "/v1/knowledgebases/kb_faq/documents/doc_faq_v1/source"
},
"locator": {
"generation": "gen_1",
"chapter": 2,
"order": 3
},
"metadata": {},
"imageContexts": [],
"score": 0.84
}
],
"reranked": false
}文档管理
GET /v1/knowledgebases/{knowledgeBaseId}/documents
SDK:KnowledgeBases.listDocuments · scope:knowledgebases.read
列出知识库内文档,可按 status/stage/enabled 过滤或用 queries 高级查询。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
versionId | query | string | 否 | 版本 ID;启用版本管理时省略则使用当前版本。 | |
status | query | string | 否 | 默认 "" | 按处理状态过滤:uploaded / processing / ready / failed。 |
stage | query | string | 否 | 默认 "" | 按处理阶段过滤。 |
enabled | query | boolean | 否 | 按启用状态过滤。 | |
documentTag | query | string | 否 | 按文档定位标签过滤;2.12.0 支持多个标签及按完整段匹配。 | |
subProductId | query | string | 否 | 按子产品编码精确过滤(2.10.0)。 | |
directoryPath | query | string | 否 | 按规范化目录及其后代过滤;非空时不可与 documentTag 或 subProductId 过滤同时使用。 | |
directoryUnclassified | query | boolean | 否 | 默认 false | 仅列无目录文档;为 true 时不可与 documentTag 或 subProductId 过滤同时使用。 |
queries | query | string[] | 否 | 默认 [] | Appbase Query 高级查询串数组,最多 100 条、单条 4096 字符。documentTag 或 subProductId 非空时服务端忽略 queries(包括过滤、排序和分页);status、stage、enabled 仍生效。 |
目录筛选边界:非空 directoryPath 与 directoryUnclassified=true 相互排斥;目录筛选不能与非空 documentTag 或 subProductId 同时使用。目录分页的 Query.limit 最大为 100,超过时返回 general_query_invalid。
输出:
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。 |
调用示例:
以下示例未指定 versionId;查询草稿时,在查询参数中指定草稿版本 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。 | |
versionId | body | string | 否 | 启用版本管理时写入须指定 DRAFT 版本 ID。 | |
bucketId | body | string | 否 | 源文件所在桶 ID;缺省用库默认桶。 | |
fileId | body | string | 是 | 已上传源文件的 Storage 文件 ID(必填)。 | |
name | body | string | 否 | 文档显示名,缺省用源文件名。 | |
source | body | string | 否 | 文档来源标记,默认 manual。 | |
externalItemId | body | string | 否 | 来自外部数据源时的条目 ID(同步去重用)。 | |
documentTag | body | string | 否 | 文档定位标签:2.12.0 支持自由格式及逗号分隔的多个非空标签;结构化定位值可省略末段,由服务端生成定位键。读取保存值后用于筛选。 | |
subProductId | body | string | 否 | 子产品编码(2.10.0,1–64 位字母/数字),存入 metadata.subProductId;同时提交非空 documentTag 并省略或清空本字段时,仅从第一个标签为有效结构化定位标识的非空子产品段派生;第一个标签为自由格式时不保证派生,即使后续标签是结构化值。召回过滤优先使用独立字段,缺省时可回退到第一个具有非空子产品段的可解析结构化标签的子产品段。 | |
sectionCode | body | string | 否 | 章节编码(2.10.0,1–64 位数字);documentTag 省略时嵌入自动生成的定位标识。 | |
parserId(或 chunkingStrategy) | body | string | 否 | 枚举:general / title / smart / regex / faq / sheet | 文档级分块策略覆盖(省略时继承知识库默认策略)。 |
parser | body | string | 否 | 枚举:text / mineru / vlm / office | 文档级解析引擎简写覆盖(等价于 parserConfig.documentParser)。 |
parserConfig | body | object | 否 | 文档级解析/分块与多模态配置覆盖(子字段见下)。 | |
parserConfig.chunkTokenNum | body | integer | 否 | 每个切片的 token 预算:general/smart 默认 512,title/regex 默认 256。 | |
parserConfig.overlapPercent | body | integer | 否 | 默认 10 | general/smart 切片器的 token 重叠百分比,默认 10。 |
parserConfig.delimiter | body | string | 否 | 超长 title/regex 切片的分隔符;默认 title 为 \n。;!?,regex 为 \n。.;;!!??。 | |
parserConfig.titleLevel | body | integer | 否 | 默认 3 | title 切片器使用的 Markdown 标题级别,默认 3。 |
parserConfig.minChunkTokens | body | integer | 否 | 默认 128 | smart 切片器最小切片大小,默认 128,不得超过 chunkTokenNum。 |
parserConfig.regexPattern | body | string | 否 | 默认 "[.!?]+\\s*" | regex 切片器使用的 PCRE 表达式,默认 [.!?]+\s*。 |
parserConfig.documentParser | body | string | 否 | 枚举:text / mineru / vlm / office | 文档解析引擎:text(纯文本)/ mineru(MinerU 复杂版面与表格解析)/ vlm(视觉大模型整页解析)/ office(Office 结构化提取)。 |
parserConfig.visionModel | body | string | 否 | documentParser=vlm 时使用的视觉模型(如 qwen-vl-max)。 | |
parserConfig.visionProviderRef | body | string | 否 | 视觉模型的钉定 provider 引用(如 project:dashscope-prod)。 | |
parserConfig.imageUnderstanding(或顶层 imageUnderstanding) | body | object | 否 | 多模态图片理解配置:enabled(boolean)、providerRef(string,如 "project:dashscope-prod")、model(string,如 "qwen-vl-max")、maxConcurrency(integer,默认 4)、prompt(string)、maxImagesPerDocument(默认 20)、maxDescriptionChars(默认 800)。 | |
metadata | body | object | 否 | 业务元数据。 |
登记后调用 POST .../ingestions(或 POST .../process)触发解析 → 切片 → Embedding 流水线。
输出:
201,返回模型 Models.KnowledgeBaseDocument(初始 status=uploaded)。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 文档 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 所属知识库 ID。 |
name* | string | 文档显示名。 |
bucketId* | string | 源文件所在 Storage 桶 ID。 |
fileId* | string | 源文件 Storage 文件 ID。 |
mimeType* | string | 源文件 MIME 类型。 |
source* | string | 来源:manual 手工上传,datasource:{id} 数据源同步,yuque:personal 个人语雀导入。 |
externalItemId* | string | 外部系统条目 ID,数据源同步据此去重更新。 |
parserId* | string | 文档级切片策略覆盖,空为继承库默认。 |
parserConfig* | object | 文档级解析/切片配置覆盖。 |
metadata* | object | 业务元数据。 |
status* | string | 处理状态:uploaded 已登记 / processing 处理中 / ready 就绪 / failed 失败。 |
enabled* | boolean | 是否参与检索;false 时切片保留但不进检索结果。 |
stage* | string | 当前/最近一次摄取的流水线阶段镜像。 |
activeIngestionId* | string | 当前或最近一次摄取任务 ID。 |
activeGeneration* | string | 检索可见代数(generation),仅 status=ready 时有效。 |
processingStartedAt* | string | 最近一次触发处理的时间。 |
chunksTotal* | integer | 预期切片总数(已知后填充)。 |
chunkCount* | integer | 活跃代数中的切片数。 |
error* | string | 最近一次处理错误信息,正常为空串。 |
lastExecutionId* | string | 已废弃的旧 Function 执行 ID。 |
调用示例:
以下示例未指定 versionId,适用于未启用版本管理的知识库;启用后须在请求体中指定 DRAFT 版本 ID。
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"fileId": "file_9a11cc",
"name": "产品使用手册 v2.pdf",
"source": "ops-console",
"parserId": "smart",
"parserConfig": {},
"metadata": {
"edition": "v2"
}
}'多解析器与分块/多模态图片理解高级调用示例(SIT 基准环境 kb_enterprise_support):
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/documents" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"bucketId": "kb_enterprise_docs",
"fileId": "file_ob_arch_v43",
"name": "OceanBase-V4.3-高可用架构白皮书.pdf",
"source": "manual",
"documentTag": "oceanbase_4301_8f9a2b3c4d5e6f708192a3b4c5d6e7f8",
"subProductId": "oceanbase",
"sectionCode": "4301",
"parser": "mineru",
"chunkingStrategy": "smart",
"parserId": "smart",
"parserConfig": {
"documentParser": "mineru",
"chunkTokenNum": 600,
"minChunkTokens": 150,
"overlapPercent": 15,
"imageUnderstanding": {
"enabled": true,
"providerRef": "project:dashscope-prod",
"model": "qwen-vl-max",
"maxConcurrency": 4,
"maxImagesPerDocument": 20,
"maxDescriptionChars": 800,
"prompt": "请提取架构图与故障排查流程图中的核心组件、数据流向与告警阈值,输出结构化文字说明。"
}
},
"imageUnderstanding": {
"enabled": true,
"providerRef": "project:dashscope-prod",
"model": "qwen-vl-max",
"maxConcurrency": 4,
"prompt": "请提取架构图与故障排查流程图中的核心组件、数据流向与告警阈值,输出结构化文字说明。"
},
"metadata": {
"department": "DBA支持中心",
"version": "4.3"
}
}'
)响应示例:
{
"$id": "doc_manual_v2",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"name": "产品使用手册 v2.pdf",
"bucketId": "bkt_kb_docs",
"fileId": "file_9a11cc",
"mimeType": "application/pdf",
"source": "manual",
"externalItemId": "",
"parserId": "",
"parserConfig": {},
"metadata": {
"edition": "v2"
},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3301",
"activeGeneration": "gen_3",
"processingStartedAt": "2026-09-01T08:00:01.000+00:00",
"chunksTotal": 86,
"chunkCount": 86,
"error": "",
"lastExecutionId": ""
}DELETE /v1/knowledgebases/{knowledgeBaseId}/documents
SDK: KnowledgeBases.deleteDocuments · scope: knowledgebases.write
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 |
documentIds | body | string[] | 是 | 需要删除的 1–50 个文档 ID。 |
versionId | body | string | 版本化启用时必填 | 指定 DRAFT 版本。 |
预检通过后删除,成功返回 204;删除前请确认目标,版本化启用时不能省略草稿版本 ID。
POST /v1/knowledgebases/{knowledgeBaseId}/documents/batch
SDK:KnowledgeBases.createDocumentsBatch · scope:knowledgebases.write
批量登记文档(1–50 个文件,先整体校验再创建)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 目标知识库 ID。 | |
versionId | body | string | 否 | 启用版本管理时写入须指定 DRAFT 版本 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。 |
调用示例:
以下示例未指定 versionId,适用于未启用版本管理的知识库;启用后须在请求体中指定 DRAFT 版本 ID。
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/batch" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"fileIds": [
"file_9a11cc",
"file_9a12dd"
],
"source": "manual",
"parserId": "smart",
"parserConfig": {},
"metadata": {
"topic": "早餐店经营"
}
}'响应示例:
{
"total": 2,
"documents": [
{
"$id": "doc_manual_v2",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-01T08:00:31.000+00:00",
"kbId": "kb_product_docs",
"name": "产品使用手册 v2.pdf",
"bucketId": "bkt_kb_docs",
"fileId": "file_9a11cc",
"mimeType": "application/pdf",
"source": "manual",
"externalItemId": "",
"parserId": "",
"parserConfig": {},
"metadata": {
"edition": "v2"
},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3301",
"activeGeneration": "gen_3",
"processingStartedAt": "2026-09-01T08:00:01.000+00:00",
"chunksTotal": 86,
"chunkCount": 86,
"error": "",
"lastExecutionId": ""
},
{
"$id": "doc_faq_v1",
"$createdAt": "2026-09-02T09:00:00.000+00:00",
"$updatedAt": "2026-09-02T09:00:40.000+00:00",
"kbId": "kb_product_docs",
"name": "售后 FAQ.docx",
"bucketId": "bkt_kb_docs",
"fileId": "file_9b22aa",
"mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"source": "manual",
"externalItemId": "",
"parserId": "faq",
"parserConfig": {},
"metadata": {},
"status": "ready",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3312",
"activeGeneration": "gen_1",
"processingStartedAt": "2026-09-02T09:00:05.000+00:00",
"chunksTotal": 21,
"chunkCount": 21,
"error": "",
"lastExecutionId": ""
}
]
}GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/content
scope:knowledgebases.read。SDK 方法是否可用以已发布版本为准。
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 |
documentId | path | string | 是 | 文档 ID。 |
versionId | query | string | 否 | 知识库版本 ID;版本管理启用时省略则使用当前版本。 |
成功返回 200 和文档内容对象,包括 content、chunksTotal、truncated 与 generation;当 truncated 为真时,内容并非完整文档。此接口与解析产物接口不同。
GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}
SDK:KnowledgeBases.getDocument · scope:knowledgebases.read
按 ID 获取文档(含处理状态、代数与切片计数)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
versionId | query | 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。 |
调用示例:
以下示例未指定 versionId;查询草稿时,在查询参数中指定草稿版本 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。 | |
versionId | body | string | 否 | 启用版本管理时写入须指定 DRAFT 版本 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 | |
name | body | string | 否 | 文档显示名。 | |
parserId | body | string | 否 | 枚举:general / title / smart / regex / faq / (空,表示不限) | 文档级切片策略覆盖;传空串清除覆盖、回退库默认。 |
parserConfig | body | object | 否 | 文档级解析/切片配置覆盖(子字段见下)。 | |
parserConfig.chunkTokenNum | body | integer | 否 | 每个切片的 token 预算:general/smart 默认 512,title/regex 默认 256。 | |
parserConfig.overlapPercent | body | integer | 否 | 默认 10 | general 切片器的 token 重叠百分比,默认 10。 |
parserConfig.delimiter | body | string | 否 | 超长 title/regex 切片的分隔符;默认 title 为 \n。;!?,regex 为 \n。.;;!!??。 | |
parserConfig.titleLevel | body | integer | 否 | 默认 3 | title 切片器使用的 Markdown 标题级别,默认 3。 |
parserConfig.minChunkTokens | body | integer | 否 | 默认 128 | smart 切片器最小切片大小,默认 128,不得超过 chunkTokenNum。 |
parserConfig.regexPattern | body | string | 否 | 默认 "[.!?]+\\s*" | regex 切片器使用的 PCRE 表达式,默认 [.!?]+\s*。 |
parserConfig.documentParser | body | string | 否 | 枚举:text / vlm / mineru | 文档解析器:text(纯文本)/ vlm(视觉模型)/ mineru;MinerU 部署与凭证不属于本 API。 |
parserConfig.visionModel | body | string | 否 | documentParser=vlm 时使用的视觉模型。 | |
parserConfig.visionProviderRef | body | string | 否 | 视觉模型的钉定 provider 引用。 | |
parserConfig.imageUnderstanding | body | object | 否 | 图片解读配置(动态对象):enabled=true 时 model 与 providerRef 必填;另含 prompt、maxImagesPerDocument(默认 20)、maxDescriptionChars(默认 800)、maxConcurrency(默认 4)。 | |
metadata | body | object | 否 | 业务元数据。 | |
documentTag | body | string | 否 | 更新文档定位标识(2.10.0,格式同创建);空字符串清除。 | |
subProductId | body | string | 否 | 更新子产品编码(2.10.0);同时提交非空 documentTag 并省略或清空本字段时,仅从第一个标签为有效结构化定位标识的非空子产品段派生;第一个标签为自由格式时不保证派生,即使后续标签是结构化值。未同时提交非空标签时,空字符串删除独立字段,但有效过滤值仍会回退到已有标签中第一个具有非空子产品段的可解析结构化标签的子产品段;要移除二者须同时清空两个字段。 | |
enabled | body | boolean | 否 | 置 false 后文档切片保留但不参与检索结果。 | |
status | body | string | 否 | 处理状态(仅 API Key 可改的遗留修正字段)。 | |
stage | body | string | 否 | 处理阶段(仅 API Key 可改的遗留修正字段)。 | |
chunksTotal | body | integer | 否 | 切片总数(仅 API Key 可改的遗留修正字段)。 | |
chunkCount | body | integer | 否 | 切片数(仅 API Key 可改的遗留修正字段)。 | |
error | body | string | 否 | 错误信息(仅 API Key 可改的遗留修正字段)。 |
输出:
200,返回模型 Models.KnowledgeBaseDocument。存在排队/运行/取消中的摄取时不可改 parserId/parserConfig。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 文档 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 所属知识库 ID。 |
name* | string | 文档显示名。 |
bucketId* | string | 源文件所在 Storage 桶 ID。 |
fileId* | string | 源文件 Storage 文件 ID。 |
mimeType* | string | 源文件 MIME 类型。 |
source* | string | 来源:manual 手工上传,datasource:{id} 数据源同步,yuque:personal 个人语雀导入。 |
externalItemId* | string | 外部系统条目 ID,数据源同步据此去重更新。 |
parserId* | string | 文档级切片策略覆盖,空为继承库默认。 |
parserConfig* | object | 文档级解析/切片配置覆盖。 |
metadata* | object | 业务元数据。 |
status* | string | 处理状态:uploaded 已登记 / processing 处理中 / ready 就绪 / failed 失败。 |
enabled* | boolean | 是否参与检索;false 时切片保留但不进检索结果。 |
stage* | string | 当前/最近一次摄取的流水线阶段镜像。 |
activeIngestionId* | string | 当前或最近一次摄取任务 ID。 |
activeGeneration* | string | 检索可见代数(generation),仅 status=ready 时有效。 |
processingStartedAt* | string | 最近一次触发处理的时间。 |
chunksTotal* | integer | 预期切片总数(已知后填充)。 |
chunkCount* | integer | 活跃代数中的切片数。 |
error* | string | 最近一次处理错误信息,正常为空串。 |
lastExecutionId* | string | 已废弃的旧 Function 执行 ID。 |
调用示例:
以下示例未指定 versionId,适用于未启用版本管理的知识库;启用后须在请求体中指定 DRAFT 版本 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。 | |
versionId | body | string | 否 | 启用版本管理时写入须指定 DRAFT 版本 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 |
输出:
204,无响应体。
调用示例:
以下示例未指定 versionId,适用于未启用版本管理的知识库;启用后须在请求体中指定 DRAFT 版本 ID。
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。 | |
versionId | body | string | 否 | 启用版本管理时写入须指定 DRAFT 版本 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(父文档)。 |
调用示例:
以下示例未指定 versionId,适用于未启用版本管理的知识库;启用后须在请求体中指定 DRAFT 版本 ID。
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。 | |
versionId | query | string | 否 | 可选;启用版本管理时省略则读取当前版本,查询草稿请指定草稿版本 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 |
用 -o 保存文件,不要按 JSON 解析。
输出:
200,File 二进制内容(Content-Type 为源文件 MIME),供归档或人工核对。
调用示例:
以下示例未指定 versionId;查询草稿时,在查询参数中指定草稿版本 ID。
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)
标签匹配边界:2.12.0 按下划线分段做前缀匹配,自由格式同样适用:finance 可命中 finance_confidential_notes。___ 的尾部空段移除后可能匹配有标签的文档,应避免使用全下划线过滤值。此筛选不能替代权限控制。读取有效 subProductId 时会跳过自由格式和子产品段为空的标签,例如 _12_<fileKey> 后的 ob_12_<fileKey> 可提供 ob;显式字段优先。
读取文档解析产物
两项 REST 接口均要求 knowledgebases.read;SDK 方法是否可用以已发布制品为准。解析产物是切片前的 Markdown,并非切片列表。
查询产物状态
GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 知识库 ID。 |
documentId | path | string | 是 | 文档 ID。 |
versionId | query | string | 否 | 指定知识库版本;版本管理启用时省略则使用当前版本。 |
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -sS "${APPBASE_ENDPOINT:?Set endpoint including /v1}/knowledgebases/${KB_ID:?Set KB_ID}/documents/${DOCUMENT_ID:?Set DOCUMENT_ID}/parse-artifact" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID:?Set project ID}"
)成功返回 200,示例(byteSize 和 sha256 为示意值):
{
"knowledgeBaseId": "kb_example",
"documentId": "doc_example",
"status": "ready",
"supported": true,
"generation": "gen_1",
"byteSize": 36,
"sha256": "81968d11f4746b211ad5eed0cb1a6e732a2da734b2ff2a6754ce52c31149d45e"
}status 可为 not_generated、ready 或 too_large;产物不属于当前活跃代数时返回 not_generated。当前版本对成功读取的文档固定返回 supported: true,不能据此判断该文档或解析器是否已生成产物;请根据 status、当前代数和内容接口判断产物是否可用。generation、byteSize 和 sha256 在不可用时可为 null。
读取产物内容
GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact/content 使用上述相同的路径参数及可选查询参数 versionId。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" | curl --disable --header @- -sS "${APPBASE_ENDPOINT:?Set endpoint including /v1}/knowledgebases/${KB_ID:?Set KB_ID}/documents/${DOCUMENT_ID:?Set DOCUMENT_ID}/parse-artifact/content" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID:?Set project ID}"
)200 返回 text/markdown; charset=utf-8 文本。调用内容接口前先检查状态:
| HTTP 状态 | 错误类型 | 含义 |
|---|---|---|
400 | general_argument_invalid | 产物过大,无法保存。 |
404 | storage_file_not_found | 产物未生成或已不属于当前活跃代数;按需重新摄取后再查。 |
知识库、文档、版本不存在或权限不足还可能返回相应错误;请结合实际错误类型排查。
GET /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks
SDK:KnowledgeBases.listChunks · scope:knowledgebases.read
列出文档当前活跃代数的切片,支持内容关键词搜索与高级查询。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
versionId | query | 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 | 切片元数据,内部溯源字段被剔除。 |
调用示例:
以下示例未指定 versionId;查询草稿时,在查询参数中指定草稿版本 ID。
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。 | |
versionId | body | string | 否 | 启用版本管理时写入须指定 DRAFT 版本 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 | 切片元数据,内部溯源字段被剔除。 |
调用示例:
以下示例未指定 versionId,适用于未启用版本管理的知识库;启用后须在请求体中指定 DRAFT 版本 ID。
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。 | |
versionId | query | 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 | 切片元数据,内部溯源字段被剔除。 |
调用示例:
以下示例未指定 versionId;查询草稿时,在查询参数中指定草稿版本 ID。
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)会重算向量。禁用切片后,它不会出现在知识库检索结果中,且文档发布不会自动重新启用它。重新启用后,仍需文档启用、摄取代数及版本发布状态允许,切片才能再次参与检索。以下是 REST 接口能力;所用 SDK 是否支持 enabled 参数以对应版本为准。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 | |
chunkId | path | string | 是 | 目标切片 ID。 | |
content | body | string | 否 | 新正文;传入即触发向量重算(连同已持久化的图片描述)。 | |
metadata | body | object | 否 | 切片元数据;仅当图片描述变化时才重算向量。 | |
enabled | body | boolean | 否 | 是否允许切片参与检索;省略则不改变当前值。 | |
versionId | body | string | 否 | 版本管理启用时写入需指定 DRAFT 版本 ID。 |
输出:
200,返回模型 Models.KnowledgeBaseChunk。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 切片 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
documentId* | string | 所属文档 ID。 |
content* | string | 切片正文。 |
ingestVersion* | string | 切片所属的摄取代数。 |
enabled | boolean | 是否允许切片参与检索。 |
source* | object | 权威来源文档描述与受保护的源 URI(动态对象)。 |
locator* | object | 版本化的章节与原文定位器(动态对象)。 |
metadata* | object | 切片元数据,内部溯源字段被剔除。 |
调用示例:
以下示例未指定 versionId,适用于未启用版本管理的知识库;启用后须在请求体中指定 DRAFT 版本 ID。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X PATCH "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/documents/doc_manual_v2/chunks/chk_0042" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"content": "Warranty lasts 24 months from purchase.",
"enabled": false,
"metadata": {
"topic": "warranty"
}
}'
)响应示例:
{
"$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": "Warranty lasts 24 months from purchase.",
"enabled": false,
"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": {
"topic": "warranty"
}
}DELETE /v1/knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}
SDK:KnowledgeBases.deleteChunk · scope:knowledgebases.write
删除单个切片,父文档 chunkCount/chunksTotal 相应递减。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
versionId | body | string | 否 | 启用版本管理时写入须指定 DRAFT 版本 ID。 | |
documentId | path | string | 是 | 目标文档 ID。 | |
chunkId | path | string | 是 | 目标切片 ID。 |
输出:
204,无响应体。
调用示例:
以下示例未指定 versionId,适用于未启用版本管理的知识库;启用后须在请求体中指定 DRAFT 版本 ID。
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。 | |
versionId | query | 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(父文档)。 |
调用示例:
以下示例未指定 versionId;查询草稿时,在查询参数中指定草稿版本 ID。
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。 | |
versionId | body | string | 否 | 启用版本管理时写入须指定 DRAFT 版本 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(父文档)。 |
调用示例:
以下示例未指定 versionId,适用于未启用版本管理的知识库;启用后须在请求体中指定 DRAFT 版本 ID。
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。 | |
versionId | query | 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(父文档)。 |
调用示例:
以下示例未指定 versionId;查询草稿时,在查询参数中指定草稿版本 ID。
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。 | |
versionId | body | string | 否 | 启用版本管理时写入须指定 DRAFT 版本 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(父文档)。 |
调用示例:
以下示例未指定 versionId,适用于未启用版本管理的知识库;启用后须在请求体中指定 DRAFT 版本 ID。
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。 | |
versionId | query | string | 否 | 可选;启用版本管理时省略则读取当前就绪版本。 | |
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": "team-docs",
"config": {
"teamId": "acme",
"repoNamespaces": [
"acme/manuals"
],
"syncSchedule": "0 2 * * *"
},
"credentials": {"teamToken": "********"},
"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。 | |
versionId | body | string | 否 | 启用版本管理时必填,填写草稿版本 ID;版本化数据源不支持定时同步。 | |
name | body | string | 是 | 数据源名称。 | |
type | body | string | 否 | 枚举:yuque | 数据源类型;当前枚举仅 yuque。 |
config | body | object | 否 | 语雀要求非空 teamId;可设置 repoNamespaces 和 syncSchedule cron。版本化数据源不能设置同步计划。 | |
credentials | body | object | 否 | 语雀要求非空 teamToken;落库加密,响应不回显密文。 | |
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 | 最近一次数据源错误信息。 |
调用示例:
请先在 Bash 中安全设置 APPBASE_API_KEY 和 YUQUE_TEAM_TOKEN;本示例需要 Python 3。请按实际环境替换地址、项目 ID 和团队信息。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" "${YUQUE_TEAM_TOKEN:?Set YUQUE_TEAM_TOKEN}"
export YUQUE_TEAM_TOKEN
python3 -c "import json, os, sys; json.dump({'name':'team-docs','type':'yuque','config':{'teamId':'acme','repoNamespaces':['acme/manuals'],'syncSchedule':'0 2 * * *'},'credentials':{'teamToken':os.environ['YUQUE_TEAM_TOKEN']},'status':'active','triggerSync':True}, sys.stdout)" |
curl --disable --fail --silent --show-error -i -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @/dev/fd/3 \
-H "Content-Type: application/json" --data-binary @- \
3< <(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY")
)创建响应不等待同步完成;如触发同步,请查看同步记录及文档摄取状态。
响应示例:
{
"$id": "ds_yuque_team",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-01T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"type": "yuque",
"name": "team-docs",
"config": {
"teamId": "acme",
"repoNamespaces": [
"acme/manuals"
],
"syncSchedule": "0 2 * * *"
},
"credentials": {"teamToken": "********"},
"status": "active",
"lastSyncAt": null,
"lastSyncStatus": null,
"lastCursor": null,
"error": null
}GET /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}
SDK:KnowledgeBases.getDataSource · scope:knowledgebases.read
按 ID 获取数据源(凭证不回显)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
versionId | query | string | 否 | 可选;启用版本管理时省略则读取当前就绪版本。 | |
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": "team-docs",
"config": {
"teamId": "acme",
"repoNamespaces": [
"acme/manuals"
],
"syncSchedule": "0 2 * * *"
},
"credentials": {"teamToken": "********"},
"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。 | |
versionId | body | string | 否 | 启用版本管理时必填,填写草稿版本 ID;版本化数据源不支持定时同步。 | |
name | body | string | 否 | 数据源名称。 | |
config | body | object | 否 | 提供时按完整配置校验并替换,语雀配置须包含非空 teamId。 | |
credentials | body | object | 否 | 提供时须包含非空 teamToken;不更新凭证时省略此字段。 | |
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 | 最近一次数据源错误信息。 |
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X PATCH "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"config": {
"teamId": "acme",
"repoNamespaces": [
"acme/manuals",
"acme/faq"
],
"syncSchedule": "0 */6 * * *"
},
"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": "team-docs",
"config": {
"teamId": "acme",
"repoNamespaces": [
"acme/manuals",
"acme/faq"
],
"syncSchedule": "0 */6 * * *"
},
"credentials": {"teamToken": "********"},
"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。 | |
versionId | body | 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。
调用示例:
请先在 Bash 中安全设置 APPBASE_API_KEY 和 YUQUE_TEAM_TOKEN;本示例需要 Python 3。请按实际环境替换地址、项目 ID 和团队信息。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" "${YUQUE_TEAM_TOKEN:?Set YUQUE_TEAM_TOKEN}"
export YUQUE_TEAM_TOKEN
python3 -c "import json, os, sys; json.dump({'teamId':'acme','teamToken':os.environ['YUQUE_TEAM_TOKEN']}, sys.stdout)" |
curl --disable --fail --silent --show-error -i -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/yuque/repos" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @/dev/fd/3 \
-H "Content-Type: application/json" --data-binary @- \
3< <(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY")
)响应示例:
{
"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/标题等),供批量导入选择。
调用示例:
请先在 Bash 中安全设置 APPBASE_API_KEY 和 YUQUE_TEAM_TOKEN;本示例需要 Python 3。请按实际环境替换地址、项目 ID 和团队信息。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}" "${YUQUE_TEAM_TOKEN:?Set YUQUE_TEAM_TOKEN}"
export YUQUE_TEAM_TOKEN
python3 -c "import json, os, sys; json.dump({'teamId':'acme','teamToken':os.environ['YUQUE_TEAM_TOKEN'],'repoNamespaces':['acme/manuals']}, sys.stdout)" |
curl --disable --fail --silent --show-error -i -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/yuque/docs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @/dev/fd/3 \
-H "Content-Type: application/json" --data-binary @- \
3< <(builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY")
)响应示例:
{
"docs": [
{
"namespace": "acme/manuals",
"title": "早餐机快速上手",
"url": "<YUQUE_DOCUMENT_URL_1>"
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/documents
SDK:KnowledgeBases.createDataSourceDocument · scope:knowledgebases.write
从数据源按 URL 导入单篇文档:URL 仅用于定位,服务端不直接抓取该 URL。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
versionId | body | string | 否 | 启用版本管理时必填,填写要写入的草稿版本 ID。 | |
dataSourceId | path | string | 是 | 目标数据源 ID。 | |
url | body | string | 是 | 语雀文档 URL;仅接受受支持语雀 HTTPS 域名与精确 {group}/{book}/{slug} 路径。 | |
idempotencyKey | body | string | 否 | 幂等键。 |
输出:
202 新建/有更新(入队摄取)或 200 内容未变(文档已 processing/ready),返回模型 Models.KnowledgeBaseDocument。409 与活跃摄取冲突;503 语雀暂不可用。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 文档 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
kbId* | string | 所属知识库 ID。 |
name* | string | 文档显示名。 |
bucketId* | string | 源文件所在 Storage 桶 ID。 |
fileId* | string | 源文件 Storage 文件 ID。 |
mimeType* | string | 源文件 MIME 类型。 |
source* | string | 来源:manual 手工上传,datasource:{id} 数据源同步,yuque:personal 个人语雀导入。 |
externalItemId* | string | 外部系统条目 ID,数据源同步据此去重更新。 |
parserId* | string | 文档级切片策略覆盖,空为继承库默认。 |
parserConfig* | object | 文档级解析/切片配置覆盖。 |
metadata* | object | 业务元数据。 |
status* | string | 处理状态:uploaded 已登记 / processing 处理中 / ready 就绪 / failed 失败。 |
enabled* | boolean | 是否参与检索;false 时切片保留但不进检索结果。 |
stage* | string | 当前/最近一次摄取的流水线阶段镜像。 |
activeIngestionId* | string | 当前或最近一次摄取任务 ID。 |
activeGeneration* | string | 检索可见代数(generation),仅 status=ready 时有效。 |
processingStartedAt* | string | 最近一次触发处理的时间。 |
chunksTotal* | integer | 预期切片总数(已知后填充)。 |
chunkCount* | integer | 活跃代数中的切片数。 |
error* | string | 最近一次处理错误信息,正常为空串。 |
lastExecutionId* | string | 已废弃的旧 Function 执行 ID。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"url": "<YUQUE_DOCUMENT_URL_1>",
"idempotencyKey": "idem-ds-01"
}'响应示例:
{
"$id": "doc_manual_v2",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"kbId": "kb_product_docs",
"name": "产品使用手册 v2.pdf",
"bucketId": "bkt_kb_docs",
"fileId": "file_9a11cc",
"mimeType": "application/pdf",
"source": "datasource:ds_yuque_team",
"externalItemId": "acme/manuals/breakfast-quickstart",
"parserId": "",
"parserConfig": {},
"metadata": {
"edition": "v2"
},
"status": "processing",
"enabled": true,
"stage": "",
"activeIngestionId": "ing_3301",
"activeGeneration": "gen_3",
"processingStartedAt": "2026-09-01T08:00:01.000+00:00",
"chunksTotal": 86,
"chunkCount": 86,
"error": "",
"lastExecutionId": ""
}POST /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/documents/batch
SDK:KnowledgeBases.createDataSourceDocumentsBatch · scope:knowledgebases.write
从数据源批量按 URL 导入文档(最多 20 条,逐项返回结果)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
versionId | body | string | 否 | 启用版本管理时必填,填写要写入的草稿版本 ID。 | |
dataSourceId | path | string | 是 | 目标数据源 ID。 | |
urls | body | string[] | 是 | 语雀文档 URL 数组,最多 20 条、不重复。 | |
idempotencyKey | body | string | 否 | 批量幂等键前缀。 |
输出:
200 全部 accepted/unchanged,207 存在 failed;返回模型 Models.KnowledgeBaseDataSourceDocumentImportBatch(results[] 与请求顺序一致,需逐项检查)。空列表/超 20 条/重复 URL/数据源非 active 返回 400。
| 字段 | 类型 | 说明 |
|---|---|---|
total* | integer | 本次处理的 URL 条数。 |
accepted* | integer | 新建/更新文档并入队摄取的 URL 数。 |
unchanged* | integer | 远端内容已处于 processing/ready 而未动的 URL 数。 |
failed* | integer | 校验或导入失败的 URL 数。 |
results* | object[] | 按请求顺序排列的逐 URL 结果。 |
url* | string | 请求的语雀文档地址。 |
status* | string | 每个地址的导入结果:accepted、unchanged 或 failed。 |
document | object | 成功或未变更时返回的知识库文档。 |
error | string | 失败时的错误详情。 |
errorType | string | 失败时可供程序识别的异常类型。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/documents/batch" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"<YUQUE_DOCUMENT_URL_1>",
"<YUQUE_DOCUMENT_URL_2>"
],
"idempotencyKey": "idem-ds-batch-01"
}'响应示例:
{
"total": 2,
"accepted": 0,
"unchanged": 0,
"failed": 0,
"results": [
{
"url": "",
"status": "available",
"document": {},
"error": "",
"errorType": ""
},
{
"url": "",
"status": "available",
"document": {},
"error": "",
"errorType": ""
}
]
}GET /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/syncs
SDK:KnowledgeBases.listDataSourceSyncs · scope:knowledgebases.read
列出数据源同步记录(按创建时间倒序),可按 status 过滤。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
versionId | query | string | 否 | 可选;启用版本管理时省略则读取当前就绪版本。 | |
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 | 同步统计:created、updated、skipped、disabled、failed。 |
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": 1,
"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": {
"created": 1,
"updated": 2,
"skipped": 36,
"disabled": 0,
"failed": 0
},
"error": "",
"startedAt": "2026-09-14T02:00:01.000+00:00",
"finishedAt": "2026-09-14T02:01:12.000+00:00"
}
]
}POST /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/syncs
SDK:KnowledgeBases.createDataSourceSync · scope:knowledgebases.write
触发一次数据源同步;已有 queued/running 同步时返回既有记录,不重复排队。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
dataSourceId | path | string | 是 | 目标数据源 ID。 | |
versionId | body | string | 否 | 启用版本管理时必填,填写要写入的草稿版本 ID。 |
输出:
202,返回模型 Models.KnowledgeBaseDataSourceSync。异步任务:轮询 GET .../syncs/{syncId} 至 ready/failed。
| 字段 | 类型 | 说明 |
|---|---|---|
$id* | string | 同步记录 ID。 |
$createdAt* | string | 创建时间(ISO 8601)。 |
$updatedAt* | string | 最近更新时间(ISO 8601)。 |
datasourceId* | string | 数据源 ID。 |
kbId* | string | 知识库 ID。 |
status* | string | 同步状态:queued / running / ready / failed。 |
cursorStart* | string | 同步起始游标。 |
cursorEnd* | string | 同步产出的新游标。 |
stats* | object | 同步统计:created、updated、skipped、disabled、failed。 |
error* | string | failed 时的错误信息。 |
startedAt* | string | worker 开始处理时间。 |
finishedAt* | string | 同步结束时间。 |
调用示例:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/syncs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"启用版本管理时,在请求正文中传入实际草稿 ID:
curl -X POST "https://<your-endpoint>/v1/knowledgebases/kb_product_docs/datasources/ds_yuque_team/syncs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" -d '{"versionId":"<DRAFT_VERSION_ID>"}'响应示例:
{
"$id": "sync_771f",
"$createdAt": "2026-09-01T08:00:00.000+00:00",
"$updatedAt": "2026-09-14T08:00:00.000+00:00",
"datasourceId": "ds_yuque_team",
"kbId": "kb_product_docs",
"status": "queued",
"cursorStart": "yq-2026-09-13T02:00:00Z",
"cursorEnd": null,
"stats": {
"created": 0,
"updated": 0,
"skipped": 0,
"disabled": 0,
"failed": 0
},
"error": null,
"startedAt": null,
"finishedAt": null
}GET /v1/knowledgebases/{knowledgeBaseId}/datasources/{dataSourceId}/syncs/{syncId}
SDK:KnowledgeBases.getDataSourceSync · scope:knowledgebases.read
查询单次同步的状态、游标推进与统计。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | 所属知识库 ID。 | |
versionId | query | string | 否 | 可选;启用版本管理时省略则读取当前就绪版本。 | |
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 | 同步统计:created、updated、skipped、disabled、failed。 |
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": {
"created": 1,
"updated": 2,
"skipped": 36,
"disabled": 0,
"failed": 0
},
"error": "",
"startedAt": "2026-09-14T02:00:01.000+00:00",
"finishedAt": "2026-09-14T02:01:12.000+00:00"
}词库(Lexicons)与绑定管理
GET /v1/lexicons
SDK:Lexicons.list · scope:lexicons.read
分页列出当前项目下可见的全部词库。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
limit | query | integer | 否 | 默认 25 | 单页返回数量,范围 1–100。 |
offset | query | integer | 否 | 默认 0 | 分页偏移量,范围 0–1000000。 |
输出:200 OK,返回 lexiconList 模型(total + lexicons[])。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X GET "<APPBASE_ENDPOINT_WITH_V1>/lexicons?limit=25&offset=0" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @-
)响应示例:
{
"total": 2,
"lexicons": [
{
"$id": "lex_enterprise_synonyms",
"$createdAt": "2026-10-21T08:00:00.000+00:00",
"$updatedAt": "2026-10-22T03:15:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"name": "企业智能客服同义词与扩展词典",
"description": "统一 OceanBase、AI 网关与智能客服业务术语标准表达",
"tokenizerProfile": "unicode-v1",
"revision": 4
},
{
"$id": "lex_support_stopwords",
"$createdAt": "2026-10-21T08:10:00.000+00:00",
"$updatedAt": "2026-10-21T09:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"name": "客服检索与对话停用词词典",
"description": "过滤口语冗余词与违规阻断词",
"tokenizerProfile": "unicode-v1",
"revision": 2
}
]
}POST /v1/lexicons
SDK:Lexicons.create · scope:lexicons.write
在项目内创建新词库。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
lexiconId | body | string | 否 | 默认 "unique()" | 自定义词库 ID(如 lex_enterprise_synonyms)或传 "unique()"。 |
name | body | string | 是 | — | 词库名称,长度 1–128 字符。 |
description | body | string | 否 | 默认 "" | 词库用途说明,最长 4096 字符。 |
permissions | body | string[] | 否 | 默认 null | 资源级权限数组(仅允许 read、update、delete 动作)。 |
输出:201 Created,返回 lexicon 模型。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/lexicons" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"lexiconId": "lex_enterprise_synonyms",
"name": "企业智能客服同义词与扩展词典",
"description": "统一 OceanBase、AI 网关与智能客服业务术语标准表达"
}'
)GET /v1/lexicons/{lexiconId}、PATCH /v1/lexicons/{lexiconId}、DELETE /v1/lexicons/{lexiconId}
SDK:Lexicons.get / Lexicons.update / Lexicons.delete · scope:lexicons.read / lexicons.write
| 方法 + 路径 | 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|---|
GET /v1/lexicons/{lexiconId} | lexiconId | path | string | 是 | 按 ID 获取词库详情(含当前 revision 与 tokenizerProfile)。 |
PATCH /v1/lexicons/{lexiconId} | lexiconId | path | string | 是 | 目标词库 ID。 |
PATCH /v1/lexicons/{lexiconId} | name | body | string | 否 | 更新后的词库名称(1–128 字符)。 |
PATCH /v1/lexicons/{lexiconId} | description | body | string | 否 | 更新后的词库说明(最长 4096 字符)。 |
PATCH /v1/lexicons/{lexiconId} | permissions | body | string[] | 否 | 资源级权限数组(更新后原子递增 revision)。 |
DELETE /v1/lexicons/{lexiconId} | lexiconId | path | string | 是 | 删除词库及其全部词条(返回 204);若仍绑定在任何知识库或智能体上,返回 409 general_conflict。 |
调用示例:
将 APPBASE_ENDPOINT 设置为目标环境的 API 地址(包含 /v1),并确认项目与凭据属于该环境。
获取词库详情
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X GET "${APPBASE_ENDPOINT}/lexicons/lex_enterprise_synonyms" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @-
)更新词库名称与描述
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X PATCH "${APPBASE_ENDPOINT}/lexicons/lex_enterprise_synonyms" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"name": "企业智能客服同义词与扩展词典(v2)",
"description": "覆盖 OceanBase V4.3、LLM Gateway 与智能体专有术语"
}'
)删除已解绑词库。仅在确认目标与影响后单独执行。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X DELETE "${APPBASE_ENDPOINT}/lexicons/lex_temp_test" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
--header @-
)GET /v1/lexicons/{lexiconId}/entries 与 POST /v1/lexicons/{lexiconId}/entries
SDK:Lexicons.listEntries / Lexicons.createEntry · scope:lexicons.read / lexicons.write
管理词库内的结构化词条規則。
创建词条(POST /v1/lexicons/{lexiconId}/entries)输入参数:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
lexiconId | path | string | 是 | — | 目标词库 ID。 |
entryId | body | string | 否 | 默认 "unique()" | 词条 ID。 |
entryType | body | string | 是 | 枚举 synonym, expansion, stop | 规则类型:synonym(双向等价同义词)、expansion(单向下位扩展词)、stop(停用词/拦截词)。 |
terms | body | string[] | 是 | — | 触发词项数组(1–100 项,单项 1–256 字符);synonym 时首项为标准词(Canonical Term)。 |
expansions | body | string[] | 否 | 默认 [] | 仅当 entryType="expansion" 时必填,填写展开后的目标词数组。 |
position | body | integer | 否 | 默认 0 | 规则匹配排序优先级(0–2147483647,越小越优先)。 |
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/lexicons/lex_enterprise_synonyms/entries" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"entryId": "unique()",
"entryType": "synonym",
"terms": ["OceanBase", "OB数据库", "蚂蚁分布式数据库"],
"expansions": [],
"position": 10
}'
)响应示例(201 Created):
{
"$id": "ent_ob_syn_01",
"$createdAt": "2026-10-22T03:15:00.000+00:00",
"$updatedAt": "2026-10-22T03:15:00.000+00:00",
"lexiconId": "lex_enterprise_synonyms",
"entryType": "synonym",
"terms": ["OceanBase", "OB数据库", "蚂蚁分布式数据库"],
"expansions": [],
"position": 10
}POST /v1/lexicons/{lexiconId}/preview、POST /v1/lexicons/{lexiconId}/import、GET /v1/lexicons/{lexiconId}/export、GET /v1/lexicons/{lexiconId}/references
SDK:Lexicons.preview / Lexicons.import / Lexicons.export / Lexicons.listReferences · scope:lexicons.read / lexicons.write
| 端点 | 核心参数 | 返回模型 / 格式 | 说明 |
|---|---|---|---|
POST /v1/lexicons/{lexiconId}/preview | query(body, string, 必填) | Models.LexiconRewrite | 预览单句查询经该词库改写后的归一化文本、同义词替换、扩展词展开与停用词命中详情。 |
POST /v1/lexicons/{lexiconId}/import | format(json/csv/xlsx)、mode(merge/overwrite)、dryRun(boolean,默认 true)、content / entries | Models.LexiconImportResult | 批量导入词条(先以 dryRun: true 校验去重与 1,000 条配额,再传 dryRun: false 正式落库并递增 revision)。 |
GET /v1/lexicons/{lexiconId}/export | format(query: json/csv/xlsx) | 文件流 / JSON | 导出指定词库的全部词条规则。 |
GET /v1/lexicons/{lexiconId}/references | lexiconId(path, string, 必填) | Models.LexiconReferenceList | 查询当前绑定了该词库的 knowledgebases 与 agents 资源引用清单。 |
调用示例(改写预览 POST /v1/lexicons/{lexiconId}/preview):
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/lexicons/lex_enterprise_synonyms/preview" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"query": "请问OB数据库向量索引报错怎么排查"
}'
)响应示例(200 OK):
{
"originalQuery": "请问OB数据库向量索引报错怎么排查",
"rewrittenQuery": "OceanBase 向量索引报错怎么排查",
"expandedTerms": [
"OceanBase",
"OB数据库",
"HNSW索引",
"IVF索引"
],
"removedStopwords": [
"请问"
],
"matchedEntries": [
{
"entryId": "ent_ob_syn_01",
"entryType": "synonym",
"matchedTerm": "OB数据库",
"canonicalTerm": "OceanBase"
}
]
}GET /v1/knowledgebases/{knowledgeBaseId}/lexicons 与 PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons
SDK:Lexicons.getKnowledgeBaseBindings / Lexicons.updateKnowledgeBaseBindings · scope:lexicons.read / lexicons.write
查询或整体替换指定知识库(如 kb_enterprise_support)绑定的词库列表及启用状态。
PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons 输入参数:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
knowledgeBaseId | path | string | 是 | — | 目标知识库 ID。 |
enabled | body | boolean | 否 | 默认 false | 是否对该知识库的检索与预处理启用词库改写。 |
bindings | body | object[] | 是 | — | 有序绑定数组(最多 100 项),每项格式为 {"lexiconId": "<id>", "priority": <int>}。 |
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X PUT "${APPBASE_ENDPOINT}/knowledgebases/kb_enterprise_support/lexicons" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"bindings": [
{"lexiconId": "lex_enterprise_synonyms", "priority": 1},
{"lexiconId": "lex_support_stopwords", "priority": 2}
]
}'
)(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
# 查询知识库当前绑定的词库列表(GET /v1/knowledgebases/{kbId}/lexicons)
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X GET "<APPBASE_ENDPOINT_WITH_V1>/knowledgebases/kb_enterprise_support/lexicons" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @-
)响应示例(200 OK):
{
"enabled": true,
"stopIntercept": false,
"stopReply": "",
"bindings": [
{
"lexiconId": "lex_enterprise_synonyms",
"priority": 1
},
{
"lexiconId": "lex_support_stopwords",
"priority": 2
}
]
}说明:当前项目智能体工作台(Agent Runtime Workbench)支持通过同构端点
GET /v1/agent-runtime/project/lexicons与PUT /v1/agent-runtime/project/lexicons(额外支持stopIntercept: true与stopReply阻断话术配置)绑定同一套项目词库,详见 Agent Runtime API。
错误与边界
知识库/文档/切片/数据源/同步/摄取不存在:
404+knowledge_base_not_found等对应类型;重复 ID:409。embeddingModel在建库时固定:修改需重建库重新摄取;文档级parserId覆盖可在摄取时以overrides再覆盖。向量化和重排依赖 LLM Gateway:模型供应商不可用或配额耗尽时,摄取或检索会返回依赖失败错误;请检查 LLM Gateway 中的供应商状态。
批量导入上限:文件 50 / URL 20;
207多状态响应需逐项检查结果,不能假定有成功项。enabled=false的文档从检索结果中排除但保留切片;删除文档级联删除切片与向量。语雀团队令牌与 OAuth 凭证属敏感凭证:
credentials写入后不回显;OAuth 会话过期后需重新创建。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
KnowledgeBases.list / create / get / update / delete | /knowledgebases CRUD |
KnowledgeBases.createSearch / createMultiSearch | POST .../{id}/search、POST /knowledgebases/search |
KnowledgeBases.getManagement / createReindex | GET .../management、POST .../reindex |
KnowledgeBases.listDocuments / createDocument / createDocumentsBatch / getDocument / updateDocument / deleteDocument | /knowledgebases/{id}/documents* |
KnowledgeBases.createDocumentProcess / getDocumentSource | POST .../process、GET .../source |
KnowledgeBases.listChunks / createChunk / getChunk / updateChunk / deleteChunk | .../chunks* |
KnowledgeBases.listIngestions / createIngestion / getIngestion / deleteIngestion | .../ingestions* |
KnowledgeBases.listDataSources / createDataSource / getDataSource / updateDataSource / deleteDataSource | .../datasources* |
KnowledgeBases.listYuqueRepos / listYuqueDocs | POST .../datasources/yuque/repos|docs |
KnowledgeBases.createDataSourceDocument / createDataSourceDocumentsBatch / listDataSourceSyncs / createDataSourceSync / getDataSourceSync | .../datasources/{dataSourceId}/documents*、syncs* |
Lexicons.list / create / get / update / delete | /v1/lexicons CRUD |
Lexicons.listEntries / createEntry / getEntry / updateEntry / deleteEntry | /v1/lexicons/{lexiconId}/entries* |
Lexicons.preview / import / export / listReferences | /v1/lexicons/{lexiconId}/preview|import|export|references |
Lexicons.getKnowledgeBaseBindings / updateKnowledgeBaseBindings | GET|PUT /v1/knowledgebases/{knowledgeBaseId}/lexicons |
2.12.0 接口与兼容增量
以下路径相对于 /v1。服务端请求携带 X-Appwrite-Project 与 X-Appwrite-Key;Key 仅留在服务端。Scope 是下表的必要条件;数据集、归属和资源状态还会追加校验。HTTP 202 只表示接受,须使用返回的任务标识查询终态。
| HTTP | Scope | SDK |
|---|---|---|
POST /knowledgebases/project-scopes | knowledgebases.write | knowledgeBases.createProjectScope |
GET /knowledgebases/project-scopes/{projectId} | knowledgebases.read | knowledgeBases.getProjectScope |
PATCH /knowledgebases/project-scopes/{projectId} | knowledgebases.write | knowledgeBases.updateProjectScope |
POST /knowledgebases/search | knowledgebases.read | knowledgeBases.createMultiSearch |
GET /knowledgebases/{knowledgeBaseId}/document-directories | knowledgebases.read | knowledgeBases.listDocumentDirectories |
POST /knowledgebases/{knowledgeBaseId}/document-directories/count | knowledgebases.read | knowledgeBases.countDocumentDirectories |
GET /knowledgebases/{knowledgeBaseId}/documents | knowledgebases.read | knowledgeBases.listDocuments |
POST /knowledgebases/{knowledgeBaseId}/documents | knowledgebases.write | knowledgeBases.createDocument |
POST /knowledgebases/{knowledgeBaseId}/documents/batch | knowledgebases.write | knowledgeBases.createDocumentsBatch |
PATCH /knowledgebases/{knowledgeBaseId}/documents/{documentId} | knowledgebases.write | knowledgeBases.updateDocument |
PATCH /knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId} | knowledgebases.write | knowledgeBases.updateChunk |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/content | knowledgebases.read | knowledgeBases.getDocumentContent |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact | knowledgebases.read | knowledgeBases.getDocumentParseArtifact |
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact/content | knowledgebases.read | knowledgeBases.getDocumentParseArtifactContent |
GET /knowledgebases/{knowledgeBaseId}/enhancement-operations | knowledgebases.read | knowledgeBases.listEnhancementOperations |
POST /knowledgebases/{knowledgeBaseId}/enhancement-operations | knowledgebases.write | knowledgeBases.createEnhancementOperation |
GET /knowledgebases/{knowledgeBaseId}/enhancement-operations/{operationId} | knowledgebases.read | knowledgeBases.getEnhancementOperation |
POST /knowledgebases/{knowledgeBaseId}/enhancement-operations/{operationId}/cancel | knowledgebases.write | knowledgeBases.cancelEnhancementOperation |
GET /knowledgebases/{knowledgeBaseId}/graph | knowledgebases.read | knowledgeBases.getGraph |
POST /knowledgebases/{knowledgeBaseId}/graph/search | knowledgebases.read | knowledgeBases.createGraphSearch |
GET /knowledgebases/{knowledgeBaseId}/lexicons | lexicons.read | lexicons.getKnowledgeBaseBindings |
PUT /knowledgebases/{knowledgeBaseId}/lexicons | lexicons.write | lexicons.updateKnowledgeBaseBindings |
POST /knowledgebases/{knowledgeBaseId}/search | knowledgebases.read | knowledgeBases.createSearch |
GET /knowledgebases/{knowledgeBaseId}/wiki/graph | knowledgebases.read | knowledgeBases.getWikiGraph |
GET /knowledgebases/{knowledgeBaseId}/wiki/pages | knowledgebases.read | knowledgeBases.listWikiPages |
POST /knowledgebases/{knowledgeBaseId}/wiki/search | knowledgebases.read | knowledgeBases.createWikiSearch |
GET /lexicons | lexicons.read | lexicons.list |
POST /lexicons | lexicons.write | lexicons.create |
GET /lexicons/{lexiconId} | lexicons.read | lexicons.get |
PATCH /lexicons/{lexiconId} | lexicons.write | lexicons.update |
DELETE /lexicons/{lexiconId} | lexicons.write | lexicons.delete |
GET /lexicons/{lexiconId}/entries | lexicons.read | lexicons.listEntries |
POST /lexicons/{lexiconId}/entries | lexicons.write | lexicons.createEntry |
GET /lexicons/{lexiconId}/entries/{entryId} | lexicons.read | lexicons.getEntry |
PATCH /lexicons/{lexiconId}/entries/{entryId} | lexicons.write | lexicons.updateEntry |
DELETE /lexicons/{lexiconId}/entries/{entryId} | lexicons.write | lexicons.deleteEntry |
GET /lexicons/{lexiconId}/export | lexicons.read | lexicons.export |
POST /lexicons/{lexiconId}/import | lexicons.write | lexicons.import |
POST /lexicons/{lexiconId}/preview | lexicons.read | lexicons.preview |
GET /lexicons/{lexiconId}/references | lexicons.read | lexicons.listReferences |
POST /knowledgebases/project-scopes
注册项目范围
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
projectId | body | 是 | string | — | 面向客户的项目标识,由 1–64 个字母或数字组成。 |
name | body | 否 | string | default="" | 可选的显示名称,用于团队命名。 |
subProductId | body | 否 | string | default="" | 绑定的子产品代码;可选,也可稍后绑定。 |
knowledgeBaseId | body | 否 | string | default="" | 绑定为项目资产库的现有知识库;可选,也可稍后通过更新接口绑定。 |
成功响应:HTTP 201 — knowledgeBaseProjectScope.
返回字段:$id (string), $createdAt (string), $updatedAt (string), projectId (string), name (string), knowledgeBaseId (string), teamId (string), subProductId (string).
GET /knowledgebases/project-scopes/{projectId}
查询项目范围
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
projectId | path | 是 | string | — | 面向客户的项目标识。 |
成功响应:HTTP 200 — knowledgeBaseProjectScope.
返回字段:$id (string), $createdAt (string), $updatedAt (string), projectId (string), name (string), knowledgeBaseId (string), teamId (string), subProductId (string).
PATCH /knowledgebases/project-scopes/{projectId}
更新项目范围
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
projectId | path | 是 | string | — | 面向客户的项目标识。 |
name | body | 否 | string | default="" | 显示名称;留空保持原值。 |
subProductId | body | 否 | string | default="" | 绑定的子产品代码;留空保持原绑定,传入新代码可重新绑定。没有专用清除值,清除须重新绑定或联系平台处理。 |
knowledgeBaseId | body | 否 | string | default="" | 绑定为项目资产库的知识库;留空保持原绑定,传入 "none" 可清除。 |
成功响应:HTTP 200 — knowledgeBaseProjectScope.
返回字段:$id (string), $createdAt (string), $updatedAt (string), projectId (string), name (string), knowledgeBaseId (string), teamId (string), subProductId (string).
POST /knowledgebases/search
跨知识库检索
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseIds | body | 否 | array[string] | default=[] | 知识库 ID 列表。不传 projectId 时须提供 1–10 个不重复的 ID;设置 projectId 时应省略,由服务端展开三层检索范围。 |
query | body | 是 | string | — | 检索文本。 |
limit | body | 否 | integer | format=int32; default=10 | 所有知识库合并后返回的最终结果数量。 |
searchMode | body | 否 | string | enum=vector, fulltext, hybrid; default="hybrid" | 检索模式:vector、fulltext 或 hybrid。 |
rerank | body | 否 | boolean | default=false | 是否通过 LLM Gateway 对合并召回结果进行一次重排。 |
recallLimit | body | 否 | integer | format=int32 | 启用重排时的全局召回数量,默认 max(limit×4, 20)。 |
rerankModel | body | 否 | string | default="" | 可选的重排模型 ID;启用重排时覆盖自动提供商选择。 |
rerankProviderRef | body | 否 | string | — | 指定重排提供商来源,格式为 project:<providerId> 或 trial:<bindingId>;不填使用自动路由,不要使用 providerType:providerId。 |
similarityThreshold | body | 否 | number | format=float | 应用于各知识库的最低向量相似度;不填时使用各知识库的默认值。 |
vectorWeight | body | 否 | number | format=float | 应用于各知识库的混合检索向量分支权重;不填时使用各知识库默认值。 |
projectId | body | 否 | string | — | 可选的客户项目标识。设置时须省略 knowledgeBaseIds;服务端先检查项目成员关系,再展开项目知识库层、绑定子产品层和公共层。成员检查失败时拒绝访问。 |
documentTag | body | 否 | string | — | 可选标签 {subProductId}_{sectionCode}_{fileKey},也可传入逗号分隔的多个标签(匹配任一即可)或自定义值;应用于各知识库的分块召回。 |
subProductId | body | 否 | string | — | 可选的子产品代码;各知识库的分块召回只返回该子产品的文档。 |
offset | body | 否 | integer | format=int32; default=0 | 融合排序后跳过的结果数,可与 limit 配合分页。 |
metadataFilter | body | 否 | object | default={} | 可选的文档元数据过滤条件,以知识库 ID 为键;可用 "*" 为未单独配置的知识库提供默认条件。各知识库在分块召回前先筛选文档。 |
成功响应:HTTP 200 — knowledgeBaseMultiSearchResultList.
返回字段:stopped (boolean), effectiveQuery (string), stopReply (string), total (integer), results (array), reranked (boolean).
GET /knowledgebases/{knowledgeBaseId}/document-directories
列出文档目录
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
parentPath | query | 否 | string | default="" | 父目录路径;留空表示根目录。 |
limit | query | 否 | integer | format=int32; default=100 | 返回目录的最大数量。 |
offset | query | 否 | integer | format=int32; default=0 | 目录分页偏移量。 |
versionId | query | 否 | string | — | 可选的知识库版本 ID。 |
成功响应:HTTP 200 — any.
POST /knowledgebases/{knowledgeBaseId}/document-directories/count
统计目录并集中的文档
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
paths | body | 否 | array[string] | default=[] | 目录路径列表;统计这些目录文档的并集。 |
versionId | body | 否 | string | — | 可选的知识库版本 ID。 |
groups | body | 否 | array[string] | — | 可选的目录并集批次,每次最多 100 组;不能与非空 paths 同时使用。 |
成功响应:HTTP 200 — any.
GET /knowledgebases/{knowledgeBaseId}/documents
列出知识库文档
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
status | query | 否 | string | default="" | 按状态过滤文档。 |
stage | query | 否 | string | default="" | 按处理阶段过滤文档。 |
enabled | query | 否 | boolean | — | 按启用状态过滤文档。 |
documentTag | query | 否 | string | — | 可选标签 {subProductId}_{sectionCode}_{fileKey},按 metadata.documentTag 精确匹配;也接受自定义值。 |
subProductId | query | 否 | string | — | 可选的子产品代码,仅返回 metadata.subProductId 或 documentTag 中子产品段与其相等的文档;可与 documentTag 组合,要求同时匹配。 |
queries | query | 否 | array[string] | default=[] | 使用 SDK 的 Query 类生成的查询字符串数组,最多 100 项,每项最多 4096 个字符;设置 documentTag 或 subProductId 时忽略。 |
versionId | query | 否 | string | — | 可选的知识库版本 ID;知识库处于 ACTIVE 状态时默认使用当前版本。 |
directoryPath | query | 否 | string | — | 规范化的目录路径,包含子目录。 |
directoryUnclassified | query | 否 | boolean | default=false | 仅包含没有目录的文档。 |
成功响应:HTTP 200 — knowledgeBaseDocumentList.
返回字段:total (integer), documents (array).
POST /knowledgebases/{knowledgeBaseId}/documents
创建知识库文档
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
bucketId | body | 否 | string | default="" | 已上传源文件所在的存储桶 ID;可选,默认使用知识库存储桶。 |
fileId | body | 是 | string | — | 已上传源文件的存储文件 ID。 |
name | body | 否 | string | default="" | 可选的文档显示名称,默认使用存储文件名。 |
documentTag | body | 否 | string | default="" | 可选标签 {subProductId}_{sectionCode}_{fileKey};可省略 fileKey,由服务端生成。多个标签用逗号分隔,也支持自定义值;以列表形式存入 metadata.documentTag。 |
subProductId | body | 否 | string | default="" | 可选的子产品代码(1–64 个字母或数字),保存为独立字段 metadata.subProductId。若同时提交非空 documentTag 并省略或清空本字段,仅当首个标签为有效结构化标识且包含非空子产品段时派生。 |
projectId | body | 否 | string | default="" | 可选的客户项目标识(1–64 个字母或数字),存入 metadata.projectId,标记文档所属项目;共享知识库方案可据此过滤召回。 |
sectionCode | body | 否 | string | default="" | 可选的章节代码(1–64 位数字);省略 documentTag 时作为自动生成标签的 sectionCode 段。 |
source | body | 否 | string | default="manual" | 文档来源,默认 manual。 |
externalItemId | body | 否 | string | default="" | 文档来自外部数据源时的外部条目 ID。 |
parserId | body | 否 | string | enum=general, title, smart, regex, faq, sheet | 可选的文档级切片策略;不填时继承知识库默认值并按具体文件校验。Excel .xls/.xlsx 直接支持 faq 或 sheet,smart 自动解析为 sheet;其他格式不可使用 sheet。 |
parserConfig | body | 否 | object | — | 可选的文档级解析器配置覆盖项。 |
metadata | body | 否 | object | default=[] | 可选的业务元数据。 |
versionId | body | 否 | string | — | 可选的 DRAFT 知识库版本 ID;版本管理为 ACTIVE 时写操作必填。 |
成功响应:HTTP 201 — knowledgeBaseDocument.
返回字段:$id (string), $createdAt (string), $updatedAt (string), kbId (string), versionId (string), name (string), bucketId (string), fileId (string), mimeType (string), source (string), externalItemId (string), parserId (string), parserConfig (object), metadata (object), status (string), enabled (boolean), stage (string), activeIngestionId (string), activeGeneration (string), processingStartedAt (string), chunksTotal (integer), chunkCount (integer), error (string), lastExecutionId (string).
POST /knowledgebases/{knowledgeBaseId}/documents/batch
批量创建知识库文档
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
fileIds | body | 是 | array[string] | — | 注册为文档的存储文件 ID,最多 50 个。 |
bucketId | body | 否 | string | default="" | 可选的存储桶 ID,默认使用知识库存储桶。 |
source | body | 否 | string | default="manual" | 文档来源,默认 manual。 |
parserId | body | 否 | string | enum=general, title, smart, regex, faq, sheet | 可选的文档级切片策略;不填时继承知识库默认值并逐个文件校验。Excel .xls/.xlsx 直接支持 faq 或 sheet,smart 自动解析为 sheet;其他格式不可使用 sheet。 |
parserConfig | body | 否 | object | — | 可选的文档级解析器配置覆盖项。 |
metadata | body | 否 | object | default=[] | 所有文档共享的可选业务元数据。 |
documentTag | body | 否 | string | default="" | 应用于批次中每个文档的可选标签 {subProductId}_{sectionCode}_{fileKey};可省略 fileKey,由服务端分别生成。多个标签用逗号分隔,也支持自定义值;以列表形式存入 metadata.documentTag。 |
subProductId | body | 否 | string | default="" | 应用于每个文档的可选子产品代码(1–64 个字母或数字),保存为独立字段 metadata.subProductId。若同时提交非空 documentTag 并省略或清空本字段,仅当首个标签为有效结构化标识且包含非空子产品段时派生。 |
projectId | body | 否 | string | default="" | 可选的客户项目标识(1–64 个字母或数字),存入每个文档的 metadata.projectId,标记所属项目;共享知识库方案可据此过滤召回。 |
sectionCode | body | 否 | string | default="" | 可选的章节代码(1–64 位数字);省略 documentTag 时作为自动生成标签的 sectionCode 段。 |
versionId | body | 否 | string | — | 可选的 DRAFT 知识库版本 ID;版本管理为 ACTIVE 时写操作必填。 |
成功响应:HTTP 201 — knowledgeBaseDocumentList.
返回字段:total (integer), documents (array).
PATCH /knowledgebases/{knowledgeBaseId}/documents/{documentId}
更新知识库文档
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
documentId | path | 是 | string | — | 知识库文档 ID。 |
name | body | 否 | string | — | 文档显示名称。 |
documentTag | body | 否 | string | — | 可选标签 {subProductId}_{sectionCode}_{fileKey};可省略 fileKey,由服务端生成,或以逗号分隔多个标签,也支持自定义值。传入空字符串可清除 metadata.documentTag。 |
subProductId | body | 否 | string | — | 可选的子产品代码,保存在独立字段 metadata.subProductId。仅清空该字段时,有效过滤值仍可能回退到已有结构化标签;要移除两处关联,须同时清空 documentTag。提交非空 documentTag 且省略或清空本字段时,仅当首个标签为有效结构化标识且包含非空子产品段时派生。 |
projectId | body | 否 | string | — | 可选的客户项目标识,存入 metadata.projectId;传入空字符串可清除。用于标记文档所属项目,供共享知识库召回过滤。 |
parserId | body | 否 | string | enum=general, title, smart, regex, faq, sheet | 文档级切片策略。Excel .xls/.xlsx 直接支持 faq 或 sheet,smart 自动解析为 sheet;其他格式不可使用 sheet。传入空字符串可清除覆盖项,并按具体文件校验继承的知识库默认策略。 |
parserConfig | body | 否 | object | — | 文档级解析器配置覆盖项。 |
metadata | body | 否 | object | default={} | 可选业务元数据,替换现有业务元数据;除非显式提供 documentTag,否则保留 metadata.documentTag。 |
enabled | body | 否 | boolean | — | 文档是否启用并可被检索;禁用的文档不会出现在知识库检索结果中。 |
status | body | 否 | string | — | 处理状态(旧版字段,仅限 API Key)。 |
stage | body | 否 | string | — | 处理阶段(旧版字段,仅限 API Key)。 |
chunksTotal | body | 否 | integer | format=int32 | 分块总数(旧版字段,仅限 API Key)。 |
chunkCount | body | 否 | integer | format=int32 | 分块数(旧版字段,仅限 API Key)。 |
error | body | 否 | string | — | 错误信息(旧版字段,仅限 API Key)。 |
versionId | body | 否 | string | — | 可选的 DRAFT 知识库版本 ID;版本管理为 ACTIVE 时写操作必填。 |
成功响应:HTTP 200 — knowledgeBaseDocument.
返回字段:$id (string), $createdAt (string), $updatedAt (string), kbId (string), versionId (string), name (string), bucketId (string), fileId (string), mimeType (string), source (string), externalItemId (string), parserId (string), parserConfig (object), metadata (object), status (string), enabled (boolean), stage (string), activeIngestionId (string), activeGeneration (string), processingStartedAt (string), chunksTotal (integer), chunkCount (integer), error (string), lastExecutionId (string).
PATCH /knowledgebases/{knowledgeBaseId}/documents/{documentId}/chunks/{chunkId}
更新知识库文档分块
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
documentId | path | 是 | string | — | 知识库文档 ID。 |
chunkId | path | 是 | string | — | 分块 ID。 |
content | body | 否 | string | — | 分块文本内容;会结合已保存的图片描述重新计算嵌入向量。 |
metadata | body | 否 | object | default={} | 可选的自定义分块元数据;图片描述变化时重新计算嵌入向量。 |
enabled | body | 否 | boolean | — | 分块是否可被检索;禁用后不会出现在知识库检索结果中,文档重新发布后仍保持禁用。 |
versionId | body | 否 | string | — | 可选的 DRAFT 知识库版本 ID;版本管理为 ACTIVE 时写操作必填。 |
成功响应:HTTP 200 — knowledgeBaseChunk.
返回字段:$id (string), $createdAt (string), $updatedAt (string), documentId (string), versionId (string), content (string), ingestVersion (string), enabled (boolean), source (object), locator (object), metadata (object).
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/content
获取知识库文档内容
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
documentId | path | 是 | string | — | 知识库文档 ID。 |
versionId | query | 否 | string | — | 可选的知识库版本 ID;知识库处于 ACTIVE 状态时默认使用当前版本。 |
成功响应:HTTP 200 — knowledgeBaseDocumentContent.
返回字段:knowledgeBaseId (string), documentId (string), name (string), mimeType (string), status (string), generation (string), chunksTotal (integer), truncated (boolean), content (string).
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact
查询知识库文档解析产物状态
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
documentId | path | 是 | string | — | 知识库文档 ID。 |
versionId | query | 否 | string | — | 可选的知识库版本 ID;知识库处于 ACTIVE 状态时默认使用当前版本。 |
成功响应:HTTP 200 — knowledgeBaseDocumentParseArtifact.
返回字段:knowledgeBaseId (string), documentId (string), status (string), supported (boolean), generation (string), byteSize (integer), sha256 (string).
GET /knowledgebases/{knowledgeBaseId}/documents/{documentId}/parse-artifact/content
获取知识库文档解析产物内容
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
documentId | path | 是 | string | — | 知识库文档 ID。 |
versionId | query | 否 | string | — | 可选的知识库版本 ID;知识库处于 ACTIVE 状态时默认使用当前版本。 |
成功响应:HTTP 200 — File.
GET /knowledgebases/{knowledgeBaseId}/enhancement-operations
列出知识库内容增强操作
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
kind | query | 否 | string | enum=enhance, clear; default="" | 可选的操作类型过滤条件。 |
status | query | 否 | string | enum=queued, running, cancelling, done, failed, cancelled; default="" | 可选的操作状态过滤条件。 |
limit | query | 否 | integer | format=int32; default=25 | 返回操作的最大数量。 |
offset | query | 否 | integer | format=int32; default=0 | 跳过的操作数量。 |
成功响应:HTTP 200 — knowledgeBaseEnhancementOperationList.
返回字段:total (integer), operations (array).
POST /knowledgebases/{knowledgeBaseId}/enhancement-operations
为已保存文档提交内容增强操作
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
kind | body | 否 | string | enum=enhance, clear; default="enhance" | 操作类型:enhance 对已保存分块重新提取关键词、问题和元数据;clear 清除已有增强结果。 |
scope | body | 否 | string | enum=knowledgebase, document; default="knowledgeBase" | 操作范围。 |
documentIds | body | 否 | array[string] | default=[] | 文档范围操作使用的文档 ID 列表。 |
config | body | 否 | object | default=[] | 仅本次生效的配置覆盖项,与继承的关键词、问题和元数据配置合并;不会保存回知识库。 |
force | body | 否 | boolean | default=false | 将本次操作入队前,取消其他正在运行的增强操作。 |
onlyMissing | body | 否 | boolean | default=false | 当 kind=enhance 时,跳过所有已启用提取器均已有结果的文档,避免重复处理。 |
idempotencyKey | body | 是 | string | — | 用于重试去重的稳定标识。 |
retryOf | body | 否 | string | — | 需要重试的失败或已取消增强操作。 |
versionId | body | 否 | string | — | ACTIVE 知识库可选的 DRAFT 版本 ID。 |
成功响应:HTTP 202 — knowledgeBaseEnhancementOperation.
返回字段:$id (string), $createdAt (string), $updatedAt (string), knowledgeBaseId (string), versionId (string), kind (string), scope (string), documentIds (array), criteria (object), status (string), stage (string), message (string), effectiveConfig (object), configHash (string), retryOf (string), stats (object), error (object), logTail (string), startedAt (string), heartbeatAt (string), finishedAt (string).
GET /knowledgebases/{knowledgeBaseId}/enhancement-operations/{operationId}
查询知识库内容增强操作
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
operationId | path | 是 | string | — | 增强操作 ID。 |
成功响应:HTTP 200 — knowledgeBaseEnhancementOperation.
返回字段:$id (string), $createdAt (string), $updatedAt (string), knowledgeBaseId (string), versionId (string), kind (string), scope (string), documentIds (array), criteria (object), status (string), stage (string), message (string), effectiveConfig (object), configHash (string), retryOf (string), stats (object), error (object), logTail (string), startedAt (string), heartbeatAt (string), finishedAt (string).
POST /knowledgebases/{knowledgeBaseId}/enhancement-operations/{operationId}/cancel
请求取消知识库内容增强操作
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
operationId | path | 是 | string | — | 增强操作 ID。 |
成功响应:HTTP 202 — knowledgeBaseEnhancementOperation.
返回字段:$id (string), $createdAt (string), $updatedAt (string), knowledgeBaseId (string), versionId (string), kind (string), scope (string), documentIds (array), criteria (object), status (string), stage (string), message (string), effectiveConfig (object), configHash (string), retryOf (string), stats (object), error (object), logTail (string), startedAt (string), heartbeatAt (string), finishedAt (string).
GET /knowledgebases/{knowledgeBaseId}/graph
浏览当前 GraphRAG 节点关系图
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
query | query | 否 | string | default="" | 可选的实体文本过滤条件。 |
type | query | 否 | string | default="" | 可选的实体类型过滤条件。 |
community | query | 否 | string | default="" | 可选的社区过滤条件。 |
seed | query | 否 | string | default="" | 可选的实体种子,用于受限的 N 跳扩展。 |
hops | query | 否 | integer | format=int32; default=1 | 提供种子实体时扩展的邻居跳数。 |
limit | query | 否 | integer | format=int32; default=100 | 返回节点的最大数量。 |
cursor | query | 否 | string | default="" | 上一页图谱结果返回的不透明游标。 |
entityScope | query | 否 | string | enum=core, all; default="core" | 实体范围:"core" 展示跨多个文档出现的实体(子系统视角),"all" 展示全部已索引实体。 |
documentId | query | 否 | string | — | 可选的知识库文档 ID;设置后仅返回属于该文档的实体,可用于从文档详情反查。 |
documentTag | query | 否 | string | — | 可选标签 {subProductId}_{sectionCode}_{fileKey}、逗号分隔的多个标签(匹配任一)或自定义值;可与 documentId 组合,要求同时匹配。 |
subProductId | query | 否 | string | — | 可选的子产品代码,仅返回该子产品文档所属的实体;可与 documentTag 组合,要求同时匹配。 |
versionId | query | 否 | string | — | 可选的知识库版本 ID;知识库处于 ACTIVE 状态时默认使用当前版本。 |
view | query | 否 | string | enum=entities, communities, community; default="entities" | 图谱视图。communities 返回轻量概览,community 分页返回成员及相连边;社区视图要求 entityScope=all,且不接受实体或文档过滤条件。 |
communityIds | query | 否 | array[string] | — | 可选的 1–8 个不重复的可视化社区 ID,适用于 view=community 且 entityScope=all;与 community 互斥,不支持 cursor。所有成员须容纳在 min(limit,100) 个节点内,否则返回 400;通过 visualization.member_batch_version=1 判断是否支持。 |
成功响应:HTTP 200 — knowledgeBaseGraph.
返回字段:resultGeneration (string), versionId (string), graph (object), totalNodes (integer), hasMore (boolean), nextCursor (string), truncated (boolean).
POST /knowledgebases/{knowledgeBaseId}/graph/search
检索单个知识库中与问题相关的 GraphRAG 上下文
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
query | body | 是 | string | — | 用于检索 GraphRAG 上下文的问题。 |
maxToken | body | 否 | integer | format=int32; default=8196 | 图谱上下文的最大 token 数。 |
entityTopN | body | 否 | integer | format=int32; default=6 | 匹配实体的最大数量。 |
relationTopN | body | 否 | integer | format=int32; default=6 | 匹配关系的最大数量。 |
communityTopN | body | 否 | integer | format=int32; default=1 | 社区报告的最大数量。 |
entitySimilarityThreshold | body | 否 | number | format=float; default=0.3 | 实体最低相似度。 |
relationSimilarityThreshold | body | 否 | number | format=float; default=0.3 | 关系最低相似度。 |
versionId | body | 否 | string | — | 可选的知识库版本 ID,默认使用当前版本。 |
成功响应:HTTP 200 — knowledgeBaseGraphSearch.
返回字段:resultGeneration (string), versionId (string), content (string), graphContext (object).
GET /knowledgebases/{knowledgeBaseId}/lexicons
getKnowledgeBaseBindings
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
成功响应:HTTP 200 — lexiconBindings.
返回字段:enabled (boolean), stopIntercept (boolean), stopReply (string), bindings (object).
PUT /knowledgebases/{knowledgeBaseId}/lexicons
updateKnowledgeBaseBindings
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
bindings | body | 是 | array[array] | — | 绑定列表。 |
enabled | body | 否 | boolean | default=false | 是否启用。 |
成功响应:HTTP 200 — lexiconBindings.
返回字段:enabled (boolean), stopIntercept (boolean), stopReply (string), bindings (object).
POST /knowledgebases/{knowledgeBaseId}/search
检索知识库
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
query | body | 是 | string | — | 检索文本。 |
limit | body | 否 | integer | format=int32; default=10 | 最终返回的结果数量。 |
searchMode | body | 否 | string | enum=vector, fulltext, hybrid; default="hybrid" | 检索模式:vector、fulltext 或 hybrid。 |
rerank | body | 否 | boolean | default=false | 是否通过 LLM Gateway 重排召回结果。 |
recallLimit | body | 否 | integer | format=int32 | 启用重排时的召回数量,默认 max(limit×4, 20)。 |
rerankModel | body | 否 | string | default="" | 可选的重排模型 ID;启用重排时覆盖自动提供商选择。 |
rerankProviderRef | body | 否 | string | — | 指定重排提供商来源,格式为 project:<providerId> 或 trial:<bindingId>;不填使用自动路由,不要使用 providerType:providerId。 |
similarityThreshold | body | 否 | number | format=float | 最低向量相似度,适用于向量检索及混合检索中的向量召回分支。 |
vectorWeight | body | 否 | number | format=float | 混合检索向量分支权重(全文分支使用 1 - vectorWeight),默认取知识库的 retrievalDefaults.vectorWeight。 |
useKnowledgeGraph | body | 否 | boolean | default=false | 是否加入已启用的 GraphRAG 检索。 |
useWiki | body | 否 | boolean | default=false | 是否加入已启用的 Wiki 检索。 |
graphOptions | body | 否 | object | default=[] | 受限的 GraphRAG 检索选项。 |
wikiOptions | body | 否 | object | default=[] | Wiki 模式、topK、minK、向量及受限的链接扩展选项。 |
allowDegraded | body | 否 | boolean | default=true | 增强能力失败时,是否允许返回普通结果并明确附带降级元数据。 |
answer | body | 否 | boolean | default=false | 是否根据合并后的检索证据生成有依据的回答;使用知识库 indexingDefaults 中的对话模型。 |
documentTag | body | 否 | string | — | 可选标签 {subProductId}_{sectionCode}_{fileKey}、逗号分隔的多个标签(匹配任一)或自定义值;用于限制分块、GraphRAG 和 Wiki 召回。 |
subProductId | body | 否 | string | — | 可选子产品代码,限制分块、GraphRAG 和 Wiki 仅召回该子产品文档(metadata.subProductId 或 documentTag 对应段)。 |
projectId | body | 否 | string | — | 可选客户项目标识,限制召回 metadata.projectId 为该项目的文档(共享知识库方案)。 |
metadataFilter | body | 否 | object | default={} | 可选文档元数据过滤条件;在分块召回前筛选文档,其他文档的分块不会参与召回。 |
applyLexicon | body | 否 | boolean | — | 仅覆盖本次检索的词库改写设置;不填时使用知识库配置。 |
documentIds | body | 否 | array[string] | — | 可选的 1–100 个不重复文档 ID,将基础 RAG 召回限制在这些文档内;不可与 GraphRAG 或 Wiki 检索组合。 |
versionId | body | 否 | string | — | 可选版本 ID;版本管理启用时默认使用当前 READY 版本。 |
成功响应:HTTP 200 — knowledgeBaseSearchResultList.
返回字段:stopped (boolean), effectiveQuery (string), stopReply (string), total (integer), results (array), reranked (boolean), resolvedVersionId (string), capabilities (object), degradedCapabilities (array), answer (object), elapsedMs (integer), timingMs (object).
GET /knowledgebases/{knowledgeBaseId}/wiki/graph
获取 Wiki 页面链接图,包括指向尚不存在页面的链接
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
versionId | query | 否 | string | — | 可选的知识库版本 ID;知识库处于 ACTIVE 状态时默认使用当前版本。 |
documentTag | query | 否 | string | — | 可选标签 {subProductId}_{sectionCode}_{fileKey}、逗号分隔的多个标签(匹配任一)或自定义值;仅返回 sourceChunks 来源引用匹配文档的 Wiki 页面,链接限制为保留页面之间的子图。 |
subProductId | query | 否 | string | — | 可选子产品代码,仅返回来源引用该子产品文档的 Wiki 页面;可与 documentTag 组合,要求同时匹配。 |
成功响应:HTTP 200 — knowledgeBaseWikiGraph.
返回字段:versionId (string), pages (array), links (object).
GET /knowledgebases/{knowledgeBaseId}/wiki/pages
列出知识库 Wiki 页面
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
pageType | query | 否 | string | enum=entity, topic, survey, agent_practice, category_index; default="" | 可选的 Wiki 页面类型。 |
status | query | 否 | string | enum=draft, published, conflict, archived; default="" | 可选的 Wiki 页面状态。 |
limit | query | 否 | integer | format=int32; default=50 | 返回页面的最大数量。 |
offset | query | 否 | integer | format=int32; default=0 | 跳过的页面数量。 |
versionId | query | 否 | string | — | 可选的知识库版本 ID;知识库处于 ACTIVE 状态时默认使用当前版本。 |
documentTag | query | 否 | string | — | 可选标签 {subProductId}_{sectionCode}_{fileKey}、逗号分隔的多个标签(匹配任一)或自定义值;仅返回 sourceChunks 来源引用匹配文档的 Wiki 页面。 |
subProductId | query | 否 | string | — | 可选子产品代码,仅返回来源引用该子产品文档的 Wiki 页面;可与 documentTag 组合,要求同时匹配。 |
成功响应:HTTP 200 — knowledgeBaseWikiPageList.
返回字段:total (integer), pages (array).
POST /knowledgebases/{knowledgeBaseId}/wiki/search
检索单个知识库中的 Wiki 页面
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
knowledgeBaseId | path | 是 | string | — | 知识库 ID。 |
query | body | 是 | string | — | Wiki 查询文本。 |
searchMode | body | 否 | string | enum=auto, wiki_direct, wiki_retrieved, rag_first; default="auto" | 覆盖 Wiki 路由等级。 |
topK | body | 否 | integer | format=int32; default=8 | 返回 Wiki 页面的最大数量。 |
useVector | body | 否 | boolean | default=true | 是否包含向量召回。 |
vectorWeight | body | 否 | number | format=float; default=0.4 | RRF 融合前的向量贡献权重。 |
linkOptions | body | 否 | object | default=[] | 受限的 Wiki 链接扩展选项。 |
versionId | body | 否 | string | — | 可选的知识库版本 ID,默认使用当前版本。 |
成功响应:HTTP 200 — knowledgeBaseWikiSearch.
返回字段:resultGeneration (string), contentStale (boolean), tier (string), results (array), toc (object), categoryIndex (object), latencyMs (integer).
GET /lexicons
list
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
limit | query | 否 | integer | format=int32; default=25 | 返回条数上限。 |
offset | query | 否 | integer | format=int32; default=0 | 分页偏移量。 |
成功响应:HTTP 200 — lexiconList.
返回字段:total (integer), lexicons (array).
POST /lexicons
create
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
lexiconId | body | 否 | string | default="unique()" | 词库 ID。 |
name | body | 是 | string | — | 名称。 |
description | body | 否 | string | default="" | 描述。 |
permissions | body | 否 | array[string] | — | 权限列表。 |
synonymRewriteMode | body | 否 | string | enum=matched, primary, primary_expansion; default="matched" | 同义词改写方式:matched、primary 或 primary_expansion。 |
成功响应:HTTP 201 — lexicon.
返回字段:$id (string), $createdAt (string), $updatedAt (string), $permissions (array), name (string), description (string), tokenizerProfile (string), synonymRewriteMode (string), revision (integer).
GET /lexicons/{lexiconId}
get
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
lexiconId | path | 是 | string | — | 词库 ID。 |
成功响应:HTTP 200 — lexicon.
返回字段:$id (string), $createdAt (string), $updatedAt (string), $permissions (array), name (string), description (string), tokenizerProfile (string), synonymRewriteMode (string), revision (integer).
PATCH /lexicons/{lexiconId}
update
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
lexiconId | path | 是 | string | — | 词库 ID。 |
name | body | 否 | string | — | 名称。 |
description | body | 否 | string | — | 描述。 |
permissions | body | 否 | array[string] | — | 权限列表。 |
synonymRewriteMode | body | 否 | string | enum=matched, primary, primary_expansion | 同义词改写方式:matched、primary 或 primary_expansion。 |
成功响应:HTTP 200 — lexicon.
返回字段:$id (string), $createdAt (string), $updatedAt (string), $permissions (array), name (string), description (string), tokenizerProfile (string), synonymRewriteMode (string), revision (integer).
DELETE /lexicons/{lexiconId}
delete
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
lexiconId | path | 是 | string | — | 词库 ID。 |
成功响应:HTTP 204 — No content.
GET /lexicons/{lexiconId}/entries
listEntries
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
lexiconId | path | 是 | string | — | 词库 ID。 |
limit | query | 否 | integer | format=int32; default=25 | 分页大小。 |
offset | query | 否 | integer | format=int32; default=0 | 分页偏移量。 |
entryType | query | 否 | string | enum=synonym, expansion, stop | 按规则类型过滤条目;不填时列出全部类型。 |
成功响应:HTTP 200 — lexiconEntryList.
返回字段:total (integer), entries (array).
POST /lexicons/{lexiconId}/entries
createEntry
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
lexiconId | path | 是 | string | — | 词库 ID。 |
entryId | body | 否 | string | default="unique()" | 条目 ID。 |
entryType | body | 是 | string | enum=synonym, expansion, stop | 条目类型。 |
terms | body | 是 | array[string] | — | 词项列表。 |
expansions | body | 否 | array[string] | default=[] | 扩展词列表。 |
position | body | 否 | integer | format=int32; default=0 | 位置。 |
成功响应:HTTP 201 — lexiconEntry.
返回字段:$id (string), $createdAt (string), $updatedAt (string), lexiconId (string), entryType (string), terms (array), expansions (array), position (integer).
GET /lexicons/{lexiconId}/entries/{entryId}
getEntry
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
lexiconId | path | 是 | string | — | 词库 ID。 |
entryId | path | 是 | string | — | 条目 ID。 |
成功响应:HTTP 200 — lexiconEntry.
返回字段:$id (string), $createdAt (string), $updatedAt (string), lexiconId (string), entryType (string), terms (array), expansions (array), position (integer).
PATCH /lexicons/{lexiconId}/entries/{entryId}
updateEntry
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
lexiconId | path | 是 | string | — | 词库 ID。 |
entryId | path | 是 | string | — | 条目 ID。 |
entryType | body | 否 | string | enum=synonym, expansion, stop | 条目类型。 |
terms | body | 否 | array[string] | — | 词项列表。 |
expansions | body | 否 | array[string] | — | 扩展词列表。 |
position | body | 否 | integer | format=int32 | 位置。 |
成功响应:HTTP 200 — lexiconEntry.
返回字段:$id (string), $createdAt (string), $updatedAt (string), lexiconId (string), entryType (string), terms (array), expansions (array), position (integer).
DELETE /lexicons/{lexiconId}/entries/{entryId}
deleteEntry
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
lexiconId | path | 是 | string | — | 词库 ID。 |
entryId | path | 是 | string | — | 条目 ID。 |
成功响应:HTTP 204 — No content.
GET /lexicons/{lexiconId}/export
export
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
lexiconId | path | 是 | string | — | 词库 ID。 |
format | query | 否 | string | enum=json, csv, xlsx; default="json" | 导出格式。 |
成功响应:HTTP 200 — File.
POST /lexicons/{lexiconId}/import
import
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
lexiconId | path | 是 | string | — | 词库 ID。 |
entries | body | 否 | array[array] | default=[] | 条目列表。 |
mode | body | 否 | string | enum=merge, overwrite; default="merge" | 模式。 |
dryRun | body | 否 | boolean | default=true | 是否仅预检。 |
format | body | 否 | string | enum=json, csv, xlsx; default="json" | 文件格式。 |
content | body | 否 | string | default="" | CSV 或 XLSX 文件的 Base64 内容。 |
成功响应:HTTP 200 — lexiconImport.
返回字段:total (integer), inserted (integer), skipped (integer), errors (object), rows (object), applied (boolean), tokenizerProfile (string), tokenizationChanged (boolean).
POST /lexicons/{lexiconId}/preview
preview
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
lexiconId | path | 是 | string | — | 词库 ID。 |
query | body | 是 | string | — | 查询内容。 |
成功响应:HTTP 200 — lexiconRewrite.
返回字段:original (string), rewritten (string), stopped (boolean), stopMatched (array), mappings (object), tokenizerProfile (string), queryTokens (array).
GET /lexicons/{lexiconId}/references
listReferences
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
lexiconId | path | 是 | string | — | 词库 ID。 |
成功响应:HTTP 200 — lexiconReferences.
返回字段:total (integer), references (object).
错误与重试边界
400/422:核对类型、枚举与规则;401/403:核对身份与 Scope,数据集分析还要求 traces.read 和 datasets.read;404:确认资源仍存在且属于当前项目;409:重新读取当前状态后决定是否重试;429:按 Retry-After 等待;5xx 或断网后先读取任务状态。涉及幂等键的写入重试保留同一个键,主动重新执行才换键。删除与清空前确认目标,禁止通过循环重试扩大写入。