企业官网建设流程全解析

• 人工智能
• 机器学习
• 深度学习

本篇指南以contrib/azureml_designer_modules目录下的 README 与配套实现为核心，系统讲解如何将 Recommenders 仓库中的推荐算法与评估指标封装为 AzureML Designer 组件：读者将掌握六个可拖拽模块（SAR 训练、SAR 打分、分层数据切分，以及 MAP / nDCG / Precision@K / Recall@K 四项评估指标）的输入输出契约、参数配置方式、命令封装原理，以及如何在可视化画布上搭建从数据切分、模型训练到离线评估的完整推荐流水线，并学会如何在此基础上扩展自己的算法模块。

AzureML Designer（Azure 机器学习设计器）允许开发者通过交互式画布，将数据集与模块可视化地连接起来，从而构建机器学习模型。其关键能力在于：任何 Python 库都可以被封装为画布上的一个模块/组件。本目录正是利用这一机制，把 Recommenders 仓库中的算法与评估函数桥接进 Designer 的产物。

该目录包含两部分资产：

一、模块总览：六个可拖拽的推荐组件

从 module_specs 中的 YAML 定义可以整理出完整的组件清单：

整体可组合成一条典型流水线：Stratified Splitter 切分数据 → SAR Training 训练模型 → SAR Scoring 产出推荐/预测 → 四个评估组件之一计算离线指标。这与 examples/00_quick_start/sar_movielens.ipynb 等 Notebook 中演示的 SAR 实验流程一一对应，只是从代码驱动换成了画布拖拽驱动。

二、组件规范（YAML）剖析：Designer 组件的声明语言

每个组件由一个遵循http://azureml/sdk-2-0/CommandComponent.jsonSchema 的 YAML 文件声明，以 sar_train.yaml 为例拆解其结构：

$schema: http://azureml/sdk-2-0/CommandComponent.json name: microsoft.com.cat.sar_training version: 1.1.1 display_name: SAR Training type: CommandComponent description: 'SAR Train from Recommenders repo: https://github.com/Microsoft/Recommenders.' tags: Recommenders: inputs: input_path: type: AnyDirectory description: The directory contains dataframe. optional: false user_column: type: String description: Column name of user IDs. default: UserId optional: false item_column: type: String description: Column name of item IDs. default: MovieId optional: false rating_column: type: String description: Column name of rating. default: Rating optional: false timestamp_column: type: String description: Column name of timestamp. default: Timestamp optional: false normalize: type: Boolean description: Flag to normalize predictions to scale of original ratings default: false optional: false time_decay: type: Boolean description: Flag to apply time decay default: false optional: false outputs: output_model: type: AnyDirectory description: The output directory contains a trained model code: ../../ command: >- python contrib/azureml_designer_modules/entries/train_sar_entry.py --input-path {inputs.input_path} --col-user {inputs.user_column} --col-item {inputs.item_column} --col-rating {inputs.rating_column} --col-timestamp {inputs.timestamp_column} --normalize {inputs.normalize} --time-decay {inputs.time_decay} --output-model {outputs.output_model} environment: conda: conda_dependencies_file: contrib/azureml_designer_modules/module_specs/sar_conda.yaml os: Linux

关键字段含义：

• $schema/type：声明这是 SDK v2 的CommandComponent——即"以命令行方式运行 Python 脚本"的组件类型，画布上的每次执行等价于一次命令行调用。
• name/version/display_name：组件的唯一标识（如microsoft.com.cat.sar_training）、版本号（当前均为1.1.1）与画布上展示的名称。
• inputs/outputs：声明端口类型与参数。AnyDirectory表示输入输出以目录形式承载 DataFrame 或模型文件；String/Boolean/Integer/Float/Enum为参数类型，并可通过default设置默认值、min/max约束取值范围、optional标记是否必填。
• code: ../../：指定组件代码的挂载根目录，即仓库根目录。这解释了为何所有入口脚本都可以在命令中直接以仓库相对路径contrib/azureml_designer_modules/entries/xxx.py引用。
• command：真正被执行的命令行。{inputs.xxx}与{outputs.xxx}是占位符，运行时由 Designer 根据画布上的实际连线自动填充。
• environment：指定运行环境。sar_conda.yaml定义了 Conda 依赖（详见下文"环境依赖"小节），os: Linux表明组件目标运行平台为 Linux 计算集群。

2.1 参数占位符与可选参数语法

在 sar_score.yaml 中可以看到更复杂的命令构造方式，方括号[ ... ]表示可选参数：

command: >- python contrib/azureml_designer_modules/entries/score_sar_entry.py --trained-model {inputs.trained_model} --dataset-to-score {inputs.dataset_to_score} --score-type {inputs.score_type} [--items-to-predict {inputs.items_to_predict}] --normalize {inputs.normalize} [--ranking-metric {inputs.ranking_metric}] [--top-k {inputs.top_k}] [--sort-top-k {inputs.sort_top_k}] [--remove-seen-items {inputs.remove_seen_items}] --score-result {outputs.score_result}

其中score_type为必填的Enum类型输入，枚举值为Rating prediction与Item recommendation，默认Item recommendation；其余如ranking_metric（Rating/Similarity/Popularity，默认Rating）、top_k（Integer，min: 1，默认10）、sort_top_k（默认true）、remove_seen_items（默认false）均声明为optional: true，因此出现在方括号中，仅在用户显式配置时才传入命令行。

三、入口脚本设计模式：每个组件的运行骨架

所有entries下的脚本遵循高度一致的"四段式"结构，理解这一模式后即可照葫芦画瓢扩展新组件：

1. argparse 声明参数：使用argparse.ArgumentParser()逐一声明与 YAMLinputs对应的命令行参数。
2. 加载数据：通过azureml.studio.core.io.data_frame_directory.load_data_frame_from_directory将 Designer 的目录端口加载为 Pandas DataFrame。
3. 调用 Recommenders 核心函数：直接复用仓库内已实现的算法或评估函数。
4. 记录指标并保存结果：调用评估函数后，先用azureml.core.Run.get_context()获取运行上下文，将指标写入 AzureML 运行仪表盘（run.parent.log(...)），再把结果 DataFrame 通过save_data_frame_to_directory写回输出端口。

3.1 数据帧的加载与保存约定

Designer 的 DataFrame 端口在底层以目录形式存在，需要借助azureml.studio.core.io.data_frame_directory模块读写。以 map_entry.py 为例：

from azureml.studio.core.io.data_frame_directory import ( load_data_frame_from_directory, save_data_frame_to_directory, ) from azureml.studio.core.data_frame_schema import DataFrameSchema rating_true = load_data_frame_from_directory(args.rating_true).data rating_pred = load_data_frame_from_directory(args.rating_pred).data

读取时.data属性即真正的 Pandas DataFrame；保存时则需同时给出列 Schema：

score_result = pd.DataFrame({"map_at_k": [eval_map]}) save_data_frame_to_directory( args.score_result, score_result, schema=DataFrameSchema.data_frame_to_dict(score_result), )

值得注意的是入口脚本普遍使用args, _ = parser.parse_known_args()而非parse_args()，即忽略未知参数——这允许同一脚本兼容 Designer 自动注入的额外参数，增强了健壮性。

3.2 指标上报到 AzureML 仪表盘

每个评估入口在算完指标后都会执行一次日志上报，例如 ndcg_entry.py：

# Log to AzureML dashboard run = Run.get_context() run.parent.log("nDCG at {}".format(k), eval_ndcg)

Run.get_context()获取当前运行上下文，run.parent.log()则将指标写入父运行，从而在 AzureML 的指标看板中实时展示。四项评估组件分别上报MAP at {k}、nDCG at {k}、Precision at {k}、Recall at {k}，键名即画布可视化图表中的指标名。

四、SAR 训练组件：把单节点 SAR 算法封装成画布模块

4.1 入口脚本的参数与调用链

train_sar_entry.py 是六个组件中唯一涉及模型训练的入口，其核心调用如下：

model = SAR( col_user=args.col_user, col_item=args.col_item, col_rating=args.col_rating, col_timestamp=args.col_timestamp, normalize=strtobool(args.normalize), timedecay_formula=strtobool(args.time_decay), ) start_time = time.time() model.fit(input_df) train_time = time.time() - start_time print("Took {} seconds for training.".format(train_time))

其中SAR类位于 recommenders/models/sar/sar_singlenode.py，是 Recommenders 仓库中 SAR（Simple Algorithm for Recommendations）的单节点实现。其核心思想是：先估计用户对物品的偏好（affinity），再估计物品之间的相似度，最后综合两者为用户生成推荐列表。从构造签名（sar_singlenode.py）可以看到，SAR还支持similarity_type（jaccard、cosine、lift、cooccurrence、mutual information等七种相似度）、time_decay_coefficient（评分半衰期天数）、threshold（低于该共现次数的物品对会被剔除）等参数，这些在 Designer 组件中暂未暴露，保持默认值。

入口脚本中两次类型转换值得注意：

• input_df[args.col_rating] = input_df[args.col_rating].astype(float)：训练前把评分列强制转为float，避免字符串或整型数据导致亲和度计算异常；
• strtobool(args.normalize)与strtobool(args.time_decay)：Designer 的Boolean输入在命令行中以字符串形式传入，需要用distutils.util.strtobool还原为布尔值。

4.2 模型序列化：joblib 保存协议

训练完成后，模型通过自定义的joblib_dumper保存（train_sar_entry.py）：

def joblib_dumper(data, file_name=None): """Return a dumper to dump a model with pickle.""" if not file_name: file_name = "_data.pkl" def model_dumper(save_to): full_path = Path(save_to) / file_name ensure_folder(Path(save_to)) with open(full_path, "wb") as fout: joblib.dump(data, fout, protocol=4) model_spec = {"model_type": "joblib", "file_name": file_name} return model_spec return model_dumper

save_model_to_directory会调用该 dumper 将模型写入输出目录，并返回描述文件名的model_spec。这样设计的好处是：Designer 的输出目录可以承载任意格式的模型，只要保存与加载两侧的model_spec约定一致即可。对应的加载侧在评分组件中（见下节joblib_loader），二者以{"model_type": "joblib", "file_name": "_data.pkl"}为契约，形成对称的读写协议。

五、SAR 评分组件：三种推荐模式与两种预测模式

score_sar_entry.py 是功能最丰富的入口，通过三个Enum类对运行模式做显式建模：

class ScoreType(Enum): ITEM_RECOMMENDATION = "Item recommendation" RATING_PREDICTION = "Rating prediction" class RankingMetric(Enum): RATING = "Rating" SIMILARITY = "Similarity" POPULARITY = "Popularity" class ItemSet(Enum): TRAIN_ONLY = "Items in training set" SCORE_ONLY = "Items in score set"

入口先按--score-type分派：Item recommendation走recommend_items，Rating prediction走predict_ratings。

5.1 物品推荐模式的三种排序依据

recommend_items根据ranking_metric映射到 SAR 模型的不同方法（score_sar_entry.py）：

这三个方法在 sar_singlenode.py 中均有实现（get_popularity_based_topk、get_item_based_topk、recommend_k_items），组件层只是把 Designer 的画布参数原样透传给模型 API。

5.2 评分预测模式的两个物品集合

predict_ratings按items_to_predict分派（score_sar_entry.py）：

normalize参数用于把预测值缩放到原始评分的量纲（如 1~5 分），其实现对应 sar_singlenode.py 中的rescale逻辑，这在将"评分预测"与"真实评分"直接做误差对比时非常必要。

5.3 加载训练产物：与保存协议对称的 joblib_loader

评分入口通过load_model_from_directory配合自定义joblib_loader反序列化训练阶段保存的模型（score_sar_entry.py）：

def joblib_loader(load_from_dir, model_spec): file_name = model_spec["file_name"] with open(Path(load_from_dir) / file_name, "rb") as fin: return joblib.load(fin) sar_model = load_model_from_directory( args.trained_model, model_loader=joblib_loader ).data

model_spec["file_name"]正是训练阶段写入的_data.pkl。得益于 sar_conda.yaml 中固定joblib==0.14.0的版本约束，训练与评分两个组件即使在不同的计算节点上运行，也能保证序列化兼容性。

六、分层切分组件：训练/测试数据的标准入口

stratified_splitter_entry.py 将python_stratified_split封装为组件，输出训练集与测试集两个端口。核心调用：

output_train, output_test = python_stratified_split( input_df, ratio=args.ratio, col_user=args.col_user, col_item=args.col_item, seed=args.seed, )

底层函数定义于 recommenders/datasets/python_splitters.py，其签名还支持min_rating（过滤交互次数过少的用户或物品）与filter_by（按user还是item过滤）等参数。分层切分保证每个用户都被同时分配到训练集和测试集，是评估"冷启动用户推荐"效果的前提——测试集中的每个用户都在训练集中见过，从而可以计算个性化的 Top-K 指标。

YAML 中ratio参数的描述值得注意（stratified_splitter.yaml）：它既可以是一个Float（如0.75表示 75% 数据进训练集），也可以是一个浮点数列表（按比例切成多份；若列表之和不为 1 会自动归一化）。组件层将该能力收窄为单个Float输入，取值范围[0.0, 1.0]，默认0.75。

七、四个评估组件：MAP / nDCG / Precision@K / Recall@K

四个评估入口结构完全同构，均接收"真实评分表 + 预测表"两个 DataFrame 输入，输出一个标量指标。以 map_entry.py 为例：

eval_map = map_at_k( rating_true, rating_pred, col_user=col_user, col_item=col_item, col_rating=col_rating, col_prediction=col_prediction, relevancy_method=relevancy_method, k=k, threshold=threshold, )

7.1 共用的七参数契约

四个入口（map_entry.py、ndcg_entry.py、precision_at_k_entry.py、recall_at_k_entry.py）暴露的参数字段完全一致，对应 YAML 中的输入定义：

四个 YAML（map.yaml、ndcg.yaml、precision_at_k.yaml、recall_at_k.yaml）中这四个组件的输入输出声明完全一致，差别仅在name、display_name与command中引用的入口脚本。

7.2 指标定义与底层实现

四个指标均实现于 recommenders/evaluation/python_evaluation.py，其函数签名与组件参数一一对应（precision_at_k见 L457、recall_at_k见 L510、ndcg_at_k见 L616、map_at_k见 L809）：

• MAP@K（Mean Average Precision at K）：对每个用户计算预测列表的平均精确率，再对所有用户取均值。输出描述为"min=0, max=1"（见 map.yaml），取值越高表示排序质量越好。
• nDCG@K（Normalized Discounted Cumulative Gain）：按位置折损的累积增益除以理想排序的增益，衡量排序位置对推荐质量的影响。
• Precision@K：预测 Top-K 中相关物品所占比例，衡量推荐的精确性。
• Recall@K：所有相关物品中被预测 Top-K 命中的比例，衡量推荐的覆盖性。

四者侧重点不同，实践中常组合使用：例如在画布上同时挂出四个评估组件，从精确率、召回率、排序位置敏感性三个维度交叉验证同一份 SAR 推荐结果。

此外，仓库的 recommenders/evaluation/spark_evaluation.py 中还提供了 Spark（PySpark MLlibRankingMetrics）版本的同类指标实现，可用于大规模分布式评估场景，但本 Designer 组件集目前封装的是纯 Python（Pandas）版本。

八、运行环境依赖

所有组件共用同一个 Conda 环境文件 sar_conda.yaml：

name: Recommenders_module_environment channels: - defaults dependencies: - python=3.7 - pip=20.2 - pip: - pandas>=0.23.4,<1.0.0 - pyarrow>=0.13.0 - azureml-defaults - azureml-designer-core - joblib==0.14.0 - scikit-learn==0.20.3

几个关键约束的含义：

• python=3.7+pip=20.2：锁定 Python 与 pip 版本，保证组件行为可复现；
• pandas>=0.23.4,<1.0.0：限定 Pandas 大版本在 0.x，与 Designer 数据帧读写模块及 SAR 实现的 API 兼容；
• azureml-defaults/azureml-designer-core：提供Run、module_logger、数据帧目录读写、模型目录读写等 Designer 运行基础设施；
• joblib==0.14.0+scikit-learn==0.20.3：固定序列化协议与相关依赖版本，确保训练产出的_data.pkl能被评分组件可靠加载。

九、在 Designer 画布上编排推荐流水线

结合前述组件契约，可以在 AzureML Designer 画布上搭建如下典型实验流程：

1. 数据接入：将用户-物品交互数据（含UserId、MovieId、Rating、Timestamp四列）以 DataFrame 数据集接入画布；
2. 分层切分：连接Stratified Splitter，设置ratio=0.75，输出训练集与测试集；
3. 模型训练：将训练集连入SAR Training，配置user_column/item_column/rating_column/timestamp_column，按需开启normalize与time_decay，产出序列化的 SAR 模型；
4. 离线打分：将模型与测试集连入SAR Scoring，选择Item recommendation模式与Rating排序依据，设置top_k（如 10），视业务需要开启remove_seen_items；
5. 指标评估：将训练集（作为真实值）与打分结果分别连入MAP / nDCG / Precision@K / Recall@K组件的两个输入端口，运行后即可在运行仪表盘上查看四个指标曲线。

需要特别留意端口的连线约定：评估组件要求rating_true输入连接"真实交互数据"，rating_pred输入连接"模型预测输出"，两者必须包含一致的user_column/item_column列名，且prediction_column默认取prediction（SAR Scoring 输出即为该列名）。若不满足，可通过组件的列名参数在画布上直接修正。

十、扩展指南：如何添加新的 Recommenders 组件

该目录的架构决定了扩展新组件的成本很低，只需三步：

1. 编写入口脚本：在 entries 下新建xxx_entry.py，复用"argparse +load_data_frame_from_directory+ 调用 Recommenders 函数 +run.parent.log+save_data_frame_to_directory"骨架。若新组件涉及模型，需同时实现与训练侧对称的 dumper / loader，并约定model_spec的字段；
2. 声明组件规范：在 module_specs 下新建xxx.yaml，参照$schema: http://azureml/sdk-2-0/CommandComponent.json声明输入输出，code指向../../（仓库根），command使用{inputs.xxx}/{outputs.xxx}占位符拼装命令行；
3. 复用环境：若新组件仍基于 Pandas / scikit-learn / joblib 生态，直接引用 sar_conda.yaml；若引入新依赖，则需在其基础上扩展依赖列表。

例如，把 Recommenders 仓库中其他算法（如 NCF、xDeepFM、LightGBM 等）封装为 Designer 组件，即可复用同一套"训练/打分/评估"三段式流水线；评估侧也可继续复用本目录的四个指标组件，因为其输入契约（真实表 + 预测表 + 列名参数）与模型无关。

结语

contrib/azureml_designer_modules为 Recommenders 仓库提供了完整的 AzureML Designer 可视化集成方案：六个组件覆盖了推荐系统离线实验"切分 → 训练 → 打分 → 评估"的完整闭环，所有组件都直接复用仓库内经过测试的算法与评估实现（如 python_evaluation.py、python_splitters.py、sar_singlenode.py），而非重复造轮子。对于希望以低代码方式在 AzureML 上开展推荐实验的团队，这套组件即开即用；对于希望把更多 Recommenders 算法带入 Designer 的开发者，本章拆解的"YAML 规范 + 入口脚本"模式则是一份可直接复用的扩展模板。

• 人工智能
• 机器学习
• 深度学习