Pipeline語義聚類節點semantic-cluster - Cloud Monitor

資料集中的記錄缺少語義分組標識時，無法按語義類別進行採樣或分析。semantic-cluster 節點基於 Embedding 向量對記錄執行聚類，為每條記錄分配簇編號（__cluster_id），不過濾資料，僅添加分組標識。常與 sample 節點群組合實現多樣性採樣。

功能說明

semantic-cluster 節點對指定的 Embedding 向量列執行聚類運算，將語義相近的記錄歸入同一簇，每條記錄被分配一個從 0 開始的簇編號（__cluster_id）。節點不過濾資料，僅添加分組標識。

適用情境：

與 sample 節點群組合，實現兼顧降採樣與語義多樣性的代表性採樣。
資料分布分析：觀察語義簇的大小與分布。
語義分組：將相似記錄歸類，便於批量處理。

節點配置

以下為 semantic-cluster 節點的 JSON 配置樣本：

{
  "id": "node_1",
  "type": "semantic-cluster",
  "parameters": {
    "field": "<Embedding向量列名>",
    "n": "<聚類簇數>",
    "output": "<輸出資料行列表>"
  }
}

參數說明

參數	類型	必填	預設值	說明
`field`	String	是	無	聚類依據的 Embedding 向量列名，資料類型須為 `array(double)`。可來自 embedding 節點或 `dedup-semantic` 節點的 `__dedup_emb` 列。
`n`	Integer	是	無	聚類簇數，必須為正整數。取值建議參見下方簇數選擇建議。
`output`	String	否	`*`	節點輸出資料行，多列以英文逗號分隔。預設值 `*` 表示保留全部列（含擴充列）。指定時僅輸出資料行出的列。

簇數選擇建議

資料量	推薦 n 範圍
< 100	5 ~ 10
100 ~ 1,000	10 ~ 50
1,000 ~ 10,000	50 ~ 100
> 10,000	100 ~ 500

輸入和輸出

輸入要求

上遊節點輸出的任意列資料。
必須包含 field 參數指定的 Embedding 向量列，資料類型為 array(double)。
通常接在 embedding 節點或 dedup-semantic 節點（輸出 __dedup_emb 列）之後。

輸出資料行

列名	類型	來源	說明
`output` 控制列	--	透傳/新增	`*` 保留全部列（含擴充列）；指定時僅輸出資料行出的列。
`__cluster_id`	bigint	新增	聚類簇編號，從 0 開始。

行數變化

M → N（M = N）：1:1 變換，每行添加簇標識，不增減行數。

效果預覽

處理前（6 條）：

question	__dedup_emb
什麼是機器學習？	[0.12, -0.34, ...]
機器學習有哪些類型？	[0.15, -0.30, ...]
如何學習Python？	[0.78, 0.23, ...]
Python有哪些庫？	[0.75, 0.20, ...]
什麼是深度學習？	[-0.11, 0.45, ...]
神經網路是什嗎？	[-0.09, 0.42, ...]

處理後（6 條）：field = "__dedup_emb"，n = 3

question	__dedup_emb	__cluster_id
什麼是機器學習？	[0.12, -0.34, ...]	0
機器學習有哪些類型？	[0.15, -0.30, ...]	0
如何學習Python？	[0.78, 0.23, ...]	1
Python有哪些庫？	[0.75, 0.20, ...]	1
什麼是深度學習？	[-0.11, 0.45, ...]	2
神經網路是什嗎？	[-0.09, 0.42, ...]	2

行數不變（6 → 6），每行新增 __cluster_id 簇編號。語義相近的記錄分配到同一簇。下遊可接 sample 節點（by = "__cluster_id"）按簇取樣，實現多樣性採樣。

使用樣本

樣本 1：基礎聚類

將資料按 question_embedding 列聚為 10 簇。

{
  "id": "n5",
  "type": "semantic-cluster",
  "parameters": {
    "field": "question_embedding",
    "n": 10
  }
}

樣本 2：聚類 + 分組採樣（多樣性採樣）

聚為 100 簇，每簇取 1 條，輸出約 100 條多樣性代表樣本。

{
  "nodes": [
    { "id": "n1", "type": "project", "parameters": { "question": "a", "output": "c" } },
    { "id": "n2", "type": "embedding", "parameters": { "field": "question" } },
    { "id": "n3", "type": "semantic-cluster", "parameters": { "field": "question_embedding", "n": 100 } },
    { "id": "n4", "type": "sample", "parameters": { "by": "__cluster_id", "n": 1 } }
  ]
}

樣本 3：複用 dedup-semantic 的向量列

直接複用 dedup-semantic 節點輸出的 __dedup_emb 列作為聚類輸入，避免重複計算 Embedding 向量。

{
  "nodes": [
    { "id": "n1", "type": "project", "parameters": { "question": "a", "input": "b", "output": "c" } },
    { "id": "n2", "type": "dedup-exact", "parameters": { "field": "question" } },
    { "id": "n3", "type": "dedup-semantic", "parameters": { "field": "question", "threshold": "0.1" } },
    { "id": "n4", "type": "semantic-cluster", "parameters": { "field": "__dedup_emb", "n": 100 } },
    { "id": "n5", "type": "sample", "parameters": { "by": "__cluster_id", "n": 1 } }
  ]
}

注意事項

使用建議

多樣性採樣：與 sample 節點群組合，先聚類再按簇取樣，兼顧降採樣與語義多樣性。典型管道：dedup-semantic → semantic-cluster → sample（直接複用 __dedup_emb）。
向量列來源：輸入必須為 array(double) 類型的 Embedding 向量列，可來自 embedding 節點或 dedup-semantic 節點的 __dedup_emb 列。
簇數選擇：n 不宜過大（影響聚類效能），也不宜過小（簇過大失去多樣性意義）。具體取值參見上方簇數選擇建議表。
僅標註不過濾：本節點僅標註簇 ID，不改變行數。降採樣需通過下遊 sample 節點完成。

邊界與異常

情境	行為
`field` 缺失	校正失敗
`n` 缺失或 ≤ 0	校正失敗
`field` 類型非 `array(double)`	運行時報錯
`n` > 資料量	由引擎處理，通常上限為資料量
Embedding 維度不一致	運行時報錯
輸入資料為空白	正常返回空結果集

節點	關係說明
sample	聚類後接 `sample`（`by = "__cluster_id"`）實現多樣性採樣。
embedding	先通過 `embedding` 或 `dedup-semantic` 產生向量列。
dedup-semantic	可直接複用 `__dedup_emb` 列作為聚類輸入，避免重複計算 Embedding。