更新分段

更新指定分段的内容。版本基线用于避免覆盖较新的修改。

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

调用前准备

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

请求体

请求示例

curl -X PATCH "https://api.moi.matrixorigin.cn/v5/semantic-models/$MODEL_ID/sources/$SOURCE_ROW_ID/segments/$SEGMENT_ID" \
  -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>,
    "content": "<SEGMENT_CONTENT>"
  }'

参数说明

路径参数

字段	类型	必填	说明
model_id	integer	是	知识库 ID。
source_row_id	string	是	来源记录 ID。
segment_id	string	是	要更新的分段 ID。

请求体

提交来源当前的版本基线，以及要更新的文本、OCR 文本或图片描述。

字段	类型	必填	说明
base_segment_version_id	string	是	调用前读取到的当前分段版本 ID。
base_index_version	integer	是	调用前读取到的当前索引版本。
content	string	否	更新后的文本内容。
ocr_text	string	否	更新后的 OCR 文本。
image_description	string	否	更新后的图片描述。

成功响应

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

响应示例

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "document": {
      "source": {
        "row_id": "src_01",
        "model_id": 401
      },
      "segment_status": {
        "available": true,
        "total": 2
      },
      "segment_versions": [
        {
          "version_id": "ver_02",
          "current": true,
          "chunk_count": 2
        }
      ],
      "segments": [
        {
          "segment_id": "seg_01",
          "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": "ErrConflict",
  "msg": "segment version conflict",
  "data": null
}

字段说明

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

后续操作

查询文档详情确认更新结果。

最后更新于 2026 年 9 月 11 日