在 .NET 8+ 项目中为 AI/ML…

为 .NET 8+ 应用添加分类/回归/聚类、LLM 集成、RAG、Agent 工作流、Copilot 扩展或 ONNX 推理时，先按决策树选型再按分支护栏实现。

适用场景

解决思路

1. 先分类任务并说明适用哪一分支及原因，再据此选技术：结构化/表格类（分类、回归、聚类、异常检测、推荐）用 ML.NET（Microsoft.ML），因其确定性（固定种子）、无云依赖、专用；自然语言理解/生成/摘要/推理（单提示→响应、无工具）用 Microsoft.Extensions.AI 的 IChatClient 调 LLM；Agentic（多步工具/函数调用、agent 循环、多 agent）用基于 Microsoft.Extensions.AI 的 Microsoft Agent Framework（Microsoft.Agents.AI）；GitHub Copilot 扩展/自定义开发工作流 agent 用 GitHub Copilot SDK（GitHub.Copilot.SDK）；生产环境运行预训练/自定义模型用 ONNX Runtime（Microsoft.ML.OnnxRuntime）；本地/离线 LLM 推理用 OllamaSharp；语义搜索、RAG、嵌入存储用 Microsoft.Extensions.VectorData.Abstractions（MEVD）+ 提供方（Azure AI Search、Milvus、MongoDB、pgvector、Pinecone、Qdrant、Redis、SQL）；文档摄取、分块、载入向量库用 Microsoft.Extensions.AI.DataIngestion（预览）+ MEVD；同时需要结构化预测和自然语言推理时用混合方案：ML.NET 打分 + LLM 推理层。
2. 关键规则：不要用 LLM 做 ML.NET 擅长的表格分类、回归、聚类任务——LLM 更慢、更贵且不确定。
3. 按库分层选型：抽象层始终用 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 平台扩展。
4. 分层规则：从 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 加载，绝不硬编码。
5. 每个回答（无论计划还是实现）都必须覆盖所选分支的护栏：ML.NET 用 new MLContext(seed: …) 保证可复现，做 TrainTestSplit 并在留出集上评估，报告真实指标（MicroAccuracy/MacroAccuracy/LogLoss、AUC/F1 或 RMSE/R²），用 PredictionEnginePool<TIn,TOut> 提供服务（绝不用单例 PredictionEngine）。
6. LLM（MEAI）护栏：依赖通过 AddChatClient 注册的 IChatClient（提供方在其后）；在 ChatOptions 中设置 Temperature 和 MaxOutputTokens；加重试/超时（RetryingChatClient/Polly）；固定带日期的模型；密钥从 user-secrets / env / Key Vault 加载，绝不硬编码 sk-… 密钥；用 schema 校验非确定性输出并准备回退。
7. Agentic（Agent Framework）护栏：用基于 IChatClient 的 Microsoft.Agents.AI 编排（绝不手写循环）；设置 MaximumIterations 和 token/成本上限；用清晰 schema 定义每个工具（AIFunctionFactory.Create）；记录每一步（绝不记录原始敏感内容）。
8. RAG/嵌入护栏：语义分块（不要固定大小）；用 IEmbeddingGenerator 并缓存嵌入（不要每次查询重新嵌入）；用 Microsoft.Extensions.VectorData.Abstractions（MEVD）+ 用户指定的提供方（如 pgvector）存储/查询；按最低相似度分数过滤；为每个答案保留来源归属；遵循用户指定的 UI/存储；只使用真实存在的 NuGet 包。
9. 然后选择深度：若只是计划/对比/架构（或要求不写代码），仅依据本文件用上述护栏作答，不要打开参考文件；RAG 计划需覆盖 chat、摄取/分块、嵌入、向量存储、来源归属及所请求的 UI/存储。
10. 若编写实现代码，读取对应参考文件获取包和实现指引（只读所选分支；混合方案同时读 Classic ML.NET 和 LLM）：Classic ML.NET → references/classic-ml.md；LLM 集成（MEAI）→ references/llm.md；Agentic（Agent Framework）→ references/agentic.md；RAG/嵌入/摄取 → references/rag.md；GitHub Copilot 扩展 → references/copilot.md；ONNX Runtime 推理 → references/onnx.md；本地/离线 LLM（Ollama）→ references/ollama.md。
11. 验证清单：选型遵循决策树——ML.NET 能做的任务不用 LLM；只产出被要求的内容（仅要计划就只给计划，不写代码）；AI/ML 服务通过 DI 注册，配置用 IOptions<T>，密钥来自安全来源；满足分支护栏（Step 2 要点，实现时加参考文件）；实现后构建并运行现有测试。
12. 拒绝反模式并重定向：表格分类用 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；业务逻辑中原始 HttpClient/OpenAI SDK 与 MEAI 并存 → 单一抽象层，依赖 IChatClient；ASP.NET Core 中 PredictionEngine 单例 → 用 PredictionEnginePool<TIn,TOut>（非线程安全）；RAG 无分块或无相关性过滤 → 语义分块 + 最低相似度分数；在 .NET 中从零构建自定义神经网络 → 用 ONNX Runtime 跑预训练模型或 LLM API。

适用边界 · 注意事项

• 目标为 .NET Framework 的项目（需要 .NET 8+）
• 纯数据工程或 ETL 且无 ML/AI 组件的任务
• 需要自定义深度学习训练循环的项目（应使用 Python 的 PyTorch/TensorFlow，再导出 ONNX 供 .NET 推理）