重新向量化

重新对来源分段执行向量化。请求提交成功后仍需读取来源或处理任务状态确认实际结果。

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

调用前准备

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

请求体

请求示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/semantic-models/$MODEL_ID/sources/$SOURCE_ROW_ID/segments/re-embedding" \
  -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。

请求体

提交来源当前的版本基线。

字段	类型	必填	说明
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,
        "ingest_status": "processing"
      },
      "segment_status": {
        "available": true,
        "total": 2
      },
      "current_segment_version_id": "ver_03",
      "current_index_version": 3,
      "segment_versions": [
        {
          "version_id": "ver_03",
          "current": true,
          "index_version": 3,
          "chunk_count": 2
        }
      ],
      "segments": [
        {
          "segment_id": "seg_01",
          "enabled": true
        }
      ]
    }
  }
}

字段说明

通用字段

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

操作结果

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

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

文档概览

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

字段	类型	说明
source	object	来源记录；固定字段为 row_id、source_id、source_type、model_id、资源 ID、路径、状态、启用、到期、标签、版本、审计、错误和治理字段；逐字段类型见查询文档详情。
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	当前分段版本。
current_index_version	integer 或 null	当前索引版本。
selected_segment_version_id	string 或 null	本次返回选择的分段版本。
selected_index_version	integer 或 null	本次返回选择的索引版本。
segment_versions	array of object	当前可用分段版本；每项包含 version_id、current、index_version、基线版本、状态、来源、分段计数、审计字段。
segments	array of object	当前版本中的分段。

来源记录

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

字段	类型	说明
row_id	string	来源记录 ID。
model_id	integer	所属知识库 ID。
ingest_status	string 或 null	当前处理状态；不以 HTTP 成功替代处理完成。

分段状态

下面表格展开响应示例中 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": "ErrConflict",
  "msg": "segment version conflict",
  "data": null
}

字段说明

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

后续操作

向量化是异步执行。通过查询数据处理任务或查询文档详情确认向量化的最终结果。

最后更新于 2026 年 9 月 11 日