# 创建分段

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

在来源当前快照中创建一个分段。可按来源内容提供一个新的文本、OCR 或图片描述分段。

```text
POST https://api.moi.matrixorigin.cn/v5/semantic-models/{model_id}/sources/{source_row_id}/segments
```

## 调用前准备

先[查询文档详情](get-document.md)，取得 `data.etag` 作为条件写入的基线。准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

来源必须是文件来源，已有知识库文件标识 `kb_file_id`，并配置了可用的向量索引。表来源不支持分段写入。

## 请求示例

示例中的凭据和资源标识需替换为当前调用者的实际值。

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/semantic-models/$MODEL_ID/sources/$SOURCE_ROW_ID/segments" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
  "if_match": "<DOCUMENT_ETAG>",
  "level": "chunk",
  "content": "<SEGMENT_CONTENT>"
}'
```

## 路径参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `model_id` | integer | 是 | 所属知识库 ID。 |
| `source_row_id` | string | 是 | 来源记录 ID。 |

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `if_match` | string | 否 | 调用前读取的 `data.etag`；使用 `If-Match` 请求头时可省略。 |
| `level` | string | 否 | 分段层级；省略时为 `chunk`；取值：`doc`、`section`、`chunk`、空字符串。 |
| `content` | string 或 null | 否 | 文本分段内容。 |
| `ocr_text` | string 或 null | 否 | OCR 识别出的文本。 |
| `image_description` | string 或 null | 否 | 图片内容说明。 |
| `image_file_id` | null | 否 | 当前不支持通过此请求指定图片文件，省略或填 null。 |
| `page_image_file_id` | null | 否 | 当前不支持通过此请求指定页面图片，省略或填 null。 |
| `bbox` | 任意 JSON | 否 | 分段在原内容中的边界信息，可使用对象、数组等 JSON 值。 |
| `metadata` | object | 否 | 自定义元数据对象；省略时由服务生成所需信息，系统管理的字段以服务写入值为准。 |

分段层级接受 `doc`、`section` 和 `chunk`，省略时使用 `chunk`。当前持久化只支持 `chunk`；在来源、索引与内容等前置检查通过后，`doc` 或 `section` 会在生成嵌入向量后的保存阶段失败。不能将请求被接收理解为这些层级已保存成功。

## 成功响应

请求成功时返回 HTTP 200，响应如下。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "document": {
      "source": {
        "row_id": "src_01",
        "source_type": "file",
        "model_id": 401,
        "resource_id": "",
        "display_name": null,
        "path": [],
        "db_name": null,
        "table_name": null,
        "size_bytes": null,
        "row_count": null,
        "ingest_status": null,
        "enabled": null,
        "expires_at": null,
        "expired": false,
        "effective_enabled": false,
        "force_enabled_after_expiry": false,
        "updated_at": null,
        "error": null
      },
      "preview": {
        "available": false
      },
      "file_info": {
        "tags": null,
        "expires_at": null,
        "enabled": null,
        "expired": false,
        "effective_enabled": false,
        "force_enabled_after_expiry": false
      },
      "segment_status": {
        "available": true,
        "total": 3
      },
      "etag": "<NEW_DOCUMENT_ETAG>",
      "segments": [
        {
          "segment_id": "seg_03",
          "level": "chunk",
          "content": "新增分段",
          "word_count": 0,
          "recall_count": 0,
          "enabled": true
        }
      ]
    }
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.document` | object | 写入后的来源文档快照。 |
| `data.document.source` | object | 来源。 |
| `data.document.source.row_id` | string | 记录ID。 |
| `data.document.source.source_id` | string | 来源 ID。 无值时可省略。 |
| `data.document.source.source_type` | string | 来源类型；取值：`file`、`table`。 |
| `data.document.source.model_id` | integer | 模型ID；有符号 64 位整数。 |
| `data.document.source.resource_id` | string | 资源ID。 |
| `data.document.source.source_resource_id` | string | 来源资源ID。 无值时可省略。 |
| `data.document.source.kb_resource_id` | string | 知识库资源ID。 无值时可省略。 |
| `data.document.source.source_file_id` | string | 来源文件ID。 无值时可省略。 |
| `data.document.source.kb_file_id` | string | 知识库文件ID。 无值时可省略。 |
| `data.document.source.source_table_id` | integer | 来源表ID；有符号 64 位整数。 无值时可省略。 |
| `data.document.source.kb_table_id` | integer | 知识库表ID；有符号 64 位整数。 无值时可省略。 |
| `data.document.source.display_name` | string 或 null | 展示名称。 |
| `data.document.source.path` | string（字符串数组） | 路径。 |
| `data.document.source.source_path` | string | 来源路径。 无值时可省略。 |
| `data.document.source.db_name` | string 或 null | 数据库名称。 |
| `data.document.source.table_name` | string 或 null | 表名称。 |
| `data.document.source.size_bytes` | integer 或 null | 字节大小；有符号 64 位整数。 |
| `data.document.source.row_count` | integer 或 null | 行数；有符号 64 位整数。 |
| `data.document.source.ingest_status` | string 或 null | 导入状态；取值：`removed`、`pending`、`succeeded`、`failed`。 |
| `data.document.source.enabled` | boolean 或 null | 是否启用。 |
| `data.document.source.expires_at` | integer 或 null | 过期时间；有符号 64 位整数。 |
| `data.document.source.expired` | boolean | 是否已过期。 |
| `data.document.source.effective_enabled` | boolean | 实际启用状态。 |
| `data.document.source.force_enabled_after_expiry` | boolean | 过期后是否强制启用。 |
| `data.document.source.tags` | string（字符串数组） | 标签列表。 无值时可省略。 |
| `data.document.source.created_by` | string | 创建者。 无值时可省略。 |
| `data.document.source.updated_by` | string | 最近更新者。 无值时可省略。 |
| `data.document.source.updated_at` | integer 或 null | 更新时间；有符号 64 位整数。 |
| `data.document.source.error` | string 或 null | 错误信息。 |
| `data.document.source.governance_status` | string | 管理状态；取值：`managed`、`legacy_unbound`。 无值时可省略。 |
| `data.document.source.legacy_origin` | string | 旧来源信息；取值：`semantic_model_explicit`、`lineage_register`。 无值时可省略。 |
| `data.document.preview` | object | 预览内容。 |
| `data.document.preview.available` | boolean | 是否可用。 |
| `data.document.preview.content` | string | 业务内容。 无值时可省略。 |
| `data.document.preview.reason` | string | 原因。 无值时可省略。 |
| `data.document.file_info` | object | 文件信息。 |
| `data.document.file_info.tags` | string（字符串数组） 或 null | 标签列表。 |
| `data.document.file_info.expires_at` | integer 或 null | 过期时间；有符号 64 位整数。 |
| `data.document.file_info.enabled` | boolean 或 null | 是否启用。 |
| `data.document.file_info.expired` | boolean | 是否已过期。 |
| `data.document.file_info.effective_enabled` | boolean | 实际启用状态。 |
| `data.document.file_info.force_enabled_after_expiry` | boolean | 过期后是否强制启用。 |
| `data.document.segment_status` | object | 分段状态。 |
| `data.document.segment_status.available` | boolean | 是否可用。 |
| `data.document.segment_status.reason` | string | 原因。 无值时可省略。 |
| `data.document.segment_status.total` | integer | 符合当前查询条件的记录数；有符号 64 位整数。 |
| `data.document.segment_status.next_cursor` | string | 下一页游标。 无值时可省略。 |
| `data.document.etag` | string | 对象ETag。 无值时可省略。 |
| `data.document.segments` | object（对象数组） | 分段列表。 |
| `data.document.segments[].segment_id` | string | 分段ID。 |
| `data.document.segments[].start_ms` | integer | 开始毫秒位置；有符号 64 位整数。 无值时可省略。 |
| `data.document.segments[].end_ms` | integer | 结束毫秒位置；有符号 64 位整数。 无值时可省略。 |
| `data.document.segments[].level` | string | 级别；取值：`chunk`。 |
| `data.document.segments[].chunk_index` | integer | 内容块序号；有符号 64 位整数。 无值时可省略。 |
| `data.document.segments[].chunk_id` | string | 内容块ID。 无值时可省略。 |
| `data.document.segments[].content` | string | 业务内容。 无值时可省略。 |
| `data.document.segments[].ocr_text` | string | OCR文本。 无值时可省略。 |
| `data.document.segments[].image_description` | string | 图像说明。 无值时可省略。 |
| `data.document.segments[].image_file_id` | string | 图像文件ID。 无值时可省略。 |
| `data.document.segments[].page_image_file_id` | string | 页面图像文件ID。 无值时可省略。 |
| `data.document.segments[].word_count` | integer | 字数；有符号 64 位整数。 |
| `data.document.segments[].recall_count` | integer | 召回次数；有符号 64 位整数。 |
| `data.document.segments[].enabled` | boolean | 是否启用。 |
| `data.document.segments[].metadata` | object | 扩展元数据。 无值时可省略。 |
| `data.document.segments[].metadata.volume_id` | 任意 JSON | 卷ID。 |

字段路径中的 `[]` 表示数组中的每一项。

## 错误响应

未提供有效 ETag 时返回 `400` 和 `ErrParamInvalid`；ETag 与当前快照不一致时返回 `409` 和 `ErrConflict`。错误信息随请求语言变化。

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "ErrParamInvalid",
  "msg": "<ERROR_MESSAGE>",
  "data": null
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 错误代码。 |
| `msg` | string | 面向调用者的错误信息。 |
| `data` | null | 发生错误时为 `null`。 |

:::::
::::::
:::::::

## 后续操作

[查询文档详情](get-document.md)确认新分段已生效。继续修改时使用新快照的 ETag；旧 ETag 与当前快照不一致时返回 `409` 和 `ErrConflict`，应重读快照并确认修改内容。