9. 从0到上线：.NET 8 + ML.NET LTR 智能类目匹配实战--Web API 接口与前端集成：把能力对外开放

这篇文章我们将采用分层架构，向外开放预测、反馈（选择与纠正）、统计与手动重训四大能力，便于灵活集成至不同应用场景。接口契约统一采用 JSON DTO，幂等性和错误码设计规范，有助于前后端高效协作。

一、接口设计与契约

1.1 接口设计

我们项目对外暴露的所有 Web API 接口均集中在 CategoryPredictionController 控制器中，遵循简明统一的分层架构，便于维护与扩展。该控制器的路由前缀为 api/categoryprediction，所有能力接口都以此为基础进行分组管理。例如，预测接口路由为 api/categoryprediction/predict，反馈接口为 api/categoryprediction/feedback，统计接口和模型训练接口则分别为 api/categoryprediction/statistics 和 api/categoryprediction/retrain。这样做不仅便于前端进行统一调用，也方便后端进行权限、日志等横切关注点的管理。所有接口规范采用基于 JSON 的 DTO 作为输入输出参数，确保契约清晰、文档自动生成，并且通过 Swagger 提供在线调试与调用示例，极大降低了集成门槛。接口代码如下：

csharp 复制代码

using Microsoft.AspNetCore.Mvc;
using SporeAccountingML.App.Domain;
using SporeAccountingML.App.Services;

namespace SporeAccountingML.App.Controllers
{
    /// <summary>
    /// 消费类目预测控制器
    /// 提供基于机器学习的消费类目智能预测与渐进式学习功能
    /// </summary>
    /// <remarks>
    /// 主要功能：
    /// 1. 智能预测消费类目（结合规则匹配与ML模型）
    /// 2. 记录用户反馈（正确选择和错误纠正）
    /// 3. 触发增量学习优化模型
    /// 4. 提供学习统计信息
    /// </remarks>
    [ApiController]
    [Route("api/[controller]")]
    public class CategoryPredictionController : ControllerBase
    {
        /// <summary>
        /// 渐进式学习管理器，负责模型训练、预测和反馈收集
        /// </summary>
        private readonly ProgressiveLearningManager _learningManager;

        /// <summary>
        /// 构造函数，通过依赖注入获取渐进式学习管理器
        /// </summary>
        /// <param name="learningManager">渐进式学习管理器实例</param>
        public CategoryPredictionController(ProgressiveLearningManager learningManager)
        {
            _learningManager = learningManager;
        }

        /// <summary>
        /// 智能预测消费类目
        /// </summary>
        /// <param name="request">预测请求，包含查询文本和候选类目列表</param>
        /// <returns>预测结果，包含推荐类目、置信度、预测方法等信息</returns>
        /// <remarks>
        /// 预测流程：
        /// 1. 如果模型未训练或数据不足，使用规则匹配（关键词）
        /// 2. 如果模型已训练，使用机器学习预测
        /// 3. 根据置信度阈值判断是否需要用户确认
        /// 4. 预测失败时自动回退到规则匹配
        /// </remarks>
        [HttpPost("predict")]
        public async Task<ActionResult<PredictionResponse>> Predict([FromBody] PredictionRequest request)
        {
            // more code ...
        }

        /// <summary>
        /// 记录用户正确选择（正反馈）
        /// </summary>
        /// <param name="request">用户选择反馈请求</param>
        /// <returns>操作结果</returns>
        /// <remarks>
        /// 用于记录用户主动选择某个类目的行为，作为正样本用于模型训练。
        /// 系统会根据配置的重训频率自动触发增量学习。
        /// </remarks>
        [HttpPost("feedback/choice")]
        public async Task<ActionResult> RecordChoice([FromBody] ChoiceFeedbackRequest request)
        {
            // more code ...
        }

        /// <summary>
        /// 记录用户纠正（负反馈+正反馈）
        /// </summary>
        /// <param name="request">用户纠正反馈请求</param>
        /// <returns>操作结果</returns>
        /// <remarks>
        /// 用于记录用户纠正模型预测错误的行为：
        /// - 错误预测类目作为负样本
        /// - 用户纠正的正确类目作为正样本
        /// 纠正反馈比普通选择更重要，会立即触发增量学习
        /// </remarks>
        [HttpPost("feedback/correction")]
        public async Task<ActionResult> RecordCorrection([FromBody] CorrectionFeedbackRequest request)
        {
            // more code ...
        }

        /// <summary>
        /// 获取学习统计信息
        /// </summary>
        /// <returns>包含反馈数量、训练数据规模、模型状态等统计信息</returns>
        /// <remarks>
        /// 用于监控渐进式学习的进展：
        /// - 总反馈数：用户提供的选择和纠正总数
        /// - 训练数据量：转换为LTR格式的训练样本数
        /// - 模型状态：是否存在已训练的模型文件
        /// - 近期反馈：最近的反馈数量
        /// </remarks>
        [HttpGet("stats")]
        public async Task<ActionResult<LearningStatsResponse>> GetStats()
        {
            // more code ...
        }

        /// <summary>
        /// 手动触发模型重训
        /// </summary>
        /// <returns>操作结果</returns>
        /// <remarks>
        /// 管理员功能：手动强制触发增量学习，无需等待自动重训条件。
        /// 适用场景：
        /// - 收集到大量新反馈后立即优化模型
        /// - 系统维护时的模型更新
        /// - 测试和调试场景
        /// </remarks>
        [HttpPost("retrain")]
        public async Task<ActionResult> TriggerRetraining()
        {
            // more code ...
        }
    }
}

上面代码展示的是一个基于 ASP.NET Core 框架实现的 Web API 控制器CategoryPredictionController，它是整个消费类目智能预测系统对外能力开放的核心部分。

首先是预测接口Predict，它监听 POST api/categoryprediction/predict 路由，参数通过 [FromBody] 自动绑定为 PredictionRequest，即用户传递的预测请求体。该接口根据实际模型状态与数据量动态选择规则推断或机器学习方法进行预测，并输出包含推荐类目、置信度、推理方法等丰富信息。

反馈采集部分分为两种接口，分别是"用户主动选择类目"RecordChoice，接口路径为 POST api/categoryprediction/feedback/choice和"用户纠正预测错误"RecordCorrection，接口路径为 POST api/categoryprediction/feedback/correction。用户主动选择行为被认为是正样本，而纠正行为则既采集了负样本（模型预测但被判为错误的类目）又采集了正样本（用户实际上选择的正确类目），其中纠正反馈优先级更高，往往会即时触发增量学习。而普通选择通常根据配置达到批量后再自动训练。所有的反馈都能帮助模型自我进化，提升个性化和准确度。

另外控制器还暴露了系统运行关键状态的查询接口GetStats，对应 GET api/categoryprediction/stats，它会统计用户反馈总量、训练样本数量、模型是否存在、近期活跃度等指标，便于对渐进式学习状态的监控与可视化。管理员则可以通过 TriggerRetraining 接口绑定 POST api/categoryprediction/retrain手动触发一次模型重新训练，这适合特殊场景如批量反馈采集后需要立即更新训练成果或者测试、系统维护时手动操作。所有接口参数和返回值均为 DTO 类型，且始终采用 JSON 标准格式，有助于保持前后端契约的一致性和健壮性。

1.2 契约

本节详细介绍消费类目智能预测 Web API 的接口契约、主要数据结构。通过标准化的接口定义和数据传输对象（DTO），前端应用可以便捷、可靠地调用后台服务，获取预测结果、提交用户反馈及查询系统状态，从而实现个性化、智能化的消费分类体验。下面详细讲解消费类目智能预测 Web API 所用到的数据传输对象（DTO），这些结构定义了前后端交互的数据协议，是系统稳健和灵活的基础。

PredictionRequest（预测请求）
- 用于前端提交类目预测请求。
- 属性
  - Query：消费描述文本（如"星巴克咖啡"）。
  - Categories：当前用户自定义的全部消费类目（用于个性化和提升推荐准确性）。
  - UserId：用户身份标识。
  - Merchant：关联的商户信息（如"美团外卖"），可选。
  - AmountBucket：金额分箱，用于数值型特征，通常是整数（比如0-4分别代表金额区间段）。
  - HourOfDay：消费发生的小时，用于建模时间偏好。
- 用途：用户在前端填写账单描述、金额、选择商户后，由前端组装这个对象请求预测推荐。
PredictionResponse（预测响应）
- 后端返回预测的推荐类目以及置信度等元信息。
- 属性
  - PredictedCategory：预测出来的最优类目信息（见下文 CategoryDto）。
  - Confidence：预测置信度，越接近1说明系统越确定。
  - Method：采用的推断方式（如"RuleBased"规则、或"MachineLearning"机器学习）。
  - RequiresUserConfirmation：若置信度低，需用户二次确认，true 表示建议用户核查，false 可直接自动填入。
ChoiceFeedbackRequest（主动选择反馈）
- 用户主动选择了某个类目（即模型推荐和用户选择可能一致或不一致），用于采集正样本。
- 属性
  - Query：原始消费描述。
  - SelectedCategory：用户最后选择的类目。
  - AvailableCategories：当时所有可选类目，用于辅助负样本生成。
  - UserId、Merchant、AmountBucket、HourOfDay：同预测请求中含义一致。
- 用途：用户点击确认/更改分类后，由前端收集这些信息发送给后端反馈采集接口。
CorrectionFeedbackRequest（纠正反馈）
- 用户对模型错误推荐进行纠正，系统既可采集负样本（错误推荐），又能采集正样本（用户正确选择）。
- 属性
  - Query：消费描述。
  - WrongCategory：模型实际推荐且被判错的类目。
  - CorrectCategory：用户实际选择的正确类目。
  - AvailableCategories、UserId、Merchant、AmountBucket、HourOfDay：含义同上。
- 用途：用户发现推荐错误并手工更正时，反馈这两个信息，便于系统调整模型。
CategoryDto（类目描述对象）
- 用户自定义的类目在系统内的表达方式（持久化和传输格式）。
- 属性
  - Id：类目唯一标识。
  - Name：类目的显示名称（如"餐饮""交通"）。
LearningStatsResponse（学习统计）
- 用于前端展示模型与反馈采集的整体进展。
- 属性
  - TotalFeedbacks：历史总反馈数量（选择+纠正）。
  - TrainingDataSize：训练用样本的数量，意味着模型学习了多少数据。
  - ModelExists：是否已存在至少一次训练出的模型（决定能否机器学习推断）。
  - RecentFeedbacks：近10条反馈的数量（可展示近期活跃度）。

三、总结

本篇文章介绍了如何通过分层架构设计，将智能消费类目预测的各项能力以 Web API 方式标准化对外开放，涵盖了预测、反馈采集、统计查询和模型手动重训等核心功能。所有接口均采用统一的 JSON DTO 契约。通过良好的接口设计和数据结构规范，前端可以高效接入智能分类能力，后端则能够灵活演进和运维模型系统。无论是实际应用场景还是后续功能扩展，这一套开放接口体系为智能账单分类系统提供了坚实高效的基础。