モデル
Model は、コンパイルされたモデルアーカイブを読み込み、Neat が実行できるルートを公開します。
すべての前処理、推論、および後処理の段階を手動で設定するこ となく、モデルを意識した実行を行いたい場合は、Model を使用してください。まず、その仕様を確認してから実行してください。不可解なテンソルは存在しません。
Model は、あなたにどのようなメリットをもたらしますか？
input_specs()とoutput_specs()は、モデルが期待するテンソルの形式と、モデルが出力するテンソルの形式を示します。metadata()、info()、および Python のsummary()を使用すると、読み込まれたモデルを調べることができます。run(...)は、1回の直接推論を実行します。build(...)は、プッシュ/プル実行に使用できる再利用可能なモデルランナーを作成します。graph()は、モデルのルートを再利用可能なGraphの一部として返します。preprocess()、inference()、およびpostprocess()は、高度な構成のためのルート段階を明らかにします。
参考文献：
モデルアーカイブを読み込む
このページの例では、model_path が Model Compiler から生成されたコンパイル済みのモデルアーカイブを指し、通常は Neat を実行するマシンにコピーされた .tar.gz であると想定しています。 まずはデフォルトのオプションを使用し、契約または入力ソースで必要な場合にのみ、ModelOptions を追加してください。
const std::string model_path = "resnet_50_model.tar.gz";
simaai::neat::Model model(model_path);
const auto info = model.info();
const auto inputs = model.input_specs();
const auto outputs = model.output_specs();
この検査ステップで予想外の結果になった場合は、そこで作業を停止してください。より大規模なアプリケーションを構築する前に、モデルのパス、アーティファクト、またはコントラクトを修正してください。
モデルの実行パスを選択してください。
職務に合った方法を選択してください。スモークテストは小規模に保ち、グラフレベルの問題にはグラフレベルの仕組みを使用するようにしてください。
| 必要です | 使用する | 返却 |
|---|---|---|
| モデルへの入力を1回実行する | model.run(...) | テンソルを入力として使用する場合はTensorListを、サンプルを入力として使用する場合はSampleを使用します。 |
| 複数の入力に対して、モデルのルートを再利用する | model.build(...) とモデル実行プログラム | モデルのルート周辺で、押し引き操作を行う |
| モデルの実行時間のみを計測します。 | model.benchmark(...)、または測定されたモデル実行環境 | BenchmarkReportまたはMeasureReport |
| モデルをアプリのワークフローに組み込む | graph.add(model) | Graph ステージ |
| コンポジションのために、ルートの境界を明確にする。 | model.graph(route_options) | 再利用可能なGraphの断片 |
| モデルの特定の段階をデバッグする | model.fragment(ModelStage::...) | ステージ固有のGraphフラグメント |
確実性を高めるために、モデルを直接呼び出す方法を使用してください。モデルがアプリケーションの一部になった場合は、Graphを使用しま す。具体的には、名前付き入力、ソースノード、ブランチ、結合、レンダリング、ビデオ出力、メタデータ出力、または複数のモデルの場合です。
モデルのオプションを選択してください。
まず、デフォルトのModelOptionsから始めます。モデルの契約または入力ソースで必要な場合にのみ、オプションを追加してください。
| 目標 | 利用可能なオプション | 備考 |
|---|---|---|
| デコードされた画像を送信 | preprocess.kind、preprocess.preset、および、リサイズ、カラー、レイアウト、正規化、量子化、またはテッセレーションなどの特定のプリプロセスフィールド。 | アプリがピクセルデータを送信する場合にこれを使用し、Neat がそれらをモデル契約に適合するように調整します。 |
| モデルの公開入力に一致するテンソルを渡す | 前処理オプションを未設定にします。 | リサイズ・正規化済みのFP32入力にも必要なCast/Quant/Tessアダプターを維持します。 |
| 検出結果を解析する。 | decode_type, decode_type_option, score_threshold, nms_iou_threshold, top_k, num_classes | 検出モデルには、明確なデコード意図が必要です。 |
| 抽出した モデルファイルを保管し、必要に応じて確認できるようにします。 | cleanup_extracted_model_data = false | デバッグ時に役立ちます。通常の使用時には、デフォルト設定のままにしておいてください。 |
| 1つのプロセスで複数のモデルのルートを実行する | name_suffixと、グラフ要素名のプレフィックス／サフィックス | 生成された名前と診断結果を読みやすく表示します。 |
| モデルの経路を途中で停止する | inference_terminal | 高度なルーティングデバッグパスです。初回実行時のコードには使用しないでください。 |
| 実行の配置や内部キューを調整します。 | processcvu, processmla, advanced_execution | 高度な設定。調整を行う前に、デフォルトのパスを測定してください。 |
検出機能を備えた画像入力
モデルが画像の前処理を必要とし、YOLO形式の検出結果を出力する場合に、このパターンを使用してください。
simaai::neat::Model::Options options;
options.preprocess.kind = simaai::neat::InputKind::Image;
options.preprocess.preset = simaai::neat::NormalizePreset::COCO_YOLO;
options.decode_type = simaai::neat::BoxDecodeType::YoloV8;
options.score_threshold = 0.25f;
options.nms_iou_threshold = 0.45f;
options.top_k = 100;
simaai::neat::Model model(model_path, options);
設定は簡潔に：必要な契約内容を変更しない限り、デフォルト値や非推奨のフィールドを設定しないでください。テンソルまたは画像のメタデータにすでにソース形式の情報が含まれている場合は、ページでその理由が説明されていない限り、同じ情報を繰り返さないようにしてください。
識別・解析のためのフィールドガイド
ルートが、生の推論テンソルではなく、デコードされたバウンディングボックス、ポーズ結果、またはセグメンテーション結果を返すようにする場合、検出デコードオプションを設定します。生のモデル出力を取得したい場合は、フィールドを未設定のままにします。
| フィールド | 使用する際は | デフォルトの意味 |
|---|---|---|
decode_type | 検出モデルに BoxDecode ステージをアタッチするには、Neat が必要です。 | Unspecified；検出された意図はデコードされませんでした。 |
decode_type_option | 検出ヘッドのテンソル順序には、特定のバリアントが必要です。 | Auto。モデル、契約、およびルートプランナーに判断を任せましょう。 |
score_threshold | デコード処理中に、信頼度の低い候補を排除したいと考えています。 | 0：後で絞り込む前に、候補者を保持しておく。 |
nms_iou_threshold | デコード処理では、非最大値抑制を適用する必要があります。 | 0； モデルにパッケージされた値を保持します。パッケージされた値がない場合、YOLO26はNMSをスキップし、その他のデコーダーは重なりのあるボックスをすべて抑制します。 |
top_k | 1回の出力あたりの検出件数に上限を設けたいのですね。 | 0；上位K件の制限なし。 |
num_classes | クラスヘッドの深さは、例えば単一クラスのYOLO分割ヘッドのように、確実に推測することはできません。 | 0。MPKメタデータまたは従来の推論を使用してください。 |
ほとんどのYOLOスタイルのモデルでは、まずdecode_type、score_threshold、nms_iou_threshold、およびtop_kから始めます。モデルの構造に調整が必要な場合にのみ、num_classesを追加します。テンソルの順序について、特定のセレクターが必要であることがわかっている場合を除き、decode_type_optionをAutoに設定したままにします。
simaai::neat::Model::Options options;
options.decode_type = simaai::neat::BoxDecodeType::YoloV8;
options.score_threshold = 0.25f;
options.nms_iou_threshold = 0.45f;
options.top_k = 100;
options.num_classes = 1; // Set only when the model contract needs the class count.
simaai::neat::Model model(model_path, options);
新しい例では、boxdecode_original_widthまたはboxdecode_original_heightを使用しないでください。座標の反転には、前処理メタデータが使用されます。画像のサイズをハードコーディングする代わりに、そのメタデータを保持してください。
生のテンソル入力
model.input_specs()に一致するテンソルを渡す場合はデフォルトを使います。NeatはMPKに必要なテンソルアダプターを維持します。
simaai::neat::Model model(model_path);
従来のpreprocess.enable = Off設定は、MLAのみの実行を選択したり、MPKに必要なCast/Quant/Tessアダプターを削除したりしません。空でないpreprocess.transformsリストはOffより優先されます。
フィールドガイドの準備
ModelOptions.preprocess どのような種類の入力を提供するか、また Neat 推論前に適応する場合があります。
| 必要です | フィールド |
|---|---|
| 画像またはテンソルを入力として選択してください。 | preprocess.kind |
| 従来の前処理制御（MPKに必要なアダプターは維持） | preprocess.enable |
| 動的な画像の入力を制限する | preprocess.input_max_width, preprocess.input_max_height, preprocess.input_max_depth |
| サイズ変更、トリミング、またはレターボックス表示 | preprocess.resize |
| RGB、BGR、NV12、I420、またはグ レースケールに変換します。 | preprocess.color_convert |
| HWC、CHW、またはその他の軸の順序を変換します。 | preprocess.layout_convert |
| 平均値/標準偏差による正規化を適用します。 | preprocess.normalizeまたはpreprocess.preset |
| 推論前に量子化する | preprocess.quantize |
| 推論の前にテッセレーションを実行する | preprocess.tessellate |
| 順序付きの変換リストで上書きする | preprocess.transforms |
実際に送信する入力内容を最も簡潔に記述するオプションセットを設定します。仕様は契約書であり、決定されたプリプロセス計画は領収書です。
仕様を確認し、直接実行します。
Graphを作成する前に、モデル契約を確認してください。仕様書には、何を割り当て、送信し、デコードするかについて記載されています。
simaai::neat::Model model(model_path, options);
const auto inputs = model.input_specs();
const auto outputs = model.output_specs();
const auto metadata = model.metadata();
const auto info = model.info();
for (const auto& input : inputs) {
const auto& shape = input.shape;
}
for (const auto& output : outputs) {
const auto& shape = output.shape;
}
simaai::neat::Tensor input = simaai::neat::Tensor::from_cv_mat(
frame,
simaai::neat::ImageSpec::PixelFormat::BGR,
simaai::neat::TensorMemory::CPU);
simaai::neat::TensorList result = model.run(
simaai::neat::TensorList{input},
/*timeout_ms=*/2000);
Pythonでは、入力のリストまたはタプルを渡します。model.run([tensor])は「1つのモデル入力」を意味します。バッチ次元は追加されません。
model.run(...)は、毎回再構築するのではなく、一度だけ実行する形式です。最初の呼び出しで、内部ランナーを遅延的に構築し、キャッシュします。以降の呼び出しでは、そのランナーを再利用し、データをプッシュ/プルします。ルーティングオプション、ランタイムオプション、測定、クローズ/ドレイン制御、またはプロデューサー/コンシューマーループが必要な場合は、明示的なmodel.build(...)を使用してください。
OpenCVサポートを使用してC++でビルドする場合、model.run(std::vector<cv::Mat>{frame}, timeout_ms)も公開されます。例でピクセル形式またはメモリの所有権を明示する必要がある場合は、明示的なTensor::from_cv_mat(...)パスを使用してください。
複数の入力とバッチを組み合わせて作業する
モデルは、複数の入力ポート、コンパイルされたバッチサイズ、またはその両方を持ち得ます。これらの概念を混同しないでください。
- 複数の入力とは、モデルへの入力ごとに1つのテンソルを意味します。想定される順序と形式については、
model.input_specs()を参照してください。 - バッチとは、モデルが一度の推論で複数の論理的なサンプルを処理するようにコンパイルされたことを意味します。
model.compiled_batch_size()を確認してください。 - Pythonの入力リストでは、バッチ次元ではなく、入力リストを選択します。
model.run([tensor])は、入力の1つです。これは、tensorをバッチサイズ1に変換するものではありません。
const int batch = model.compiled_batch_size();
const auto specs = model.input_specs();
// Two-input model: pass one tensor per ingress.
simaai::neat::TensorList inputs{left_tensor, right_tensor};
simaai::neat::TensorList outputs = model.run(inputs, /*timeout_ms=*/2000);
バッチ処理を行うモデルが形状 [N, ...] を期待する場合、入力仕様に従ってテンソルの形状に N を配置します。モデルに N 入力ポートがある場合を除き、N 個別の Python リスト項目を渡さないでください。
ルート計画を確認してください。
前処理、トポロジーの出力、またはルーティングの選択で予期せぬ結果が生じた場合は、推測するのではなく、実際にルーティングを確認してください。
| 質問 | 点検する |
|---|---|
| このモデルは、どのようなテンソルの形状とデータ型を公開しますか？ | input_specs()とoutput_specs() |
| コンパイルされたアーティファクトは、どのような情報を宣言していましたか？ | info()とmetadata() |
| 前処理では、どのような入力が想定されていますか？ | preprocess_requirements() |
| Neat は、どのプリプロセスパスを使用してコンパイルされましたか？ | resolved_preprocess_plan() / Python preprocess_plan() |
| どのバッチサイズでコンパイルされましたか？ | compiled_batch_size() |
| どの出力形式をデコードすればよいでしょうか？ | 出力仕様とinfo().output_topology。 |
const auto requirements = model.preprocess_requirements();
const auto plan = model.resolved_preprocess_plan();
std::cout << "preprocess: " << plan.to_debug_string() << "\n";
決定された計画は、監査ログです。具体的には、リクエストされたオプション、有効なオプション、グラフファミリー、イングレス契約、MLA契約、および警告が含まれます。
モデルのルートのスナップショットを読み込んでください。
モデルアーカイブを手動で読み込むことなく、コンパクトなルートのスナップショッ トが必要な場合は、info() を使用してください。Pythonでは、テキストをすばやく表示するための summary() も提供されています。C++では、構造化された info() の結果を使用します。
| 質問 | 検査対象のinfo()フィールド |
|---|---|
| 私が読み込んだアーティファクトはどれですか？ | model_name, mpk_json_path |
| どの種類の変換アダプターが必要ですか？ | needs |
| どの種類の変換アダプターが利用可能ですか？ | capabilities |
| そのルートには、前処理または後処理が含まれていましたか？ | selection.include_preprocess_stage, selection.include_postprocess_stage |
| これは推論のみを行う経路ですか？ | selection.infer_only |
| どの種類の前処理グラフまたは後処理が選択されましたか？ | selection.preprocess_graph, selection.selected_post_kind |
| 物理的な出力と論理的な出力はそれぞれいくつありますか？ | output_topology.physical_outputs, logical_outputs, packed_outputs |
| ルートプランナーはどのような警告を表示しましたか？ | warnings |
const auto info = model.info();
std::cout << "model=" << info.model_name << "\n";
std::cout << "physical_outputs=" << info.output_topology.physical_outputs
<< " logical_outputs=" << info.output_topology.logical_outputs << "\n";
for (const auto& warning : info.warnings) {
std::cerr << warning << "\n";
}
経路に関する警告を、最も重要な証拠として扱う。経路プランナーが何か異常なことを示している場合は、それを無視したり、都合の良いように解釈したりしないで ください。まず、契約内容または設定を見直して修正してください。
モデルが実行する内容を確認する
execution_plan() を使うと、モデルが実行するノード、各ノードが実行される場所、ノード間を流れるテンソルを確認できます。Model::execution_plan(...) は build(...) と同じ引数を受け取り、フレームを実行せずにモデルをビルドし、プランを読み取った後に閉じます。そのため、デバイスが必要です。
const simaai::neat::ExecutionPlan plan = model.execution_plan();
std::cout << plan.to_json() << "\n";
JSON には、モデルのグラフノードがパイプライン順に並び、連続する 2 つのノードの間に 1 つのエッジがあります。
| フィールド | 意味 |
|---|---|
model | モデル名、batch（MLA の 1 回の実行あたりのフレーム数）、memory（処理中の 1 フレームあたりのデバイスメモリ） |
nodes[].kind | ノードの種類。Input、Preproc、Quant、ModelFragment、Dequant、SimaBoxDecode、Output など |
nodes[].runs_on | ノードが実行される場所：A65（Arm コア）、EV74（ビジョンプロセッサ）、または MLA |
nodes[].kernel | EV74 または A65 のノードが実行するカーネル |
nodes[].settings | 解決済みの Preproc と SimaBoxDecode の設定。名前は PreprocOptions と BoxDecodeOptions と同じです |
edges[].tensors | あるノードから次のノードへのテンソル：バッチ先頭の shape、dtype、量子化テンソルの quant（scale、zero_point） |
SimaBoxDecode の設定には、モデルまたはオプションで設定した場合にのみ、しきい値と top_k が表示されます。設定していない場合は、デコーダーの既定値が使われます。スキーマは schemas/execution_plan_v1.schema.json です。
グラフ内のモデルを使用する
一般的なパスの場合、公開されている入力と出力の間にモデルを直接追加します。
simaai::neat::Graph graph("classifier");
graph.add(simaai::neat::nodes::Input("image"));
graph.add(model);
graph.add(simaai::neat::nodes::Output("classes"));
モデルの画像入力に直接接続されたデフォルトの公開 Input は、その入力の画像の解釈と形式を継承します。ソースの形式を明示的に設定することもできます。その場合、グラフがモデルのコントラクトと照合します。ソースのメモリ、寸法、タイムスタンプ、キュー設定は変わりません。接続先が複数ある場合や曖昧な場合は、入力オプションを明示してください。
この解釈は Graph の入力境界に適用されます。モデルを直接呼び出す場合は、引き続きモデルが宣言する画像またはテンソルのコントラクトを満たす入力が必要です。
再利用可能なコード片や、明確なルーティング境界が必要な場合は、model.graph(...) を使用してください。
ルーティングオプションは、そのコード片がどのようにインターフェースを公開するかを制御します。
| 必要です | 経路オプション |
|---|---|
| 返されたグラフに、公開入力ノードを追加します。 | include_input |
| 返されたグラフに、公開出力ノードを追加します。 | include_output |
| 個別の物理的な出力ポートを公開する | expose_all_outputs |
| 生成された要素名の曖昧さを解消する。 | name_suffix |
| 特定のアップストリーム要素名から接続します。 | upstream_name |
| このルートに対して、高度な実行設定を上書きします。 | advanced_execution |
simaai::neat::Model::RouteOptions route;
route.include_input = true;
route.include_output = true;
route.name_suffix = "_detector";
simaai::neat::Graph model_fragment = model.graph(route);
ルートの境界は一種の契約です。フラグメントが外部に公開する入力または出力を持つようにしたい場合は、それらを追加してください。モデルがより大きなグラフ内の単一の段階にすぎない場合は、それらを省略してください。
高度な構成には、ステージフラグメントを使用してください。
ほとんどのアプリでは、モデルのルート全体を追加する必要があります。ルートを意図的に構成またはデバッグする場合にのみ、ステージフラグメントを使用してください。
simaai::neat::Graph preprocess =
model.fragment(simaai::neat::Model::Stage::Preprocess);
simaai::neat::Graph inference =
model.fragment(simaai::neat::Model::Stage::Inference);
simaai::neat::Graph postprocess =
model.fragment(simaai::neat::Model::Stage::Postprocess);
高度なヘルパー関数は、診断や意図的なコードの構成に使用します。初期実行時に使用するコードには含めないでください。
| アシスタント | 言語 | 使用する際は |
|---|---|---|
backend_fragment(stage) | C++とPython | ルートのデバッグ中に、あるモデルのステージのバックエンドフラグメントを調べてください。 |
input_appsrc_options(tensor_mode) | C++とPython | 単一入力モデルでは、入力境界に対して正確に導出された InputOptions Neat が必要です。 |
input_appsrc_options_list(tensor_mode) | C++ | 複数の入力を持つモデルには、各入力ポートごとに InputOptions が必要です。 |
find_config_path_by_plugin(plugin_id) | C++とPython | 証拠を収集する際に、特定のプラグインの構成ファイルが必要になります。 |
find_config_path_by_processor(processor) | C++とPython | MLA、CVU、またはAPUなどのプロセッサを使用するには、設定ファイルが必要です。 |
infer_output_name() | C++とPython | 診断のために、標準的な推論段階の出力要素名が必要です。 |
ヘルパーがバックエンドの名前や抽出されたファイルを公開した場合、その結果をアプリケーションの制御フローではなく、証拠として扱うものとします。公開されているModel、Graph、Run、Input、およびOutput APIは、通常のアプリケーションパスを使用する必要があります。
ベースラインを確立した後での み、モデルの実行を調整してください。
ほとんどのモデルは、まずデフォルトの実行設定で実行する必要があります。適切な基準値が得られたら、高度な実行フィールドを使用して、一度に1つの変更をテストします。1つの設定を変更し、測定を行い、デフォルトの設定を基準として保持します。
advanced_execution 新しいドキュメントやサンプルで推奨されるオプションの形式は、各フィールドが意図を直接示すためです。未設定のフィールドは無視されます。ルートレベルのオプションは、そのルートに対してモデルレベルのオプションを上書きします。
| 必要です | フィールド | 備考 |
|---|---|---|
| モデルによって管理される前処理が実行される場所を選択してください。 | advanced_execution.preprocess_target | "AUTO"、"A65"、または"EV74"などのターゲットトークンは、配置を証明する場合にのみ使用してください。 |
| モデルによって管理される後処理が実行される場所を選択してください。 | advanced_execution.postprocess_target | 複数のターゲットで実行できる後処理段階にこれを使用してください。 |
| 非同期で前処理を実行できるよう にします。 | advanced_execution.preprocess_async | 機能を有効にする前と有効にした後で、遅延とスループットを測定してください。 |
| MLA推論を非同期的に実行できるようにします。 | advanced_execution.inference_async | 継続的に処理を行うストリーミング型のワークロードに役立ちます。 |
| 推論出力バッファリングを調整します。 | advanced_execution.inference_output_buffers | 測定の結果、出力バッファリングがボトルネックになっていることが判明した場合にのみ、値を増やしてください。 |
| 出力キャッシュの同期を遅延させる | advanced_execution.defer_output_cache_sync | 高度な設定です。消費者とメモリの寿命について十分に理解している場合にのみ使用してください。 |
| 内部の同時処理数を調整する | advanced_execution.internal_queue_depth | 内部に挿入されるキューと数値演算 Runner の実行容量を制限します。MLA 出力バッファの設定は上書きしません。 |
処理の重なりの制限、入力の寿命、フレームあたりの CPU 測定については、キューを無制限に増やさずにフレーム処理を重ねるを参照してください。残されている prepared_runner フィールドはソース互換性のためのもので、選択可能な実行バックエンドではありません。デフォルトのままにしてください。廃止されたモードはグラフ構築時に失敗します。
実験に最も適した、可能な限り狭い範囲で、高度な実行フィールドを設定してください。
simaai::neat::Model::RouteOptions route;
route.name_suffix = "_lane0";
route.advanced_execution.inference_async = true;
auto runner = model.build(route);
デフォルトのルートをコントロールとして維持します。1つのフィールドを変更し、測定を行い、結果をエクスポートしてから、その変更をアプリケーションに採用するかどうかを決定します。
C++では、Model::Options、Model::RouteOptions、およびGraphOptionsで、より低レベルのprocesscvu、processmla、prepared_runner、およびasync_queue_depthフィールドも公開しています。既存のC++コードを維持する場合や、特定の低レベルフィールドをデバッグする場合を除き、顧客の例ではadvanced_executionの使用を推奨します。
モデルランナーを再利用する
各入力に対してルートを再構築することを避けたい場合は、build(...) を使用してください。
auto runner = model.build();
// Convenience path: push one input and wait for its output.
simaai::neat::TensorList result = runner.run(
simaai::neat::TensorList{input},
/*timeout_ms=*/2000);
// Async path: push now, pull later.
runner.push(simaai::neat::TensorList{input});
simaai::neat::Sample sample = runner.pull(/*timeout_ms=*/2000);
runner.close_input();
runner.close();
各処理で 1 つの入力をプッシュし、その出力が完了するまで待機させる必要がある場合は、runner.run(...) を使用します。アプリケーションで処理を継続させたい場合は、push(...) / pull(...) を使用します。それ以上の入力が不要で、残りの処理を完了させたい場合は、close_input() を使用します。ランナーの処理が完了した場合は、close() を使用します。
push は入力キューに空きができるまで待機します。待機せずに送信するには、C++ では Sample または TensorList を指定して runner.try_push を使用し、Python では runner.try_push_samples / runner.try_push_tensors を使用します。RunOptions.queue_depth と overflow_policy は、ランナーを構築する前に設定してください。上限のあるキューが満杯の場合、KeepLatest は保留中の最も古いサンプルを置き換えて true を返し、Block と DropIncoming は false を返します。入力が閉じられている場合も false を返します。1 フレーム分の対になるテンソルは、1 つの TensorSet サンプルにまとめてください。置き換えによって実行中の推論が取り消されることはなく、これらの転送メソッドでペイロードのコピーが追加されることもありません。
特定のルートに特化したランナーを作成する
再利用可能なランナーが、デフォルトのルートとは異なるルートレベルの実行設定またはルート名を使用する必要がある場合は、ルート固有のランナーを使用してください。Model::build(...) は、ランナーの入力と出力の境界を自動的に設定します。
simaai::neat::Model::RouteOptions route;
route.name_suffix = "_detector";
auto runner = model.build(route);
最初の本番環境へのデプロイ前に、実際の入力が、形状、形式、またはペイロードの互換性に関して期待どおりに機能することを確認するために、ビルドの初期段階でテストを実施してください。
auto runner = model.build(simaai::neat::TensorList{input}, route);
証拠や早期の不具合検出のために、毎回同じ条件でビルドを行うのではなく、必要に応じて特定の条件でビルドを行ってください。デフォルトのビルドで既に要件が満たされている場合は、サンプルをより簡潔に保ってください。
画像入力では、シードは現在の形状とピクセル形式を指定し、preprocess.input_max_width、input_max_height、input_max_depth を置き換えません。たとえば、容量を 1920×1920 と指定して 640×640 のシードを使った場合、同じランナーで後続の 800×800 や 1920×1080 のフレームを受け入れます。容量を超えるフレームは拒否されます。上限を省略すると、シードなしのビルドと同じ解決済み容量が維持されます。
モデルの実行を測定する
model.benchmark(...) を使用して、迅速な合成モデルのベンチマークを実施してください。これにより、input_specs() から入力が生成され、主要な レイテンシー、スループット、電力、およびボードのテレメトリが返されます。モデルやランタイムの変更を比較するために使用し、実際の運用環境におけるスループットを主張するためには使用しないでください。
simaai::neat::BenchmarkReport report = model.benchmark();
std::cout << "latency_ms=" << report.latency_ms
<< " fps=" << report.fps << "\n";
BoxDecodeルートの場合、合成入力のソース画像のジオメトリを記述してください。これにより、ベンチマークは、モデルの座標から検出結果を元の画像にマッピングできるようになります。
simaai::neat::BenchmarkOptions options;
options.num_samples = 100;
options.original_width = 1920;
options.original_height = 1080;
options.resize_mode = simaai::neat::ResizeMode::Letterbox;
simaai::neat::BenchmarkReport report = model.benchmark(options);
original_widthとoriginal_heightを組み合わせて設定します。ベンチマークは引き続き、モデルの形状を持つ合成テンソルを生成します。これらのフィールドは、BoxDecodeメタデータに必要なソースジオメトリとリサイズ変換を提供します。これらを省略すると、ベンチマークは解決された前処理とモデル入力コントラクトからジオメトリを推測します。これらの実行ごとの値は、ModelOptions内の非推奨のBoxDecodeジオメトリヒントよりも優先されます。既存のbenchmark(num_samples)の呼び出しは、同じ動作を維持します。
MLA のレイヤーごと、またはステージごとの時間も計測するには、include_mla_layer_stats または include_mla_stage_stats を設定します。結果を残すには、report.save(path) でレポートを YAML として書き出します。パスが .json で終わる場合は JSON として書き出します。両方の例はモデルをベンチマークするを参照してください。
独自の入力で測定する
検出やセグメンテーションのデコーダーのように、コストがデータに依存するモデルでは、合成入力では正しく測定できないことがあります。実際のデータで測定するには、run() に渡すテンソルをモデルの入力ごとに 1 つずつ inputs に設定します。ベンチマークは、これらをレイテンシーとスループットの両方の測定に使用します。
cv::Mat image;
cv::cvtColor(cv::imread("bus.jpg"), image, cv::COLOR_BGR2RGB); // the format input_specs() reports
simaai::neat::BenchmarkOptions options;
options.inputs = simaai::neat::TensorList{
simaai::neat::Tensor::from_cv_mat(image, simaai::neat::ImageSpec::PixelFormat::RGB,
simaai::neat::TensorMemory::EV74)};
simaai::neat::BenchmarkReport report = model.benchmark(options);
std::cout << "input=" << report.input << " fps=" << report.fps << "\n"; // input=provided
入力の数、形状、データ型がモデルと一致しない場合、benchmark() は開始前にエラーコード misconfig.input_shape の NeatError をスローします。ルートが変換できない色フォーマットは、run() と同様にパイプラインの構築時にエラーになります。画像を前処理するルートでは、画像のサイズは任意です。色フォーマットは input_specs() が示すものを使用してください。
実行時間
ベンチマークは、入力を 1 つずつ実行してレイテンシーを測定し、その後、別のスループット測定パスを実行します。各パスは、少なくとも num_samples 個の入力を測定し、かつ min_duration_ms（デフォルトは 10 秒）が経過するまで続きます。そのため、両方のパスは同じ規則で停止し、スループット測定パスの電力と温度の値は短時間のバーストではなく、複数のテレメトリサンプルにわたって取得されます。latency_ms はレイテンシー測定パスの平均レイテンシーで、latency_p50_ms、latency_p95_ms、latency_p99_ms はそのパーセンタイルです。throughput_samples と throughput_duration_ms は、スループット測定パスで測定した内容を示します。簡単なスモークテストでは、min_duration_ms を 0 に設定すると、各パスが num_samples 個の入力の後で停止します。
simaai::neat::BenchmarkOptions options;
options.min_duration_ms = 0;
simaai::neat::BenchmarkReport report = model.benchmark(options);
電力とボードのテレメトリ
電力とボードのテレメトリは、Neat インストーラーがボード上にセットアップする DevKit テレメトリデーモン Sentinel から取得します。ベンチマークはスループット測定の前後で TelemetryMonitor を使って記録します。測定開始後から、必要な出力がすべて完了して測定が停止するまでのサンプルを選択します。準備、モニターワーカーの join、最後の Sentinel 読み取りによって、測定対象ワークロードの時間は延長されません。サンプルのタイムスタンプが無効な場合や時計の不連続を検出した場合は、無関係な区間を選ぶのではなく、ベンチマークのテレメトリを利用不可にします。report.telemetry に概要が含まれます。
| フィールド | 意味 |
|---|---|
avg_power_watts, peak_power_watts | スループット測定パス中の SoM 電力の推定平均値と推定最大値です。 |
energy_joules | num_samples 個の入力の処理に必要なエネルギーです。平均電力に、測定したスループットで num_samples 個の入力を処理するのに必要な時間を掛けた値です。パスが長くなっても増加しません。 |
telemetry.power_mla_watts, telemetry.power_rails_watts | MLA レールの電力と、ボードが報告するすべてのレールの電力です。MLA レールのないボードでは、samples == 0 として報告されます。 |
telemetry.die_temperatures_c, telemetry.die_temperature_max_c | MLA、APU、CVU、TOP の各サイトにあるオンダイセンサーの温度と、各サンプルにおけるそれらの最高温度です。 |
telemetry.board_temperatures_c | SoM の表面側と裏面側のセンサーの温度です。 |
telemetry.cpu_usage_pct | CPU 使用率です。各サンプルは直前の区間の平均であるため、maximum は最も負荷の高い区間を示します。 |
telemetry.cpu_cores_usage_pct | 各 CPU コアの使用率です（コア順）。全コアの平均である cpu_usage_pct が低いままでも、1 つのコアの高負荷がここに表れます。 |
telemetry.mla_memory_mib | MLA が保持するメモリ（MiB 単位）です。MLA のメモリプールのバッファと、MLA だけ が使う共有バッファを含みます。モデルはロード時にこれを割り当てるため、他に何も実行していなければ、この値がモデルの MLA メモリです。 |
telemetry.ev74_memory_mib | EV74 が保持するメモリ（MiB 単位）です。たとえば、EV74 が MLA 向けに前処理する入力フレームが該当します。EV74 と MLA の両方が使う共有バッファは mla_memory_mib ではなくこちらに数えるため、2 つを足すとモデルのアクセラレーターメモリになります。ビデオデコーダーやカメラ ISP が生成したフレームはどちらにも含まれません。 |
telemetry.linux_memory_used_mib | ボード全体が使用しているメモリ（Linux の MemTotal - MemAvailable、MiB 単位）です。すべてのプロセスと EV74 のバッファを含むため、上の 2 つに加算しないでください。 |
各メトリクスは samples、mean、minimum、maximum、last を報告し、samples == 0 はボードがそのメトリクスを報告しなかったことを意味します。報告された 0 もサンプルとして数えられます。モデルが読み込まれていない場合、mla_memory_mib と ev74_memory_mib は samples > 0 のまま 0 MiB を示します。Sentinel は 2 秒ごとにサンプリングするため、10 秒のパスでは約 5 個のサンプルが得られます。すべての値はボード全体のもので、実行中の他のプロセスも含みます。
Sentinel が実行されていない場合、またはパスが短すぎてサンプルを収集できない場合でも、ベンチマークはレイテンシーと FPS を返します。電力フィールドはゼロのままになり、telemetry.status にその理由が示され（それ以外の場合は "ok"）、出力される概要には Power: unavailable (<reason>) と表示されます。
独自のループを測定する
入力ループを制御し、そのループを測定したい場合は、ランナー測定を使用してください。
auto runner = model.build();
auto scope = runner.start_measurement();
for (const auto& input : inputs) {
(void)runner.run(simaai::neat::TensorList{input}, /*timeout_ms=*/2000);
}
simaai::neat::MeasureReport report = scope.stop();
runner.close();
一度限りのスモークテストと、事前に起動させて再利用するテスト環境を比較しないでください。それらは異なる目的のために行われます。
ボードのテレメトリを記録する
TelemetryMonitor を使用すると、独自の推論ループなど、任意のウィンドウにわたって電力、温度、CPU 使用率、メモリを記録できます。これらは Sentinel から読み取られ、report.telemetry と同じ Telemetry サマリーとして返されます。
simaai::neat::TelemetryMonitor monitor;
monitor.start();
for (const auto& input : inputs) {
(void)runner.run(simaai::neat::TensorList{input}, /*timeout_ms=*/2000);
}
simaai::neat::Telemetry telemetry = monitor.stop();
std::cout << telemetry; // YAML
telemetry.save("telemetry.json"); // .json writes JSON; other names write YAML
モニターは既定で /run/simaai-sentinel/api.sock を読み取ります。別のパスにマウントした Sentinel の Unix ソケットを使う場合は、C++ では TelemetryMonitor(socket_path)、Python では pyneat.TelemetryMonitor(socket_path="...") にそのパスを渡してください。この指定はそのモニターの接続先だけを選び、Model::benchmark() を変更したり Sentinel を起動したりしません。構築時にはソケットへ接続しません。
start()は新しいウィンドウを開始します。その後に Sentinel が取得したサンプルだけが集計されます。Sentinel は 2 秒ごとにサンプリングするため、それより短いウィンドウではサンプルが 1 つもない場合があり、その場合はstatusがそのことを示します。read()は、停止せずにその時点までのサマリーを返します。各測定値のlastは最新の値で、mean、minimum、maximumはその時点までのウィンドウを対象とします。stop()は最終的なサマリーを返します。再度呼び出しても同じ結果を返します。- サマリーは測定値ごとに 1 つのエントリだけを保持するため、ウィンドウがどれだけ長くてもメモリ使用量は変わりません。
- 複数のモニタは、1 つのプロセス内でも複数のプロセスにまたがっても、互いに、また
Model::benchmark()と同時に実行できます。 - すべての値はボード全体のもので、Sentinel、モニタ自体 、その他のプロセスを含みます。各電力値はサンプルごとに 1 回の 250 ms の読み取りから得られるため、読み取りの間に発生する短いスパイクは表れません。
- Sentinel が実行されていない場合、モニタは警告を 1 回出力し、
statusが Sentinel のインストール方法または起動方法を説明します。Sentinel が応答するようになると、モニタはサンプルの集計を始めます。Sentinel の問題で例外をスローすることはありません。 - Python では、
start()、read()、stop()は待機中に GIL を解放します。
出力結果を解読する
まず、出力仕様を確認してください。モデルの出力契約で、ペイロードが検出、ポーズ、またはセグメンテーション形式であると明記されている場合にのみ、デコードを実行してください。
| 契約書を出力する | 使用する |
|---|---|
| 生のテンソル | 返されたテンソルをそのまま使用するか、Pythonでto_numpy(...) / to_torch(...)を使用して変換します。 |
| 箱を詰めてテンソルとして表現する。 | C++ simaai::neat::decode_bbox(...) / Python pyneat.decode_bbox(...) |
| タイプされた記録として梱包された箱 | C++ simaai::neat::decode_bbox_tensor(...) / Python pyneat.detections.decode_bbox_tensor(...) |
| ポーズを固定 | C++ simaai::neat::decode_pose(...) / Python pyneat.decode_pose(...) |
| パッキングされたセグメンテーション | C++ simaai::neat::decode_segmentation(...) / Python pyneat.decode_segmentation(...) |
次の段階でテンソルが必要な場合は、テンソルデコードを使用します。アプリケーションコードで、x1、y1、x2、y2、score、およびclass_idを含むレコードが必要な場合は、型付きデコードを使用します。
const auto decoded = simaai::neat::decode_bbox_tensor(
outputs[0],
image_width,
image_height,
/*expected_topk=*/100,
/*strict=*/true);
for (const auto& box : decoded.boxes) {
handle_box(box.x1, box.y1, box.x2, box.y2, box.score, box.class_id);
}
デコードヘルパーは、対応する出力形式でのみ使用してください。
エラー処理
モデル駆動型のグラフは、生のGraphと同じ診断契約を使用します。
NeatError.report().error_code端末の故障時。NeatError.report().repro_note具体的な状況とヒントを提供するため。- プラグインまたはランタイムの詳細に関するエラー報告用：
NeatError.report().bus。
try {
auto result = model.run(simaai::neat::TensorList{input}, /*timeout_ms=*/2000);
} catch (const simaai::neat::NeatError& error) {
const auto& report = error.report();
std::cerr << report.error_code << "\n";
std::cerr << report.repro_note << "\n";
}
まず、misconfig.*、build.*、runtime.*、またはio.*などのerror_codeの値から始めます。構造化されたエラーメッセージが示すまで、バスログは読み込まないでください。