用途
当 MAUI 应用需要通过 Microsoft.Maui.Essentials.AI 与 Microsoft.Extensions.AI 抽象使用设备本地 AI 时，可使用本技能。它帮助开发者明确应提及的包与主要类型：Microsoft.Maui.Essentials.AI、AppleIntelligenceChatClient、NLEmbeddingGenerator，并保持平台支持说明清晰。
平台支持
聊天支持： iOS 26+ 使用 Apple Intelligence / Foundation Models；Mac Catalyst 26+ 使用 Apple Intelligence；macOS 26+ 使用 Apple Intelligence；Android 与 Windows 标注为即将推出。
嵌入支持： iOS 13+ 使用 NaturalLanguage embeddings；Mac Catalyst 13.1+ 使用 NaturalLanguage embeddings；macOS 10.15+ 使用 NaturalLanguage embeddings；Android 与 Windows 不支持。
Apple Intelligence 支持的版本号反映当前已公布的 OS 版本；发布前应核实最终发布的平台版本。
应为不支持的平台设计回退行为。除非用户明确希望使用云端回退，否则不要将私有数据静默路由到云端模型。
安装与注册
安装命令： dotnet add package Microsoft.Maui.Essentials.AI --prerelease
注册示例（保留原始代码）：
using Microsoft.Extensions.AI; using Microsoft.Extensions.DependencyInjection; using Microsoft.Maui.Essentials.AI;
#if IOS || MACCATALYST || MACOS builder.Services.AddSingleton<NLEmbeddingGenerator>(); builder.Services.AddSingleton<IEmbeddingGenerator<string, Embedding<float>>>(sp => sp.GetRequiredService<NLEmbeddingGenerator>());
if (OperatingSystem.IsIOSVersionAtLeast(26) || OperatingSystem.IsMacCatalystVersionAtLeast(26) || OperatingSystem.IsMacOSVersionAtLeast(26)) { builder.Services.AddSingleton<IChatClient>(new AppleIntelligenceChatClient()); } else { // Leave IChatClient unregistered and check availability before use, // or register an app-specific unavailable implementation. } #endif
如果应用同时面向不支持的平台，应有条件地注册平台特定实现。如果应用的最低 Apple OS 目标低于 26，应使用运行时 OS 检查来保护聊天注册，或为较旧 OS 版本注册应用特定的不可用实现。对于 MAUI Labs AppKit（MACOS），发布前应针对目标包验证 Essentials.AI 集成。
聊天工作流
将 IChatClient 注入视图模型或服务，而不是直接注入页面，除非应用架构已经如此。从命令和生命周期边界传递取消令牌。对交互式 UI 使用流式响应：
await foreach (var update in _chat.GetStreamingResponseAsync(messages, cancellationToken)) { MainThread.BeginInvokeOnMainThread(() => ResponseText += update.Text); }
将对话状态保存在应用服务中，使其在页面重建后仍然存在。在 UI 中呈现模型可用性与失败状态。如果视图模型框架已将属性更改封送到 UI 线程，则沿用该约定；否则显式调度绑定到 UI 的属性更新。
嵌入与语义搜索
使用 NLEmbeddingGenerator 对应用自有内容进行本地语义搜索。默认构造函数使用 Apple 的英语句子嵌入；当应用需要其他受支持语言或嵌入时，可传入 NaturalLanguage.NLLanguage 或现有的 NaturalLanguage.NLEmbedding：
#if IOS || MACCATALYST || MACOS var generator = new NLEmbeddingGenerator(); var embeddings = await generator.GenerateAsync( ["sunset beach", "mountain hiking"], cancellationToken); #endif
推荐做法：将应用内容分块为小型可搜索记录；在摄取/更新时生成嵌入；本地存储向量与元数据；用余弦相似度比较查询嵌入；返回源片段与 ID，以便 UI 展示有依据的结果。避免每次搜索都对整个语料库重新生成嵌入。
工具使用
Essentials AI 返回 Microsoft.Extensions.AI 客户端，因此适用常规工具调用模式：
var innerClient = serviceProvider.GetService<IChatClient>(); if (innerClient is null) { // Chat is unavailable on this platform/OS version; hide or disable the feature. return; }
var appTools = YourAppTools.Default.Tools; // Define with [AIToolSource]; see maui-ai-tool-bindings.
var client = innerClient.AsBuilder() .UseFunctionInvocation() .ConfigureOptions(options => { options.Tools ??= []; foreach (var tool in appTools) options.Tools.Add(tool); }) .Build(serviceProvider);
当工具应通过 [ExportAIFunction]、DI 参数绑定或 AOT 友好定义从应用方法生成时，使用 maui-ai-tool-bindings。
隐私与用户体验护栏
说明 AI 在受支持的 Apple 平台上于设备本地运行。在添加云端回退前先询问用户。将提示、嵌入和工具输出保持在应用的数据处理策略范围内。展示不支持设备与模型不可用状态。生成响应或嵌入时不要阻塞 UI 线程。对会修改数据、发送消息、购买、删除或意外导航的操作，使用需要批准的工具。
验证清单
应用目标平台支持所请求的 AI 能力，或具有显式回退。AI 客户端已在 DI 中注册，并从服务/视图模型中使用。已处理流式传输、取消和错误状态。语义搜索将元数据与嵌入一起存储，并避免每次查询都全量重新摄取。工具使用有范围限制，敏感操作需用户批准。