# 知识库 (/docs/api/compatible/openai/vector-stores)



官方 openai Python SDK 可直接使用知识库、文件和批次操作。两个地址访问同一份数据。

`https://api.deepraxis.ai/openai/v1`

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

## 当前差异 [#当前差异]

搜索按块返回，同一文件可能出现多次；max\_num\_results 计算块数。rewrite\_query 为 true 时先用小模型改写查询（按模型用量计费，失败时回退原查询），改写所用模型只能在原生 API 的 models 中设置，兼容接口传 models 返回 400。搜索 has\_more 恒为 false、next\_page 恒为 null。description 接受后丢弃。expand=files 与 expand\[]=files 为 Praxis 扩展；未知值忽略。

删除知识库后保留 7 天，读取仍可返回 200 completed，但写入和搜索返回 409。恢复、失败重试、分段、事件和混合搜索权重请使用原生 API；兼容接口不返回 praxis、chunk\_id、page 或 span。usage\_bytes 为抽取文本块的字节数。未知请求字段当前会被忽略。

[原生 API](/docs/api/native/knowledge) · [错误码](/docs/api/native/knowledge/errors)

| 方法     | 路径                                                                               | 操作     |
| ------ | -------------------------------------------------------------------------------- | ------ |
| POST   | /openai/v1/vector\_stores                                                        | 创建知识库  |
| GET    | /openai/v1/vector\_stores                                                        | 列出知识库  |
| GET    | /openai/v1/vector\_stores/\{vector\_store\_id}                                   | 读取知识库  |
| POST   | /openai/v1/vector\_stores/\{vector\_store\_id}                                   | 更新知识库  |
| DELETE | /openai/v1/vector\_stores/\{vector\_store\_id}                                   | 删除知识库  |
| POST   | /openai/v1/vector\_stores/\{vector\_store\_id}/search                            | 搜索知识库  |
| POST   | /openai/v1/vector\_stores/\{vector\_store\_id}/files                             | 添加文件   |
| GET    | /openai/v1/vector\_stores/\{vector\_store\_id}/files                             | 列出文件   |
| GET    | /openai/v1/vector\_stores/\{vector\_store\_id}/files/\{file\_id}                 | 读取文件   |
| POST   | /openai/v1/vector\_stores/\{vector\_store\_id}/files/\{file\_id}                 | 更新文件属性 |
| DELETE | /openai/v1/vector\_stores/\{vector\_store\_id}/files/\{file\_id}                 | 移除文件   |
| GET    | /openai/v1/vector\_stores/\{vector\_store\_id}/files/\{file\_id}/content         | 读取抽取内容 |
| POST   | /openai/v1/vector\_stores/\{vector\_store\_id}/file\_batches                     | 创建文件批次 |
| GET    | /openai/v1/vector\_stores/\{vector\_store\_id}/file\_batches/\{batch\_id}        | 读取文件批次 |
| POST   | /openai/v1/vector\_stores/\{vector\_store\_id}/file\_batches/\{batch\_id}/cancel | 取消文件批次 |
| GET    | /openai/v1/vector\_stores/\{vector\_store\_id}/file\_batches/\{batch\_id}/files  | 列出批次文件 |

## 创建知识库 [#创建知识库]

`POST /openai/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 | 可选; 不生效: 接受后丢弃，不保存也不返回；当前不校验类型。 |

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

```bash
curl -X POST "https://api.deepraxis.ai/openai/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" | 必有; in_progress 表示仍有文件入库中；completed 表示没有入库中的文件，不保证全部成功；expired 表示过期策略已生效。 |
| 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 |

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

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

`GET /openai/v1/vector_stores`

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

### 参数 [#参数]

| 名称     | 位置与类型                 | 说明                                    |
| ------ | --------------------- | ------------------------------------- |
| 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/openai/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" | 必有; in_progress 表示仍有文件入库中；completed 表示没有入库中的文件，不保证全部成功；expired 表示过期策略已生效。 |
| 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 |
| first_id | string / null | 必有; 本页首项的 ID；空页为 null。 |
| last_id | string / null | 必有; 本页末项的 ID，可作为 after 继续查询；空页为 null。 |
| has_more | boolean | 必有; 当前游标范围内，本页之后是否还有条目。 |

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

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

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

使用创建或列表返回的 id 读取知识库。添加 ?expand=files 可同时返回附件首页。已删除的库返回 404。

### 参数 [#参数-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/openai/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" | 必有; in_progress 表示仍有文件入库中；completed 表示没有入库中的文件，不保证全部成功；expired 表示过期策略已生效。 |
| (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 |
| (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.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 /openai/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 |

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

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

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

HTTP 200

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | string | 必有; 资源 ID。; 最短字符数: 1 |
| object | "vector_store" | 必有; 对象标记；vector_store 表示知识库。 |
| name | string | 必有; 知识库显示名称；空字符串表示未设置名称。; 最长字符数: 256 |
| status | "in_progress" / "completed" / "expired" | 必有; in_progress 表示仍有文件入库中；completed 表示没有入库中的文件，不保证全部成功；expired 表示过期策略已生效。 |
| 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 |

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

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

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

删除后读取和重复 DELETE 返回 404 not\_found\_error，列表不含已删除库；自有面可在 7 天内恢复。

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

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

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

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

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

HTTP 200

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | string | 必有; 资源 ID。; 最短字符数: 1 |
| object | "vector_store.deleted" | 必有; 对象标记；vector_store.deleted 表示此操作回执。 |
| deleted | true | 必有; 确认兼容面的知识库删除；后续访问返回未找到。 |

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

## 搜索知识库 [#搜索知识库]

`POST /openai/v1/vector_stores/{vector_store_id}/search`

每文件一条，content 为按分数降序的命中块；max\_num\_results 计文件，从最多 50 个召回分段聚合。has\_more 表示文件结果截断，next\_page 仍为 null。

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

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

### 请求体 [#请求体-2]

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| 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 | 可选; 从最多 50 个召回分段聚合后，最多返回的不同文件数。; 最小: 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 | 可选; 不支持: 在 /openai/v1 返回 400 INVALID_PARAMS；设置权重请使用 /knowledge/v1。; Praxis 扩展 |
| ranking_options.hybrid_search.embedding_weight | number | 必填; 语义检索相对权重；零表示禁用语义检索。; 最小: 0; 默认: 0.7 |
| ranking_options.hybrid_search.text_weight | number | 必填; 关键词检索相对权重；零表示禁用关键词检索。; 最小: 0; 默认: 0.3 |
| praxis | object | 可选; 不生效: 兼容响应会删除 praxis，包括搜索解释。 |
| praxis.explain | boolean | 可选; 请求生成解释；兼容响应不返回这些解释。 |

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

```bash
curl -X POST "https://api.deepraxis.ai/openai/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}"
```

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

HTTP 200

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| object | "vector_store.search_results.page" | 必有; 对象标记；vector_store.search_results.page 表示搜索结果页。 |
| search_query | string[] | 必有; 实际用于检索的查询，与输入一一对应；rewrite_query 为 true 时为改写后的查询，否则原样返回。 |
| data | object[] | 必有; 每个文件返回一条；content 包含该文件命中的分段。 |
| data[].file_id | string | 必有; 资源 ID。; 最短字符数: 1 |
| data[].filename | string | 必有; 命中文件的源文件名。 |
| data[].score | number | 必有; 该文件命中分段的最高分数。; 最小: 0; 最大: 1 |
| data[].attributes | object / null | 必有; 用于筛选的当前文件属性；未设置时为 null。 |
| data[].content | object[] | 必有; 按分段分数降序排列的命中分段。 |
| data[].content[].type | "text" | 必有; text 表示提取出的文本分段。 |
| data[].content[].text | string | 必有; 命中分段的提取文本，可能与相邻分段重叠。 |
| has_more | boolean | 必有; 过滤后的文件数超过 max_num_results 时为 true；next_page 仍为 null。; 支持:  |
| next_page | null | 必有; 不生效: 恒为 null，没有下一页搜索结果。 |

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

## 添加文件 [#添加文件]

`POST /openai/v1/vector_stores/{vector_store_id}/files`

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

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

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

### 请求体 [#请求体-3]

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| 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 |

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

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

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

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 表示未设置。 |

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

## 列出文件 [#列出文件]

`GET /openai/v1/vector_stores/{vector_store_id}/files`

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

### 参数 [#参数-6]

| 名称                | 位置与类型                                                        | 说明                                                                                    |
| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| 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 表示批次取消已停止入库。省略时包含全部状态。 |

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

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

### 响应 [#响应-7]

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 表示未设置。 |
| first_id | string / null | 必有; 本页首项的 ID；空页为 null。 |
| last_id | string / null | 必有; 本页末项的 ID，可作为 after 继续查询；空页为 null。 |
| has_more | boolean | 必有; 当前游标范围内，本页之后是否还有条目。 |

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

## 读取文件 [#读取文件]

`GET /openai/v1/vector_stores/{vector_store_id}/files/{file_id}`

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

### 参数 [#参数-7]

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

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

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

### 响应 [#响应-8]

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 表示未设置。 |

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

## 更新文件属性 [#更新文件属性]

`POST /openai/v1/vector_stores/{vector_store_id}/files/{file_id}`

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

### 参数 [#参数-8]

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

### 请求体 [#请求体-4]

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

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

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

### 响应 [#响应-9]

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 表示未设置。 |

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

## 移除文件 [#移除文件]

`DELETE /openai/v1/vector_stores/{vector_store_id}/files/{file_id}`

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

### 参数 [#参数-9]

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

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

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

### 响应 [#响应-10]

HTTP 200

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

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

## 读取抽取内容 [#读取抽取内容]

`GET /openai/v1/vector_stores/{vector_store_id}/files/{file_id}/content`

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

### 参数 [#参数-10]

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

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

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

### 响应 [#响应-11]

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；提取内容不分页。 |

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

## 创建文件批次 [#创建文件批次]

`POST /openai/v1/vector_stores/{vector_store_id}/file_batches`

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

### 参数 [#参数-11]

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

### 请求体 [#请求体-5]

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 时不生效。 |

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

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

### 响应 [#响应-12]

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 时间戳，单位秒。 |

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

## 读取文件批次 [#读取文件批次]

`GET /openai/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}`

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

### 参数 [#参数-12]

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

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

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

### 响应 [#响应-13]

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 时间戳，单位秒。 |

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

## 取消文件批次 [#取消文件批次]

`POST /openai/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel`

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

### 参数 [#参数-13]

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

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

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

### 响应 [#响应-14]

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 时间戳，单位秒。 |

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

## 列出批次文件 [#列出批次文件]

`GET /openai/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/files`

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

### 参数 [#参数-14]

| 名称                | 位置与类型                                                        | 说明                                                                                    |
| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| 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 表示批次取消已停止入库。省略时包含全部状态。 |

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

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

### 响应 [#响应-15]

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 表示未设置。 |
| first_id | string / null | 必有; 本页首项的 ID；空页为 null。 |
| last_id | string / null | 必有; 本页末项的 ID，可作为 after 继续查询；空页为 null。 |
| has_more | boolean | 必有; 当前游标范围内，本页之后是否还有条目。 |

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