技術ポータル「iSUS」をリニューアルいたしました！お探しの記事を快適に検索いただくための絞り込み機能 (トピック検索) の使い方はこちら。

インテル® VTune™ プロファイラー AI アシスタント — ユーザーガイド

インテル® VTune™ プロファイラー
Linuxドキュメント

このドキュメントは、インテル® VTune™ プロファイラー 2026.4 Linux 版のインストールに含まれる、vtune-profiler-ai-assistant/user-docs/USER_GUIDE.md を iSUS で翻訳した日本語参考訳です。原文は更新される可能性があります。原文と翻訳文の内容が異なる場合は原文を優先してください。

インテル® VTune™ プロファイラー向けの対話型アシスタント。「バイナリーのホットスポットを見つける」、「5 秒間プロファイルする」といった具合に、やりたいことを簡単な言葉で伝えると、アシスタントが適切なインテル® VTune™ プロファイラーのコマンドを生成し、ユーザーの確認を得て実行します。さらに、生成された (膨大な) レポートを解析し、その結果をパフォーマンス・エンジニアリングの観点から解説します。

このガイドでは、日常的な使い方を説明します。インストール方法および AI プロバイダーの選択については、README を参照してください。トラブルシューティングについては、FAQ をご覧ください。

1. 「できること」 と 「できないこと」

できること:

  • インテル® VTune™ プロファイラーのインストール状況、およびプローブホストの機能 (PMU へのアクセス、権限) を確認できます。

  • 適切な分析タイプを選択して、正しい `vtune -collect` / `vtune -report` コマンドを作成します。

  • 収集やレポートを実行します (影響の大きい操作については、常にユーザーの同意を得て実行します)。

  • 詳細な CSV/XML レポートを要約してボトルネックについて説明します。

  • 実行の記録は、閲覧やラベル付けが可能なローカルの「パフォーマンス・ラボ・ノートブック」に保存されます。

できないこと (設計上の理由):

  • システムのシェルコマンドを実行したり、`sudo` を使用するには、それらの機能を有効にする必要があります ([§7](利用許諾と安全性) を参照)。

  • 事前の確認なしに、影響の大きい操作 (収集、コンパイル、ファイル編集など) を実行すること。

  • 設定した AI プロバイダー ([§8](データの保存場所) を参照) 以外に送信すること。

2. セッションを開始

$ bash
$ ./bin/vtune-ai chat

最初に遭遇する可能性があること:

  • プライバシーとデータに関する同意 (初回実行時のみ): アシスタントは LLM を使用するため、コードやインテル® VTune™ プロファイラーのメトリックは、解析のため設定済みのプロバイダーへ送信されます。承諾すると、その選択が維持されます。

  • オプション機能に関する注意: 安全上の理由から、昇格権限が無効化された状態で提供されています。起動時に、それらを有効にするよう提案します:

    • シェルアクセス (`allow_dangerous_shell`) — アシスタントが `ls` / `file` などのコマンドを実行して、バイナリーの場所を特定したり、それらを調査できるようにします。それがなければ、アシスタントはファイルシステムを閲覧することができません。

    • 権限の昇格 (`allow_sudo`) — ホストが制限されている環境でハードウェア・サンプリングを行うため、アシスタントがインテル® VTune™ プロファイラー・コマンドの先頭に `sudo` を付加できるようにします。それぞれ、`y`/`n` で回答します。選択した内容は `vtune-ai.toml` に書き込まれ、すぐに反映されます (再起動は不要)。

チャットを開始する前に、プロバイダーや認証情報が設定されていることを確認するには:

$ bash
$ ./bin/vtune-ai check

3. プロファイルのワークフロー

インテル® VTune™ プロファイラーのオプションフラグを覚える必要はありません。目的を指定します。典型的な対話:

> 開発者: ~/test-app/branching/inefficient_long_debug に対して 5 秒間のパフォーマンス・スナップショットを実行する (run a performance snapshot against ~/test-app/branching/inefficient_long_debug for 5 seconds)

アシスタントは以下のことを行います:

  1. ターゲットが存在することを確認します (同時に、ホストのサポート状況やインテル® VTune™ プロファイラーの構文を確認します)。

  2. コマンドを構築して提示しますが、実行はしません。

  3. 開発者の同意を待機します。提案された収集に対して `yes` (または `no`) で回答します。

  4. それを実行し、レポートを生成して要約し結果を説明します。

これはインテル® VTune™ プロファイラー自体の操作フローを反映しています: 収集 → レポート → まとめ。アシスタントは生成したコマンドを常に正確に表示するため、開発者はターミナルでどの手順も再現できます。

同意: 読み取り専用の操作 (検出、ホストチェック、ヘルプ、ファイル一覧の表示) は即座に実行されます。収集の実行、ファイルのコンパイルや編集など、何らかの影響を及ぼす操作については、まず提案がなされ、開発者の明示的な同意 `yes` を待機します。いずれかのステップが失敗した場合、アシスタントはそのまま再試行することはなく、処理を停止して説明します。

4. サンプリング・モード (ハードウェアとソフトウェア)

サポートする解析をホストが許可している場合、アシスタントはハードウェア・イベント・ベースのサンプリング (オーバーヘッドが低く、分解能が高く、カーネル時間も収集可能) を優先的に使用します。

解析

サンプリング knob

`hotspots`

`-knob sampling-mode=hw`

`threading`

`-knob sampling-and-waits=hw` (異なる knob)

他の解析手法 (`performance-snapshot`、`uarch-exploration`、`memory-access`、`hpc-performance` など) は、ソフトウェア/ハードウェアの切り替え (knob) を考慮していません。これは、`uarch-exploration` と `memory-access` は、ハードウェアベースであるためです。

ハードウェア・サンプリングでは、昇格権限が必要です。`perf_event_paranoid` (> 1) の制限が設定されているホスト上では、root 以外のユーザーはハードウェア・サンプリングを実行できません。`allow_sudo` を有効にしている場合、アシスタントは `sudo` を付加したコマンドを提案します。そうでない場合、ソフトウェア・サンプリングにフォールバックするか、`perf_event_paranoid` の設定を下げるか、SEP ドライバーをインストールする、のいずれかになります。詳細は、FAQ を参照してください。

5. パフォーマンス・ラボ・ノートブック

実行するすべての収集は、ローカルの SQLite ノートブックに自動的に保存されます。これはデフォルトで有効になっています。これにより、実行のたびにコンテキストが失われることなく、最適化の履歴を蓄積できます。

スラッシュコマンドでいつでも閲覧できます (即時表示、AI 呼び出しは不要):

$ /jobs

Performance Lab Notebook — 4 most recent run(s)

ID

When

Analysis

Target

Status

Label / Tags

4

2026-06-29…

performance-…

…branching

completed

phase=base

これにより可能なこと (ID を指定して実行内容を参照するだけです):

  • 後で簡単に参照できるよう、実行にラベルを付けます: “ジョブ 4 をベースラインとしてラベル付ける” (label job 4 as baseline) と、後続の実行を “after-O3” とすることができます。

  • 過去の実行内容を再確認: “このバイナリーをプロファイルした過去の実行結果を表示する” (show my past runs profiling this binary) — アシスタントは再実行する代わりに、保存されたメトリックを使用します。

  • 結果と変更の記録: アシスタントは、解析内容、ユーザーが行ったコードやフラグの変更、および重要な KPI (CPI など) を記録します。これにより、試した内容と、それがパフォーマンスにどのような影響を与えたかについて、監査証跡が作成されます。

> 実行結果の比較: 専用の比較ツールの導入が計画されています。現在は、アシスタントに 2 回の実行結果を要約してもらい、それらを比較してください。

6. スラッシュ (/) コマンド

これらはローカルの REPL コマンド (`>` プロンプトで入力したもの) であり、モデルには送信されません:

コマンド

何を行うか

`/jobs` (または `/history`)

パフォーマンス・ラボ・ノートブックの最近の実行結果を一覧表示

`/clear`

画面を消去して会話履歴をリセット

`/copy`

アシスタントの最後の応答をクリップボードにコピー

`/exit` (または `/quit`)

セッションを終了

Tab キーを押すと、コマンドが自動補完されます。

7. 利用許諾と安全性

アシスタントは、意図的に制限されています。2 つのオプトイン機能 (いずれもデフォルトでは無効、設定は `vtune-ai.toml` で行う):

設定

有効

デフォルト

`allow_dangerous_shell`

システムシェルコマンドの実行 (`ls`、`file`、`perf`、…)

`false`

`shell_whitelist`

シェルが実行可能なバイナリー (`[“*”]` ＝ 任意のもの

`[“*”]`

`allow_sudo`

ハードウェア・サンプリングを行うには、インテル® VTune™ プロファイラー・コマンドの先頭に `sudo` を追加します

`false`

これらは、セッションの起動時(§2) で有効にするか、`vtune-ai.toml` を直接編集することで有効にできます。編集内容はリアルタイムで反映されるため、アプリを再起動する必要はありません。

その他のガード (常時有効): インテル® VTune™ プロファイラーのコマンドは検証済みであり、シェルから実行されることはないため (インジェクションはありません)、実行対象は検出されたインテル® VTune™ プロファイラーのバイナリーに限定されます。また、保存された実行結果を削除するには、ユーザーの同意が必要です。

8. データの保存場所

すべてのデータは、コンピューター上のプロジェクト・ディレクトリーに保持されます:

パス

内容

`vtune-ai.toml`

ルーティング設定 (プロバイダー、モデル) および権限設定

`.env`

プロバイダーのシークレット (API キー、リージョン、エンドポイント) — コミットしないこと

`data/vtune_ai.db`

パフォーマンス・ラボ・ノートブック: 実行、レポート、分析、ラベル、KPI

`results/`

インテル® VTune™ プロファイラー結果ディレクトリー (`<analysis>_<target>_<timestamp>`)

`reports/`

`job_<id>_<type>.<ext>` という名前で生成され、実行に関連するレポートファイル

`logs/`

セッションごとの JSONL 形式のトランスクリプト (git の管理対象外)

使用するコンピューターから外部に送信されるデータは、設定した AI プロバイダーに送られるもの (解析用のコードスニペットやインテル® VTune™ プロファイラーのメトリック) だけであり、これについては初回起動時に同意が必要です。

9. 独自のエージェント (スタンドアロン MCP サーバー) を使用

同梱の `vtune-ai chat` CLI ではなく、独自の AI エージェント (Claude Code、Claude Desktop、Cursor、または MCP 互換ホストなど) を使用する場合、プロジェクトの MCP サーバーを登録できます。その後、エージェントはインテル® VTune™ プロファイラーを直接取得し、独自モデルと対話ループを使用します。

取得できるもの

MCP サーバーは、インテル® VTune™ プロファイラー・ツール (バンドルされているペルソナではなく) を提供します。エージェントは、インテル® VTune™ プロファイラーの検出やホスト/PMU のサポート状況の確認、CLI 構文の検索、プロファイル手法に関する知識の参照、データ収集とレポートの生成・実行、結果の要約を行うほか、パフォーマンス・ラボ・ノートブックの全機能 （`list_jobs` での閲覧、`tag_job` でのラベル付け、`log_analysis`/`log_modification`/`record_kpi` での注釈追加、`prune_jobs` での削除) を利用できます。全リストについては、以下の [ツールとリソースカタログ] を参照してください。6 つのリソースも公開されています (`vtune://concepts`、`vtune://environment`、`vtune://release-notes`、`vtune://methodology`、`vtune://workload-signatures`、`vtune://metrics`)。

> 注: CLI の動作上のガード (同意確認の仕組み、「影響の大きい操作を行う前の安全な承認」というポリシー、サンプリングのヒューリスティクスなど) は、MCP サーバーではなく、CLI のペルソナに実装されています。エージェントが、判断を下します。特に、サーバー側に同意確認の仕組みは存在しません。そのため、`prune_jobs` のような破壊的なツールは、エージェントが (サーバーからの指示に従って) 事前に確認を行うかどうかに依存します。

要件

`./setup.sh` を一度実行します (README に記載)。これにより、`<project>/.venv/bin/vtune-mcp` (`<project>` はこのチェックアウトの絶対パス) に自己完結型のサーバーランチャーが作成されます。stdio 経由で動作し、独自の API キーを必要とせず、どこから起動された場合でもプロジェクトを基準として設定ファイルやデータベースの場所を特定します。

Claude Code に登録

$ bash
$ claude mcp add vtune -- /ABSOLUTE/PATH/TO/PROJECT/.venv/bin/vtune-mcp

その後、Claude Codeのセッション内で、`/mcp` は `vtune` サーバーとそのツールをリストアップします。

Claude Desktop / Cursor に登録 (JSON 設定)

ホストの MCP 設定 (Claude Desktop `claude_desktop_config.json` の設定やプロジェクト `.mcp.json` など) にサーバーを追加します:

json
{
  "mcpServers": {
    "vtune": {
      "command": "/ABSOLUTE/PATH/TO/PROJECT/.venv/bin/vtune-mcp"
    }
  }
}

`/ABSOLUTE/PATH/TO/PROJECT` を使用するチェックアウト・パスで置き換えます。新しいサーバーを認識させるために、ホストを再起動します。

検証

登録後、エージェントに “VTuneのインストール状況を確認する” (discover the VTune installation) や “このホストはどのような解析タイプをサポートしているか?” (what analysis types does this host support?) といった質問を試してください。— `discover_vtune`/`check_host` を呼び出す必要があります。サーバーが表示されない場合は、`vtune-mcp` へのパスが絶対パスであり、かつ実行可能 (`ls -l <project>/.venv/bin/vtune-mcp`) であることを確認してください。

10. ツールとリソースカタログ

これらは、アシスタントが内部で使用する構成要素です。通常、CLI でそれらを直接呼び出すことはありません。目標を記述すれば、アシスタントが適切なものを選択してくれます。これらは、透明性を確保するため、また MCP (§9) 経由で接続する外部エージェントが呼び出すために、ここに記載されています。

ディスカバリーとホスト

ツール

何を行うか

`discover_vtune`

インテル® VTune™ プロファイラーのバイナリーの位置を特定し、そのバージョンをレポートします。

`check_host`

ホストの機能 (`perf_event_paranoid`、仮想化、SEP ドライバー) を調査し、サポートされている解析タイプをレポートします。

`check_pmu`

ディストリビューション固有のガイドを含め、この CPU で利用可能な PMU イベントを照会します。

`get_help`

任意のトピックについて、インテル® VTune™ プロファイラーの CLI ヘルプを参照してください (インストールされているバージョンのコマンド構文をベースに)。

プロファイル手法に関する知識 (アシスタントが参照する読み取り専用のリファレンス)

ツール

何を行うか

`get_analysis_methodology_ref`

観測されたメトリックを次に実行すべき解析へマッピングする決定ルールと、ボトルネックごとの修正のヒント。

`get_workload_signatures_ref`

ワークロードの分類 (HPC、AI、GPU、データベース、ウェブなど) を識別する早見表。

`get_metrics_reference_ref`

インテル® VTune™ プロファイラーのメトリック/カラムおよびその重大度の定義集。

`get_release_notes`

インテル® VTune™ プロファイラーのリリースノートおよびシステム要件 (バージョン、サポートされる機能)

ビルドと実行 (実行は影響を及ぼす操作であるため、CLI では実行前に同意が求められます)

ツール

何を行うか

`build_collect_command`

レビュー用に、検証済みの `vtune -collect` コマンド (タイムスタンプ付きの結果ディレクトリーを含む) を作成します。

`build_report_command`

レビュー用に、検証済みの `vtune -report` コマンドを作成します。`run_collection` 構築された収集コマンドを実行します。

`run_collection`

構築された収集コマンドを実行します。

`run_report`

構築されたレポートコマンドを実行します。

`summarize_report`

冗長な CSV/XML レポートを解析し、LLM にとって有益な情報 (ハイシグナルな知見) を抽出します。

パフォーマンス・ラボ・ノートブック (実行履歴 — §5 を参照)

ツール

何を行うか

`list_jobs`

記録された実行 (CLI `/jobs` コマンドの背後にあるデータ) を閲覧します。

`tag_job`

実行にラベルまたはキー値のタグを適用します。

`log_analysis`

実行に関するアシスタントの解析を記録します。

`log_modification`

実行の合間のコードやフラグの変更を記録します。

`record_kpi`

実行時の KPI (例: CPI、経過時間) を記録します。

`prune_jobs`

保存された実行結果を削除します (破壊的操作には同意が必要)。

> また、CLI には、`ls`/`file`/`perf` のような読み取り専用のホストを診断するため、条件付きで登録されるツール `run_system_shell_command` (`allow_dangerous_shell` による制限あり。§7を参照) も用意されています。意図的に MCP 経由では公開されていません。外部ホストは独自のシェルを使用します。

リソース (MCP のみ — 外部ホストがアタッチ可能な読み取り専用コンテキスト):

`vtune://concepts`、`vtune://environment`、`vtune://release-notes`、`vtune://methodology`、`vtune://workload-signatures`、`vtune://metrics`。

タイトルとURLをコピーしました