Skip to content

模型训练与在线推理 ​

按你已有的条件选择路径:

  • 已有 HTTP 模型服务:使用下面的 external 模型接入,不需要 SQLRec 训练、导出或部署推理容器。
  • 需要 SQLRec 训练并部署模型:先准备服务环境,再按训练型模型流程操作。
  • 使用 Hugging Face 模型:下载 Hub 快照后直接创建服务,见后端差异。

接入已有 HTTP 模型服务 ​

准备 SQLRec 可访问的推理地址,并声明服务的输入、输出字段:

sql
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 缓存表,再调用服务。用空表声明输出结构:

sql
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 声明的输入字段:

json
[
  {"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 数组;每个数组长度必须与输入行数一致,顺序与输入对应:

json
{"score": [0.85, 0.72]}

使用下方的 User-Item 调用形式时,请求为列式 JSON,User 字段为单元素数组,Item 字段按行排列:

json
{
  "user_id": [1],
  "item_id": [101, 102],
  "category": ["phone", "tablet"],
  "price": [3999.0, 2999.0]
}

选择模型后端 ​

模型类型数据来源TRAIN MODELEXPORT MODEL服务使用的 Checkpoint
tzrec WideAndDeep / DeepFM / DSSM / MMoE / RocketLaunchingSQL 表训练需要export
LightGBM / XGBoost / CatBoostSQL 表训练需要export
Hugging Face TransformersHub 快照下载,不需要 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. 创建模型 ​

sql
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 ​

sql
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 训练任务。语句成功提交不等于训练已完成;创建导出任务前,先使用以下语句检查状态:

sql
SHOW CHECKPOINTS rank_model;

DESCRIBE FORMATTED MODEL rank_model
CHECKPOINT = '2026_09_13';

3. 导出模型 ​

sql
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. 创建在线服务 ​

sql
CREATE SERVICE `rank-service`
ON MODEL rank_model
CHECKPOINT = '2026_09_13_export'
WITH (
  'replicas' = '1',
  'pod_cpu_cores' = '1',
  'pod_memory' = '2Gi'
);

创建服务后可以查看定义和状态信息:

sql
SHOW SERVICES;

DESCRIBE FORMATTED SERVICE `rank-service`;

调用模型服务 ​

call_service 将模型输出追加到输入数据。模型服务的输入字段应在 Model 中声明,并与传入表的字段对应。

行式输入 ​

sql
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 输入 ​

排序时可分开传入一行用户特征和多行候选物品,避免重复发送用户数据:

sql
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:

sql
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 返回行数不正确 ​

检查模型服务返回的每个数组是否与输入行数一致,并确认输出字段名与当前模型控制器定义一致。