模型训练与在线推理
按你已有的条件选择路径:
- 已有 HTTP 模型服务:使用下面的
external模型接入,不需要 SQLRec 训练、导出或部署推理容器。 - 需要 SQLRec 训练并部署模型:先准备服务环境,再按训练型模型流程操作。
- 使用 Hugging Face 模型:下载 Hub 快照后直接创建服务,见后端差异。
接入已有 HTTP 模型服务
准备 SQLRec 可访问的推理地址,并声明服务的输入、输出字段:
CREATE MODEL external_rank_model (
user_id BIGINT,
item_id BIGINT,
category VARCHAR,
price DOUBLE
) WITH (
'model' = 'external',
'output_columns' = 'score:FLOAT'
);
CREATE SERVICE `external-rank-service`
ON MODEL external_rank_model
WITH (
'url' = 'http://rank-service:8080/predict'
);本地文件模式将两份定义分别保存为 model/external_rank_model.sql 和 service/external-rank-service.sql,放在完整的 SQL_SCHEMA_DIR 下并重启;加载方法见Docker 指南。远程元数据模式通过 Beeline 或 JDBC 执行定义。
先准备包含上述字段的 rank_input 缓存表,再调用服务。用空表声明输出结构:
CACHE TABLE external_rank_output AS
SELECT *, CAST(NULL AS FLOAT) AS score FROM rank_input LIMIT 0;
CACHE TABLE result_table AS
CALL call_service('external-rank-service', rank_input)
LIKE external_rank_output;结果保留输入列,并追加 score。仅接入已有服务时,不需要 Kubernetes 训练环境;推理服务仍须遵循以下协议。
HTTP 推理协议(服务提供方)
服务接受 POST 请求。单表调用发送 JSON 对象数组,只包含 Model 声明的输入字段:
[
{"user_id": 1, "item_id": 101, "category": "phone", "price": 3999.0},
{"user_id": 1, "item_id": 102, "category": "tablet", "price": 2999.0}
]输入表中已有字段的 SQL NULL 值会作为显式 JSON null 发送,不会省略该键;输入表中不存在的字段不生成对应键。服务提供方应按模型约定处理空值,TZRec、GBDT 和 Hugging Face 的输入要求见内置模型。
服务返回按输出字段组织的 JSON 数组;每个数组长度必须与输入行数一致,顺序与输入对应:
{"score": [0.85, 0.72]}使用下方的 User-Item 调用形式时,请求为列式 JSON,User 字段为单元素数组,Item 字段按行排列:
{
"user_id": [1],
"item_id": [101, 102],
"category": ["phone", "tablet"],
"price": [3999.0, 2999.0]
}选择模型后端
| 模型类型 | 数据来源 | TRAIN MODEL | EXPORT MODEL | 服务使用的 Checkpoint |
|---|---|---|---|---|
| tzrec WideAndDeep / DeepFM / DSSM / MMoE / RocketLaunching | SQL 表 | 训练 | 需要 | export |
| LightGBM / XGBoost / CatBoost | SQL 表 | 训练 | 需要 | export |
| Hugging Face Transformers | Hub 快照 | 下载,不需要 ON 表 | 不支持 | origin |
| external | 已有 HTTP 服务 | 不支持 | 不支持 | 不需要 |
配置参数见内置模型。
核心对象
| 对象 | 作用 |
|---|---|
| Model | 保存模型类型、输入字段、模型契约及默认配置 |
| Checkpoint | 一次训练、下载或导出产生的版本化结果 |
| Service | 将指定 Checkpoint 部署为可调用的在线服务 |
Checkpoint 有两种类型:
origin:训练或下载产生的原始结果。export:由EXPORT MODEL生成、可供 tzrec 或 GBDT 在线服务加载的结果。
Checkpoint 名称是用户自定义的版本标识。TRAIN 同名运行中或成功任务直接复用,失败重试保留存储目录,并按本次 SQL 参数重新提交;需要重新提供训练数据和参数。EXPORT 同名目标在校验通过后清理并重新导出,被服务引用的目标不能覆盖。源和目标须不同,导出源须为成功的 origin checkpoint。
新任务使用新的 checkpoint 名称。目标存储路径已存在、但没有对应 checkpoint 记录时,操作会失败;请先确认已有数据的来源再重试。
checkpoint 的 created 表示已提交、尚未确认完成。导出或创建服务前,先确认状态为 succeeded;创建服务后也需确认工作负载就绪,再发送推理请求。
训练型模型的完整流程
以下训练、导出和自托管服务部署需要完整服务环境,包括 Kubernetes 和模型存储。Docker Demo 不提供这些组件。执行前还需准备可访问的 training_sample 训练表,字段与模型定义兼容。
TZRec 样本按样本数据格式准备。训练入口不额外扫描训练集或验证集标签,标签类型、取值和正负样本要求须在生成数据时保证。
1. 创建模型
CREATE MODEL rank_model (
user_id BIGINT,
item_id BIGINT,
category VARCHAR,
price DOUBLE,
is_click INT
) WITH (
'model' = 'tzrec.wide_and_deep',
'label_columns' = 'is_click'
);训练数据须包含 label_columns 指定的标签列及模型使用的特征列,名称和类型与模型配置匹配。TZRec 和 GBDT 在线推理只需非标签特征,不需要提供标签列。
2. 训练并生成 origin checkpoint
TRAIN MODEL rank_model CHECKPOINT = '2026_09_13'
ON training_sample
WHERE dt = '2026-09-13'
WITH (
'num_epochs' = '1',
'batch_size' = '8192'
);TRAIN MODEL 会提交 Kubernetes 训练任务。语句成功提交不等于训练已完成;创建导出任务前,先使用以下语句检查状态:
SHOW CHECKPOINTS rank_model;
DESCRIBE FORMATTED MODEL rank_model
CHECKPOINT = '2026_09_13';3. 导出模型
EXPORT MODEL rank_model CHECKPOINT = '2026_09_13'
ON training_sample;导出的具体处理由模型后端决定。导出完成后会生成 export checkpoint,常规单模型的名称为 <origin_checkpoint>_export。DSSM 会分别生成 user 和 item 塔产物,具体名称以 SHOW CHECKPOINTS 的结果为准。
RocketLaunching 导出单个 light 推理产物,输出 probs_light;训练时的 booster 不参与推理。网络、特征、标签和蒸馏配置在续训、导出及服务部署时保持一致,样本要求见内置模型。
4. 创建在线服务
CREATE SERVICE `rank-service`
ON MODEL rank_model
CHECKPOINT = '2026_09_13_export'
WITH (
'replicas' = '1',
'pod_cpu_cores' = '1',
'pod_memory' = '2Gi'
);创建服务后可以查看定义和状态信息:
SHOW SERVICES;
DESCRIBE FORMATTED SERVICE `rank-service`;调用模型服务
call_service 将模型输出追加到输入数据。模型服务的输入字段应在 Model 中声明,并与传入表的字段对应。
行式输入
CACHE TABLE rank_input AS
SELECT user_id, item_id, category, price FROM candidate_item;
CACHE TABLE rank_output AS
SELECT *, CAST(NULL AS FLOAT) AS probs FROM rank_input LIMIT 0;
CACHE TABLE ranked_item AS
CALL call_service('rank-service', rank_input) LIKE rank_output;这个 Wide & Deep 示例保留输入列,并追加 probs;其他模型的输出字段见内置模型。
User-Item 输入
排序时可分开传入一行用户特征和多行候选物品,避免重复发送用户数据:
CACHE TABLE item_rank_output AS
SELECT *, CAST(NULL AS FLOAT) AS probs FROM item_candidates LIMIT 0;
CACHE TABLE ranked_item AS
CALL call_service('rank-service', user_features, item_candidates)
LIKE item_rank_output;- User 表必须恰好一行;Item 表可以有多行。
- 同名输入字段优先从 User 表取值,其余模型字段从 Item 表取值。
- 结果保留 Item 表字段,并追加模型输出字段。
- Item 表为空时不发 HTTP 请求,直接返回结构完整的空表。
外部服务的请求和响应约定见HTTP 推理协议。
Hugging Face 模型的不同之处
Hugging Face 后端的 TRAIN MODEL 表示从 Hub 下载指定 revision,不是使用 SQL 表训练,因此不需要 ON data_source:
TRAIN MODEL text_embedding_model CHECKPOINT = 'v1' WITH (
'revision' = 'main'
);该 checkpoint 的类型为 origin,可以直接创建服务;当前不支持 EXPORT MODEL。完整的任务和参数见内置模型。
常见问题
创建 Service 时提示 checkpoint 类型错误
确认模型后端需要的 checkpoint 类型。tzrec 和 GBDT 需要 export,Hugging Face 使用 origin,external 不需要 checkpoint。
训练数据字段不匹配
对比 DESCRIBE MODEL 结果与训练表字段,确认字段名、类型、标签列以及模型特有的 user/item 特征配置。
call_service 返回行数不正确
检查模型服务返回的每个数组是否与输入行数一致,并确认输出字段名与当前模型控制器定义一致。