文档管理

请求参数

代码示例

resp = client.upload_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "filePath": "/home/user/docs/product_manual.pdf",
            "metadata": {"author": "张三", "category": "产品文档"}
        },
        {
            "filePath": "/home/user/docs/faq.docx",
            "metadata": {"author": "李四", "category": "FAQ"}
        }
    ]
})

resp = client.add_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "ossKey": "oss://example-bucket/docs/product_manual.pdf",
            "metadata": {"author": "张三"}
        }
    ]
})

resp = client.add_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {
            "ossKey": "oss://example-bucket/docs/",
            "inclusionFilters": ["*.pdf", "*.docx"],
            "exclusionFilters": ["*draft*"]
        }
    ]
})

响应说明

{
  "code": "SUCCESS",
  "data": {
    "documentDetails": [
      {"docId": "fc6ed97f-...", "status": "succeed", "ossKey": "oss://example-bucket/docs/product_manual.pdf"},
      {"docId": "940f2c5c-...", "status": "succeed", "ossKey": "oss://example-bucket/docs/faq.docx"}
    ]
  },
  "message": "succeed"
}

{
  "code": "SUCCESS",
  "data": {
    "documentDetails": [
      {"status": "failed", "failureReason": "Metadata field 'date' date string format is not supported", "ossKey": "oss://..."},
      {"status": "succeed", "ossKey": "oss://...", "docId": "940f2c5c-..."}
    ]
  },
  "message": "succeed"
}

注意事项

• HTTP 200 + code: SUCCESS 不代表所有文档都处理成功。必须逐个检查 documentDetails 中每个文档的 status 字段。

• status: "succeed" 表示上传任务已接收，并非索引完成。必须等到文档状态变为 Completed 才能被检索。

• 知识库开启 subspace 后必须传 subspace 参数，否则报 INVALID_PARAMETER。

• metadata 日期格式需使用支持的格式（如 yyyy-MM-dd HH:mm:ss），不支持的格式会导致文档 failed。

• 单次请求最多 10 个文档，单文件最大 50MB。

查询索引状态

文档上传后经过异步处理才能被检索。如需确认文档是否索引完成，建议采用指数退避轮询。

import time

def wait_for_document(client, kb_name, doc_id, max_interval=30):
    """指数退避轮询文档状态，等待索引完成。"""
    interval = 3
    while True:
        resp = client.get_document({
            "knowledgeBaseName": kb_name,
            "docId": doc_id
        })
        status = resp["data"][0]["status"]
        if status == "completed":
            print(f"索引完成，切片数: {resp['data'][0].get('chunkNum', 'N/A')}")
            return resp
        elif status == "failed":
            raise Exception(f"索引失败: {resp['data'][0].get('failedDetails')}")
        print(f"当前状态: {status}，{interval}s 后重试...")
        time.sleep(interval)
        interval = min(interval * 2, max_interval)

文档处理时间受文件大小、类型和数量影响，小文件通常几秒完成，大文件或批量导入可能需要数分钟。

请求参数

代码示例

resp = client.get_document({
    "knowledgeBaseName": "product_docs_kb",
    "docId": "fc6ed97f-..."
})

doc = resp["data"][0]
print(f"状态: {doc['status']}, 切片数: {doc.get('chunkNum', 'N/A')}")

响应说明

注意事项

同一个 ossKey 经历创建→删除→创建后，get_document 可能返回多条记录（包含历史记录）。根据 status 字段判断有效文档，取 Completed 状态的记录。

请求参数

代码示例

resp = client.list_documents({
    "knowledgeBaseName": "product_docs_kb",
    "maxResults": 20
})

for doc in resp["data"]["documentDetails"]:
    print(f"[{doc['status']}] {doc['ossKey']} (切片数: {doc.get('chunkNum', '-')})")

注意事项

subspace 参数支持多值列表，但最多 10 个，超过会报错。

请求参数

代码示例

resp = client.update_document({
    "knowledgeBaseName": "product_docs_kb",
    "docId": "fc6ed97f-...",
    "metadata": {"author": "张三", "category": "技术文档", "version": 2}
})

print(f"更新状态: {resp['data']['updateStatus']}")  # UPDATED 或 NO_OP

响应说明

注意事项

• metadata 采用覆盖式更新，传入的值会全量替换原有 metadata。如果只想更新一个字段，必须把所有字段都带上。

• 传入 "metadata": null 会清空所有 metadata。

• 不传 metadata 字段则保留原值。

• 限制：metadata 总大小（key + value）最大 4KB，字段数最多 200 个。

请求参数

代码示例

resp = client.delete_documents({
    "knowledgeBaseName": "product_docs_kb",
    "documents": [
        {"docId": "fc6ed97f-..."},
        {"ossKey": "oss://example-bucket/docs/faq.docx"}
    ]
})

# 逐个检查删除结果
for detail in resp["data"]["documentDetails"]:
    print(f"{detail['ossKey']}: {detail['status']}")

注意事项

同 AddDocuments，删除结果也需逐个检查 documentDetails 中每个文档的 status。