重要的 API 概念Important API concepts

注意

針對發行前產品的部分相關資訊,在產品正式發行時可能會有大幅修改。Some information relates to pre-released product, which may be substantially modified before it's commercially released. 針對此處提供的資訊,Microsoft 不做任何明示或默許的擔保。Microsoft makes no warranties, express or implied, with respect to the information provided here.

SkillInterfacePreview命名空間提供一組基底介面,可供所有技能擴充,以及適用于 Windows 上技能實施者的類別和協助程式方法。The Microsoft.AI.Skills.SkillInterfacePreview namespace provides a set of base interfaces to be extended by all skills as well as classes and helper methods for skill implementers on Windows.

此 API 旨在簡化技能的運作方式,以及開發人員與它們互動的方式。This API is meant to streamline the way skills work and how developers interact with them. 其目標是要將每個技能邏輯的 API 特例抽象化,並改用一組廣泛方案和應用程式的一致開發人員直覺。The goal is to abstract away the API specificities of each skill's logic and leverage instead a consistent developer intuition over a broad set of solutions and applications. 它也可以利用 Windows 基本專案,以簡化作業系統 Api 的互通性。It is also meant to leverage Windows primitives which eases interop with OS APIs. 這構成一個衍生自的範本,可將開發人員流程和 API 互動標準化于所有技能上。This constitutes a template to derive from that standardizes the developer flow and API interactions across all skills.

因此,所有技能都應該以最少的下列介面來執行:Therefore all skills are expected to implement at the very least the following interfaces:


名稱Name 描述Description
ISkillDescriptorISkillDescriptor 提供技能的相關資訊,並公開其要求 (輸入、輸出、版本等) 。Provides information on the skill and exposes its requirements (input, output, version, etc). 作為 ISkill的 factory。Acts as a factory for the ISkill.
ISkillBindingISkillBinding 作為 ISkillFeature的索引容器。Serves as an indexed container of ISkillFeature. 它可做為輸入和輸出變數的管道,以來回傳遞給 ISkillIt acts as a conduit for input and output variables to be passed back and forth to the ISkill. 它會處理輸入/輸出資料的前置處理和後置處理,並簡化其存取。It handles pre-processing and post-processing of the input/output data and simplifies their access.
ISkillISkill 公開處理其輸入,並透過 ISkillBinding形成其輸出的核心邏輯。Exposes the core logic of processing its input and forming its output via an ISkillBinding. 作為 ISkillBinding的 factory。Acts as a factory for the ISkillBinding.

技能的目的是要以最佳的方式利用硬體功能 (CPU、GPU 等 ) 其執行所在的每個系統。Skills are meant to optimally leverage the hardware capabilities (CPU, GPU, etc.) of each system they run on. 這些硬體加速裝置是藉由衍生與SkillExecutionDeviceKind相關聯的ISkillExecutionDevice介面來表示。These hardware acceleration devices are represented by deriving the ISkillExecutionDevice interface associated with a SkillExecutionDeviceKind. 因此, ISkillDescriptor衍生物件必須尋找、篩選和公開可執行ISkill邏輯的主機系統上目前可用的一組ISkillExecutionDevice物件。Therefore, ISkillDescriptor derivatives have to find, filter, and expose the set of ISkillExecutionDevice objects currently available on the host system that can execute the ISkill logic.

這可讓開發人員取用技能套件,以最佳選擇如何在使用者系統上的執行時間中使用支援的硬體資源。This will allow the developer consuming the skill package to best chose how to tap into supported hardware resources at runtime on a user's system. 有些 ISkillExecutionDevice 衍生類別已定義,而且可供便利性 (SkillExecutionDeviceCPUSkillExecutionDeviceDirectX) 。There are some ISkillExecutionDevice derivative classes already defined and available for convenience (SkillExecutionDeviceCPU and SkillExecutionDeviceDirectX).

為了確保輸入和輸出變數會以正確的格式傳遞給技能,會定義 ISkillFeature 介面。In order to ensure that input and output variables are passed in the correct format to the skill, the ISkillFeature interface is defined. 其目的是要以預先定義的格式來封裝值。It is meant to encapsulate a value in a predefined format. 這個值是以 ISkillFeatureValue的衍生表示,它有多個已定義的常見衍生,可供便利性 (ISkillFeatureTensorValueSkillFeatureImageValueSkillFeatureMapValue) 。This value is represented by a derivative of ISkillFeatureValue, which has multiple common derivatives already defined and available for convenience (ISkillFeatureTensorValue, SkillFeatureImageValue, and SkillFeatureMapValue).

每個 ISkillFeatureValue 衍生都有一個對應的 ISkillFeatureDescriptor 衍生定義,可描述技能所支援的預期格式 (ISkillFeatureTensorDescriptorISkillFeatureImageDescriptorISkillFeatureMapDescriptor) 。Each ISkillFeatureValue derivative has a corresponding ISkillFeatureDescriptor derivative defined that describes the expected format supported by the skill (ISkillFeatureTensorDescriptor, ISkillFeatureImageDescriptor, and ISkillFeatureMapDescriptor). 這些 ISkillFeatureDescriptor 衍生物件也可作為其所描述之 ISkillFeatureValue 物件的 factory 物件。These ISkillFeatureDescriptor derivatives also act as factory objects for the ISkillFeatureValue objects they describe.

在具現化時,如果用來指派給 ISkillFeatureValue 的基本型別不符合其 ISkillFeatureDescriptor 對應項所提供的描述,則每種類型專屬的自動轉換都可以順暢地進行 (例如,將影像系結的格式與所需的影像不同,或裁剪外觀比例是否不同) 。At instantiation time, if the primitive used to assign to ISkillFeatureValue does not match the description provided by its ISkillFeatureDescriptor counterpart, an automatic conversion specific to each type can occur seamlessly (for example, transcoding when binding an image in a different format than the one required, or cropping if the aspect ratio differs).

API 流程 API flow

由於所有技能都會從 SkillInterfacePreview衍生一組相同的基底介面,因此它們都遵循相同的流程,通常會細分為下列作業:Since all skills derive the same set of base interfaces from Microsoft.AI.Skills.SkillInterfacePreview, they all follow the same flow which usually boils down to the following operations:

Windows 視覺技能 API 流程圖展示從應用程式擷取 Windows 視覺技能的一般 API 呼叫順序

  1. 具現化 ISkillDescriptor 衍生。Instantiate the ISkillDescriptor derivative.

  2. 使用步驟1中的實例查詢可用的執行裝置 (使用 ISkillDescriptor. GetSupportedExecutionDevicesAsync) 或略過並直接嘗試步驟3。Query the available execution devices using the instance from step 1 (using ISkillDescriptor.GetSupportedExecutionDevicesAsync) or skip and directly attempt step 3.

  3. 使用步驟1中的實例和步驟2中所需的執行裝置來具現化技能 (使用 ISkillDescriptor. CreateSkillAsync (ISkillExecutionDevice) ) 或由技能開發人員 (使用 ISkillDescriptor. CreateAsync ( # B6 ) 所決定的預設值。Instantiate the skill using the instance from step 1 and the desired execution device from step 2 (using ISkillDescriptor.CreateSkillAsync(ISkillExecutionDevice)) or the default one decided by the skill developer (using ISkillDescriptor.CreateAsync()).

  4. 使用 ISkill CreateSkillBindingAsync) 的步驟 3 (中的技能實例,具現化技能系結物件。Instantiate a skill binding object using the skill instance from step 3 (using ISkill.CreateSkillBindingAsync).

  5. 從您的應用程式中 ) 取得基本 (>videoframeIVectorViewIMapView等,然後藉由存取透過其名稱編制索引的對應 ISkillFeature ,並呼叫 ISkillFeature (物件) ) ,來將其系結至步驟 4 (的系結物件。Retrieve your primitives (VideoFrame, IVectorView, IMapView, etc.) from your application and bind them to your binding object from step 4 (by accessing the corresponding ISkillFeature indexed via its name and calling ISkillFeature.SetFeatureValueAsync(Object)).

  6. 藉由呼叫 ISkill EvaluateAsync) ,在您的系結物件 (上執行您的技能。Run your skill over your binding object (by calling ISkill.EvaluateAsync).

  7. 從步驟 (4 中具現化的系結物件取得輸出基本專案,方法是透過其名稱存取對應的 ISkillFeature ,並呼叫 getter ISkillFeature. FeatureValue) 。Retrieve your output primitives from your binding object instantiated in step 4 (by accessing the corresponding ISkillFeature indexed via its name and calling the getter ISkillFeature.FeatureValue).

  8. 使用相同的系結物件和新的基本專案,清除並重複執行步驟5。Rinse and repeat from step 5 using the same binding object and new primitives.

若要查看其實際運作情形,請參閱 從應用程式擷取 Windows 視覺技能的教學課程。To see this in action, refer to the tutorial on ingesting a Windows Vision Skill from an app.

注意

使用下列資源取得 Windows Vision Skills 的說明:Use the following resources for help with Windows Vision Skills: