この記事は、https://www.oneapi.io/spec/ で 2023年9月14日に公開された『oneAPI 1.3 Provisional Specification Rev. 1』 (HTML、PDF) をベースにしています。原文は2000 ページ近くあり、翻訳の時間とリソースも限られるため、全文翻訳ではなく、記事形式で区切った仕様とその解説を提供することにしました。
この回では、『oneAPI 1.3 Provisional Specification Rev. 1』の「oneDAL」の「End-to-end example」と「Descriptors」の節を取り上げています。
エンドツーエンドの例
以下に、GPU で oneDAL アルゴリズムを使用する一般的なワークフローを示します。この例は、主成分分析アルゴリズム (Principal Component Analysis algorithm (PCA)) (英語) 向けに提供されています。
以下に手順を示します。
- CSV ファイルからデータを読み取ります。
- PCA のトレーニングと推論操作を実行します。
- トレーニング・ステージで得られた中間結果にアクセスします。
すべての oneDAL 宣言を利用できるように、次のヘッダーをインクルードします。
#include "oneapi/dal.hpp" /* この例で必要な標準ライブラリーのヘッダー */ #include <cassert> #include <iostream>
対象のデバイスセレクターを使用して SYCL* キューを作成します。ここでは、GPU セレクターを使用します。
const auto queue = sycl::queue{ sycl::gpu_selector{} };すべての oneDAL 宣言は、
oneapi::dal名前空間にあり、簡素化のためoneapi::dalに代わって dal を使用するには、oneapi名前空間からすべての宣言をインポートします。using namespace oneapi;
CSV データソースを使用して、CSV ファイルからテーブルにデータを読み取ります。
const auto data = dal::read<dal::table>(queue, dal::csv::data_source{"data.csv"});PCA 記述子を作成し、パラメーターを構成して、CSV からロードされたデータに対してトレーニング・アルゴリズムを実行します。
const auto pca_desc = dal::pca::descriptor<float> .set_component_count(3) .set_deterministic(true); const dal::pca::train_result train_res = dal::train(queue, pca_desc, data);
学習した固有ベクトルを出力します。
const dal::table eigenvectors = train_res.get_eigenvectors(); const auto acc = dal::row_accessor<const float>{eigenvectors}; for (std::int64_t i = 0; i < eigenvectors.row_count(); i++) { /* テーブルから i 番目の行を取得し、固有ベクトルは USM へのポインターを格納します */ const dal::array<float> eigenvector = acc.pull(queue, {i, i + 1}); assert(eigenvector.get_count() == eigenvectors.get_column_count()); std::cout << i << "-th eigenvector: "; for (std::int64_t j = 0; j < eigenvector.get_count(); j++) { std::cout << eigenvector[j] << " "; } std::cout << std::endl; }トレーニングされたモデルを推論に適用してデータの次元を減らします。
const dal::pca::model model = train_res.get_model(); const dal::table data_transformed = dal::infer(queue, pca_desc, data).get_transformed_data(); assert(data_transformed.column_count() == 3);
記述子
記述子は、すべてのメタ・パラメーター、ほかのアルゴリズムへの依存関係、浮動小数点データタイプ、計算メソッド、およびタスクを含むアルゴリズムを表すオブジェクトです。記述子は次のように機能します。
操作 (英語) のディスパッチ・メカニズム。記述子のタイプを基に操作は特定のアルゴリズムの実装を実行します。
- メタ・パラメーターのアグリゲーター。コンパイル時または実行時にメタ・パラメーターを設定するインターフェイスを提供します。
- アルゴリズムの状態を保存するオブジェクト。一般に、記述子は状態を持つオブジェクトで、操作が適用された後に状態が変化します。
それぞれの oneDAL アルゴリズムには、対応する記述子が定義される専用の名前空間があります (詳細は、名前空間 (英語) を参照)。記述子は以下を定義します。
テンプレート・パラメーター。記述子には任意の数のテンプレート・パラメーターを含めることができますが、少なくとも 3 つをサポートする必要があります。
プロパティー。プロパティーは、対応するゲッターとセッターメソッドを使用してアクセスできる実行時のパラメーターです。
次のサンプルコードは、抽象化アルゴリズムの記述子定義の一般的な構造を示します。特定のアルゴリズムを定義するには、次の文字列を置き換えます。
%ALGORITHM%は、アルゴリズムの名称と名前空間です。アルゴリズムに関連するすべてのクラスと構造は、名前空間で定義されます。%PROPERTY_NAME%と%PROPERTY_TYPE%は、アルゴリズムのプロパティーの名前とタイプです。
namespace oneapi::dal::%ALGORITHM% {
template <typename Float = default_float_t,
typename Method = method::by_default,
typename Task = task::by_default,
/* 追加のテンプレート・パラメーター */>
class descriptor {
public:
/* コンストラクター */
descriptor(const %PROPERTY_TYPE%& %PROPERTY_NAME%,
/* 追加のプロパティー */)
/* `%PROPERTY_NAME_2%` プロパティーのゲッターとセッター */
descriptor& set_%PROPERTY_NAME%(%PROPERTY_TYPE% value);
%PROPERTY_TYPE% get_%PROPERTY_NAME%() const;
/* 追加のプロパティー */
};
} // namespace oneapi::dal::%ALGORITHM%
アルゴリズムのメタ・パラメーターは、次の要件を満たすプロパティーにマップされます。
- プロパティーはゲッターメソッドとセッターメソッドで定義されます。プロパティーの値を格納するベースとなるクラスメンバーは、記述子のインターフェイスに現われることはありません。
- ゲッターはベースとなるクラスメンバー変数の値を取得します。
- セッターは、プロパティー・タイプのパラメーターを 1 つだけ受け入れ、それをベースとなるクラスメンバー変数に設定します。
- ほとんどのプロパティーはデフォルト値で事前設定されますが、事前設定されないプロパティーは設定値をコンストラクターに渡すことで初期化されます。
- セッターは記述子オブジェクトへの参照を返しますが、次に示すように呼び出しを連鎖することもできます。
auto desc = descriptor{} .set_property_name_1(value_1) .set_property_name_2(value_2) .set_property_name_3(value_3);
浮動小数点タイプ
アルゴリズムは、少なくとも 1 つの実装定義の浮動小数点タイプをサポートする必要があります。その他の浮動小数点タイプはオプションです (float、double、float16、bfloat16 など)。これらのタイプをサポートするかどうかは、oneDAL の実装に依存します。
記述子のデフォルトで使用される浮動小数点タイプは実装依存であり、最上位の名前空間内で宣言する必要があります。
namespace oneapi::dal {
using default_float_t = /* 実装定義 */;
} // namespace oneapi::dal
計算メソッド
サポートされる計算メソッドは、タグタイプを使用して %ALGORITHM%::method 名前空間で宣言されます。アルゴリズムは、少なくとも 1 つのメソッドをサポートし、次に示すようにメソッドの 1 つを参照する by_default タイプのエイリアスを宣言する必要があります。
namespace oneapi::dal::%ALGORITHM% {
namespace method {
struct x {};
struct y {};
using by_default = x;
} // namespace method
} // namespace oneapi::dal::%ALGORITHM%
計算タスク
サポートされる計算メソッドは、タグタイプを使用して %ALGORITHM%::task 名前空間で宣言されます。アルゴリズムは、少なくとも 1 つのタスクをサポートし、次に示すようにタスクの 1 つを参照する by_default タイプのエイリアスを宣言する必要があります。
アルゴリズムが classification タスクと regression回帰 タスクの両方を想定する場合、デフォルトタスクは classification になります。アルゴリズムでトレーニングと推論ステージが明確に定義されていない場合、アルゴリズムは単一のタスクのみを定義することがあります。
namespace oneapi::dal::%ALGORITHM% {
namespace task {
struct classification {};
struct regression {};
using by_default = classification;
} // namespace task
} // namespace oneapi::dal::%ALGORITHM%
法務上の注意書き
The content of this oneAPI Specification is licensed under the Creative Commons Attribution 4.0 International License (英語). Unless stated otherwise, the sample code examples in this document are released to you under the MIT license (英語).
This specification is a continuation of Intel’s decades-long history of working with standards groups and industry/academia initiatives such as The Khronos Group*, to create and define specifications in an open and fair process to achieve interoperability and interchangeability. oneAPI is intended to be an open specification and we encourage you to help us make it better. Your feedback is optional, but to enable Intel to incorporate any feedback you may provide to this specification, and to further upstream your feedback to other standards bodies, including The Khronos Group SYCL* specification, please submit your feedback under the terms and conditions below. Any contribution of your feedback to the oneAPI Specification does not prohibit you from also contributing your feedback directly to other standard bodies, including The Khronos Group under their respective submission policies.
By opening an issue, providing feedback, or otherwise contributing to the specification, you agree that Intel will be free to use, disclose, reproduce, modify, license, or otherwise distribute your feedback at its sole discretion without any obligations or restrictions of any kind, including without limitation, intellectual property rights or licensing obligations.
This document contains information on products, services and/or processes in development. All information provided here is subject to change without notice.
© Intel Corporation. Intel、インテル、Intel ロゴ、その他のインテルの名称やロゴは、Intel Corporation またはその子会社の商標です。
* その他の社名、製品名などは、一般に各社の表示、商標または登録商標です。
