知识库 API

资源	用途
知识库	创建、读取、更新、删除与恢复
文件	添加、读取、更新属性、移除与重试
批量	成批添加文件、读取状态与取消
搜索	检索相关文本分段
分段	读取分段、位置与关键词
事件	读取知识库与文件处理事件

错误码 · 上限与格式支持 · OpenAI vector stores

知识库

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

创建知识库

POST /knowledge/v1/vector_stores

创建知识库。可用 file_ids 添加已有 File 并异步入库；后续调用使用返回的 id。最小请求体：{"name":"Refund policies"}。

请求体

字段	类型	说明
name	string	可选; 省略时为空字符串；不接受 null。; 最长字符数: 256; 默认: ""
metadata	object / null	可选; 知识库自定义字符串元数据；省略或 null 得到空对象。; 默认: {}
expires_after	object / null	可选; 从最近活动计算的过期策略；省略或 null 表示不自动过期。; 默认: null
expires_after (1).anchor	"last_active_at"	必填; last_active_at 表示从最近活动时间开始计算过期。
expires_after (1).days	integer	必填; 自最近活动起的天数；添加文件和搜索会刷新活动时间。; 最小: 1; 最大: 365
file_ids	string[]	可选; 要加入的已有文件 ID；每库最多 10,000 个文件。
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
description	string	可选; 不生效: 接受后丢弃，不保存也不返回；当前不校验类型。
models	object / null	可选; 要设置的模型角色。模型必须在模型目录中且支持该角色（embedding → openai.embeddings，rerank → cohere.rerank，query_rewrite → openai.chat.completions）。嵌入模型必须输出 1024 维向量。省略的角色不变；null 恢复全部默认。未知角色或空 ID 返回 400 INVALID_PARAMS。OpenAI 兼容接口传入此字段返回 400。; Praxis 扩展
models (1).embedding	string / null	可选; 给文件分段和查询生成向量。库中已有文件后不能更换。null 恢复默认（bge-m3）。
models (1).rerank	string / null	可选; ranking_options.ranker 为 default-2024-11-15 时用于重排结果。null 恢复默认（bge-reranker-base）。
models (1).query_rewrite	string / null	可选; 搜索设置 rewrite_query 时用于改写查询。null 恢复默认（qwen3.8-flash）。

请求示例

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

响应

HTTP 200

字段	类型	说明
id	string	必有; 资源 ID。; 最短字符数: 1
object	"vector_store"	必有; 对象标记；vector_store 表示知识库。
name	string	必有; 知识库显示名称；空字符串表示未设置名称。; 最长字符数: 256
status	"in_progress" / "completed" / "expired" / "deleting"	必有; in_progress 表示仍有文件入库中；completed 表示没有入库中的文件，不保证全部成功；expired 表示过期策略已生效。deleting 表示已软删除、等待永久清除。
usage_bytes	integer	必有; 已完成源文件的字节数之和。; 最小: 0
file_counts	object	必有; 仍属于该库或批次的附件数量，按入库状态分组。
file_counts.in_progress	integer	必有; 等待或正在入库的文件数。; 最小: 0
file_counts.completed	integer	必有; 已完成入库的文件数。; 最小: 0
file_counts.failed	integer	必有; 入库失败的文件数。; 最小: 0
file_counts.cancelled	integer	必有; 因批次取消而停止入库的文件数。; 最小: 0
file_counts.total	integer	必有; 全部入库状态的附件总数。; 最小: 0
created_at	integer	必有; Unix 时间戳，单位秒。
last_active_at	integer / null	必有; 最近创建、添加文件或搜索的 Unix 秒时间戳；不可用时为 null。
expires_after	object / null	必有; 从最近活动开始计算的过期策略；null 表示不自动过期。
expires_after (1).anchor	"last_active_at"	必有; last_active_at 表示从最近活动时间开始计算过期。
expires_after (1).days	integer	必有; 自最近活动起的天数；添加文件和搜索会刷新活动时间。; 最小: 1; 最大: 365
expires_at	integer / null	必有; 预计过期的 Unix 秒时间戳；未设置过期策略时为 null。
metadata	object	必有; 最多 16 个键；键最多 64 字符；字符串值最多 512 字符。; 最多键数: 16; 键最多 64 字符; 值: string
purge_at	string / null	可选; ISO 8601 格式的恢复截止时间；未软删除时为 null。
models	object	可选; 各角色生效的模型（Router 模型 ID）；未设置的角色使用默认模型。; Praxis 扩展
models.embedding	string	必有; 给文件分段和查询生成向量。库中已有文件后不能更换。默认 bge-m3。; 最短字符数: 1
models.rerank	string	必有; ranking_options.ranker 为 default-2024-11-15 时用于重排结果。默认 bge-reranker-base。; 最短字符数: 1
models.query_rewrite	string	必有; 搜索设置 rewrite_query 时用于改写查询。默认 qwen3.8-flash。; 最短字符数: 1
praxis	object	可选; 此知识库的原生生命周期与恢复信息。
praxis.lifecycle	"provisioning" / "active" / "expired" / "deleted" / "failed"	必有; provisioning 表示正在初始化；active 允许文件操作与搜索；expired 表示已过期；deleted 表示已软删除；failed 表示初始化失败。
praxis.deleted_at	integer / null	必有; 软删除的 Unix 秒时间戳；未软删除时为 null。
praxis.purge_at	integer / null	必有; 恢复截止的 Unix 秒时间戳；未软删除时为 null。

列出知识库

GET /knowledge/v1/vector_stores

列出调用方可见的知识库，默认最新在前。将 last_id 作为 after 读取下一页，例如 ?limit=20。

参数

名称	位置与类型	说明
status	query: "active" / "deleting"	active 筛选活跃库；deleting 筛选软删除待清除的库。省略时排除软删除库。
after	query: string	上一页的 ID 游标。最短字符数: 1
before	query: string	返回此 ID 之前的条目。最短字符数: 1
limit	query: integer	每页条数。最小: 1; 最大: 100; 默认: 20
order	query: "asc" / "desc"	知识库和文件默认按创建时间降序；分段默认按序号升序。默认: "desc"

请求示例

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

响应

HTTP 200

字段	类型	说明
object	"list"	必有; 对象标记；list 表示游标分页集合。
data	object[]	必有; 按请求顺序返回的当前页条目。
data[].id	string	必有; 资源 ID。; 最短字符数: 1
data[].object	"vector_store"	必有; 对象标记；vector_store 表示知识库。
data[].name	string	必有; 知识库显示名称；空字符串表示未设置名称。; 最长字符数: 256
data[].status	"in_progress" / "completed" / "expired" / "deleting"	必有; in_progress 表示仍有文件入库中；completed 表示没有入库中的文件，不保证全部成功；expired 表示过期策略已生效。deleting 表示已软删除、等待永久清除。
data[].usage_bytes	integer	必有; 已完成源文件的字节数之和。; 最小: 0
data[].file_counts	object	必有; 仍属于该库或批次的附件数量，按入库状态分组。
data[].file_counts.in_progress	integer	必有; 等待或正在入库的文件数。; 最小: 0
data[].file_counts.completed	integer	必有; 已完成入库的文件数。; 最小: 0
data[].file_counts.failed	integer	必有; 入库失败的文件数。; 最小: 0
data[].file_counts.cancelled	integer	必有; 因批次取消而停止入库的文件数。; 最小: 0
data[].file_counts.total	integer	必有; 全部入库状态的附件总数。; 最小: 0
data[].created_at	integer	必有; Unix 时间戳，单位秒。
data[].last_active_at	integer / null	必有; 最近创建、添加文件或搜索的 Unix 秒时间戳；不可用时为 null。
data[].expires_after	object / null	必有; 从最近活动开始计算的过期策略；null 表示不自动过期。
data[].expires_after (1).anchor	"last_active_at"	必有; last_active_at 表示从最近活动时间开始计算过期。
data[].expires_after (1).days	integer	必有; 自最近活动起的天数；添加文件和搜索会刷新活动时间。; 最小: 1; 最大: 365
data[].expires_at	integer / null	必有; 预计过期的 Unix 秒时间戳；未设置过期策略时为 null。
data[].metadata	object	必有; 最多 16 个键；键最多 64 字符；字符串值最多 512 字符。; 最多键数: 16; 键最多 64 字符; 值: string
data[].purge_at	string / null	可选; ISO 8601 格式的恢复截止时间；未软删除时为 null。
data[].models	object	可选; 各角色生效的模型（Router 模型 ID）；未设置的角色使用默认模型。; Praxis 扩展
data[].models.embedding	string	必有; 给文件分段和查询生成向量。库中已有文件后不能更换。默认 bge-m3。; 最短字符数: 1
data[].models.rerank	string	必有; ranking_options.ranker 为 default-2024-11-15 时用于重排结果。默认 bge-reranker-base。; 最短字符数: 1
data[].models.query_rewrite	string	必有; 搜索设置 rewrite_query 时用于改写查询。默认 qwen3.8-flash。; 最短字符数: 1
data[].praxis	object	可选; 此知识库的原生生命周期与恢复信息。
data[].praxis.lifecycle	"provisioning" / "active" / "expired" / "deleted" / "failed"	必有; provisioning 表示正在初始化；active 允许文件操作与搜索；expired 表示已过期；deleted 表示已软删除；failed 表示初始化失败。
data[].praxis.deleted_at	integer / null	必有; 软删除的 Unix 秒时间戳；未软删除时为 null。
data[].praxis.purge_at	integer / null	必有; 恢复截止的 Unix 秒时间戳；未软删除时为 null。
first_id	string / null	必有; 本页首项的 ID；空页为 null。
last_id	string / null	必有; 本页末项的 ID，可作为 after 继续查询；空页为 null。
has_more	boolean	必有; 当前游标范围内，本页之后是否还有条目。

读取知识库

GET /knowledge/v1/vector_stores/{vector_store_id}

使用创建或列表返回的 id 读取知识库。添加 ?expand=files 可同时返回附件首页。软删除的库在永久清除前仍可读取，status 为 deleting。

参数

名称	位置与类型	说明
vector_store_id	path: string	必填；创建或列表返回的知识库 ID；不要使用显示名称。最短字符数: 1
expand	query: "files"[]	两个地址均支持的 Praxis 扩展：files 附带文件首页；未知值忽略。
expand[]	query: "files"[]	两个地址均支持的 Praxis 扩展：files 附带文件首页；未知值忽略。

请求示例

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

响应

HTTP 200

字段	类型	说明
(1).id	string	必有; 资源 ID。; 最短字符数: 1
(1).object	"vector_store"	必有; 对象标记；vector_store 表示知识库。
(1).name	string	必有; 知识库显示名称；空字符串表示未设置名称。; 最长字符数: 256
(1).status	"in_progress" / "completed" / "expired" / "deleting"	必有; in_progress 表示仍有文件入库中；completed 表示没有入库中的文件，不保证全部成功；expired 表示过期策略已生效。deleting 表示已软删除、等待永久清除。
(1).usage_bytes	integer	必有; 已完成源文件的字节数之和。; 最小: 0
(1).file_counts	object	必有; 仍属于该库或批次的附件数量，按入库状态分组。
(1).file_counts.in_progress	integer	必有; 等待或正在入库的文件数。; 最小: 0
(1).file_counts.completed	integer	必有; 已完成入库的文件数。; 最小: 0
(1).file_counts.failed	integer	必有; 入库失败的文件数。; 最小: 0
(1).file_counts.cancelled	integer	必有; 因批次取消而停止入库的文件数。; 最小: 0
(1).file_counts.total	integer	必有; 全部入库状态的附件总数。; 最小: 0
(1).created_at	integer	必有; Unix 时间戳，单位秒。
(1).last_active_at	integer / null	必有; 最近创建、添加文件或搜索的 Unix 秒时间戳；不可用时为 null。
(1).expires_after	object / null	必有; 从最近活动开始计算的过期策略；null 表示不自动过期。
(1).expires_after (1).anchor	"last_active_at"	必有; last_active_at 表示从最近活动时间开始计算过期。
(1).expires_after (1).days	integer	必有; 自最近活动起的天数；添加文件和搜索会刷新活动时间。; 最小: 1; 最大: 365
(1).expires_at	integer / null	必有; 预计过期的 Unix 秒时间戳；未设置过期策略时为 null。
(1).metadata	object	必有; 最多 16 个键；键最多 64 字符；字符串值最多 512 字符。; 最多键数: 16; 键最多 64 字符; 值: string
(1).purge_at	string / null	可选; ISO 8601 格式的恢复截止时间；未软删除时为 null。
(1).models	object	可选; 各角色生效的模型（Router 模型 ID）；未设置的角色使用默认模型。; Praxis 扩展
(1).models.embedding	string	必有; 给文件分段和查询生成向量。库中已有文件后不能更换。默认 bge-m3。; 最短字符数: 1
(1).models.rerank	string	必有; ranking_options.ranker 为 default-2024-11-15 时用于重排结果。默认 bge-reranker-base。; 最短字符数: 1
(1).models.query_rewrite	string	必有; 搜索设置 rewrite_query 时用于改写查询。默认 qwen3.8-flash。; 最短字符数: 1
(1).praxis	object	可选; 此知识库的原生生命周期与恢复信息。
(1).praxis.lifecycle	"provisioning" / "active" / "expired" / "deleted" / "failed"	必有; provisioning 表示正在初始化；active 允许文件操作与搜索；expired 表示已过期；deleted 表示已软删除；failed 表示初始化失败。
(1).praxis.deleted_at	integer / null	必有; 软删除的 Unix 秒时间戳；未软删除时为 null。
(1).praxis.purge_at	integer / null	必有; 恢复截止的 Unix 秒时间戳；未软删除时为 null。
(2).files	object	可选; 仅在 expand=files 时返回文件首页。
(2).files.object	"list"	必有; 对象标记；list 表示游标分页集合。
(2).files.data	object[]	必有; 按请求顺序返回的当前页条目。
(2).files.data[].id	string	必有; 与源文件相同的 ID。; 最短字符数: 1
(2).files.data[].object	"vector_store.file"	必有; 对象标记；vector_store.file 表示知识库中的附件。
(2).files.data[].vector_store_id	string	必有; 资源 ID。; 最短字符数: 1
(2).files.data[].status	"in_progress" / "completed" / "cancelled" / "failed"	必有; in_progress 表示等待或正在入库；completed 表示可检索；failed 表示入库失败；cancelled 表示批次取消已停止入库。
(2).files.data[].last_error	object / null	必有; 入库失败详情；未失败、成功完成或重新入库时为 null。
(2).files.data[].last_error (1).code	"server_error" / "unsupported_file" / "invalid_file"	必有; unsupported_file 表示不支持的文件类型；invalid_file 表示加密、空文件或超过解析 token 上限；server_error 表示其它入库失败或超过截止时间。
(2).files.data[].last_error (1).message	string	必有; 与 code 对应的入库失败说明。
(2).files.data[].usage_bytes	integer	必有; 完成后计入源文件字节数；处理中、失败或已取消时为零。; 最小: 0
(2).files.data[].created_at	integer	必有; Unix 时间戳，单位秒。
(2).files.data[].chunking_strategy	object / object	必有; 此附件已保存的分段策略；auto 输入返回为具体 static 设置。
(2).files.data[].chunking_strategy (1).type	"static"	必有; static 表示使用显式分段大小与重叠设置。
(2).files.data[].chunking_strategy (1).static	object	必有; 以估算 token 数表示的分段大小与重叠限制。
(2).files.data[].chunking_strategy (1).static.max_chunk_size_tokens	integer	必有; 每段的估算 token 数。; 最小: 100; 最大: 4096
(2).files.data[].chunking_strategy (1).static.chunk_overlap_tokens	integer	必有; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048
(2).files.data[].chunking_strategy (2).type	"other"	必有; other identifies a stored strategy whose chunk-size settings are unavailable.
(2).files.data[].attributes	object / null	必有; 用于搜索筛选的文件属性；null 表示未设置。
(2).files.data[].praxis	object	可选; 原生入库进度与源文件统计。
(2).files.data[].praxis.stage	"queued" / "parse" / "chunk" / "embed" / "index" / null	必有; queued 表示等待；parse 提取文本；chunk 划分分段；embed 生成向量；index 建立检索索引。null 表示入库已不在进行中。
(2).files.data[].praxis.deadline_at	integer / null	必有; 入库截止的 Unix 秒时间戳；到点仍未完成的入库转为失败。
(2).files.data[].praxis.filename	string	必有; File 服务返回的源文件名。
(2).files.data[].praxis.bytes	integer	必有; 源文件字节数。; 最小: 0
(2).files.data[].praxis.pages	integer / null	必有; 成功入库后的解析页数；成功结果保存前为 null。
(2).files.data[].praxis.chunk_count	integer	必有; 已完成入库的分段数；完成前、失败或取消后为零。; 最小: 0
(2).files.first_id	string / null	必有; 本页首项的 ID；空页为 null。
(2).files.last_id	string / null	必有; 本页末项的 ID，可作为 after 继续查询；空页为 null。
(2).files.has_more	boolean	必有; 当前游标范围内，本页之后是否还有条目。

更新知识库

POST /knowledge/v1/vector_stores/{vector_store_id}

使用返回的 id 修改活跃知识库。省略的字段不变；metadata 替换整个对象。请求体示例：{"name":"Refund policies"}。

参数

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

请求体

字段	类型	说明
name	string / null	可选; null 将名称清空为空字符串；省略的字段不变。
metadata	object / null	可选; 替换全部元数据；null 清空为一个空对象。
expires_after	object / null	可选; null 取消自动过期。
expires_after (1).anchor	"last_active_at"	必填; last_active_at 表示从最近活动时间开始计算过期。
expires_after (1).days	integer	必填; 自最近活动起的天数；添加文件和搜索会刷新活动时间。; 最小: 1; 最大: 365
models	object / null	可选; 要设置的模型角色。模型必须在模型目录中且支持该角色（embedding → openai.embeddings，rerank → cohere.rerank，query_rewrite → openai.chat.completions）。嵌入模型必须输出 1024 维向量。省略的角色不变；null 恢复全部默认。未知角色或空 ID 返回 400 INVALID_PARAMS。OpenAI 兼容接口传入此字段返回 400。; Praxis 扩展
models (1).embedding	string / null	可选; 给文件分段和查询生成向量。库中已有文件后不能更换。null 恢复默认（bge-m3）。
models (1).rerank	string / null	可选; ranking_options.ranker 为 default-2024-11-15 时用于重排结果。null 恢复默认（bge-reranker-base）。
models (1).query_rewrite	string / null	可选; 搜索设置 rewrite_query 时用于改写查询。null 恢复默认（qwen3.8-flash）。

请求示例

curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"models\":{\"query_rewrite\":\"qwen3.8-flash\"}}"

响应

HTTP 200

字段	类型	说明
id	string	必有; 资源 ID。; 最短字符数: 1
object	"vector_store"	必有; 对象标记；vector_store 表示知识库。
name	string	必有; 知识库显示名称；空字符串表示未设置名称。; 最长字符数: 256
status	"in_progress" / "completed" / "expired" / "deleting"	必有; in_progress 表示仍有文件入库中；completed 表示没有入库中的文件，不保证全部成功；expired 表示过期策略已生效。deleting 表示已软删除、等待永久清除。
usage_bytes	integer	必有; 已完成源文件的字节数之和。; 最小: 0
file_counts	object	必有; 仍属于该库或批次的附件数量，按入库状态分组。
file_counts.in_progress	integer	必有; 等待或正在入库的文件数。; 最小: 0
file_counts.completed	integer	必有; 已完成入库的文件数。; 最小: 0
file_counts.failed	integer	必有; 入库失败的文件数。; 最小: 0
file_counts.cancelled	integer	必有; 因批次取消而停止入库的文件数。; 最小: 0
file_counts.total	integer	必有; 全部入库状态的附件总数。; 最小: 0
created_at	integer	必有; Unix 时间戳，单位秒。
last_active_at	integer / null	必有; 最近创建、添加文件或搜索的 Unix 秒时间戳；不可用时为 null。
expires_after	object / null	必有; 从最近活动开始计算的过期策略；null 表示不自动过期。
expires_after (1).anchor	"last_active_at"	必有; last_active_at 表示从最近活动时间开始计算过期。
expires_after (1).days	integer	必有; 自最近活动起的天数；添加文件和搜索会刷新活动时间。; 最小: 1; 最大: 365
expires_at	integer / null	必有; 预计过期的 Unix 秒时间戳；未设置过期策略时为 null。
metadata	object	必有; 最多 16 个键；键最多 64 字符；字符串值最多 512 字符。; 最多键数: 16; 键最多 64 字符; 值: string
purge_at	string / null	可选; ISO 8601 格式的恢复截止时间；未软删除时为 null。
models	object	可选; 各角色生效的模型（Router 模型 ID）；未设置的角色使用默认模型。; Praxis 扩展
models.embedding	string	必有; 给文件分段和查询生成向量。库中已有文件后不能更换。默认 bge-m3。; 最短字符数: 1
models.rerank	string	必有; ranking_options.ranker 为 default-2024-11-15 时用于重排结果。默认 bge-reranker-base。; 最短字符数: 1
models.query_rewrite	string	必有; 搜索设置 rewrite_query 时用于改写查询。默认 qwen3.8-flash。; 最短字符数: 1
praxis	object	可选; 此知识库的原生生命周期与恢复信息。
praxis.lifecycle	"provisioning" / "active" / "expired" / "deleted" / "failed"	必有; provisioning 表示正在初始化；active 允许文件操作与搜索；expired 表示已过期；deleted 表示已软删除；failed 表示初始化失败。
praxis.deleted_at	integer / null	必有; 软删除的 Unix 秒时间戳；未软删除时为 null。
praxis.purge_at	integer / null	必有; 恢复截止的 Unix 秒时间戳；未软删除时为 null。

删除知识库

DELETE /knowledge/v1/vector_stores/{vector_store_id}

软删除后保留 7 天；返回 status=deleting 和 ISO purge_at，重复删除幂等。读取仍为 200，对象操作返回 409。

参数

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

请求示例

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

响应

HTTP 200

字段	类型	说明
id	string	必有; 资源 ID。; 最短字符数: 1
object	"vector_store"	必有; 对象标记；vector_store 表示知识库。
name	string	必有; 知识库显示名称；空字符串表示未设置名称。; 最长字符数: 256
status	"in_progress" / "completed" / "expired" / "deleting"	必有; in_progress 表示仍有文件入库中；completed 表示没有入库中的文件，不保证全部成功；expired 表示过期策略已生效。deleting 表示已软删除、等待永久清除。
usage_bytes	integer	必有; 已完成源文件的字节数之和。; 最小: 0
file_counts	object	必有; 仍属于该库或批次的附件数量，按入库状态分组。
file_counts.in_progress	integer	必有; 等待或正在入库的文件数。; 最小: 0
file_counts.completed	integer	必有; 已完成入库的文件数。; 最小: 0
file_counts.failed	integer	必有; 入库失败的文件数。; 最小: 0
file_counts.cancelled	integer	必有; 因批次取消而停止入库的文件数。; 最小: 0
file_counts.total	integer	必有; 全部入库状态的附件总数。; 最小: 0
created_at	integer	必有; Unix 时间戳，单位秒。
last_active_at	integer / null	必有; 最近创建、添加文件或搜索的 Unix 秒时间戳；不可用时为 null。
expires_after	object / null	必有; 从最近活动开始计算的过期策略；null 表示不自动过期。
expires_after (1).anchor	"last_active_at"	必有; last_active_at 表示从最近活动时间开始计算过期。
expires_after (1).days	integer	必有; 自最近活动起的天数；添加文件和搜索会刷新活动时间。; 最小: 1; 最大: 365
expires_at	integer / null	必有; 预计过期的 Unix 秒时间戳；未设置过期策略时为 null。
metadata	object	必有; 最多 16 个键；键最多 64 字符；字符串值最多 512 字符。; 最多键数: 16; 键最多 64 字符; 值: string
purge_at	string / null	可选; ISO 8601 格式的恢复截止时间；未软删除时为 null。
models	object	可选; 各角色生效的模型（Router 模型 ID）；未设置的角色使用默认模型。; Praxis 扩展
models.embedding	string	必有; 给文件分段和查询生成向量。库中已有文件后不能更换。默认 bge-m3。; 最短字符数: 1
models.rerank	string	必有; ranking_options.ranker 为 default-2024-11-15 时用于重排结果。默认 bge-reranker-base。; 最短字符数: 1
models.query_rewrite	string	必有; 搜索设置 rewrite_query 时用于改写查询。默认 qwen3.8-flash。; 最短字符数: 1
praxis	object	可选; 此知识库的原生生命周期与恢复信息。
praxis.lifecycle	"provisioning" / "active" / "expired" / "deleted" / "failed"	必有; provisioning 表示正在初始化；active 允许文件操作与搜索；expired 表示已过期；deleted 表示已软删除；failed 表示初始化失败。
praxis.deleted_at	integer / null	必有; 软删除的 Unix 秒时间戳；未软删除时为 null。
praxis.purge_at	integer / null	必有; 恢复截止的 Unix 秒时间戳；未软删除时为 null。

恢复知识库

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

恢复删除未满 7 天的知识库；可用库返回 409 VECTOR_STORE_INVALID_STATE，不存在返回 404；请求体可为空。

参数

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

请求示例

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

响应

HTTP 200

字段	类型	说明
id	string	必有; 资源 ID。; 最短字符数: 1
object	"vector_store"	必有; 对象标记；vector_store 表示知识库。
name	string	必有; 知识库显示名称；空字符串表示未设置名称。; 最长字符数: 256
status	"in_progress" / "completed" / "expired" / "deleting"	必有; in_progress 表示仍有文件入库中；completed 表示没有入库中的文件，不保证全部成功；expired 表示过期策略已生效。deleting 表示已软删除、等待永久清除。
usage_bytes	integer	必有; 已完成源文件的字节数之和。; 最小: 0
file_counts	object	必有; 仍属于该库或批次的附件数量，按入库状态分组。
file_counts.in_progress	integer	必有; 等待或正在入库的文件数。; 最小: 0
file_counts.completed	integer	必有; 已完成入库的文件数。; 最小: 0
file_counts.failed	integer	必有; 入库失败的文件数。; 最小: 0
file_counts.cancelled	integer	必有; 因批次取消而停止入库的文件数。; 最小: 0
file_counts.total	integer	必有; 全部入库状态的附件总数。; 最小: 0
created_at	integer	必有; Unix 时间戳，单位秒。
last_active_at	integer / null	必有; 最近创建、添加文件或搜索的 Unix 秒时间戳；不可用时为 null。
expires_after	object / null	必有; 从最近活动开始计算的过期策略；null 表示不自动过期。
expires_after (1).anchor	"last_active_at"	必有; last_active_at 表示从最近活动时间开始计算过期。
expires_after (1).days	integer	必有; 自最近活动起的天数；添加文件和搜索会刷新活动时间。; 最小: 1; 最大: 365
expires_at	integer / null	必有; 预计过期的 Unix 秒时间戳；未设置过期策略时为 null。
metadata	object	必有; 最多 16 个键；键最多 64 字符；字符串值最多 512 字符。; 最多键数: 16; 键最多 64 字符; 值: string
purge_at	string / null	可选; ISO 8601 格式的恢复截止时间；未软删除时为 null。
models	object	可选; 各角色生效的模型（Router 模型 ID）；未设置的角色使用默认模型。; Praxis 扩展
models.embedding	string	必有; 给文件分段和查询生成向量。库中已有文件后不能更换。默认 bge-m3。; 最短字符数: 1
models.rerank	string	必有; ranking_options.ranker 为 default-2024-11-15 时用于重排结果。默认 bge-reranker-base。; 最短字符数: 1
models.query_rewrite	string	必有; 搜索设置 rewrite_query 时用于改写查询。默认 qwen3.8-flash。; 最短字符数: 1
praxis	object	可选; 此知识库的原生生命周期与恢复信息。
praxis.lifecycle	"provisioning" / "active" / "expired" / "deleted" / "failed"	必有; provisioning 表示正在初始化；active 允许文件操作与搜索；expired 表示已过期；deleted 表示已软删除；failed 表示初始化失败。
praxis.deleted_at	integer / null	必有; 软删除的 Unix 秒时间戳；未软删除时为 null。
praxis.purge_at	integer / null	必有; 恢复截止的 Unix 秒时间戳；未软删除时为 null。

永久清除知识库

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

立即永久清除删除中的知识库，不可撤销；复用到期清理路径。可用库返回 409，不存在返回 404；请求体可为空。

参数

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

请求示例

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

响应

HTTP 200

字段	类型	说明
id	string	必有; 已永久清除的知识库 ID。
object	"vector_store"	必有; 对象标记；vector_store 表示此操作回执。
purged	true	必有; 确认已永久清除知识库及其索引内容。

文件

路径中的 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"	必有; other identifies a stored strategy whose chunk-size settings are unavailable.
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"	必有; other identifies a stored strategy whose chunk-size settings are unavailable.
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"	必有; other identifies a stored strategy whose chunk-size settings are unavailable.
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"	必有; other identifies a stored strategy whose chunk-size settings are unavailable.
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"	必有; other identifies a stored strategy whose chunk-size settings are unavailable.
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

批量

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

创建文件批次

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

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

参数

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

请求体

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

字段	类型	说明
(1).file_ids	string[]	必填; 使用共同属性和分段设置的已有 File ID 列表。file_ids 与 files 二选一。; 最少条数: 1; 最多条数: 500
(1).attributes	object / null	可选; 用于每个新附件的搜索筛选属性；省略或 null 表示不设置。
(1).chunking_strategy	object / 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).static	object	必填; 以估算 token 数表示的分段大小与重叠限制。
(1).chunking_strategy (2).static.max_chunk_size_tokens	integer	必填; 每段的估算 token 数。; 最小: 100; 最大: 4096
(1).chunking_strategy (2).static.chunk_overlap_tokens	integer	必填; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048
(2).files	object[]	必填; 分别指定属性和分段设置的附件列表；忽略顶层 attributes 与 chunking_strategy。; 最少条数: 1; 最多条数: 500
(2).files[].file_id	string	必填; 上传文件返回的已有源 File ID；文件必须对调用方可见。; 最短字符数: 1
(2).files[].attributes	object	可选; 用于搜索筛选的文件属性。最多 16 个键，键最多 64 字符，字符串值最多 512 字符。; 最多键数: 16; 键最多 64 字符; 值: string / number / boolean
(2).files[].chunking_strategy	object / 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).static	object	必填; 以估算 token 数表示的分段大小与重叠限制。
(2).files[].chunking_strategy (2).static.max_chunk_size_tokens	integer	必填; 每段的估算 token 数。; 最小: 100; 最大: 4096
(2).files[].chunking_strategy (2).static.chunk_overlap_tokens	integer	必填; 不得超过 max_chunk_size_tokens 的一半。; 最小: 0; 最大: 2048
(2).attributes	JSON	可选; 不生效: 使用 files 时不生效。
(2).chunking_strategy	JSON	可选; 不生效: 使用 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

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

读取文件批次

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

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

参数

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

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

取消文件批次

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

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

参数

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

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

列出批次文件

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

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

参数

名称	位置与类型	说明
vector_store_id	path: string	必填；创建或列表返回的知识库 ID；不要使用显示名称。最短字符数: 1
batch_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}/file_batches/${BATCH_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"	必有; other identifies a stored strategy whose chunk-size settings are unavailable.
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	必有; 当前游标范围内，本页之后是否还有条目。

搜索

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

搜索知识库

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

按分段返回，同一文件可出现多次。最多 50 条，没有下一页。

参数

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

请求体

字段	类型	说明
query	string / string[]	必填; 非空白文本；多个查询以换行连接后共同搜索。
filters	object / object / object	可选; 按类型严格匹配文件属性；根条件以下最多嵌套 20 层。
filters (1).type	"eq" / "ne" / "gt" / "gte" / "lt" / "lte"	必填; eq 等于，ne 不等于，gt 大于，gte 大于等于，lt 小于，lte 小于等于；属性必须存在且值类型一致。
filters (1).key	string	必填; 要比较的文件属性原始键名，标点也是键名的一部分。; 最短字符数: 1
filters (1).value	string / number / boolean	必填; 不进行类型转换的比较值。
filters (2).type	"in" / "nin"	必填; in 匹配数组中的值；nin 匹配不在数组中的值。属性不存在时均不匹配。
filters (2).key	string	必填; 要比较的文件属性原始键名，标点也是键名的一部分。; 最短字符数: 1
filters (2).value	string / number[]	必填; 不进行类型转换的字符串或数值成员列表。
filters (3).type	"and" / "or"	必填; and 要求所有子条件匹配；or 要求至少一个子条件匹配。
filters (3).filters	object / object / object[]	必填; 按选定 and/or 运算符组合的非空子条件列表。; 最少条数: 1
filters (3).filters[]	object / object / object	递归使用同一筛选结构，嵌套上限 20 层。
max_num_results	integer	可选; 最多返回的分段数，不是不同文件数。; 最小: 1; 最大: 50; 默认: 10
rewrite_query	boolean	可选; 支持: 为 true 时，先用该库 query_rewrite 角色的模型把每条查询改写为简洁的检索查询；检索使用改写结果，search_query 返回改写后的查询。每次改写是一次小模型调用，按模型用量计费。改写失败、超时（5 秒）或为空时，该条查询回退为原文，搜索照常完成。省略或为 false 时不调用模型。
next_page	string	可选; 不生效: 搜索不支持翻页；提供游标不生效。
ranking_options	object	可选; 控制结果排序与纳入结果的最低分数。
ranking_options.ranker	"none" / "auto" / "default-2024-11-15"	可选; 只有 default-2024-11-15 请求重排；none、auto 和省略时使用初始排序。尚未单独实测重排效果。
ranking_options.score_threshold	number	可选; 最低分数；分数不是相关性概率。尚未单独实测阈值效果。; 最小: 0; 最大: 1; 默认: 0
ranking_options.hybrid_search	object	可选; Praxis 扩展。两个权重均须提供，必须非负且总和大于 0；省略时使用 0.7 / 0.3。; Praxis 扩展
ranking_options.hybrid_search.embedding_weight	number	必填; 语义检索相对权重；零表示禁用语义检索。; 最小: 0; 默认: 0.7
ranking_options.hybrid_search.text_weight	number	必填; 关键词检索相对权重；零表示禁用关键词检索。; 最小: 0; 默认: 0.3
praxis	object	可选; 设置 explain=true 返回分数和关键词解释。; Praxis 扩展
praxis.explain	boolean	可选; true 请求每条结果的分数、排名与关键词解释。; 默认: false

请求示例

curl -X POST "https://api.deepraxis.ai/knowledge/v1/vector_stores/${VECTOR_STORE_ID}/search" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"query\":\"When will I receive my refund?\",\"max_num_results\":5,\"praxis\":{\"explain\":true}}"

响应

HTTP 200

字段	类型	说明
object	"vector_store.search_results.page"	必有; 对象标记；vector_store.search_results.page 表示搜索结果页。
search_query	string[]	必有; 实际用于检索的查询，与输入一一对应；rewrite_query 为 true 时为改写后的查询，否则原样返回。
data	object[]	必有; 每个命中分段返回一条；同一 file_id 可重复出现。
data[].file_id	string	必有; 资源 ID。; 最短字符数: 1
data[].filename	string	必有; 命中文件的源文件名。
data[].score	number	必有; 此分段的相关排序分数，限制在 0 到 1；不是概率。; 最小: 0; 最大: 1
data[].attributes	object / null	必有; 用于筛选的当前文件属性；未设置时为 null。
data[].content	object[]	必有; 命中分段文本与源文坐标；原生结果每条包含一个分段。
data[].content[].type	"text"	必有; text 表示提取出的文本分段。
data[].content[].text	string	必有; 命中分段的提取文本，可能与相邻分段重叠。
data[].content[].chunk_id	string	可选; 资源 ID。; 最短字符数: 1
data[].content[].page	integer / null	可选; 此段起点所在的源文页码，从一开始；无页码映射时为 null。
data[].content[].span	integer[]	可选; 以 UTF-16 代码单元表示的起止位置。; 最少条数: 2; 最多条数: 2
data[].praxis	object	可选; 原生搜索解释；仅请求 praxis.explain 时返回。
data[].praxis.explain	object	必有; 每个命中分段的检索分数、排名与匹配词。
data[].praxis.explain.semantic_score	number / null	必有; 此段语义检索分数；不在语义候选中时为 null。
data[].praxis.explain.keyword_score	number / null	必有; 此段关键词检索分数；不在关键词候选中时为 null。
data[].praxis.explain.rerank_score	number / null	必有; 重排模型分数；未重排时为 null。
data[].praxis.explain.semantic_rank	integer / null	必有; 语义候选中的排名，从一开始；该路未召回时为 null。
data[].praxis.explain.keyword_rank	integer / null	必有; 关键词候选中的排名，从一开始；该路未召回时为 null。
data[].praxis.explain.rank_before_rerank	integer	必有; One-based fused rank before reranking; without reranking, the position among returned filtered results.; 最小: 1
data[].praxis.explain.query_terms	string[]	必有; 解释使用的归一化查询词，包括相邻汉字组成的双字词。
data[].praxis.explain.matched_terms	string[]	必有; 归一化分段文本中出现的查询词。
has_more	boolean	必有; 过滤后的分段数超过 max_num_results 时为 true；next_page 仍为 null。; 支持:
next_page	null	必有; 不生效: 恒为 null，没有下一页搜索结果。

分段

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

列出文件分段

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

列出附件已有分段，默认按分段序号升序。使用附件 id，并将 last_id 作为 after 继续查询；返回的分段 id 可单独读取。

参数

名称	位置与类型	说明
vector_store_id	path: string	必填；创建或列表返回的知识库 ID；不要使用显示名称。最短字符数: 1
file_id	path: string	必填；添加附件或附件列表返回的源 File ID。最短字符数: 1
after	query: string	上一页的 ID 游标。最短字符数: 1
before	query: string	返回此 ID 之前的条目。最短字符数: 1
limit	query: integer	每页条数。最小: 1; 最大: 100; 默认: 20
order	query: "asc" / "desc"	知识库和文件默认按创建时间降序；分段默认按序号升序。默认: "asc"

请求示例

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

响应

HTTP 200

字段	类型	说明
object	"list"	必有; 对象标记；list 表示游标分页集合。
data	object[]	必有; 按请求顺序返回的当前页条目。
data[].id	string	必有; 资源 ID。; 最短字符数: 1
data[].file_id	string	必有; 资源 ID。; 最短字符数: 1
data[].index	integer	必有; 此段在源文中的序号，从零开始。; 最小: 0
data[].text	string	必有; 此分段覆盖的提取文本；相邻分段可能重叠。
data[].tokens	integer	必有; 此段的估算 token 数，不是模型分词器计数。; 最小: 0
data[].page	integer / null	必有; 分段起点所在源文页码，从一开始；无页码映射时为 null。
data[].span	integer[]	必有; 以 UTF-16 代码单元表示的起止位置。; 最少条数: 2; 最多条数: 2
data[].overlap_prev_tokens	integer	必有; 与前段重叠的估算 token 数；首段为零。; 最小: 0
data[].overlap_next_tokens	integer	必有; 与后段重叠的估算 token 数；末段为零。; 最小: 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}/segments/{chunk_id}

读取一个分段及其词频统计。chunk_id 来自分段列表或原生搜索 content；分段必须属于此知识库。

参数

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

请求示例

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

响应

HTTP 200

字段	类型	说明
id	string	必有; 资源 ID。; 最短字符数: 1
file_id	string	必有; 资源 ID。; 最短字符数: 1
index	integer	必有; 此段在源文中的序号，从零开始。; 最小: 0
text	string	必有; 此分段覆盖的提取文本；相邻分段可能重叠。
tokens	integer	必有; 此段的估算 token 数，不是模型分词器计数。; 最小: 0
page	integer / null	必有; 分段起点所在源文页码，从一开始；无页码映射时为 null。
span	integer[]	必有; 以 UTF-16 代码单元表示的起止位置。; 最少条数: 2; 最多条数: 2
overlap_prev_tokens	integer	必有; 与前段重叠的估算 token 数；首段为零。; 最小: 0
overlap_next_tokens	integer	必有; 与后段重叠的估算 token 数；末段为零。; 最小: 0
terms	object[]	必有; 此段出现的关键词及其段内频次、全库包含段数。
terms[].term	string	必有; 小写文本词；连续汉字还生成相邻双字词。
terms[].count	integer	必有; 该词在此段中的出现次数。; 最小: 0
terms[].chunks_in_store	integer	必有; 此库索引中包含该词的分段数。; 最小: 0

事件

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

列出事件

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

按序号升序读取此知识库事件，软删除期间仍可读取。将 next_seq 作为 after_seq 继续查询；next_seq 为 null 表示当前已到末尾。例如 ?after_seq=0&limit=20。

参数

名称	位置与类型	说明
vector_store_id	path: string	必填；创建或列表返回的知识库 ID；不要使用显示名称。最短字符数: 1
after_seq	query: integer	返回 seq 更大的事件；使用 next_seq 继续。当前忽略非数字文本。默认: 0
limit	query: integer	每页条数。最小: 1; 最大: 100; 默认: 20

请求示例

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

响应

HTTP 200

字段	类型	说明
data	object[]	必有; seq 大于 after_seq 的事件，按 seq 升序返回。
data[].seq	integer	必有; 库内递增事件序号；将返回的 next_seq 作为 after_seq 继续查询。; 最小: 1
data[].id	string	必有; 服务端生成的事件 UUID。
data[].type	"vector_store.created" / "vector_store.updated" / "vector_store.expired" / "vector_store.deleted" / "vector_store.restored" / "file.attached" / "file.stage_changed" / "file.completed" / "file.failed" / "file.cancelled" / "file.removed" / "batch.created" / "batch.completed" / "batch.cancelled"	必有; 此知识库记录的库、文件入库或批次事件类别。
data[].processed_at	integer	必有; Unix 时间戳，单位秒。
data[].vector_store_id	string	必有; 资源 ID。; 最短字符数: 1
data[].file_id	string / null	必有; 关联的源 File ID；无关联文件时为 null。
data[].batch_id	string / null	必有; 关联的文件批次 ID；无关联批次时为 null。
data[].data	object	必有; 事件详情；阶段变化含 stage，入库失败含 code，其它事件可为空对象。
next_seq	integer / null	必有; 作为下一页的 after_seq；null 表示没有后续。