文档与摄取
文档登记、摄取管线、图片理解、语雀数据源同步与全量重建的各语言调用示例;概念、参数与边界口径见知识库。
各语言调用示例
摄取文档(登记 → 摄取 → 轮询)
createDocument 登记源文件,createIngestion 异步入队并返回 HTTP 202(表示任务已受理,不代表立即可检索)。轮询 getIngestion 至 ready,并确认 Document 的 status=ready、activeGeneration 与该 ingestion 的 generation 一致后,再按新代检索;ingestion 409 表示同文档已有进行中任务。Web 面无摄取能力。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
const doc = await kb.createDocument({ knowledgeBaseId: base.$id, fileId: '<storageFileId>' });
// 批量登记:kb.createDocumentsBatch(单批最多 50 个文件)
await kb.createIngestion({ knowledgeBaseId: base.$id, documentId: doc.$id }); // 异步入队,可带幂等键
// 轮询:状态机 queued → running → ready | failed | cancelled
const ing = await kb.getIngestion({ knowledgeBaseId: base.$id, documentId: doc.$id, ingestionId: '<ingestionId>' });var doc = kb.createDocument(base.getId(), "<storageFileId>",
null, null, null, null, null, null, null, null); // bucketId / name / documentTag / source / externalItemId / parserId / parserConfig / metadata
kb.createIngestion(base.getId(), doc.getId(), null, null, null, null); // 异步入队(幂等键 / retryOf / overrides 可选)
// 轮询:kb.getIngestion(base.getId(), doc.getId(), "<ingestionId>"),状态机 queued → running → ready | failed | cancelleddoc = kb.create_document(knowledge_base_id=base['$id'], file_id='<storageFileId>')
# 批量登记:kb.create_documents_batch(单批最多 50 个文件)
kb.create_ingestion(knowledge_base_id=base['$id'], document_id=doc['$id']) # 异步入队,可带幂等键
# 轮询:状态机 queued → running → ready | failed | cancelled
kb.get_ingestion(knowledge_base_id=base['$id'], document_id=doc['$id'], ingestion_id='<ingestionId>')doc, err := kb.CreateDocument(base.Id, "<storageFileId>") // fileId 为位置参数;其余经 WithCreateDocument* 选项
_, err = kb.CreateIngestion(base.Id, doc.Id,
kb.WithCreateIngestionIdempotencyKey("<idem-key>")) // 异步入队
// 轮询:状态机 queued → running → ready | failed | cancelled
_, err = kb.GetIngestion(base.Id, doc.Id, "<ingestionId>")curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/kb_product_docs/documents" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"fileId":"<storageFileId>"}'
# 摄取:POST /knowledgebases/{kbId}/documents/{documentId}/ingestions(可选幂等键 idempotencyKey)
# 轮询:GET .../ingestions/{ingestionId};重(再)处理:POST .../documents/{documentId}/process
# 批量登记(单批最多 50 文件):POST /knowledgebases/{kbId}/documents/batch图片理解(可选)
在 parserConfig.imageUnderstanding 配置,是解析后的独立步骤:为有信息量的图片生成描述并加入检索文本,不修改原始 chunk 的 content / span / locator;enabled=true 时 model 与 providerRef 必填。maxImagesPerDocument 传 null 或省略表示不限制图片理解数量。Web 面无此能力。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
await kb.createDocument({
knowledgeBaseId: base.$id,
fileId: '<storageFileId>',
parserConfig: {
imageUnderstanding: {
enabled: true,
model: '<visionModelId>', // 项目视觉模型 ID
providerRef: 'project:<providerId>', // 项目 Provider 引用
prompt: '用中文概括图片中的关键信息', // ≤4000 字符,空值用内置提示词
maxImagesPerDocument: 20, // 1–20,默认 20
maxDescriptionChars: 800, // 1–800,默认 800
maxConcurrency: 4 // 1–8,默认 4
}
}
});import io.agentbase.models.KnowledgeBaseImageUnderstandingConfig;
import io.agentbase.models.KnowledgeBaseParserConfig;
// parserConfig 为强类型模型(Java 面不外露 Map 形态):
var config = new KnowledgeBaseParserConfig()
.setImageUnderstanding(new KnowledgeBaseImageUnderstandingConfig()
.setEnabled(true)
.setModel("<visionModelId>") // 项目视觉模型 ID(enabled=true 时 model 与 providerRef 必填)
.setProviderRef("project:<providerId>") // 项目 Provider 引用
.setPrompt("用中文概括图片中的关键信息") // ≤4000 字符,空值用内置提示词
.setMaxImagesPerDocument(20L) // 1–20,默认 20
.setMaxDescriptionChars(800L) // 1–800,默认 800
.setMaxConcurrency(4L)); // 1–8,默认 4
kb.createDocument(base.getId(), "<storageFileId>",
null, null, null, null, null, null, config, null); // bucketId / name / documentTag / source / externalItemId / parserId 为 nullkb.create_document(
knowledge_base_id=base['$id'],
file_id='<storageFileId>',
parser_config={
'imageUnderstanding': {
'enabled': True,
'model': '<visionModelId>', # 项目视觉模型 ID(enabled=true 时 model 与 providerRef 必填)
'providerRef': 'project:<providerId>', # 项目 Provider 引用
'prompt': '用中文概括图片中的关键信息', # ≤4000 字符,空值用内置提示词
'maxImagesPerDocument': 20, # 1–20,默认 20
'maxDescriptionChars': 800, # 1–800,默认 800
'maxConcurrency': 4 # 1–8,默认 4
}
}) # keys 与 REST 请求体一致(camelCase 透传)import "agentbase-go-sdk/models"
_, err := kb.CreateDocument(base.Id, "<storageFileId>",
kb.WithCreateDocumentParserConfig(models.KnowledgeBaseParserConfig{
ImageUnderstanding: models.KnowledgeBaseImageUnderstandingConfig{
Enabled: true,
Model: "<visionModelId>", // 项目视觉模型 ID(enabled=true 时 model 与 providerRef 必填)
ProviderRef: "project:<providerId>", // 项目 Provider 引用
Prompt: "用中文概括图片中的关键信息", // ≤4000 字符,空值用内置提示词
MaxImagesPerDocument: 20, // 1–20,默认 20;省略不限制
MaxDescriptionChars: 800, // 1–800,默认 800
MaxConcurrency: 4, // 1–8,默认 4
}}))curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/kb_product_docs/documents" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"fileId":"<storageFileId>","parserConfig":{"imageUnderstanding":{"enabled":true,"model":"<visionModelId>","providerRef":"project:<providerId>","prompt":"用中文概括图片中的关键信息"}}}'
# 描述生成随摄取管线执行,跟随该文档 ingestion 状态一并完成Excel 工作表解析(2.7.0)
parserId 新增 sheet:仅适用于 Excel .xls / .xlsx,为每个非空工作表生成一个完整 chunk,并保存 sheetName / sheetIndex / sheetPages。Excel 文档直接支持 faq 或 sheet,smart 在摄取时自动解析为 sheet;general / title / regex 对具体 Excel 摄取返回 400。documentParser 仍可叠加:text 保留单元格结构化文本,vlm / mineru 把每个目标 Sheet 单独渲染成临时 PDF(适合图表与图片)。空输出 Sheet 不入库;工作簿 Sheet 数、解压量、压缩比、单元格矩形与渲染输入都有硬限制。Web 面无此能力,本卡不设 Web 页签。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
import { ParserId, KnowledgeBaseDocumentParser } from 'agentbase-node-sdk';
// 库级默认或文档级覆盖都可用 sheet;文档级 parserConfig 非空时整体替换 KB 默认
await kb.createDocument({
knowledgeBaseId: base.$id,
fileId: '<xlsxFileId>',
parserId: ParserId.Sheet,
parserConfig: { documentParser: KnowledgeBaseDocumentParser.Text }, // 逐 Sheet 提取结构化文本
});
// 图表密集型工作簿:documentParser 用 Vlm / Mineru(每个目标 Sheet 渲染为临时 PDF)import io.agentbase.enums.ParserId;
import io.agentbase.models.KnowledgeBaseParserConfig;
import io.agentbase.enums.KnowledgeBaseDocumentParser;
kb.createDocument(base.getId(), "<xlsxFileId>",
null, null, null, null, null, // bucketId / name / documentTag / source / externalItemId
ParserId.SHEET,
new KnowledgeBaseParserConfig().setDocumentParser(KnowledgeBaseDocumentParser.TEXT),
null); // metadatafrom agentbase.enums.parser_id import ParserId
kb.create_document(
knowledge_base_id=base['$id'],
file_id='<xlsxFileId>',
parser_id=ParserId.SHEET,
parser_config={'documentParser': 'text'}) # 逐 Sheet 提取结构化文本;图表密集用 vlm / mineruimport "agentbase-go-sdk/models"
_, err := kb.CreateDocument(base.Id, "<xlsxFileId>",
kb.WithCreateDocumentParserId("sheet"),
kb.WithCreateDocumentParserConfig(models.KnowledgeBaseParserConfig{DocumentParser: "text"}))
// 图表密集型工作簿:DocumentParser 用 "vlm" / "mineru"(每个目标 Sheet 渲染为临时 PDF)curl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/kb_product_docs/documents" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"fileId":"<xlsxFileId>","parserId":"sheet","parserConfig":{"documentParser":"text"}}'
# Excel 继承/指定 general、title、regex 会在摄取时返回 400;smart 自动解析为 sheet批量删除文档(2.8.0)
knowledgeBases.deleteDocuments({ knowledgeBaseId, documentIds, versionId })(versionId 可选) 一次请求删除多个文档,单批最多 50 个;成功返回 204。请求先做预检:所有 ID 必须属于该库(传入 versionId 时须属于该可写 DRAFT 版本),预检失败则一个都不会删。删除按请求顺序执行;若中途外部存储或并发失败,重新拉取列表、仅重试仍存在的 ID。需要 knowledgebases.write scope。版本化激活后写路径必须携带 versionId。
- Node.js(Server)
- REST(curl)
await kb.deleteDocuments({
knowledgeBaseId: base.$id,
documentIds: ['doc_001', 'doc_002'] // 单批最多 50 个
});curl -sS -X DELETE "$APPBASE_ENDPOINT/knowledgebases/kb_product_docs/documents" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"documentIds":["doc_001","doc_002"]}' # 数组最多 50 个;可带 versionId
# 204 No Content;预检失败不删除任何文档索引输出语言与嵌入输入上限(2.7.0)
输出语言:建库 / 改库时用
indexingDefaults保存 GraphRAG / RAPTOR / Wiki 共享的 Chat LLM 配置;各能力的updateIndexCapability配置里config.language控制生成输出语言——auto(默认,按源内容检测)/zh/en/ja,显式值覆盖检测。调用示例见 wiki.md「能力配置与构建」。嵌入输入上限:LLM Gateway Provider 的
maxInputTokens会成为 Wiki projection 的有效 embedding 输入上限——索引器只截断 embedding 投影并按上限打包 batch,不修改 canonical Wiki 内容;null表示不限。
语雀个人授权与团队同步
个人语雀授权和导入需要当前控制台用户身份,不能用项目 API 密钥或普通终端用户会话替代。目标环境须配置语雀授权能力;仅支持特定企业语雀域名,请向环境管理员确认。
以下示例使用 Console Python SDK。请使用对目标项目有知识库写权限的控制台用户会话签发的短期 JWT,并确认该会话仍有效;客户端指定目标项目、admin 模式和该 JWT,不同时附带其他已生效的 Cookie。首次授权时按提示在浏览器完成授权;会话、项目、知识库和用户须保持一致。启用版本管理时填写实际草稿 ID,未启用时设为空字符串。
- Python
from getpass import getpass
from agentbase_console.client import Client
from agentbase_console.services.knowledge_bases import KnowledgeBases
client = (Client().set_endpoint('<ENDPOINT>/v1').set_project('<PROJECT_ID>')
.set_mode('admin').set_jwt(getpass('Console user JWT: ')))
kb = KnowledgeBases(client)
knowledge_base_id = '<KNOWLEDGE_BASE_ID>'
draft_version_id = '<DRAFT_VERSION_ID>'
authorization = kb.create_yuque_o_auth_session(knowledge_base_id=knowledge_base_id)
if not authorization['authorized']:
print(authorization['authorizeUrl'])
input('Complete authorization in your browser, then press Enter: ')
session = kb.get_yuque_o_auth_session(
knowledge_base_id=knowledge_base_id, session_id=authorization['sessionId'])
if not session['authorized']:
raise RuntimeError('Yuque authorization is not complete')
result = kb.create_yuque_documents(
knowledge_base_id=knowledge_base_id, session_id=authorization['sessionId'],
urls=['<SUPPORTED_YUQUE_DOCUMENT_URL>'], version_id=draft_version_id or None)
for item in result.results:
print(item.url, item.status, item.error or '')
if result.failed:
raise RuntimeError(f'{int(result.failed)} document(s) failed to import')团队数据源同步
以下示例使用已创建的团队数据源和具有 knowledgebases.write 权限的服务端客户端 kb。请替换实际知识库、数据源和草稿 ID;未启用版本管理时将 draftVersionId 设为空字符串,或在 REST 请求中省略 versionId。
- Node.js(Server)
- REST(curl)
const knowledgeBaseId = '<knowledgeBaseId>';
const dataSourceId = '<dataSourceId>';
const draftVersionId = '<DRAFT_VERSION_ID>';
const sync = await kb.createDataSourceSync({
knowledgeBaseId,
dataSourceId,
...(draftVersionId ? { versionId: draftVersionId } : {})
});printf 'header = "X-Appwrite-Key: %s"\n' "$APPBASE_API_KEY" | \
curl --config - -X POST "$APPBASE_ENDPOINT/knowledgebases/<knowledgeBaseId>/datasources/<dataSourceId>/syncs" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H 'Content-Type: application/json' -d '{"versionId":"<DRAFT_VERSION_ID>"}'全量重建
改库级解析配置不会重写历史 chunk;把全部就绪文档有界分批重新入队摄取用 createReindex(返回 202,不改变 embeddingModel),nextCursor 非 null 时携带游标继续下一批。Web 面无此能力。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
let res = await kb.createReindex({ knowledgeBaseId: base.$id, limit: 50 });
while (res.nextCursor) { // 有界分批:继续入队直至 nextCursor 为 null
res = await kb.createReindex({ knowledgeBaseId: base.$id, limit: 50, cursor: res.nextCursor });
}var res = kb.createReindex(base.getId(), 50L, null, null); // 位置参数:limit / cursor / idempotencyKey
while (res.getNextCursor() != null) { // 有界分批:继续入队直至 nextCursor 为 null
res = kb.createReindex(base.getId(), 50L, res.getNextCursor(), null);
}
// 202 返回 queued / skipped / failed / nextCursorres = kb.create_reindex(knowledge_base_id=base['$id'], limit=50)
while res['nextCursor']: # 有界分批:继续入队直至 nextCursor 为 null
res = kb.create_reindex(knowledge_base_id=base['$id'], limit=50, cursor=res['nextCursor'])res, err := kb.CreateReindex(base.Id, kb.WithCreateReindexLimit(50))
for res.NextCursor != "" { // 有界分批:继续入队直至 nextCursor 为 null
res, err = kb.CreateReindex(base.Id,
kb.WithCreateReindexLimit(50), kb.WithCreateReindexCursor(res.NextCursor))
}
// 202:queued / skipped / failed / nextCursorcurl -sS -X POST "$APPBASE_ENDPOINT/knowledgebases/kb_product_docs/reindex" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" -H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"limit":50,"idempotencyKey":"idem-reindex-01"}'
# 202:queued / skipped / failed / nextCursor;nextCursor 非 null 时携带它继续调用