通过数据接口管理知识库文档

获取企业知识空间版本

使用上传接口前，建议先查询当前运行的企业知识空间版本，以确定是否支持省略doc_id：

curl -sS -u '<username>:<password>' \
  'http://<opensearch-host>:<port>/_plugins/_polar_rag/_version'

当安装包携带1.0.6发布标识时，响应形如：

{
  "version": "t-polardb-rag-1.0.6-20260814175603.al8.x86_64"
}

• 确认为1.0.6或更高版本：上传支持缺省doc_id，推荐缺省。

• 低于1.0.6：必须显式提供doc_id。

• 返回404、unknown、仅有OpenSearch插件描述版本（例如3.3.2-SNAPSHOT）或无法确认企业知识空间发布版本：按旧版本兼容处理，显式提供doc_id。

Base URL

http://<opensearch-host>:<port>/_plugins/_polar_rag

接口详情中的路径均以/_plugins/_polar_rag开头，实际请求时请拼接实际的搜索节点地址。

认证与权限

如果服务启用了OpenSearch Security，请在开放空间（ACL Disabled）模式下的直连请求中请携带搜索节点的账号密码：

curl -u '<username>:<password>' ...

请求格式

时间字段使用ISO-8601 UTC字符串。

OSS路径填写规则

文档上传时需要填写oss_path，格式必须是：

oss://<bucket>/<object_key>

参数说明

示例

oss://xxx_bucket/docs/report.pdf

常见状态码

示例

• 常见错误响应：

  {
    "error_type": "invalid_parameter",
    "error": "kb_id is required"
  }

• 权限感知空间（ACL Enforced）误用直连接口时可能返回：

  {
    "error_type": "acl_context_required",
    "error": "Use the protected document endpoint"
  }

开放空间（ACL Disabled）

1. 将文件上传到当前空间可访问的OSS Bucket。

2. 查询企业知识空间版本；1.0.6及以上推荐省略doc_id，旧版本或版本不明确时显式提供。

3. 调用托管文档上传接口，保存响应中的document.doc_id。

4. 轮询文档状态至COMPLETED或FAILED，完成后再搜索；删除返回PROCESSING时继续查询删除任务。

权限感知空间（ACL Enforced）

通过PolarDB Agentic Server（MCP Server）完成资源发现、上传、状态查询、删除和搜索。MCP Server负责从认证会话生成可信ACL身份上下文。

上传单个文档

提交OSS中的文件进行解析、分块和索引。

批量上传文档

批量提交OSS文件进行解析、分块和索引，单次最多提交500个文档。从 1.0.6 版本起，每个元素的 doc_id 可以省略，并按省略文档 ID 时的生成规则（仅 1.0.6 及以上版本适用）分别生成。

• 请求地址：

  POST /_plugins/_polar_rag/spaces/{space_id}/managed_documents/_bulk
  Content-Type: application/json

• 请求示例：

  {
    "documents": [
      {
        "kb_id": "pkb-xxx",
        "oss_path": "oss://xxx_bucket/docs/report-1.pdf",
        "filename": "report-1.pdf",
        "file_type": "pdf",
        "file_md5": "replace_with_actual_file_md5_1",
        "file_size_bytes": 123456
      },
      {
        "doc_id": "customer_doc_002",
        "kb_id": "pkb-xxx",
        "oss_path": "oss://xxx_bucket/docs/report-2.docx",
        "filename": "report-2.docx",
        "file_type": "docx"
      }
    ]
  }

  说明

  示例中的replace_with_actual_file_md5_1为占位值，调用时请替换为对应OSS对象的实际MD5值，并保证file_size_bytes与该对象一致。

• 响应示例：

  {
    "total": 2,
    "documents": [
      {
        "success": true,
        "idempotent": false,
        "document": {
          "doc_id": "27b950f1-xxxx-xxxx-xxxx-145d2d1c4c7a",
          "space_id": "pks-xxx",
          "kb_id": "pkb-xxx",
          "oss_path": "oss://xxx_bucket/docs/report-1.pdf",
          "filename": "report-1.pdf",
          "status": "DISPATCHED"
        }
      },
      {
        "success": true,
        "idempotent": false,
        "document": {
          "doc_id": "customer_doc_002",
          "space_id": "pks-xxx",
          "kb_id": "pkb-xxx",
          "oss_path": "oss://xxx_bucket/docs/report-2.docx",
          "filename": "report-2.docx",
          "status": "DISPATCHED"
        }
      }
    ],
    "succeeded": 2,
    "failed": 0
  }

  批量请求中的文档逐条处理，单个文档失败不会回滚已成功提交的文档：

  • 失败数为0时返回HTTP 201。即使全部成功项均为幂等返回，整体仍返回201。

  • 失败数大于0时返回HTTP 200，包括部分失败和全部失败。

  • 请逐项检查success字段。对成功项请继续检查idempotent，并按上传单个文档的规则理解对应的document.status。

查询单个文档状态

• 请求地址：

  GET /_plugins/_polar_rag/documents/{doc_id}/status

• 处理中的响应示例：

  {
    "doc_id": "doc_12345678",
    "status": "CHUNKING",
    "chunk_count": 0,
    "created_at": "2026-04-21T10:00:00Z",
    "updated_at": "2026-04-21T10:01:00Z",
    "space_id": "pks-xxx",
    "kb_id": "pkb-xxx",
    "filename": "report.pdf",
    "submit_retry_count": 0,
    "task": {
      "task_id": "task_12345678",
      "taskd_task_id": "taskd_xxx",
      "task_status": "DISPATCHED",
      "retry_count": 0,
      "poll_error_count": 0,
      "dispatched_at": "2026-04-21T10:01:00Z"
    }
  }

• 处理完成的响应示例：

  {
    "doc_id": "doc_12345678",
    "status": "COMPLETED",
    "chunk_count": 15,
    "created_at": "2026-04-21T10:00:00Z",
    "updated_at": "2026-04-21T10:05:00Z",
    "completed_at": "2026-04-21T10:05:00Z"
  }

• 处理失败的响应示例：

  {
    "doc_id": "doc_12345678",
    "status": "FAILED",
    "chunk_count": 0,
    "created_at": "2026-04-21T10:00:00Z",
    "updated_at": "2026-04-21T10:02:00Z",
    "error_message": "TaskD processing failed"
  }

• 文档状态说明：

  状态	含义
  PENDING	已提交，等待派发。
  DISPATCHED	已派发给文档处理服务。
  CHUNKING	正在分块。
  INDEXING	正在写入索引。
  COMPLETED	处理完成，可以检索。
  FAILED	处理失败，详情请参见error_message。
  DELETING	正在删除。

批量查询文档状态

• 请求地址：

  POST /_plugins/_polar_rag/documents/_batch_status
  Content-Type: application/json

• 请求示例：

  {
    "doc_ids": ["doc_12345678", "doc_87654321"]
  }

• 响应示例：

  {
    "total": 2,
    "found": 2,
    "documents": [
      {
        "doc_id": "doc_12345678",
        "status": "CHUNKING",
        "chunk_count": 0,
        "space_id": "pks-xxx",
        "kb_id": "pkb-xxx",
        "filename": "report.pdf",
        "submit_retry_count": 0
      },
      {
        "doc_id": "doc_87654321",
        "status": "COMPLETED",
        "chunk_count": 15,
        "completed_at": "2026-04-21T10:05:00Z"
      }
    ]
  }

• 响应字段说明：

  字段	说明
  total	请求中的doc_id数量。
  found	实际查询到的文档数量。found可能小于total，表示部分文档ID不存在。
  documents	文档状态列表。

删除单个文档

删除指定企业知识空间中的托管文档。删除完成后，文档对应的索引数据将被清理，托管文档记录将被标记为已删除。

• 请求地址

  DELETE /_plugins/_polar_rag/spaces/{space_id}/managed_documents/{doc_id}

• 该接口不需要请求体。路径参数：

  参数	类型	必填	说明
  space_id	string	是	企业知识空间ID。
  doc_id	string	是	待删除的文档ID。

• 删除完成的响应示例：

  {
    "doc_id": "doc_12345678",
    "task_id": "task_12345678",
    "status": "COMPLETED",
    "error_message": null
  }

• 删除处理中的响应示例：

  {
    "doc_id": "doc_12345678",
    "task_id": "task_12345678",
    "status": "PROCESSING",
    "error_message": null
  }

• 响应中的status取值说明：

  状态	说明
  COMPLETED	文档删除完成。
  PROCESSING	删除任务仍在后台执行。
  FAILED	文档删除失败，具体原因请参见error_message。

查询删除任务

使用删除接口返回的task_id查询后台删除任务的状态。

• 请求地址：

  GET /_plugins/_polar_rag/delete_tasks/{task_id}

• 路径参数：

  参数	类型	必填	说明
  task_id	string	是	删除任务ID。

• 响应示例：

  {
    "task_id": "task_12345678",
    "task_type": "delete",
    "type": "doc_id",
    "target_id": "doc_12345678",
    "space_id": "pks-xxx",
    "status": "COMPLETED",
    "total_docs": 1,
    "deleted_docs": 1,
    "created_at": "2026-08-14T10:00:00Z",
    "completed_at": "2026-08-14T10:00:03Z"
  }

• 任务状态说明：

  状态	说明
  PENDING	删除任务已创建，等待执行。
  PROCESSING	正在删除。
  COMPLETED	删除完成。
  FAILED	删除失败。响应中可能包含error_message、failed_docs和failed_doc_ids字段。

  当任务状态为PENDING或PROCESSING时，请继续轮询，直到状态变为COMPLETED或FAILED。权限感知空间（ACL Enforced）的删除与任务查询应由MCP Server统一完成，不向终端客户暴露acl_context。