doca-bench

DOCA Bench（doca_bench）

例

• 「このデバイスで、この DOCA ライブラリは実際にどのような性能を発揮しますか？」 — これは対象範囲内です。doca_bench を使い、独自の マイクロベンチマークは作成しないでください。
• 「このインストール環境で、doca_bench が実行できる DOCA ライブラリはどれですか？」 — まず組み込みクエリを試してください。列挙結果が空の場合は、ベンチマークの失敗ではなく、 ライブラリがないことを意味します。

手順

以下の読み込み順に従ってください。設定／実行／デバッグについてはタスク用コンパニオンを開いてください。モードと測定の妥当性については機能用コンパニオンを開いてください。コンパニオンファイルをすべて開く必要はありません。

最初に確認する内容： これは、クロスライブラリのマイクロベンチマークハーネスである doca_bench を実行するためのツールスキルです。タスク用 コンパニオンを開き、まず ## configure で3軸の判断 （対象ライブラリ × ワークロードの形状 × 測定軸）を確認し、続いて ## run でスモークテストを先に行ってから一括実行するフローを確認してください。質問が「doca_bench で測定できる内容」、 「実行できる DOCA ライブラリ」、 または「ウォームアップや定常状態について誤った解釈をせずに、スループット／レイテンシー／操作レートの出力をどう解釈するか」に関する場合は、機能用コンパニオンを開いてください。DOCA がまだインストールされていない場合は、まず doca-setup/SKILL.md に案内してください。インストール済みのバージョンが < 2.7.0 の場合、このホストには doca_bench は含まれていません。

このスキルがうまく回答できる質問の例

このスキルが回答するために設計された doca_bench に関する質問の種類と、それぞれの具体例です。重要なのは質問の種類であり、具体例はその一例です。

• 「このデバイスで、この DOCA ライブラリは実際にどのような性能を発揮しますか？」 — 具体例：「自分の BlueField-3 での DOCA Compress のスループット」。 機能用コンパニオンの3軸構成 と、タスク用コンパニオンのスモークテストを先に行ってから一括実行するフローで回答します。 *「DOCA RDMA の送信側スループット」*にも同じ構成で回答できます。doca_bench は クロスライブラリ対応であり、単一ライブラリ専用ではありません。
• 「このインストール環境で、doca_bench が実際に実行できる DOCA ライブラリはどれですか？」 — 具体例：「粒度の細かいビルドのインストール環境で doca_sha を列挙できるか」。機能用コンパニオンで説明する組み込みクエリシステム と、タスク用コンパニオンのステップ 2 （ベンチマーク前のプローブ）で回答します。列挙結果が空の場合は、ライブラリがインストールされていないことを意味し、ベンチマークの失敗ではありません。
• 「この数値は信頼できますか。それともウォームアップを見落としましたか？」 — 具体例：「最初の1秒間の数値が定常状態の数値と異なるのはなぜか」。機能用コンパニオンの レイヤー 5 にある測定妥当性のオーバーレイと、タスク用コンパニオンで回答します（eval-loop オーバーレイでは、ウォームアップ／定常状態／外れ値を、一度きりの事実ではなく再実行のトリガーとして扱います）。
• 「ベンチマークでスループットがゼロと報告される／開始時にハングする／公開ドキュメントと一致しない」 — 具体例：「doca_caps ではデバイスが AES-GCM をサポートしていると示されるのに、doca_bench では操作数がゼロと表示される」。機能用コンパニオンの階層化されたエラー分類 （設定構文 → デバイスのバインド → ライブラリの前提条件 → ワークロードの前提条件 → 測定の妥当性 → バージョン → 横断的要因）と、タスク用コンパニオンで回答します。
• 「後で回帰テストに使えるベースラインを取得するには、どうすればよいですか？」 — 具体例：「ファームウェア更新前に、この BlueField と DOCA バージョンでの解凍スループットを記録する」。 タスク用コンパニオンにある CSV 出力とバージョンオーバーレイのルールで回答します（数値とともに、コマンドライン、バージョン、デバイス、実環境の設定を記録してください。この4つの組み合わせを記録せずに数値だけを引用すると、バージョンをまたいだ回帰調査で問題になります）。
• 「doca_bench がライブラリ X の結果を何も返しません。これは何を意味しますか？」 — 具体例：「DOCA SHA の出力が空」。 タスク用コンパニオンと機能用コンパニオンの、空の出力の解釈ルールで回答します。 まず doca-caps/SKILL.md に案内し、デバイスごと・ライブラリごとの大まかな機能の実態を確認してから、その機能が存在すると確認できた時点でベンチマークに戻ります。

対象読者

このスキルは、ユーザーが実際にインストールしている環境とデバイスで DOCA ライブラリのパフォーマンスを測定するために、再現可能でベンダーがサポートする方法を必要とする外部オペレーター、開発者、AI エージェントを対象としています。 具体的には、次のような人が該当します。

• アプリケーション設計を確定する前に、DOCA ライブラリ（COMPRESS と SHA、DMA のスループットなど）のどれを使うか選ぶ外部開発者。
• 新しい状態に対して記録済みの doca_bench ベースラインを再実行し、チューニングの変更（NUMA の固定、ドライバーのアップグレード、ファームウェアの書き込み）を検証するプラットフォームオペレーター。
• 下流の利用者（キャパシティプランニング、リグレッションの二分探索）が参照できる「デバイスが現時点で実現する性能」を示す成果物を作成する SRE／パフォーマンスエンジニア。
• *「デバイス Y 上の DOCA ライブラリ X では、どの程度のスループット／レイテンシが期待できますか？」*という問いに対して、データシートの見出しから推測するのではなく、測定値、その測定に使用したコマンドライン、対象範囲を示すバージョン、デバイス、環境を添えて、正確に答える AI エージェント。

このスキルは、doca_bench のソースコードをデバッグするユーザー向けではなく、docs.nvidia.com にある公開中の DOCA Bench ガイドに代わるものでもありません。

doca_bench は、リンクして使うライブラリではなく、ツール（単体の CLI バイナリと、リモートメモリ／RDMA／Eth シナリオのリモート側で使用するコンパニオンアプリ）として提供されます。このスキルでは、バンドル内の他のものと同じ kind: tool の3ファイル構成を使用するため、個々の動詞が提供済みバイナリへのルーティングスタブに集約される場合でも、エージェントのタスク動詞の契約（configure / build / modify / run / test / debug）を、ライブラリ、サービス、ツール間で統一できます。

このスキルを読み込むタイミング

ユーザーが DOCA ≥ 2.7.0 をインストール済みの実ホスト上で（または同等バージョンの公開 NGC DOCA コンテナー内で）doca_bench を実行して、DOCA ライブラリのパフォーマンスを測定する場合、あるいはエージェントがその実行を必要とする場合に、このスキルを読み込みます。 具体的には、次のような場合です。

• 候補となるワークロードのベンチマーク対象となる DOCA ライブラリ（RDMA、COMPRESS、DMA など）を選ぶ。
• 求める測定軸（スループット、バルクレイテンシ、精度レイテンシ）を選ぶ。これらは公開ガイドに記載されている3つのモードです。max-bandwidth モードなどが含まれるかどうかも含め、全モードの一覧を --help で確認してください。各モードは相互に置き換えられません。
• インストール環境の粒度別ビルドの状態を調べ、ワークロードを捏造するのではなく、「このインストール環境ではこのライブラリを利用できません」とエージェントが正確に報告できるようにする。
• 後でリグレッションを調査できるよう、文書化されたベースライン（コマンドライン、バージョン、デバイス、デプロイ時の環境、測定値）を記録する。
• ワークロードの担当者に許容できるばらつきを事前に宣言してもらい、その許容範囲内に収まる連続2回の実行結果を得てから安定した結果を報告する。そうでない場合は、ばらつきをエスカレーションする。
• ベンチマーク実行でゼロ、不安定、または予想外の結果が報告された理由を診断する（タスクのコンパニオンにあるエラー分類に沿って確認します）。

一般的な DOCA の概要、ライブラリ API の作業、インストールには、このスキルを読み込まないでください。これらには、doca-public-knowledge-map/SKILL.md、該当する libs/<library> スキル、または doca-setup/SKILL.md を使用します。アプリケーションレベルのエンドツーエンドベンチマークにも、このスキルを読み込まないでください。doca_bench が測定するのは DOCA ライブラリのインターフェイスであり、その上に構築されたユーザーのアプリケーションではありません。

このスキルでできること

これは薄いローダーです。実質的な情報は、次の2つの関連ファイルに記載されています。

• capabilities companion — doca_bench で測定できる内容（ライブラリ横断の対象範囲、3軸の設定モデル、文書化されている動作モード、測定の妥当性を左右するウォームアップ／パイプライン／マルチコアの概念）、バージョンのオーバーレイ（正規の doca-version ルールに doca-bench 固有の情報を重ねたもの）、階層化されたエラー分類（config-syntax／device-binding／library-precondition／workload-precondition／measurement-soundness／version／cross-cutting）、可観測性の範囲（画面＋CSV 出力、リアルタイム統計、クエリーシステム）、安全性に関する方針（公開ガイドにある 「本番環境では使用しないでください」 という警告、ホストと BlueField の実行ルール、コンパニオンアプリの攻撃対象領域）。
• tasks companion — 対象となるタスク動詞の手順を追ったワークフロー：configure（3軸の判断＋ベンチマーク前のプローブ手順）、build（インストール先に誘導 — バイナリとコンパニオンアプリは配布済み）、modify（拒否 — ベンチマークのバイナリにパッチを適用せず、代わりにベンチマークの呼び出し方を変更）、run（大規模実行の前にスモークテストを行うフロー）、test（評価ループ — ウォームアップ、定常状態、外れ値、バージョン間比較）、debug（エラー分類を各階層に沿って確認）、さらに対象範囲外の質問を案内する Deferred task verbs ブロックと、doca_bench 固有の呼び出しクラスをまとめた Command appendix。

このスキルは、DOCA ≥ 2.7.0 がすでにインストールされているホスト（または同等のバージョンの公開 NGC DOCA コンテナーが稼働しているホスト）を前提としています。また、オペレーターには、利用するプラットフォームで doca_bench がデバイスをバインドし、リソースを割り当てるために公開ガイドで要求されている権限が付与されているものとします。

このスキルに意図的に含めていないもの

このスキルはエージェント向けのガイダンスであり、サンプルやスクリプトのバンドルではありません。境界を明確に保つため、意図的に以下を含めていません。プルリクエストで追加しないでください。

• 公開 DOCA Bench ガイドに記載されているもの以外の、具体的なフラグ文字列やシナリオ／メトリック／属性名。 フラグの仕様は変化し、インストール環境にも依存します。正確な情報は、文書化された呼び出し方と、インストール済みバージョンでの --help です。フラグをでっち上げることは、このスキルで最もよくあるハルシネーションです。
• 事前に用意した出力例や想定スループット値。 ベンチマークの出力は、デバイス、バージョン、ファームウェア、NUMA、チューニングに依存します。特定のプラットフォームと DOCA バージョンに固定された数値を引用すると、別のプラットフォームやバージョンを使うオペレーターを誤解させます。
• doca_bench の CSV や標準出力を読み込む、あらゆる言語のラッパー、パーサー、スクリプト。 出力形式は文書化されています。ユーザーがそれらをスクリプトから扱いたい場合は、「現行のガイドを読み、インストール済みバージョンに合わせてパーサーを作成してください」と案内するのが適切です。
• samples/ または reference/ のサブツリー。 これは文書化された CLI 用の薄いローダーです。実質的な情報は公開ページと --help にあります。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内か確認します（ユーザーが求めているのは、DOCA ライブラリ全般について学ぶことではなく、測定のために実際に doca_bench を呼び出すことです）。
2. doca_bench で測定できる内容、3軸モデル、バージョンのオーバーレイ、エラー分類、可観測性の範囲、安全性に関する方針については、capabilities companion を参照してください。
3. 文書化された呼び出し方と、大規模実行の前にスモークテストを行うワークフロー（configure、build、modify、run、test、debug）については、tasks companion を参照してください。

関連スキル

• doca-public-knowledge-map/SKILL.md — docs.nvidia.com の公開 DOCA Bench ページと、その他の公開 DOCA ドキュメント一式へのルーティングです。
• doca-version/SKILL.md — 正規の バージョン検出チェーン、4者照合ルール、NGC コンテナの セマンティクス、およびヘッダー優先ルールを定めています。このスキルの ## Version compatibility セクションは、doca-version に重ねる薄い オーバーレイです。本体はそちらにあります。
• doca-structured-tools-contract/SKILL.md — 構造化出力ヘルパーツールに関する、バンドル全体の 契約です。検出・優先・フォールバック・報告のループを満たす Bench ランナー／Bench スナップショットの実行ファイルは PR2 まで保留されています。この 契約を事前に取り込むことで、タスク側のコンパニオンにある ## Command appendix が PR1 からインフラを考慮した内容になります。
• doca-setup/SKILL.md — 環境の準備、 インストールの検証、HugePages、NUMA の認識、および 公開 NGC DOCA コンテナを使う インストールがまだありません の 手順です。
• doca-debug/SKILL.md — 分野横断的な デバッグ手順です。Bench はコンパニオンの capabilities で 独自のエラー分類を示します。 原因が DOCA の下位レイヤー（ドライバー、ファームウェア、 NUMA）にあると判明した場合は、Bench のエラー分類から doca-debug に引き継ぎます。
• doca-caps/SKILL.md — デバイスごと・ライブラリごとの大まかな 機能スナップショットを取得する、兄弟 DOCA ツールです。 Bench は独自のクエリシステムを使って、より細かい粒度で機能を調べます。 doca_caps は、デバイスが DOCA から認識されているかを確認するための、より手軽な最初の手段です。
• 対象ライブラリに対応する libs/<library> スキル — 例： doca-comch/SKILL.md、 doca-compress/SKILL.md — テスト対象ライブラリの ワークロード側の前提条件、機能クエリのルール、および エラー分類のオーバーレイを説明します。Bench は ライブラリを動作させ、ライブラリのスキルは、そのライブラリにとって 「健全」とは何を意味するか を説明します。