知识存储（RAG）服务HTTP JSON API 接口参考 - 表格存储

通过 HTTP JSON 接口直接调用知识存储（RAG）服务，适用于需要直接 HTTP 调用的场景。

知识库管理

CreateKnowledgeBase

创建一个新的知识库。系统自动在 Tablestore 中创建对应的 Document 表、Chunk 表和索引表。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）。字母开头，仅允许字母、数字和下划线，长度 1–64 字符，不可重复
`description`	string	知识库描述，最大 4KB
`subspace`	boolean	是否开启子空间。默认为 false，开启后所有文档操作和检索必须指定 subspace 字段。创建后不可修改
`tags`	list<string>	标签列表，总长度不超过 4KB
`metadata`	list<object>	元数据字段定义，详见下方说明
`embeddingConfiguration`	object	Embedding 配置，创建后不可修改。不传时默认使用百炼 `text-embedding-v4`（1024 维）
`retrievalConfiguration`	object	默认检索配置。Retrieve 接口不传配置时使用此处的设定。创建后可通过 UpdateKnowledgeBase 修改

metadata 字段定义

每个元素包含 name（字段名）和 type（字段类型）。

定义项	说明
支持的类型	`string`、`long`、`double`、`boolean`、`date`、`string_list`、`long_list`、`double_list`、`boolean_list`、`date_list`
字段名	最大 128 字符，不能包含 `.`
字段数量	最多 200 个
保留字段	`_uid`、`_id`、`_type`、`_all`、`_parent`、`_routing`、`_index`、`_size`、`_timestamp`、`_ttl`、`_score`

重要

metadata 字段定义创建后不可增删。创建前应梳理所有可能用于过滤检索结果的维度，一次性定义完整。

embeddingConfiguration

参数	类型	说明
`provider`	string	模型提供方。默认为 `bailian`（百炼内置），也支持 `custom`（自定义）
`model`	string	模型名称。默认为 `text-embedding-v4`，百炼还支持 `text-embedding-v3`
`dimension`	int	向量维度。默认为 1024
`apiKey`	string	仅 `custom` 模式需要
`url`	string	仅 `custom` 模式需要，需提前联系表格存储注册

retrievalConfiguration

参数	类型	说明
`searchType`	list<string>	检索类型。默认为 `["DENSE_VECTOR", "FULL_TEXT"]`
`denseVectorSearchConfiguration.numberOfResults`	int	向量检索返回数量。默认为 20
`fullTextSearchConfiguration.numberOfResults`	int	全文检索返回数量。默认为 20
`rerankingConfiguration.type`	string	Rerank 类型：`RRF`、`WEIGHT` 或 `MODEL`。默认为 `WEIGHT`
`rerankingConfiguration.numberOfResults`	int	Rerank 后返回的结果数。默认为 20
`weightConfiguration.denseVectorSearchWeight`	double	向量检索加权比例。默认为 0.7
`weightConfiguration.fullTextSearchWeight`	double	全文检索加权比例。默认为 0.3
`rrfConfiguration.denseVectorSearchWeight`	double	RRF 模式下的向量检索权重。默认为 1.0
`rrfConfiguration.fullTextSearchWeight`	double	RRF 模式下的全文检索权重。默认为 1.0
`rrfConfiguration.k`	int	RRF 算法参数。默认为 60，必须大于 0
`modelConfiguration.provider`	string	Rerank 模型提供方。默认 `bailian`，当前仅支持百炼
`modelConfiguration.model`	string	Rerank 模型名称。默认 `gte-rerank-v2`（新加坡地域默认`qwen3-rerank`）

完整的检索配置说明参见检索和排序。

请求示例

{
  "knowledgeBaseName": "product_docs_kb",
  "description": "产品文档知识库",
  "subspace": true,
  "tags": ["产品", "文档"],
  "metadata": [
    {"name": "author", "type": "string"},
    {"name": "date", "type": "date"},
    {"name": "score", "type": "double"}
  ],
  "embeddingConfiguration": {
    "provider": "bailian",
    "model": "text-embedding-v4",
    "dimension": 1024
  },
  "retrievalConfiguration": {
    "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
    "denseVectorSearchConfiguration": {"numberOfResults": 10},
    "fullTextSearchConfiguration": {"numberOfResults": 10},
    "rerankingConfiguration": {
      "type": "RRF",
      "numberOfResults": 5,
      "rrfConfiguration": {
        "denseVectorSearchWeight": 0.6,
        "fullTextSearchWeight": 0.4,
        "k": 60
      }
    }
  }
}

正常响应

{"code": "SUCCESS", "data": {}, "message": "succeed"}

UpdateKnowledgeBase

更新知识库的描述、标签或检索配置。description、tags、retrievalConfiguration 至少填一个。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）
`description`	string	更新描述信息，最大 4KB
`tags`	list<string>	更新标签
`retrievalConfiguration`	object	更新默认检索配置

说明

description、tags、retrievalConfiguration 至少填一个，否则报错。

请求示例

{
  "knowledgeBaseName": "product_docs_kb",
  "description": "更新后的描述",
  "tags": ["上线"]
}

正常响应

{"code": "SUCCESS", "data": {}, "message": "succeed"}

DescribeKnowledgeBase

查询指定知识库的完整配置。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）

响应字段

字段	类型	说明
`knowledgeBaseName`	string	知识库名称
`description`	string	知识库描述
`tags`	list<string>	标签列表
`subspace`	boolean	是否开启子空间
`createdAt`	int	创建时间戳（毫秒）
`updatedAt`	int	更新时间戳（毫秒）
`metadata`	list<object>	元数据字段定义
`embeddingConfiguration`	object	Embedding 配置
`retrievalConfiguration`	object	检索配置

响应示例

{
  "code": "SUCCESS",
  "data": {
    "knowledgeBaseName": "product_docs_kb",
    "description": "产品文档知识库",
    "tags": ["产品", "文档"],
    "subspace": true,
    "metadata": [{"name": "author", "type": "string"}],
    "createdAt": 1774494642525,
    "updatedAt": 1774494642525,
    "embeddingConfiguration": {
      "provider": "bailian",
      "model": "text-embedding-v4",
      "dimension": 1024
    },
    "retrievalConfiguration": {
      "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
      "denseVectorSearchConfiguration": {"numberOfResults": 20},
      "fullTextSearchConfiguration": {"numberOfResults": 20},
      "rerankingConfiguration": {
        "type": "WEIGHT",
        "numberOfResults": 20,
        "weightConfiguration": {
          "denseVectorSearchWeight": 0.7,
          "fullTextSearchWeight": 0.3
        }
      }
    }
  },
  "message": "succeed"
}

ListKnowledgeBase

分页查询当前 Project 下的所有知识库。

请求参数

参数	类型	说明
`maxResults`	int	返回数量。默认为 10，最大 100
`nextToken`	string	翻页 token，首次请求不传

响应字段

字段	类型	说明
`knowledgeBases`	list<object>	知识库列表，每项含 `knowledgeBaseName`、`description`、`subspace`、`tags`、`createdAt`、`updatedAt`
`nextToken`	string	翻页 token，为空表示已到最后一页

请求示例

{"maxResults": 10}

DeleteKnowledgeBase

删除指定的知识库及其下所有 Document 和 Chunk 数据。

重要

此操作不可逆。删除知识库会同时删除其下所有 Document 和 Chunk 数据。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）

请求示例

{"knowledgeBaseName": "product_docs_kb"}

文档管理

AddDocuments

将文档导入知识库。系统自动完成解析、切片、向量化和索引构建。相同 ossKey 重复上传会覆盖原有文档。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）
`subspace`	string	子空间名称，最大 128 字符。开启 subspace 时必填
`documents`	list<object>	文档列表（必填）。单次最多 10 个
`documents[].filePath`	string	本地文件路径。upload_documents 时必填
`documents[].ossKey`	string	OSS 文件或目录路径，长度 1–256。add_documents 时必填
`documents[].metadata`	object	文档元数据，必须与知识库定义的 metadata schema 一致
`documents[].inclusionFilters`	list<string>	包含过滤器，支持首尾 `` 通配符（如`.pdf`），用于 OSS 目录扫描
`documents[].exclusionFilters`	list<string>	排除过滤器，支持首尾 `` 通配符（如`draft*`）

响应字段

字段	类型	说明
`documentDetails`	list<object>	每个文档的处理结果
`documentDetails[].docId`	string	文档 ID
`documentDetails[].ossKey`	string	文档 OSS 路径
`documentDetails[].status`	string	`succeed` 或 `failed`
`documentDetails[].failureReason`	string	失败原因（仅 failed 时）

请求示例

{
  "knowledgeBaseName": "product_docs_kb",
  "subspace": "default",
  "documents": [
    {
      "ossKey": "oss://example-bucket/docs/manual.pdf",
      "metadata": {"author": "张三", "date": "2026-01-22 10:00:59"}
    }
  ]
}

响应示例

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

说明

HTTP 200 + code: SUCCESS 不代表所有文档都处理成功。必须逐个检查 documentDetails 中每个文档的 status 字段。status: "succeed" 表示上传任务已接收，并非索引完成。

GetDocument

查询指定文档的详细信息。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）
`subspace`	string	子空间名称。开启 subspace 时必填
`docId`	string	文档 ID。与 `ossKey` 二选一
`ossKey`	string	OSS 文件路径。与 `docId` 二选一

响应字段

字段	类型	说明
`docId`	string	文档 ID
`ossKey`	string	OSS 路径
`subspace`	string	子空间
`chunkNum`	int	切片数量
`status`	string	文档状态：`Pending`/`Indexing`/`Completed`/`Failed`/`Deleting`
`createdAt`	int	创建时间戳
`updatedAt`	int	更新时间戳
`eTag`	string	文档 eTag
`failedDetails`	string	失败原因（仅 Failed 时）
`metadata`	object	文档元数据

ListDocuments

分页查询知识库下的文档列表。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）
`subspace`	list<string>	子空间列表，最多 10 个。开启 subspace 时必填
`maxResults`	int	返回数量。默认为 10，最大 1000
`nextToken`	string	翻页 token

UpdateDocument

更新指定文档的 metadata。仅 Completed 状态的文档可更新。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）
`subspace`	string	子空间名称。开启 subspace 时必填
`ossKey`	string	文档 OSS 路径。与 `docId` 二选一
`docId`	string	文档 ID。与 `ossKey` 二选一
`metadata`	map	新的 metadata（必填）

响应字段

字段	类型	说明
`docId`	string	文档 ID
`ossKey`	string	OSS 路径
`updatedAt`	long	更新时间戳
`updateStatus`	string	`NO_OP` 或 `UPDATED`

说明

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

DeleteDocuments

删除指定的文档及其所有切片。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）
`subspace`	string	子空间名称。开启 subspace 时必填
`documents`	list<object>	要删除的文档列表（必填）
`documents[].docId`	string	文档 ID。与 `ossKey` 二选一
`documents[].ossKey`	string	OSS 路径。与 `docId` 二选一

检索

Retrieve

在知识库中执行语义检索，返回与查询文本最相关的切片列表。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）
`subspace`	list<string>	子空间列表，最多 32 个。开启 subspace 时必填
`retrievalQuery`	object	检索查询（必填）
`retrievalQuery.type`	string	查询类型（必填）。当前仅支持 `TEXT`
`retrievalQuery.text`	string	检索文本（必填）。最长 128 字符
`retrievalConfiguration`	object	检索配置，不传时使用知识库级别配置或系统默认值
`retrievalConfiguration.searchType`	list<string>	检索类型
`retrievalConfiguration.denseVectorSearchConfiguration.numberOfResults`	int	向量检索返回数量，最大 100
`retrievalConfiguration.fullTextSearchConfiguration.numberOfResults`	int	全文检索返回数量，最大 100
`retrievalConfiguration.rerankingConfiguration`	object	Rerank 配置
`retrievalConfiguration.filter`	object	元数据过滤条件

检索配置优先级

Retrieve 接口的检索配置（retrievalConfiguration）按以下优先级确定最终生效的参数：

优先级	来源	说明
1（最高）	Retrieve 接口参数	本次请求中传入的 `retrievalConfiguration`，仅对当次生效
2	知识库级别配置	创建知识库时设定，可通过 UpdateKnowledgeBase 随时修改
3（最低）	系统默认值	向量 + 全文混合检索，WEIGHT 加权融合（向量 0.7 : 全文 0.3），返回 20 条结果

最简单的检索请求只需传 knowledgeBaseName 和 retrievalQuery，系统自动使用知识库配置或默认值。

filter支持的算子

比较算子

算子	符号	说明	适用类型
`equals`	=	等于	所有类型
`notEquals`	≠	不等于	所有类型
`greaterThan`	>	大于	long, double, date
`greaterThanOrEquals`	≥	大于等于	long, double, date
`lessThan`	<	小于	long, double, date
`lessThanOrEquals`	≤	小于等于	long, double, date

集合与匹配算子

算子	说明	适用类型
`in`	值在给定集合中	所有类型
`notIn`	值不在给定集合中	所有类型
`startsWith`	字符串前缀匹配	string
`stringContains`	字符串包含匹配	string
`listContains`	列表字段包含指定元素	list 类型

逻辑组合算子

算子	说明
`andAll`	所有条件同时满足
`orAll`	任一条件满足
`notAll`	所有条件都不满足

andAll、orAll和notAll支持嵌套，可构建复杂的组合过滤逻辑。

响应字段

字段	类型	说明
`retrievalResults`	list<object>	检索结果列表，按相关性得分降序排列
`retrievalResults[].docId`	string	所属文档 ID
`retrievalResults[].chunkId`	int	切片 ID
`retrievalResults[].ossKey`	string	所属文档 OSS 路径
`retrievalResults[].score`	float	相关性得分，越高越相关
`retrievalResults[].content`	string	切片原文内容
`retrievalResults[].subspace`	string	所属子空间
`retrievalResults[].metadata`	object	文档元数据

请求示例

{
  "knowledgeBaseName": "product_docs_kb",
  "subspace": ["default"],
  "retrievalQuery": {"type": "TEXT", "text": "产品的安装步骤是什么"},
  "retrievalConfiguration": {
    "searchType": ["DENSE_VECTOR", "FULL_TEXT"],
    "denseVectorSearchConfiguration": {"numberOfResults": 10},
    "fullTextSearchConfiguration": {"numberOfResults": 10},
    "rerankingConfiguration": {
      "type": "RRF",
      "numberOfResults": 5,
      "rrfConfiguration": {"denseVectorSearchWeight": 0.6, "fullTextSearchWeight": 0.4, "k": 60}
    },
    "filter": {
      "andAll": [
        {"greaterThanOrEquals": {"key": "score", "value": 60}}
      ]
    }
  }
}

响应示例

{
  "code": "SUCCESS",
  "data": {
    "retrievalResults": [
      {
        "ossKey": "oss://example-bucket/docs/manual.pdf",
        "docId": "96fb386e-...",
        "chunkId": 3,
        "subspace": "default",
        "score": 0.85,
        "content": "第一步：下载安装包...",
        "metadata": {"author": "张三", "category": "产品文档"}
      }
    ]
  },
  "message": "succeed"
}

切片管理

ListChunks

分页查询指定文档的切片列表。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）
`subspace`	string	子空间名称。开启 subspace 时必填
`docId`	string	文档 ID。与 `ossKey` 二选一
`ossKey`	string	OSS 路径。与 `docId` 二选一
`maxResults`	int	返回数量。默认为 10，最大 1000
`nextToken`	string	翻页 token

响应字段

字段	类型	说明
`chunkDetails[].subspace`	string	所属子空间
`chunkDetails[].chunkId`	int	切片 ID
`chunkDetails[].content`	string	切片内容
`chunkDetails[].title`	string	切片标题
`chunkDetails[].chunkType`	string	切片类型，如 `TEXT`
`chunkDetails[].status`	string	`active`（可检索）或 `inactive`（不可检索）
`chunkDetails[].docId`	string	所属文档 ID
`chunkDetails[].ossKey`	string	所属文档 OSS 路径
`chunkDetails[].createdAt`	int	创建时间戳
`chunkDetails[].updatedAt`	int	更新时间戳
`nextToken`	string	翻页 token，为空表示最后一页

UpdateChunks

批量更新切片的标题、内容或状态。

请求参数

参数	类型	说明
`knowledgeBaseName`	string	知识库名称（必填）
`subspace`	string	子空间名称。开启 subspace 时必填
`chunks`	list<object>	要更新的切片列表（必填）。单次最多 10 个
`chunks[].docId`	string	文档 ID。与 `ossKey` 二选一
`chunks[].ossKey`	string	OSS 路径。与 `docId` 二选一
`chunks[].chunkId`	int	切片 ID（必填）
`chunks[].title`	string	更新标题，最大 100 Token
`chunks[].content`	string	更新内容，最大 320 Token
`chunks[].status`	string	修改状态：`active`（可检索）或 `inactive`（不可检索）

响应说明

字段	类型	说明
`updateDetails[].docId`	string	文档 ID
`updateDetails[].ossKey`	string	OSS 路径
`updateDetails[].chunkId`	int	切片 ID
`updateDetails[].updateStatus`	string	`succeed` 或 `failed`
`updateDetails[].failureReason`	string	失败原因，仅 failed 时

请求示例

{
  "knowledgeBaseName": "product_docs_kb",
  "subspace": "default",
  "chunks": [
    {"ossKey": "oss://example-bucket/docs/manual.pdf", "chunkId": 0, "status": "inactive"},
    {"ossKey": "oss://example-bucket/docs/manual.pdf", "chunkId": 1, "title": "更新后的标题", "content": "更新后的内容"}
  ]
}

常见错误码

错误码	含义	常见原因
`INVALID_PARAMETER`	参数校验失败	字段类型不匹配、超出长度限制、缺少必填字段
`NOT_FOUND`	资源不存在	知识库名称拼写错误或已被删除
`BAD_REQUEST`	请求格式错误	JSON 格式不合法
`VALIDATION_ERROR`	业务校验失败	RRF 的 k 值为 0、检索参数不合法

说明

AddDocuments、DeleteDocuments 和 UpdateChunks 的响应中，HTTP 200 + code: SUCCESS 不代表所有条目都处理成功。每个条目有独立的 status 字段，必须逐个检查。