设为当前分段版本

将一个已存在的分段版本切换为来源当前版本。

PATCH https://api.moi.matrixorigin.cn/v5/semantic-models/{model_id}/sources/{source_row_id}/segment-versions/{version_id}/current

调用前准备

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

请求体

请求示例

curl -X PATCH "https://api.moi.matrixorigin.cn/v5/semantic-models/$MODEL_ID/sources/$SOURCE_ROW_ID/segment-versions/$VERSION_ID/current" \
  -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>
  }'

参数说明

路径参数

字段	类型	必填	说明
model_id	integer	是	知识库 ID。
source_row_id	string	是	来源记录 ID。
version_id	string	是	要切换到的分段版本 ID。

请求体

提交来源当前的版本基线。version_id 指向要切换到的版本，不应替代基线字段。

字段	类型	必填	说明
base_segment_version_id	string	是	调用前读取到的当前分段版本 ID。
base_index_version	integer	是	调用前读取到的当前索引版本。

成功响应

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

响应示例

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "document": {
      "source": {
        "row_id": "src_01",
        "model_id": 401
      },
      "segment_status": {
        "available": true,
        "total": 2
      },
      "current_segment_version_id": "ver_01",
      "current_index_version": 1,
      "segment_versions": [
        {
          "version_id": "ver_01",
          "current": true,
          "index_version": 1
        },
        {
          "version_id": "ver_02",
          "current": false,
          "index_version": 2
        }
      ],
      "segments": [
        {
          "segment_id": "seg_01",
          "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	分段状态；包含 available、reason、total。
current_segment_version_id	string	已切换到的当前分段版本 ID。
current_index_version	integer	当前索引版本。
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 或 null	分段内容。
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": "ErrNotFound",
  "msg": "resource not found",
  "data": null
}

字段说明

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

后续操作

查询文档详情确认当前分段版本已切换。

最后更新于 2026 年 9 月 11 日