Windows 应用 SDK中的 AI 映像入门

项目
02/11/2025

重要

Windows 应用 SDK 的最新试验通道版本中提供。

Windows 应用 SDK 试验通道包括开发早期阶段的 API 和功能。试验通道中的所有 API 都可能经过大量修订和中断性变更，并且随时可从后续版本中删除。实验性功能不支持在生产环境中使用，且使用这些功能的应用无法发布到Microsoft应用商店。

图像处理功能在中国不可用。
不支持解压缩的应用。

映像功能由 Windows 应用 SDK 通过一组由人工智能（AI 提供支持）的 API 提供，这些 API 支持以下功能：

图像超级分辨率：缩放和锐化图像
图像说明：生成描述图像的文本
图像分段：标识图像中的对象

有关 API 详细信息，请参阅 Windows 应用 SDK 中 AI 成像功能的 API 参考。

有关 内容管理的详细信息，请参阅生成式 AI API内容安全。

提示

通过在 Windows 应用 SDK GitHub 存储库中创建新问题（在标题中包括Imaging）或通过响应现有问题，提供有关这些 API 及其功能的反馈。

先决条件

来自高通、Intel 或 AMD 的 CoPilot+ 电脑（基于 AMD 的 CoPilot+ 电脑当前不支持图像超级分辨率）。
Windows 11 Insider Preview 内部版本 26120.3073（开发和 Beta 频道）或更高版本必须安装在设备上。

我可以使用图像超分辨率做什么？

Windows 应用 SDK 中的图像超分辨率 API 支持图像锐化和缩放。

缩放的最大限制为 8 倍。较大的缩放系数可能会引入伪影并损害图像准确性。如果最终宽度或高度大于其原始值 8 倍，则会引发异常。

下面的示例演示如何更改现有软件位图图像（softwareBitmap）的规模（targetWidth、targetHeight），并改进图像锐度（为了在不缩放图像的情况下提高锐度，只需使用 ImageScaler 对象指定现有图像宽度和高度）。

通过调用 ImageScaler.IsAvailable 方法，然后等待 ImageScaler.MakeAvailableAsync 方法成功返回，确保图像超分辨率模型可用。
图像超级分辨率模型可用后，创建一个 ImageScaler 对象来引用它。
通过使用 ScaleSoftwareBitmap 方法将现有图像和所需宽度和高度传递给模型，获取现有图像的锐化和缩放版本。

using Microsoft.Windows.Imaging;
using Microsoft.Windows.Management.Deployment;
using Windows.Graphics.Imaging;

if (!ImageScaler.IsAvailable())
{
    var result = await ImageScaler.MakeAvailableAsync();
    if (result.Status != PackageDeploymentStatus.CompletedSuccess)
    {
        throw result.ExtendedError;
    }
}
ImageScaler imageScaler = await ImageScaler.CreateAsync();
SoftwareBitmap finalImage = imageScaler.ScaleSoftwareBitmap(softwareBitmap, targetWidth, targetHeight);

#include <winrt/Microsoft.Graphics.Imaging.h>
#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.Graphics.Imaging.h>

using namespace winrt::Microsoft::Graphics::Imaging;
using namespace winrt::Windows::Foundation; 
using namespace winrt::Windows::Graphics::Imaging; 

 
if (!ImageScaler::IsAvailable()) 
{ 
    winrt::PackageDeploymentResult result = ImageScaler::MakeAvailableAsync().get(); 
    if (result.Status() != PackageDeploymentStatus::CompletedSuccess)
    {
       throw result.ExtendedError();
    }
}

ImageScaler imageScaler = ImageScaler::CreateAsync().get(); 
SoftwareBitmap finalImage = imageScaler.ScaleSoftwareBitmap(softwareBitmap, targetWidth, targetHeight);

图像说明可以用来做些什么？

重要

图像说明目前在中国不可用。

Windows 应用 SDK 中的图像说明 API 提供为图像生成各种类型的文本说明的功能。

支持以下类型的文本说明：

无障碍访问 - 提供详细说明，包含面向具有无障碍需求用户的详细信息。
字幕 - 提供适合图像字幕的简短说明。如果未指定任何值，则为默认值。
DetailedNarration - 提供较长的说明。
OfficeCharts - 提供适合图表和关系图的说明。

由于这些 API 使用机器学习（ML）模型，因此在文本无法正确描述图像的位置偶尔会发生错误。因此，不建议在以下方案中将这些 API 用于映像：

其中图像包含潜在的敏感内容和不准确的描述可能会引起争议，例如国旗、地图、地球、文化符号或宗教符号。
当准确的描述至关重要时，例如医疗建议或诊断、法律内容或财务文档。

从图像获取文本说明

图像说明 API 采用图像、所需文本描述类型（可选）和要采用的内容审查级别（可选），以防止有害使用。

以下示例演示如何获取图像的文本说明。

注意

映像必须是 ImageBuffer 对象，因为当前不支持 SoftwareBitmap。此示例演示如何将 SoftwareBitmap 转换为 ImageBuffer。

通过调用 ImageDescriptionGenerator.IsAvailable 方法，然后等待 ImageDescriptionGenerator.MakeAvailableAsync 方法成功返回，确保图像超分辨率模型可用。
图像超级分辨率模型可用后，创建一个 ImageDescriptionGenerator 对象来引用它。
（可选）创建 ContentFilterOptions 对象并指定首选值。如果选择使用默认值，则可以传入 null 对象。
通过调用 ImageDescriptionGenerator.DescribeAsync 方法，同时使用原始图像、首选说明类型的枚举（可选）以及 ContentFilterOptions 对象（可选）来获取图像说明（LanguageModelResponse.Response）。

using Microsoft.Graphics.Imaging;
using Microsoft.Windows.Management.Deployment;  
using Microsoft.Windows.AI.Generative;
using Microsoft.Windows.AI.ContentModeration;
using Windows.Storage.StorageFile;  
using Windows.Storage.Streams;  
using Windows.Graphics.Imaging;

if (!ImageDescriptionGenerator.IsAvailable())
{
    var result = await ImageDescriptionGenerator.MakeAvailableAsync();
    if (result.Status != PackageDeploymentStatus.CompletedSuccess)
    {
        throw result.ExtendedError;
    }
}

ImageDescriptionGenerator imageDescriptionGenerator = await ImageDescriptionGenerator.CreateAsync();

// Convert already available softwareBitmap to ImageBuffer.
ImageBuffer inputImage = ImageBuffer.CreateCopyFromBitmap(softwareBitmap);  

// Create content moderation thresholds object.
ContentFilterOptions filterOptions = new ContentFilterOptions();
filterOptions.PromptMinSeverityLevelToBlock.ViolentContentSeverity = SeverityLevel.Medium;
filterOptions.ResponseMinSeverityLevelToBlock.ViolentContentSeverity = SeverityLevel.Medium;

// Get text description.
LanguageModelResponse languageModelResponse = await imageDescriptionGenerator.DescribeAsync(inputImage, ImageDescriptionScenario.Caption, filterOptions);
string response = languageModelResponse.Response;

#include <winrt/Microsoft.Graphics.Imaging.h>
#include <winrt/Microsoft.Windows.AI.ContentModeration.h>
#include <winrt/Microsoft.Windows.AI.Generative.h>
#include <winrt/Windows.Foundation.h>
#include <winrt/Windows.Graphics.Imaging.h> 
#include <winrt/Windows.Storage.Streams.h>
#include <winrt/Windows.Storage.StorageFile.h>
using namespace winrt::Microsoft::Graphics::Imaging; 
using namespace winrt::Microsoft::Windows::AI::ContentModeration; 
using namespace winrt::Microsoft::Windows::AI::Generative; 
using namespace winrt::Windows::Foundation; 
using namespace winrt::Windows::Graphics::Imaging;
using namespace winrt::Windows::Storage::Streams;
using namespace winrt::Windows::Storage::StorageFile;

if (!ImageDescriptionGenerator::IsAvailable()) 
{ 
    winrt::PackageDeploymentResult result = ImageDescriptionGenerator::MakeAvailableAsync().get(); 
    if (result.Status() != PackageDeploymentStatus::CompletedSuccess)
    {
       throw result.ExtendedError();
    }
}

ImageDescriptionGenerator imageDescriptionGenerator = ImageDescriptionGenerator::CreateAsync().get(); 
// Convert already available softwareBitmap to ImageBuffer.
auto inputBuffer = ImageBuffer::CreateCopyFromBitmap(softwareBitmap); 

// Create content moderation thresholds object.
 ContentFilterOptions contentFilter{};
 contentFilter.PromptMinSeverityLevelToBlock().ViolentContentSeverity(SeverityLevel::Medium);
 contentFilter.ResponseMinSeverityLevelToBlock().ViolentContentSeverity(SeverityLevel::Medium);


// Get text description.
LanguageModelResponse languageModelResponse = imageDescriptionGenerator.DescribeAsync(inputImage, ImageDescriptionScenario::Caption, contentFilter).get();
string text = languageModelResponse.Response();

我可以用图像分割做什么？

图像分段可用于标识图像中的特定对象。模型同时获取图像和“提示”对象，并返回已标识对象的掩码。

可以通过以下任意组合提供提示：

属于要标识的点的坐标。
不属于要标识的点的坐标。
一个坐标矩形，该矩形将你标识的内容括起来。

提供的提示越多，模型就越精确。遵循以下提示准则，尽量减少不准确的结果或错误。

避免在提示中使用多个矩形，因为它们可以生成不准确的掩码。
避免以独占方式使用排除点，而无需包含点或矩形。
不要指定最多 32 个坐标（一个点为 1，一个矩形为 2），因为这将返回错误。

返回的掩码采用灰度-8 格式，其中标识对象的掩码的像素值为 255（所有其他值为 0）。

标识图像中的对象

以下示例演示了标识图像中的对象的方法。这些示例假定你已经有一个用于输入的软件位图对象（softwareBitmap）。

通过调用 IsAvailable 方法并等待 MakeAvailableAsync 方法成功返回，确保图像分段模型可用。
图像分段模型可用后，创建一个 ImageObjectExtractor 对象来引用它。
将图像传递给 ImageObjectExtractor.CreateWithSoftwareBitmapAsync。
创建一个 ImageObjectExtractorHint 对象。稍后将演示创建具有不同输入的提示对象的其他方法。
使用 GetSoftwareBitmapObjectMask 方法将提示提交到模型，该方法会返回最终结果。

using Microsoft.Windows.Imaging;
using Microsoft.Windows.Management.Deployment;
using Windows.Graphics.Imaging;

if (!ImageObjectExtractor.IsAvailable())
{
    var result = await ImageObjectExtractor.MakeAvailableAsync();
    if (result.Status != PackageDeploymentStatus.CompletedSuccess)
    {
        throw result.ExtendedError;
    }
}

ImageObjectExtractor imageObjectExtractor = await ImageObjectExtractor.CreateWithSoftwareBitmapAsync(softwareBitmap);

ImageObjectExtractorHint hint = new ImageObjectExtractorHint{
    includeRects: null, 
    includePoints:
        new List<PointInt32> { new PointInt32(306, 212),
                               new PointInt32(216, 336)},
    excludePoints: null};
    SoftwareBitmap finalImage = imageObjectExtractor.GetSoftwareBitmapObjectMask(hint);

#include <winrt/Microsoft.Graphics.Imaging.h> 
#include <winrt/Windows.Graphics.Imaging.h>
#include <winrt/Windows.Foundation.h>
using namespace winrt::Microsoft::Graphics::Imaging; 
using namespace winrt::Windows::Graphics::Imaging; 
using namespace winrt::Windows::Foundation; 


if (!ImageObjectExtractor::IsAvailable()) 
{ 
    winrt::PackageDeploymentResult result = ImageObjectExtractor::MakeAvailableAsync().get(); 
    if (result.Status() != PackageDeploymentStatus::CompletedSuccess)
    {
       throw result.ExtendedError();
    }
}

ImageObjectExtractor imageObjectExtractor =  ImageObjectExtractor::CreateWithSoftwareBitmapAsync(softwareBitmap).get();

ImageObjectExtractorHint hint(
    {}, 
    { 
        PointInt32{306, 212}, 
        PointInt32{216, 336} 
    },
    {}
);

SoftwareBitmap finalImage = imageObjectExtractor.GetSoftwareBitmapObjectMask(hint);

指定包含和排除点的提示

此代码片段演示如何将包含的和排除的点用作提示。

ImageObjectExtractorHint hint(
    includeRects: null,
    includePoints: 
        new List<PointInt32> { new PointInt32(150, 90), 
                               new PointInt32(216, 336), 
                               new PointInt32(550, 330)},
    excludePoints: 
        new List<PointInt32> { new PointInt32(306, 212) });

ImageObjectExtractorHint hint(
    {}, 
    { 
        PointInt32{150, 90}, 
        PointInt32{216, 336}, 
        PointInt32{550, 330}
    },
    { 
        PointInt32{306, 212}
    }
);

使用矩形指定提示

此代码片段演示如何将矩形（RectInt32 X, Y, Width, Height）用作提示。

ImageObjectExtractorHint hint(
    includeRects: 
        new List<RectInt32> {new RectInt32(370, 278, 285, 126)},
    includePoints: null,
    excludePoints: null );

ImageObjectExtractorHint hint(
    { 
        RectInt32{370, 278, 285, 126}
    }, 
    {},
    {}
);

负责任的 AI

这些映像 API 为开发人员提供了强大的可信模型，用于构建具有安全安全 AI 体验的应用。我们已使用以下步骤的组合来确保这些映像 API 可信、安全且负责任地生成。我们建议在应用中实施 AI 功能时，参阅 Windows 上负责任的生成式 AI 开发中描述的最佳做法。

对模型质量进行彻底测试和评估，以识别和缓解潜在风险。
逐步推出图像处理 API 试验版。在最终的实验发布之后，推出将扩展到已签名的应用，以确保恶意软件扫描已应用于具有本地模型功能的应用程序。
为内容审查提供本地 AI 模型，用于识别和筛选任何使用生成 AI 模型的 API 的输入和 AI 生成的输出中的有害内容。此本地内容审查模型基于 Azure AI 内容安全模型进行文本审查并提供类似的性能。

重要

没有任何内容安全系统是完美无瑕的，偶尔会发生错误，因此我们建议集成补充的负责任 AI（RAI）工具和实践。有关更多详细信息，请参阅 Windows 上负责任的生成式 AI 开发。

通过