メインコンテンツまでスキップ

MPK契約

このドキュメントは、モデルアーカイブの取り込みとMPK契約の解析に関する正式な契約を定義します。

適用範囲​

この契約は、以下のものに適用されます。

  • src/model/ModelPack.cpp
  • src/model/ModelArchiveLoader.cpp
  • src/model/internal/ModelArchiveLoader.h
  • src/pipeline/internal/sima/MpkContract.cpp
  • src/pipeline/internal/sima/static_contract/MpkDecoder.cpp

許容されるアーカイブ形式​

許容されるパッケージ拡張子：小文字の.tar.gzのみ。.mpk、.tgz、.tar、および単独の.gzは、tarの検査前に拒否されます。

アーカイブの要件：

  • アーカイブはtarストリームとして読み取り可能である必要があります。
  • アーカイブのサイズは、ローダーで設定されたmax_archive_bytes以下である必要があります。
  • エントリの数は、ローダーで設定されたmax_entries以下である必要があります。
  • エントリのペイロードサイズは、ローダーで設定されたmax_entry_bytes以下である必要があります。

許容されるレイアウト​

抽出には、通常のファイルのみが許可されます。ディレクトリエントリは許可されますが、無視されます。

抽出可能なファイルクラス：

  • JSON設定ファイル（*.json）-> etc/の下に抽出されます。
  • 共有オブジェクト（*.so）-> lib/の下に抽出されます。
  • ELFバイナリ（*.elf）-> share/の下に抽出されます。

必要なパッケージコンテンツ：

  • MPK推論契約（mpk.jsonまたは*_mpk.json）
  • ランタイムに必要なローダー側のステージ/設定JSON
  • 少なくとも1つのモデルバイナリアーティファクト（*.elfまたは*.so）

MPK マニフェストの読み込み​

モデルの読み込み、準備済みランタイムの構築、PCIe ホストは、MpkDecoder::load を通じて mpk.json を読み込みます。マニフェストを一度だけ読み込み、そのバイト列から意味的な MpkContract を構築し、各ステージの実行ファイルをパッケージ内で解決します。MLA の実行ファイルは share/、lib/、次にパッケージのルートから、A65 モジュールは lib/、パッケージのルート、次に share/ から解決します。実行の受け入れ判定と PCIe ホストは、実行ファイルの ELF と GraphExecutor の根拠を使って同じバイト列をデコードするため、プランと契約は同じバイト列から作られます。

抽出の安全規則​

抽出は、エラーが発生した場合に安全に停止するように設計されている必要があります。

拒否されるパス形式：

  • 絶対パス（例：/etc/passwd）
  • トラバーサルセグメント（..）
  • Windowsドライブプレフィックス（C:）
  • 混合セパレータートラバーサル形式（..\\、..//）
  • 無効なUTF-8パスバイト
  • Unicodeスラッシュ/バックスラッシュの紛らわしい文字（例：U+FF0F、U+2215、U+FF3C）
  • トラバーサルに似たパスで使用されるUnicodeドットの紛らわしい文字（例：U+FF0E、U+2024、U+FE52）

拒否されるエントリタイプ：

  • シンボリックリンクエントリ
  • ハードリンクエントリ
  • デバイスエントリ
  • FIFOエントリ

抽出の動作：

  • アーカイブパスをファイルシステムの出力パスに直接書き込まないでください。
  • まず、アーカイブエントリパスを正規化および検証します。
  • 承認されたエントリをコンテンツストリームとして制御された一時ルートに抽出します。
  • 抽出ルート外への書き込みは許可しないでください。
  • 正規化されたtarパスが重複している場合、invalid_archiveとして拒否されます。
  • tarヘッダー/チェックサムの破損は、invalid_archiveとして拒否されます。

JSONとシーケンスの検証​

pipeline_sequence.jsonは、以下を満たす必要があります。

  • 空ではないpipelines配列を持つJSONオブジェクト。
  • 最初のパイプラインオブジェクトには、空ではないsequence配列が含まれている必要があります。
  • 各ステージエントリには、以下が含まれている必要があります。
    • sequence_id（整数）
    • name（空でない文字列）
    • pluginId（空でない文字列）
    • configPath（空でない文字列）
    • processor（空でない文字列）
    • kernel（空でない文字列）
  • ステージ名が重複している場合は拒否されます。
  • JSONキーが重複している場合は拒否されます。
  • JSONのネストが、ローダーのmax_json_depthよりも深い場合は拒否されます。
  • サポートされていないkernelの値は拒否されます。
  • input内のステージの依存関係は、次のいずれかのみを参照する必要があります。
    • decoder、または
    • 安定した順序で並べられた、それより前のステージ名。

エラー分類​

すべてのモデルアーカイブまたはMPK契約の取り込みエラーは、以下のいずれかのクラスにマッピングされる必要があります。

  • invalid_archive
  • path_traversal
  • schema_error
  • unsupported_version
  • size_limit_exceeded

公開されるエラーメッセージには、分類の決定性を検証するために、タクソノミキーを含める必要があります。

決定性の要件​

  • 繰り返し実行された場合でも、シーケンスの順序は決定的に一貫している必要があります。
  • tests/assets/mpk の下のフィクスチャアーカイブは、ビット単位で完全に再現可能である必要があります。
  • test-assets/model-archive/fixtures_manifest.json の下の生成されたフィクスチャマニフェストのチェックサムは、ビルドツリーのセキュリティフィクスチャの信頼できる情報源です。

テストマッピングの要件​

すべてのネガティブなモデルアーカイブ/MPK契約テストは、上記のタクソノミキーのいずれかを検証する必要があります。