4. 从0到上线：.NET 8 + ML.NET LTR 智能类目匹配实战--从业务到方案：数据与特征工程：从 CSV 到可训练的 LTR 样本

本文聚焦于把原始账单/行为数据从 CSV 平滑落地为可训练的 Learning-to-Rank 样本，系统讲清数据合同 LtrRow 的每个字段含义与约束、推荐的 CSV 列设计与样例、从原始列到特征的标准化流程（文本清洗与向量化、UserId/Merchant 的 OneHotHash 编码、amount 金额分箱到 AmountBucket、hour 到 HourOfDay），以及保证排序学习成立的关键：按查询聚合并统一 GroupId。同时给出缺失值与异常处理策略、常见坑及修复要点，并通过代码引用解释训练与预测端如何保持特征一致性，构建可复现、可评估的 LTR 训练数据管线。

一、要点速览

本节将围绕统一的数据合同 LtrRow 展开，明确 Query、Candidate、Label、GroupId 以及 UserId、Merchant、AmountBucket、HourOfDay 等字段在样本中的职责与约束，强调同一查询的一组候选必须共享 GroupId 才能让 LTR 按组学习排序关系；在特征层面，我们采用文本与类别与数值的多模态组合，通过 NormalizeText 与 FeaturizeText 处理文本，通过 OneHotHash 编码高基数的用户与商户类别，并让金额分箱与小时数以数值直通的方式参与训练；并且给出从 CSV 到可训练样本的可重复流程，从字段校验到预处理、从金额与时间的派生特征到分组与导出均形成标准化步骤；最后补充工程稳健性实践，包括面向小数据的参数选型、缺失值的处理策略、哈希碰撞的监控与缓解，以及面对分布漂移时以回放集与滚动更新保障效果的常态化机制。

二、数据合同

2.1 可训练的 LTR 样本结构

在进入特征工程与训练管道细节之前，需要先把"可训练的一行数据"定义清楚：样本既要完整承载查询、候选与监督信号，也要为后续的文本向量化、类别编码与排序分组提供稳定一致的字段约定。本小节从工程落地的角度界定 LtrRow 的最小完备字段集与约束，并说明这些字段如何在训练与预测两端保持一致，使得数据从 CSV 落地到模型能够无缝衔接。我们先来看一下LtrRow的代码定义：

public sealed class LtrRow
{
    public string Query { get; set; } = string.Empty;
    public string Candidate { get; set; } = string.Empty;
    public float Label { get; set; }
    public string GroupId { get; set; } = string.Empty;
    public string? UserId { get; set; }
    public string? Merchant { get; set; }
    public float AmountBucket { get; set; }
    public float HourOfDay { get; set; }
}

在 LtrRow 这个结构里，Query 就是账单的消费描述，相当于最核心的文本特征了，我们需要先做下清理，比如把前后的空格、控制字符都去掉，免得脏数据影响效果。Candidate 是每个账单想分去的候选类目，比如餐饮、娱乐等，一般都是用户自己设的或者预置的类目，这同样作为文本直接给模型用。Label 这个字段，大家都很熟悉，训练打标签用的，1 代表正样本，0 代表负样本，仅在训练用，预测时直接忽略就行。再说 GroupId，它其实是告诉模型怎么分组排序的，一条 query 下所有候选，它们的 GroupId 必须一致，并且一组里得既有正样本也有负样本，要不然模型学不到排序关系。

再看 UserId 和 Merchant，这两个主要是做个性化和上下文还原的，模型有了这些，可以结合用户或者商户做定制；如果拿不到值，可以直接是空字符串，模型端就不会出错。AmountBucket 是金额分桶，不管是按区间还是分位数分，把金额大致归分类，核心思想是表达金额的量级差别，不用特别精确的数值。最后 HourOfDay 很直观，就是发生时的小时数（0 到 23），可以直接当特征进模型，后面想用成周期特征、拼点新花样也很方便。

2.2 CSV 列定义与示例

准备 CSV 的时候，字段顺序没死规定，只要我们在后续数据映射时统一起来就行了，整个流程顺畅最重要。基本上字段包括这几个：query（原始账单描述文本），candidate（目标分类文本），label（监督信号，0 或 1），group_id（批次分组用的，同一组代表同一个查询上下候选），user_id 和 merchant（用户和商户，能有更好，没有就留空），amount（账单原始金额，后续会分箱处理），hour（发生的小时数，直接用 0 到 23 就行）。

举个直观点的例子，每一行其实都差不多这样：

query,candidate,label,group_id,user_id,merchant,amount,hour
星巴克咖啡,餐饮,1,6e0b...,u_001,星巴克,36.5,9
星巴克咖啡,娱乐,0,6e0b...,u_001,星巴克,36.5,9
地铁充值,交通,1,2a77...,u_002,地铁,50,8
地铁充值,餐饮,0,2a77...,u_002,地铁,50,8

Tip：注意，amount 这一列在数据导进来后会转换成 AmountBucket，人工分桶反映大致金额量级，而 hour 字段就是直接转成 HourOfDay，供模型用，没啥复杂处理。所以总的来说，先保证 CSV 字段统一靠谱，然后落地时按标准化流程处理特征，这样我们的后续特征工程和 LTR 训练就不会踩坑了。

二、特征工程流水线（训练端）

有了标准化的 LtrRow 数据合同，接下来就是把这些原始字段转换成模型能直接"吃"的特征向量。特征工程的核心目标是把文本、类别、数值这些不同模态的信息统一成稠密或稀疏的数值表示，让 LightGBM 排序模型能够有效学习查询与候选之间的匹配关系。整个流程包括文本的标准化与向量化、高基数类别的哈希独热编码、数值特征的直接拼接，以及最关键的排序分组键转换，最终将所有特征合并成一个统一的 Features 列供模型训练使用。训练使用的管道的关键代码如下：

var pipeline =
    _ml.Transforms.Text.NormalizeText("q_norm", nameof(LtrRow.Query))
    .Append(_ml.Transforms.Text.FeaturizeText("q_feat", "q_norm"))
    .Append(_ml.Transforms.Text.NormalizeText("c_norm", nameof(LtrRow.Candidate)))
    .Append(_ml.Transforms.Text.FeaturizeText("c_feat", "c_norm"))
    .Append(_ml.Transforms.Categorical.OneHotHashEncoding("user_feat", nameof(LtrRow.UserId)))
    .Append(_ml.Transforms.Categorical.OneHotHashEncoding("m_feat", nameof(LtrRow.Merchant)))
    .Append(_ml.Transforms.Conversion.MapValueToKey("group_key", nameof(LtrRow.GroupId)))
    .Append(_ml.Transforms.Concatenate("Features",
        new[] { "q_feat", "c_feat", "user_feat", "m_feat", nameof(LtrRow.AmountBucket), nameof(LtrRow.HourOfDay) }))
    .Append(_ml.Ranking.Trainers.LightGbm(new LightGbmRankingTrainer.Options
    {
        LabelColumnName = nameof(LtrRow.Label),
        FeatureColumnName = "Features",
        RowGroupColumnName = "group_key",
        NumberOfLeaves = 4,
        MinimumExampleCountPerLeaf = 1,
        NumberOfIterations = 50,
        LearningRate = 0.1,
        Booster = new GradientBooster.Options()
    }));

这段代码展示了完整的特征工程与模型训练流程，我们来逐步拆解每个环节的设计思路与工程考量。

首先是文本特征的处理，对 Query 和 Candidate 都采用了"先标准化再向量化"的两步策略。NormalizeText 负责处理标点符号、大小写统一、去除多余空白等基础清洗工作，确保后续向量化不会因为格式差异产生噪声。紧接着 FeaturizeText 将清洗后的文本转换为数值向量，这里会用到词频、TF-IDF 或者更高级的嵌入技术，具体取决于 ML.NET 的默认实现。这种两步法保证了向量维度的稳定性，避免因为文本格式变化导致特征空间不一致。

类别特征的处理选择了 OneHotHashEncoding 而不是传统的独热编码，这主要是为了应对高基数问题。UserId 和 Merchant 这类字段的取值可能非常多，如果用传统独热会带来维度爆炸，而哈希独热通过哈希函数将高维稀疏空间映射到固定维度的稠密空间，既保留了类别信息又控制了计算复杂度。不过需要注意哈希碰撞的概率，当不同类别被映射到同一个哈希桶时会产生信息损失，我们可以通过调整哈希位数或引入频次截断来缓解。

分组键的转换是整个 LTR 训练的关键环节，MapValueToKey 将字符串类型的 GroupId 转换为数值键，这是 LightGBM 排序算法的硬性要求。排序学习需要知道哪些样本属于同一组，模型会在组内学习相对排序关系，所以同一次查询的所有候选必须共享相同的 group_key，否则算法无法正确工作。

数值特征方面的处理相对简单，AmountBucket 和 HourOfDay 直接拼接到最终的 Features 向量中，不需要额外的归一化处理。LightGBM 对数值特征的尺度不敏感，而且分箱后的金额桶值本身就在合理范围内，小时数也是 0-23 的有限离散值，直接使用不会影响模型收敛。

最后是 LightGBM 的参数配置，这里针对小数据集做了专门的优化。NumberOfLeaves 设为 4 是为了控制模型复杂度，避免过拟合。MinimumExampleCountPerLeaf 设为 1 允许叶子节点包含最少样本，适应数据稀疏场景。NumberOfIterations 和 LearningRate 的组合需要平衡收敛速度与稳定性，50 轮迭代配合 0.1 的学习率是比较保守但稳健的选择。

三、重点代码讲解

从数据合同到特征工程，再到预测推理，整个流程的设计都围绕着"一致性"这个核心原则。LtrRow 作为统一的数据载体，其字段设计体现了多模态特征的融合思路：Query 和 Candidate 作为主要的文本特征，承载了语义匹配的核心信息；UserId 和 Merchant 通过 OneHotHash 编码捕捉个性化与上下文信号，让模型能够区分不同用户和场景的偏好差异；AmountBucket 和 HourOfDay 作为数值特征，提供了金额量级和时间模式的结构化信息；而 GroupId 则是整个 LTR 学习的"组键"，它将同一次查询的所有候选绑定在一起，形成可学习的排序对照关系。

分组键的转换是整个排序学习的关键环节，MapValueToKey 将字符串类型的 GroupId 映射为数值类型的 group_key，这是 LightGBM 排序算法的硬性要求。排序学习需要在组内进行相对排序，模型通过比较同一组内不同候选的得分来学习"哪个更好"的排序关系。如果组内没有正负样本的对照，或者不同查询的候选被错误地分到同一组，排序学习就会退化，模型无法学到有效的排序模式。下面是重点代码：

public IEnumerable<CategoryMatchResult> PredictTopK(
    string query,
    IEnumerable<UserCategory> categories,
    string? userId = null,
    string? merchant = null,
    float amountBucket = 0,
    float hourOfDay = 0,
    int k = 3)
{
    if (string.IsNullOrWhiteSpace(query)) throw new ArgumentException("query is required", nameof(query));
    if (categories is null) throw new ArgumentNullException(nameof(categories));
    var model = _model ?? throw new InvalidOperationException("Model not loaded or trained");
    string gid = Guid.NewGuid().ToString("N");
    var rows = categories.Select(c => new LtrRow
    {
        Query = query,
        Candidate = c.Name,
        Label = 0f,
        GroupId = gid,
        UserId = userId ?? string.Empty,
        Merchant = merchant ?? string.Empty,
        AmountBucket = amountBucket,
        HourOfDay = hourOfDay
    });
    var view = _ml.Data.LoadFromEnumerable(rows);
    var scored = model.Transform(view);
    var scores = _ml.Data.CreateEnumerable<LtrScore>(scored, reuseRowObject: false).ToArray();
    return categories.Zip(scores, (c, s) => new CategoryMatchResult(c, s.Score))
                     .OrderByDescending(x => x.Score)
                     .Take(k);
}

这段 PredictTopK 方法展示了从用户查询到推荐结果的完整预测流程，方法首先进行严格的参数校验，确保 query 不为空且 categories 集合有效，同时检查模型是否已加载，这些前置检查避免了运行时异常，提高了系统的健壮性。

接下来是核心的样本构建环节，为当前查询生成统一的 gid 作为分组标识，这是排序学习的关键。所有候选类目都使用相同的 GroupId，确保它们属于同一组，模型就能在组内进行相对排序比较。为每个候选构建 LtrRow 样本时，Query 保持相同，Candidate 对应不同的类目名称，Label 在预测时设为 0，因为模型只需要特征信息进行推理。UserId 和 Merchant 使用空字符串作为默认值，AmountBucket 和 HourOfDay 直接传入，这些特征将参与模型的个性化判断。

模型推理环节使用训练好的管道对所有候选进行批量评分，Transform 方法会应用与训练时完全相同的特征工程步骤，确保特征空间的一致性。评分结果通过 CreateEnumerable 转换为可枚举的 LtrScore 对象，每个对象包含一个候选的匹配度分数。

最后是排序和截取环节，使用 Zip 将候选类目与对应分数组合，按分数降序排列后取前 K 个作为最终推荐结果。这保证了推荐结果的有序性，分数越高的候选越相关，用户可以根据置信度阈值决定是否采用自动推荐或进行人工确认。

四、从 CSV 到 LTR 的标准流程

将原始 CSV 数据转换为可训练的 LTR 样本需要经过一系列标准化的预处理步骤，每个环节都有其特定的工程考量。首先是数据读取与基础校验阶段，需要确保必填字段的完整性，包括 query、candidate、label、group_id 等核心列不能为空。同时进行数据合法性检查，label 必须为 0 或 1，hour 必须在 0-23 范围内，文本字段需要去除首尾空白并控制长度上限，通常设置为 128 或 256 字符，避免过长文本影响向量化效果。

接下来是文本清洗与规范化环节，这是保证特征质量的关键步骤。统一使用 UTF-8 编码处理多语言文本，移除不可见字符和控制字符，对全角半角字符、特殊空格进行标准化处理，通常使用正则表达式进行批量替换。大小写策略需要根据业务场景确定，中文文本通常对大小写不敏感，英文文本可以考虑统一转为小写，但要注意保留专有名词的原始格式。

金额分箱是数值特征工程的重要环节，需要根据业务分布特点设计合理的分桶策略。可以采用固定区间的方式，比如 0-20、20-50、50-100、100-300、300+ 这样的五桶设计，也可以基于数据的分位数进行自适应分箱，比如 20%、40%、60%、80% 分位数作为切分点。分箱的目标是将连续金额转换为离散的层级信息，让模型能够捕捉"小额、中额、大额"这样的结构化模式。

时间特征的处理相对直接，HourOfDay 直接使用 0-23 的整数值即可，这个范围已经能够表达一天中的时段信息。如果需要更精细的周期性建模，可以在后续扩展中加入正弦余弦变换，将小时数转换为周期性的三角函数值，这样模型就能更好地理解"早晨、中午、晚上"这样的时间模式。

分组与负样本补齐是 LTR 学习的关键环节，需要确保每个分组内既有正样本也有负样本，否则模型无法学到有效的排序关系。当某个分组只有正样本时，需要从同组的候选集中抽取若干负样本进行补齐，或者从其他相似查询的负样本中进行补充。这个过程需要仔细设计，确保负样本的质量和代表性。

最后是将所有处理好的字段映射到 LtrRow 数据结构中，形成标准化的训练样本。这个映射过程需要保持字段类型和顺序的一致性，确保后续的特征工程和模型训练能够正确识别每个字段的含义。生成的 LtrRow 序列可以直接用于模型训练，也可以保存为中间格式供后续的离线评估和模型优化使用。

五、由反馈生成训练样本（在线闭环）

在线阶段的每一次用户选择与纠正，都是高价值的监督信号。为了让模型越用越准，我们需要把这些反馈稳定地转换成 LTR 可用的组内样本：同一条查询的所有候选共用一个 GroupId，用户选中的类目标记为正样本，其他候选标记为负样本，如此即可形成可学习的排序对照关系。下面这段代码演示了如何把反馈文档转成 LtrRow 序列，并确保分组、一致性与特征字段的完整。

private IEnumerable<LtrRow> ConvertFeedbacksToTrainingData(IEnumerable<UserFeedback> feedbacks)
{
    var rows = new List<LtrRow>();
    foreach (var feedback in feedbacks)
    {
        var gid = feedback.Id;
        var candidates = feedback.AvailableCategories.Count > 0
            ? feedback.AvailableCategories
            : new List<string> { feedback.SelectedCategory };
        if (!candidates.Contains(feedback.SelectedCategory))
        {
            candidates = new List<string>(candidates) { feedback.SelectedCategory };
        }
        foreach (var candidate in candidates)
        {
            var label = candidate == feedback.SelectedCategory ? 1f : 0f;
            rows.Add(new LtrRow
            {
                Query = feedback.Query,
                Candidate = candidate,
                Label = label,
                GroupId = gid,
                UserId = feedback.UserId,
                Merchant = feedback.Merchant,
                AmountBucket = feedback.AmountBucket,
                HourOfDay = feedback.HourOfDay
            });
        }
    }
    return rows;
}

这段实现的核心，是把一条用户反馈展开成"同组多候选"的排序样本。以反馈的 Id 作为 GroupId，可以稳定地把同一次交互产生的所有候选归入同一组。当 AvailableCategories 为空时退化为只包含被选中的类目，并在必要时将 SelectedCategory 追加进候选集，保证组内一定存在正样本并且候选集合齐备、可比较。这样做的直接收益是训练时排序学习总能拿到一个成组的、语义完整的对照集合，避免因为候选缺失导致的单点监督无法学习排序关系。

随后对候选逐一生成 LtrRow，被用户选中的类目打上 Label=1f，其余候选统一打 Label=0f，并把查询文本 Query、个性化与上下文特征 UserId、Merchant、以及数值特征 AmountBucket、HourOfDay 原样写入。这里最关键的是"训练---预测一致性"：这些字段与训练管道中的列名、类型、含义完全对齐，后续进入同一条特征工程流水线（文本标准化与向量化、类别哈希独热、数值直通、分组键映射与特征拼接），模型才能可靠地在组内学习相对排序。工程上还可以按需加入去重与候选数上限控制，使用时间衰减或权重机制提升近期反馈的影响力，但不论如何扩展，都应保持分组键的稳定性和字段语义的一致性，这是让在线反馈真正转化为可用训练信号的底线。

六、常见问题

6.1 缺失值与异常处理策略

在进入训练环节前，先把输入数据做一次系统性的缺失与异常治理是非常必要的。对于核心文本字段 Query 与 Candidate，一旦缺失就应当直接丢弃该行，因为这是语义匹配的基础信号，缺失会让样本丧失可训练性。GroupId 的缺失可以通过规则化生成来兜底，例如对 query 或 (query,userId) 做稳定哈希，或使用外部生成的行级 GUID，但要确保同一查询在不同批次中能够得到一致的分组值，更推荐在离线导入阶段统一构造并固化到持久层。UserId 与 Merchant 缺失时，可以安全地落空字符串，这些类别特征会被 OneHotHash 编码自然吸收，不会引发维度错位。

数值侧的异常处理则以稳健为先，对金额类输入建议先做合理区间的裁剪，再进行分箱以降低极端值的影响，同时把被裁剪的比例记录到数据质量日志，方便后续监控与回溯。时间字段 HourOfDay 应严格限制在 0 到 23 的整数范围，超出范围可以就近映射到合法边界或使用业务约定的默认值（如 0），并记录清洗率以便评估数据源稳定性。完成上述治理后，再进入标准化的特征工程流水线，能够显著降低异常样本对训练收敛与线上表现的干扰。

6.2 评估与报表（NDCG/MAP 概览）

在将 CSV 转换为 LtrRow 之后，需要预留独立的验证集，并采用按组的排序指标进行评估，常用的是 NDCG@K 与 MAP@K，它们都要求以 GroupId 为维度在组内计算相对排序质量。小数据场景下更建议使用 K 折交叉验证或基于时间切片的评估方式，以降低数据泄漏的风险，同时让评估结论更稳健可信。

落地到报表层面，除了关注整体 NDCG 外，还应分层查看不同金额桶与不同时段的 NDCG 表现，并按用户与商户维度做切片，观察模型在主要人群与关键商户上的稳定性。如果发现某些分层指标显著低于整体水位，往往意味着特征刻画或样本覆盖在该分层存在短板，这也是后续特征扩展、数据补齐与增量再训练的优先方向。

七、总结

本文从工程落地的视角，围绕"如何把原始 CSV 数据稳定地转换为可训练的 Learning-to-Rank 样本"给出了一条端到端的可复用路径。我们首先用 LtrRow 明确了训练/预测两端都要遵循的数据合同，强调 Query/Candidate 文本特征的清洗与一致性、UserId/Merchant 的高基数类别处理、AmountBucket/HourOfDay 的数值承载，以及决定排序学习是否成立的 GroupId 分组语义。随后以训练管道为主线，讲解了文本标准化与向量化、OneHotHash 编码、分组键映射与特征拼接的完整流程，并给出了 PredictTopK 的推理实现以说明训练与预测必须共享同一条特征工程链路。

在在线闭环方面，我们将用户的选择与纠正转化为"同组多候选"的排序样本，确保组内有明确的正负对照，让模型在真实反馈中持续学习区分度。同时给出缺失值与异常处理的治理建议，包含核心文本缺失的剔除、分组键的稳定生成策略、金额裁剪与分箱以及小时范围校验等，最大限度降低脏数据对训练与评估的干扰。最后，我们提出以 NDCG/MAP 为核心的按组评估方法，并建议从金额桶、时段、用户与商户等维度做分层报表，以识别薄弱环节，指导特征扩展与数据补齐。