doca-urom-svc

DOCA UROM Service

まず対象範囲を確認してください。 このスキルは、DPU 側のサービスコンテナーを操作します。 たとえば MPI または UCX ジョブからオフロードする操作を送信する、ホスト側アプリケーションコードの作成はこのスキルの対象外です。 その場合は doca-urom/SKILL.md のホストライブラリを参照し、連携するサービスについてのみ、ここに戻ってください。

例

• 「BlueField ペアで UCX の集合通信が遅いです。」 — これは DPU 側サービスコンテナーの対象です。ホストアプリケーションコードについては、doca-urom ライブラリのスキルを参照してください。
• 「起動後に予期しない NOT_PERMITTED が発生します。」 — Comch のペアリングと、公開範囲を広げる前に最小権限のメモリー領域を確認してください。

手順

以下の読み込み順に従ってください。設定／ペアリング／デバッグについてはタスク用のコンパニオンファイルを開いてください。キューと UCX コンポーネントについては機能用のコンパニオンファイルを開いてください。

最初に確認する内容： このスキルは、BlueField の Arm 側で DOCA UROM Service コンテナーを操作するためのものです。ライブラリへのリンクや、ホスト側のエンキューインターフェイスは対象ではありません。ユーザーがサービスコンテナーをデプロイまたは実行したい場合は、タスク用コンパニオンファイルの ## configure から始めてください。DOCA UROM Service のサービス形態、実行する処理、ホスト側ライブラリとの連携方法についての質問であれば、機能用コンパニオンファイルから始めてください。BlueField に DOCA がまだインストールされていない場合は、まず doca-setup/SKILL.md を参照してください。ユーザーの本当の質問が、連携 API を通じてリモートメモリー操作をエンキューするホスト側コードの作成についてであれば、適切なスキルはホスト側ライブラリの doca-urom/SKILL.md です。このサービスは、同ライブラリが処理をオフロードする DPU 側の実行機能です。

このスキルの使い方。 このファイルを読んだ後、質問に必要な ## <name> 見出しをコンパニオンファイル内で検索し、そのセクション全体を読んでください。その内容だけに基づいて回答し、記載されているシンボルとコマンドのみを引用してください。ドキュメントを閲覧せず、doca-public-knowledge-map のエントリーポイントを使用してください。対象外の依頼については、担当するスキルを示して終了してください。

このスキルが的確に回答できる質問の例

このスキルが回答できるように設計されている、DOCA UROM Service に関する質問の種類と、それぞれの回答例です。重要なのは質問の種類であり、回答例はその一例です。

• 「DOCA UROM Service は BlueField にデプロイすべきものですか。それともホストライブラリだけが必要ですか？」 — 回答例：「MPI クラスターのホストノードは doca-urom にリンクしています。BlueField 側では何を実行し、なぜそれも必要なのですか？」。capabilities companion のパブリッシャー／エグゼキューターのペア契約モデルと、capabilities companion の「どのような場合にデプロイするか」というパス選択ルール、さらに tasks companion の環境準備チェックリストで回答します。
• 「組み合わせて実行すべきライブラリとサービスのバージョンはどれですか？」 — 回答例：「ホスト群を新しい doca-urom にアップグレードしました。すべての BlueField のサービスコンテナーもアップグレードする必要がありますか。それとも組み合わせは柔軟ですか？」。capabilities companion のバージョン契約の補足情報、tasks companion のバージョンの組み合わせ手順、および標準の本文である doca-version/SKILL.md で回答します。
• 「このサービスは何を設定しますか。UCX コンポーネント、集団通信、キュー深度、ホストと Comch 経由でペアリングする方法ですか？」 — 回答例：「上流のスタックで all-reduce の集団通信をオフロードしたいのですが、この集団通信ファミリーをサービスに公開するにはどうすればよいですか。また、ホストは DOCA Comch 経由でどのようにペアリングしますか？」。capabilities companion の設定項目の表と、tasks companion の設定作成手順で回答します。
• 「doca_dev へのアクセスには問題がないのに、ホストの doca-urom 呼び出しが NOT_PERMITTED で失敗します。これはサービスの問題ですか？」 — 回答例：「doca_ctx_start() は正常に完了した後、ホストからの最初のエンキューが DOCA_ERROR_NOT_PERMITTED を返します」。capabilities companion の Comch ペアリング／RDMA 権限レイヤーと、tasks companion の段階的な切り分け手順で回答します。この手順では、サービス側の認可レイヤーを疑う前に、*「DOCA Comch エンドポイントのペアは正しく確立されているか、また基盤となる RDMA 権限スタックは正常か」*を確認します（出荷されたバイナリにそのようなレイヤーは存在しません。ここでの NOT_PERMITTED は Comch／RDMA のシグナルであり、UROM サービスの認可シグナルではありません）。
• 「操作はエンキューされますが、完了しません。サービスと基盤のどちらに問題がありますか？」 — 回答例：「ホストからのエンキューは成功しますが、進行エンジンが完了を検出しません。どのレイヤーで停止していますか？」。capabilities companion のサービスと基盤の切り分け、および tasks companion の段階的な切り分け手順で回答します。この手順では、どちらの側の修正を勧める前に、サービスキューの満杯／ハンドラーの停止と基盤となる RDMA トランスポートの停止を区別します。
• 「オフロード時のパフォーマンスがホスト CPU のベースラインより低下します。サービスがボトルネックですか？」 — 回答例：「サービスをデプロイしてワークロードは実行されますが、ホスト CPU が自ら投稿していたときより集団通信が遅くなっています」。capabilities companion の「オフロードは無料ではない」というルールと、tasks companion の大規模展開前のスモークテスト手順で回答します。この手順では、ワークロードのパターンが実際には DPU オフロードの恩恵を受けない可能性があることを、サービスのバグではなく妥当な診断として示します。

対象読者

このスキルは、BlueField 上で DOCA UROM Service コンテナをデプロイして運用する外部オペレーターおよびプラットフォームチームを対象としています。ホスト上の HPC／UCX／MPI ワークロードが doca-urom を介してキューに登録するリモートメモリー操作を受信し、実行するためのものです。具体的には、BlueField Arm 上でサービスコンテナを実行する人、公開する UCX コンポーネントとコレクティブを選択する人、エンキューキューの深さを設定する人、ホストの doca-urom とサービスコンテナ間の DOCA Comch エンドポイントのペアリングを設定する人（提供されているバイナリには、サービス側に独立した「ホストエンドポイントの認可リスト」はありません。アクセスは Comch のペアリングと基盤となる RDMA 権限によって制御されます）、そして本番の HPC ワークロードを拡大する前に、ホストライブラリと DPU サービスのペア契約をエンドツーエンドで検証する人が対象です。

このスキルは、DOCA UROM Service 自体に貢献する NVIDIA の開発者向けではありません。また、DOCA ライブラリを使った開発ガイドでもありません（doca-programming-guide/SKILL.md を参照）。DOCA UROM Service はライブラリではなくサービスです。オペレーターはコンテナをデプロイして設定します。リンクする lib<uromservice>.so はありません。対になるホスト側ライブラリ doca-urom/SKILL.md は、HPC アプリケーション開発者向けであり、サービスオペレーター向けではない、別の対象読者を持つ独立したスキルです。この 2 つをまとめて扱わないでください。

最初にデプロイ対象を選択してください。 HPC クラスターのホストノードが doca-urom ライブラリを使い、コレクティブ通信を BlueField にオフロードしてホスト CPU を計算に使えるようにしたい場合、チームが doca-urom を基盤とするカスタム HPC スタックを構築している場合、または上流の MPI／UCX スタックが UROM をトランスポートとして使うように設定されている場合は、このサービスをデプロイしてください。ホストが doca-urom を使っていない場合、HPC スタックが MPI でも UCX でもない場合（このサービスが実行するのは UROM 形式のオフロードであり、任意のネットワーキングには対応しないため、役に立ちません）、または想定するオフロードに対して BlueField ハードウェアの性能が不足している場合（デプロイ時の cap-query で事前に確認できます）は、このサービスをデプロイしないでください。ホストのワークロードが doca-urom を介してオフロードされない環境に、見込みだけでデプロイすると、メリットがないまま運用の複雑さが増します。

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

DOCA がすでにインストールされている BlueField で、DOCA UROM Service の実運用デプロイ作業を行う場合に、このスキルを読み込んでください。具体的には、次のような場合です。

• ユーザーの HPC 環境に DOCA UROM Service が適切かどうかを判断する場合（raw doca-rdma を使ってホスト CPU を通信経路に残す場合、または DPU オフロードをまったく使わない場合との比較）。
• BlueField Arm にサービスコンテナーをデプロイする場合 — 公開されている DOCA UROM Service Guide に従ってイメージを取得し、デーモンの CLI フラグ／環境変数（SERVICE_ARGS、UROM_PLUGIN_PATH）を設定し、plugins/ ディレクトリーをマウントし、公開されている Container Deployment Guide に従って BlueField コンテナーランタイム上でコンテナーを起動／停止します。
• サービスの設定項目を選択する場合 — サービスが公開する UCX コンポーネント／コレクティブ（BlueField の世代がサポートする範囲に制限）、オフロード経路の enqueue キュー深度、ホストの doca-urom ライブラリーとサービスを DOCA Comch 経由でペアリングする方法（アクセスは Comch のペアリングと基盤となる RDMA 権限によって制御されます。サービス側に認可リストはありません）。明示的に対象とするホストのみをペアリングし、RDMA エクスポートと権限はワークロードに必要な最小限にしてください。起動前に、文書化されている Comch および RDMA の読み取り専用インターフェイスを使って検証することが必須です。
• ホストライブラリーと DPU サービスのバージョンの組み合わせが DOCA Compatibility Policy でサポートされていることを確認する場合 — 不一致は、このペアリング契約において見落とされやすい典型的な障害要因です。
• サービスコンテナーのログ、サービスの可観測性インターフェイス、基盤となる RDMA 基盤のカウンターを確認し、ホストが enqueue した操作をサービスが実際に実行しているか検証する場合。
• コンテナーは正常でもホストの doca-urom enqueue が失敗または完了しない場合や、オフロードのパフォーマンスがホスト CPU のベースラインを下回るデプロイをデバッグする場合。

一般的な DOCA の概要、DOCA 自体のインストール、ホスト側 doca-urom ライブラリー API に関する質問、または UROM 以外の HPC スタックに関するトピックでは、このスキルを読み込まないでください。その場合は、doca-public-knowledge-map/SKILL.md、doca-setup/SKILL.md、または対応するホスト側ライブラリースキル doca-urom/SKILL.md に案内してください。

このスキルでできること

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

• 機能に関する関連ファイル — サービスのアーキテクチャ（ペアリングされたホストから UROM オフロードを実行する、BlueField Arm 上の長時間稼働コンテナー）、パブリッシャー／エグゼキューターのペアリング契約モデルと重要なバージョン連携ルール、設定項目（UCX コンポーネント／コレクティブの範囲、enqueue キューのサイズ設定、DOCA Comch エンドポイントのペアリング）、デプロイ構成（公開されている Container Deployment Guide に従った BlueField Arm 上のコンテナー）、ペアリングのインターフェイス（ホストの doca-urom ライブラリーと基盤となる doca-rdma トランスポート基盤）、可観測性インターフェイス（コンテナーの状態＋サービスログ＋RDMA カウンター）、エラー分類（コンテナーランタイム関連、サービス側リソース関連、トランスポート基盤関連、ペアリングされたバージョンの不一致）、安全ポリシー（経路の選択ルール、バージョン契約ルール、スケール前のスモークテスト）。
• タスクに関する関連ファイル — 対象となるサービス操作の動詞 configure、build、modify、run、test、debug についての手順を追ったワークフローに加え、対象外の質問の案内先を示す Deferred task verbs ブロックと、繰り返し使うコマンドをまとめた Command appendix。

このスキルは、DOCA がすでにインストールされている BlueField と、公開されている DOCA UROM Service Guide が想定する、BlueField Arm 上でコンテナーを取得、実行、設定する権限をオペレーターが持っていることを前提としています。DOCA のインストールは対象外です。その手順については doca-setup/SKILL.md を参照してください。ホスト側 doca-urom ライブラリー API も対象外です。こちらについては doca-urom/SKILL.md を参照してください。

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

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

• あらかじめ用意された DOCA UROM Service のフラグ／環境変数一式（UCX コンポーネント／collective の公開設定を網羅したマニフェストや、そのまま実行できるキュー深度の SERVICE_ARGS 文字列など）で、本番環境にコピー＆ペーストすることを目的としたもの。サービス設定はデプロイごとに異なります（BlueField の世代ごとの機能上限や、ワークロードの collective パターンに応じて変わります）。外部の運用者に対する安全な回答は、公開されている DOCA UROM Service Guide を参照し、自分のデプロイに合わせてデーモンのフラグ／環境変数を導き出すことです。エージェントの役割は、手順と設定軸に関する判断を示すことであり、ユーザーが変更せずに実行するおそれのある設定を提供することではありません。
• コンテナーイメージ名、タグ、レジストリパス。 信頼できるイメージソースは、doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）から参照できる公開 DOCA UROM Service Guide です。サービスのイメージタグはバージョンに紐づいており、DOCA のリリース間で変わります。また、ペアリング契約のルールに従って、ホスト側のライブラリバージョンと一致している必要があります。タグを推測したり記憶に頼ったりすることは、サービス向けスキルで典型的な幻覚の失敗パターンであり、とりわけこのサービスでは、ホストライブラリとサービスのバージョン不一致を気づかれないまま引き起こすおそれがあります。
• ホスト側の doca-urom アプリケーションのソースコード、ビルドマニフェスト、MPI／UCX 統合用のコード。 これらはホスト上にあり、doca-urom/SKILL.md（ホストライブラリの API）、または上流の MPI／UCX ドキュメント（スタック側の統合）の対象です。このスキルでは、ホスト側を doca-urom 経由で接続する必要があることと、サービスとバージョンを組み合わせる必要があることを示しますが、ホスト側の実装内容は対象外です。
• samples/、templates/、reference/ のいずれかのサブツリー。 模擬成果物に「reference」というラベルを付けると、本番環境で使用可能なものに見えてしまいます。また、ペアリング契約のあるサービスでは、スキルが保証できないホストライブラリのバージョンとのペアリングを暗に主張することになります。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内であること、そして DOCA UROM Service が適切な解決策であることを確認します（ホスト側ライブラリのスキルに完全に振り分けるべきか、ワークロードがオフロードの恩恵を実際には受けないため UROM 以外に振り分けるべきかも確認してください）。
2. サービスのデプロイ形態、パブリッシャー／エグゼキューターのペアリング契約モデル、設定軸、ホストライブラリと RDMA 基盤の組み合わせ、エラーの分類、可観測性、バージョン連携のルール、パス選択の安全性ポリシーについては、機能の補足ドキュメントを参照してください。
3. 設定、ビルド、変更、実行、テスト、デバッグの手順を順に説明するワークフローについては、タスクの補足ドキュメントを参照してください。

関連するスキル

• doca-urom/SKILL.md — 対となるホスト側ライブラリです。ホストは doca-urom をリンクしてリモートメモリ操作を ENQUEUE し、このサービスがそれを EXECUTES します。HPC オフロードを導入する際は、2 つのスキルを併せて読み込みます。ただし、両者は互いに統合されるものではありません。ライブラリ単体では実行されず、このサービスが単独で ENQUEUE されることもありません。ライブラリとサービスの不整合は、この連携契約における微妙な障害の主な原因です。
• doca-rdma/SKILL.md — ホストからの ENQUEUE が DPU に到達した後、実際にバイト列を転送するためにこのサービスが使用する、基盤となる RDMA トランスポート層です。このサービスは RDMA を置き換えるものではなく、その上で動作します。RDMA ファブリックに障害があると、このサービスでは 操作が ENQUEUE されたものの完了しない 状態となり、ホストでは DOCA_ERROR_IO_FAILED が発生します。修正するのはこのサービスの設定ではなく、基盤層です。
• doca-public-knowledge-map/SKILL.md — 公開 DOCA UROM Service Guide およびその他の公開 DOCA ドキュメント一式へのルーティングテーブルです。サービスの URL は ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）に記載されています。
• doca-setup/SKILL.md — サービスコンテナを実行する BlueField での環境準備とインストールの確認について説明します。公開 NGC DOCA コンテナを利用する まだインストールしていない場合 の手順も含まれます。このスキルでは、BlueField Arm 上で前提条件が満たされていることを想定しています。
• doca-version/SKILL.md — DOCA のバージョンを扱う際の規則を定めた正規の情報源です。このサービスのコンテナタグはバージョンに依存し、ホストライブラリとの組み合わせもバージョンに依存します。このスキルの ## Version compatibility では、4 つの要素の一致ルールへの相互リンクに加え、UROM の運用に不可欠なホストライブラリと DPU サービスのバージョン組み合わせに関する補足を記載しています。
• doca-structured-tools-contract/SKILL.md — バンドル内の構造化ツールに関する優先順位の規則（検出／優先／フォールバック／報告）です。タスク用コンパニオンの「コマンド」付録はこの規則に従います。
• doca-programming-guide/SKILL.md — DOCA の一般的なパターンを説明します。DOCA UROM Service はライブラリ型ではなくサービス型のため、ここにあるビルド／変更／最初のアプリケーションのパターンは直接適用できません。ただし、サービスがコンテナランタイムまたは呼び出した DOCA ライブラリに起因するエラーを報告した場合は、ライブラリをまたいだデバッグの基本原則（プログラムより先に環境、設定より先にレイヤー）が引き続き役立ちます。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／ランタイム／プログラム／ドライバーを順に確認する、横断的なデバッグ手順です。サービス固有のデバッグ（コンテナが起動していない、ホストライブラリとサービスのバージョン不一致、トランスポート層の停止、オフロードが実際には役立っていない）は、この手順に重ねて行います。
• doca-dms/SKILL.md および doca-firefly/SKILL.md — 同系列のサービス用スキルです。これらのスキルを読むエージェントは、サービス用スキルに共通する構成（BlueField Arm 上のコンテナ、標準的な手順としての公開 Container Deployment Guide、最初に環境の前提条件を確認し、サービスごとに文書化された方法で設定すること — UROM の場合はマウントした設定ファイルではなく、デーモンの CLI フラグ／環境変数 —、規模拡大の前にスモークテストを行うこと）と、サービスごとに異なる問題領域（DMS は gNMI／gNOI によるデバイス管理、Firefly は PTP による時刻同期、UROM Service は対となる doca-urom ライブラリを介した HPC リモートメモリ操作の実行）を把握できます。