数据集中的记录缺少语义分组标识时，无法按语义类别进行采样或分析。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": "<输出列列表>"
}
}参数说明
参数 | 类型 | 必填 | 默认值 | 说明 |
| String | 是 | 无 | 聚类依据的 Embedding 向量列名，数据类型须为 |
| Integer | 是 | 无 | 聚类簇数，必须为正整数。取值建议参见下方簇数选择建议。 |
| 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列）之后。
输出列
列名 | 类型 | 来源 | 说明 |
| -- | 透传/新增 |
|
| 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节点完成。
边界与异常
场景 | 行为 |
| 校验失败 |
| 校验失败 |
| 运行时报错 |
| 由引擎处理，通常上限为数据量 |
Embedding 维度不一致 | 运行时报错 |
输入数据为空 | 正常返回空结果集 |