# 知识库 (/docs/api/native/knowledge/stores)



[快速开始：官方 Python SDK](/docs/cloud/services/knowledge/quickstart)

[基础地址与鉴权](/docs/api/native/knowledge)

路径中的 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）。 |

### 请求示例 [#请求示例]

```bash
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。 |

[错误码与错误对象](/docs/api/native/knowledge/errors)

## 列出知识库 [#列出知识库]

`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"       |

### 请求示例 [#请求示例-1]

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

### 响应 [#响应-1]

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 | 必有; 当前游标范围内，本页之后是否还有条目。 |

[错误码与错误对象](/docs/api/native/knowledge/errors)

## 读取知识库 [#读取知识库]

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

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

### 参数 [#参数-1]

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

### 请求示例 [#请求示例-2]

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

### 响应 [#响应-2]

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" | 必有 |
| (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 | 必有; 当前游标范围内，本页之后是否还有条目。 |

[错误码与错误对象](/docs/api/native/knowledge/errors)

## 更新知识库 [#更新知识库]

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

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

### 参数 [#参数-2]

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

### 请求体 [#请求体-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）。 |

### 请求示例 [#请求示例-3]

```bash
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\"}}"
```

### 响应 [#响应-3]

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。 |

[错误码与错误对象](/docs/api/native/knowledge/errors)

## 删除知识库 [#删除知识库]

`DELETE /knowledge/v1/vector_stores/{vector_store_id}`

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

### 参数 [#参数-3]

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

### 请求示例 [#请求示例-4]

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

### 响应 [#响应-4]

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。 |

[错误码与错误对象](/docs/api/native/knowledge/errors)

## 恢复知识库 [#恢复知识库]

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

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

### 参数 [#参数-4]

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

### 请求示例 [#请求示例-5]

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

### 响应 [#响应-5]

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。 |

[错误码与错误对象](/docs/api/native/knowledge/errors)

## 永久清除知识库 [#永久清除知识库]

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

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

### 参数 [#参数-5]

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

### 请求示例 [#请求示例-6]

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

### 响应 [#响应-6]

HTTP 200

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

[错误码与错误对象](/docs/api/native/knowledge/errors)