# 分段 (/docs/api/native/knowledge/segments)



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

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

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

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

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

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

## 读取分段 [#读取分段]

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

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

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

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

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

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

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

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 |

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