Praxis文档
控制台
知识库

批量

请求字段、响应对象和当前限制。

快速开始：官方 Python SDK

基础地址与鉴权

路径中的 ID 使用已有资源的 ID。示例中的环境变量由调用者设置。

创建文件批次

POST /knowledge/v1/vector_stores/{vector_store_id}/file_batches

批量添加已有 File 并异步入库。file_ids 与 files 必须且只能提供一个；files 支持逐文件设置。已有附件直接复用。使用返回的批次 id 查询进度。

参数

名称位置与类型说明
vector_store_idpath: string必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1

请求体

file_ids 与 files 必须且只能提供一个。已有文件直接复用，不修改属性或分段策略。

字段类型说明
(1).file_idsstring[]必填; 使用共同属性和分段设置的已有 File ID 列表。file_ids 与 files 二选一。; 最少条数: 1; 最多条数: 500
(1).attributesobject / null可选; 用于每个新附件的搜索筛选属性；省略或 null 表示不设置。
(1).chunking_strategyobject / object可选; auto 等同于每段 800 token、重叠 400 token。; 默认: {"type":"auto"}
(1).chunking_strategy (1).type"auto"必填; auto 使用默认静态分段：800 个估算 token，重叠 400 个。
(1).chunking_strategy (2).type"static"必填; static 表示使用显式分段大小与重叠设置。
(1).chunking_strategy (2).staticobject必填; 以估算 token 数表示的分段大小与重叠限制。
(1).chunking_strategy (2).static.max_chunk_size_tokensinteger必填; 每段的估算 token 数。; 最小: 100; 最大: 4096
(1).chunking_strategy (2).static.chunk_overlap_tokensinteger必填; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048
(2).filesobject[]必填; 分别指定属性和分段设置的附件列表；忽略顶层 attributes 与 chunking_strategy。; 最少条数: 1; 最多条数: 500
(2).files[].file_idstring必填; 上传文件返回的已有源 File ID；文件必须对调用方可见。; 最短字符数: 1
(2).files[].attributesobject可选; 用于搜索筛选的文件属性。最多 16 个键，键最多 64 字符，字符串值最多 512 字符。; 最多键数: 16; 键最多 64 字符; 值: string / number / boolean
(2).files[].chunking_strategyobject / object可选; auto 等同于每段 800 token、重叠 400 token。; 默认: {"type":"auto"}
(2).files[].chunking_strategy (1).type"auto"必填; auto 使用默认静态分段：800 个估算 token，重叠 400 个。
(2).files[].chunking_strategy (2).type"static"必填; static 表示使用显式分段大小与重叠设置。
(2).files[].chunking_strategy (2).staticobject必填; 以估算 token 数表示的分段大小与重叠限制。
(2).files[].chunking_strategy (2).static.max_chunk_size_tokensinteger必填; 每段的估算 token 数。; 最小: 100; 最大: 4096
(2).files[].chunking_strategy (2).static.chunk_overlap_tokensinteger必填; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048
(2).attributesJSON可选; 不生效: 使用 files 时不生效。
(2).chunking_strategyJSON可选; 不生效: 使用 files 时不生效。

请求示例

curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/file_batches" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"file_ids\":[\"${FILE_ID}\"]}"

响应

HTTP 200

字段类型说明
idstring必有; 资源 ID。; 最短字符数: 1
object"vector_store.files_batch"必有; 对象标记；vector_store.files_batch 表示批量附件。
vector_store_idstring必有; 资源 ID。; 最短字符数: 1
status"in_progress" / "completed" / "cancelled" / "failed"必有; cancelled 表示批次已取消；否则 in_progress 表示仍有成员入库中，failed 表示入库结束且有失败成员，completed 表示无入库中或失败成员。取消终态批次不会改变它。
file_countsobject必有; 仍属于该库或批次的附件数量，按入库状态分组。
file_counts.in_progressinteger必有; 等待或正在入库的文件数。; 最小: 0
file_counts.completedinteger必有; 已完成入库的文件数。; 最小: 0
file_counts.failedinteger必有; 入库失败的文件数。; 最小: 0
file_counts.cancelledinteger必有; 因批次取消而停止入库的文件数。; 最小: 0
file_counts.totalinteger必有; 全部入库状态的附件总数。; 最小: 0
created_atinteger必有; Unix 时间戳，单位秒。

错误码与错误对象

读取文件批次

GET /knowledge/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}

读取此知识库中创建的批次，包括当前状态和文件计数。使用创建批次返回的 id 监测入库结果。

参数

名称位置与类型说明
vector_store_idpath: string必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1
batch_idpath: string必填；此知识库创建批次时返回的文件批次 ID。 最短字符数: 1

请求示例

curl -X GET "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/file_batches/${BATCH_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

响应

HTTP 200

字段类型说明
idstring必有; 资源 ID。; 最短字符数: 1
object"vector_store.files_batch"必有; 对象标记；vector_store.files_batch 表示批量附件。
vector_store_idstring必有; 资源 ID。; 最短字符数: 1
status"in_progress" / "completed" / "cancelled" / "failed"必有; cancelled 表示批次已取消；否则 in_progress 表示仍有成员入库中，failed 表示入库结束且有失败成员，completed 表示无入库中或失败成员。取消终态批次不会改变它。
file_countsobject必有; 仍属于该库或批次的附件数量，按入库状态分组。
file_counts.in_progressinteger必有; 等待或正在入库的文件数。; 最小: 0
file_counts.completedinteger必有; 已完成入库的文件数。; 最小: 0
file_counts.failedinteger必有; 入库失败的文件数。; 最小: 0
file_counts.cancelledinteger必有; 因批次取消而停止入库的文件数。; 最小: 0
file_counts.totalinteger必有; 全部入库状态的附件总数。; 最小: 0
created_atinteger必有; Unix 时间戳，单位秒。

错误码与错误对象

取消文件批次

POST /knowledge/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel

只取消处理中的批次和文件。已完成、失败或已取消的批次原样返回（200，幂等），计数不变。

参数

名称位置与类型说明
vector_store_idpath: string必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1
batch_idpath: string必填；此知识库创建批次时返回的文件批次 ID。 最短字符数: 1

请求示例

curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/file_batches/${BATCH_ID}/cancel" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

响应

HTTP 200

字段类型说明
idstring必有; 资源 ID。; 最短字符数: 1
object"vector_store.files_batch"必有; 对象标记；vector_store.files_batch 表示批量附件。
vector_store_idstring必有; 资源 ID。; 最短字符数: 1
status"in_progress" / "completed" / "cancelled" / "failed"必有; cancelled 表示批次已取消；否则 in_progress 表示仍有成员入库中，failed 表示入库结束且有失败成员，completed 表示无入库中或失败成员。取消终态批次不会改变它。
file_countsobject必有; 仍属于该库或批次的附件数量，按入库状态分组。
file_counts.in_progressinteger必有; 等待或正在入库的文件数。; 最小: 0
file_counts.completedinteger必有; 已完成入库的文件数。; 最小: 0
file_counts.failedinteger必有; 入库失败的文件数。; 最小: 0
file_counts.cancelledinteger必有; 因批次取消而停止入库的文件数。; 最小: 0
file_counts.totalinteger必有; 全部入库状态的附件总数。; 最小: 0
created_atinteger必有; Unix 时间戳，单位秒。

错误码与错误对象

列出批次文件

GET /knowledge/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/files

列出指定批次仍在库中的附件，默认最新附件在前。使用批次创建返回的 id；?filter=failed 查看失败文件，last_id 可作为下一页 after。

参数

名称位置与类型说明
vector_store_idpath: string必填；创建或列表返回的知识库 ID；不要使用显示名称。 最短字符数: 1
batch_idpath: string必填；此知识库创建批次时返回的文件批次 ID。 最短字符数: 1
afterquery: string上一页的 ID 游标。 最短字符数: 1
beforequery: string返回此 ID 之前的条目。 最短字符数: 1
limitquery: integer每页条数。 最小: 1; 最大: 100; 默认: 20
orderquery: "asc" / "desc"知识库和文件默认按创建时间降序；分段默认按序号升序。 默认: "desc"
filterquery: "in_progress" / "completed" / "failed" / "cancelled"in_progress 表示等待或正在入库；completed 表示可检索；failed 表示入库失败；cancelled 表示批次取消已停止入库。省略时包含全部状态。

请求示例

curl -X GET "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/file_batches/${BATCH_ID}/files" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"

响应

HTTP 200

字段类型说明
object"list"必有; 对象标记；list 表示游标分页集合。
dataobject[]必有; 按请求顺序返回的当前页条目。
data[].idstring必有; 与源文件相同的 ID。; 最短字符数: 1
data[].object"vector_store.file"必有; 对象标记；vector_store.file 表示知识库中的附件。
data[].vector_store_idstring必有; 资源 ID。; 最短字符数: 1
data[].status"in_progress" / "completed" / "cancelled" / "failed"必有; in_progress 表示等待或正在入库；completed 表示可检索；failed 表示入库失败；cancelled 表示批次取消已停止入库。
data[].last_errorobject / null必有; 入库失败详情；未失败、成功完成或重新入库时为 null。
data[].last_error (1).code"server_error" / "unsupported_file" / "invalid_file"必有; unsupported_file 表示不支持的文件类型；invalid_file 表示加密、空文件或超过解析 token 上限；server_error 表示其它入库失败或超过截止时间。
data[].last_error (1).messagestring必有; 与 code 对应的入库失败说明。
data[].usage_bytesinteger必有; 完成后计入源文件字节数；处理中、失败或已取消时为零。; 最小: 0
data[].created_atinteger必有; Unix 时间戳，单位秒。
data[].chunking_strategyobject / object必有; 此附件已保存的分段策略；auto 输入返回为具体 static 设置。
data[].chunking_strategy (1).type"static"必有; static 表示使用显式分段大小与重叠设置。
data[].chunking_strategy (1).staticobject必有; 以估算 token 数表示的分段大小与重叠限制。
data[].chunking_strategy (1).static.max_chunk_size_tokensinteger必有; 每段的估算 token 数。; 最小: 100; 最大: 4096
data[].chunking_strategy (1).static.chunk_overlap_tokensinteger必有; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048
data[].chunking_strategy (2).type"other"必有
data[].attributesobject / null必有; 用于搜索筛选的文件属性；null 表示未设置。
data[].praxisobject可选; 原生入库进度与源文件统计。
data[].praxis.stage"queued" / "parse" / "chunk" / "embed" / "index" / null必有; queued 表示等待；parse 提取文本；chunk 划分分段；embed 生成向量；index 建立检索索引。null 表示入库已不在进行中。
data[].praxis.deadline_atinteger / null必有; 入库截止的 Unix 秒时间戳；到点仍未完成的入库转为失败。
data[].praxis.filenamestring必有; File 服务返回的源文件名。
data[].praxis.bytesinteger必有; 源文件字节数。; 最小: 0
data[].praxis.pagesinteger / null必有; 成功入库后的解析页数；成功结果保存前为 null。
data[].praxis.chunk_countinteger必有; 已完成入库的分段数；完成前、失败或取消后为零。; 最小: 0
first_idstring / null必有; 本页首项的 ID；空页为 null。
last_idstring / null必有; 本页末项的 ID，可作为 after 继续查询；空页为 null。
has_moreboolean必有; 当前游标范围内，本页之后是否还有条目。

错误码与错误对象

文件

请求字段、响应对象和当前限制。

搜索

请求字段、响应对象和当前限制。

导出
本页 Markdown本节 Markdown整本 PDF

本页内容

创建文件批次参数请求体请求示例响应读取文件批次参数请求示例响应取消文件批次参数请求示例响应列出批次文件参数请求示例响应