このチュートリアルでは、次の上に実装します。 Nsight Pythonは、NVIDIA のカーネルプロファイラへのオープンソース Python インターフェースです。スクリプトを Nsight Compute のコマンドラインで実行してからレポートを掘り起こす代わりに、注目するコードを nsight.annotate でマークし、ベンチマーク関数を nsight.analyze.kernel でデコレートすれば、注釈付き領域ごと、構成ごと、実行ごとのハードウェアメトリクスの pandas DataFrame が返ってきます。バージョン 1.0 以来、このライブラリは実行中の Python プロセスに Nsight Compute をアタッチできるため、Jupyter や Colab で使用可能であり、今後の 1.1 リリースでは実験的な CUPTI バックエンド、明示的なツール管理、カスタム情報コレクターが追加されます。すべて無料の Colab T4 上で実行します。Colab に同梱されているものの横に最新の Nsight Compute をインストールし、最初のカーネルをプロファイリングし、1 つの測定に何回の実行が必要かを決め、キャッシュ制御とクロック制御が同じカーネルに与える影響を測定し、導出した TFLOP/s メトリクスを用いて fp32 と fp16 で行列サイズをスイープし、ハードウェアカウンターを使って計算束縛とメモリ束縛の処理を区別し、移動バイト数でカーネル融合を測定し、実行ごとにクロックと温度を記録し、CUPTI バックエンドを Nsight Compute と比較し、より深い分析のために生のレポートを保持します。
Copy Codeimport os
import sys
import glob
import json
import time
import shutil
import textwrap
import traceback
import subprocess
RESULTS = {}
def banner(title):
print("\n" + "=" * 78)
print(title)
print("=" * 78)
def section(name):
def wrap(fn):
def run(*a, **kw):
banner(name)
try:
out = fn(*a, **kw)
RESULTS[name] = out if isinstance(out, str) else "ok"
return out
except Exception as e:
RESULTS[name] = f"SKIPPED / FAILED -> {type(e).__name__}: {str(e).splitlines()[0][:160]}"
print(f"\n[!] {name} did not complete: {type(e).__name__}: {e}")
traceback.print_exc(limit=3)
return None
return run
return wrap
def sh(cmd):
"""Run a shell command and return its stdout, stripped."""
return subprocess.run(cmd, shell=True, capture_output=True, text=True).stdout.strip()
banner("1. Install a current Nsight Compute next to Colab's, then import nsight before CUDA")
print(f" GPU: {sh('nvidia-smi --query-gpu=name,driver_version,memory.total,compute_cap --format=csv,noheader')}")
preinstalled = shutil.which("ncu")
print(f" ncu already on PATH: {preinstalled} -> {sh('ncu --version | tail -1') if preinstalled else 'none'}")
# nsight-python needs Nsight Compute 2026.2.1 or newer. Colab ships an older ncu, but its image already
# carries NVIDIA's CUDA apt repository, so a current release is one apt-get away. It installs into
# /opt/nvidia/nsight-compute/<version>/ and leaves the preinstalled one untouched.
subprocess.run("apt-get update -qq > /tmp/ncu_install.log 2>&1", shell=True)
for NCU_VERSION in ("2026.3.1", "2026.2.1"):
if subprocess.run(f"apt-get install -y -qq nsight-compute-{NCU_VERSION} >> /tmp/ncu_install.log 2>&1",
shell=True).returncode == 0:
break
else:
print(sh("tail -5 /tmp/ncu_install.log"))
raise RuntimeError("could not install Nsight Compute 2026.2.1+ from NVIDIA's apt repository")
# ask dpkg where the package put the ncu launcher rather than assuming /opt/nvidia/nsight-compute/<version>/
ncu_paths = sh(f"dpkg -L nsight-compute-{NCU_VERSION} | grep -E '/ncu$'").split()
if not ncu_paths:
raise RuntimeError(f"dpkg lists no ncu executable in nsight-compute-{NCU_VERSION}")
NCU_DIR = os.path.dirname(min(ncu_paths, key=len)) # the top-level launcher, not a per-platform copy
os.environ["PATH"] = NCU_DIR + os.pathsep + os.environ["PATH"] # nsight-python looks ncu up on PATH
print(f" installed: {shutil.which('ncu')} -> {sh('ncu --version | tail -1')}")
# nsight-python 1.1.0 (CUPTI backend, tool APIs, info collectors) is tagged but not yet on PyPI;
# pin the commit this notebook was written against. The [cupti] extra is used in step 9.
NSIGHT_COMMIT = "bb96db4260b1823d86ecab9acfed0646d7af79ad"
subprocess.run([sys.executable, "-m", "pip", "install", "-q",
f"nsight-python @ git+https://github.com/NVIDIA/nsight-python@{NSIGHT_COMMIT}"], check=True)
# The CUPTI backend needs cupti-python 13.4, which wants a newer libcupti than Colab's torch is pinned to.
# Install it into a separate directory that only step 9's child process puts on its path.
CUPTI_DIR = "/content/cupti_env"
CUPTI_EXTRA = subprocess.run([sys.executable, "-m", "pip", "install", "-q", "--target", CUPTI_DIR, "--no-deps",
"cupti-python>=13.4.0", "nvidia-cuda-cupti~=13.4", "pyelftools"]).returncode == 0
import nsight # activates Nsight Compute's injection library: must come before anything initializes CUDA
from nsight.collection import ncu as ncu_backend
import numpy as np
import pandas as pd
import torch
SILENT = nsight.VerbosityLevel.SILENT
pd.set_option("display.width", 200)
pd.set_option("display.max_columns", 30)
print(f" nsight-python {nsight.__version__} | active tool: {nsight.get_active_tool()}"
f" | injection error at import: {ncu_backend.injection_load_error}")
print(f" torch {torch.__version__} (CUDA {torch.version.cuda}) | {torch.cuda.get_device_name(0)}"
f" | cupti-python installed: {CUPTI_EXTRA}")
print("\n Order matters: `import nsight` loads Nsight Compute into this Python process, and it can only")
print(" attach to CUDA work started after that. Every profiled function below runs in this same")
print(" process; nsight-python starts `ncu --mode attach` on its own PID for each one.")
まず GPU とプロファイラを確認します。Nsight Python は Nsight Compute のコマンドラインツール ncu のバージョン 2026.2.1 以降を必要とし、PATH で検索して見つけます。Colab の GPU イメージには古い Nsight Compute が同梱されています。それでも NVIDIA の CUDA パッケージリポジトリはすでに設定されているため、apt-get で Nsight Compute 2026.3.1 をインストールし、dpkg に ncu ランチャーの配置先を尋ね、そのディレクトリを PATH の先頭に置きます。次に、このノートブックを執筆した際の 1.1.0 プレリリースのコミットにピン留めした Nsight Python と、cupti-python パッケージを別のディレクトリにインストールします。これは、Colab の PyTorch がピン留めしているものより新しい CUPTI ライブラリが必要だからです。インポートの順序が重要です: import nsight は Nsight Compute のインジェクションライブラリを Python プロセスに読み込み、それ以降に開始された CUDA 処理にしかアタッチできないため、nsight は torch が GPU に触れる前にインポートしなければなりません。
Copy CodeADD = lambda x, y: x + y # sums a metric if cuBLAS splits one matmul into several kernels
@nsight.analyze.kernel(thermal_mode="off", combine_kernel_metrics=ADD)
def first_matmul(n: int) -> None:
a = torch.randn(n, n, device="cuda")
b = torch.randn(n, n, device="cuda")
with nsight.annotate("matmul"):
_ = a @ b
@section("2. Profile one kernel: what a ProfileResults row contains")
def first_profile():
df = first_matmul(2048).to_dataframe()
print(f"\n to_dataframe() columns: {list(df.columns)}\n")
r = df.iloc[0]
t = float(r["AvgValue"])
print(f" annotation {r['Annotation']!r}, n = {r['n']}, kernel {r['Kernel']}")
print(f" {r['Metric']} = {t:,.0f} {r['Unit']} (runs {r['NumRuns']}, stable: {r['StableMeasurement']})")
print(f" GPU {r['GPU']}, ComputeClock {r['ComputeClock']}, MemoryClock {r['MemoryClock']}")
print(f" -> {2 * 2048 ** 3 / (t * 1e-9) / 1e12:.2f} TFLOP/s for a 2048 x 2048 fp32 matmul")
print("\n Only the kernel launched inside nsight.annotate() is profiled; torch.randn above it is not.")
print(" With a single run, StableMeasurement is <NA>: one sample has no spread to judge.")
return f"fp32 2048 matmul {t / 1e6:.3f} ms ({2 * 2048 ** 3 / (t * 1e-9) / 1e12:.2f} TFLOP/s)"
first_profile()
最初のプロファイルは単一の fp32 行列乗算です。ベンチマーク関数が入力を作成し、乗算だけを nsight.annotate で囲むため、入力を生成する乱数カーネルは測定されません。デコレートされた関数を呼び出すと、ノートブック自身のプロセス上でアタッチモードの ncu が開始され、関数が実行され、to_dataframe メソッドが注釈・構成・メトリクスごとに 1 行を持つ ProfileResults オブジェクトが返されます。列を表示して行を読み取ります。カーネル名、ナノ秒単位の測定値 gpu__time_duration.sum、実行回数、GPU 名とクロック属性を確認し、時間を手動で TFLOP/s に変換します。combine_kernel_metrics 引数は、cuBLAS が乗算を複数のカーネルに分割した場合に時間を合計します。実行が 1 回の場合、StableMeasurement フラグは未定義です。1 つのサンプルにはばらつきがないためです。
Copy Codedef show(df, cols, scale=None, fmt="{:,.2f}"):
out = df[cols].copy()
for c, f in (scale or {}).items():
out[c] = out[c] * f
print(textwrap.indent(out.to_string(index=False, float_format=lambda v: fmt.format(v)), " "))
@nsight.analyze.kernel(configs=[1 << 14, 1 << 24], runs=20, thermal_mode="off", verbosity=SILENT,
combine_kernel_metrics=ADD)
def noisy_or_not(n: int) -> None:
x = torch.randn(n, device="cuda")
y = torch.randn(n, device="cuda")
a = torch.randn(2048, 2048, device="cuda")
with nsight.annotate("vector add"):
_ = x + y
with nsight.annotate("matmul 2048"):
_ = a @ a
@section("3. How many runs? Spread, confidence intervals and the stability flag")
def stability():
df = noisy_or_not().to_dataframe()
print(" 20 runs per configuration; times in microseconds:\n")
show(df, ["Annotation", "n", "AvgValue", "StdDev", "CI95_Lower", "CI95_Upper", "RelativeStdDevPct",
"StableMeasurement"], scale={"AvgValue": 1e-3, "StdDev": 1e-3, "CI95_Lower": 1e-3, "CI95_Upper": 1e-3})
tiny = df[(df.Annotation == "vector add") & (df.n == 1 << 14)].iloc[0]
print(f"\n StableMeasurement is simply RelativeStdDevPct < 2. The smallest kernel ({tiny['AvgValue'] / 1e3:.1f} us)"
f" varies by {tiny['RelativeStdDevPct']:.1f}%:")
print(" at microsecond scale, launch and clock jitter are a large share of the time. Judge small kernels")
print(" with more runs, and compare their confidence intervals rather than single averages.")
return f"16K-element add RSD {tiny['RelativeStdDevPct']:.1f}%; " + \
f"2048 matmul RSD {df[df.Annotation == 'matmul 2048'].RelativeStdDevPct.max():.1f}%"
stability()
1 回の測定ではノイズについて何も分からないため、次のステップでは各構成を 20 回実行します。DataFrame には平均、標準偏差、95 パーセント信頼区間、パーセントで表した相対標準偏差、および StableMeasurement フラグが含まれ、ソースコードではこのフラグは単純に相対標準偏差が 2 パーセント未満であることを意味します。マイクロ秒で実行される 16,000 要素のベクトル加算と 16,000,000 要素のベクトル加算という 2 つのサイズ、さらにそれと並行して 2048 × 2048 の行列乗算をプロファイリングし、それぞれのばらつきの程度を比較します。実用的なルールは、短いカーネルほど多くの回数実行し、単一の平均値ではなく信頼区間を比較することです。
Copy Codedef make_scale_bench(cache_control, clock_control):
@nsight.analyze.kernel(configs=[1 << 18, 1 << 24], runs=10, cache_control=cache_control,
clock_control=clock_control, thermal_mode="off", verbosity=SILENT,
metrics=["gpu__time_duration.sum", "gpc__cycles_elapsed.avg.per_second"])
def scale(n: int) -> None:
x = torch.randn(n, device="cuda")
with nsight.annotate("x * 2"):
_ = x * 2.0
return scale
@section("4. Cache and clock control: two defaults that change the answer")
def cache_and_clocks():
rows = []
for cache in ("all", "none"):
for clock in ("none", "base"):
try:
df = make_scale_bench(cache, clock)().to_dataframe()
except Exception as e:
print(f" cache_control={cache!r}, clock_control={clock!r}: failed -> {type(e).__name__}: {str(e)[:120]}")
continue
t = df[df.Metric == "gpu__time_duration.sum"].set_index("n").AvgValue
hz = df[df.Metric == "gpc__cycles_elapsed.avg.per_second"].set_index("n").AvgValue
for n in t.index:
rows.append({"cache_control": cache, "clock_control": clock, "MB": 4 * n / 2 ** 20,
"time_us": t[n] / 1e3, "GB/s": 2 * 4 * n / t[n], "SM_MHz": hz[n] / 1e6})
tab = pd.DataFrame(rows)
print(textwrap.indent(tab.to_string(index=False, float_format=lambda v: f"{v:,.1f}"), " "))
print("\n The T4's L2 cache is 4 MB. A 1 MB input stays in L2 between runs unless caches are flushed,")
print(" so cache_control='none' measures a warm-cache kernel and 'all' (the default) a cold one.")
print(" clock_control='base' locks the SM clock to base frequency for every replay (the plain ncu CLI")
print(" default); nsight-python defaults to 'none', so the GPU boosts. SM_MHz is measured per kernel")
print(" (gpc__cycles_elapsed.avg.per_second). The ComputeClock column is not: it is the device's")
print(" rated clock attribute and stays the same whatever the kernel ran at.")
globals()["CLOCK_TABLE"] = tab
small = tab[tab.MB < 2].set_index(["cache_control", "clock_control"]).time_us
return (f"1 MB scale: cold/boost {small.get(('all', 'none'), float('nan')):.1f} us, "
f"warm/boost {small.get(('none', 'none'), float('nan')):.1f} us, "
f"cold/base {small.get(('all', 'base'), float('nan')):.1f} us")
cache_and_clocks()
プロファイラの 2 つのデフォルト設定が測定の意味を決定します。このステップでは、ベクトルを 2 倍にスケーリングする同じカーネルで両方を測定します。cache_control は、各カーネルリプレイの前にキャッシュをフラッシュするかどうかを決定します。Nsight Python はデフォルトでフラッシュするため、本来なら T4 の 4 MB L2 キャッシュに留まるはずの小さな入力でも、毎回メモリから読み込まれます。clock_control は GPU クロックを固定するかどうかを決定します。Nsight Python はデフォルトで固定しないままにしますが、素の ncu コマンドラインはベースクロックに固定します。1 MB と 64 MB で 4 通りの組み合わせをすべて実行し、さらにカーネルが実際に動作したクロックを測定する gpc__cycles_elapsed.avg.per_second も収集します。これは重要です。なぜなら、ソースコードが示すように、DataFrame の ComputeClock 列は測定値ではなくデバイスの定格クロック属性だからです。
Copy CodeSIZES = [(512,), (1024,), (2048,), (4096,)]
def tflops(time_ns: float, n: int) -> tuple[float, str]:
return 2 * n ** 3 / (time_ns * 1e-9) / 1e12, "TFLOP/s"
def make_precision_body():
def precision(n: int) -> None: # a fresh function object for each decorator
a = torch.randn(n, n, device="cuda")
b = torch.randn(n, n, device="cuda")
a16, b16 = a.half(), b.half()
with nsight.annotate("fp32"):
_ = a @ b
with nsight.annotate("fp16"):
_ = a16 @ b16
return precision
precision_tflops = nsight.analyze.kernel(configs=SIZES, runs=5, derive_metric=tflops, thermal_mode="off",
verbosity=SILENT, combine_kernel_metrics=ADD)(make_precision_body())
precision_ratio = nsight.analyze.kernel(configs=SIZES, runs=5, normalize_against="fp32", thermal_mode="off",
verbosity=SILENT, combine_kernel_metrics=ADD)(make_precision_body())
@section("5. A size sweep, a derived TFLOP/s metric, and normalisation")
def precision_sweep():
df = precision_tflops().to_dataframe()
tf = df[df.Metric == "tflops"].pivot(index="n", columns="Annotation", values="AvgValue")
print(" derive_metric=tflops receives (gpu__time_duration.sum, n) and returns (value, 'TFLOP/s'):\n")
print(textwrap.indent(tf[["fp32", "fp16"]].to_string(float_format=lambda v: f"{v:,.2f}"), " "))
print("\n T4 datasheet peaks: 8.1 TFLOP/s fp32, 65 TFLOP/s fp16 on tensor cores.")
rd = precision_ratio().to_dataframe()
fp16 = rd[rd.Annotation == "fp16"][["n", "AvgValue", "StdDev", "Unit", "Normalized"]]
print("\n normalize_against='fp32' divides each AvgValue by the fp32 AvgValue of the same configuration:\n")
print(textwrap.indent(fp16.to_string(index=False, float_format=lambda v: f"{v:,.3f}"), " "))
print("\n Read the row carefully: AvgValue is now a ratio (fp16 time / fp32 time), but StdDev and Unit are")
print(" still those of the raw nanosecond measurement, because only AvgValue is divided.")
best = tf.loc[4096]
return f"n=4096: fp32 {best['fp32']:.2f}, fp16 {best['fp16']:.2f} TFLOP/s"
precision_sweep()
次に、行列サイズを512から4096まで掃引し、1つのベンチマーク関数でfp32とfp16の両方を、精度ごとに1つのアノテーションを付けて実行します。derive_metric 関数は測定された時間と、その後にベンチマークの引数を受け取り、単位付きの値、ここではTFLOP/sを返し、DataFrameはこれを時間の隣の追加メトリックとして保存します。T4のデータシート上のピークは、fp32で8.1 TFLOP/s、テンソルコア上のfp16で65 TFLOP/sであり、これが測定値のスケールの目安となります。次に、normalize_against をfp32のアノテーションに設定して同じ掃引を実行すると、同じ構成のfp32の値ですべてのAvgValueが除算されます。変換のソースが示すように、除算されるのはAvgValueのみで、StdDev、信頼区間、Unit列は依然として生のナノ秒測定値を表しており、これは誤読しやすい点です。
コードをコピーBOUND_METRICS = ["gpu__time_duration.sum",
"sm__throughput.avg.pct_of_peak_sustained_elapsed",
"dram__throughput.avg.pct_of_peak_sustained_elapsed"]
@nsight.analyze.kernel(metrics=BOUND_METRICS, runs=3, thermal_mode="off", verbosity=SILENT)
def what_limits(n: int) -> None:
a = torch.randn(n, n, device="cuda").half()
x = torch.randn(64 * 2 ** 20, device="cuda")
s = torch.randn(8192, 1024, device="cuda")
with nsight.annotate("fp16 matmul 4096"):
_ = a @ a
with nsight.annotate("x * 2 (256 MB)"):
_ = x * 2.0
with nsight.annotate("softmax 8192x1024"):
_ = torch.softmax(s, dim=-1)
@section("6. Compute-bound or memory-bound? Three metrics from one replayed kernel")
def bound():
df = what_limits(4096).to_dataframe()
tab = df.pivot(index="Annotation", columns="Metric", values="AvgValue")
tab = tab.rename(columns={"gpu__time_duration.sum": "ms",
"sm__throughput.avg.pct_of_peak_sustained_elapsed": "SM % of peak",
"dram__throughput.avg.pct_of_peak_sustained_elapsed": "DRAM % of peak"})
tab["ms"] = tab["ms"] / 1e6
tab["limited by"] = np.where(tab["SM % of peak"] > tab["DRAM % of peak"], "compute", "memory")
print(textwrap.indent(tab.to_string(float_format=lambda v: f"{v:,.2f}"), " "))
x2 = tab.loc["x * 2 (256 MB)"]
gbs = 2 * 4 * 64 * 2 ** 20 / (x2["ms"] * 1e6)
print(f"\n Cross-check: x * 2 moves 2 x 256 MB in {x2['ms']:.2f} ms = {gbs:.0f} GB/s, against the T4's 320 GB/s")
print(f" datasheet peak ({100 * gbs / 320:.0f}%); Nsight Compute reports {x2['DRAM % of peak']:.0f}% DRAM throughput.")
print(" Collecting several metrics makes Nsight Compute replay each kernel once per pass it needs;")
print(" nsight-python still returns one row per annotation and metric.")
return f"x*2: {gbs:.0f} GB/s ({x2['DRAM % of peak']:.0f}% DRAM); fp16 matmul SM {tab.loc['fp16 matmul 4096', 'SM % of peak']:.0f}%"
bound()
ハードウェアカウンタは、カーネルがなぜそのだけの時間を要するのかを教えてくれます。メトリックのリストを渡すと、Nsight Computeはそれらをすべて収集するのに必要な回数だけ各カーネルをリプレイし、Nsight Pythonはアノテーションとメトリックの組み合わせごとに1行を返します。我々は、持続ピークに対する割合として、持続時間、SMスループット、DRAMスループットを、性格の異なる3つのカーネル、すなわちfp16の行列乗算、256 MBベクトルのスケーリング、8192行×1024値のsoftmaxについて収集し、それぞれをより高い方のスループットでラベル付けします。ベクトルのスケーリングについては、移動が必要なバイト数と測定時間から実効帯域幅も計算し、T4のデータシート上のピークである320 GB/s、およびNsight Computeが報告するDRAMの割合と比較します。
コードをコピーBYTES = ["gpu__time_duration.sum", "dram__bytes_read.sum", "dram__bytes_write.sum"]
@nsight.analyze.kernel(metrics=BYTES, runs=5, thermal_mode="off", verbosity=SILENT,
combine_kernel_metrics=lambda x, y: x + y)
def fusion(n: int) -> None:
a, b, c = (torch.randn(n, device="cuda") for _ in range(3))
with nsight.annotate("a + b * c (unfused)"):
_ = a + b * c
with nsight.annotate("torch.addcmul (fused)"):
_ = torch.addcmul(a, b, c)
@nsight.analyze.kernel(runs=1, thermal_mode="off", verbosity=SILENT)
def fusion_without_combine(n: int) -> None:
a, b, c = (torch.randn(n, device="cuda") for _ in range(3))
with nsight.annotate("a + b * c"):
_ = a + b * c
@section("7. Kernel fusion, measured in bytes: combine_kernel_metrics")
def fused():
n = 32 * 2 ** 20
try:
fusion_without_combine(n)
print(" (the unfused expression profiled without combine_kernel_metrics)")
except Exception as e:
print(f" Profiled without combine_kernel_metrics, the unfused expression raises:\n {type(e).__name__}: {str(e).splitlines()[0][:200]}\n")
df = fusion(n).to_dataframe()
tab = df.pivot(index="Annotation", columns="Metric", values="AvgValue")
tab = pd.DataFrame({"ms": tab["gpu__time_duration.sum"] / 1e6,
"MB read": tab["dram__bytes_read.sum"] / 2 ** 20,
"MB written": tab["dram__bytes_write.sum"] / 2 ** 20})
print(f" {n:,} float32 elements per tensor (128 MB each); metrics summed over the kernels in each region:\n")
print(textwrap.indent(tab.to_string(float_format=lambda v: f"{v:,.1f}"), " "))
u, f = tab.loc["a + b * c (unfused)"], tab.loc["torch.addcmul (fused)"]
print(f"\n The unfused version writes b * c to memory and reads it back: {u['MB read'] + u['MB written']:,.0f} MB of")
print(f" traffic against {f['MB read'] + f['MB written']:,.0f} MB, and {u['ms'] / f['ms']:.2f}x the time.")
return f"fusion: {u['ms'] / f['ms']:.2f}x faster, {(u['MB read'] + u['MB written']) / (f['MB read'] + f['MB written']):.2f}x less traffic"
fused()
カーネル融合は通常、時間の観点で説明されますが、ここではバイト数で測定します。eager PyTorchの式 a + b * c は、a を加算する前に b * c をメモリ上に実体化しますが、torch.addcmul は同じ結果を1つの操作で計算します。まず combine_kernel_metrics を使わずに非融合の式をプロファイリングして、アノテーション領域に複数のカーネルが含まれる場合にNsight Pythonが送出するエラーを示し、次に combine_kernel_metrics を使って各領域内のすべてのカーネルにわたって持続時間と読み書きされたDRAMバイト数を合計しながら、2^25（約33.5 million）個のfloat32要素のテンソルについて両バージョンをプロファイリングします。
コードをコピーimport pynvml
pynvml.nvmlInit()
NVML = pynvml.nvmlDeviceGetHandleByIndex(0)
@nsight.experimental.collect(scope=nsight.CollectionScope.ONCE)
def driver_version(*args):
return pynvml.nvmlSystemGetDriverVersion()
@nsight.experimental.collect(scope=nsight.CollectionScope.RUN)
def sm_clock_mhz(*args):
return pynvml.nvmlDeviceGetClockInfo(NVML, pynvml.NVML_CLOCK_SM)
@nsight.experimental.collect(scope=nsight.CollectionScope.RUN)
def gpu_temp_c(*args):
return pynvml.nvmlDeviceGetTemperature(NVML, pynvml.NVML_TEMPERATURE_GPU)
def make_heat_body():
def heat(n: int) -> None:
a = torch.randn(n, n, device="cuda").half()
with nsight.annotate("fp16 matmul"):
_ = a @ a
return heat
@section("8. Custom info collectors and thermal control (experimental API)")
def collectors():
out = {}
for mode in ("off", "auto"):
bench = nsight.analyze.kernel(configs=[4096], runs=30, thermal_mode=mode, thermal_timeout=60,
info_collectors=[driver_version, sm_clock_mhz, gpu_temp_c],
verbosity=SILENT, output_prefix=f"/content/nspy_thermal_{mode}/",
output_csv=True)(make_heat_body())
t0 = time.time()
try:
df = bench().to_dataframe()
except Exception as e:
print(f" thermal_mode={mode!r}: failed -> {type(e).__name__}: {str(e).splitlines()[0][:150]}")
continue
wall = time.time() - t0
csvs = sorted(glob.glob(f"/content/nspy_thermal_{mode}/profiled_data-*.csv"))
raw = pd.read_csv(csvs[-1]) if csvs else pd.DataFrame()
out[mode] = (df.iloc[0], wall, raw)
r = df.iloc[0]
print(f" thermal_mode={mode!r}: {r['AvgValue'] / 1e6:.3f} ms +/- {r['RelativeStdDevPct']:.1f}% "
f"wall {wall:.0f}s driver {r['driver_version']}")
print(f"\n The collectors became DataFrame columns; RUN-scoped ones were called before every run.")
if "off" not in out:
return "info-collector run failed"
raw = out["off"][2]
tcol = "Value" if "Value" in raw.columns else raw.columns[-1]
print(f" raw per-run CSV columns: {list(raw.columns)}")
if {"sm_clock_mhz", "gpu_temp_c"} <= set(raw.columns):
corr = raw[[tcol, "sm_clock_mhz", "gpu_temp_c"]].corr().iloc[0]
print(f" over 30 runs: SM clock {raw.sm_clock_mhz.min()}-{raw.sm_clock_mhz.max()} MHz, "
f"temperature {raw.gpu_temp_c.min()}-{raw.gpu_temp_c.max()} C")
print(f" correlation of kernel time with SM clock {corr['sm_clock_mhz']:+.2f}, with temperature {corr['gpu_temp_c']:+.2f}")
print("\n thermal_mode='auto' (the default) pauses between runs when the GPU's thermal headroom runs low;")
print(" the wall-time difference is the price of that, the spread difference what it buys.")
return "; ".join(f"{m} {out[m][0]['RelativeStdDevPct']:.1f}% RSD in {out[m][1]:.0f}s" for m in out)
collectors()
バージョン1.1では、結果にアプリケーション固有の値を添付するための実験的APIであるカスタム情報コレクタが追加されました。nsight.experimental.collect とコレクションスコープでデコレートされた関数は、セッション、構成、実行、またはアノテーションごとに1回呼び出され、その戻り値が列になります。我々はドライバのバージョンを1回記録し、長いfp16乗算の実行前にNVMLを通じてSMクロックとGPU温度を読み取り、output_csv を有効にして実行ごとの行が集約行の隣に書き込まれるようにします。サーマルコントロールを無効にした場合とデフォルトのautoモード、すなわちGPUのサーマルヘッドルームが低下したときにNsight Pythonが実行間で一時停止するモードでベンチマークを2回実行し、両者のばらつきと実時間（wall-clock time）を比較します。
コードをコピーCUPTI_SCRIPT = r'''
import os, json, time
os.environ["NSPY_NCU_INIT_AT_IMPORT"] = "0" # do not load Nsight Compute in this process
import nsight
nsight.activate(nsight.Tool.CUPTI)
import torch
@nsight.analyze.kernel(configs=[512, 1024, 2048, 4096], runs=10, thermal_mode="off",
verbosity=nsight.VerbosityLevel.SILENT, combine_kernel_metrics=lambda x, y: x + y)
def matmul(n):
a = torch.randn(n, n, device="cuda")
b = torch.randn(n, n, device="cuda")
with nsight.annotate("matmul"):
_ = a @ b
t0 = time.time()
df = matmul().to_dataframe()
wall = time.time() - t0
nsight.deactivate()
print(json.dumps({"wall": wall, "rows": df[["n", "AvgValue", "RelativeStdDevPct"]].to_dict("records")}))
'''
@nsight.analyze.kernel(configs=[512, 1024, 2048, 4096], runs=10, thermal_mode="off", verbosity=SILENT,
combine_kernel_metrics=ADD)
def matmul_ncu(n: int) -> None:
a = torch.randn(n, n, device="cuda")
b = torch.randn(n, n, device="cuda")
with nsight.annotate("matmul"):
_ = a @ b
@section("9. The experimental CUPTI backend, in its own process, against Nsight Compute")
def cupti_vs_ncu():
t0 = time.time()
ncu_df = matmul_ncu().to_dataframe().set_index("n")
ncu_wall = time.time() - t0
if not CUPTI_EXTRA:
return f"cupti-python could not be installed; Nsight Compute run took {ncu_wall:.0f}s"
with open("/content/cupti_matmul.py", "w") as f:
f.write(CUPTI_SCRIPT)
env = {k: v for k, v in os.environ.items() if k not in ("NVTX_INJECTION64_PATH", "NV_COMPUTE_PROFILER_PERFWORKS_DIR",
"NV_COMPUTE_PROFILER_IN_PROCESS")}
env["PYTHONPATH"] = CUPTI_DIR + os.pathsep + env.get("PYTHONPATH", "")
p = subprocess.run([sys.executable, "/content/cupti_matmul.py"], capture_output=True, text=True, env=env, timeout=900)
if p.returncode != 0:
print(f" CUPTI run failed (exit {p.returncode}); last lines of its stderr:")
print(textwrap.indent("\n".join(p.stderr.strip().splitlines()[-8:]), " "))
return f"CUPTI backend failed (exit {p.returncode}); Nsight Compute run took {ncu_wall:.0f}s"
res = next((json.loads(line) for line in reversed(p.stdout.strip().splitlines()) if line.startswith('{"wall"')), None)
if res is None:
return f"CUPTI run printed no result; Nsight Compute run took {ncu_wall:.0f}s"
cu = pd.DataFrame(res["rows"]).set_index("n")
print(f" {'n':>5s} {'ncu ms':>8s} {'cupti ms':>9s} {'ratio':>6s} {'ncu RSD%':>9s} {'cupti RSD%':>11s}")
for n in ncu_df.index:
a, b = ncu_df.loc[n, "AvgValue"] / 1e6, cu.loc[n, "AvgValue"] / 1e6
print(f" {n:5d} {a:8.3f} {b:9.3f} {b / a:6.2f} {ncu_df.loc[n, 'RelativeStdDevPct']:9.1f} {cu.loc[n, 'RelativeStdDevPct']:11.1f}")
print(f"\n wall time for 4 sizes x 10 runs: Nsight Compute {ncu_wall:.1f}s, CUPTI {res['wall']:.1f}s"
f" ({ncu_wall / res['wall']:.1f}x)")
print(" The two tools are mutually exclusive in one process and Nsight Compute cannot be unloaded, so")
print(" CUPTI runs in a child process with NSPY_NCU_INIT_AT_IMPORT=0. CUPTI records one execution per")
print(" launch, with no replay, no cache flush and no clock control: cheaper, and warmer caches.")
return f"CUPTI {ncu_wall / res['wall']:.1f}x faster to profile; durations within {abs(1 - cu.AvgValue.div(ncu_df.AvgValue)).max():.0%}"
cupti_vs_ncu()
CUPTIバックエンドは1.1のもう一つの目玉機能です。Nsight Computeを使わず、CUPTIのアクティビティAPIを通じて測定されたカーネルの持続時間です。2つのツールは単一のプロセス内で相互排他的です。Nsight Computeは一度有効化するとアンロードできないため、nsightをインポートする前に NSPY_NCU_INIT_AT_IMPORT を0に設定し、CUPTIツールを有効化し、同じ4つの行列サイズをプロファイリングして、パス上のcupti-pythonディレクトリを指定して子プロセスで実行する小さなスクリプトを作成します。CUPTIは持続時間メトリックのみをサポートし、リプレイ、キャッシュフラッシュ、クロック制御なしに1回の起動ごとに1回の実行を記録するため、Nsight Compute下の同じベンチマークと、持続時間とプロファイリングの実時間コストの両方を比較します。
コードをコピー@section("10. Keep the evidence: CSVs and the full Nsight Compute report")
def evidence():
files = sorted(glob.glob("/content/nspy_thermal_off/*"))
for f in files:
print(f" {os.path.basename(f):60s} {os.path.getsize(f) / 1024:9.1f} KB")
import ncu_report
rep_path = next((f for f in files if f.endswith(".ncu-rep")), None)
if rep_path is None:
raise RuntimeError("no .ncu-rep in /content/nspy_thermal_off/ (step 8 did not complete)")
rep = ncu_report.load_report(rep_path)
actions = [rep.range_by_idx(i).action_by_idx(j) for i in range(rep.num_ranges())
for j in range(rep.range_by_idx(i).num_actions())]
a0 = actions[0]
print(f"\n the .ncu-rep holds {len(actions)} profiled kernel launches; the first is")
print(f" {a0.name()}")
print(f" gpu__time_duration.sum = {a0['gpu__time_duration.sum'].value():,.0f} {a0['gpu__time_duration.sum'].unit()}")
print(f" {len(a0.metric_names())} metrics available in the report for this launch")
print("\n output_csv=True writes profiled_data (one row per run) and processed_data (the aggregated")
print(" DataFrame). The .ncu-rep opens in the Nsight Compute GUI for source-level analysis.")
return f"{len(actions)} launches in the report, {len(a0.metric_names())} metrics each"
evidence()
プロファイリングされた各呼び出しは証拠を残します。出力プレフィックスと output_csv を指定すると、ディレクトリにはNsight Computeのレポート、そのログ、実行ごとの profiled_data CSV、および集約された processed_data CSVが格納されます。我々はファイルを一覧表示し、Nsight ComputeのPythonレポートインターフェースである ncu_report でレポートを開きます。Nsight Python自身もこれを使用しています。このインターフェースはプロファイリングされたカーネル起動を一覧表示し、それぞれが収集されたすべてのメトリックを保持しています。同じ .ncu-rep ファイルは、ソースレベルの解析のためにNsight Computeインターフェースで開くこともできます。
コードをコピーbanner("SUMMARY")
for name, res in RESULTSitems():
print(f" {name:<76s} {res}")
print("""
What to carry over
- import nsight first; it loads Nsight Compute into the process before CUDA starts.
- Annotate exactly the work you mean to measure; one kernel per region unless you pass
combine_kernel_metrics.
- Decide cache and clock control on purpose: nsight-python flushes caches and leaves clocks
unlocked by default, which is not what a plain ncu run does.
- Use runs and the CI95 / RelativeStdDevPct columns; one run tells you nothing about noise.
- After normalize_against, only AvgValue is a ratio.
Where to go next
- Triton and cuTile kernels: examples/07_triton_minimal.py and examples/12_cutile.py.
- Plots: @nsight.analyze.plot(...) on top of @nsight.analyze.kernel, with row/col panels.
- Docs: docs.nvidia.com/nsight-python Code: github.com/NVIDIA/nsight-python
""")
まとめでは、各ステップの1行の結果と、守る価値のある習慣が出力されます。何かがCUDAを初期化する前に nsight をインポートすること、測定しようとする作業そのものだけをアノテートすること、キャッシュ制御とクロック制御を意図的に選択すること、十分な回数の実行を行い信頼区間を読むこと、そして正規化されるのはAvgValueだけであることを覚えておくことです。最後に、リポジトリ内のTritonとcuTileの例、およびプロット用デコレータへの参照が示されます。
結論として、Nsight Python はカーネルプロファイリングを独立したコマンドラインセッションから、測定対象のコード内の数行へと変えます。デコレータ、アノテーション、そして測定値・そのばらつき・そのコンテキストを運ぶ DataFrame です。Colab T4 でこれを試すと、この便利さの裏に数値を変えてしまう判断が隠れていることも分かります。プロファイラは Colab に同梱されているものより新しく、CUDA が起動する前にロードされていなければなりません。キャッシュフラッシュとクロック固定は、素の ncu 実行とは既定で逆の設定になります。クロックの列はカーネルが実際に動作したクロックではなくカードの定格を報告し、正規化は平均のみを割り算の対象とします。結合方法を指定しない限り、各アノテーション領域には正確に 1 個のカーネルが含まれていることが期待されます。これらの選択を明示してしまえば、同じ数行が実務上重要な問いに答えてくれます。測定がどれだけ安定しているか、カーネルの限界は何か、融合が実際にどれだけ節約するか、そして新しい CUPTI バックエンドのようなより安価なプロファイラが、低いオーバーヘッドと引き換えに何を諦めているのか。
チェックしてみてください: 全コードはこちら。本プロジェクトの研究者に全ての功績があります。また、ぜひ私たちをフォローしてください: Twitter そして、私たちへのご参加もお忘れなく 150k以上の ML SubReddit および登録する 当社のニュースレター。ちょっと待って!Telegramを使っていますか? 「telegramでもご一緒に参加できるようになりました。」
この投稿 NVIDIA Nsight Python チュートリアル：GPUカーネルをプロファイリングする方法 「appeared first on」→「最初に掲載されたのは」 MarkTechPost.