9.【.NET10 实战--孢子记账--产品智能化】--SP.MLService Microsoft.ML 升级到 .NET 10

在整个从 .NET 8 迁移到 .NET 10 的升级旅程中，SP.MLService 的依赖升级是最后一个被标记为高风险的环节。这个"高风险"标签的来源，与我们此前处理的其他高风险步骤截然不同。Ocelot 升级的高风险在于它是系统的唯一外部入口，一旦出现问题，整个系统对外不可用。而 SP.MLService 的高风险则来自一个更底层、更隐蔽的维度------原生库（native binaries） 。Microsoft.ML.LightGbm 依赖 LightGBM 的非托管 C++ 实现，这部分代码以平台相关的动态链接库形式在运行时加载，它的兼容性逻辑与托管代码完全脱节，dotnet build 永远无法发现原生库的加载问题，只有在真实运行时触发特定代码路径时，问题才会暴露出来。这意味着即便 NuGet 包替换成功且编译零错误，我们仍然无法在完成跨平台功能验证之前自信地宣布升级成功。带着对这个特殊性的清醒认识，我们开始本次升级。

一、升级前的准备工作

本次升级涉及三个 NuGet 包：Microsoft.ML（ML.NET 核心）、Microsoft.ML.LightGbm（LightGBM 训练器集成）以及 MongoDB.Driver（FeedbackStorage 依赖）。在动手之前，我们需要分别确认它们在 .NET 10 环境下的兼容性情况，因为这三个包的技术架构各不相同，面临的升级挑战也存在显著差异。

我们首先打开 NuGet.org，搜索 Microsoft.ML。ML.NET 作为微软主推的机器学习框架，其 NuGet 包历来采用 netstandard2.0 作为基础目标框架------这是一个刻意为之的设计选择，目的是最大化跨平台兼容性。截至本文撰写时，Microsoft.ML 和 Microsoft.ML.LightGbm 的最新稳定版本均为 5.0.0 ，目标框架列表包含 netstandard2.0。虽然 5.0.0 未直接标注 net10.0 TFM，但这并不构成障碍------.NET 10 对 netstandard2.0 有完整的向下兼容支持，NuGet 在还原时会自动选取最合适的目标框架，整个引用过程对开发者完全透明。

MongoDB.Driver 的情况则简单许多。MongoDB 官方文档明确说明最新稳定版在 .NET 10 下经过验证，可以直接升级。FeedbackStorage 层仅使用了标准的 CRUD 和聚合查询 API，不涉及 GridFS 或 Change Streams 等高级特性，因此 MongoDB.Driver 的升级是本次操作中风险最低的部分，不需要专门的迁移评估。

然而，Microsoft.ML.LightGbm 的情况值得专门展开讲解。虽然 NuGet 包层面的兼容性没有问题，但 LightGBM 的核心计算引擎是以原生代码形式分发的，在 Windows 上是 LightGBM.dll，在 Linux 上是 lib_lightgbm.so，在 macOS 上是 lib_lightgbm.dylib。这些原生库被内嵌在 Microsoft.ML.LightGbm 的 NuGet 包中，按照 runtimes/{rid}/native/ 的目录结构组织，.NET 运行时在首次触发 LightGBM 相关计算时通过 P/Invoke 机制加载它们。这个加载过程中存在两个潜在的失败点：第一是运行时标识符（RID）解析错误，导致找不到对应平台的原生库文件，第二是平台系统依赖缺失，例如 Linux 环境下 LightGBM 原生库依赖 libgomp（OpenMP 运行时），而精简版 Docker 基础镜像通常不预装这个库。这两类问题都只会在运行时暴露，且触发时机是首次调用训练器或执行包含 LightGBM 节点的预测管道，而非服务启动时，这正是为什么仅靠观察服务能否启动来判断升级是否成功是远远不够的。

Tip：判断 ML.NET 升级是否需要专门关注原生库，有一个简单的标准------看项目是否引用了 Microsoft.ML.LightGbm、Microsoft.ML.OnnxRuntime 或类似以外部原生库为核心的扩展包。纯粹使用 Microsoft.ML 核心包（线性模型、决策树等）的项目不涉及额外的原生库，风险相对较低。而一旦引入了依赖外部 C++ 库的组件，跨平台原生库验证就是绕不过去的必要步骤。

综合评估后，本次升级的策略非常清晰：三个包均有可以直接引用的最新稳定版本，版本替换和编译验证是常规操作，真正的技术挑战集中在 LightGBM 原生库的跨平台加载验证，以及 CategoryMatcher 功能的端到端正确性确认。

二、升级

2.1 升级 NuGet 包

确定目标版本之后，包升级本身是一个直接的操作，同样以 Agent 模式交给 AI 完成。与其他步骤略有不同的是，我们需要在同一个指令中处理三个包，并且明确要求 AI 关注构建输出中的特定信息：

markdown 复制代码

请将 SP.MLService 项目中的以下 NuGet 包升级到最新稳定版本：
- Microsoft.ML → 5.0.0
- Microsoft.ML.LightGbm → 5.0.0
- MongoDB.Driver → 最新稳定版

完成后执行 `dotnet build`，将完整的构建输出返回给我。重点标注以下两类信息：
1. 任何 CS0246、CS1061、CS0619 等编译错误；
2. 任何 NU1701 目标框架兼容性警告，并注明是哪个包触发的。

AI 完成替换并执行构建后，我们需要仔细解读输出结果。与 Ocelot 升级时主要关注 CS0619 硬错误不同，Microsoft.ML 升级后更常见的构建输出是 NU1701 警告，其形式大致如下：

复制代码

warning NU1701: Package 'Microsoft.ML.LightGbm 5.0.0' was restored using
'.NETStandard,Version=v2.0' instead of the project target framework 'net10.0'.
This package may not be fully compatible with your project.

这条警告的含义是，NuGet 找不到精确匹配 net10.0 的版本，因此退而选用了 netstandard2.0 兼容包。这是预期内的正常行为，不代表功能异常，.NET 10 对 netstandard2.0 包有完整的运行时支持。但它确实提示我们，这个包尚未发布 net10.0 原生版本，原生库的加载行为需要通过运行时验证来最终确认，而不能靠构建结果来推断。

如果构建输出中出现了 CS0246（类型找不到）或 CS1061（方法或属性找不到）这类编译错误，则新版本 ML.NET 中某些 API 发生了破坏性变更，需要对照 ML.NET 5.0 的 CHANGELOG 找到替代 API 并逐一修复。CategoryMatcher.cs 中使用的核心 API MLContext 的初始化、TextFeaturizingEstimator 的 Pipeline 构建，以及 LightGbmRankingTrainer 的 Options 配置------在 ML.NET 5.0 中均保持了向后兼容的签名。孢子记账项目在此步骤预期不会出现编译错误，如果构建输出仅有若干 NU1701 警告，可以直接进入下一步。

2.2 跨平台原生库验证

构建通过之后，我们进入本次升级中技术含量最高的环节：原生库的跨平台加载验证。这是 Microsoft.ML 升级区别于其他所有步骤的核心所在，既不能跳过，也不能用编译结果代替，需要在 Windows 和 Linux 两个平台上分别完成。

Windows 平台验证 首先进行。在本机直接启动 SP.MLService，观察启动日志是否有任何异常输出。服务正常启动之后，通过 API 调用或直接触发的方式启动 CategoryMatcher 的训练流程------这一步会初始化 LightGbmRankingTrainer 并执行实际的 GBM 树构建，是在 Windows 环境下加载 LightGBM.dll 的唯一时机。训练完成后，再发起一次预测调用，观察分类排名结果是否正常返回。如果两个步骤均无异常，Windows 平台验证通过。

Linux 容器验证 随后进行，这是更关键的一步，因为生产部署的目标是 Docker/Linux 环境。在本地执行 docker build 构建 SP.MLService 的容器镜像（此时基础镜像应已更新为 mcr.microsoft.com/dotnet/aspnet:10.0），随后通过 docker run 启动容器，执行与 Windows 阶段完全相同的训练和预测调用。如果在容器中遇到类似以下的异常：

复制代码

System.DllNotFoundException: Unable to load shared library 'lib_lightgbm'
or one of its dependencies.

最常见的原因是容器镜像缺少 libgomp（OpenMP 运行时）。解决方案是在 Dockerfile 的运行时镜像层添加以下安装命令：

dockerfile 复制代码

RUN apt-get update && apt-get install -y --no-install-recommends libgomp1 \
    && rm -rf /var/lib/apt/lists/*

添加之后重新构建镜像并再次验证。值得反复强调的是，libgomp1 的缺失问题只会在 Linux 容器中出现，因为 Windows 的 Visual C++ 运行时已内置 OpenMP 支持，所以 Windows 平台验证通过并不能排除 Linux 上的此类问题------这正是必须在两个平台上分别验证而不能"以 Windows 代替 Linux"的根本原因。

Tip：在 Dockerfile 中安装系统依赖时，建议将 --no-install-recommends 标志与 rm -rf /var/lib/apt/lists/* 配合使用。前者避免安装不必要的推荐包，后者清除 apt 缓存，两者共同作用能够使最终镜像体积保持最小。对于生产服务镜像，这是一个值得养成的好习惯。

2.3 CategoryMatcher 功能验证

原生库跨平台验证通过之后，最后一步是对 CategoryMatcher 的核心业务逻辑进行端到端的功能验证。这一步的目的是确认 ML.NET 版本升级后，模型的训练行为和预测排名输出在业务层面保持正确。

CategoryMatcher 的工作流程分为两个阶段。训练阶段从 MongoDB 的 FeedbackStorage 中读取历史用户反馈数据，经过 Text Featurization Pipeline 对账单文本进行特征化处理，最终由 LightGbmRankingTrainer 拟合出一个学习排名（Learning to Rank）模型。预测阶段则接收账单文本输入，通过训练好的 ITransformer 执行推理，输出按相关性得分排序的分类候选列表。我们需要完整地触发这两个阶段，并核查两个方面：其一是训练过程是否正常完成（无异常抛出、ITransformer 正常生成）；其二是预测结果的 Top-N 排名是否与升级前的基线一致。

在实际操作中，同样可以让 AI 生成一个轻量验证脚本，读取少量历史反馈作为训练样本，执行训练后针对几条典型账单文本发起预测，将排名结果打印出来与升级前的基线记录进行比对：

markdown 复制代码

请基于 SP.MLService 中 CategoryMatcher 的现有代码，编写一个轻量验证脚本：
1. 从 MongoDB FeedbackStorage 读取少量历史数据作为训练样本；
2. 执行训练，确认 ITransformer 正常生成；
3. 针对以下三条测试账单文本发起预测，打印 Top-3 分类候选及得分：
   - "星巴克拿铁 35 元"
   - "滴滴出行 18 元"
   - "京东购物 299 元"

需要特别说明的是，ML.NET 版本升级后，模型输出的得分（score）数值可能在小数点后若干位发生微小变化，这是由 LightGBM 内部实现细节的版本差异引起的，属于正常现象。真正需要关注的是 Top-1 或 Top-3 候选分类的顺序是否出现颠覆性变化------如果原本"餐饮"排第一的账单，升级后依然应该返回"餐饮"作为最优候选。若出现了排名顺序的剧烈变化，则需要检查 TextFeaturizingEstimator 的默认超参数是否在新版本中发生了调整，并根据实际情况重新校准。

Tip：LightGbmRankingTrainer 的训练结果本质上依赖于训练数据的分布，而非固定的模型权重文件。FeedbackStorage 中积累的历史数据越多、质量越高，模型对 LightGBM 内部实现细节的版本差异就越有鲁棒性------数据的力量会让小版本变化带来的影响可以忽略不计。

三、总结

本次 SP.MLService 的依赖升级，从表象上看是三个 NuGet 包的版本替换，但它所包含的技术深度和验证复杂度远超其他步骤。Microsoft.ML 和 Microsoft.ML.LightGbm 的升级，涉及对 netstandard2.0 兼容性加载机制的理解、对 LightGBM 原生二进制文件跨平台加载链路的系统性验证设计，以及对机器学习模型在版本切换后数值稳定性的评估。而 MongoDB.Driver 的升级虽然是本次操作中最轻量的部分，但作为 FeedbackStorage 的核心依赖，同样需要在功能验证阶段确认读写链路的正常运转。

在风险把控的思路上，本次升级遵循了"构建验证 → 平台验证 → 功能验证"三层递进的策略。编译通过只是第一层门槛，仅能排除托管代码层面的 API 不兼容；Windows 和 Linux 双平台的原生库加载测试构成第二层，覆盖了两个实际部署目标；CategoryMatcher 端到端训练与预测验证从业务正确性角度提供最终确认。这三层验证之间存在严格的先后依赖，任何一层出现问题都需要先解决再继续，而不能跳跃。这个"三层递进"的验证策略，本质上是在回答一个问题：我们相信一次升级真正成功，需要相信到哪个粒度？对于涉及原生库的机器学习组件而言，只有业务功能验证通过，才是那个真正可以相信的粒度。

至此，整个孢子记账系统从 .NET 8 迁移到 .NET 10 的核心升级任务------涵盖基础框架、微软官方包、认证安全、API 文档、Ocelot 网关、OCR 方案以及 ML 服务依赖的全部升级工作------已经全部完成。接下来等待我们的，是最终的全链路集成验证，以及由此开启的 .NET 10 时代新篇章。