technology-selection

.NET AI 与机器学习

先选对技术，然后只交付任务要求的内容。如果任务要求制定计划、进行比较或设计架构（或明确说“不要编写代码”），就按要求完成——不要擅自搭建项目、构建或运行代码。

步骤 1：判断任务类型（决策树）

说明适用的分支及原因，然后选择对应的技术。

任务类型	技术	原因
结构化/表格数据：分类、回归、聚类、异常检测、推荐	ML.NET（Microsoft.ML）	结果确定（固定种子）、不依赖云、专为此类任务打造
自然语言理解、生成、摘要、推理（单次提示词 → 响应，不使用工具）	通过 Microsoft.Extensions.AI 使用 LLM（IChatClient）	提供语言能力，无需编排
Agent 式任务：多步骤工具/函数调用、Agent 循环、多 Agent	基于 Microsoft.Extensions.AI 使用 Microsoft Agent Framework（Microsoft.Agents.AI）	需要编排、工具分派和迭代控制；IChatClient 不具备这些能力
GitHub Copilot 扩展/自定义开发工作流 Agent	GitHub Copilot SDK（GitHub.Copilot.SDK）	与 Copilot Agent 运行时集成
在生产环境中运行预训练/自定义模型	ONNX Runtime（Microsoft.ML.OnnxRuntime）	支持硬件加速，推理不受格式限制
本地/离线 LLM 推理	OllamaSharp（Ollama 模型）	适用于隐私敏感、隔离网络或成本受限的场景
语义搜索、RAG、嵌入存储	Microsoft.Extensions.VectorData.Abstractions（MEVD）+ 提供程序（Azure AI Search、Milvus、MongoDB、pgvector、Pinecone、Qdrant、Redis、SQL）	与提供程序无关的向量搜索
将文档摄取、分块并载入向量存储	Microsoft.Extensions.AI.DataIngestion（预览版）+ MEVD	解析、分块、生成嵌入并执行 upsert
同时需要结构化预测和自然语言推理	混合方案：ML.NET 评分 + LLM 推理层	ML.NET 具有可复现性；LLM 可补充解释

**重要规则：**对于 ML.NET 能妥善处理的任务（表格分类、回归、聚类），不要使用 LLM——LLM 处理这些任务速度更慢、成本更高，结果也不确定。

步骤 1b：选择库层

层	库	适用场景
抽象层	Microsoft.Extensions.AI（MEAI）	始终作为基础层。对于提示词-响应和简单、有界的函数调用，直接使用 IChatClient。
提供程序 SDK	Azure.AI.OpenAI / OpenAI / Azure.AI.Inference / OllamaSharp	通过 AddChatClient 接入 MEAI 后使用的具体提供程序。
编排层	Microsoft.Agents.AI（预发行版）	多步骤工具使用、持久化 Agent 循环和多 Agent 工作流。
Copilot	GitHub.Copilot.SDK	仅用于构建 Copilot 平台扩展。

规则：从 MEAI 开始；通过 AddChatClient 将提供程序置于其后（不要在业务逻辑中直接调用提供程序）；对于多步骤或持久化 Agent 工作流，使用 Microsoft.Agents.AI，而不是手动编写 Agent 循环；不要在同一工作流中混用原始 HttpClient 对 OpenAI 的调用和 MEAI。不要使用 Accord.NET（已归档）。对于新项目，优先使用 MEAI 和 Agent Framework；只有在必须使用现有 Semantic Kernel 功能或投资时才例外。通过 DI 注册 AI/ML 服务；从 user-secrets / env / Key Vault 加载密钥——绝不要将密钥硬编码。

步骤 2：涵盖所选分支的基本要求，然后决定深入程度

每个回答——无论是计划还是实现——都必须满足所选分支的防护要求：

• ML.NET——使用 new MLContext(seed: …)（确保结果可复现）；使用 TrainTestSplit，并在留出集上进行评估；报告真实指标（MicroAccuracy/MacroAccuracy/LogLoss、AUC/F1 或 RMSE/R²）；使用 PredictionEnginePool<TIn,TOut> 提供服务（绝不能使用单例 PredictionEngine）。
• LLM (MEAI)——依赖通过 AddChatClient 注册的 IChatClient（底层接入具体提供程序）；在 ChatOptions 中设置 Temperature 和 MaxOutputTokens；添加重试/超时机制（RetryingChatClient/Polly）；固定使用带日期的模型；从 user-secrets / env / Key Vault 加载密钥——绝不硬编码 sk-… 密钥；根据架构校验非确定性输出，并提供回退方案。
• Agentic (Agent Framework)——使用 Microsoft.Agents.AI 和 IChatClient 进行编排（绝不手写循环）；设置 MaximumIterations 和令牌/成本上限；使用清晰的架构定义每个工具（AIFunctionFactory.Create）；记录每个步骤（绝不记录原始敏感内容）。
• RAG / embeddings——使用语义分块（而非固定大小）；使用 IEmbeddingGenerator 并缓存嵌入向量（不要针对每次查询重新生成嵌入）；使用 Microsoft.Extensions.VectorData.Abstractions (MEVD) 和用户指定的提供程序（例如 pgvector）进行存储/查询；按最低相似度分数过滤；为每个回答保留来源归属信息。遵循用户指定的 UI/存储方式；只使用真实存在的 NuGet 包。

然后选择深入程度：

• 仅提供计划 / 比较 / 架构（或“不要编写代码”）：仅依据本文件，使用上述基本要求作答。不要打开参考文档——此处的分支基本要求足以制定选择或计划。对于 RAG 计划，涵盖聊天、数据导入/分块、嵌入、向量存储、来源归属信息，以及用户要求的 UI/存储方式。
• 编写实现代码：阅读对应的参考文档，了解包和实现指南（仅阅读所选分支的文档；对于 Hybrid，阅读 Classic ML.NET 和 LLM 两者）：
  • Classic ML.NET → references/classic-ml.md
  • LLM 集成 (MEAI) → references/llm.md
  • Agentic (Agent Framework) → references/agentic.md
  • RAG / embeddings / 数据导入 → references/rag.md
  • GitHub Copilot 扩展 → references/copilot.md
  • ONNX Runtime 推理 → references/onnx.md
  • 使用 Ollama 的本地/离线 LLM → references/ollama.md

验证

• 选择符合决策树要求——ML.NET 能处理的任务不使用 LLM
• 只产出用户要求的内容（仅要求计划时提供计划，而非代码）
• AI/ML 服务通过 DI 注册；通过 IOptions<T> 配置；密钥来自安全来源
• 满足分支防护要求（步骤 2 中的基本要求，以及实现时的参考文档要求）
• 实现后，构建项目并运行现有测试

应拒绝的反模式

反模式	替代方案
使用 LLM 进行表格分类	使用 ML.NET ——速度更快、成本更低、结果确定
调用 LLM 时未设置重试/超时	添加 RetryingChatClient 或 Polly 重试
将 API 密钥提交到 appsettings.json	使用 user-secrets / env / Key Vault
使用 Accord.NET，或在没有需求的情况下默认采用 Semantic Kernel	使用 ML.NET；对于新工作，优先选择 MEAI + Microsoft.Agents.AI
使用 IChatClient 手写多步工具循环	使用 Microsoft.Agents.AI（MaximumIterations、工具调度）
用 Agent Framework 处理单次提示词→响应	直接使用 IChatClient
在 MEAI 之外的业务逻辑中使用原始 HttpClient/OpenAI SDK	使用单一抽象层；依赖 IChatClient
在 ASP.NET Core 中将 PredictionEngine 设为单例	使用 PredictionEnginePool<TIn,TOut>（非线程安全）
使用 RAG，但不进行分块或相关性筛选	采用语义分块 + 最低相似度分数
在 .NET 中从头构建自定义神经网络	通过 ONNX Runtime 使用预训练模型，或调用 LLM API