文件

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

添加文件

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

异步处理。重复加入同一文件返回已有记录，不应用新的属性或分段策略。

参数

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

请求体

字段	类型	说明
file_id	string	必填; 上传文件返回的已有源 File ID；文件必须对调用方可见。; 最短字符数: 1
attributes	object / null	可选; 新附件的搜索筛选属性；省略或 null 表示不设置。重复加入已有文件不改变属性。
chunking_strategy	object / object	可选; auto 等同于每段 800 token、重叠 400 token。; 默认: {"type":"auto"}
chunking_strategy (1).type	"auto"	必填; auto 使用默认静态分段：800 个估算 token，重叠 400 个。
chunking_strategy (2).type	"static"	必填; static 表示使用显式分段大小与重叠设置。
chunking_strategy (2).static	object	必填; 以估算 token 数表示的分段大小与重叠限制。
chunking_strategy (2).static.max_chunk_size_tokens	integer	必填; 每段的估算 token 数。; 最小: 100; 最大: 4096
chunking_strategy (2).static.chunk_overlap_tokens	integer	必填; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048

请求示例

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

响应

HTTP 200

字段	类型	说明
id	string	必有; 与源文件相同的 ID。; 最短字符数: 1
object	"vector_store.file"	必有; 对象标记；vector_store.file 表示知识库中的附件。
vector_store_id	string	必有; 资源 ID。; 最短字符数: 1
status	"in_progress" / "completed" / "cancelled" / "failed"	必有; in_progress 表示等待或正在入库；completed 表示可检索；failed 表示入库失败；cancelled 表示批次取消已停止入库。
last_error	object / null	必有; 入库失败详情；未失败、成功完成或重新入库时为 null。
last_error (1).code	"server_error" / "unsupported_file" / "invalid_file"	必有; unsupported_file 表示不支持的文件类型；invalid_file 表示加密、空文件或超过解析 token 上限；server_error 表示其它入库失败或超过截止时间。
last_error (1).message	string	必有; 与 code 对应的入库失败说明。
usage_bytes	integer	必有; 完成后计入源文件字节数；处理中、失败或已取消时为零。; 最小: 0
created_at	integer	必有; Unix 时间戳，单位秒。
chunking_strategy	object / object	必有; 此附件已保存的分段策略；auto 输入返回为具体 static 设置。
chunking_strategy (1).type	"static"	必有; static 表示使用显式分段大小与重叠设置。
chunking_strategy (1).static	object	必有; 以估算 token 数表示的分段大小与重叠限制。
chunking_strategy (1).static.max_chunk_size_tokens	integer	必有; 每段的估算 token 数。; 最小: 100; 最大: 4096
chunking_strategy (1).static.chunk_overlap_tokens	integer	必有; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048
chunking_strategy (2).type	"other"	必有
attributes	object / null	必有; 用于搜索筛选的文件属性；null 表示未设置。
praxis	object	可选; 原生入库进度与源文件统计。
praxis.stage	"queued" / "parse" / "chunk" / "embed" / "index" / null	必有; queued 表示等待；parse 提取文本；chunk 划分分段；embed 生成向量；index 建立检索索引。null 表示入库已不在进行中。
praxis.deadline_at	integer / null	必有; 入库截止的 Unix 秒时间戳；到点仍未完成的入库转为失败。
praxis.filename	string	必有; File 服务返回的源文件名。
praxis.bytes	integer	必有; 源文件字节数。; 最小: 0
praxis.pages	integer / null	必有; 成功入库后的解析页数；成功结果保存前为 null。
praxis.chunk_count	integer	必有; 已完成入库的分段数；完成前、失败或取消后为零。; 最小: 0

错误码与错误对象

列出文件

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

列出附件及入库状态，默认最新附件在前。使用 last_id 作为 after 继续查询；?filter=failed 筛选可重新入库的失败文件。

参数

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

请求示例

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

响应

HTTP 200

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

错误码与错误对象

读取文件

GET /knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}

使用添加附件或附件列表返回的 id 读取文件。可轮询此操作，直到 status 离开 in_progress 后确认入库结果。

参数

名称	位置与类型	说明
vector_store_id	path: string	必填；创建或列表返回的知识库 ID；不要使用显示名称。最短字符数: 1
file_id	path: string	必填；添加附件或附件列表返回的源 File ID。最短字符数: 1

请求示例

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

响应

HTTP 200

字段	类型	说明
id	string	必有; 与源文件相同的 ID。; 最短字符数: 1
object	"vector_store.file"	必有; 对象标记；vector_store.file 表示知识库中的附件。
vector_store_id	string	必有; 资源 ID。; 最短字符数: 1
status	"in_progress" / "completed" / "cancelled" / "failed"	必有; in_progress 表示等待或正在入库；completed 表示可检索；failed 表示入库失败；cancelled 表示批次取消已停止入库。
last_error	object / null	必有; 入库失败详情；未失败、成功完成或重新入库时为 null。
last_error (1).code	"server_error" / "unsupported_file" / "invalid_file"	必有; unsupported_file 表示不支持的文件类型；invalid_file 表示加密、空文件或超过解析 token 上限；server_error 表示其它入库失败或超过截止时间。
last_error (1).message	string	必有; 与 code 对应的入库失败说明。
usage_bytes	integer	必有; 完成后计入源文件字节数；处理中、失败或已取消时为零。; 最小: 0
created_at	integer	必有; Unix 时间戳，单位秒。
chunking_strategy	object / object	必有; 此附件已保存的分段策略；auto 输入返回为具体 static 设置。
chunking_strategy (1).type	"static"	必有; static 表示使用显式分段大小与重叠设置。
chunking_strategy (1).static	object	必有; 以估算 token 数表示的分段大小与重叠限制。
chunking_strategy (1).static.max_chunk_size_tokens	integer	必有; 每段的估算 token 数。; 最小: 100; 最大: 4096
chunking_strategy (1).static.chunk_overlap_tokens	integer	必有; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048
chunking_strategy (2).type	"other"	必有
attributes	object / null	必有; 用于搜索筛选的文件属性；null 表示未设置。
praxis	object	可选; 原生入库进度与源文件统计。
praxis.stage	"queued" / "parse" / "chunk" / "embed" / "index" / null	必有; queued 表示等待；parse 提取文本；chunk 划分分段；embed 生成向量；index 建立检索索引。null 表示入库已不在进行中。
praxis.deadline_at	integer / null	必有; 入库截止的 Unix 秒时间戳；到点仍未完成的入库转为失败。
praxis.filename	string	必有; File 服务返回的源文件名。
praxis.bytes	integer	必有; 源文件字节数。; 最小: 0
praxis.pages	integer / null	必有; 成功入库后的解析页数；成功结果保存前为 null。
praxis.chunk_count	integer	必有; 已完成入库的分段数；完成前、失败或取消后为零。; 最小: 0

错误码与错误对象

更新文件属性

POST /knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}

替换已有附件的搜索筛选属性，不重新入库。使用附件 id。请求体示例：{"attributes":{"category":"refund"}}；null 清空属性。

参数

名称	位置与类型	说明
vector_store_id	path: string	必填；创建或列表返回的知识库 ID；不要使用显示名称。最短字符数: 1
file_id	path: string	必填；添加附件或附件列表返回的源 File ID。最短字符数: 1

请求体

字段	类型	说明
attributes	object / null	可选; 替换全部搜索筛选属性；null 清空属性。

请求示例

curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/files/${FILE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"attributes\":{\"category\":\"refund\"}}"

响应

HTTP 200

字段	类型	说明
id	string	必有; 与源文件相同的 ID。; 最短字符数: 1
object	"vector_store.file"	必有; 对象标记；vector_store.file 表示知识库中的附件。
vector_store_id	string	必有; 资源 ID。; 最短字符数: 1
status	"in_progress" / "completed" / "cancelled" / "failed"	必有; in_progress 表示等待或正在入库；completed 表示可检索；failed 表示入库失败；cancelled 表示批次取消已停止入库。
last_error	object / null	必有; 入库失败详情；未失败、成功完成或重新入库时为 null。
last_error (1).code	"server_error" / "unsupported_file" / "invalid_file"	必有; unsupported_file 表示不支持的文件类型；invalid_file 表示加密、空文件或超过解析 token 上限；server_error 表示其它入库失败或超过截止时间。
last_error (1).message	string	必有; 与 code 对应的入库失败说明。
usage_bytes	integer	必有; 完成后计入源文件字节数；处理中、失败或已取消时为零。; 最小: 0
created_at	integer	必有; Unix 时间戳，单位秒。
chunking_strategy	object / object	必有; 此附件已保存的分段策略；auto 输入返回为具体 static 设置。
chunking_strategy (1).type	"static"	必有; static 表示使用显式分段大小与重叠设置。
chunking_strategy (1).static	object	必有; 以估算 token 数表示的分段大小与重叠限制。
chunking_strategy (1).static.max_chunk_size_tokens	integer	必有; 每段的估算 token 数。; 最小: 100; 最大: 4096
chunking_strategy (1).static.chunk_overlap_tokens	integer	必有; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048
chunking_strategy (2).type	"other"	必有
attributes	object / null	必有; 用于搜索筛选的文件属性；null 表示未设置。
praxis	object	可选; 原生入库进度与源文件统计。
praxis.stage	"queued" / "parse" / "chunk" / "embed" / "index" / null	必有; queued 表示等待；parse 提取文本；chunk 划分分段；embed 生成向量；index 建立检索索引。null 表示入库已不在进行中。
praxis.deadline_at	integer / null	必有; 入库截止的 Unix 秒时间戳；到点仍未完成的入库转为失败。
praxis.filename	string	必有; File 服务返回的源文件名。
praxis.bytes	integer	必有; 源文件字节数。; 最小: 0
praxis.pages	integer / null	必有; 成功入库后的解析页数；成功结果保存前为 null。
praxis.chunk_count	integer	必有; 已完成入库的分段数；完成前、失败或取消后为零。; 最小: 0

错误码与错误对象

移除文件

DELETE /knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}

返回后立即不再搜索到该文件；不会删除源文件。

参数

名称	位置与类型	说明
vector_store_id	path: string	必填；创建或列表返回的知识库 ID；不要使用显示名称。最短字符数: 1
file_id	path: string	必填；添加附件或附件列表返回的源 File ID。最短字符数: 1

请求示例

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

响应

HTTP 200

字段	类型	说明
id	string	必有; 资源 ID。; 最短字符数: 1
object	"vector_store.file.deleted"	必有; 对象标记；vector_store.file.deleted 表示此操作回执。
deleted	true	必有; 确认已从此知识库移出；源 File 未删除。

错误码与错误对象

读取抽取内容

GET /knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}/content

抽取文本按分段返回，可能重叠。图片内容可能是生成的描述，并非逐字 OCR。

参数

名称	位置与类型	说明
vector_store_id	path: string	必填；创建或列表返回的知识库 ID；不要使用显示名称。最短字符数: 1
file_id	path: string	必填；添加附件或附件列表返回的源 File ID。最短字符数: 1

请求示例

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

响应

HTTP 200

字段	类型	说明
object	"vector_store.file_content.page"	必有; 对象标记；vector_store.file_content.page 表示提取的文件内容。
data	object[]	必有; 按分段序号排列的全部现存文本分段；相邻分段可能重叠。
data[].type	"text"	必有; text 表示提取出的文本分段。
data[].text	string	必有; 此分段的提取文本；可能与相邻分段重叠。
has_more	false	必有; 恒为 false；此响应返回全部现存分段。
next_page	null	必有; 恒为 null；提取内容不分页。

错误码与错误对象

重试失败文件

POST /knowledge/v1/vector_stores/{vector_store_id}/files/{file_id}/retry

仅重试 failed 文件；其他状态返回 409 FILE_INVALID_STATE。本次实测尚未覆盖失败后的重试。

参数

名称	位置与类型	说明
vector_store_id	path: string	必填；创建或列表返回的知识库 ID；不要使用显示名称。最短字符数: 1
file_id	path: string	必填；添加附件或附件列表返回的源 File ID。最短字符数: 1

请求示例

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

响应

HTTP 200

字段	类型	说明
id	string	必有; 与源文件相同的 ID。; 最短字符数: 1
object	"vector_store.file"	必有; 对象标记；vector_store.file 表示知识库中的附件。
vector_store_id	string	必有; 资源 ID。; 最短字符数: 1
status	"in_progress" / "completed" / "cancelled" / "failed"	必有; in_progress 表示等待或正在入库；completed 表示可检索；failed 表示入库失败；cancelled 表示批次取消已停止入库。
last_error	object / null	必有; 入库失败详情；未失败、成功完成或重新入库时为 null。
last_error (1).code	"server_error" / "unsupported_file" / "invalid_file"	必有; unsupported_file 表示不支持的文件类型；invalid_file 表示加密、空文件或超过解析 token 上限；server_error 表示其它入库失败或超过截止时间。
last_error (1).message	string	必有; 与 code 对应的入库失败说明。
usage_bytes	integer	必有; 完成后计入源文件字节数；处理中、失败或已取消时为零。; 最小: 0
created_at	integer	必有; Unix 时间戳，单位秒。
chunking_strategy	object / object	必有; 此附件已保存的分段策略；auto 输入返回为具体 static 设置。
chunking_strategy (1).type	"static"	必有; static 表示使用显式分段大小与重叠设置。
chunking_strategy (1).static	object	必有; 以估算 token 数表示的分段大小与重叠限制。
chunking_strategy (1).static.max_chunk_size_tokens	integer	必有; 每段的估算 token 数。; 最小: 100; 最大: 4096
chunking_strategy (1).static.chunk_overlap_tokens	integer	必有; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048
chunking_strategy (2).type	"other"	必有
attributes	object / null	必有; 用于搜索筛选的文件属性；null 表示未设置。
praxis	object	可选; 原生入库进度与源文件统计。
praxis.stage	"queued" / "parse" / "chunk" / "embed" / "index" / null	必有; queued 表示等待；parse 提取文本；chunk 划分分段；embed 生成向量；index 建立检索索引。null 表示入库已不在进行中。
praxis.deadline_at	integer / null	必有; 入库截止的 Unix 秒时间戳；到点仍未完成的入库转为失败。
praxis.filename	string	必有; File 服务返回的源文件名。
praxis.bytes	integer	必有; 源文件字节数。; 最小: 0
praxis.pages	integer / null	必有; 成功入库后的解析页数；成功结果保存前为 null。
praxis.chunk_count	integer	必有; 已完成入库的分段数；完成前、失败或取消后为零。; 最小: 0

错误码与错误对象

文件

本页内容