创建分段

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

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

调用前准备

先查询文档详情，取得当前分段版本 ID 和索引版本作为基线。准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

请求体

请求示例

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 '{
    "base_segment_version_id": "<SEGMENT_VERSION_ID>",
    "base_index_version": <INDEX_VERSION>,
    "level": "chunk",
    "content": "<SEGMENT_CONTENT>"
  }'

参数说明

路径参数

字段	类型	必填	说明
model_id	integer	是	知识库 ID。
source_row_id	string	是	来源记录 ID。

请求体

提交来源当前的版本基线和分段内容。

字段	类型	必填	说明
base_segment_version_id	string	是	调用前读取到的当前分段版本 ID。
base_index_version	integer	是	调用前读取到的当前索引版本。
level	string	否	分段层级。
content	string	否	文本分段内容。
ocr_text	string	否	OCR 识别出的文本。
image_description	string	否	图片内容说明。
image_file_id	string	否	关联图片文件 ID。
page_image_file_id	string	否	关联页面图片文件 ID。
bbox	object	否	json.RawMessage 开放键值边界信息；服务端按原样接收，不定义固定子字段。
metadata	object	否	json.RawMessage 开放键值元数据；服务端按原样接收，不定义固定子字段。

成功响应

成功时返回 200 和更新后的来源文档快照。

响应示例

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "document": {
      "source": {
        "row_id": "src_01",
        "model_id": 401
      },
      "segment_status": {
        "available": true,
        "total": 3
      },
      "segment_versions": [
        {
          "version_id": "ver_03",
          "current": true,
          "chunk_count": 3
        }
      ],
      "segments": [
        {
          "segment_id": "seg_03",
          "segment_type": "text",
          "level": "chunk",
          "content": "新增分段",
          "enabled": true
        }
      ]
    }
  }
}

字段说明

通用字段

字段	类型	说明
code	string	成功时为 OK。
msg	string	成功时为 OK。
data	object	本次操作的返回数据。

操作结果

下面表格展开响应示例中 data 对象；每一行是该对象的一个字段。

字段	类型	说明
document	object	写入后的来源文档快照。

文档概览

下面表格展开响应示例中 data.document 对象；每一行是该对象的一个字段。

字段	类型	说明
source	object	来源记录；完整固定字段见查询文档详情的 data.source。
preview	object	来源内容预览；包含 available、content 和 reason。
file_info	object	文件信息；包含 tags、expires_at、enabled、expired、effective_enabled、force_enabled_after_expiry、index_version 和 segment_version_id。
segment_status	object	当前分段可用状态和总数。
current_segment_version_id	string 或 null	当前分段版本 ID。
current_index_version	integer 或 null	当前索引版本。
selected_segment_version_id	string 或 null	本次返回选择的分段版本 ID。
selected_index_version	integer 或 null	本次返回选择的索引版本。
segment_versions	array of object	所有分段版本。
segments	array of object	当前版本中的分段。

来源记录

下面表格展开响应示例中 data.document.source 对象；每一行是该对象的一个字段。

字段	类型	说明
row_id	string	来源记录 ID。
model_id	integer	所属知识库 ID。

分段状态

下面表格展开响应示例中 data.document.segment_status 对象；每一行是该对象的一个字段。

字段	类型	说明
available	boolean	分段是否可用。
reason	string 或 null	分段不可用原因。
total	integer	当前分段数量。

分段版本

下面表格展开响应示例中 data.document.segment_versions 数组的每一项；每一行是该数组项的一个字段。

字段	类型	说明
version_id	string	新建或更新后的分段版本 ID。
current	boolean	是否为当前分段版本。
index_version	integer 或 null	索引版本。
base_version_id	string 或 null	基线分段版本 ID。
base_index_version	integer 或 null	基线索引版本。
status	string	版本状态。
source	string	版本来源。
chunk_count	integer	分段总数。
enabled_chunk_count	integer	已启用分段数。
created_by	string 或 null	创建者 ID。
updated_by	string 或 null	最后更新者 ID。
created_at	integer 或 null	创建时间。
updated_at	integer 或 null	最近更新时间。

分段内容

下面表格展开响应示例中 data.document.segments 数组的每一项；每一行是该数组项的一个字段。

字段	类型	说明
segment_id	string	新分段 ID。
segment_type	string	分段类型。
start_ms	integer 或 null	起始时间或位置。
end_ms	integer 或 null	结束时间或位置。
level	string	分段层级。
chunk_index	integer 或 null	分段序号。
chunk_id	string 或 null	块 ID。
content	string	分段文本；内容未返回时可能省略。
ocr_text	string 或 null	OCR 文本。
image_description	string 或 null	图片描述。
image_file_id	string 或 null	图片文件 ID。
page_image_file_id	string 或 null	页图片文件 ID。
word_count	integer	词数。
recall_count	integer	召回次数。
enabled	boolean	分段是否参与检索。
metadata	object	json.RawMessage 开放键值元数据；服务端不定义固定子字段。

错误响应

响应示例

{
  "code": "ErrParamInvalid",
  "msg": "invalid segment version baseline",
  "data": null
}

字段说明

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

后续操作

查询文档详情确认新分段已生效。

最后更新于 2026 年 9 月 11 日