こんにちは、Qualiteg研究部です。

私たちは PII-FI という、個人識別情報や機密情報の検出とマスキングを行うツールを開発・提供しています。

あるとき、いくつかのGitHubのリポジトリをPII検査したところ、製品名や識別子に含まれる短い技術語を、組織名や社内用語として拾う誤検出が見つかりました。

数件の除外語を足せば、その画面だけは直せます。

しかし未知のリポジトリでは、別の技術語、issue番号、バージョン番号、識別子の断片へ誤検出先が移ります。

PII-FIのパイプライン処理の一部でNER（固有表現認識）を使用しているのですが、今回はNERの継続学習に関する技術記事となります。

当社では、これまで数年間をかけて構築した大規模コーパスを使い学習した強力なNERを扱っていますが、これを便宜上「強NER」と呼ぶことにして、本記事を執筆してまいりたいとおもいます。

さて、冒頭ご説明した誤検出について、私たちは、辞書による例外処理ではなく、強NERそのものを継続学習で直しました。

今回正式採用までに作成したNERモデルは100を超えます。目的の誤検出を0にできた候補は途中にもありましたが、既存文書の再現率や別の固有表現の種類を少しでも悪化させた候補は採用しませんでした。

本記事では、こうした　ポロポロ　とでてくる誤検出にたいして、学習済モデルをどのように進化させていくか、という点について私たちの実験で得られた知見を共有させていただければとおもいます。

結論から言うと、勝ち筋は「大きな学習を一度当てる」ことではありませんでした。
現行モデル自身から難しい負例（ハードネガティブ）を採掘し、未知表現の多様性と既存モデルが失いやすい弱い正例境界を別々に守り、残った数件だけを最小限の学習で修復し、最後に種類別の未正規化スコア（ロジット）を必要な幅だけ補正する。
この順序が、誤検出をなくしながら既存性能も上げる交点を作りました。

この記事では、モデル名、顧客データ、内部の学習文書そのものは公開せず、再利用できる学習設計、数式、失敗の読み方、採用ゲートを紹介します。

1. 最初に「合格」を数式で固定する

改善を始める前に、採用条件を固定しました。

全体F1が上がればよい、ではありません。

固有表現の種類を \(c\)、現行モデルを \(\mathrm{base}\)、新候補を \(\mathrm{new}\) とすると、製品評価では少なくとも次を満たすことを条件にしました。

$$\begin{aligned} \mathrm{TP}_{\mathrm{new}}(c) &\ge \mathrm{TP}_{\mathrm{base}}(c) \\ \mathrm{FP}_{\mathrm{new}}(c) &\le \mathrm{FP}_{\mathrm{base}}(c) \\ \mathrm{FN}_{\mathrm{new}}(c) &\le \mathrm{FN}_{\mathrm{base}}(c) \qquad \forall c \end{aligned}$$

ひとつの型でも正解を失えば不採用です。

目的の技術語で誤検出が0でも、別分野の人名を1件落とした候補は不採用にしました。この基準を後から緩めないことが重要です。

候補を長く追い込むほど、「ここまで良くなったのだから採用したい」という心理が働くからです。
（とくに１０回、２０回と学習を重ねると、なんかの値が多少さがっていても、他の値が圧倒的にのびていれば、「もーこれでいいじゃん」という悪魔のささやきに完全にまけそうになります）

適合率（Precision）、再現率（Recall）、F1も確認します。

$$\begin{aligned} P &= \frac{\mathrm{TP}}{\mathrm{TP}+\mathrm{FP}} \\ R &= \frac{\mathrm{TP}}{\mathrm{TP}+\mathrm{FN}} \\ F_1 &= \frac{2PR}{P+R} \end{aligned}$$

ただし、これらの集計値は最後の要約です。採否を決めるのは、種類別のTP、FP、FNと、実際に増減した検出範囲です。

図1　誤検出の発見から正式採用までの改善ループ

2. データを4区画に分け、見た評価は検証用と呼ぶ

最初に、実PIIを含まない合成技術文を用意しました。重要なのは件数より分離方法です。

重複を避ける対象は文書全文だけではありません。語彙、識別子の構成部品、接頭辞・接尾辞、文型テンプレートも分離しました。たとえば同じ語を別のテンプレートへ入れただけでは、語を暗記したモデルでも合格してしまいます。逆に単語を変えても識別子の部品や文型が同じなら、未知性を過大評価します。

各集合は件数とハッシュを固定しました。再生成のたびに内容が変わる評価では、候補間の差を学習効果として説明できません。

ここで大切なのは呼び方です。

追加検証用の結果を見て学習条件を変えた時点で、その集合は独立した最終テストではなく検証用です。固定回帰用も、最初の有望候補で開くまでは未開封でしたが、その後は複数候補の非劣化確認へ再利用しました。したがって、この記事では「最後まで未使用のテストで性能を保証した」とは書きません。100回超の適応的な探索で見た集合は、正直に開発・回帰用として扱います。

3. 選んだ単語ではなく、モデル自身の誤検出を採掘する

最初は、誤検出した技術語を負例として教えました。しかし、その単語を抑えると、同じ文のissue番号やバージョン番号、隣接する短い断片へ誤検出が移りました。

そこで、現行モデルを学習側に固定した合成技術文へ通し、対象の定義上は固有表現でないと生成規則または注釈で確認できた位置のうち、モデルが実際に固有表現と判定した検出範囲を採掘しました。開発用、追加検証用、固定回帰用の本文は採掘へ使っていません。難しい負例は、人が「難しそう」と選んだ語ではなく、現在の判定境界が実際に負けた位置です。

対象種類の未正規化スコアを \(z_e\)、固有表現ではないOのスコアを \(z_O\)、必要な余裕幅を \(m\) とすると、負例位置では次のような二者間のマージン損失を使えます。

$$\mathcal{L}_{\mathrm{neg}}=\max\!\left(0,\,m+z_e-z_O\right)$$

すでに \(z_O\) が十分高い負例には勾配を掛けず、誤検出している境界だけを必要な幅まで押し戻します。文書全体をOとして学習するより、変更範囲を狭くできます。

4. GitHub文書を丸ごとOにすると、正しい固有表現まで壊れる

大きな失敗のひとつは、技術文書の未注釈単位（token）をすべてOとして学習したことでした。学習内のスコアは高くなり、未知技術語の誤検出も大幅に減りました。しかし、別分野の実文書では、本来拾うべき社内固有語の再現率が落ちました。

理由はtoken数の偏りです。ひとつの文書には少数の訂正対象と大量の背景tokenがあります。背景をすべてOとして交差エントロピー損失へ入れると、今回直す必要のない位置までO方向へ押します。本件は新しい固有表現クラスを順に増やすclass-incremental NERそのものではありません。ただし、未注釈の固有表現までOとして学習すると既存の識別能力を壊し得る、という構造は継続NERの既往研究と共通しています。

訂正対象tokenの集合を \(M\) とすると、訂正箇所に限定した交差エントロピー損失は次のように書けます。

$$\mathcal{L}_{\mathrm{focused}} =-\frac{1}{|M|}\sum_{t\in M}\log p_{\theta}(y_t\mid x)$$

\(M\) 以外は単純なO正解として扱いません。損失計算から除外するか、旧モデルを教師モデルとして、その出力を保護します。

主要な失敗系統を比較する

5. 正例は「強くする」のではなく、2種類に分けて守る

負例だけを学習すると、本物の固有表現まで弱くなります。では正例を大量に反復すればよいかというと、これも失敗しました。正例の交差エントロピー損失を強くすると、未知の一般語まで固有表現側へ寄り、適合率が下がりました。

最終的に必要だった正例は、役割の違う2種類でした。

多様な合成正例だけでは、既存製品にある弱い境界を守れません。弱い境界だけでは、その文脈を覚えて未知表現へ広がりません。この2軸を同じ学習単位（バッチ）で負例と競合させたとき、未知正例と既存TPを同時に保てる候補が初めて現れました。

図2　負例修正と3種類の保護を釣り合わせる

6. 旧モデルは正解ラベルではなく、動かさない基準として使う

既存能力を守るため、現行モデルを教師モデルとして使いました。訂正対象以外のtoken集合を \(U\)、教師モデルと生徒モデルの未正規化スコアをそれぞれ \(z_t^T\)、\(z_t^S\) とすると、文脈安定化損失は次の形です。

$$\mathcal{L}_{\mathrm{KD}} =\frac{1}{|U|}\sum_{t\in U}\left\lVert z_t^S-z_t^T\right\rVert_2^2$$

または温度付きソフトマックスに対するKLダイバージェンスを使えます。重要なのは、分類器の既存行を凍結しただけでは既存種類を守れないことです。

LoRAでエンコーダーが変われば、固定した分類器へ入る表現も変わり、最終的な未正規化スコアは動きます。分類器の凍結と出力蒸留は別の保護です。

今回の全体損失は、概念的には次の組み合わせになりました。

$$\mathcal{L} =\mathcal{L}_{\mathrm{neg}} +\alpha\mathcal{L}_{\mathrm{pos}} +\beta\mathcal{L}_{\mathrm{KD}} +\gamma\mathcal{L}_{\mathrm{preserve}}$$

\(\mathcal{L}_{\mathrm{neg}}\)は誤検出境界の修正、\(\mathcal{L}_{\mathrm{pos}}\)は多様な合成正例と弱い正例境界に対する教師あり損失、\(\mathcal{L}_{\mathrm{KD}}\)は訂正箇所以外の出力維持、\(\mathcal{L}_{\mathrm{preserve}}\)は既存分野から固定したラベル付き保持データに対する教師あり損失です。

係数は大きいほど安全なのではありません。正例保護が強すぎれば誤検出が戻り、負例修正が強すぎれば再現率が落ちます。各損失値の桁は目安として確認し、最終的には開発用データのFP、FN、検出範囲の差分を見て、一方の目的だけが改善する設定を除外しました。

7. 一度に完成させず、残差だけを局所修復する

広い学習で誤検出を数件まで減らした後は、同じ規模の学習を繰り返しませんでした。

残った誤検出範囲と、新候補が失った正解範囲を差分で特定し、そのトークナイザーから見える文脈窓だけを使って小さく修復しました。

修復へ戻した本文は、学習用データと正式な学習源から再生成した開発用回帰窓に限定しました。固定回帰用データで見つかった本文を、そのまま学習へ戻してはいません。

ここでは「差し引きで改善している」だけでは足りません。種類ごとに改善と悪化を分けます。ある種類でTPが差し引き同数でも、別の正解を1件失い、新しい正解を1件得ている可能性があります。失った検出範囲を特定できれば、その1件だけを正例窓として残差負例と同時に学習できます。

学習率、学習ステップ数、正例損失の重みは小刻みに比較しました。残る誤検出の信頼度と検出範囲の長さも追います。誤検出が2文字から1文字へ縮み、Oとの余裕幅が0へ近づいているなら、改善方向へ動いている兆候とみなし、追加の小さな学習を試す材料にしました。逆に件数が同じでも信頼度が上がっていれば、その系統は打ち切れます。

最終候補へ近づいた局面では、数回の学習ステップの差、正例重みの小さな差が、未知正例の維持と最後の誤検出0を分けました。

100回超の探索で得たのは、大規模なハイパーパラメータ探索ではなく、
失敗差分を次の小実験へ変換する方法です。

8. 評価は軽い門から重い門へ進める

全候補へ製品全体の評価を実行すると、時間を浪費します。

前の門を通った候補だけ次へ進める漏斗にしました。

1. 目的の誤検出集合
   ↓
2. 学習と分離した追加検証用の未知正例
   ↓
3. 基本的な技術負例
   ↓
4. 大規模な負例耐性試験
   ↓
5. 開封後は再利用する固定回帰用データ
   ↓
6. 製品文書の型別TP・FP・FN
   ↓
7. 異分野の適合率・再現率
   ↓
8. 実際のランタイム契約
   ↓
9. 正式基準一式

目的集合で1件でも残る候補を重い評価へ進めません。

未知正例が基準未達なら負例耐性試験を回しません。製品評価では全体F1だけでなく種類別の検出範囲の差分まで保存します。ここに並べた門は、いずれも最終候補を選ぶための開発・回帰用です。不合格理由を次の学習データまたは損失設計へ戻したため、独立した最終テストとは区別します。

図3　候補を正式採用まで絞り込む評価漏斗

9. 最後は全種類一律ではなく、種類別スコアを最小幅だけ補正する

学習後の有望候補は、目的の技術誤検出と製品評価を通りましたが、別分野の適合率が合格線へわずかに届きませんでした。

Oの未正規化スコアを全種類に対して一律に上げると適合率は改善します。しかし、本物の未知固有表現までまとめて消えました。

そこで、誤検出が集中した2種類だけへ負方向のバイアスを加え、該当種類の未正規化スコアをわずかに下げました。

$$z'_c=z_c+b_c,\qquad b_c<0$$

これは特定単語の除外語リストではありません。同じ種類の全候補に作用します。

また、確率と正答率を合わせる通常の意味での「校正」ではなく、種類別のロジット補正です。補正幅は開発用の異分野評価で比較し、合格線を越える最小値を採用しました。その後、未知正例、固定回帰、製品の全種類、正式基準をすべて再実行しました。それ以上強い補正は、適合率が上がっても本物を余計に落とすため捨てました。

10. 最終結果と、成功の決め手

正式候補は、固定したGitHub技術語評価、追加検証用の未知正例、基本負例、大規模な負例耐性試験、固定回帰用データを通過しました。

製品評価でも、旧モデルに対して正解が増え、同一の固定製品回帰データ上で誤検出が約400件減り、見逃しも減りました。

主要な固有表現の種類を含め、種類別TP・FP・FNの悪化は0でした。

ここでいう誤検出0は、固定した評価集合上の実測値であり、あらゆる未知リポジトリで誤検出が起きないという意味ではありません。

成功をひとつの手法へ要約するなら、LoRAでも蒸留でもマージン損失でもありません。

次の組み合わせです。

1. モデル自身の誤検出を難しい負例にする
2. 未注釈tokenを安易にOへ落とさない
3. 未知表現の多様性と、既存の弱い正例境界を別々に守る
4. 旧モデルを教師モデルとして訂正箇所以外の出力を固定する
5. 残差だけを最小限の学習で修復する
6. 最後は誤差が集中した種類だけを最小幅で補正する
7. 全体F1ではなく全型のTP・FP・FNで採用する

今回、強NERの主要な改善は100回超の学習を経て実現し、新しいモデル成果物として正式採用しました。

まとめ

最後に、学習を成功させるための重要な論点を質問形式でまとめて書いておきます

• 学習用、開発用、追加検証用、固定回帰用の役割を分けたか
• 語彙だけでなく識別子部品と文型も分離したか
• モデル自身の誤検出範囲を採掘したか
• 未注釈tokenを全部Oとして学習していないか
• 正例の多様性と弱い境界を両方保護したか
• 分類器を凍結しただけで旧型を守ったつもりになっていないか
• 候補ごとの改善と悪化を検出範囲単位で保存したか
• 軽い門を通った候補だけ重い製品評価へ進めたか
• 全体F1の改善で型別劣化を隠していないか
• 種類別スコア補正は合格線を越える最小幅で止めたか

NERの継続学習では、目的データのスコアを上げることより、どの能力を動かさないかを測れることのほうが難しいものです。

100回超の失敗を候補名の列で終わらせず、誤検出の移動、信頼度の変化、失った検出範囲、種類別の改善と悪化を次の小実験へ変換する。

そこまで設計して、初めて改善作業が再現可能になるということが、実体験を経て理解できました。

以前の記事「モデルを「壊さずに」ドメインを広げる　XLM-RoBERTa継続学習の設計ノート」では、追加学習で動かす範囲を限定する考え方を紹介しました。

今回は、その限定学習でも一度では合格できなかったとき、データと評価をどう組み直したかという続編です。

それでは、また次回お会いしましょう！

出典・参考

• Continual Named Entity Recognition without Catastrophic Forgetting（EMNLP 2023）
• Learning “O” Helps for Learning More: Handling the Unlabeled Entity Problem for Class-incremental NER（ACL 2023）

関連記事

• モデルを「壊さずに」ドメインを広げる　XLM-RoBERTa継続学習の設計ノート
• PII非識別化の設計原則

こんにちは！

「TensorRT 10 × Blackwell 移行ガイド」シリーズもいよいよ最終回です。前編では TensorRT 化の基本と「5D（volumetric）の grid_sample はビルドが拒否される」という壁を、中編では「ビルドが通っても正しいとは限らない」沈黙劣化の数々を扱いました。

後編は、前編で保留にした最大の宿題に挑みます。TensorRT がネイティブに対応していない 5D grid_sample を、カスタムプラグインで通す話です。ゴールは明確で、前編でこのエラーを出したのと同じモデル・同じ入力から export した ONNX を、5D の GridSample ノードだけプラグイン用ノードへ置き換えて、最後までビルド・実行することです。

INetworkDefinition::addGridSample: Error Code 3: API Usage Error
(Parameter check failed, condition: input.getDimensions().nbDims == 4. ...)

先に結論を言うと、通りました。PyTorch の F.grid_sample（5D）と最大絶対誤差 7.2e-07 で一致するエンジンができています。ただしそこまでの道には、Blackwell 世代ならではの壁がいくつも立っています。本記事ではその壁と越え方を、実機ログつきで順に共有します。

この記事の対象環境 WSL2 Ubuntu 24.04 ／ NVIDIA RTX PRO 4000 Blackwell・GeForce RTX 5060 Ti（ともに Compute Capability 12.0 = sm_120）／ PyTorch 2.11.0 + cu128 ／ TensorRT 10.16.1.11 ／ システム nvcc は CUDA 12.0（あえて古いまま使います。理由は本文で）。 題材のプラグインは OSS の grid-sample3d-trt-plugin（Apache License 2.0）です。リポジトリに正式リリースは無いため、本記事で使用したコミット（f964750）を明記しておきます。改変版のソースや .so を再配布する場合は、同ライセンスの条件（ライセンス文・著作権表示の同梱など）に従ってください。本記事のコード・ログ・数値はすべて実機の実測です。

第1部: プラグインという仕組み — TensorRT は「知らない op」をどう扱うか

前編で見たとおり、TensorRT の ONNX parser は、GridSample ノードの入力が 5 次元だとその場でビルドを拒否します。ネイティブ実装が存在しないからです。

こういうときのための正式な拡張機構がカスタムプラグインです。仕組みはこうなっています。

1. 演算の CUDA カーネルと、TensorRT へのアダプタ（プラグインクラス）を C++ で書き、共有ライブラリ（.so）にする
2. プロセス起動時にその .so をロードすると、プラグインが TensorRT の plugin registry に登録される
3. ONNX parser は、知らない op_type に出会うと plugin registry を検索し、同名のプラグインが見つかればそれをレイヤとして組み込む

つまりやることは 2 つです。(a) 5D grid_sample のプラグインを Blackwell で動く形にビルドする。(b) ONNX の GridSample ノードを、プラグインの op 名に張り替える。

幸い、(a) のカーネルをゼロから書く必要はありません。TensorRT 8 の時代から使われてきた OSS 実装 grid-sample3d-trt-plugin があり、5D grid_sample の CUDA カーネルとプラグインクラスが揃っています。問題は、これを TensorRT 10 × Blackwell の環境でビルドし直すところに集中しています。

第2部: ビルドの壁 3 連発

まず、プラグイン本体を本記事と同じソースで取得しておきます。

git clone https://github.com/SeanWangJS/grid-sample3d-trt-plugin.git
cd grid-sample3d-trt-plugin
git checkout f964750

壁その 1: pip で入れた TensorRT には、開発用ヘッダが入っていない

プラグインのビルドには TensorRT の C++ ヘッダ（NvInfer.h など）とリンク用の libnvinfer.so が必要です。ところが、pip の tensorrt-cu12 パッケージに入っているのは実行用の .so だけで、ヘッダは一切含まれていません。

NVIDIA が案内する正規の方法は、tar / Debian / RPM などヘッダを含む配布形態を使うことです。以下は「pip 環境を二重化したくない」場合に当社環境で実証した回避策、という位置づけで読んでください。NVIDIA/TensorRT の OSS リポジトリから、pip 版とバージョンの合う公開ヘッダだけを取ってくる方法です。

# ヘッダ: OSS リポの対応タグ（v10.16）を blob:none で軽量 clone
git clone --depth 1 --branch v10.16 --filter=blob:none \
    https://github.com/NVIDIA/TensorRT.git ~/trt_headers
# → 使うのは ~/trt_headers/include/ だけ

# リンク用 lib: pip が入れた実行用 .so へ symlink を張る
#（リンカは -lnvinfer で libnvinfer.so を探すので、バージョン付きの実体へ繋ぐ）
# .so の場所は環境ごとに違うので、Python に聞くのが確実
TRT_LIB_DIR="$(python -c "import pathlib, tensorrt_libs; print(pathlib.Path(tensorrt_libs.__file__).parent)")"
mkdir -p ~/trt_link
ln -sf "$TRT_LIB_DIR/libnvinfer.so.10" ~/trt_link/libnvinfer.so

TensorRT の公開 API・ABI はセマンティックバージョニングに従うため、v10.16 タグのヘッダと pip の 10.16.1.11 という近接した組み合わせは理にかなっており、実機でビルド・動作を確認しました（異なる minor 系列を混ぜる場合、特に新しいヘッダの API を古いライブラリへリンクする向きは成立しない可能性があるので、実際の組み合わせで確認してください）。

もうひとつ、元リポジトリの CMakeLists.txt は、この 2 つの場所をそのままでは参照してくれません。次の変更を入れて、外から渡せるようにします（CUDA_ARCHITECTURES の行は次の壁で説明します）。

# 追加: 外部から渡した TensorRT のヘッダ・lib を使う
target_include_directories(${PROJECT_NAME} PRIVATE
    "./src" ${CUDAToolkit_INCLUDE_DIRS} ${TensorRT_INCLUDE_DIR})
target_link_directories(${PROJECT_NAME} PRIVATE ${TensorRT_LIB_DIR})
target_link_libraries(${PROJECT_NAME} PRIVATE nvinfer CUDA::cudart)

ビルドコマンドはこうです。

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release \
  -DTensorRT_INCLUDE_DIR="$HOME/trt_headers/include" \
  -DTensorRT_LIB_DIR="$HOME/trt_link"
cmake --build . --parallel

壁その 2: 手元の nvcc が Blackwell を知らない

次の壁が本記事の山場です。プラグインの CUDA カーネルをコンパイルしようとすると、こういう状況に直面します。

• Blackwell（sm_120）向けのネイティブコードを吐けるのは CUDA 12.8 以降の nvcc
• ところが手元のシステム nvcc は CUDA 12.0（nvcc --list-gpu-arch の上限が compute_90）
• CUDA toolkit を入れ替えれば解決するが、既存環境への影響が大きい

ここで効くのが、PTX の forward compatibility（前方互換） です。CUDA のコンパイルには 2 段階あります。nvcc がソースを PTX（仮想アーキテクチャ向けの中間表現）へ落とす段階と、PTX を実 GPU 向けのネイティブコード（SASS）へ落とす段階です。後者は GPU ドライバが実行時に JIT コンパイルすることもできます。

つまり、「nvcc では compute_90 の PTX までを作り、sm_120 への最終変換は Blackwell 対応済みのドライバに任せる」という分担にすれば、古い nvcc のままでもビルドできます。CMake ではこう書きます。

# compute_90 の PTX のみを埋め込む（"90" だと SASS も作ろうとして失敗する）。
# 実行時に driver が PTX → sm_120 へ JIT コンパイルする
set_target_properties(${PROJECT_NAME} PROPERTIES CUDA_ARCHITECTURES "90-virtual")

ビルドした .so に本当に PTX しか入っていないことは、cuobjdump で確認できます。

$ cuobjdump libgrid_sample_3d_plugin.so | grep -E "arch|Fatbin" | sort | uniq -c
      1 Fatbin ptx code:
      1 arch = sm_90

ネイティブコード（Fatbin elf code）の行がなく、PTX が 1 本だけ。この状態で sm_120 の GPU にロードすると、ドライバが JIT コンパイルして動きます（後述の数値照合が通っていることが、JIT が正しく機能した証明になります）。初回実行時には PTX の JIT コンパイル時間が発生します（本記事ではその時間は計測していません）。

余談ですが、JIT の検証手段として CUDA_FORCE_PTX_JIT=1（全カーネルを PTX からの JIT に強制する環境変数）も知られています。ただし当環境で試したところ、プロセス全体に効くため、SASS しか持たないカーネルを含む PyTorch 側が no kernel image is available で先に落ちました。PyTorch と同居するスクリプトでは使えないので、プラグイン単体の確認は上記の cuobjdump と数値照合で行うのが実務的です。

壁その 3: deprecated 警告の山

ビルドログには、IPluginV2DynamicExt 系 API への deprecated 警告が並びます。この API は TensorRT 10.0 で deprecated になっており、新規実装には V3 系が推奨されています。本記事の TensorRT 10.16.1.11 では警告止まりで、実際にビルド・実行できました。ただし TensorRT 11 では V2 系プラグイン API 自体が削除されているため、このプラグインをそのまま 11 系へ持っていくことはできません。今回は OSS 実装を無改変で活かす方針なので、警告は許容して先へ進みます（新規にプラグインを書き起こすなら V3 系 API を使ってください）。

ここまでの 3 つの壁を整理すると、次のとおりです。

第3部: ONNX ノードを張り替えて、ビルドを通す

プラグインができたら、次は (b) の張り替えです。前編で使った 5D のダミーモデル VolumetricWarp を、まったく同じように export します。

class VolumetricWarp(nn.Module):
    """5D（volumetric）grid_sample を含む最小モジュール（前編と同じ）"""
    def forward(self, vol, grid):
        return F.grid_sample(vol, grid, align_corners=False)

torch.manual_seed(0)
vol = torch.randn(1, 32, 16, 64, 64, device="cuda")
grid = torch.rand(1, 16, 64, 64, 3, device="cuda") * 2 - 1
model = VolumetricWarp().eval().cuda()

torch.onnx.export(model, (vol, grid), "vol_warp.onnx",
                  input_names=["vol", "grid"], output_names=["y"],
                  opset_version=20, dynamo=True)

この ONNX の GridSample ノードを、プラグインの op 名 GridSample3D へ張り替えます。属性もプラグインが期待する形式（int 型 3 つ）に置き換えます。

import onnx
from onnx import helper

def swap_gridsample(src_onnx, dst_onnx):
    """ONNX の GridSample(5D) ノードをプラグイン op『GridSample3D』へ張り替える"""
    m = onnx.load(src_onnx, load_external_data=False)
    n = 0
    for node in m.graph.node:
        if node.op_type != "GridSample":
            continue
        ins, outs, name = list(node.input), list(node.output), node.name
        del node.attribute[:]
        node.op_type = "GridSample3D"
        node.domain = ""      # 非標準 op → parser が plugin registry を検索しにいく
        node.attribute.extend([
            helper.make_attribute("interpolation_mode", 0),   # 0 = linear
            helper.make_attribute("padding_mode", 0),         # 0 = zeros
            helper.make_attribute("align_corners", 0),        # 0 = False
        ])
        del node.input[:]
        node.input.extend(ins)
        del node.output[:]
        node.output.extend(outs)
        node.name = name
        n += 1
    onnx.save(m, dst_onnx)
    return n

なお、この swap_gridsample はグラフ内のすべての GridSample を無条件に置き換えます。本記事のダミーは「5D の GridSample が 1 個だけ」という前提なので、それを検査してから使います（4D と 5D が混在する実モデルで使う場合は、shape 推論で入力の次元数を確認するか、対象ノード名を指定できるようにしてください）。

count = swap_gridsample("vol_warp.onnx", "vol_warp_plugin.onnx")
if count != 1:
    raise RuntimeError(f"expected exactly one GridSample node, found {count}")

もうひとつ、プラグインのロードには重要な注意があります。本記事の構成では、プラグインの共有ライブラリを plan へシリアライズしていないため（TensorRT には version-compatible engine へプラグインを同梱する仕組みもありますが、今回は使っていません）、.so のロードはビルド時だけでなく、保存済みエンジンを別プロセスで deserialize する前にも必要です。共通のロード関数を作っておきます。

import ctypes
from pathlib import Path

_PLUGIN_HANDLES = []   # GC でアンロードされないよう、プロセス中は参照を保持する

def load_grid_sample_plugin(plugin_path):
    # プラグイン .so を RTLD_GLOBAL でロードする。ロードの副作用（ライブラリ内の
    # 登録処理）で、プラグインが TensorRT の plugin registry に登録される。
    # ビルド前と deserialize 前の両方で呼ぶこと
    handle = ctypes.CDLL(str(Path(plugin_path).resolve()), mode=ctypes.RTLD_GLOBAL)
    _PLUGIN_HANDLES.append(handle)

ビルド側はこうなります。GridSample3D を registry に登録しているのは上のロード処理で、init_libnvinfer_plugins は NVIDIA 標準プラグイン群の初期化 API です（今回のカスタムプラグインの登録主体ではありません）。

import tensorrt as trt

def build_engine_with_plugin(onnx_path, engine_path, fp16=False):
    load_grid_sample_plugin("./libgrid_sample_3d_plugin.so")
    trt.init_libnvinfer_plugins(TRT_LOGGER, "")   # NVIDIA 標準プラグインの初期化（念のため）

    builder = trt.Builder(TRT_LOGGER)
    network = builder.create_network(1 << int(trt.NetworkDefinitionCreationFlag.EXPLICIT_BATCH))
    parser = trt.OnnxParser(network, TRT_LOGGER)
    if not parser.parse_from_file(onnx_path):
        errs = [str(parser.get_error(i)) for i in range(parser.num_errors)]
        raise RuntimeError("ONNX parse failed:\n" + "\n".join(errs))
    config = builder.create_builder_config()
    config.set_memory_pool_limit(trt.MemoryPoolType.WORKSPACE, 2 << 30)
    if fp16:
        config.set_flag(trt.BuilderFlag.FP16)
    plan = builder.build_serialized_network(network, config)
    if plan is None:
        raise RuntimeError("build failed")
    with open(engine_path, "wb") as f:
        f.write(plan)
    return engine_path

関数を定義したら、張り替え済みの ONNX からエンジンを作ります。

build_engine_with_plugin("vol_warp_plugin.onnx", "vol_warp_plugin.plan", fp16=False)

実行側（保存済みエンジンを使うプロセス）では、deserialize の前にロードします。

load_grid_sample_plugin("./libgrid_sample_3d_plugin.so")
runner = TRTRunner("vol_warp_plugin.plan")   # deserialize はロードの後

そして——前編で拒否されたのと同じ計算グラフ（プラグインノードへの置き換えのみ）のビルドが通ります。実行して、PyTorch の F.grid_sample（5D）と突き合わせた結果がこちらです（照合の作法は前編・中編のとおり、export に使った同じモデル・同じ入力・fp32 基準です）。

計測条件: GeForce RTX 5060 Ti ／ 固定形状 [1,32,16,64,64]・batch=1 ／ 両者とも fp32 ／ ウォームアップ 30 回・計測 200 回・CUDA Event の median ／ TensorRT 側は入出力バッファを事前確保し enqueue 区間のみ ／ 1 回のビルドでの結果です。約 15% の差はモデルや GPU で容易に変わるので、「当環境のこの単体演算ではこうだった」として読んでください。

fp32 基準に対して非常に小さい誤差に収まりました。compute_90 の PTX を Blackwell のドライバが JIT した結果としてこの数値が出ている、というのが本記事の要点です。速度は単体ではわずかに速い程度ですが、本当の価値は「これまで PyTorch に残すしかなかった 5D grid_sample 入りのモジュールを、まるごと 1 個の TensorRT エンジンにできる」ことにあります。torch と TensorRT の境界そのものが消えるからです。

第4部: 中編の教訓をここでも — fp16 を受理する構成を検証する

さて、ここで終わると中編の教訓が泣きます。「ビルドが通っても、正しいとは限らない」 —— プラグインにも同じ検証を通します。

この OSS プラグインは fp16 カーネルも実装しており、supportsFormatCombination（TensorRT に「この精度・形式を受け入れるか」を答えるメソッド）は fp32 と fp16 の両方を受理する実装になっています。そこで、fp16 を受理する元実装のままの .so を別にビルドし、FP16 tactic を許可してエンジンを作って実測しました（プラグイン内部で実際に fp16 経路が選ばれたことのログ確認まではしていないため、正確には「fp16 を受理する構成のエンジン」の結果です）。

fp16 を受理する構成では、fp32 比で誤差が 5 桁悪化しました。nRMSE 2.1% は単一演算の fp16 丸め単位より大幅に大きく、少なくとも本用途では許容できない水準です（補間では座標の量子化・重み計算・積和などで誤差が増幅し得ますが、どの処理で増幅しているかまでは特定していません）。さらに私たちが実務モデルの内部で fp16 を受理する構成を使った際には、出力が数百のオーダーでずれる完全な数値破綻も経験しています（入力の分布次第で被害は大きく変わります。これも「乱数入力の結果を信用するな」の一例です）。

対処 — プラグイン側で fp16 を「受理しない」

対処はシンプルで、プラグインの supportsFormatCombination から fp16 の受理を外し、fp32 専用にすることです。

bool GridSample3DPlugin::supportsFormatCombination(int32_t pos,
                                                   PluginTensorDesc const* inOut,
                                                   int32_t nbInputs,
                                                   int32_t nbOutputs) noexcept {
    assert(nbInputs == 2 && nbOutputs == 1 && pos < (nbInputs + nbOutputs));
    bool condition = inOut[pos].format == TensorFormat::kLINEAR;
    // fp32-only: fp16 を受理する構成で許容できない誤差を観測したため kHALF を受理しない。
    // FP16 tactic を許可したエンジン内でも、TensorRT が本レイヤの前後に
    // reformat（型変換）を自動挿入し、この演算だけ fp32 で実行してくれる
    condition &= inOut[pos].type == DataType::kFLOAT;
    condition &= inOut[pos].type == inOut[0].type;
    return condition;
}

ここが面白いところで、こうしてもエンジン全体を fp32 にする必要はありません。FP16 tactic を許可してビルドすると、TensorRT はプラグインの申告を見て、このレイヤの前後にだけ型変換（reformat）を自動で挿入できます。結果として「grid_sample は fp32、周辺のレイヤは fp16 候補から選択」という構成が 1 個のエンジンの中で成立し得ます。ただし reformat のコストや、実際に選ばれた精度・エンジン全体の数値は、完成したエンジンで改めて検証してください（前編・中編で書いたとおり、「許可した」と「実際に使われた」は別物です）。

まだ確かめていないこと

• fp16 を受理する構成での誤差の根本原因 — プラグイン内部で実際に fp16 経路が選ばれたことのログ確認、および誤差がどの処理で増幅しているかの特定はしていません（本記事は「検証して、危なければ受理しない」という運用側の対処に留めています）
• JIT コンパイルの初回コスト — 初回ロード時の JIT 時間は計測していません。デプロイ形態によっては起動時間に効く可能性があります
• 新世代プラグイン API（V3 系）への移行 — 本記事は旧 API（IPluginV2DynamicExt）のまま動かしています。TensorRT の将来のメジャーバージョンでは旧 API が削除される可能性があります
• 可変形状（dynamic shape）での動作 — 本記事の検証はすべて固定形状です

まとめ — シリーズを締めて

後編の要点です。

1. TensorRT が知らない演算は、カスタムプラグイン + ONNX ノードの張り替えで通せる
2. pip の TensorRT にはヘッダが無い → OSS リポの対応タグから include を取り、lib は pip の .so へ symlink
3. nvcc が新しい GPU を知らなくても、PTX（仮想アーキテクチャ）でビルドして driver の JIT に任せる手がある（CUDA_ARCHITECTURES "90-virtual"）
4. プラグインにも中編の検証をそのまま適用する。許容できない誤差が出る型は supportsFormatCombination で受理対象から外す。TensorRT が reformat を自動挿入できるので、周辺は fp16 候補を残したまま該当演算だけ守れる（実際に選ばれた精度と数値は完成エンジンで確認する）

シリーズ 3 本を通して伝えたかったことを一言でまとめると、「TensorRT 化は『変換して速くなったら終わり』ではなく、export・ビルド・実行・数値のすべてを実測で確かめて初めて完成する」ということです。Blackwell という新しい世代はその検証の重要性を一段引き上げましたが、本シリーズの手順とチェックリストがそのまま皆さまの移行作業の地図になれば幸いです。

それでは、また次回、お会いしましょう！

参考資料（一次情報・主要ソース）

• SeanWangJS/grid-sample3d-trt-plugin（5D grid_sample プラグインの OSS 実装・Apache-2.0。使用コミット f964750）
• NVIDIA/TensorRT（OSS リポジトリ・公開ヘッダの取得元）
• NVIDIA TensorRT ドキュメント（プラグイン / Developer Guide）
• CUDA C++ Programming Guide: PTX と JIT コンパイル（forward compatibility）
• NVIDIA/TensorRT issue #3890: 5D GridSample のネイティブ対応要望
• 当社関連記事: 前編 / 中編 / 2026年 NVIDIA GPU 一発検索ツール

こんにちは！
Qualitegプロダクト開発部です！

本日はLuckfox Pico Mという4000円弱の小さなLinuxボードをインターネット越しに操作できるようにしてみました。NAT越えの仕組みは無料プランのWireCanalを使いました。

先日、秋葉原の千石電商さんでLuckfox Pico M を税込3,750円で入手しました。

Raspberry Pi Picoとほぼ同じ大きさで、ピンヘッダ実装済み、CPUはRockchip RV1103（ARM Cortex-A7 1.2GHz）、メモリは64MB、起動はmicroSDカードからです。

Linuxが動くのに、この値段とこの大きさです。

これを外出先（インターネット越しに）から使えるようにしていきます。

ボードにはRJ45のコネクタ（いわゆるLAN端子）もWi-Fiもなく、あるのはUSB-Cのポートだけ。

それでもインターネット側から届く形にして、スマホから叩いてみます。
さて、できるのでしょうか？

先に結果を言うと、できました。

ボード側にWeb公開用の受信ポートを追加せず、WireCanalの無料プラン（0円）だけで、公開URLからLuckfox上のWebサーバーがそのまま見えるところまで行けました。

さらに今回は、ボードに挿したLED 1本を、公開ページのボタンでインターネット越しに点けたり消したりできるようにしました。

再起動しても、実測33秒で公開URLが自動で復活します。

ただし、Pico M自身にはWi-FiもRJ45もないため、今回はUSB接続したWindows PCをインターネットへのゲートウェイとして使います。
（今後はイーサつきLuckFoxでの実験記事も投稿予定です！）

なので、今回は、外出先からアクセスするときも、このPCは起動している必要があります。

この記事では、SDカードへのイメージ書き込みから、起動、ネットワーク、LEDの配線、WireCanalでの公開、再起動しても復活する常駐設定まで、実際にやった手順と実測値を最初から最後まで書きます。

対象はLuckfox Pico M（無印Luckfox Picoのピンヘッダ実装版）と公式のBuildrootイメージ、作業PCはWindows 11です。WireCanalは当社が開発・運営している自社サービスで、記事中の数値は2026年8月19日時点の実測値です。

Luckfox Pico Mとはどんなボードか

LuckfoxはRockchipのビジョン向けSoC（RV1103／RV1106）を載せた小型Linuxボードのシリーズで、Pico Mはその入門機です。今回の実機で確認した中身は次のとおりでした。

Raspberry Piと違って、有線LANもWi-Fiも「そのままでは」使えません。

そこで今回は、PCとUSB-Cで繋いで仮想的なネットワークアダプタ（RNDIS）を生やして、PCとボードの間だけの小さなネットワークができるというしかけで使います。

MagJackとよばれるトランス入りのRJ45ジャック（いわゆるLAN端子）を自分で結線すればLANケーブルをつなぐことができますが少々手間がかかります。

また、そもそもRJ45ジャックつきのLuckFox製品もありますので直接LANケーブルでつなぎたい場合はそちらを使うこともできます（別記事として投稿予定です）

さて、今回はPCのインターネットをもらいにいく方法で実験しますので、外に出るにはPC側でひと工夫が要ります（手順3）。

もうひとつの特徴は、メモリの小ささです。

Linuxから見えるのは33MB。

ここにWireCanalの常駐エージェントを載せて実用になるのか、というのが今回の見どころのひとつです。

材料

WireCanalの無料プランは、canal（公開URLと転送先の組）が1本、公開アドレスはおまかせのランダムなサブドメインです。

作ったcanalはAgentを使っている限り消えず、Agentの最終接続から72時間で失効します。今回のように常駐で動かし続けるならURLは維持されます。

手順1: microSDカードにBuildrootイメージを書き込む

まず、必要なファイルとツールを集めます。入手先はすべて公式で、Luckfox Wikiの書き込み手順ページ（Flash Image）に、ツールとイメージへのリンクがまとまっています。ダウンロードするのは次の3つです。

OSイメージのzipを展開すると、次のファイルが出てきます。

env.img  idblock.img  uboot.img  boot.img  oem.img  userdata.img  rootfs.img
update.img  download.bin  sd_update.txt  tftp_update.txt

最初にSD Card Formatterでカードをフォーマットします。インストールして起動すると、カードのドライブが「カードの選択」に出るので、それが本当にSDカードか（容量・ドライブレター）を確認して、クイックフォーマットのまま「フォーマット」を押します。別のUSBドライブを挿している人は、ここの選び間違いにだけ注意してください。

次にSocToolKitです。zipを展開し、SocToolKit.exeを右クリックから「管理者として実行」で起動します（管理者で起動しないとSDカードを認識しないことがある、と公式手順にも書かれています）。最初にChip Selectionダイアログが出るので、RV1103を選んでOKを押します。

公式手順ではRV1106を選択するよう案内されていますが、今回は実機のSoCに合わせてRV1103を選択しました。この選択のまま、7つのイメージの書き込み完了（Create sdcard OK）からPico Mの実機起動まで確認しています。

「SDTool」タブに切り替えると、Usb Disk欄に挿したカード（今回は59.5G）が出ています。モードは「SD Boot」を選びます。

「Boot Files...」を押すとファイル選択ダイアログが開くので、さっき展開したフォルダから7つの.img（env.img・idblock.img・uboot.img・boot.img・oem.img・userdata.img・rootfs.img）をまとめて選びます。update.imgは含めません。読み込まれると一覧に7ファイルが並びます。

「Create SD」を押すと、書き込み先デバイスの最終確認ダイアログが出ます。デバイス名と容量をもう一度確認してYesを押すと書き込みが始まり、右側のログに各イメージの「Write disk from file (100%)...OK」が流れていきます。今回は1〜2分で「Create sdcard OK」まで到達しました。これで書き込みは完了です。

ここで面白いのは、同梱の sd_update.txt にSDカード上の配置がセクタ単位で書いてあることです。抜粋するとこうなっています。

#env.img 0x0:0x0 0x40:0x8000 0x40:0x8000
#idblock.img 0x40:0x8000 0x400:0x80000 0x170:0x2E000
#uboot.img 0x440:0x88000 0x400:0x80000 0x200:0x40000
#boot.img 0x840:0x108000 0x10000:0x2000000 0x1899:0x313200
#oem.img 0x10840:0x2108000 0x100000:0x20000000 0x17C78:0x2F8F000
#userdata.img 0x110840:0x22108000 0x80000:0x10000000 0x4C4A:0x989400
#rootfs.img 0x190840:0x32108000 0xC00000:0x180000000 0x4CD80:0x99B0000

各行は「名前 開始セクタ:開始バイト 領域サイズ 実体サイズ」です。つまりSocToolKitがやっているのは、Rockchip/Luckfox側で定められたこのオフセットへ各イメージをそのまま置くことです。

MBR/GPTのパーティションテーブルを自分で作る必要はありません。RockchipのブートROMはSDカードのセクタ64（0x8000バイト目）にある idblock.img を読みに来て起動が始まります（ブート時のパーティション構成はU-Boot環境側にも保持されています）。

Linux機で書きたい人は、この表のとおりに各イメージを所定オフセットへ直接書けば同じものが作れます。

ですので、実際にわたしもPythonつかって自分で各イメージを書き込んでみたところ、うまく起動しました。（このとき使ったスクリプトもリポジトリに sdwrite.py として置いてあります。既定は書き込みなしのdry-runで、--writeを付けたときだけ書き込みます）

ただ、その場合、書き込み先のディスクを間違えると別のドライブを消すので、そこだけは慎重にしましょう。

手順2: 起動して、SSHで入る

書き込んだmicroSDをPico Mに挿し、USB-CでPCに繋ぎます。これが給電になり、そのまま起動します。10秒ほどで、Windows側にネットワークアダプタ「Remote NDIS based Internet Sharing Device」が現れました。追加ドライバは不要でした（Windows 11標準のRNDISドライバで認識）。

ボード側のIPアドレスは 172.32.0.93 に固定されています。ちなみにLuckfox既定のこの 172.32.0.0/16 は、RFC 1918のプライベートアドレス範囲（172.16.0.0〜172.31.255.255）の外なので、同じ範囲への経路がある環境では競合に注意してください。

PC側のRNDISアダプタに、同じネットワークのIPアドレスを手で付けます。管理者権限のPowerShellで、アダプタのifIndexを確認してから設定します。

# RNDIS アダプタの ifIndex を確認（InterfaceDescription が Remote NDIS ... の行）
Get-NetAdapter | Where-Object InterfaceDescription -match 'NDIS'

# その ifIndex に固定 IP を付ける（例: ifIndex 41）。自動で付いた 169.254.x.x は先に外す
Remove-NetIPAddress -InterfaceIndex 41 -AddressFamily IPv4 -Confirm:$false -ErrorAction SilentlyContinue
New-NetIPAddress -InterfaceIndex 41 -IPAddress 172.32.0.100 -PrefixLength 16

これで ping 172.32.0.93 が返り、SSHで入れます。ユーザーは root、初期パスワードは luckfox です。

$ ssh root@172.32.0.93
# uname -a
Linux luckfox 5.10.160 #22 Wed Jun 11 18:43:57 CST 2025 armv7l GNU/Linux
# free -m
              total        used        free      shared  buff/cache   available
Mem:             33          10           4           0          19          20
# df -h | head -2
Filesystem                Size      Used Available Use% Mounted on
/dev/root                 5.8G     79.1M      5.6G   1% /

メモリの合計が33MB。ここに公開の仕組みを載せていきます。

手順3: ボードをインターネットに出す（PC経由）

ここが、Raspberry Piにはなかった一手間です。（しかもあまり本質的ではない・・・）

Pico MはPCとしか繋がっていないので、PCをルーター役にしてボードのパケットを外へ出します。Windowsには WinNAT という仕組みがあり、管理者権限のPowerShellで作れます。まず既存のNATがないか確認してください。

# 既存の NAT を確認（何か表示されたら注意。下の注記を参照）
Get-NetNat

WinNATの利用は、Microsoftの公式手順ではHyper-Vが有効になっていることが前提です（本記事のPCはWindows 11 Proで、WSL 2でも使われるHyper-Vの仮想化基盤が有効な状態で実測しています）。

また、WinNATは1台のPCにつき内部NATのサブネットプレフィックスを1つしかサポートしません。DockerやHyper-Vの仮想ネットワークなどが既にNATを作っているPCでは、次のコマンドが通らないことがあります。その場合、既存のNATは他の仕組みが使っているので削除せず、構成への影響を確認してから進めてください。

確認できたら、NATを作ってフォワーディングを有効にします。

New-NetNat -Name LuckfoxNAT -InternalIPInterfaceAddressPrefix 172.32.0.0/16
Set-NetIPInterface -InterfaceIndex 41 -Forwarding Enabled

ボード側には、デフォルトゲートウェイ（PCのアドレス）とDNSを教えます。

ip route add default via 172.32.0.100 dev usb0
printf 'nameserver 1.1.1.1\nnameserver 8.8.8.8\n' > /etc/resolv.conf

これで ping 1.1.1.1 が通り、名前も引けます。ただ、HTTPSはまだ通りません。ここで踏んだのが次の2つでした。

ひとつめは、証明書のルート集（CAバンドル）がイメージに入っていないこと。TLSの相手を検証できないので、Pythonでもエージェントでも certificate verify failed になります。Git for Windowsに同梱されているMozillaのバンドルをそのまま置きました。

# 実機側: 置き場所を作る
mkdir -p /etc/ssl/certs

# Windows 側（PowerShell）: PC から実機へコピー（PuTTY 付属の pscp）
pscp -pw luckfox "C:\Program Files\Git\mingw64\etc\ssl\certs\ca-bundle.crt" root@172.32.0.93:/etc/ssl/certs/ca-certificates.crt

# 実機側: 権限と、python が既定で見に行くパスへのリンク
chmod 644 /etc/ssl/certs/ca-certificates.crt
ln -sf /etc/ssl/certs/ca-certificates.crt /etc/ssl/cert.pem

ふたつめは、時計です。起動直後の実機は1970年1月1日から始まっていて、この状態では証明書の有効期間の外なので、これもTLSが失敗します。ntpdは入っているのですが、経路ができる前に起動しているので、いったん手で合わせました。

# 現在の日時（UTC）に置き換えて実行してください
date -s '2026-08-18 08:45:51'

この2つを入れたところで、実機からHTTPSが通るようになりました。

# python3 -c 'import urllib.request;print(urllib.request.urlopen("https://download.wirecanal.com/latest/VERSION").read())'
b'0.18.3\n'

経路・DNS・時刻は再起動で消えるので、手順6の起動スクリプトにまとめて入れ直します。

配線: LEDを1本つなぐ

公開の前に、今回のデモの主役であるLEDをつないでおきます。使うのは物理ピン4（GPIO1_C7）と、その隣の物理ピン3（GND）です。

ピン配置は公式のGPIOドキュメントに図があります。

USB-Cコネクタを上にしてボードを見て、左の列の上から3番目がGND、4番目がGPIO1_C7です。

ブレッドボード上で

ピン4 → 抵抗（1KΩ）→ LEDアノード(長い足)＞LEDカソード(短い足)→ ピン3（GND）

とつないであります。

出力とGNDが隣同士のピンなので配線は最短で済みます。

なお、物理ピン1・2はデバッグ用のシリアルコンソール（UART2）に割り当てられているので、LED用途には使わないでおきます。

つないだら、SSHから点くかどうかを先に確かめておきます。LinuxのGPIOはsysfsからそのまま操作できます。

echo 55 > /sys/class/gpio/export
echo out > /sys/class/gpio/gpio55/direction
echo 1 > /sys/class/gpio/gpio55/value   # 点灯
echo 0 > /sys/class/gpio/gpio55/value   # 消灯

55という番号は「GPIO番号 = bank×32 ＋（groupをA=0〜D=3として）group×8 ＋ 番号」の式から来ています。

GPIO1_C7なら 1×32＋2×8＋7 = 55 です。echo 1 でブレッドボードのLEDが点けば、配線は合っています。

手順4: WireCanalでcanalを作る

ここからはRaspberry Pi 5の記事と同じ流れです。ダッシュボードの「新しい canal を作成」から、4ステップのウィザードで作ります。今回はアカウントを無料プランのままにして、そのままの条件で進めます。

転送先には localhost:18080 を入れます。Luckfoxの中でこれから立てるWebサーバーのポートです。

作成すると、canal詳細画面に接続ファイル（wirecanal.json）とセットアップ手順が出ます。Linuxタブの手順は「ワンライナーでAgentを入れる → wirecanal.jsonを置く → 起動する」の3つです。

手順5: AgentをLuckfoxに入れて、公開する

WireCanalのAgentは、CPUの種類ごとに1個の静的バイナリです。Luckfox Pico Mは32bit ARM（uname -m で armv7l）なので、wirecanal-linux-arm を使います。ワンライナーの install.sh は uname -m で自動判定して同じファイルを取りに行くのですが、今回のBuildrootイメージには curl が入っていません。なのでPC側でダウンロードして、実機へコピーしました。

# Windows 側（PowerShell）
curl.exe -fsSL https://download.wirecanal.com/latest/wirecanal-linux-arm -o wirecanal
pscp -pw luckfox wirecanal root@172.32.0.93:/root/wirecanal_demo/wirecanal
pscp -pw luckfox wirecanal.json root@172.32.0.93:/root/wirecanal_demo/wirecanal.json   # canal 詳細からダウンロードした接続ファイル

実機側で実行権限を付けて、バージョンを確認します。

# cd /root/wirecanal_demo && chmod +x wirecanal && chmod 600 wirecanal.json
# ./wirecanal --version
wirecanal v.0.18.3 powered by Qualiteg Inc. https://qualiteg.com

公開する中身は、ブラウザからLEDを点け消しできる小さなWebサーバーにしました。ONボタンを押すと、さっき配線したLEDが実際に光り、OFFで消えます。押されている側のボタンに色が付くので、いまどちらの状態かも画面で分かります。イメージにpython3が入っているので、標準ライブラリだけで書いています。127.0.0.1の18080番で待ち、GET /led で現在の状態を返し、POST /led/on・/led/off で切り替えます。LEDの操作は、配線の節で試したのと同じ /sys/class/gpio への書き込みです。

今回のコード一式（demo_server.py・S99wirecanal・settime.py・補足の sdwrite.py）は、GitHubの qualiteg/luckfox-pico-wirecanal-demo（記事執筆時点のコミット） に置いてあります。git cloneしてそのまま使えます。

demo_server.py（実機に置いたもの・全文）

# LED control page for the Luckfox Pico M
# Served on 127.0.0.1:18080 and published to the internet through a WireCanal tunnel.
# The ON/OFF buttons drive GPIO1_C7 (sysfs number 55, physical pin 4) where an LED is wired.
import http.server, subprocess, socket, html, os

GPIO = "55"
GPIO_DIR = "/sys/class/gpio/gpio" + GPIO

def gpio_init():
    if not os.path.isdir(GPIO_DIR):
        with open("/sys/class/gpio/export", "w") as f:
            f.write(GPIO)
    with open(GPIO_DIR + "/direction", "w") as f:
        f.write("out")

def gpio_set(v):
    with open(GPIO_DIR + "/value", "w") as f:
        f.write("1" if v else "0")

def gpio_get():
    with open(GPIO_DIR + "/value") as f:
        return f.read().strip() == "1"

def sh(c):
    try: return subprocess.run(c, shell=True, capture_output=True, text=True, timeout=5).stdout.strip()
    except Exception as e: return str(e)

PAGE = """<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>Luckfox Pico M LED control</title>
<style>body{font-family:system-ui,-apple-system,Segoe UI,Roboto,sans-serif;margin:0;background:#f7fafd;color:#15222b}
.wrap{max-width:720px;margin:40px auto;padding:0 20px}.card{background:#fff;border:1px solid #dde5ee;border-radius:16px;padding:28px 32px;box-shadow:0 2px 12px rgba(0,0,0,.05)}
h1{font-size:1.5rem;margin:0 0 6px}.sub{color:#5f6b78;margin:0 0 20px}table{border-collapse:collapse;width:100%%}td{padding:8px 6px;border-bottom:1px solid #eef2f6;vertical-align:top}
td:first-child{color:#5f6b78;width:150px}code{background:#f1f5f9;padding:2px 6px;border-radius:6px}
.led{display:flex;align-items:center;gap:16px;margin:18px 0 22px}
.dot{width:26px;height:26px;border-radius:50%%;background:#cfd8e3;transition:all .15s}
.dot.on{background:#e5484d;box-shadow:0 0 14px 3px rgba(229,72,77,.55)}
button{font-size:1rem;font-weight:600;border-radius:10px;border:1px solid #cdd7e1;background:#fff;color:#15222b;padding:10px 26px;cursor:pointer;transition:all .15s}
button.active{background:#1f7ae0;border-color:#1f7ae0;color:#fff}
#btnOn.active{background:#e5484d;border-color:#e5484d}
.state{font-weight:700;min-width:44px}
.foot{color:#8b96a4;font-size:.85rem;margin-top:16px}</style></head><body><div class="wrap"><div class="card">
<h1>Luckfox Pico M &mdash; LED control</h1>
<p class="sub">The buttons below drive a real LED wired to GPIO1_C7 (physical pin 4) on the board, through a WireCanal tunnel. No inbound port is exposed directly to the internet.</p>
<div class="led"><div id="dot" class="dot"></div><span id="state" class="state">...</span>
<button id="btnOn" onclick="setLed(1)">ON</button><button id="btnOff" onclick="setLed(0)">OFF</button></div>
<table>
<tr><td>Board</td><td>Luckfox Pico M (Rockchip RV1103, ARM Cortex-A7, 64 MB DDR2)</td></tr>
<tr><td>Hostname</td><td><code>%(host)s</code></td></tr>
<tr><td>Kernel</td><td><code>%(uname)s</code></td></tr>
<tr><td>Uptime</td><td>%(uptime)s</td></tr>
<tr><td>LED pin</td><td><code>GPIO1_C7</code> = sysfs gpio%(gpio)s, physical pin 4 (GND on pin 3)</td></tr>
</table>
<p class="foot">Agent: WireCanal (linux/arm) &middot; Powered by Qualiteg</p>
</div></div>
<script>
async function refresh(){const r=await fetch('/led');const j=await r.json();
document.getElementById('dot').className='dot'+(j.on?' on':'');
document.getElementById('state').textContent=j.on?'ON':'OFF';
document.getElementById('btnOn').className=j.on?'active':'';
document.getElementById('btnOff').className=j.on?'':'active';}
async function setLed(v){await fetch('/led/'+(v?'on':'off'),{method:'POST'});refresh();}
refresh();setInterval(refresh,3000);
</script></body></html>"""

class H(http.server.BaseHTTPRequestHandler):
    def _send(self, code, body, ctype="text/html; charset=utf-8"):
        data = body.encode("utf-8")
        self.send_response(code)
        self.send_header("Content-Type", ctype)
        self.send_header("Content-Length", str(len(data)))
        self.end_headers()
        self.wfile.write(data)
    def do_GET(self):
        if self.path == "/led":
            return self._send(200, '{"on": %s}' % ("true" if gpio_get() else "false"), "application/json")
        body = PAGE % {
            "host": html.escape(socket.gethostname()),
            "uname": html.escape(sh("uname -srm")),
            "uptime": html.escape(sh("uptime")),
            "gpio": GPIO,
        }
        self._send(200, body)
    def do_POST(self):
        if self.path == "/led/on":
            gpio_set(True)
        elif self.path == "/led/off":
            gpio_set(False)
        else:
            return self._send(404, '{"error":"not found"}', "application/json")
        self._send(200, '{"on": %s}' % ("true" if gpio_get() else "false"), "application/json")
    def log_message(self, *a): pass

gpio_init()
http.server.HTTPServer(("127.0.0.1", 18080), H).serve_forever()

ひとつだけ注意点があります。今回のBuildroot環境では python3 -m http.server をそのまま起動するとIPv6側のソケットを開こうとして Address family not supported で落ちました（このイメージのカーネルにはIPv6がありません）。上のコードのように 127.0.0.1 を明示して待ち受ければ問題ありません。

Webサーバーを裏で起動し、続けてAgentを起動します。

cd /root/wirecanal_demo
(setsid nohup python3 demo_server.py >/dev/null 2>&1 &)
./wirecanal -config wirecanal.json

wirecanal v.0.18.3 powered by Qualiteg Inc. https://qualiteg.com
wirecanal: warning: mode=http かつ http ルール未設定のため、全パスを転送先へ通します。特定のパス・メソッドに絞る場合は http.default: deny ＋ http.rules を設定してください
wirecanal: 自動更新が有効です（無効化は wirecanal.json に "auto_update": false）
wirecanal: canal urym: https://fxsu8b0c.ja000.wirecanal.com へのアクセスをローカルの転送先 localhost:18080 に届けます
wirecanal: 設定は https://app.wirecanal.com/canals/urym をご確認ください
wirecanal 0.18.3: connecting tenant=urym mode=http forward_target=localhost:18080

この時点で、ダッシュボードの接続状態が「● 接続中」に変わります。

インターネット側から見てみる

公開URLをブラウザで開きます。

「Linux 5.10.160 armv7l」というカーネルも稼働時間も、さっきSSHで見た実機の生きた値がそのままインターネット越しに出ています。そしてONボタンを押すと、手元のブレッドボードの上でLEDが実際に光ります。ブラウザは公開URLを叩いているだけで、その先で実物が動く。スマホでも同じURLをそのまま開けます。

curlでの実測はこうでした。ページを経由せず、APIを直接叩いてLEDを操作することもできます。

$ curl -s -o /dev/null -w "HTTP %{http_code} / %{time_total}s" https://fxsu8b0c.ja000.wirecanal.com/
HTTP 200 / 0.232s
$ curl -s -X POST https://fxsu8b0c.ja000.wirecanal.com/led/on
{"on": true}
$ curl -s -X POST https://fxsu8b0c.ja000.wirecanal.com/led/off
{"on": false}

このときインターネット側からPico Mへ直接到達できる受信ポートは、ひとつもありません。18080番は 127.0.0.1 だけで待っていて、PCのNATにも受信（ポートフォワード）の設定は何も入れていません。公開は、Agentの外向き接続だけで成立しています。SSH（22番）はRNDIS側で待受していますが、これはPCとボードの間だけの閉じたネットワークで、インターネット側からは届きません。

なお、今回は認証を付けていないため、URLを知っている人はページの閲覧もLEDのON/OFF操作もできます。今回は抵抗を介したLED 1本だけのデモなのでそのまま公開していますが、リレー・モーター・鍵・電源制御など実物に影響するGPIOを公開する場合は、canalのアクセス保護（IP制限・認証）やHTTPルールで、操作できる相手・パス・メソッドを必ず絞ってください。

手順6: 常駐させて、電源を抜いても戻ってくるようにする

手順5の起動はターミナルを閉じると止まりますし、経路・DNS・時刻は再起動で消えます。Raspberry Pi OSならsystemdの雛形を置くだけでしたが、Buildrootのinitはbusyboxの /etc/init.d/S??name 方式なので、起動スクリプトを1本書きます。

その前に、スワップを用意しておきます。Linuxから見えるメモリが33MBで、Agentは自動更新のための常駐ウォッチドッグ（wirecanal-safeguard）と組で動くので、そのぶんの余裕を持たせるためです。SDカード上に128MBのファイルを切って有効にしました。

dd if=/dev/zero of=/swapfile bs=1M count=128
chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile

起動スクリプトは次のとおりです。やっていることは、スワップを有効化し、USB側のネットワーク（usb0）にアドレスが付くのを待ち、経路とDNSを入れ、ntpを起動し直して時計が合うのを待ってから、Webサーバーとエージェントを起動する、という順番です。エージェントは終了したら5秒後に立ち上げ直すループにしています。systemdの Restart=always の代わりです。監視ループのPIDをファイルに控えて、二重起動の防止と、stop で監視ループごと全部止まるようにしてあります（監視ループを残したままエージェントだけkillすると、5秒後に勝手に復活してしまいます）。

/etc/init.d/S99wirecanal（実機に置いたもの・全文）

#!/bin/sh
# WireCanal Agent (Luckfox Pico M / Buildroot busybox init)
WD=/root/wirecanal_demo
SUPERVISOR_PID=/var/run/wirecanal-supervisor.pid
case "$1" in
  start)
    # 二重起動防止（前回の監視ループが生きていれば何もしない）
    if [ -f "$SUPERVISOR_PID" ] && kill -0 "$(cat $SUPERVISOR_PID)" 2>/dev/null; then
      echo "wirecanal supervisor already running (pid $(cat $SUPERVISOR_PID))"
      exit 0
    fi
    (
      [ -f /swapfile ] && swapon /swapfile 2>/dev/null
      i=0; while ! ip -4 addr show usb0 2>/dev/null | grep -q inet && [ $i -lt 60 ]; do sleep 2; i=$((i+1)); done
      ip route | grep -q '^default' || ip route add default via 172.32.0.100 dev usb0
      grep -q nameserver /etc/resolv.conf 2>/dev/null || printf 'nameserver 1.1.1.1\nnameserver 8.8.8.8\n' > /etc/resolv.conf
      /etc/init.d/S49ntp restart >/dev/null 2>&1
      i=0; while [ "$(date +%Y)" -lt 2025 ] && [ $i -lt 20 ]; do sleep 3; i=$((i+1)); done
      [ "$(date +%Y)" -lt 2025 ] && python3 $WD/settime.py >/dev/null 2>&1
      cd $WD && (setsid nohup python3 demo_server.py >/dev/null 2>&1 &)
      # Agent が終了したら 5 秒後に立ち上げ直す（systemd の Restart=always の代わり）
      cd $WD && while true; do ./wirecanal -config wirecanal.json >> agent.log 2>&1; sleep 5; done
    ) >/dev/null 2>&1 &
    echo $! > $SUPERVISOR_PID
    ;;
  stop)
    # 監視ループ → Agent/ウォッチドッグ → Web サーバーの順にすべて止める
    if [ -f "$SUPERVISOR_PID" ]; then
      kill "$(cat $SUPERVISOR_PID)" 2>/dev/null
      rm -f $SUPERVISOR_PID
    fi
    for p in $(ps | grep -E '[w]irecanal -config|[w]irecanal-safeguard|[d]emo_server' | awk '{print $1}'); do
      kill "$p" 2>/dev/null
    done
    ;;
  restart) "$0" stop; sleep 1; "$0" start ;;
esac
exit 0

途中で呼んでいる settime.py は、ntpが間に合わなかったときの保険で、HTTPの応答ヘッダにある日付で時計を合わせるだけの数行のスクリプトです。これはTLSを使える時刻まで戻すためのデモ用フォールバックで、通常の時刻同期はNTPに任せます。

settime.py（全文）

import urllib.request, urllib.error, email.utils, subprocess
try:
    r = urllib.request.urlopen('http://download.wirecanal.com/', timeout=10)
except urllib.error.HTTPError as e:
    r = e
t = email.utils.parsedate_to_datetime(r.headers.get('Date'))
subprocess.run(['date', '-u', '-s', t.strftime('%Y-%m-%d %H:%M:%S')])

ここで一度ハマった話を書いておきます。busyboxの ip route show default は「default」の指定を無視して全経路を返します。最初はこれで「経路がある」と誤判定して、再起動後に外へ出られませんでした。上のスクリプトのように ip route | grep '^default' で見るのが確実です。もうひとつはPIDの控え方で、サブシェルの中で $$ を書くと、BusyBoxのshでは親のPIDが記録されてしまい、二重起動ガードが効きません。上のスクリプトのように、サブシェルをバックグラウンドにした直後に親側で $! を書き出すのが確実です（これも実測で気づきました）。

実行権限を付けて sync したら、いよいよ再起動です。

chmod +x /etc/init.d/S99wirecanal && sync && reboot

再起動しても、公開は自動で復活するか

再起動をかけた瞬間から時間を測り、公開URLが200を返すまでを実測しました。

# uptime
 10:31:08 up 0 min,  load average: 5.00, 1.25, 0.41
# free -m
              total        used        free      shared  buff/cache   available
Mem:             33          17           1           0          14          13
Swap:           128           9         119
# ps | grep -E 'wirecanal|demo_server'
  793 root     python3 demo_server.py
  794 root     ./wirecanal -config wirecanal.json
  808 root     /root/wirecanal_demo/wirecanal-safeguard -config wirecanal.json -exec /root/wirecanal_demo/wirecanal -state-dir .wirecanal-state

復帰直後に公開URLを開くと、ページの稼働時間が「up 0 min」でした。再起動したばかりの実物が、そのままインターネット側から見えている証拠です。USB-Cを物理的に抜き差ししたときも同じで、挿し直すだけで何もせずに公開URLが復活しました。

3,750円のボードでも、外から届くサーバーになった

Luckfox Pico Mは、Linuxから見えるメモリが33MB、有線もWi-Fiもない、USB-Cが1本だけのボードです。それでも、SDカードへの書き込みからインターネット側で公開URLが返るまで、必要だったのは、この記事に書いた手順だけでした。Web公開のための受信ポートは最後まで追加していませんし、WireCanalは無料プランのままです。

Raspberry Pi 5のときと違ったのは、ネットワークをPC経由にする一手間と、Buildrootならではの下ごしらえ（CAバンドル・時刻・busybox init）です。逆に言うと、そこさえ越えれば、Agentのやること自体は同じでした。wirecanal-linux-arm のバイナリを置いて、wirecanal.jsonを隣に置いて、起動する。それだけです。

今回はLED 1本でしたが、この小さなボードには、これからセンサーやカメラを載せて、外出先から見られるものを増やしていきたいとおもいます！

それでは、また次回お会いしましょう！

出典・参考

• Luckfox Wiki（Luckfox Pico RV1103 シリーズの公式ドキュメント・イメージ配布・SDカード書き込み手順）
• サンプルコード一式（GitHub: qualiteg/luckfox-pico-wirecanal-demo・記事執筆時点のコミット）
• WireCanal IoTデバイス対応ページ（対応チップ＋Linuxの組み合わせと、対応チップを搭載したデバイスの例）
• WireCanal Linuxセットアップガイド（Agentの配布ファイル名と常駐手順）
• Luckfox Wiki: Flash Image（SDカード書き込みの公式手順。SocToolKitとOSイメージの配布リンクもこのページ）
• Luckfox Wiki: GPIO（ピン配置図と /sys/class/gpio でのGPIO操作）
• SD Card Formatter（SDアソシエーション公式のフォーマットツール）
• New-NetNat（Microsoft Learn・WinNAT のコマンドリファレンス）

関連記事

• Raspberry Pi 5のWebサーバーをインターネットに公開する。ポートは開けない、WireCanalのトンネルで
• Raspberry Pi 5をモニターなしでセットアップする。Windows PCだけでOS書き込みからSSH接続まで
• Raspberry Pi 5を堅牢化する。SSH鍵認証・UFW・fail2banと、再起動でIPv6が復活する罠
• 自宅PCのローカルLLMを外出先のスマホから使う。Ollama＋Open WebUI+WireCanal

こんにちは！Qualitegプロダクト開発部です！

Raspberry Pi 5の連載も3回目です。

第1話でモニターなしのセットアップ、第2話で堅牢化をやりました。第2話ではUFWで受信を原則拒否し、自宅LANからのSSHだけを明示的に許可しました。

ラズパイの上ではWebサーバーが動いているのに、外からはもちろん、LAN内からすら8080には繋がらない状態です。

今回はこのラズパイのWebサーバーを、インターネット側から使えるようにします。ただし、

Web公開のために受信ポートを追加で開くことはしません。ルーターのポート開放もしません。使うのは、当社のトンネルサービスWireCanalです.今回の用途なら無料です。

先に結果を言うと、Agentのインストールから公開URLで表示できるところまで実測およそ5分、systemdでの常駐化まで含めて約10分でした。

この記事では、その手順を実際の画面と実測値つきで最初から最後まで書きます。再起動しても公開が自動で復活するところまで検収します。

対象はRaspberry Pi OS（64-bit・Debian 13 trixieベース）です。WireCanalは当社が開発・運営している自社サービスで、クレジットカード登録なしのフリープラン（0円）から使えます。記事中の数値は2026年8月14日時点の実測値です。

ポートを開けずに、どうやって公開するのか

普通、自宅のサーバーを公開しようとすると、ルーターのポート開放（ポートフォワーディング）が要ります。ただ、これは外からの入口を自宅に作る行為なので、第2話でせっかく受信を固めたのに、今度はルーターに穴を開けるのかという話になります。さらに、グローバルIPが変動する環境で同じ名前から継続的にアクセスしたいなら、DDNSなどの仕組みも必要になります。集合住宅の回線だと、そもそもポート開放ができないこともあります。

トンネル方式は逆向きです。ラズパイの中のAgentが、WireCanalの中継サーバーへ外向きに接続します。外からのアクセスは中継サーバーが受け、その確立済みの接続を通ってラズパイに届きます。自宅側に入口を作らないので、ポート開放もルーター設定も要りません。UFWの「受信は原則拒否」もそのままです。

第2話の「受信を原則拒否する」と今回の「Web公開用の受信ポートを追加しない」は、この仕組みで両立します。

材料

ラズパイ側は前回までの状態そのままです。状態表示の小さなWebサーバー（Python標準ライブラリ製・ポート8080）がsystemdで常駐しています。

WireCanal側はアカウントだけ用意してください。フリープラン（0円・カード登録不要）で今回の手順はすべて試せます。なお、フリーは転送量が月10GB目安で、超過後は減速する場合があります。もうひとつ、フリープランのおまかせサブドメインは、Agentを使っている限り有効ですが、Agentの最終接続から72時間で失効します。長期間止めても同じURLを維持したい場合は、永続URLのあるライト以上が対象です。今回のように常駐で動かし続けるなら、フリーでもURLは維持されます。

手順1: ラズパイにAgentをインストールする

SSHでラズパイに入り、置きたいディレクトリでワンライナーを実行します。

mkdir -p ~/wirecanal && cd ~/wirecanal
curl -fsSL https://download.wirecanal.com/install.sh | sh

実行結果がこれです。CPUアーキテクチャ（ラズパイ5はarm64）は自動判定されます。

WireCanal Agent v.0.18.1 をダウンロードしています...
wirecanal v.0.18.1 powered by Qualiteg Inc. https://qualiteg.com

インストール完了: /home/pi/wirecanal/wirecanal
次の手順:
  1. ダッシュボード（https://app.wirecanal.com）の canal 詳細から wirecanal.json を
     ダウンロードして、wirecanal と同じフォルダに置く
  2. 起動: ./wirecanal -config wirecanal.json

バージョン表示まで自動で確認されて終わります。Agentは単一バイナリで、これ以外に入れるものはありません。

手順2: canalを作る（4ステップのウィザード）

WireCanalでは、公開URLと転送先の組をcanalと呼びます。ダッシュボードの「新しい canal を作成」から、ウィザードで作ります。種類は「HTTP」を選びます。Webサーバーを HTTPS で公開するモードです。

公開アドレスは「おまかせサブドメイン」にしました。ランダムな名前で今すぐ発行され、全プランで使えます。次の設定画面で、転送先に localhost:8080 を入れます。ラズパイの中でWebサーバーが待っているポートです。メモは任意ですが、あとで一覧を見たときに分かるように書いておくのがおすすめです。

確認画面で「作成する」を押すと、公開URLと接続キー（access_key）が発行されます。今回発行されたのは https://5m0kjyxw.ja100.wirecanal.com でした。

手順3: wirecanal.jsonを置いて起動する

canal詳細画面に、接続ファイル（wirecanal.json）が表示されます。ダウンロードして、ラズパイのAgentと同じフォルダに置きます。画面にはセットアップ手順もLinux用のタブでそのまま出ています。

この連載はWindowsからのヘッドレス操作なので、ダウンロードしたファイルはscpでラズパイへ送ります（第2話で仕込んだSSH鍵がそのまま使えます）。

# Windows側（PowerShell）
scp "$env:USERPROFILE\Downloads\wirecanal.json" pi@192.168.12.17:/home/pi/wirecanal/

wirecanal.jsonにはcanal専用の接続キー（access_key）が入っています。ラズパイ側で権限を絞ってから起動します。

cd ~/wirecanal
chmod 600 wirecanal.json
./wirecanal -config wirecanal.json

wirecanal v.0.18.1 powered by Qualiteg Inc. https://qualiteg.com
wirecanal: canal t5zd: https://5m0kjyxw.ja100.wirecanal.com へのアクセスをローカルの転送先 localhost:8080 に届けます
wirecanal 0.18.1: connecting tenant=t5zd mode=http forward_target=localhost:8080

この時点でダッシュボードの接続状態が「● 接続中」に変わり、トンネルが開通しています。

手順4: systemdで常駐させる

手順3の起動は、ターミナルを閉じると止まります。サーバーとして使うので、Webサーバーと同じくsystemdで常駐させます。Linuxセットアップガイドの常駐手順の雛形どおり、/opt/wirecanal に置いて専用ユーザーで動かします。

sudo mkdir -p /opt/wirecanal
sudo cp ~/wirecanal/wirecanal ~/wirecanal/wirecanal.json /opt/wirecanal/

sudo tee /etc/systemd/system/wirecanal.service > /dev/null <<'EOF'
[Unit]
Description=WireCanal Agent
After=network-online.target
Wants=network-online.target

[Service]
User=wirecanal
WorkingDirectory=/opt/wirecanal
ExecStart=/opt/wirecanal/wirecanal -config /opt/wirecanal/wirecanal.json
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo useradd --system --home /opt/wirecanal --shell /usr/sbin/nologin wirecanal
sudo chown -R wirecanal: /opt/wirecanal
sudo chmod 600 /opt/wirecanal/wirecanal.json
sudo systemctl daemon-reload
sudo systemctl enable --now wirecanal
systemctl status wirecanal --no-pager

Restart=always なので、Agentのプロセスが終了した場合は5秒後に自動で再起動します（systemctl stop のような明示的な停止は除きます）。ログは journalctl -u wirecanal -f で追えます。

インターネット側から見てみる

公開URLをブラウザで開きます。

ラズパイの状態表示ページが、そのまま出ました。CPU温度も稼働時間も生きた値です。curlでの実測はこうでした。

$ curl -s -o /dev/null -w "HTTP %{http_code} / %{time_total}s" https://5m0kjyxw.ja100.wirecanal.com/
HTTP 200 / 0.18s

このときラズパイ側の受信ポートは、第2話のUFW設定（受信は原則拒否・SSHのみLAN限定許可）のままです。8080は外からもLANからも閉じたままで、公開はAgentの外向き接続だけで成立しています。

なお、URLを知っている人は誰でも見られる状態なので、見せたい相手を絞る場合はcanalのアクセス保護（IP制限・認証など）を設定してください。今回は無害な状態表示ページなので、そのまま公開しています。

再起動しても、公開は自動で復活するか

第2話で「設定を入れて確認しただけでは、永続性は保証されない」という教訓を得ました。今回も実際に再起動して検収します。

面白かったのは、再起動直後に公開URLへアクセスしたら、ページの稼働時間表示が「0時間0分」だったことです。再起動したばかりの実物が、そのままインターネット側から見えている証拠になりました。

まとめ

3話かけて、ヘッドレスセットアップから堅牢化、そしてWeb公開まで到達しました。ラズパイは、Web公開用の受信ポートを1つも開けないまま、インターネット側から使えるサーバーになりました！

インターネットから使えるということはスマホからも使えますし、ラズパイですので、スマホで外出先から、家庭内機器を操作したり。もちろんＬＥＤチカチカさせたり、カメラをつけて、みたり、とできることは無限大ではないでしょうか。

ということで、このラズパイはこれから、家の中の小さな常設サーバーとして育てていきます。

載せるものが増えたら、また記事にしたいとおもいます。

それでは、また次回お楽しみに！

出典・参考

• WireCanal 公式サイト
• WireCanal Linuxセットアップガイド（常駐手順の雛形はここ）
• Raspberry Pi Documentation（公式ドキュメント）

関連記事

• Raspberry Pi 5をモニターなしでセットアップする。Windows PCだけでOS書き込みからSSH接続まで（第1話）
• Raspberry Pi 5を堅牢化する。SSH鍵認証・UFW・fail2banと、再起動でIPv6が復活する罠（第2話）
• 自宅PCのローカルLLMを外出先のスマホから使う。Ollama＋Open WebUI+WireCanal
• ngrokとWireCanalは何が違う？開発元が料金・運用・MCP設計を比較

こんにちは！
Qualitegプロダクト開発部です！

前回の記事で、モニターなしのRaspberry Pi 5をWindows PCだけでセットアップし、SDカード挿入から約3分でSSH接続まで到達しました。

このラズパイ、ゆくゆくは小さなWebサーバーを載せてインターネット側から使えるようにする予定です。

ただ、その前にやることがあります。

セットアップ直後のRaspberry Pi OSは、実測してみると思った以上に無防備

でした。

前回の検証用セットアップで設定した簡易なパスワードでパスワード認証が有効なまま、ファイアウォールなし、更新可能なパッケージが172件たまり、そして意図していないのにIPv6のグローバルアドレスまで付いていました。

この記事では、

SSHの鍵認証化・UFW・fail2ban・更新の自動適用・IPv6無効化までを実コマンドでやり切り、実際に再起動して設定が生き残ることまで検収します

先にことわっておくと、この検収で1回つまずきました。

sysctlで無効化したはずのIPv6が、再起動したら復活していたのです。

原因はNetworkManagerの接続プロファイルでした。

この顛末は後半で詳しく書きます。

この記事の対象はRaspberry Pi OS（64-bit・Debian 13 trixieベース）です。

作業はすべてWindows PCからSSH越しに行い、ラズパイにモニターは最後まで繋ぎません。記事中の数値は2026年8月14日時点の実測値です。

初期状態を実測したら、ここまで無防備だった

手を入れる前に、まず現状を実測しました。「たぶん危ない」ではなく、どこがどう開いているかを確かめてから塞ぎます。

IPv6は意外に思うかもしれません。LAN内運用のつもりでも、ルーター広告（RA）を受けて 2409: で始まるグローバルIPv6アドレスが自動で付いていました。

IPv6のグローバルアドレスはNATを前提としないため、IPv4とは露出の考え方が異なります。

本記事ではIPv6を運用対象にしない方針なので、使わない経路を残さないために明示的に無効化します。

方針。ポートは開けない、公開はトンネルで

堅牢化の方針はこう決めました。

SSHは鍵認証のみにして、接続元も自宅LANに限定します。それ以外の受信ポートは、Webサーバー用の8080を含めて一切開けません。

「外から使えるようにしたいのにポートを開けない」のは矛盾に見えますが、公開は次回、WireCanalのトンネル経由で行います。トンネル方式ならラズパイ側は外向きの接続だけで済むので、受信ポートを開ける必要も、ルーターのポート開放も要りません。

つまり今回の堅牢化は「全部閉じる」、
次回の公開は「閉じたまま外に出す」という分担です。

手順1: SSH鍵を仕込む（締め出さない順序がすべて）

最初に鍵を仕込みます。ここで鉄則がひとつあります。鍵ログインの成功を実測してから、パスワード認証を止める。順序を誤ると、自分がSSHで入れなくなります。モニターなし運用のラズパイでは、ヘッドレスのままの復旧がかなり面倒になるので、この順序だけは崩せません。

SSH鍵をまだ持っていない場合は、先にWindows側で ssh-keygen -t ed25519 を実行して作っておきます。

途中で訊かれるパスフレーズは設定しておくのがおすすめです（鍵ファイルが漏れたときの保険になります）。公開鍵は %USERPROFILE%\.ssh\id_ed25519.pub にできます。

まず、ラズパイ側に公開鍵を置きます。

# ラズパイ側（piユーザーで実行）
D=/home/pi/.ssh
mkdir -p "$D"; chmod 700 "$D"
cat > "$D/authorized_keys" <<'EOF'
ssh-ed25519 AAAA...（あなたの公開鍵）
EOF
chmod 600 "$D/authorized_keys"; chown -R pi:pi "$D"

なお、cat > は既存の authorized_keys を丸ごと上書きします。今回は新規構築直後なのでこの書き方にしていますが、既に鍵を登録してある環境では追記（>>）にしてください。

GitHubを使っている方は、https://github.com/<アカウント名>.keys で自分の公開鍵一覧を取得できるので、そこからコピーするのが手早いです。

置いたら、Windows側から鍵だけでログインできることを確認します。

ssh -o PasswordAuthentication=no pi@192.168.12.17

これが通ってから次へ進みます。

手順2: パスワード変更・IPv6無効化・SSHを鍵のみにする

ここからはroot権限での作業です（sudo -i で入るか、各コマンドに sudo を付けてください）。まずパスワードの変更です。前回の検証用の簡易なパスワードから、きちんとしたものに変えます。鍵のみ化した後もsudoでパスワードは使うので、ここで整えておきます。

passwd pi

次に、OS側でIPv6を無効化します。

cat > /etc/sysctl.d/99-disable-ipv6.conf <<'EOF'
net.ipv6.conf.all.disable_ipv6 = 1
net.ipv6.conf.default.disable_ipv6 = 1
net.ipv6.conf.lo.disable_ipv6 = 1
EOF
sysctl --system

そしてSSHを固めます。設定は本体ファイルを書き換えず、drop-inで追加します。

cat > /etc/ssh/sshd_config.d/00-hardening.conf <<'EOF'
PasswordAuthentication no
KbdInteractiveAuthentication no
PermitRootLogin no
AddressFamily inet
EOF
sshd -t && systemctl restart ssh

AddressFamily inet はIPv4のみで待ち受ける指定です。UbuntuだとsshdがソケットActivation（ssh.socket）経由のことがあり、socket側にもdrop-inが要るのですが、今回の実機では ssh は service 直起動（ssh.socket は disabled）だったので、sshd_config の指定だけで [::]:22 が消えました（実測）。

ここで一度、別のターミナルからパスワード認証を試しておきます。拒否されれば成功です。既存の鍵ログインが生きていることも忘れずに確認します。

手順3: 保留172件の更新と、fail2ban・自動更新

export DEBIAN_FRONTEND=noninteractive
apt-get update -q
apt-get -y -q full-upgrade          # 保留172件を全適用
apt-get -y -q install ufw fail2ban unattended-upgrades

fail2banはSSHへの試行失敗を数えて自動でBANしてくれる番人です。ひとつ押さえておきたいのは、今回のRaspberry Pi OS trixie実機にはrsyslogが入っておらず /var/log/auth.log も存在しないことです。

sshdのログはjournaldから読むことになります。Debianのfail2banパッケージにはsshd向けにjournaldを見る設定（sshd_backend = systemd）が入っていますが、古い解説記事はauth.logを前提にしていることが多いので、今回はjail設定でもbackendを明示しました。

cat > /etc/fail2ban/jail.d/sshd.local <<'EOF'
[sshd]
enabled = true
backend = systemd
maxretry = 5
bantime = 1h
EOF
systemctl enable --now fail2ban

更新の自動適用（unattended-upgrades）も入れます。

夜中に勝手に再起動されると困るので、自動再起動だけは切っておきます。なお定期実行の実体はAPT側のタイマー（apt-daily.timer / apt-daily-upgrade.timer）なので、検収ではタイマーが有効なことまで確認します。

cat > /etc/apt/apt.conf.d/20auto-upgrades <<'EOF'
APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Unattended-Upgrade "1";
EOF
cat > /etc/apt/apt.conf.d/52unattended-upgrades-local <<'EOF'
Unattended-Upgrade::Automatic-Reboot "false";
EOF
systemctl enable --now unattended-upgrades

ひとつ、full-upgradeの副作用で面白い発見がありました。

今回の実機では、初期状態に /etc/sudoers.d/010_pi-nopasswd があってsudoがパスワードなしで通っていたのですが、

full-upgrade後にこのファイルが消えて、sudoがパスワード必須に変わりました
（今回の環境での実測で、一般の仕様変更として確認したものではありません）。堅牢化としては望ましい方向なので、そのまま採用しています。

手順4: UFWは「許可を先に入れてから」有効化する

ファイアウォールで怖いのは自分の締め出しです。UFWはインストール直後は無効（disabled）なので、既定ポリシーを設定した瞬間に遮断が始まるわけではありません。

危険なのは、SSHの許可ルールを入れないまま ufw enable することです。

だから許可ルールを先に入れてから有効化します。

ufw default deny incoming
ufw default allow outgoing
ufw allow from 192.168.12.0/24 to any port 22 proto tcp   # 自宅LANのセグメントに合わせる
ufw --force enable

新規の受信は原則拒否し、ユーザー定義の許可ルールは自宅LANからのSSH(22)だけにします。検証用に動かしているWebサーバーの8080も、あえて許可しません（次回、ここをトンネルで公開します）。有効化したら、いまのSSHセッションは閉じずに、別のターミナルから新しくSSH接続できることを確認してください。

検収。全項目を実測で通す

設定を書き終わったら検収です。「設定ファイルにそう書いたから大丈夫」ではなく、実際の挙動を外形から確かめます。

ここまでは順調でした。問題は次です。

再起動したら、IPv6が復活していた

設定の永続性は、実際に再起動しないと分かりません。1回目の再起動検収では、再起動をかけてから約21秒でSSHが復帰し、UFWもfail2banも自動起動していました。ところが。

ip -6 addr show scope global
# → 2409:xx:xxxx:... が、いる

消したはずのIPv6グローバルアドレスが、復活していました。

原因はNetworkManagerでした。接続プロファイル側でIPv6が有効なままだったため、sysctlの disable_ipv6 を適用していても、

Wi-Fi接続が確立するタイミングでインターフェース単位の disable_ipv6 が0に書き戻されていました（今回の環境での観測）。

適用直後の確認では ip -6 addr が空になるので成功に見える。しかし再起動してWi-Fiが繋ぎ直されると、設定が巻き戻る。この動きは1回目の再起動検収で初めて表面化しました。

恒久化するには、NetworkManagerの接続プロファイル側でIPv6を無効にします。

# プロファイル名を確認（今回の実機では preconfigured という名前でした）
nmcli connection show --active

# プロファイル側でIPv6を無効化
nmcli connection modify "<上で確認した接続名>" ipv6.method "disabled"

これを入れて2回目の再起動検収を実施し、今度は再起動後もグローバルアドレス0件を維持できました。

この件の教訓は、IPv6の設定方法そのものより、こちらだと思っています。

「設定を入れて、その場で確認した」だけでは、永続性は保証されない。再起動まで含めて検収して、初めて完了になる。

検収で1項目でも落ちたら全体を未完として扱い、直してから再検収する。この運用にしていたおかげで、「無効化したつもりの設定が、再起動後には元に戻っていた」状態を公開前に見つけられました。

今回のtrixie実機で確認した、古い手順との違い

Debian 13 trixieベースになって、昔からある手順の前提と違っていた箇所がいくつかありました。

今回の実機で確認できた範囲で整理しておきます。

まとめ

セットアップ直後のRaspberry Pi 5は、検証用の簡易なパスワードでパスワード認証が有効・ファイアウォールなし・更新可能パッケージ172件・意図しないIPv6アドレス保持、という状態でした。

今回の作業で、SSHは鍵のみ・接続元LAN限定になり、UFWは受信を原則拒否してSSHだけを自宅LANから明示的に許可する構成になり、unattended-upgradesの対象となる更新は自動適用されるようになりました。

作業はすべてSSH越しで、モニターは一度も繋いでいません。

いちばんの収穫は、sysctlのIPv6無効化がNetworkManagerの接続プロファイルに書き戻される現象を、実再起動の検収で捕まえられたことです。設定直後の確認だけで完了にしていたら、この巻き戻りには公開後まで気づけないところでした。

次回はいよいよ、このラズパイの上のWebサーバーを、受信ポートを一切開けないままWireCanalでインターネット側から使えるようにします。

それでは、また次回をお楽しみに！

出典・参考

• Raspberry Pi Documentation | Configuration（公式ドキュメント）
• fail2ban 公式リポジトリ（GitHub）
• UFW - Community Help Wiki（Ubuntu公式Wiki）
• NetworkManager 公式ドキュメント（freedesktop.org）

関連記事

• Raspberry Pi 5をモニターなしでセットアップする。Windows PCだけでOS書き込みからSSH接続まで
• 自宅PCのローカルLLMを外出先のスマホから使う。Ollama＋Open WebUI+WireCanal
• ngrokとWireCanalは何が違う？開発元が料金・運用・MCP設計を比較

こんにちは！

Qualitegプロダクト開発部です！

本稿はRaspberry Pi(ラズベリーパイ、通称ラズパイ）をインターネット越しにコントロール方法についてシリーズでお伝えいたします。

シリーズですが以下の図のように、①ヘッドレスセットアップ（今回）をやったあと、インターネット公開にむけてセキュリティ対策として②Rasberry Pi の堅牢化を行い、③インターネット側から直接Rasberry Pi内に起動したWebサーバーにアクセスできるようにします

第1回の今回は、ラズパイの入手から初期セットアップ手順に関する内容です。

Windows 11のPCだけでOSの書き込みからSSH接続までを完了させた手順を、実測値つきでご紹介します。SDカードを挿して電源を入れてから、SSHでログインできるまでは約3分でした。

用意するもの

• Raspberry Pi 5本体・・・本稿では4GBモデルを使います。
• microSDカード・・・今回は64GB。初回起動時に全容量まで自動拡張されます
• Rasberry Pi5用のヒートシンク・・・熱対策用
• USBカードリーダー・・・SDカードにラズパイイメージを書き込みます
• Windows 11のPC
• USB-C電源（Raspberry Pi 5は5V/5A給電が推奨で、公式のRaspberry Pi 27W USB-C Power Supplyなどが該当します。5V/3A級の充電器でも構成によっては起動できますが、電力不足による制限や不安定動作が起きる可能性があります）

実機のセットアップ

組み立て

では、さっそくラズパイを組み立てていきましょう！

これがラズパイです。

まず、熱対策としてヒートシンクをつけていきます。

ヒートシンクをつけるまえに、CPUチップなど発熱するパーツに付属のシリコンゴムっぽい素材を貼り付けていきます。これはサーマルパッド（熱伝導パッド）というやつですね。

はい、すっかりサーマルパッドをはりつけましたので、次にヒートシンク本体を取り付けましょう。

絶縁プラスチックでできたネジでこんなふうに裏側からヒートシンクをとめてできあがり。

ヒートシンク本体がとりつけられました。

ファン用電源コネクタがラズパイ基盤上部にあるので、そこにヒートシンク側から出た電源ケーブル差し込みます。

ちなみに、SDカードはまだ挿しません。何もはいっていないので挿しても何もできません。

さて、ここまで数分で終わると思います。

次に、ソフトウェアをやっていきましょう。

モニターなしでラズパイをセットアップしていく

さっそくソフトウェアをセットアップしていきましょう。
今回はCLIのみでセットアップしていきます。つまりヘッドレスセットアップですね。

動作確認した環境は、

・書き込みソフト：Raspberry Pi Imager 2.0.8
・書き込んだOS：Raspberry Pi OS 64-bit（Debian 13 trixieベース、カーネル6.18）
・作業PC：Windows 11 Proです。

手順1: 書き込み先の物理ディスク番号を確認する

まずラズパイに差し込むSDカードを作る作業からです。

そのためには、専用の書き込みソフト「Raspberry Pi Imager 2.0.8」をつかいます。

SDカードへの書き込みは物理ディスク単位で行うため、最初にディスク番号を確認します。

Raspberry Pi Imager 2.0.8には、内蔵ドライブなど書き込み対象外のデバイスへの書き込みを拒否する安全機構がありますが、それでも、別のUSBストレージを取り違えればデータを消してしまうため、ディスク番号・容量・BusTypeの確認は必ず行ってください。

SDカードをカードリーダーでPCにつなぎ、PowerShellで次を実行します。

Get-Disk

Number FriendlyName           BusType SizeGB
------ ------------           ------- ------
     0 CT4000P3PSSD8          NVMe      3726
     1 Generic- SD/MMC/MS PRO USB       59.5

今回の環境では、内蔵SSDがディスク0、USBカードリーダー経由のSDカードがディスク1と表示されました。容量（59.5GB）とBusTypeがUSBであることからSDカードだと判断できますね。

以降の手順では書き込み先を \\.\PhysicalDrive1 と指定します。ディスク番号はお使いの環境で必ず読み替えてください。

手順2: Raspberry Pi ImagerとOSイメージを用意する

Raspberry Pi Imagerはwingetで入ります。

winget install --id RaspberryPiFoundation.RaspberryPiImager --silent --accept-package-agreements --accept-source-agreements

インストール先は C:\Program Files\Raspberry Pi Ltd\Imager\ です。GUIで使うのと同じ実行ファイルがCLIモードを持っていて、スクリプト用のラッパー rpi-imager-cli.cmd も同梱されています。

OSイメージは公式のダウンロードサイトから取得します。
raspios_arm64_latest というURLは常に最新の64-bit版（デスクトップあり）へリダイレクトされるので、覚えておくと便利です。

curl.exe -L --fail -o C:\qualiteg_examples\raspi\raspios.img.xz https://downloads.raspberrypi.com/raspios_arm64_latest

サイズは約1.3GBでした。xz圧縮のまま書き込みに使えるので、自分で展開する必要はありません。

手順3: 初回起動スクリプトfirstrun.shを作る

ここがヘッドレスセットアップの心臓部です。

Raspberry Pi OSに標準で入っているヘルパー imager_custom と userconf を呼び出して、ホスト名、SSH、ユーザー、Wi-Fi、キーボード配列、タイムゾーンをまとめて設定します。ファイル名は firstrun.sh とし、置き場所はどこでも構いません（次の手順で書き込み時にパスを渡します）。

#!/bin/bash
# set +e は途中のコマンドが失敗しても最後の後始末まで進めるための指定。
# 設定が反映されないときは、各コマンドの成否を個別に確認すること
set +e

/usr/lib/raspberrypi-sys-mods/imager_custom set_hostname raspberrypi
/usr/lib/raspberrypi-sys-mods/imager_custom enable_ssh
/usr/lib/userconf-pi/userconf 'pi' '$6$…（openssl passwd -6 で生成したハッシュ）'
/usr/lib/raspberrypi-sys-mods/imager_custom set_wlan 'your-ssid' 'your-wifi-password' 'JP'
/usr/lib/raspberrypi-sys-mods/imager_custom set_keymap 'jp'
/usr/lib/raspberrypi-sys-mods/imager_custom set_timezone 'Asia/Tokyo'

rm -f /boot/firstrun.sh /boot/firmware/firstrun.sh
sed -i 's| systemd.run.*||g' /boot/cmdline.txt /boot/firmware/cmdline.txt 2>/dev/null
exit 0

SSIDとWi-Fiパスワード（上記スクリプトの'your-ssid' 'your-wifi-password'の部分）はご自身のものに置き換えてください。

ーザーのパスワードは平文ではなくSHA-512ハッシュで渡します。ハッシュはGit Bashなどで次のように作れます。

openssl passwd -6 '設定したいパスワード'

末尾の2行は、スクリプトが自分自身を削除して通常起動に戻すための後始末です。Imagerが起動設定（cmdline.txt）に仕込むエントリを外しています。

ひとつだけ重要な注意があります。

このファイルの改行コードは必ずLFにしてください。

Windowsのエディタで作るとCRLFになりがちで、CRLFのままだと初回起動時にスクリプトが失敗します。SSHは有効にならず、Wi-Fiにもつながらず、モニターがないので失敗の様子も見えないという、なかなかつらい状態になります。

セキュリティ上の注意もひとつ。firstrun.sh にはWi-Fiパスワードが平文で入ります。Gitへのコミットや共有フォルダへの配置は避け、Windows側に残った作業用ファイルも不要になったら削除してください。

手順4: CLIでSDカードに書き込む

物理ディスクへの書き込みには管理者権限が必要なので、PowerShellから昇格つきで実行します。UACのダイアログが出たら許可してください。

$imgr = 'C:\Program Files\Raspberry Pi Ltd\Imager\rpi-imager.exe'
$opts = @('--cli', '--debug', '--disable-eject',
          '--first-run-script', 'C:\qualiteg_examples\raspi\firstrun.sh',
          '--log-file',         'C:\qualiteg_examples\raspi\flash-log.txt',
          'C:\qualiteg_examples\raspi\raspios.img.xz',
          '\\.\PhysicalDrive1')
Start-Process -FilePath $imgr -ArgumentList $opts -Verb RunAs -Wait

使っているオプションの意味です。

書き込み後の読み戻し検証（ベリファイ）はデフォルトで有効です。実測では、1.3GBのxzイメージの展開に53秒、書き込みと検証を合わせて5分ほどで完了しました。書き込みの遅いSDカードだとログに書き込みレイテンシの警告が出ますが、Imagerが自動でバッファ量を調整して続行するので、そのまま待てば大丈夫です。

進捗表示について補足します。今回のように Start-Process -Verb RunAs で昇格して起動した構成では、元のPowerShell側では進捗を確認できませんでした。そのため --log-file を指定し、ログファイルで進捗と結果を確認しています。ログの最後に succeeded と出ていれば成功です。

手順5: 電源を入れて3分待ち、SSHで接続する

書き込みが終わったSDカードをラズパイ5に挿しましょう。

そして、USB-C電源をつなぐだけで起動します。

Raspberry Pi 5には電源ボタンもありますが、通常の初回起動ではボタン操作は不要です。初回はファイルシステムの自動拡張、firstrun.sh の実行、再起動が順に走るので、2〜3分待ちます。基板の緑のLEDが点滅していれば起動処理中です。

待ったら、WindowsのターミナルからSSHで接続します。

ssh pi@raspberrypi.local

raspberrypi.local という名前はmDNSという仕組みで解決されます。Windows 11は標準で対応しているので、追加のソフトは要りません。今回の実測では、SDカードを挿して電源を入れてから約3分でSSHポートが開き、初期設定したユーザーでログインできました。

ログイン後の状態も確認しました。uname -a、vcgencmd measure_temp、df -h の出力の抜粋です。

Linux raspberrypi 6.18.34+rpt-rpi-2712 #1 SMP PREEMPT Debian 1:6.18.34-1+rpt1 (2026-06-09) aarch64 GNU/Linux
temp=34.0'C
/dev/mmcblk0p2   58G  6.6G   49G  12% /

64GBカードの全域がルートファイルシステムに拡張済みで、CPU温度は34.0度、Wi-Fi経由でIPv4アドレスも取得できていました。

ここまでくれば、あとは普通のLinuxマシンとして使えます。

ハマりどころと回避策

今回の作業で実際に踏んだ罠を表にまとめます。

最後のplinkの罠は、SSH接続までスクリプトで自動化したい人向けの補足です。手でsshコマンドを打つ分には遭遇しません。

まとめ

モニターなしのRaspberry Pi 5セットアップは、次の5点を押さえれば安全に完走できます。

• 書き込み前に Get-Disk で物理ディスク番号を確認する（最重要）
• OSイメージは raspios_arm64_latest から取得し、xzのまま書き込む
• firstrun.sh にWi-Fi、SSH、ユーザー設定を仕込む。改行コードはLF
• 書き込みは管理者権限で実行し、結果は --log-file のログで確認する
• 初回起動は3分待ってから ssh pi@raspberrypi.local

ログインできたら、次の一手として最初にパスワードの変更とパッケージ更新をおすすめします。

passwd
sudo apt update && sudo apt full-upgrade -y

デスクトップ画面を使いたくなったら、sudo raspi-config でVNCを有効にすると、Windowsからリモートデスクトップのように操作できます。

このあたりは別の記事で紹介する予定です。

それでは、また次回お楽しみに！

参考リンク

• Raspberry Pi Imager（公式ダウンロードページ）
• Raspberry Pi OS イメージ一覧（公式ダウンロードサイト）
• Cloud-init on Raspberry Pi OS（公式ブログ。firstrun.sh方式からcloud-initへの移行について）
• PuTTY 公式サイト（plink のダウンロード）

こんにちは！

LINE Botを作ろうとして最初にぶつかる壁は、コードではなくWebhookです。

LINEのMessaging APIは、ユーザーがBotに送ったメッセージを、LINEのサーバーからこちらのサーバーへHTTPSのPOSTで通知してきます。

この受け口（Webhook URL）にはインターネットから届くHTTPSのURLしか指定できず、開発中の http://localhost:5000 をそのまま書くことはできません。

トンネルツールで一時URLを発行して回避する方法が定番ですが、今度は別の問題が待っています。トンネルの方式によっては、起動のたびにランダムなURLが発行されます。その場合、開発を再開するたびにLINE Developersコンソールを開いてWebhook URLを書き換えることになります。コードを直すたび、翌日再開するたび、まずURLの貼り直しから。これが地味に堪えます。

結論から言うと、

ローカルPCの開発サーバーに「変わらない公開URL」を1本付けてしまえば、Webhook URLの設定は最初の1回だけで終わります。

この記事では、LINE公式アカウントの開設からMessaging APIの設定、PythonでのWebhook受信サーバーの実装、固定URLでの公開、スマホの実機でBotが返事するところまでを、最初から最後まで書きます。

手順・コマンド・画面はすべて筆者が実際に動かして確認したものです
（確認日は2026年8月11日。LINE側の画面は変わることがあります）。

なお、Botの中身は受け取ったメッセージをそのまま返す最小構成にしてあります。この記事のゴールは「LINEからのWebhookがローカルのPythonに届き、返事がスマホに出る」までの経路を作りきることです。

手順1: LINE公式アカウントを作る（2026年8月の現行手順）

まず知っておきたいのは、

Messaging APIチャネルはLINE Developersコンソールから直接作れなくなった

現在この画面には
「LINE公式アカウントを作成した後、LINE Official Account Manager上でMessaging APIの利用を有効にしてください」
と案内が出ます。

現行の流れはこうなります。

1. LINEビジネスID（LINEヤフーBusiness ID）を作る。メールアドレスだけで作成でき、LINEアプリのアカウントは不要です
2. LINE Developersコンソールに開発者登録し、プロバイダーを作る
3. LINE公式アカウントを作る。作成時にビジネスマネージャー組織との接続を求められるので、組織がなければその場で作成します（組織名は空欄ならアカウント名と同じになります）
4. LINE Official Account ManagerでMessaging APIを有効にする

プロバイダーは、このBotを提供する個人・企業・団体を表す単位です。LINEログインなどと組み合わせた場合には同意画面にも表示されるため、会社名やサービス名など、利用者が提供元を判断できる名前にしておくのが無難です
（筆者は「Qualiteg」で作りました）。

公式アカウントの作成フォームでは、アカウント名（友だちリストとトーク画面に表示されるBotの名前）、会社・事業者名、業種などを入力します。ここでひとつ注意があります。公式アカウントの新規作成には、電話番号認証（SMSまたは通話）が必要です。画面の案内によれば、認証に使った電話番号が友だちに公開されることはありません。

アカウントの種別は「未認証アカウント」のままで大丈夫です。認証済アカウント（緑色の認証バッジ）はLINE内の検索対象になるなどのメリットがありますが、開発用のBotには必要ありません。

手順2: Messaging APIを有効にして、鍵を3つ手に入れる

公式アカウントができたら、LINE Official Account Manager（管理画面）を開き、設定の「Messaging API」から「Messaging APIを利用する」を押します。ここでプロバイダーを選びますが、一度ひもづけたプロバイダーはあとから変更できません。手順1で作ったプロバイダーを選んでください。

有効になると、この画面にChannel IDとChannel secretが表示されます。

Botの開発に必要な「鍵」は3つあります。

チャネルアクセストークンだけはDevelopersコンソール側での発行操作が必要です。発行したトークンとChannel secretは、コードに直書きせず環境変数で渡します（次の手順で使います）。

手順3: Webhookを受ける最小のBotを書く

サーバーはPythonで書きます。公式SDK（line-bot-sdk）とFlaskを入れます。

pip install line-bot-sdk flask

筆者環境ではline-bot-sdk 3.25.0とflask 3.1.3が入りました（Python 3.11）。

app.py（全文）

import os

from flask import Flask, request, abort
from linebot.v3 import WebhookHandler
from linebot.v3.exceptions import InvalidSignatureError
from linebot.v3.messaging import (
    ApiClient,
    Configuration,
    MessagingApi,
    ReplyMessageRequest,
    TextMessage,
)
from linebot.v3.webhooks import MessageEvent, TextMessageContent

app = Flask(__name__)

configuration = Configuration(access_token=os.environ["LINE_CHANNEL_ACCESS_TOKEN"])
handler = WebhookHandler(os.environ["LINE_CHANNEL_SECRET"])


@app.route("/health", methods=["GET"])
def health():
    return "OK"


@app.route("/callback", methods=["POST"])
def callback():
    signature = request.headers.get("X-Line-Signature", "")
    body = request.get_data(as_text=True)
    try:
        handler.handle(body, signature)
    except InvalidSignatureError:
        abort(400)
    return "OK"


@handler.add(MessageEvent, message=TextMessageContent)
def handle_message(event):
    reply = f"「{event.message.text}」を受け取りました！"
    with ApiClient(configuration) as api_client:
        MessagingApi(api_client).reply_message(
            ReplyMessageRequest(
                reply_token=event.reply_token,
                messages=[TextMessage(text=reply)],
            )
        )


if __name__ == "__main__":
    app.run(host="127.0.0.1", port=5000)

やっていることは3つだけです。/callback でLINEからのPOSTを受け、X-Line-Signature ヘッダーをChannel secretで検証し（この検証がSDKに入っているので、自前実装は不要です）、テキストメッセージが来たら「「◯◯」を受け取りました！」と返します。

なお、このコードはローカル開発用の最小例です。本番運用では、Webhookへの応答（200）を速やかに返し、イベントの処理は非同期にする構成がLINE公式ドキュメントで推奨されています。

手順2の鍵を環境変数に入れて起動します。

$env:LINE_CHANNEL_SECRET = '（Channel secret）'
$env:LINE_CHANNEL_ACCESS_TOKEN = '（チャネルアクセストークン）'
python app.py

http://localhost:5000/health が OK を返せば起動しています。この時点ではまだlocalhostの中の話で、LINEからは届きません。

手順4: ローカルに「変わらない公開URL」を付ける

ここが本題です。localhost:5000に、再起動しても変わらないHTTPSのURLを付けます。

この記事では、当社が開発・運営しているWireCanalで進めます（自社サービスなので、そこは割り引いて読んでください）。

なお、固定のURLを使うこと自体はWireCanal固有の話ではなく、他のトンネルサービスの固定ドメイン機能でも同じ考え方で実現できます。

ダッシュボードでcanal（トンネルの公開口）を作ります。種類はHTTP、転送先に localhost:5000 を指定すると、公開URLが1本発行されます。

このURLはランダムな文字列で発行されますが、起動のたびに変わることはありません。 PCを再起動しても、エージェントを止めて翌日つなぎ直しても、同じURLで受けられます。プランによる違いだけ正確に書いておくと、無料プランの公開URLは「使っている限り有効」（エージェントの最終接続から72時間で失効）で、毎日開発する分には同じURLのままです。3日以上止めても失効しない永続URLにしたい場合はライトプラン以上になります（筆者はライトプランで検証しました。スクリーンショットの「予約（永続）」はその表示です）。

次に、PCへエージェントを入れて起動します。セットアップガイド（wirecanal.com）のとおり、PowerShellで1行です。

irm https://download.wirecanal.com/install.ps1 | iex

ダッシュボードから接続設定ファイル（wirecanal.json）をダウンロードしてエージェントと同じフォルダに置き、起動します。

.\wirecanal.exe -config wirecanal.json

ダッシュボードに「接続されました！」と出れば、公開URLへのアクセスがlocalhost:5000へ届く状態です。

外から確認してみます。

> curl https://7pqvyoih.ja100.wirecanal.com/health
OK

手順3のFlaskが、インターネット越しに応答しました。受信ポートの開放もVPNも使っていません（エージェントは外向きの接続だけで通信します）。

手順5: Webhook URLを設定して検証する

LINE Developersコンソールに戻り、チャネルの「Messaging API設定」タブでWebhook URLを設定します。公開URLに、app.pyで受けているパス /callback を付けたものです。

https://（あなたの公開URL）/callback

設定したら、その下の「Webhookの利用」を必ずオンにします。URLを入れただけではWebhookは届きません。

「検証」ボタンを押すと、LINEのサーバーからこのURLへ実際にテスト接続が飛びます。「成功」が出れば、LINE→トンネル→ローカルのFlaskまでの経路が通っています。

つまずきポイント: 返事が二重に届く

これで動くはずなのですが、実際にスマホからメッセージを送ると、筆者の環境では奇妙なことが起きました。Botの返事の前に、身に覚えのない定型文が届くのです。

メッセージありがとうございます！申し訳ありませんが、このアカウントでは個別のお問い合わせを受け付けておりません。

正体は、公式アカウントに最初から入っている応答メッセージ（自動応答）です。筆者が新規作成したアカウントでは「Default」という一律応答が有効になっており、Webhookとは別枠で動くため、Botの返事と定型文の両方がユーザーに届いていました。

二重返信が起きたら、Official Account Managerで応答メッセージの状態を確認します。止め方は2つあり、応答メッセージ一覧で個別のメッセージを利用停止にするか、「設定」→「応答設定」で機能全体の「応答メッセージ」をオフにします。いま実際に送られる状態かどうかは、応答メッセージ一覧の上部にある「現在のステータス」で確認できます（「利用中。応答メッセージは送信されています」と出ていたら、まだ送られます）。筆者はここのステータスが「利用中」のままなのに気づかず、1回むだにテストしました。

スマホから使ってみる

友だち追加用のQRコード（Official Account Managerの「友だち追加ガイド」にあります）をスマホのLINEで読み取り、Botを友だち追加してメッセージを送ります。

「こんにちは」と送ると、即座に「「こんにちは」を受け取りました！」が返ってきます。サーバー側のログにも、LINEからのPOSTが記録されています。

127.0.0.1 - - [11/Aug/2026 00:24:32] "POST /callback HTTP/1.1" 200 -

ここまでで、スマホのLINE→LINEプラットフォーム→固定の公開URL→ローカルPCのFlask→返信、という経路が全部つながりました。

まとめ: URLを書き換える作業は、もう発生しない

この構成のいちばんの利点は、翌日の開発再開が「エージェントとapp.pyを起動するだけ」になることです。公開URLが変わらないので、LINE Developersコンソールを開き直してWebhook URLを貼り替える作業がそもそも発生しません。コードを直したらapp.pyを再起動するだけで、同じURLのまま試せます。

最後に、今回の構成の勘所を置いておきます。

それでは、また次回、お会いしましょう！

出典・参考

• Messaging APIを始めよう（LINE Developers公式ドキュメント）
• Messaging APIの概要（LINE Developers公式ドキュメント）
• line-bot-sdk-python（LINE公式SDK・GitHub）
• WireCanal 料金プラン
• WireCanal セットアップガイド（Windows）

関連記事

• ngrokとWireCanalは何が違う？開発元が料金・運用・MCP設計を比較
• 自宅PCのローカルLLMを外出先のスマホから使う。Ollama＋Open WebUI+WireCanal

こんにちは！

自宅のGPU入りPCでローカルLLMを動かしていると、外出先でふと「あれ、手元のモデルに聞きたい」という場面がやってきます。

家のPCには自分で選んだり、自分でチューニングしたモデルが載っていて、会話履歴の保存先も自分のPCの中にできる。

せっかく作った環境なので、スマホからも使いたくなります。

かといって、自宅ルーターのポートを開けて外へさらすのは怖い。

結論から言うと、

Windows PC 1台だけで、外出先のスマホから自宅のローカルLLMと日本語チャットできる状態

まで持っていけます。DockerもWSLも使いません。ポート開放もしません。

この記事では、Ollamaとgemma4でローカルLLMを動かし、Open WebUIでチャット画面を付けて、トンネルで公開し、スマホの実機から使うまでの手順を最初から最後まで書きます。

手順・コマンド・画面はすべて筆者が実際に動かして確認したものです。検証機はWindows 11 Pro＋GeForce RTX 3090 Ti（24GB）ですが、モデルを選べば12GBクラスのGPUでも同じ構成が組めます。

なお、この記事は「自分ひとりで、家のPCのLLMを外から使う」までを扱います。

手順1: Ollamaを入れてgemma4をGPUで動かす

まず、LLMを動かすランタイムのOllamaを入れます。

Ollama公式サイトからOllamaSetup.exeをダウンロードして実行するだけです。ウィザードを進めれば入ります（筆者はサイレント導入 OllamaSetup.exe /VERYSILENT で入れました。動作確認したのはv0.32.6）。

GPUは自動認識されるので、CUDAの手動セットアップは要りません。

ひとつだけ先に決めておきたいのがモデルの置き場所です。既定ではCドライブのユーザーフォルダにモデルがたまっていきます。1モデルで10GB前後を平気で食うので、大きいドライブに逃がしたい場合はシステム環境変数で指定します。
わたしは、Dドライブを置き場にしました。

OLLAMA_MODELS = D:\qualiteg_examples\ollama-models

モデルは、ollamaのライブラリの人気上位から、日本語が自然で手元のGPUに収まるgemma4（ダウンロード9.6GB）を選びました。

ollama pull gemma4

取得できたら動作確認です。

> ollama run gemma4 "日本の首都は"
東京（とうきょう）です。

GPUに載っているかは ollama ps で見えます。

NAME             ID              SIZE      PROCESSOR    CONTEXT
gemma4:latest    c6eb396dbd59    3.4 GB    100% GPU     32768

PROCESSORが100% GPUになっていれば成功です。CPUに落ちていると応答が桁違いに遅くなるので、ここは必ず確認してください。なお、ダウンロードは9.6GBですが、筆者のOllama 0.32.6ではps上のSIZEが3.4GBと表示されました（加工せず実測のまま載せています）。

手順2: 「最初の1回だけ返事が来ない」を先に潰す

構築中にいちばん焦ったのがこれでした。

しばらく放置したあとに質問すると、画面が数十秒うんともすんとも言わない。壊れたのかと思ってログを見ると、推論自体は2.1秒で終わっていました。

犯人はOllamaの既定動作です。未使用のまま5分たつと、モデルをGPUから降ろします。次の質問が来た瞬間に9.6GBを積み直すので、その間ずっと無反応に見えるわけです。

外からスマホで使う用途だと「たまに開いて1問聞く」が典型パターンなので、毎回この再ロードを踏むことになります。システム環境変数で常駐させておきましょう。

OLLAMA_KEEP_ALIVE = -1

設定後にOllamaを再起動して ollama ps を見ると、UNTIL列がForeverになります。

NAME             ID              SIZE      PROCESSOR    CONTEXT    UNTIL
gemma4:latest    c6eb396dbd59    3.4 GB    100% GPU     32768      Forever

これで何時間放置しても最初の1問から即答します。GPUをゲームや学習にも使うPCなら、-1のかわりに 24h のような値で妥協点をさぐりましょう。

手順3: Open WebUIはpipで入る（Dockerは要らない）

チャット画面はOpen WebUIを使いました。

ChatGPTライクなUIで、Ollamaを自動で見つけてくれる定番のOSSです。

Open WebUIはpipインストールが公式にサポートされています。

Open WebUIがサポートするPythonは3.11と3.12で、3.13は未対応です
（公式の推奨は3.11。筆者はcondaで3.11.15の環境を作りました。venvでも同じです）。

pip install open-webui

依存パッケージが多いので数分かかります。入ったら、環境変数を2つ与えて起動します（動作確認したのはv0.11.0）。

$env:OLLAMA_BASE_URL = 'http://localhost:11434'
$env:DATA_DIR = 'D:\qualiteg_examples\open-webui-data'
open-webui serve --port 3000

OLLAMA_BASE_URLは手順1のOllama、DATA_DIRはユーザー情報やチャット履歴の置き場です。

筆者環境では起動から約35秒で http://localhost:3000/health が {"status":true} を返しました。

ブラウザで http://localhost:3000 を開くと、最初のアカウント作成を求められます。ここで作る最初のアカウントが管理者になります。公開はまだ先ですが、癖として「公開する前に管理者登録を済ませる」を徹底してください。先に公開してしまうと、たまたまURLを踏んだ第三者が管理者になれてしまいますので注意しましょう。

手順4: 受信ポートを開けずに外へ公開する

ここからが本題です。localhost:3000を外出先のスマホから届く場所に出します。

外に出す方法はいくつかあります。

今回はトンネル型を使います。

自宅側からトンネル事業者へ張った外向きの接続だけで通信するので、自宅の受信ポートは1つも開きません。

この記事では、当社が開発・運営しているWireCanalで進めます。本記事の用途であれば無料プランで十分足ります。カード登録も不要です。

手順は3つだけです。

まず、WireCanalのダッシュボードでcanal（トンネルの公開口）を作ります。種類はHTTP、転送先に localhost:3000 を指定すると、公開URLが1本発行されます。

次に、自宅PCへAgentを入れます。セットアップガイド（wirecanal.com）のとおり、PowerShellで1行です（動作確認したAgentはv0.18.0です）。

irm https://download.wirecanal.com/install.ps1 | iex

ダッシュボードからwirecanal.json（接続設定）をダウンロードしてAgentと同じフォルダに置けば準備完了です。

最後に、AgentをWindowsサービスとして登録します。手動起動でも動きますが、サービスにしておくとPCを再起動しても勝手に復帰します。

.\wirecanal.exe service install -config wirecanal.json

wirecanal service install: service "wirecanal-agent" installed (auto start; restarts 5s after a failure)
wirecanal service install: service started.

これで公開URLにアクセスすると、自宅のOpen WebUIのログイン画面が表示されます。PCのブラウザで一度フルフロー（ログイン→質問→応答）を通して、動くことを確かめてから外に持ち出しましょう。

手順5: スマホから使う

あとは外出先のスマホで公開URLを開くだけです。

あらかじめ、canal詳細画面でcanalのURLのQRを表示させてスマホで読ませておくとURL入力の手間が省けて便利です

手順3で作ったアカウントでログインすると、家のPCで見ていたのと同じチャット画面がそのまま出ます。

モバイル回線から、自宅のRTX 3090 Ti上のgemma4が日本語で答えてきます。

モデル本体とOpen WebUIの会話履歴の保存先は自宅のPCです（スマホとの通信そのものは、トンネルの中継サーバーを経由します。公開URLはHTTPSです）。

これで自分だけの専用LLMに外出先からアクセスできました

インターネット側に公開するときの安全の考え方

今回の構成では、Open WebUI自身のログインを門番にします。手順3で「公開すWireCanal側にもIP・国・時間帯といったアクセス保護が標準で付いているので、用途に合わせて併用してください。

canalはスマホブラウザからいつでも一時停止・再開ができるので、使うときだけ回線をひらき、使わない期間はcanalを止めておく、というのも簡単にできます。

本記事は「ポート開放なしで外から使う」ための構成例として読んでください。

常駐化していつでも使えるようにする

最後に、PCの再起動や再ログオンに耐える形にします。Agentは手順4でサービス化済みなので、残るはOllamaとOpen WebUIです。タスクスケジューラに「PC起動時」のタスクとして登録します（PowerShellを管理者で実行）。

$action   = New-ScheduledTaskAction -Execute 'powershell.exe' `
  -Argument '-NoProfile -ExecutionPolicy Bypass -File D:\qualiteg_examples\open-webui\run-open-webui.ps1'
$trigger  = New-ScheduledTaskTrigger -AtStartup
$settings = New-ScheduledTaskSettingsSet -ExecutionTimeLimit ([TimeSpan]::Zero) `
  -RestartCount 5 -RestartInterval (New-TimeSpan -Minutes 1)
Register-ScheduledTask -TaskName 'openwebui-serve' -Action $action -Trigger $trigger `
  -User 'SYSTEM' -RunLevel Highest -Settings $settings

run-open-webui.ps1の中身は手順3の起動コマンドとほぼ同じですが、1か所だけ重要な違いがあります。SYSTEMで動くタスクはconda activateを通らないので、open-webuiは環境内の実行ファイルを絶対パスで指定します。

$env:OLLAMA_BASE_URL = 'http://localhost:11434'
$env:DATA_DIR = 'D:\qualiteg_examples\open-webui-data'
& 'C:\tools\Anaconda3\envs\openwebui\Scripts\open-webui.exe' serve --port 3000

ポイントは、実行時間の制限を無効にすること（既定の72時間で切られます）と、SYSTEMで動かしてログオンと切り離すことです。Ollama側も同じ型で ollama serve のタスクを作ります。こちらもollama.exeを絶対パスで指定してください（筆者環境では C:\Users\<ユーザー名>\AppData\Local\Programs\Ollama\ollama.exe）。通常のインストーラ版はログオン時の自動起動も入るので、二重起動にならないよう自動起動側は無効にしておきます。

もうひとつ注意点があります。SYSTEMタスクから起動するPowerShellスクリプトに日本語コメントを書くと、文字コードの解釈違い（BOM無しUTF-8をANSIとして読む）で動かないことがあります。スクリプトはASCIIだけで書くか、BOM付きUTF-8で保存してください。ここでも30分溶かしました。

まとめ: 家のGPUが、ポケットの中から使える

やったことを並べると、インストーラ1本、pip 1回、トンネル設定、いくつかの環境変数でした。大げさな仕掛けなしに、自宅のGPUマシンが「自分専用のLLMサーバー」になります。

最後に、今回の構成の勘所を置いておきます。

それでは、また次回、お会いしましょう！

出典・参考

• Ollama 公式サイト（ダウンロード）
• Ollama FAQ（keep_alive の仕様）
• Open WebUI 公式ドキュメント（pip でのインストール・Python 要件）
• WireCanal セットアップガイド（Windows）

関連記事

• MCPサーバーの作り方 — PythonとFastMCPで自作して、データベースにAIが日本語で答えるまで（前編）
• MCPサーバーの作り方 — 自作MCPサーバーをWeb版のChatGPT・Claudeから使う（後編）

こんにちは！Qualitegプロダクト開発部です！

前編では、PythonとFastMCPでMCPサーバーを自作し、手元のClaude Codeから売上データベースに日本語で聞けるところまで作りました。後編の今回は、予告どおりその続きです。

手元（localhost）で動いているこのMCPサーバーを、Web版のChatGPTとClaudeから使えるようにします。

先に結論を言うと、サーバーのコードは1行も変えずに、ブラウザのChatGPTとClaudeの両方から「職業別の売上トップ3を教えて」が通るようになりました。返ってきた数字は前編の実測値と完全に一致しています。到達性・HTTPS・OAuth認証という3つの壁は、当社のWireCanalで越えます。前編の最後に開示したとおり自社サービスですが、この記事の手順は無料（フリープラン）で使える機能だけでできています。クレジットカードの登録も要りません。

前編を読んでいない方はこちらからどうぞ。

MCPサーバーの作り方（前編）｜ PythonとFastMCPで売上DBをAIにつなぐ（当ブログ）

なぜ localhost のままでは Web版から使えないのか

前編のサーバーはHTTPモードで起動すると http://127.0.0.1:9904/mcp がMCPエンドポイントになります。CLI版のClaude Codeは同じPCの中にいるので、このURLで届きます。

Web版は事情がまったく違います。ChatGPTもClaudeも、コネクタへの接続リクエストを投げてくるのはあちら側のサーバーです。あなたのブラウザではありません。だから壁は3つあります。

ひとつめは到達性。一般的な家庭・社内ネットワークでは、手元のPCはNATやファイアウォールの内側にあって、そのままでは外から到達できません。ふたつめはHTTPS。コネクタに登録するURLは https:// が前提です。3つめが認証。外から届くようにしたということは、世界中の誰からも届くということなので、認証なしで社内データベースにつながるサーバーを置く選択肢はありません。

このうち3つめが、いちばん手ごわい相手です。

ChatGPTもClaudeも、構成によっては認証なしのリモートMCPに接続できます。ただ、社内データベースに到達するサーバーを無認証で公開する選択肢はないので、MCP Authorization仕様に沿ったOAuthで守ることになります。そうすると、認証情報のないアクセスに401を返し、認可サーバーの情報を公開し、クライアント情報を扱い、認可画面・トークン発行・リクエストごとの検証までを用意する必要があります。この一式を自前で実装すると、ツール本体（前編で書いた200行）よりはるかに大きな仕事になります。ここで力尽きて「Web版はあきらめてCLIだけで使う」となりがちなのが、リモートMCPの現実でした。

WireCanal がこの3つをまとめて引き受ける

そこで後編では、当社が提供しているセキュアトンネルサービスのWireCanalを使います。

仕組みは図3のとおりです。手元のPCでAgentという小さなプログラムを動かすと、AgentがWireCanalのサーバーへ外向きに接続してトンネルを張ります。受信ポートの開放もVPNも要りません。外の世界には https://＜名前＞.wirecanal.com という公開URLができて、そこへ届いたリクエストがトンネル経由で手元の 127.0.0.1:9904 に流れます。

OAuthも同じURLが引き受けます。認証なしのアクセスには401を返し、ChatGPT・Claudeからの接続はWireCanalの認可画面で持ち主が許可したものだけが通ります。

もうひとつ、MCPならではの仕掛けがあります。外のAIに見せてよいツールを、手元の設定ファイル（wirecanal.json）で選べます。 既定は全ツール拒否で、許可リストに書いたツールしか公開されません。この許可リストの正本は手元のファイルにあります。ダッシュボードからの変更は提案として扱われ、手元側で承認・反映しない限り公開ツールは増えません。

それでは、前編のサーバーが 127.0.0.1:9904 で動いている状態から始めます。

手順1: ダッシュボードで canal を作る

WireCanalのダッシュボード（app.wirecanal.com）にアカウント登録すると、「canal」という公開経路を作れます。作成ウィザードは5ステップです。

まず種類。「MCP 社内MCPサーバーをAIサービスへ公開」を選びます。

次に「どのAIから使いますか」。今回はClaudeとChatGPTの両方にチェックを入れました。ここで選んだAIに合わせて、OAuthの接続設定がcanalに自動で入ります。

公開アドレスは「おまかせサブドメイン」のまま進めます。転送先には、前編のサーバーが待っている 127.0.0.1:9904 を入れます。

確認画面で公開URLが決まります。筆者環境では https://mh1sjzat.ja100.wirecanal.com が発行されました。

「作成する」を押すと、canalの詳細画面に移ります。ここまででサーバー側の設定は終わりです。固定IPも証明書の取得も、何もしていません。

手順2: 見せてよいツールを wirecanal.json に書く

canal詳細の「セットアップ」タブに、接続ファイル（wirecanal.json）が表示されます。ダウンロードしてそのまま使えますが、MCPの場合はひとつだけ手を入れます。tools.allow に、外のAIへ見せてよいツール名を書きます。

wirecanal.json（tools.allow に2本を追記したもの）

{
  "access_key": "ck_（canalごとに発行される接続キー）",
  "forward_target": "127.0.0.1:9904",
  "mode": "mcp",
  "tools": {
    "default": "deny",
    "allow": ["execute_sql_query", "get_database_stats"]
  },
  "lang": "ja"
}

既定は "default": "deny" かつ allow が空、つまりつないだ直後は全ツール拒否から始まります。前編のサーバーはツールが2本だけなので全部書きましたが、たとえば社内のMCPサーバーに20本ツールがあっても、ここに書いた2本以外は外のAIからは見えません。一覧（tools/list）にも出ません。

この安全側に倒した初期値は、前編で書いた「AIに全部見せない」設計と同じ考え方です。公開範囲を決める台帳の正本が手元にあるので、ダッシュボード側の操作だけでは公開ツールは増えません。反映には手元での承認が要ります。

手順3: Agent を起動する

セットアップタブの案内どおり、公開したいサーバーが動いているマシンにAgentを入れて起動します。Windowsなら2コマンドです。

irm https://download.wirecanal.com/install.ps1 | iex
.\wirecanal.exe -config wirecanal.json

1行目がAgentのダウンロード（カレントフォルダに wirecanal.exe が置かれます）、2行目が起動です。組織のセキュリティポリシーでリモートスクリプトの直接実行が禁止されている場合は、install.ps1 をいったんファイルとして保存し、中身を確認してから実行してください。筆者環境の起動ログがこちらです。

ダッシュボード側にも数秒で「接続されました！」が出て、この時点でトンネルが開通しています。

認証なしのアクセスが 401 で止まることを確かめる

つなぐ前に、公開URLが「誰でも呼べる状態」になっていないことを確かめておきます。前編で「効いていない防御ほど怖いものはない」と書いたとおり、ここは実際に叩いて見るのが確実です。

curl -i -X POST https://mh1sjzat.ja100.wirecanal.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1}'

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mh1sjzat.ja100.wirecanal.com/.well-known/oauth-protected-resource"

認証トークンなしのリクエストは、手元のサーバーに届く前に401で止まりました。あわせて WWW-Authenticate ヘッダに resource_metadata が付いています。これはRFC 9728で定義された「保護対象リソースのメタデータ文書」のURLで、認可サーバーそのもののURLではありません。ChatGPTやClaudeはまずこの文書を取得し、そこに書かれた authorization_servers をたどって認可サーバーを見つけ、OAuthの接続手続きを自動で始めます。

Claude から接続する

Web版Claudeの設定から、コネクタの画面を開いて「カスタムコネクタを追加」を選びます。入力するのは名前と、さきほどの公開URLに /mcp を付けたものだけです。クライアントIDやシークレットの欄は空のままでかまいません（末尾に挙げたWireCanal公式ガイドは、クライアントIDとシークレットを手入力する手順で書かれています。筆者環境の2026年8月6日時点では、URLを入れるだけで接続できました）。

「追加」して「連携」を押すと、WireCanalの認可画面に切り替わります。どのcanalへの接続を求められているかが表示されるので、内容を確認して許可します。

接続が済むと、コネクタの詳細にツール一覧が出ます。ここに注目してください。

並んでいるのは、wirecanal.json の allow に書いた2本だけです。

あとは前編のClaude Codeと同じように、チャットで日本語で聞くだけです。既定ではツールを使う前に承認を求められます。

許可すると、Claudeが売上データベースにSQLを投げて答えを返してきました。

経営者 25,621,641円、研究者 24,525,975円、公務員 23,685,112円。前編でClaude Codeが返した集計と同じ、固定シードのダミーデータの実測値どおりです。ブラウザのClaudeから、手元のPCで動くSQLiteまで、ちゃんと一本の道が通っています。

ChatGPT から接続する

ChatGPT側は、未検証のMCPサーバーをつなぐために開発者モードを先に有効にします。筆者環境では、設定の「セキュリティとログイン」にある「開発者モード」をオンにしました（設定の「プラグイン」画面の下にも同じ場所へのリンクがあります）。データを壊しうるコネクタを自己責任で追加する機能なので、リスクの説明をよく読んだうえで進めてください。画面構成はプランや提供時期によって変わることがあります。

次にサイドバーの「プラグイン」から「アプリを作成」。名前とサーバーURL（https://＜名前＞.wirecanal.com/mcp）を入れると、認証欄のOAuth設定は自動で検出されます。

「作成する」のあと「サインイン」に進むと、Claudeのときと同じWireCanalの認可画面が出るので許可します。

使うときは、ひとつだけコツがあります。チャット入力欄の「＋」からいま作ったアプリを選んで、会話に添えてから質問してください。筆者環境では、アプリを添えずに「売上データベースを使って」と文章で頼んだところ、ChatGPTはコネクタではなくWeb検索を始めてしまいました。＋から明示的に選べば確実にMCPサーバーが呼ばれます。

返ってきた表もClaudeと同じ数字です。ローカルのサーバーログにも、ChatGPT側からのリクエストが POST /mcp として記録されていました。

料金

この記事の手順（MCP canalの作成・OAuth認証・おまかせサブドメイン）は、WireCanalの料金ページ（wirecanal.com）の対応表のとおり、フリープランで使えます。クレジットカードの登録も不要です。

つまり、この記事でやったこと（自作MCPサーバーの公開からWeb版ChatGPT・Claudeとの接続まで）は、すべて無料でできます。

フリープランで発行される公開ホスト名は、使っている限り消えません。Agentの接続が生きている間は有効期限が自動延長されます。

逆にAgentを落とすなどして接続を切ると、最後の接続から72時間で失効します（失効しても作り直しはできますがURLが変更されます）。

MCPサーバーを常用するならAgentは動かしっぱなしにするはずなので、実用上はフリープランのままで同じURLを使い続けられます。

好きな名前のサブドメインを予約したい場合は、接続が途切れても消えない永続ホスト名を持てるライト以上が候補になります。ほかにプランで変わるのは、TCP公開（RDPやSSH）がプロ以上、独自ドメインの持ち込みがプレミアム、というあたりです。

なお、この記事のスクリーンショットの一部はライトプランのアカウントで撮っていますが、手順はどれもフリープランの機能だけでできています。

もうひとつ、組織で使うときの話をひとつだけ。今回はcanalの持ち主本人がOAuthの許可を出しましたが、ライト以上では会社の認証基盤（Google WorkspaceなどのOIDC IdP）と連携して、組織のメンバーが自分の会社アカウントで接続許可を受けられるようになります。メンバー全員でMCPサーバーを使う形は、この連載の後の回で実際にやります。

ChatGPTとつなぐときのOAuthは経路側で解決

今回のポイントは、前編のサーバーに1行も手を入れていないことです。localhost向けに書いたMCPサーバーがそのまま、Web版のChatGPTとClaudeの両方から使えました。到達性・HTTPS・OAuthという3つの壁は、サーバーのコードの問題ではなく経路の問題なので、経路側で解決するのが筋がいい、というのが今回の答えです。

公開経路の安全面は二重になっています。入口ではOAuthが認証なしのアクセスを401で止め、その先ではツール許可リストが「見せる2本」以外を隠す。許可リストの正本は手元のwirecanal.jsonにあり、ダッシュボード側の操作だけでは変わりません。変更を反映するには手元での承認が要ります。前編でサーバー内部に作った3段の安全弁（読み取り専用・SELECT検査・実行時間上限）は、そのまま最後の砦として生きています。

ひとつ引っかかったのは、ChatGPTがアプリを自動では選んでくれなかったことでした。最初に知らないと「つながっているのに使われない」ように見えます。同じところで止まる方が多いはずなので、本文に残しました。

検証していないことも書いておきます。今回つないだのは、2026年8月6日時点で開発者モードが表示された筆者のChatGPT Plusアカウントと、Claudeの有料アカウントです。ChatGPTの開発者モードやカスタムMCPアプリの提供対象・画面構成は、プランやアカウントへの展開状況によって変わることがあり、同じ項目がどのアカウントにも表示されるとは限りません。AIサービス側の無料プランでどこまで使えるかも確認していません。また、社内の実データベースへつなぐ場合は、前編で書いたとおり業務別ツールへの分割やアクセスログの監査など、この記事の先にやるべきことがあります。

それでは、また次回、お会いしましょう！

サンプルコード

前編のコードをそのまま使っています。cloneして、DB作成とHTTPモード起動までは次のコマンドです。

qualiteg/mcp-server-tutorial ｜ サンプルコード一式とREADME（GitHub）

git clone https://github.com/qualiteg/mcp-server-tutorial.git
cd mcp-server-tutorial
python -m pip install -r requirements.txt
python db_setup.py
python mcp_server_sales.py --http --port 9904

参考

• MCP Authorization（Model Context Protocol 公式仕様） ※ draft は更新されます。本記事は2026年8月6日時点の内容で確認しています
• OAuth 2.0 Protected Resource Metadata（RFC 9728）
• WireCanal 公式サイト ｜ MCP対応セキュアトンネル
• ClaudeとMCP canalを接続する手順（wirecanal.com のガイド）
• ChatGPTとMCP canalを接続する手順（wirecanal.com のガイド）

関連記事

MCPサーバーの作り方 — PythonとFastMCPでデータベースにAIが日本語で答えるようにする（前編）

MCPサーバーの作り方を、動くコードつきで最初から解説します。PythonとFastMCPでSQLiteの売上データベースをMCP化し、AIに日本語で聞くとAIが自分でSQLを書いて集計まで返すところまで作ります。

Qualiteg BlogQualiteg プロダクト開発部

ngrokとWireCanalは何が違う？開発元が料金・運用・MCP設計を比較

ngrokと同じリバーストンネル方式の国産サービスWireCanalを、開発元が正直に比較します。違いは料金の考え方・運用の場所・AIにつなぐときの許可の置き場所の3つです。

Qualiteg BlogQualiteg プロダクト開発部

こんにちは！
Qualitegプロダクト開発部です！

「ngrok の代替になる国産のトンネルサービスはないか」。

そう検索して、この記事にたどり着いた方も多いはずです。

この記事は、その問いに開発元として正面から答えます。

先にことわっておきますと、ここで紹介する WireCanal は、日本法人である当社（株式会社Qualiteg）が開発・運営し、中継基盤を国内サーバーで運用しているトンネルサービスです。

自社製品を自分で比較する記事なので、都合のよい話だけを並べても信用されません。同じところは同じと書き、ngrok のほうが向いている場合もそのまま書きます。

結論から言うと、

トンネルの基本の仕組みは ngrok と同じです。

違いは3つあります。

料金の考え方（固定枠・従量要素を持つドル建ての料金体系か、追加請求のない円建て定額か）・運用と契約の形（国内中継基盤と日本法人との日本語・円建て契約）・AI につなぐときの許可の置き場所（許可台帳の正本を社内側に置く）

この3つが刺さらない使い方なら、無理に乗り換える必要はありません。どこが同じで、どこが違うのかを順に見ていきます。

仕組みは同じです。だから学び直しはほぼ要りません

ngrok で広く知られるようになったリバーストンネル方式は、こういう仕組みです。手元のPCや社内サーバーに小さなプログラム（WireCanal では Agent と呼びます）を置き、それが内側から外向きに中継サーバーへ接続してトンネルを張ります。外の世界には公開URLができて、そこに届いたアクセスがトンネルを通って手元に流れてくる。

ファイアウォールに受信ポートを開けずに済むのが、この方式の利点です。

WireCanal も同じ考え方を土台にしています（図1）。コマンドを実行して Agent を入れ、canal と呼ぶ公開経路を作り、転送先に手元のポートを指定する。ngrok を使ったことがある方なら、概念の学び直しはほぼ要りません。

なお、現在の ngrok はクラウド側エンドポイントなど製品の範囲が広がっていますが、この記事では「Agent を使ってローカル・社内サービスを公開する」基本構成を比べます。

だからこの記事で書くべきは「どちらが優れているか」ではなく、その先の設計がどう違うか、です。

違い1　料金は円建て・税込の定額制です

ngrok には Free・Hobbyist・Pay-as-you-go などのプランがあります（2026年8月時点・公式サイトで確認）。まず形を表で比べます。

本番利用を想定した Pay-as-you-go は、月20ドルの利用枠を含み、超えた分は転送量・リクエスト数・エンドポイントの稼働などに応じて追加料金が発生する仕組みです。使った分だけ払う合理的な設計ですが、利用が伸びた月の請求額は事前に読みにくく、ドル建てなので為替でも変わります。

WireCanal は、どのプランも月額定額の円建て・税込にしました。プランごとの違いはこうです。

年払いにすると月額換算でライト1,280円・プロ2,980円・プレミアム9,980円になります。

転送量に応じた追加請求はありません。

フリープランは月10GBが目安で、超過時は速度を調整する場合があります。有償プランには通常利用での月間転送量の上限を設けていませんが、公平な利用とネットワーク維持のため、極端な大容量通信は速度制限等の対象になる場合があります。

ことわっておくと、定額が常に得というわけではありません。利用規模や用途によっては、ngrok の Free・Hobbyist・Pay-as-you-go のほうが安く収まる場合もあります。定額制の価値は請求額が事前に読めることにあり、稟議や予算取りが要る組織ほど効いてきます。

違い2　国内リージョンで動き、契約・請求・サポートが日本語と円で完結します

WireCanal の中継基盤は国内リージョンに配置しています。契約とサポートは日本の事業者である当社が日本語で提供し、請求は円建てです。ここも表で整理します。

なお、ngrok にも東京の接続拠点（PoP）があり、地域を指定したルーティングの仕組みもあります。つまり、単純な「国内経路の有無」の比較ではありません。WireCanal の違いは、中継基盤を国内サーバーで運用することをサービス設計として掲げ、日本法人との契約・日本語サポート・円建て請求までセットになっている点です。

「海外SaaSの利用申請が社内でなかなか通らない」「円建ての請求書が出ないと経理処理が面倒」という組織にとって、ここは機能の優劣ではなく、導入できるかどうかの分かれ目になります。

正直に書いておくと、国内リージョンだからといって、海外サービスより常に速いとは言えません。実際の遅延は利用場所・接続先・経路で変わります。逆に、世界各地の利用者に配信したい・海外拠点からも同じように使いたいという場合は、世界規模の接続拠点を持つ ngrok や Cloudflare のほうが適しています。

違い3　AI に見せる機能の「許可台帳」を、社内側に置いています

ここが、当社がいちばん考え抜いた部分です。

生成AIに社内システムを操作させる接続方式として、MCP（Model Context Protocol）が広まりつつあります。すると実務では「AI に社内システムのどの機能まで触らせるか」が問題になります。社内の MCP サーバーには、参照するだけのツールから更新・削除を行うツールまで並んでいるのが普通だからです。

MCP を外部の AI につなぐ際にゲートウェイ側で制御する、という発想自体は当社だけのものではありません。各社の公式ドキュメントで確認できる範囲を表にします。

WireCanal が異なるのは、ツール単位の許可そのものに加えて、その許可台帳の正本を社内側の設定ファイルに置いている点です（図2）。

wirecanal.json（ツール許可の部分・抜粋）

{
  "tools": {
    "default": "deny",
    "allow": ["execute_sql_query", "get_database_stats"]
  }
}

既定は全拒否で、この allow に書いたツールしか AI には見えません。許可していないツールは、ツール一覧（tools/list）にも出ません。クラウドの管理画面からできるのは変更の提案までで、反映には社内側での承認操作が必要です。つまり、通常の管理画面の操作だけでは、社内側の承認なしに公開範囲は広がりません。

もうひとつ、Agent は設定ファイルに登録された転送先へだけ接続し、クラウド側から転送先を動的に変える指示は受け付けません。トンネルの出口が社内の任意の宛先へ向かう汎用の中継点にならないよう、Agent 側でも制限しています。

自作の MCP サーバーを実際に Web 版の ChatGPT・Claude へつないだ手順は、当ブログの連載で画面つきで公開しています。この記事の最後にリンクを置きました。

ngrok のままがよい場合も書いておきます

ここまで読んで分かるとおり、WireCanal が向くのは「国内で・見通せる料金で・AI への公開範囲を統制しながら」使いたい場合です。使い方ごとに整理するとこうなります。

道具は用途で選んでください。無理に乗り換える理由がなければ、それはそれで正しい判断です。

無料でどこまで使えるか

WireCanalのフリープランに期間の制限はなく、クレジットカードの登録も要りません。

canal 1本で、HTTPS 公開・MCP 公開（ChatGPT/Claude などとの OAuth 連携）・IP制限・BASIC認証・Bearerトークン・時間帯公開などのアクセス保護8種まで、ぜんぶ使えます。

公開ホスト名は、使っている限り消えません。Agent の接続が生きている間は有効期限が自動延長され、最後の接続から72時間で失効します（失効しても作り直せます）。名前を自分で選びたい、接続を止めても同じ名前を残したい、となったときにライト以上を検討すれば十分です。

まずは手元の Web アプリか MCP サーバーをひとつ公開してみて、使い勝手を確かめるのがおすすめです。WireCanal は無料で始められます（wirecanal.com）。

まとめ　同じ方式、違う置きどころ

ngrok と WireCanal は、リバーストンネルという同じ方式の上に立っています。違いは、お金の払い方（固定枠・従量要素を持つドル建ての料金体系か、追加請求のない円建て定額か）、運用と契約の形（国内中継基盤と日本法人との日本語・円建て契約か、グローバルサービスの利用か）、そして AI 向けのツール許可台帳の正本を社内側に置いていること。この3点に集約されます。

トンネルサービスは、いちど運用に組み込むと長く付き合う道具です。機能表の○×だけでなく、この3つの置きどころが自分の組織に合うかで選ぶと、あとで後悔しません。

それでは、また次回、お会いしましょう！

参考（一次情報）

• ngrok の料金プラン（公式サイト）　※2026年8月時点の内容で確認しています
• ngrok の MCP ゲートウェイ公式ガイド（ngrok Docs）
• ngrok の接続拠点一覧（ngrok Docs）
• Cloudflare MCP Server Portals（Cloudflare Docs）
• WireCanal の料金プランと機能の対応表（wirecanal.com）
• WireCanal の MCP・AI 連携の解説（wirecanal.com）

関連記事

• MCPサーバーの作り方（前編）｜ PythonとFastMCPで売上DBをAIにつなぐ（当ブログ）

こんにちは！Qualitegプロダクト開発部です！

手元のデータベースをAIから問い合わせられるようにしたい。 そのために必要なのがMCPサーバーです。

やりたいことは単純なのですが、いざ調べてみると「MCPサーバーを作ればいい」というところまでは分かっても、自分のデータベースをどうやってMCP化するのかでつまずきます。

この記事では、

PythonとFastMCPでMCPサーバーを自作し、CLI版のClaude Codeから売上データベースに日本語で聞けるようにする

までの手順を、動くコードつきで最初から最後まで書きます。コードは200行ほどです。「職業別の売上トップ3を教えて」と聞くと、Claude Codeが自分でSQLを組み立てて集計まで返してくれるようになります。

書いたコードは全部GitHubに置きました。cloneして、依存関係のインストールとDB作成を行えば動きます。動かす手順はリポジトリのREADMEにも全部書いてあるので、記事を読まずに手を動かしたい方はそちらからどうぞ。

qualiteg/mcp-server-tutorial ｜ サンプルコード一式とREADME（GitHub）

前後編に分かれていて、前編（この記事）ではCLI版のClaude Codeから使えるところまで。後編では、同じサーバーをWeb版のChatGPT・Claudeから使えるようにします。手元で動くCLI版と、ブラウザで動くWeb版。この2つのあいだに、多くの人が引っかかる壁があります。

MCPとは何か、3分で

MCP（Model Context Protocol）は、AIアプリと外部のデータやツールをつなぐための共通規格です。Anthropicが2024年末に公開し、いまではClaudeだけでなくChatGPT、Gemini、各種コーディングエージェントが対応しています。

MCPが無かったころは、AIにデータベースを触らせたければ、AIアプリごとの独自プラグインや関数呼び出しに個別対応する必要がありました。MCPでは「サーバー（データやツールを出す側。今回作るもの）」と「クライアント（ClaudeやChatGPTなどのAIアプリ側）」の話し方が規格で決まっています。一度MCPサーバーを作れば、AIアプリごとに専用プラグインを作り直さずに、MCP対応の複数のAIアプリから利用できます。ただし、使えるトランスポートや認証方式、プラン、管理者設定はクライアントごとに違います。

MCPサーバーが出せるものはtools・resources・promptsの3種類ありますが、実務でまず使うのはtools、つまりAIが呼び出せる関数です。この記事もtoolsだけ扱います。

もうひとつ、後編で効いてくる予備知識があります。MCP仕様が定める標準トランスポートは2系統あります。

この記事では、前編でCLI版のClaude Codeからローカルのstdioサーバーを使い、後編でWeb版からリモートのStreamable HTTPサーバーを使います。ただし「CLI版ならstdio、Web版ならHTTP」と一対一で決まるわけではありません。たとえばClaude CodeはstdioにもリモートのHTTPにも接続できます。前編では両方の動かし方を試します。

何を作るか

PCパーツのオンラインショップを想定した売上データベース（SQLite）と、それに問い合わせるMCPサーバーです。

テーブルは3つです。顧客マスター（customers）が500人ぶん、商品マスター（products）がPCパーツ8カテゴリで72商品、そして売上明細（sales_transactions）が2024年から2026年までの4,000件。顧客には年齢や職業、年収帯といった属性を持たせてあるので、「職業別に見ると」のような分析ができます。

Claude Codeに渡すツールは、思い切って2つだけにします。テーブル構造と統計を返す get_database_stats と、SELECT文を実行する execute_sql_query です。

「売上集計ツール」「顧客分析ツール」と業務ごとに関数を並べる設計もあります。ただ、SQLを書けるのはClaude Code側なので、汎用のSQL実行ツールを1本渡すほうが応用が利きます。そのぶん安全側の手当てはサーバーの責任になりますが、これは後で書きます。

準備

MCPサーバー自体の実装に必要なのは、Python 3.10以降とFastMCPです。この記事と同じ形でClaude Codeから試すなら、Claude Codeを使える環境も別途必要です。

python -m pip install fastmcp

pip ではなく python -m pip を使ってください。pip だと、あとでMCPサーバーを起動するPythonと別の環境に入ってしまうことがあります。

FastMCPは、Python関数にデコレータを1つ付けるだけでMCPツールを定義できる高水準フレームワークです。クライアント機能やHTTPサーバー機能もまとめて使えます。筆者環境で動作確認したのはstandalone版の3.4.5です。

まず10行で、動くMCPサーバー

いきなり売上DBに行く前に、最小構成で全体像をつかみます。

# hello_mcp.py
from fastmcp import FastMCP

mcp = FastMCP(name="hello-server")

@mcp.tool(description="2つの数値を足し算します")
def add(a: int, b: int) -> int:
    return a + b

if __name__ == "__main__":
    mcp.run()  # 既定はstdioトランスポート

これで完成です。関数の型ヒントとdescriptionから、AIに渡されるツール定義が自動生成されます。

なお python hello_mcp.py を実行しただけでは何も表示されません。stdioサーバーとして入力待ちになるだけです。動きを確かめたいときは、FastMCPのin-memoryクライアントから呼びます。

import asyncio

from fastmcp import Client
from hello_mcp import mcp


async def main():
    async with Client(mcp) as c:
        print([t.name for t in await c.list_tools()])   # ['add']
        result = await c.call_tool("add", {"a": 120, "b": 5})
        print(result.data)                              # 125


if __name__ == "__main__":
    asyncio.run(main())

Claude Codeへの登録は1行です（登録して使うところは後半でやります）。

claude mcp add hello-server -- python hello_mcp.py

うまく繋がらないときは、Pythonとスクリプトを絶対パスで指定してください。仮想環境を使っている場合は、その中のPythonを指す必要があります。

ここで注目してほしいのは、AIが「計算が必要だ」「addというツールがある」「呼ぼう」と判断する材料が、ツール名、description、引数名や型から生成されるinputSchemaしかないことです。なかでもdescriptionは、そのツールをどんな場面で使うのかを自然文で伝えられる中心的な項目で、これがMCPサーバー設計でいちばん効いてきます。

手順1: 売上データベースを用意する

SQLiteでテーブルを3本作ります。

db_setup.py（テーブル定義とダミーデータ生成の全文コード（GitHub））

cur.execute("""
CREATE TABLE sales_transactions (
    transaction_id   INTEGER PRIMARY KEY,
    date             TEXT NOT NULL,     -- 'YYYY-MM-DD'
    customer_id      TEXT NOT NULL REFERENCES customers(customer_id),
    product_id       TEXT NOT NULL REFERENCES products(product_id),
    product_name     TEXT NOT NULL,
    product_category TEXT NOT NULL,
    quantity         INTEGER NOT NULL,
    unit_price       INTEGER NOT NULL,
    total_price      INTEGER NOT NULL
)""")

cur.execute("CREATE INDEX idx_trans_date     ON sales_transactions(date)")
cur.execute("CREATE INDEX idx_trans_customer ON sales_transactions(customer_id)")
cur.execute("CREATE INDEX idx_trans_category ON sales_transactions(product_category)")

インデックスは張っておいてください。AIは遠慮なく全期間の集計クエリを投げてきます。

乱数は固定シードにしてあるので、誰が実行しても同じデータになります。筆者環境で流すとこうなりました。

この記事に出てくる数字は、すべてこのデータの実測値です。手元で同じ数字が出るはずです。

手順2: ツールのdescriptionにスキーマを丸ごと書く

ここがこの記事でいちばん伝えたいところです。

execute_sql_queryのdescriptionには、データベースのスキーマとクエリ例を全部書き込みます。

mcp_server_sales.py（descriptionの全文コード（GitHub））

@mcp.tool(description="""SQLクエリを実行して売上データを取得します。SELECT文のみサポートします。

【データベーススキーマ】

■ customers（顧客マスター）
  - customer_id (TEXT): 顧客ID（例 'C0001'）
  - age (INTEGER): 年齢
  - gender (TEXT): 性別（'男性', '女性'）
  - prefecture (TEXT): 都道府県
  - occupation (TEXT): 職業（'ITエンジニア', '会社員', '学生', '自営業' など）
  - annual_income (INTEGER): 年収（万円）

■ products（商品マスター）
  - product_id (TEXT): 商品ID（例 'CPU_001'）
  - product_category (TEXT): CPU, GPU, Memory, SSD, HDD, Motherboard, PowerSupply, PCCase
  - tier (TEXT): 'high' / 'mid' / 'entry'
  （以下略。全カラムをこの調子で書く）

■ sales_transactions（売上明細）
  - date (TEXT): 売上日（YYYY-MM-DD形式）
  - customer_id (TEXT): 顧客ID → customers.customer_id
  - product_id (TEXT): 商品ID → products.product_id
  - quantity / unit_price / total_price (INTEGER)

【データ期間】2024-01-01 〜 2026-12-31（4,000件）

【クエリ例】
- 職業別の売上:
  SELECT c.occupation, SUM(t.total_price) AS sales
  FROM sales_transactions t JOIN customers c ON t.customer_id = c.customer_id
  GROUP BY c.occupation ORDER BY sales DESC

- ハイエンドGPUの売上:
  SELECT p.product_name, SUM(t.total_price) AS sales
  FROM sales_transactions t JOIN products p ON t.product_id = p.product_id
  WHERE p.product_category = 'GPU' AND p.tier = 'high'
  GROUP BY p.product_name ORDER BY sales DESC
""")
async def execute_sql_query(sql: str, ctx: Context) -> str:
    ...

やたら長いと思われるかもしれません。でもAIが正しいSQLを書けるかどうかは、モデルの賢さよりもスキーマをどれだけ正確に渡せているかで大きく変わります。今回のような小規模で固定されたスキーマなら、必要なカラムとJOIN関係をdescriptionに含めておくのが有効でした。

AIがツールを選ぶ材料は、ツール名、description、引数名や型から生成されるinputSchemaです。なかでもdescriptionは、どんな場面で呼ぶツールなのかを自然文で伝えられます。

クエリ例を2〜3個入れておくのもコツです。JOINの書き方や列の使い方のお手本があると、AIが書くSQLの精度が目に見えて安定します。

手順3: SQL実行ツールに3つの安全弁を設ける

AIにSQL実行を任せる以上、書き込みの防止と、重いクエリでリソースを持っていかれることの両方に備える必要があります。役割の違う3つの安全弁を設けます。

1段目、データベースを読み取り専用で開く。 SQLiteはURI接続でmode=roを指定すると、そもそも書き込みを受け付けなくなります。あとの検査をすり抜けられても、ここで止まります。

mcp_server_sales.py（読み取り専用で接続する関数のコード（GitHub））

conn = sqlite3.connect(f"file:{DB_PATH.as_posix()}?mode=ro", uri=True)

2段目、SELECT以外を弾く。 これは構文解析ではなく文字列の検査なので、明らかな書き換え命令を早い段階で落とすための保守的な補助フィルターです。最終的な書き込み防止は1段目に任せます。

mcp_server_sales.py（SELECT以外を弾く部分のコード（GitHub））

normalized = sql.strip().upper()
if not normalized.startswith("SELECT"):
    return "エラー: SELECT文のみサポートしています"
for keyword in ("DROP", "DELETE", "INSERT", "UPDATE", "ALTER", "CREATE", "TRUNCATE", "ATTACH", "PRAGMA"):
    if keyword in normalized:
        return f"エラー: {keyword} は許可されていません"

3段目、実行時間に上限を付ける。 重い集計で固まらないよう、SQLiteの進捗ハンドラで打ち切ります。

mcp_server_sales.py（実行時間に上限を付ける部分のコード（GitHub））

import time

def install_query_timeout(conn, timeout_sec):
    deadline = time.monotonic() + timeout_sec

    def guard():
        return 1 if time.monotonic() >= deadline else 0

    # SQLite仮想マシンが1,000命令を実行するたびに guard を呼ぶ
    conn.set_progress_handler(guard, 1000)

ここは一度間違えました。進捗ハンドラの呼び出し回数を数えて上限にしていたのですが、set_progress_handler の第2引数は秒ではなくSQLite仮想マシンの命令数です。呼ばれた回数は実行時間そのものではないので、マシンの速度やクエリの内容で待ち時間が変わってしまいます。time.monotonic() で実時間を見るのが正解でした。

なお、この3段目は読み取り専用にするための対策ではありません。暴走したクエリでリソースを持っていかれないための対策です。それぞれ守っているものが違います。

3段が本当に効いているかどうかは、あとで実際に確かめます。

手順4: AIに返す量を、サーバー側で決める

クエリ結果を整形する部分です。返す行数に上限を付けているところを見てください。

mcp_server_sales.py（クエリ結果を整形する部分のコード（GitHub））

    if not rows:
        return "クエリの結果、データが見つかりませんでした。"

    lines = [" | ".join(columns), "-" * 40]
    for row in rows[:MAX_ROWS]:                      # MAX_ROWS = 50
        lines.append(" | ".join("" if v is None else str(v) for v in row))
    if len(rows) > MAX_ROWS:
        lines.append(f"... 他 {len(rows) - MAX_ROWS} 件（全体を見るには集計するか条件を絞ってください）")

    return f"クエリ結果（{len(rows)} 件）:\n\n" + "\n".join(lines)

AIは平気でSELECT * FROM sales_transactionsを投げてきます。4,000行をそのまま返してもコンテキストを溢れさせるだけです。件数だけは正直に伝えて、「集計するか条件を絞って」と促すのが実用的でした。

ただしこの実装が制限しているのはAIへ返す行数だけで、SQLiteから読み込む件数は制限していません。数百万行の実データを相手にするなら、fetchmany(MAX_ROWS + 1) にする、SQL側にLIMITを付ける、クエリコストを見る、といった手当てが別に要ります。

手順5: 「まず全体像を見せる」ツールを足す

2本目のツールは、テーブル構造と統計の要約を返すだけのものです。

mcp_server_sales.py（統計情報を返すツールの全文コード（GitHub））

@mcp.tool(description="""データベースのテーブル構造・件数・データ期間・カテゴリ別売上の統計を返します。
SQLを作る前に、必ずこのツールを呼んで構造を確認してください。""")
async def get_database_stats(ctx: Context) -> str:
    ...

descriptionの最後の一文が仕事をします。

「SQLを作る前に、必ずこのツールを呼んで」

筆者環境では、これを書いたことで、まず統計を確認してからSQLを組み立てる動きになりました。

ただしこれはモデルへのお願いであって、サーバー側で強制される制御ではありません。モデルやクライアント、会話の流れによっては、統計を見ずにいきなりSQLを投げてくることもあります。安全性をこの一文に頼らせない、というのが大事なところです。ツールの説明文は、機能の説明だけでなく、使う条件や手順をモデルへ伝える場所としても働く、くらいの理解が安全です。

使ってみる

Claude Codeに登録します。

claude mcp add sales-db -- python C:\qualiteg_examples\mcp_server_sales.py

登録できたか確認します。

claude mcp list

sales-db: python C:\qualiteg_examples\mcp_server_sales.py - ✔ Connected

✔ Connected が出れば、AIからこのサーバーが見えています。あとは日本語で聞くだけです。

claude -p "職業別の売上トップ3を教えて"

返ってきたのがこれです。

質問したのは日本語の一文だけです。AIはこちらがSQLを一行も書かないまま、テーブル構造を確認し、JOINとGROUP BYを組んだクエリを投げ、集計結果を表にまとめて返してきました。

金額はダミーデータの実測値と一致しています。さらに、質問には含めていなかった取引件数も追加で集計し、「研究者は件数が最多だが単価が低い」「経営者は件数が少ないぶん単価が高い」という読みまで付けてきました。単にSQLを生成するだけでなく、集計結果の解釈まで行っています。

「2025年に発売されたハイエンドGPUで、20代への売上が多い順に」のような多段の条件も同じ調子で通ります。SQLを書いたことがない人でも、売上データベースに話しかけられるようになりました。

ただし、自然言語で聞けることと、集計結果が業務上正しいことは別の話です。重要な判断に使うなら、実行されたSQL・集計の定義・対象期間・除外条件を確認できるようにしておいてください。「売上」「顧客数」「平均単価」あたりは、社内の定義次第で数字が変わります。

安全弁がちゃんと効いているか確かめる

書いたつもりで効いていない防御ほど怖いものはありません。実際、この記事を書いている途中でタイムアウトが機能していないことに気づきました。

3段はそれぞれ守っているものが違うので、確かめ方も分ける必要があります。ツール経由のキーワード検査はFastMCPのin-memoryクライアントで、読み取り専用とタイムアウトはDB接続を直接触って確認します。

verify.py（検証スクリプトの全文コード（GitHub））

# 1段目: 接続そのものが書き換えを拒むか
conn = connect_readonly()
try:
    conn.execute("DELETE FROM customers")
    raise AssertionError("読み取り専用のはずが書き込めてしまいました")
except sqlite3.OperationalError as e:
    assert "readonly" in str(e).lower()

# 3段目: 重いクエリが実時間で中断されるか
conn = connect_readonly()
install_query_timeout(conn, QUERY_TIMEOUT_SEC)
started = time.monotonic()
try:
    conn.execute(HEAVY_SQL).fetchone()
    raise AssertionError("中断されませんでした")
except sqlite3.OperationalError as e:
    assert "interrupted" in str(e).lower()
    print(f"{time.monotonic() - started:.1f} 秒で中断")

筆者環境での結果です。

SELECTで始まってはいるがDROPを潜ませたクエリも止まっています。読み取り専用の接続は「attempt to write a readonly database」で書き込みを拒み、重いクエリは実時間10.0秒で中断されました。行数上限も、SELECT * FROM sales_transactionsを投げると50行のあとに「... 他 3950 件」と付いて返ってきます。

なおこの検証はin-memoryクライアントとDB接続を直接使ったもので、stdioやHTTPのトランスポートを経由した動作までは確認していません。

ここまで確認してから、はじめて社内で使ってもらうようにしてください。

HTTPサーバーとして常駐させる

ここまではstdio、つまりAIアプリが手元でサーバーを起動する形でした。独立して常駐させ、ネットワーク経由で使うならStreamable HTTPに切り替えます。変えるのは起動の1行だけです。

mcp_server_sales.py（起動部分のコード（GitHub））

mcp.run(transport="http", host="127.0.0.1", port=9904)

これでhttp://127.0.0.1:9904/mcpがMCPエンドポイントになります。

待受は127.0.0.1にしてください。 このサーバーは認証を持っていません。0.0.0.0で待ち受けると、そのネットワークから届く相手なら誰でもSQLを実行できてしまいます。サンプルコードでも既定を127.0.0.1にして、外部待受を指定したときは警告を出すようにしました。社内で共有する、外から使うという段階に進むなら、HTTPS、認証と認可、接続元の制限、Origin検証、監査ログを前段に置く前提になります。この記事のサーバーは、その手前の「仕組みを理解するための最小構成」です。

死活監視用のエンドポイントも追加しておくと運用が楽です。

mcp_server_sales.py（ヘルスチェックのコード（GitHub））

@mcp.custom_route("/health", methods=["GET"])
async def health_check(request):
    from starlette.responses import JSONResponse
    return JSONResponse({"status": "ok", "service": "sales-database-server"})

サンプルコードでは--httpオプションで切り替えられるようにしてあります。

python mcp_server_sales.py --http --port 9904

起動したら、ヘルスチェックを叩いて生きていることを確かめます。

curl http://127.0.0.1:9904/health

{"status":"ok","service":"sales-database-server"}

返すのは状態だけにしてあります。監視に要らない情報（DBの絶対パスや例外の中身）を外へ出す理由はありません。

作ってみて分かったこと

今回いちばん効いたのは、ツールを2本に絞ったことでした。業務ごとに関数を並べるより、汎用のSQL実行ツールを1本渡すほうが、AIは自分で考えて答えを出してくれます。ただしこれは小規模なダミーDBでの話です。実データを扱うなら、取得できるテーブルや列、集計の粒度を絞った業務別ツールのほうが安全で、監査もしやすくなります。

そのぶん、descriptionの書き方で結果が大きく変わります。スキーマとクエリ例を丸ごと書いたら、AIのSQLが安定しました。descriptionは機能の説明だけでなく、ツールを使う条件や手順をモデルへ伝える場所としても働きます。ただし手順の指示はお願いであって、実行が保証される仕組みではありません。

安全側の手当ては3段にしました。読み取り専用で開き、SELECT以外を弾き、実行時間に上限を付ける。そして書いて終わりにせず、3段それぞれを実際に試して確かめました。ここを省くと、効いていない防御を効いていると思い込んだまま社内に配ることになります。実際、最初に書いたタイムアウトは実時間を測っておらず、まったく機能していませんでした。

返す行数の上限も忘れないでください。AIは平気で全件取得を投げてきます。50行で切って件数だけ正直に伝えたところ、筆者環境では集計クエリへ切り替える動きが確認できました。

常駐させて使うならStreamable HTTPに切り替えて、ヘルスチェックも足しておくと運用が楽になります。ただし認証は入っていないので、そのまま社内LANや外部へ出さないでください。

もうひとつ。このサンプルは仕組みを理解するための最小構成です。複数人が同時に使う場面では、同期的なDB処理をスレッドへ逃がす、同時実行数を絞る、DB側のタイムアウトを設ける、といった手当てが別に要ります。

次回予告

後編でやることは、はっきりしています。

手元（localhost）で作ったこのMCPサーバーを、Web版のChatGPT・Claudeと連携させます。OAuth認証の壁も乗り越えます。

CLI版のClaude Codeを使うのは開発者です。でもブラウザで使うWeb版なら、コマンドラインを触らない人にも渡せます。営業企画のメンバーが、いつものChatGPTの画面から「先月いちばん売れたGPUは？」と聞ける。同じMCPサーバーのまま、使える人の範囲が一気に広がります。

ところが、ここが本当に難しい。Web版のコネクタにMCPサーバーをつなぐには、次の2つが要ります。

ひとつは、インターネットから到達できるHTTPSのURL。手元のPCで動いているサーバーには、外から誰も届きません。かといって社内DBに届くサーバーをそのまま外に晒すわけにもいきません。

もうひとつが、利用者を識別してアクセスを制御するための認証・認可です。

ChatGPTもClaudeも、構成によっては認証なしのリモートMCPに接続できます。ただ、社内データベースに到達するMCPサーバーを認証なしで公開する選択肢はありません。そこで後編では、MCP Authorization仕様に沿ったOAuth認証を使います。

これを自前で実装するとなると、認可メタデータ、クライアント登録、認可エンドポイント、トークンの発行と検証と、ツール本体とはまったく別の実装が必要になります。ツール本体は200行で書けたのに、本題に入る前に力尽きる。ここで止まる人が多いところです。

後編では、この2つの壁をどう越えるかを、実際にWeb版のChatGPTとClaudeから今回の売上DBにつなぐところまで、画面つきで書きます。しかも無料で試せる方法でです。

先に開示しておくと、後編では当社が提供しているWireCanalを使います。無料で試せる枠があるので、そのまま手を動かせます（利用条件や無料枠は執筆時点のものです）。

それでは、また次回、お会いしましょう！

サンプルコード

この記事のコードはすべてGitHubに置いてあります。

qualiteg/mcp-server-tutorial ｜ サンプルコード一式とREADME（GitHub）

git clone https://github.com/qualiteg/mcp-server-tutorial.git
cd mcp-server-tutorial
python -m pip install -r requirements.txt
python db_setup.py

続けてClaude Codeへ登録します。

claude mcp add sales-db -- python /path/to/mcp-server-tutorial/mcp_server_sales.py
claude mcp list
claude -p "職業別の売上トップ3を教えて"

stdioで使う場合、python mcp_server_sales.py を別ターミナルで手動起動する必要はありません。登録したコマンドはClaude Codeが子プロセスとして起動します。

ここに書いた手順は、リポジトリのREADMEにも全部書いてあります。 クイックスタート、Claude Codeへの登録方法、提供しているツールの説明、HTTPサーバーとしての起動まで揃っているので、手元で動かすときはREADMEだけ見れば足ります。

参考

• Model Context Protocol 公式サイト
• FastMCP
• Anthropic: Introducing the Model Context Protocol

関連記事

株式会社Qualiteg（本社：東京都千代田区、代表取締役：三澤 智則）は、2026年8月4日、「WireCanal（ワイヤキャナル）」の一般提供を開始しました。WireCanalは、ClaudeやChatGPTなどのクラウドAIと、社内ネットワークにあるデータベースやMCPサーバーを安全につなぐサービスです。会社の認証基盤で利用者を認証し、管理者が許可したドメインに属する組織アカウントだけが、AIを通じて社内システムへアクセスできます。AI連携のほか、HTTPSやTCP（RDP、SSH、データベースなど）の汎用セキュアトンネルとしても利用できます。

「canal」は、英語で「運河」を意味する言葉です。運河が、行き先の定まった船だけを通す人工の水路であるように、WireCanalは、クラウドAIと社内システムの間に、許可された通信だけが行き来できる専用の通り道（セキュアトンネル）を構築します。WireCanalでは、この一本一本の通信経路を「canal」と呼びます。canalは、社内に設置した中継プログラム「WireCanal Agent」が社内側から外向きに接続して開通するため、受信ポートの開放や、新たなVPN環境の構築は必要ありません。

WireCanalは、クレジットカード登録不要のフリープラン（0円）から利用できます。あわせて、一般提供の開始を記念したリリースキャンペーンを実施します。2026年8月31日までにライトプラン（canal 1本）を年間契約でお申し込みいただくと、初年度を年額6,000円（税込・月額換算500円）でご利用いただけます。キャンペーン終了後（2026年9月1日以降）の新規年間契約価格は、年額15,360円（税込）です。

AIに社内の生きたデータを使わせたい。しかし、社内システムは公開できない

「社内の売上データをClaudeに聞きたい」「在庫や生産の状況を、SQLやシステムの操作を覚えずに言葉で確かめたい」。クラウドAIの業務活用が進む一方、その答えの根拠となるデータベースや基幹システム、そしてそれらをAIから扱えるようにするMCPサーバーは、手元のPCや社内ネットワークの中にあります。クラウド上のAIからは、そのままでは届きません。

MCP（Model Context Protocol）は、AIが外部のツールを発見して実行するための共通仕様であり、認証・認可の仕組みも定めています。一方で、MCPに対応しただけで、クラウドAIから社内ネットワークまでの安全な到達経路や、会社のIdPと連動したアカウント管理まで自動的に用意されるわけではありません。

クラウドAIから社内ネットワークへ届く通信経路、会社のIDによる利用者の管理、退職時の会社アカウント停止に連動したアクセスの失効といった企業向けの運用基盤は、別途構築する必要があります。

かといって、適切な認証やアクセス制御を設けずにMCPサーバーをインターネットへ公開すれば、社内システムへの入口を広く露出することになります。受信ポートの開放やVPNの構築で対応しようとすれば、今度は情報システム部門の構築・運用負担が重くのしかかります。「使いたい。しかし、安全に出す方法がない」。ここで多くの企業が立ち止まっています。

WireCanalの答え：社内から外向きにつなぎ、会社のIDで入口を守る

Windows、Linuxで動作する接続アプリ「WireCanal Agent」を社内に置くと、Agentが外向きの暗号化トンネルを構築し、ClaudeやChatGPTからのリクエストは、あらかじめ指定した社内のMCPサーバーだけへ届きます。

そして入口を守るのは、会社のIDです。利用者がcanalにアクセスすると、Google Workspaceなど会社の認証基盤のログイン画面が表示され、接続できるのは管理者が許可したドメインの組織アカウントだけになります。WireCanal専用のアカウントを一人ずつ発行する必要はありません。退職などで会社側がアカウントを停止すると、その利用者の接続も1時間以内に自動的に失効します。「誰が使えるか」の管理を会社の既存のID基盤にそのまま委ねられること。これがWireCanalの答えです。

WireCanalの特長：AIに見せるツールを、社内が選ぶ

WireCanalは、HTTPSでのWebシステム公開と、IPアドレス制限・BASIC認証・トークン認証など8種のアクセス保護を全プランで提供する、汎用のセキュアトンネルとしても使えます。RDP・SSH・データベースなどに対応するTCP中継は、プロプラン以上で利用できます。

そのうえでの特長が、MCPツール単位の公開制御です。社内MCPに多数のツールがあっても、AIに見せるものを許可台帳で選べます。既定は全拒否。許可台帳の正本は社内に置く設定ファイルであり、クラウド側の管理画面からできるのは変更の「提案」まで、反映には社内での承認操作が必要です。トンネルが土管だとすれば、WireCanalは中身を理解して通すものを選ぶ門番です。

組織のAI利用を守る、多層防御

ここまで述べた「誰が接続できるか」「AIに何を見せるか」に、「社内のどこへ届くか」を加えた3つが、WireCanalの守る境界です。接続アプリは設定した転送先以外へは接続せず、これにより、トンネルが社内の任意の宛先へ通信を中継する通り道として使われることを防ぎます。WireCanalの中継基盤は国内サーバー上で運用しており、canalごとに到達アクセスを記録して、いつ・どこから接続があったかを後から確認できます。WireCanalのアクセス制御で許可を確認できない通信は拒否する、fail-closed設計を採用しています。

この境界を、次の5層の防御が支えます。

1. 転送先の固定 ― Agentは設定した転送先以外へ接続しません。接続のたびに宛先を検証し直し、リダイレクトにも追従しません
2. 入口の限定 ― 公開入口を正規の呼び出し元のIPアドレスに絞り込めます。Agentの接続は発行済みキーの照合で確認します
3. アクセス保護 ― IP制限、国別制限、BASIC認証、トークン認証、時間帯公開、パス制限、自動ブロック、ステルスモードの8種を、全プランで利用できます
4. 公開範囲の許可リスト ― 外部に見せるMCPツール・URLパスは、社内側の許可台帳で管理します。既定は全拒否です
5. 標準準拠のMCP認証 ― MCP Authorization仕様および関連RFC（RFC 9728・RFC 8414・RFC 8707など）に対応した認証・認可機能を内蔵し、入口で検証した認証情報は転送先へ渡しません

これらに加えて、canalごとの専用サブドメインと固有IDによる分離、canal単位の一時停止・再開、社内側からの即時遮断、プランに応じたアクセスログ（直近1,000〜10,000件・CSVダウンロード対応）を備えます。社内データベースやMCPサーバー本体は社内に置いたままです。まず一人で試し、部署へ広げるときも、IdP設定・canal・許可ツールという同じ仕組みのまま管理を引き継げます。

利用イメージ：Claudeと社内の売上データベースをつなぐ、3つのステップ

事前に社内MCPサーバーとWireCanal Agentを用意した後、MCP canalの作成、会社の認証基盤との連携、Claudeへの接続URLの登録という3つのステップで接続を設定できます。

1. MCP canalを作成する

WireCanalの管理画面で、利用するAIと、転送先となる社内のMCPサーバーを指定してMCP canalを作成すると、Claudeに登録するための接続URLが発行されます。社内に置いたWireCanal Agentが外向きに接続し、通信経路はこの時点で開通します。

2. 会社の認証基盤でMCP canalを守る

作成したMCP canalにGoogle Workspaceなどの組織IdPを割り当て、接続を許可するドメインを設定します。以後、このcanalの入口は会社のログイン画面になります。

3. Claudeに接続URLを登録する

発行された接続URLをClaudeのカスタムコネクタに登録し、会社のアカウントでログインすれば設定は完了です。接続に必要なOAuthの設定はWireCanalが自動で応答するため、AIサービスとの接続用に認可サーバーを別途構築する必要はありません（組織IdP連携の初回設定では、お使いのIdP側でのクライアント登録が必要です）。あとはClaudeに話しかけるだけで、カテゴリー別の売上、年間の売上推移、商品別の販売動向などを、社内の最新データを基に質問・分析できます。SQLを書く必要はありません。

リリースキャンペーン：canal 1本・永続サブドメイン付きのライトプランを、初年度 年額6,000円（税込・月額換算500円）で提供

一般提供の開始を記念し、ライトプラン（canal 1本）を対象としたリリースキャンペーンを実施します。2026年8月31日（月）までに年間契約でお申し込みいただくと、初年度を年額6,000円（税込・月額換算500円）でご利用いただけます。キャンペーン終了後（2026年9月1日以降）の新規年間契約価格は、年額15,360円（税込）です。

※プロモーションを適用できるのは、初回の年間契約時に限ります。2年目以降に契約を更新する場合は、更新時点の通常価格が適用されます。キャンペーンの内容および実施期間は、予告なく変更または終了する場合があります。

WireCanalについて

WireCanalは、クラウドAIや外部サービスと社内システムを安全につなぐ、中継基盤を国内サーバー上で運用するセキュアトンネル＋MCPポリシーゲートウェイです。会社の認証基盤による利用者の確認と、MCPツール単位の権限制御を備え、受信ポートの開放や新たなVPN構築なしに、ClaudeやChatGPTなどから社内システムを利用できるようにします。MCPのほかHTTPSやTCP（RDP、SSH、データベースなど）にも対応し、接続アプリ「WireCanal Agent」はWindows、Linuxで動作します。クレジットカードの登録が不要なフリープランから利用できます。

製品・料金・セキュリティの詳細：https://wirecanal.com/

株式会社Qualitegについて

株式会社Qualitegは、2023年7月に設立されたAIカンパニーです。「世界中の人々のクリエイティビティを深化させる」という経営理念のもと、最先端のAI技術を通じて人々の創造力を増幅し、これまで想像もできなかった新たな表現と価値を生み出す世界の実現に取り組んでいます。AIを一部の専門家の特権にとどめるのではなく、誰もが直感的にAIを活用して自らの創造性を深化させられる、技術格差による分断のない社会を目指し、生成AIプロダクトの研究開発とコンサルティングを行っています。

本件に関するお問い合わせ

株式会社Qualiteg

WireCanal PR担当

お問い合わせ：wirecanal-pr@qualiteg.com

※組織IdP連携はライトプラン以上で利用できます。

※クラウドAIをご利用の場合、MCPツールの呼び出しに必要なリクエストと実行結果は、利用するAIサービスにも送信されます。データの取り扱いは、各AIサービスの規約および設定に従います。

※対応するAIサービス、利用可能な機能、設定手順および必要な管理者権限は、各AIサービスのプランやワークスペース設定により異なります。記載内容は2026年8月4日時点のものです。

※ダッシュボードで参照できるアクセスログの保存件数は、ご利用プランにより異なります。

※記載されている会社名・製品名・サービス名は、各社の商標または登録商標です。第三者のサービス名は接続例として記載しており、各社との提携・後援・推奨関係を示すものではありません。

こんにちは！

前回の記事「TensorRT 10 × Blackwell 移行ガイド【前編】RTX 50 で推論資産が動かない — 基本と最初の壁」では、Blackwell 世代への移行で既存の推論資産が動かなくなる理由と、TensorRT 10 化を最小構成で通す手順を扱いました。前編で出てきた問題には、実はひとつ共通点があります。

すべて、エラーで止まってくれたということです。

本当に怖いのはその先です。TensorRT への移行パイプラインには、

• ビルドが通る
• 実行も通る
• 速度もちゃんと出る
• 出力の形も、値も、一見それらしい
• なのに、中身が間違っている

という失敗の仕方が存在します。

本記事では、TensorRT 本体の挙動だけでなく、export 時のミス・精度設定・エンジンの配布ミスまで含めて、エラーで停止せず誤った出力へ至る事象を便宜上 「沈黙劣化」 と呼びます。

テストが通り、ベンチマークが良い数字を出し、「◯倍速くなりました」と報告した後になって発覚するので、非常に厄介です。

本記事では、実際に踏んだ 5 つの沈黙劣化を、症状 → なぜ起きるか → どう見つけるか → 回避策の順に共有します。

最後に、これらを体系的に検出するための検証設計をまとめます。各事例をどこまで実証できているかを、先に正直に示しておきます。

第1部: 入出力の dtype を取り違える

症状

FP16 tactic を許可してモデルをエンジン化し、PyTorch の half テンソルをそのまま渡して実行しました
（前編の TRTRunner に入っている「dtype 合わせの 2 行」を入れる前の、素朴な実装です）。

エラーは出ません。速度も出ます。ただ、出力が PyTorch とまったく違いました。

どれくらい違ったかというと、出力の値域が 0.5 弱のモデルで、最大絶対誤差が約 13.8 です。fp16 の精度の問題という水準ではありません。完全な別物です。

なぜ起きるか

config.set_flag(trt.BuilderFlag.FP16) は「FP16 の実装候補を許可する」指定で、内部演算で FP16 tactic が選択可能になります（層によっては fp32 が選ばれます）。しかし、ネットワークの入出力テンソルの型は ONNX の定義のままです。ONNX を fp32 で export していれば、エンジンの入出力も fp32 のままなのです。

そこに PyTorch の half テンソルのアドレス（data_ptr()）を渡すとどうなるか。TensorRT はその領域を 「fp32 要素が並ぶ入力バッファ」として扱います。fp16 は 1 要素 2 バイト・fp32 は 4 バイトなので、値の解釈が変わるだけでなく、TensorRT が PyTorch 側の確保範囲を超えて読み出す可能性もあります。挙動は未定義で、出力の破損だけでなく、環境によっては CUDA エラーやクラッシュも起こり得ます。

そして最悪なのは、今回の実測では、この状態でも `execute_async_v3` が `True`（成功）を返し、NaN も出ず、例外も飛ばなかったことです。

回避策

エンジンが要求する dtype を問い合わせて、明示的に合わせてから渡します。 前編の TRTRunner に入れていた 2 行が、これに当たります。

want = _TRT2TORCH[self.engine.get_tensor_dtype(name)]   # エンジンが要求する型を問い合わせる
t = t.to(device=self.device, dtype=want).contiguous()   # 合わせてから渡す
if not self.ctx.set_tensor_address(name, t.data_ptr()):
    raise RuntimeError(f"set_tensor_address failed: {name}")

「fp16 でビルドしたのだから入力も fp16 だろう」は成り立ちません。必ずエンジンに聞いてください。

第2部: mode='linear' が黙って nearest で実行されていた

5 つの中で最も見つけにくく、最も驚いた罠です。

症状

前編で扱った 5D の grid_sample は、TensorRT がビルドを拒否してくれます（＝親切）。では 4D の `grid_sample` はどうかというと、ビルドも実行も問題なく成功します。

ところが出力を PyTorch と比べると、一様にズレている。fp16 でも fp32 でも同じだけズレる。つまり精度の問題ではなく、構造的に何かが違う。それでいて出力画像はパッと見では「ちゃんとそれらしい」のです。

まず、何が起きているかを突き止める

再現用の最小構成はこれだけです（build_engine / TRTRunner は前編のものをそのまま使います）。

class PlanarWarp(nn.Module):
    """4D grid_sample を含む最小モジュール"""
    def forward(self, im, grid):
        return F.grid_sample(im, grid, align_corners=False)

torch.manual_seed(0)
im = torch.randn(1, 8, 128, 128, device="cuda")
grid = torch.rand(1, 128, 128, 2, device="cuda") * 2 - 1
model = PlanarWarp().eval().cuda()

torch.onnx.export(model, (im, grid), "planar_warp.onnx",
                  input_names=["im", "grid"], output_names=["y"],
                  opset_version=20, dynamo=True)
build_engine("planar_warp.onnx", "planar_warp.plan", fp16=False)
runner = TRTRunner("planar_warp.plan")
trt_out = runner.run({"im": im, "grid": grid})["y"]

原因を突き止めるために、TensorRT の出力を、PyTorch の `F.grid_sample` の全解釈と総当たりで突き合わせました。mode（bilinear / nearest）× align_corners（True / False）× padding_mode（zeros / border / reflection）の全 12 通りです。

for mode, align, pad in itertools.product(
        ["bilinear", "nearest"], [False, True], ["zeros", "border", "reflection"]):
    ref = F.grid_sample(im, grid, mode=mode, align_corners=align, padding_mode=pad)
    print(mode, align, pad,
          (trt_out - ref).abs().max().item(),   # 最大絶対誤差
          torch.equal(trt_out, ref))            # ビット単位の一致判定

結果がこちらです。

TensorRT の出力は、`mode='nearest', align_corners=False` の結果と `torch.equal` が True、つまりビット単位で完全一致しました。 一方、本来あるべき bilinear との差は 3.1 以上あります。バイリニア補間が最近傍補間にすり替わると、出力は「なんとなくジャギーになる」程度の変化しか見せません。ワーピング処理の中に埋もれていると、目視ではまず気づけません。

なぜ起きるか — opset 16 と 20 で切り分ける

ONNX ファイルのノード属性を確認すると、こう書かれていました。

ONNX GridSample attributes: {'align_corners': 0, 'mode': 'linear', 'padding_mode': 'zeros'}

mode は opset 20 の仕様どおり正しく linear と書かれています。ここで重要な事実があります。ONNX の GridSample は、opset 16 では補間モード名が `bilinear` で、opset 20 で `linear` へ改名されました。そして TensorRT の公式ドキュメント上、GridSample の linear 補間はサポート対象です。つまり「TensorRT が linear をサポートしない」わけではない。怪しいのは opset 20 の新しい属性名を、取り込み（parser）がどう解釈しているかです。

そこで、同じモデル・同じ入力を opset 16 と 20 の両方で export して比較しました。

同じ TensorRT・同じモデルで、opset 16 なら正しく、opset 20 だと nearest になる。この実測から、当環境の TensorRT 10.16 の ONNX 取り込み経路が、opset 20 で導入された mode='linear' を正しく線形補間へ対応づけられず、nearest へフォールバックしている可能性が高いと強く推定できます（ONNX 仕様でも TensorRT のドキュメント上でも linear はサポート対象・既定側の値なので、「nearest が既定だから」ではありません。parse 後のレイヤ属性や parser 実装までは確認していないため、発生箇所の断定はしていません。将来のバージョンで修正される可能性もあります）。

回避策 — 簡単な順に 3 つ

回避策 1: opset 16 で export する（最も簡単・実測済み）

上の表のとおり、opset 16 で export すれば当環境では正しく bilinear になります。5D が必要（opset 20 が必須）でない限り、これで十分です。

回避策 2: `grid_sample` を基本演算に分解する（TensorRT 実行まで実測済み）

opset 20 を使う事情がある場合や、演算そのものを TensorRT 任せにしたくない場合は、その演算を、TensorRT で数値実績のある基本演算だけで数学的に等価に組み直す手があります。バイリニア補間は要するに「4 近傍を取ってきて重み付き平均する」だけなので、Floor / Clamp / Gather / 四則演算に分解できます。

回避策 3: カスタムプラグイン（後編で扱います）

import torch
import torch.nn.functional as F

def bilinear_grid_sample(im, grid, align_corners=False):
    """F.grid_sample(im, grid, mode='bilinear', padding_mode='zeros') の forward 推論を再現する実装。

    export 時だけこちらへ差し替えて使う。有限値の grid を前提とし、
    NaN/Inf・backward・border/reflection・5D 入力は対象外。
      im:   (N, C, H, W)
      grid: (N, Hg, Wg, 2)  値域 [-1, 1]（x, y の順）
    """
    n, c, h, w = im.shape
    gx, gy = grid[..., 0], grid[..., 1]

    # 正規化座標 [-1, 1] → ピクセル座標
    if align_corners:
        x = (gx + 1) / 2 * (w - 1)
        y = (gy + 1) / 2 * (h - 1)
    else:
        x = ((gx + 1) * w - 1) / 2
        y = ((gy + 1) * h - 1) / 2

    x0, y0 = torch.floor(x), torch.floor(y)
    x1, y1 = x0 + 1, y0 + 1

    # 4 近傍の重み
    wa = (x1 - x) * (y1 - y)
    wb = (x1 - x) * (y - y0)
    wc = (x - x0) * (y1 - y)
    wd = (x - x0) * (y - y0)

    # padding_mode='zeros' の再現:
    # 1px のゼロパディングを張り、インデックスを [-1, size] に clamp してから +1 する。
    # どれだけ範囲外へ外れても、値 0 のパディング画素を参照する形に落ちる。
    im_p = F.pad(im, (1, 1, 1, 1), mode="constant", value=0.0)
    x0i = (x0.clamp(-1.0, float(w)) + 1).long()
    x1i = (x1.clamp(-1.0, float(w)) + 1).long()
    y0i = (y0.clamp(-1.0, float(h)) + 1).long()
    y1i = (y1.clamp(-1.0, float(h)) + 1).long()

    wp = w + 2
    im_flat = im_p.reshape(n, c, -1)          # (N, C, (H+2)*(W+2)) に平坦化

    def gather(yi, xi):
        # ONNX / TensorRT との対応を確実にするため GatherElements(dim=2) の形に寄せる
        idx = (yi * wp + xi).reshape(n, 1, -1).expand(-1, c, -1)
        return torch.gather(im_flat, 2, idx)

    va, vb, vc, vd = gather(y0i, x0i), gather(y1i, x0i), gather(y0i, x1i), gather(y1i, x1i)

    hg, wg = grid.shape[1], grid.shape[2]
    out = (va * wa.reshape(n, 1, -1) + vb * wb.reshape(n, 1, -1)
           + vc * wc.reshape(n, 1, -1) + vd * wd.reshape(n, 1, -1))
    return out.reshape(n, c, hg, wg)

この分解版は、PyTorch 上のセルフテストだけでなく、実際に ONNX export → TensorRT build → 実行まで通して検証しました。三者比較の実測はこうです。

TensorRT に載せても正しく bilinear のまま動く、というところまで確認できています。範囲外のグリッドを含むセルフテストも一緒に書いておくとよいでしょう。

torch.manual_seed(0)
dev = "cuda:0"
src = torch.randn(4, 3, 256, 256, device=dev)

cases = {
    "uniform_pm1":   torch.rand(4, 256, 256, 2, device=dev) * 2 - 1,
    "outside_pm1.5": torch.rand(4, 256, 256, 2, device=dev) * 3 - 1.5,   # 範囲外を含む
}
ys, xs = torch.meshgrid(torch.linspace(-1, 1, 256, device=dev),
                        torch.linspace(-1, 1, 256, device=dev), indexing="ij")
ident = torch.stack([xs, ys], dim=-1).expand(4, -1, -1, -1)
cases["identity_plus_flow"] = ident + torch.randn(4, 256, 256, 2, device=dev) * 0.05

for name, grid in cases.items():
    ref = F.grid_sample(src, grid)          # bilinear / zeros / align_corners=False
    got = bilinear_grid_sample(src, grid)
    ma = float((ref - got).abs().max())
    print(f"[selftest] {name}: max_abs={ma:.3e} -> {'PASS' if ma < 1e-5 else 'FAIL'}")

ポイントは、この差し替えを export 用のラッパの中だけで行うことです。 本番のモデルコードには一切手を入れずに済みます。

第3部: 同じ世代でも、GPU の機種が違うとエンジンは壊れ得る

症状

ある GPU でビルドしたエンジンを、同じ Blackwell 世代（sm_120）の別の機種へ持っていって実行しました。動きはします。速度も出ます。

しかし出力が壊れていました。

TensorRT のログにはこう出ていました（後半の 1 文をそのまま引用します）。

[TRT] [WARNING] Using an engine plan file across different models of devices is not
supported and is likely to affect performance or even cause errors or deadlock.

前段にはもう 1 本、「このデバイスが持つ SM（Streaming Multiprocessor）の数より、このエンジンが要求する SM 数のほうが多い。デッドロックの可能性が高い」という趣旨の警告も出ます。それでも `deserialize` は成功し、`execute_async_v3` も `True` を返し、処理は止まりません。

なぜ起きるか

前編で書いたとおり、TensorRT はビルド時に実機でカーネルを実測し、最速の実装を選びます。既定設定のエンジンは、Compute Capability だけでなく、ビルドした GPU の複数のハードウェア特性（SM 数・共有メモリ・L2 キャッシュなど）を前提として実行計画を組んでいます。別機種ではこれらが異なるため、性能低下だけでなく実行上の問題につながる可能性があり、TensorRT 自身も不一致を検出して警告を出します。

「Compute Capability が同じなら互換」は誤りです。 同じ sm_120 同士でも、機種が違えば別物として扱う必要があります。

ここが本当に厄介なところ

今回、この状況を再現する検証もしてみました。SM 数の多い機種でビルドしたエンジンを、少ない機種でロードして実行したのです。結果はこうでした。

警告は 2 本とも出ました。しかし出力は、ビルドした機種での結果と一致しました（最大絶対誤差は実測値そのものが 0.0。ただし `torch.equal` までは確認していません）。

つまり、小さくて単純なモデルでは、警告を無視しても「動いてしまう」のです。これが最悪です。開発中に一度「動いた」経験をしてしまうと、この警告はただのノイズに見えます。そして本番の複雑なモデルに載せ替えたとき、CUDA エラーを吐きながら壊れた出力を流し続ける、という形で牙を剥きます。私たちが実際に経験したのは後者でした。

なお公式ドキュメントは、同一アーキテクチャの別 GPU でも機能上は動き、小さな性能低下に留まる場合があるとも説明しています。それでも私たちは、本番運用では この警告を fail-fast の対象（＝出たら止める）として扱う方針にしています。壊れる条件が特定できていない以上、「今は動いているから大丈夫」に賭けるべきではない、という判断です。

回避策

1. エンジンは Compute Capability 単位ではなく「GPU 機種」単位で管理・ビルドする — 保管ディレクトリを sm_120/ で切るだけでは足りません。機種名まで含めて分けます
2. ビルド時に「GPU 製品名・Compute Capability・SM 数・TensorRT / CUDA バージョン」をメタデータ（sidecar JSON など）として保存し、起動時に実行環境と照合して、不一致なら deserialize する前に拒否する — ここが実効的な防波堤です。注意すべきは、`execute_async_v3` の戻り値チェックはこの罠の検出には使えないことです。今回の検証でも、機種不一致の状態で True が返りました
3. TensorRT の警告を本番ではエラー扱いにする — ロガーの WARNING を握りつぶさず、上の照合と併せて fail-fast にします
4. 複数機種への配布がどうしても必要なら、hardware compatibility mode（`SAME_COMPUTE_CAPABILITY` など）でビルドする — 同じ Compute Capability の GPU 間で使うための正式な仕組みです。ただし性能や機能に制約が生じるため、速度と数値を別途検証してから使ってください

第4部: fp32 でビルドしても、TF32 が候補に入る

症状

FP16 tactic を許可した設定では精度が足りなかったモジュールを、FP16 tactic を許可しない FP32 設定でビルドし直しました。それでも PyTorch との一致度が期待より伸びません。しかも、ビルドし直すたびに一致度が微妙に変動する。合格ラインを超えたり超えなかったりします。

なぜ起きるか

TensorRT は fp32 のテンソルに対する畳み込みや行列積について、既定で TF32 tactic の使用を「許可」しています。 TF32 は仮数部を 10 bit に削った高速な形式で、Ampere 以降の Tensor Core で使われます。すべての fp32 演算が TF32 になるわけではなく通常の fp32 実装が選ばれる場合もありますが、「fp32 でビルドした＝すべて fp32 で走っている」という思い込みは成り立ちません。

ビルドごとに結果が揺れた原因として考えられるのが、ビルド時の計測ノイズです。TensorRT のビルドは実機計測に基づくため、性能の近い実装候補からビルドごとに異なる tactic が選ばれる場合があります（公式ドキュメントにもこの説明があります）。ただし今回、実際に選択された tactic の比較までは行っていません。

回避策と、意外な副産物

忠実度を厳密に検証するエンジンでは、TF32 を明示的に無効化します。

config = builder.create_builder_config()
config.clear_flag(trt.BuilderFlag.TF32)     # ★ TF32 tactic を候補から外す

実測結果がこちらです。

最大絶対誤差は 2.55e-04 から 6.26e-07 へ、3 桁改善しました。

そして面白いことに、今回の 1 組のビルドでは、TF32 を無効にした側のほうが速い結果になりました（0.874ms → 0.772ms）。別の tactic が選ばれた可能性はありますが、原因の切り分け（選択 tactic の比較）まではしていません。ビルド時の計測ノイズの影響も受け得る差なので、この約 12% を一般的な傾向と読まないでください。それでも「TF32 を切ると必ず遅くなる」という思い込みで試さないのはもったいないので、速度もその構成で実測してください。TF32 を無効にしても、演算順序や tactic の違いによる PyTorch との数値差が完全になくなるわけではない点も添えておきます。

第5部: ONNX export で引数が入れ替わっていた（最も泣けてきた事故）

最後は、TensorRT の問題ではなく 私たち自身のミスです。しかし、これがシリーズ中で最も発見に時間がかかりました。同じ構造の事故は誰にでも起こりうるので共有します。なお本事例は実務モデルで発生したもので、機密上モデルは公開できず、本記事用のダミーモデルでの再現実験は行っていません。

症状

あるモジュールを TensorRT 化したところ、入力によって出力の壊れ方が変わるという奇妙な症状が出ました。ある条件では完璧に一致するのに、別の条件では明確に劣化します。しかも劣化の量は入力の「動きの大きさ」に比例して拡大していました。

fp16 でも fp32 でも、TF32 を切っても、劣化量は変わりません。この時点で、単純な精度差より構造的な問題を強く疑いました。

なぜ起きたか

torch.onnx.export に渡した引数の順序が、モデルの forward の引数順と食い違っていました。

# forward の定義:   forward(self, feature, kp_driving, kp_source)
# export で渡したもの:      (feature, kp_source, kp_driving)   ← 2 番目と 3 番目が逆
torch.onnx.export(model, (feature, kp_source, kp_driving), "m.onnx", ...)

位置引数なので、Python は何も文句を言いません。 export は成功し、ONNX ファイルも生成され、TensorRT のビルドも通り、実行もできます。ただ、モデルの中で 2 つの入力の役割が入れ替わったまま固定された ONNX ができあがります。

内部の計算が「基準 − 入力A + 入力B」のような差分の形になっていたため、誤差はちょうど 2 ×（2 つの入力の差） になります。だから「差が小さい入力では一致し、差が大きい入力ほど盛大に壊れる」という症状になりました。

なぜ発見が遅れたか — 「自己再演」検証の落とし穴

いちばんの問題はここです。当時の検証は、同じデータを両方の入力に与える形で行っていました。この条件では 2 つの入力が等しいので、入れ替わっていても結果は完全に一致します。テストは堂々と合格していました。

これを私たちは 「自己再演パリティ」の罠と呼んでいます。入力と基準が一致してしまう条件だけで等価性を検証すると、引数の取り違えのような構造的なバグが完全に無害化されます。

見つけ方 — 犯人が TensorRT か ONNX かを切り分ける

このとき有効だったのが、onnxruntime を使った切り分けです。

1. まずモデルを段階的に分割し、どこで数値がズレ始めるかを二分探索する（中間テンソルの比較）
2. ズレる部分グラフが特定できたら、同じ ONNX を onnxruntime の CPU 実行で走らせる
3. onnxruntime でも同じ方向にズレるなら、まず ONNX グラフ・export 時の入力束縛・演算の仕様差を疑う。PyTorch と onnxruntime が一致して TensorRT だけズレるなら、TensorRT の parser・エンジン・実行側の設定を優先して疑う

これは犯人を論理的に確定する手続きではなく、どこから先に調べるかを決める切り分けです（onnxruntime 側にも実装差はあり得ますし、TensorRT 側の入力名や dtype の渡し方の問題ということもあります）。それでも調査の初動を大きく変えてくれます。今回のケースでは onnxruntime でも同じだけ食い違ったため export 側を先に調べ、位置引数の取り違えをコード上で特定しました。

なお、層ごとの比較には polygraphy の全層比較（mark all）が便利ですが、大きなモデルではメモリを使い切って落ちます。実務では、疑わしい部分だけを切り出す二分探索のほうが確実でした。

回避策 — kwargs による keyword 束縛

export への引数の受け渡し自体を keyword にします。 torch.onnx.export には位置引数用の args とは別に、keyword 入力として渡す正式な `kwargs` 引数があります。これを使えば、タプルの順番という概念そのものが消えます。

# 課題: args はタプルであり、位置順で束縛される。forward の引数順を
#       取り違えても export は成功してしまい、入力の役割が入れ替わった
#       ままの ONNX が生成される（input_names は名前を付けるだけで、
#       意味上の対応を保証しない）
# 対策: kwargs 引数で「名前 → テンソル」を明示的に対応づける
torch.onnx.export(
    model,
    args=(),
    kwargs={
        "feature": feature,
        "kp_source": kp_source,
        "kp_driving": kp_driving,
    },
    f="m.onnx",
    input_names=["feature", "kp_source", "kp_driving"],
    output_names=["y"], opset_version=20, dynamo=True,
)

修正後、劣化は完全に消えました。

沈黙劣化を検出する検証設計

5 つの罠を並べると、共通する対策が見えてきます。

1. 速度より先に数値を測る

順序を逆にすると、「速くなった」という良い知らせが先に来てしまい、数値の検証が形式的になります。数値が合っていない高速化には価値がありません。

2. 乱数入力の一致を信用しない — 実データで検証する

これは実測でも裏づけが取れました。LayerNorm と GELU を重ねたブロックを FP16 tactic 許可でエンジン化し、入力のレンジだけを変えて誤差を測ったところ、次のようになりました（比較の基準は PyTorch fp32。表の「FP16 許可 / 不許可」はいずれも TF32 は既定＝許可のままです）。

入力スケールを広げると、FP16 設定の最大絶対誤差は大きく増えました（ただし増加は入力倍率への単純比例ではありません。LayerNorm がスケールを正規化するためです）。一方 nRMSE は 8.9e-04 から 2.5e-04 へむしろ低下しており、少なくとも入力スケールとともに悪化してはいません。つまり絶対誤差と正規化誤差では、同じ結果でも評価の見え方がまったく違います。ここから言えるのは、「絶対誤差いくつ以下なら OK」という合格バーを標準正規乱数だけで決めると、実データのレンジでは簡単に破られるということです。

さらに私たちの実モデルでは、これが単なる誤差の増大では済まず、実データを入れた瞬間に全出力が NaN になるという形で現れました（LayerNorm 直前で中間値が fp16 の表現範囲を超えたためです）。対処は、そのモジュールでは FP16 tactic を許可せず、FP32 設定でビルドすることでした。

3. 「自己再演」で等価性を検証しない

第5部のように、入力と基準が一致する条件だけのテストは、構造的なバグを完全に隠します。検証データには、実運用で起こりうる「差が大きいケース」を必ず含めてください。

4. 犯人の切り分けは「PyTorch / onnxruntime / TensorRT」の三点測量で

• PyTorch と onnxruntime が一致し、TensorRT だけズレる → TensorRT のセマンティクス・カーネルを疑う（第2部）
• onnxruntime でもズレる → ONNX、つまり export を疑う（第5部）

この切り分けができると、調査時間が桁で変わります。

5. 疑わしい演算は「1 個だけ」切り出してテストする

モデル全体で「なんとなくズレている」を追うのは非効率です。第2部は grid_sample 1 個を切り出して総当たり照合したことで、一発で確定しました。

6. 精度を切り替えて症状が変わるかを見る

fp16 / fp32 / TF32 を切り替えても劣化量がほとんど変わらないなら、丸め誤差よりも入力束縛や演算セマンティクスなど、構造的な問題を優先して疑います。証明ではありませんが、調査の優先順位を決める判定として非常に有効でした。

7. 失敗を握りつぶさない仕組みを入れる

execute_async_v3 の戻り値チェック、エンジンとデバイスの整合検査、部品が欠けていたら起動を拒否する設計。「一部が壊れたまま正常に見える」状態を作らないことが、沈黙劣化に対する最後の防波堤です。

まだ確かめていないこと

• `mode='linear'` が nearest になる件の根本箇所 — opset 16/20 の比較から parser 段階の解釈が原因と強く推定していますが、parser のソースコードや parse 直後のレイヤ属性までは確認していません。また検証は TensorRT 10.16.1.11 の 1 バージョンのみで、将来のバージョンで修正される可能性があります
• 機種またぎで壊れる条件 — 今回のダミーモデルでは警告が出ても出力は一致しました。「どの程度の規模・構造から壊れ始めるか」は特定できていません
• int8 量子化での同種の問題 — 本記事は fp16 / fp32 / TF32 のみを扱っています

まとめ

一言でまとめると、「TensorRT への移行パイプラインでは、『ビルドが通った』も『実行できた』も『速くなった』も、出力が正しいことを一切保証しない」ということです。

だからこそ、速度を測る前に数値を測り、乱数ではなく実データで測り、ズレたら三点測量で犯人を切り分け、失敗を握りつぶさない仕組みを入れておく。これが TensorRT を本番に載せるための最低条件だと考えています。

次回（後編）は、前編で保留にした最大の宿題、TensorRT がネイティブに対応していない 5D grid_sample を、カスタムプラグインで通す話をお届けします。新しい CUDA / TensorRT 世代でこれをビルドするには、いくつも越えるべきものがあります。手元の nvcc が Blackwell 向けのコードを生成できないときにどうするか、pip で入れた TensorRT には開発用ヘッダが入っていないという問題、そしてプラグインの fp16 カーネルが数値破綻するという、またしても沈黙劣化に近い話です。

それでは、また次回、お会いしましょう！

参考資料（一次情報・主要ソース）

• NVIDIA TensorRT ドキュメント（Developer Guide / Release Notes）
• ONNX Operators: GridSample（mode / align_corners / padding_mode の仕様）
• PyTorch: torch.nn.functional.grid_sample
• NVIDIA/TensorRT issue #3890: 5D GridSample のネイティブ対応要望
• NVIDIA: TensorFloat-32（TF32）の解説
• polygraphy（TensorRT のデバッグ・比較ツール）
• 当社関連記事: 2026年 NVIDIA GPU 一発検索ツール

こんにちは！

2026年7月24日、AnthropicからClaude Opus 5がリリースされました。

Opus 4.8（5月28日リリース）からわずか2ヶ月での世代交代です。このあたりのスピード感、加速していますね。

さて、当ブログではClaude Opus 4.7 完全ガイド、Claude Opus 4.8 完全ガイドとOpusの世代を追いかけてきましたが、今回のOpus 5は過去2回の「4.x内のアップデート」とは立て付けが根本的に違います。

何が違うのか。まず、Opus 5は「最上位モデル」ではありません。

Anthropicのラインナップには2026年6月9日リリースのClaude Fable 5が最上位として存在し、Opus 5はその下位、Sonnet 5の上位という「中上位」ポジションで投入されました。

Opusという名前が「最上位ティア」を意味した時代は、Fable 5の登場で終わっています。

そのうえでAnthropicはOpus 5を「Fable 5のフロンティア級の賢さに、半額で迫るモデル」と位置づけ、一部ベンチマークではFable 5を上回るスコアさえ公表しています。

価格はOpus 4.8と同じ入力$5・出力$25。

つまり「最上位ではないが、実務ではこれが本命」という、いままでのOpusにはなかったキャラクターです。

しかも思い出してほしいのですが、Fable 5は6月12日に米国政府の指令で一時提供停止になり、7月1日に復帰するという波乱を経ています（経緯はFable 5・Mythos 5 提供停止の経緯で詳しく書きました）。

この事件の中心にあった「安全分類器」が、実はOpus 5にも搭載されました。

Opus 4.8にはなかったものが載ったわけで、これは移行時に必ず知っておくべき変化です（第7章で詳しく扱います）。

本稿は長編なので、頭から通読する必要はありません。気になる章だけ拾い読みしてください。出典は記事末にまとめてあります。

想定読者は、Opus 4.8からの移行を検討しているエンジニア、Fable 5とOpus 5のどちらを使うべきか判断したいテックリード、Claude Codeをチームで運用しているリードエンジニア、そしてAPI利用のコスト最適化を考えている方です。

目次

第1部　Claude Opus 5とは何か

• 1. Claude 5ファミリーの中でのOpus 5の位置づけ
• 2. Claude Opus 5の基本仕様
• 3. ベンチマークで見る「Fable 5超え」の中身
• 4. thinkingまわりで変わる2つのAPI破壊的変更
• 5. 移行チェックリスト（公式ガイドより）
• 6. 新機能・関連機能まとめ

第2部　APIで使うときの注意点

• 7. 4.8にはなかった安全分類器が搭載された
• 8. Effortの使い分け
• 9. エージェントに予算感覚を持たせるTask budgets（beta）
• 10. Opus 5を最大限引き出すプロンプティング

第3部　Claude Codeで使うOpus 5

• 11. Claude CodeでOpus 5を使う前提
• 12. Claude Codeのeffort設定は引き継ぎ挙動に注意
• 13. Fast modeの変更点
• 14. フラグされたらどうなるか、自動モデルフォールバックの仕組み
• 15. 1Mコンテキストとopusplan
• 16. 日常運用のリズム

4.8からのアップデート、ざっくり

前回記事で扱ったOpus 4.8から、Opus 5では主に次の点が変わりました。

詳細は各章で扱いますが、まず全体像です。

段階的改善ではなく「step-change（段差のある改善）」

公式ドキュメント自身が4.8比を「incrementalではなくstep-change」と表現しています。深い推論・長時間エージェンティックタスク・test-time compute scalingで最大の伸びです（第3章）。

thinkingがデフォルトON

4.8ではthinkingフィールド無しのリクエストは思考なしで動きましたが、Opus 5では同じリクエストが思考ありで動きます。max_tokensの見直しが必要です（第4章）。

thinking無効化はeffort `high`以下でのみ可能（破壊的変更）

thinking: {type: "disabled"}とeffort xhigh/maxの組み合わせは400エラーになります（第4章）。

effortの推奨スタート地点が変化

APIデフォルトは従来どおりhighのままです。公式ガイドの推奨が4.7/4.8の「コーディングはxhighで開始」から、Opus 5では「highで開始し、要求の厳しい作業のみxhighへ」に変わり、low/mediumの積極活用が明記されました（第8章）。

Web Fetchサーバーツール非対応

Opus 4.8で使えるWeb FetchツールはOpus 5では利用できません（Web検索とは別機能です）。利用中のAPI統合は代替設計が必要です（第5章）。

安全分類器が搭載された

4.8にはなかったモデル固有のサイバー・生物学分類器がOpus 5には載っています。介入頻度はFable 5より約85%少ないとされますが、4.8からの移行では新しい制約になります（第7章）。

ナレッジカットオフが2026年5月

Fable 5・Sonnet 5（いずれも2026年1月）より新しく、現行ラインナップで最も新しい知識を持ちます（第2章）。

新機能・関連機能

会話途中のツール変更（beta）、fallbacksパラメータの"default"モード（beta）、Task budgets（beta）、キャッシュ最小長が512トークンに低下、などがあります（第6章・第7章・第9章）。

価格は据え置き

入力$5・出力$25のまま。Fast modeも$10/$50でOpus 4.8と同額です（第2章）。

Priority Tier非対応

Opus 4.8では使えたPriority TierがOpus 5では未サポートです。コミットメントがある組織は容量計画に注意してください（第5章）。

なお、Opus 4.8向けのコードはモデルIDの差し替えだけで動くとは限りません。

thinkingデフォルトの変化と、thinking無効化の制限という2つの挙動変更があるため、移行チェックリスト（第5章）を一度通すことをおすすめします。

第1部　Claude Opus 5とは何か

1. Claude 5ファミリーの中でのOpus 5の位置づけ

まず、2026年6月からの2ヶ月弱でAnthropicのラインナップがどう変わったかを整理します。

この期間、Anthropicは4つのモデルを立て続けに投入しました。

• 6月9日 Claude Fable 5 / Claude Mythos 5 リリース（新設の最上位「Mythosクラス」。ベンチマーク解説）
• 6月12日 米商務省の輸出管理指令により両モデルの提供を全世界で停止（経緯の詳細）
• 6月26日 Mythos 5が審査済み米国組織限定で一部復帰
• 6月30日 輸出規制が解除。同日、Claude Sonnet 5リリース（導入価格$2/$10、2026年8月31日まで。以降$3/$15）
• 7月1日 Fable 5がclaude.ai・Claude Code等で全面復帰
• 7月24日 Claude Opus 5リリース。同日、Opus 4.7のFast modeが提供終了

この結果、現在のラインナップは上から Fable 5（$10/$50）、Opus 5（$5/$25）、Sonnet 5（$3/$15）、Haiku 4.5（$1/$5）という4層構造です。

Opus 5の公式な位置づけは「complex agentic coding and enterprise work（複雑なエージェンティックコーディングとエンタープライズ業務）向け」です。

AnthropicはこれをClaude Maxの新デフォルトモデル、Proプランで使える最上位モデルに据えました。

「日常の主力はOpus 5、真にフロンティアな仕事だけFable 5」という使い分けをAnthropic自身が推奨する構図です。

（出典はAnthropic公式モデル一覧。価格・カットオフは2026年7月27日時点）

見落とされがちですが重要なのがナレッジカットオフです。

Opus 5のreliable knowledge cutoffは2026年5月で、
Fable 5・Sonnet 5の2026年1月より4ヶ月新しく、現行ラインナップ最新です。

新しめのライブラリやAPIを扱う場面では、「上位」のFable 5より新しい知識を持っている可能性があります。

ただしカットオフの新しさが個別仕様の正確性を保証するわけではありません。後述のとおりOpus 5はWeb Fetchサーバーツール非対応（第5章）なので、最新情報の取り込みはWeb検索ツールや自前の取得で補い、公式ドキュメントとの照合は引き続き必要です。

LLM各社の料金体系の比較はLLM API価格まとめ、Fable 5のコスト問題についてはFable 5のコストと展望も参考にしてください。

Fable 5は「トークン消費が激しい」という利用者の不満が広く報じられており、Fortuneによれば、Opus 5がトークン効率を前面に出すのはこの不満への回答でもあります。

7月9日にリリースされたOpenAIのGPT-5.6も経済的なトークン消費を売りにしており、「賢さ」から「賢さとコストの釣り合い」へ競争軸が移っていることがわかります。

2. Claude Opus 5の基本仕様

4.8から引き継がれた仕様も多い一方、「1Mがデフォルトかつ最大で、そもそも小さいコンテキストのバリアントが存在しない」「thinkingがデフォルトON」の2点は世代の切り替わりを感じさせます。

なおclaude-opus-5はエバーグリーンなポインタではなく固定スナップショットです（Claude 4.6世代から続く日付なしID方式）。

3. ベンチマークで見る「Fable 5超え」の中身

Anthropicのローンチ発表は、複数のベンチマークで「Opus 5がFable 5を上回る」と主張しています。

当ブログの流儀に従い、誰が測った数値かを区別しながら見ていきます。

Frontier-Bench v0.1（Anthropicによる内部実行）

System Cardの評価サマリー表でOpus 5が43.3%と比較対象モデル中トップ。Fable 5の33.7%、Opus 4.8の18.7%を大きく上回り、4.8比では2倍超です。しかもタスクあたりコストは低いとされます。

ローンチ時の公式チャートにはeffortレベル別の複数値も示されているため、43.3%がOpus 5のeffort別ピーク値とは限りません。

ARC-AGI 3（ARC Prizeによる検証済み外部評価）

Opus 5はhigh effortで30.16%（公表時の丸め値30.2%）。次点とされるGPT-5.6 Solの7.8%の約3.9倍です（Anthropicの発表文は「3倍」と控えめに表現しています）。

Opus 4.8は1.5%とほぼゼロでした。なお評価期間が短かったため、Opus 5のmaxはARC-AGI 3では未評価です。

CursorBench 3.2（Cursorによる外部評価）

max時にOpus 5が70.0%、Fable 5が70.5%と0.5ポイント差。タスクあたり平均コストはOpus 5の$8.23に対しFable 5は$17.32と2倍超です。

ただしCursor自身が「小さなスコア差は統計的に有意でない可能性がある」と注記しています。

OSWorld 2.0（コンピュータ操作。Anthropic評価、System Card記載）

70.57%（5回実行の平均初回成功率）でOpus 4.8の55.7%から大幅改善。Fable 5のベスト結果を約3分の1のコストで上回るとされます。

Zapier AutomationBench（外部の評価提供者による結果）

合格率が次点モデルの約1.5倍です（同等のタスクあたりコストで）。

ライフサイエンス（Anthropic自身の評価）

有機化学タスクでOpus 4.8比+10.2ポイント、タンパク質予測で+7.7ポイント。AnthropicはOpus 5を「科学研究向けに最も高性能な一般提供モデル」と押し出しています。

注意点を2つ挙げます。

第一に、数値の帰属は3種類に分かれます。(a) Anthropicが自社で実行した評価（Frontier-Bench・OSWorld・ライフサイエンス）、(b) ベンチマーク提供者が実行・掲載した外部評価（ARC Prize・Cursor・Zapier）、(c) それらを報じた報道です。

(b)は自己申告ではありませんが、第三者コミュニティによる独立追試とも別物です。

第二に、「Fable 5超え」はすべてのベンチマークの話ではありません。

Anthropic自身、最高難度の長時間自律タスクではFable 5を推奨し続けており、サイバーセキュリティのエクスプロイト能力では「Mythos 5に及ばない」と明言しています。

ブラインド投票（Arena系）やLLMランキングでどう出るかは、独立評価が出揃ってからの答え合わせになります。

TechCrunchは、Anthropicが強調した特性として「自分の成果物を検証し、成功するまで丁寧にイテレーションする」点を挙げています。

早々に勝利宣言せず、検証して直す。これは後述するプロンプティングの変化（自己検証と重複する再検証指示を外す。第5章・第10章）と表裏一体の、Opus 5の性格を象徴する変化です。

4. thinkingまわりで変わる2つのAPI破壊的変更

Opus 4.7から4.8のときは「モデルID差し替えだけで動く」移行でした。

今回はAPIパラメータ上の破壊的変更が2つあります。加えて機能面では、前述のWeb FetchとPriority Tierの非対応という実質的な非互換もあります（第5章のチェックリストで扱います）。

変更その1、thinkingがデフォルトONになった

Opus 4.8ではthinkingフィールドを付けないリクエストは思考なしで動きました。

Opus 5では同じリクエストが思考ありで動きます（モデルがターンごとに思考の要否と深さを判断するアダプティブシンキング）。

ワイヤ上の値は変わっておらず、thinking: {type: "adaptive"}を明示しても同じ挙動です。

実務上の注意はmax_tokensです。

max_tokensは思考と本文の合計に対するハードリミットなので、4.8で思考なしで動かしていたワークロードをそのまま移すと、思考トークンが加わったぶん本文が途中で切れる（stop_reason: "max_tokens"）ことがあります。

thinkingなし前提で小さめのmax_tokensを設定していた箇所は見直してください。

変更その2、thinking無効化はeffort `high`以下のみになった

旧挙動を維持したい場合はthinking: {type: "disabled"}を渡せますが、Opus 5ではeffortレベルがhigh以下のときしか受け付けられません。

thinking: {type: "disabled"}とeffort xhigh/maxの組み合わせは400エラーになります。

4.8ではこの組み合わせが通っていたので、移行前に該当リクエストを洗い出しておく必要があります。

チェックはリクエスト単位で毎回行われるため、「会話の前半は通っていたのに、途中でeffortを上げた瞬間に400」ということも起こります。

# 4.8では通るが、Opus 5では400エラーになるリクエスト
client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    output_config={"effort": "xhigh"},   # disabled と xhigh の組み合わせが不可
    messages=[{"role": "user", "content": "..."}],
)

# 対処A thinkingフィールドを外す（デフォルトの思考ありに戻す）
client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    output_config={"effort": "xhigh"},   # thinking はデフォルトON
    messages=[{"role": "user", "content": "..."}],
)

# 対処B thinking無効を維持して effort を high 以下へ
client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    output_config={"effort": "high"},    # high / medium / low なら可
    messages=[{"role": "user", "content": "..."}],
)

さらに公式ドキュメントは、thinkingを無効化した場合の副作用を明記しています。

思考なしのOpus 5は、まれにツール呼び出しをtool_useブロックではなく本文テキストとして書いてしまうことがあります。呼び出しは実行されず、エージェントループでは漏れたテキストが会話履歴に残って後続ターンにも影響します。

<thinking>等の内部XMLタグを可視出力に混ぜてしまうこともあります。

公式の推奨は「thinkingは有効のまま、コストは低effortで制御する」です。

ほとんどのタスクで「thinking有効かつlow effort」のほうが「thinking無効」より同等コストで良い結果になるとされています。どうしても無効化が必要な統合向けのプロンプト緩和策は第10章で扱います。

5. 移行チェックリスト（公式ガイドより）

公式移行ガイドのチェックリストを、実務の順序に並べ直したものです。

1. モデル名をclaude-opus-4-8からclaude-opus-5へ更新する
2. Web Fetchサーバーツールを使っているリクエストを洗い出す。Opus 5では利用できないため、Web検索ツール・クライアント側での取得・該当処理だけ別モデルへルーティング、等の代替を設計する
3. thinkingフィールド無しで運用していたワークロードを洗い出す（Opus 5では思考ありで動く）。max_tokensを見直すか、thinking: {type: "disabled"}とeffort high以下で旧挙動を維持する
4. thinking: {type: "disabled"}とeffort xhigh/maxを併用しているリクエストを修正する（400エラーになる）
5. effort設定を白紙から再評価する。旧モデルから持ち越さず、自分のevalsでeffortスイープを取り直す。low/mediumはコスト・レイテンシ制御として積極的に試し、maxは能力優先タスクで試す価値あり。xhigh/maxで走らせるならmax_tokensは64k以上から
6. キャッシュ境界付近のプロンプトを確認する（512トークン以上でキャッシュ可能に。4.8では1,024）
7. stop_reason: "refusal"のハンドリングを確認し、fallbacks: "default"（beta）の採用を検討する（第7章）
8. Priority Tierのコミットメントがある組織は容量計画を分けて立てる。Priority TierはOpus 5非対応で、Opus 4.8では引き続き利用可能
9. エージェンティックワークロードならTask budgets（beta）とmid-conversation tool changes（beta）を検討する（第9章・第6章）
10. 長さ・冗長性のプロンプトを再調整する。Opus 5は可視応答も成果物ドキュメントも長くなりがちで、effortを下げても短くならない（第10章）
11. 旧モデル向けの再検証指示（「最後に検証ステップを入れよ」「ダブルチェックせよ」「サブエージェントで検証せよ」等）を削除する。Opus 5は言われなくても自己検証するため、残すと過剰検証でトークンを浪費する。ただし、指定テストの実行・lint・型検査といったプロジェクト固有の受入条件は削除しない（第10章）
12. 自分のワークロードでコストとレイテンシを再ベースラインする

このうち5・10・11は「壊れないが最適でなくなる」系で、飛ばしてもエラーにはなりません。

ただし11（重複する再検証指示の削除）は公式が「品質を落とさずトークン削減」と明言している数少ない項目なので、優先度高めで対応する価値があります。

6. 新機能・関連機能まとめ

Opus 5で利用できる新機能・関連機能を整理します。

Opus 5と同時に追加された機能だけでなく、既存機能のOpus 5対応も含みます。詳細は該当章で扱います。

Mid-conversation tool changesは地味ながらエージェント開発者に効く変更です。

従来、ツールリストを変えるとキャッシュ済みプレフィックスが無効化されるため、セッションの最初に全ツールを渡しておくのが定石でした。

betaヘッダmid-conversation-tool-changes-2026-07-01を付けると、タスクの進行に応じてツールを段階的に公開したり退役させたりしても、それ以前のターンのキャッシュヒットが保てます。

4.8で入ったmid-conversation system messages（会話途中のシステムメッセージ追記）の続編と考えるとわかりやすい機能です。

第2部　APIで使うときの注意点

7. 4.8にはなかった安全分類器が搭載された

先に重要な事実を押さえてください。

Fable 5と同系のモデル固有安全分類器（サイバーセキュリティ・生物学）が、Opus 5にも搭載されました。

そしてOpus 4.8にはこの分類器は載っていません。

公式ドキュメントが分類器つきと明記しているのはFable 5とOpus 5だけです。フラグされたリクエストの逃がし先がOpus 4.8であること自体が、4.8に同じ分類器がないことの裏付けです。

なお4.8時代にも、プラットフォーム側のUsage Policyセーフガードの誤検知はありました。6月の記事で扱ったものがそれで、モデル固有分類器とは別の層の話です。

つまり4.8から移行するユーザーにとって、これは新たに加わる制約です。

「安全になった」という話ではなく、「分類器が付いてしまった。ただしFable 5ほど頻繁には介入しない」と読むのが正確です。

そのうえで、Fable 5の提供停止で業務が止まる経験をした直後という文脈では、Fable 5との違いにも実務上の意味があります。ポイントは4つあります。

(1) アライメント自体は歴代最良

Anthropicの自動挙動監査（automated behavioral audit）で、Opus 5のミスアライン挙動スコアは2.3（低いほど良い）。

Opus 4.8・Sonnet 5・Fable 5を含む近年のモデルで最良で、「最もアラインされたOpusであり、悪用に誘導されにくい」とAnthropicは主張しています（自己評価である点に留意してください）。

(2) 分類器の介入はFable 5比で約85%減（ゼロではない）

Fable 5はサイバーセキュリティ能力の高さゆえに強力な安全分類器を常時走らせており、これが正当なセキュリティ業務まで妨げるという不満がありました。

Opus 5では素のエクスプロイト能力をMythos 5より意図的に抑えたうえで、分類器の介入頻度を「Fable 5の約85%減」に抑えたとしています。

裏を返せば、4.8では起きなかったモデル分類器の介入が、Opus 5では一定頻度で起きるということです。

線引きとしては、ソースコードを対象とする脆弱性発見は許可する一方、バイナリを対象とした脆弱性スキャンやエクスプロイト生成はブロックする設計です。

防御的セキュリティのための特別枠であるProject Glasswing（Mythos 5の提供枠組み）についてはGlasswing解説記事を参照してください。

Cyber Verification Program（CVP）参加済みの企業・研究者は、制限が緩和された状態でOpus 5に即アクセスできます。

(3) フラグ時の自動フォールバック（API側）

分類器がリクエストをフラグしたとき、エラーで終わらせず別モデルに自動で流す選択肢が入りました。

fallbacksパラメータの新しい"default"モード（fallbacks: "default"）は、拒否カテゴリに応じてAnthropic推奨のフォールバックモデルを自動選択します。たとえばOpus 5のサイバー系拒否はOpus 4.8へ流れます。

従来の明示的なモデルリスト指定も引き続き可能で、"default"モードにはserver-side-fallback-2026-07-01ベータヘッダが必要です。

(4) データ保持の違い（公式ドキュメントで確認）

Anthropic公式の「API and data retention」ドキュメントは、30日データ保持が必須の「Covered Models」としてFable 5とMythos 5を明記しており、この2モデルはZDR（ゼロデータリテンション）では利用できません。Claude CodeのモデルピッカーにもZDR環境では出ません。

Opus 5はCovered Modelsに含まれておらず、ローンチ発表でも一般アクセスのOpus 5にモデル固有のデータ保持要件は課されていません。

したがってClaude APIでZDR契約を持つ組織は、ZDR適格な機能の範囲でOpus 5を利用できます。

ただしZDRは組織単位の契約で、Pro/Max等のコンシューマープラン自体は対象外です。Batch APIやコード実行などZDR対象外の機能もあるため、実際の適用範囲は契約条件と機能別のZDR適格性を確認してください。

まとめると、視点によって評価が分かれる変更です。

4.8ユーザーから見れば、分類器の搭載は純粋に制約の追加です。セキュリティ・生物学が絡むワークロードでは、4.8で通っていた処理が止まる可能性があります（4.8の継続利用も選択肢です。第16章）。

一方、Fable 5ユーザーから見れば、介入頻度は約85%少なく、モデル固有の30日保持要件がなく、サイバー系の拒否には自動フォールバックも用意されているぶん、明らかに扱いやすくなっています。

なお自動フォールバックはAPIではオプトインで、Opus 5の生物学カテゴリにはフォールバック先がない（第14章）等の制約はあります。将来の規制措置まで保証するものでもありません。

8. Effortの使い分け

effortはOpus 4.7以降、Opusを使いこなす最重要レバーであり続けています。

Opus 5では公式ガイドの推奨の書き方が変わりました。

誤解しやすいので先に整理すると、APIのデフォルトは4.7以降ずっとhighのまま変わっていません。変わったのは推奨スタート地点の記述です。

4.7/4.8の公式ガイドは「コーディング・エージェンティック用途はxhighで開始（Start with xhigh for coding and agentic use cases）」と明記していました。

Opus 5のガイドは「high（デフォルト）で開始し、evalsに基づいて調整せよ。要求の厳しいコーディング・エージェンティック作業ではxhighへステップアップ（Start with high, the default … step up to xhigh for demanding coding and agentic work）」という書き方になっています。

表にします。

書き方が変わった背景は、Opus 5の低effortの効率改善です。

公式は「lowとmediumが、上位設定のわずかなトークンとレイテンシで強い品質を出す」とし、「low/mediumをコストと応答時間の主要コントロールとして自由に（liberally）使え」とまで書いています。

4.8時代の「とりあえずxhigh」を無条件に持ち込むと、品質差が小さいのにトークンだけ倍増、ということになりかねません。

旧モデルからeffort設定を持ち越さず、自分のevalsでスイープを取り直すのが公式の明確な推奨です。

一方で上端のmaxは、追加effortを結果に変換する能力（test-time compute scaling）が歴代Opusで最も高いため、4.8時代より試す価値が上がっています。

CursorBenchでFable 5のピークに0.5ポイント差まで迫ったのもmax effort時の話です。

xhigh/maxで走らせるときは、思考とツール呼び出しの余地を確保するためmax_tokensを64k以上から始めて調整してください。

effortに関する固有の注意が2つあります。

effortは可視応答の長さを制御しない

Opus 5でeffortを下げると思考量は減りますが、ユーザー向け応答の長さは確実には短くなりません。応答を短くしたければプロンプトで明示します（第10章）。

effortは会話の途中で変えない

effortはレンダリングされるプロンプトに影響するため、リクエスト間で値を変えるとそれ以前のプレフィックスのプロンプトキャッシュが無効になります。キャッシュに依存する長いセッションでは、最初に決めた値を固定してください。

なお、thinking: {type: "disabled"}と併用できるのはhigh以下のみという制約（第4章）もeffort選択に影響します。

「思考は切りたいがeffortは上げたい」という構成はOpus 5では組めません。

9. エージェントに予算感覚を持たせるTask budgets（beta）

Opus 5でも利用できるbeta機能の中で、エージェント基盤の開発者にいちばん面白いのがTask budgetsです。

betaヘッダはtask-budgets-2026-03-13。対応はOpus 5 / Fable 5 / Mythos 5 / Opus 4.8 / 4.7で、Sonnet 5は非対応です。Opus 5固有の新機能ではなく、既存beta機能のOpus 5対応です。

output_config.task_budgetに{type: "tokens", total: N}を渡すと、思考・ツール呼び出し・ツール結果・出力を含むエージェンティックループ全体のトークン予算をモデルに伝えられます。

モデルはサーバー側で注入されるカウントダウンを見ながら、残り予算に応じて作業の優先順位を付け、予算が尽きる前に「発見の要約」「進捗の報告」といった形で優雅に着地します。

with client.beta.messages.stream(
    model="claude-opus-5",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 64000},
    },
    messages=[{"role": "user", "content": "Review the codebase and propose a refactor plan."}],
    betas=["task-budgets-2026-03-13"],
) as stream:
    response = stream.get_final_message()

概念の整理をしておきます。

effortが「各ステップの推論の深さ」を制御するのに対し、task_budgetは「ループ全体の仕事量」を制御します。

深さのeffort、総量のtask budget、そして毎リクエストのハード上限がmax_tokensという三層構造です。

運用上の注意を4つ挙げます。

予算は助言（advisory）であり強制ではない

中断のほうが破壊的な作業の途中では超過することもあります。ハードキャップは従来どおりmax_tokensで掛けます。

最小値は20,000トークン

それ未満は400エラーになります。

小さすぎる予算は「拒否のような挙動」を引き起こす

数時間級のタスクに2万トークンの予算を渡すと、モデルはタスク自体を辞退したり、過剰にスコープを削ったり、途中で切り上げたりします。

予算設定後に不可解な拒否や早期終了を見たら、他のパラメータを疑う前にまず予算を増やしてください。

カウントダウンはモデルにしか見えない

APIレスポンスに残予算フィールドはありません。

クライアント側でremainingを毎ターン減らして送るとキャッシュを壊すうえ、二重カウントで実際より速く予算が減って見え、早じまいの原因になります。

基本は初回にtotalだけ設定してサーバー任せにします。remainingを使うのは、コンパクション（文脈圧縮）で履歴を書き換えたときに消費済みトークンを引き継ぐ場面だけです。

予算の決め方は「勘で決めない」が公式の推奨です。

まずtask_budgetなしで代表的なタスクを走らせ、ループ全体のusage.output_tokensとツール結果トークンの分布を測り、p99あたりから始めて調整します。

なおTask budgetsはClaude Code / Coworkでは使えません。Messages APIを直接叩くエージェント基盤向けの機能です（Claude Codeのワークフロー機能には類似の予算機構が別途あります）。

10. Opus 5を最大限引き出すプロンプティング

Opus 5は4.8向けプロンプトでも素のままよく動きます。

ただ、公式プロンプティングガイドが「調整が要りやすい」と明言する挙動が5つあります。すべてモデルが勝手にやってくれる方向に変わった結果、旧来の指示が過剰になるパターンです。

(1) 応答・成果物が長くなった

会話応答も、ディスクに書くレポートやMarkdown文書も、4.8より長くなりがちです。

前述のとおりeffortを下げても短くならないので、プロンプトで明示します。

Keep responses focused, brief, and concise. Keep disclaimers and caveats short, and spend most of the response on the main answer. When asked to explain something, give a high-level summary unless an in-depth explanation is specifically requested.

長いシステムプロンプトでは、末尾近くに短いリマインダ（<tone_preference>Keep outputs reasonably concise.</tone_preference>のようなもの）を重ねるのが効くとされています。

文書の長さには「実質をカバーし、埋め草セクション・冗長な要約・ボイラープレートで水増ししない」という較正指示を入れます。

(2) 進捗ナレーションが増えた

エージェント作業中に「これから何をするか」を積極的に宣言し、メッセージあたりの出力も長めです。

頻度と形を明示的に指定するのが有効で、公式の例はこうです。

Before your first tool call, say in one sentence what you're about to do. While working, give a brief update only when you find something important or change direction. When you finish, lead with the outcome: your first sentence should answer "what happened" or "what did you find," with supporting detail after it for readers who want it.

逆にナレーションを増やしたい場合やスタイルを変えたい場合も、禁止形ではなく望む形の肯定例を示すほうが効きます。

(3) 自己検証・自己修正を勝手にやる

これがOpus 5最大の性格変化です。

「最後に検証ステップを入れよ」「ダブルチェックせよ」「サブエージェントで検証せよ」のような、モデルの自己検証と重複する再検証指示は削除が公式推奨です。

モデル自身の検証行動と重なって過剰検証になり、品質向上なしにコストだけ増えるからです。

ただし削除してよいのはこの種の重複指示だけです。

「変更後に指定のテストスイートを実行する」「lintと型検査を通す」といったプロジェクト固有の受入条件は、自己チェックの重複ではなく完了条件なので残します。

また、自分の前言の訂正を口に出しやすくなりました。ユーザー向け製品では「ユーザーのコード・結論・意思決定を変える誤りだけ簡潔に訂正し、影響のない言い間違いは黙って直せ」と絞る指示が紹介されています。

(4) タスクスコープを広げがち

頼んでいないステップを足したり、「本来こうあるべき」と判断してタスクを変形したりすることがあります。

狭いタスクではスコープを明示的に縛ります。

Deliver what was asked, at the scope intended. Make routine judgment calls yourself, and check in only when different readings of the request would lead to materially different work. If the request seems mistaken or a better approach exists, say so in a sentence and continue with the task as asked rather than quietly narrowing, widening, or transforming it.

(5) サブエージェントへの委任が増えた

マルチエージェント基盤では、4.8より積極的にサブエージェントを起動します。

真に独立した大きな作業では強みですが、小タスクではコストと時間を掛け算で増やします。委任条件の明示か、スポーン数の決定論的な上限を推奨します。

「数回のツール呼び出しで終わる仕事を委任するな」「自分の検証にサブエージェントを使うな」という例文が公式に載っています。

ちなみに4.8のプロンプティングガイドは真逆で、「サブエージェントを増やす」誘導例を載せていました。

世代ごとにデフォルト挙動が振り子のように動くので、ハーネス側の誘導プロンプトは毎世代見直しが必要です。

このほか2つ、特筆したい強化があります。

コードレビュー用途

Opus 5は「1パスあたり高い率で本物のバグを見つけ、追加の指摘もほとんどが誤検知でない」とされます。

しかも低effortでも精度が保たれるため、「レビュー時に速いパス、後でより徹底したパス」という2段構成が組めます。

4.8時代と同じく、「high-severityのみ報告せよ」という指示は文字どおりに守って報告を減らすので、発見段階では全部報告させ、フィルタは別パスで行うのが定石です。

ビジョン（画像理解）

チャート・文書・図の理解と、UIやフロントエンドの視覚的再現が向上しています。

旧モデル向けに入れた画像まわりのワークアラウンドは再検証をおすすめします。

画像を反復的に解析・クロップ・確認できるツールを与えるほうが、thinkingを盛るよりコスト効率が良いとされています。

第3部　Claude Codeで使うOpus 5

11. Claude CodeでOpus 5を使う前提

Claude Codeをまだ使ったことがない方はClaude Code入門（CLI版とWeb版）からどうぞ。

ここでは運用者向けの前提を押さえます。

バージョン

Opus 5にはClaude Code v2.1.219以降が必要です（Sonnet 5はv2.1.197以降、Opus 4.8はv2.1.154以降）。claude updateで更新してください。

エイリアス解決

opusエイリアスの解決先が4.8時代から大きく前進しました。

Anthropic APIだけでなく、Claude Platform on AWS・Amazon Bedrock・Google CloudのAgent PlatformでもopusはOpus 5に解決されます（4.8時代はプロバイダごとにバラバラでした）。

例外はMicrosoft Foundryで、opusはOpus 4.6のまま。Foundryでは完全なモデル名指定かANTHROPIC_DEFAULT_OPUS_MODELで対応します。

`best`エイリアス

組織がFable 5にアクセスできるならFable 5、できなければ最新Opusに解決するbestが使えます。fableエイリアスの直接指定も可能です。

default（モデル未指定時）の解決先は次のとおりです。

ProプランのデフォルトがSonnet 5になった点に注意してください。

Fable 5はどのアカウント種別でもデフォルトにはなりません（/model fable等での明示選択が必要です）。

バージョン固定したい場合は、エイリアスではなくフルモデル名（claude-opus-5）か環境変数（ANTHROPIC_DEFAULT_OPUS_MODEL）を使う、という定石は従来どおりです。

12. Claude Codeのeffort設定は引き継ぎ挙動に注意

Claude Codeでのeffort操作方法（/effort・--effort・CLAUDE_CODE_EFFORT_LEVEL・設定ファイルのeffortLevel・スキルやサブエージェントのフロントマター）は4.8時代と同じです。

Opus 5で特に注意したいのが、effort設定の引き継ぎ挙動です。

Fable 5・Opus 4.8・4.7では、そのモデルを初めて使うとき、以前別モデルで設定したレベルがあってもモデルデフォルトが強制適用される仕様でした（4.8ガイドで注意喚起した挙動です）。

Opus 5にはこのホールドがなく、以前設定したレベルがそのまま引き継がれます。

つまり4.8でxhighを常用していた人がOpus 5に切り替えると、気づかないままxhighで走り続けます。

第8章のとおりOpus 5ではhighから始めて必要に応じて調整するのが公式推奨なので、切り替え直後に/effortで現在値を確認し、意図的に選び直すことをおすすめします。

現在のeffortはセッションヘッダの「with xxx effort」表示でも確認できます。

そのほかは従来どおりです。

maxはセッション限定（設定ファイルには保存不可）、ultracodeは「xhighと動的ワークフローのオーケストレーション」というClaude Code側の設定でモデルのeffortレベルではないこと、一回だけ深く考えさせたいときはプロンプトにultrathinkと書くこと、などは4.8ガイドの第9章・第11章を参照してください。

動的ワークフロー（Dynamic Workflows）自体の仕組みも4.8ガイドで詳説したとおりで、Opus 5で仕組みの変更はありません。

13. Fast modeの変更点

/fastで切り替えるFast mode（同じモデル・同じ品質のまま最大2.5倍速）は、v2.1.219以降でOpus 5がデフォルト対象になりました。

価格はOpus 5・Opus 4.8とも入力$10・出力$50で、4.8時代に値下げされた水準が維持されています（1Mウィンドウ全域でフラット）。

注意点は4.8時代から引き継ぎつつ、ひとつ動きがありました。

• Opus 4.7のFast modeは2026年7月24日（Opus 5ローンチ当日）に削除。しかもClaude Codeは4.7をFast mode対象として扱い続けるため、4.7セッションでFast modeがONのままだとAPIがリクエストを拒否します（標準速度へのフォールバックではなくエラー）。4.7でFast modeを使っていた場合はOpus 5か4.8に切り替えてください
• サブスクリプションプラン（Pro/Max/Team/Enterprise）ではusage credits経由のみ。プランの通常利用枠には含まれず、最初のトークンからFast mode単価
• 会話の途中でONにすると、その時点の会話文脈全体に未キャッシュ入力単価が一度かかるため、使うならセッション開始時から
• Bedrock / Google Cloud / Foundry / Claude Platform on AWSでは利用不可。VS Code拡張も非対応（CLIのみ）

14. フラグされたらどうなるか、自動モデルフォールバックの仕組み

第7章で述べたAPI側のfallbacksとは別に、Claude Code側にもカテゴリベースの自動フォールバックが入りました（v2.1.219以降）。

Fable 5とOpus 5はサイバーセキュリティ・生物学の安全分類器つきで動いており、リクエストがフラグされたときの挙動はこうなります。

この表からも分かるとおり、Opus 4.8に該当分類器がないからこそ、4.8がフォールバック先になっています。

フォールバック後のセッションはそのモデルのまま続くので、戻りたければ/modelで戻します。

運用上知っておくべき挙動を3つ挙げます。

セッションの最初のリクエストでいきなり発火することがある

初回リクエストにはCLAUDE.mdやgit statusなどのワークスペース文脈が載ります。

セキュリティ・生物学系の内容を含むリポジトリでは、何も変なことを頼んでいなくても分類器が反応します。

切り分けにはclaude --safe-mode（CLAUDE.md・スキル・MCP・フックを無効化して起動）が使えます。

自動で切り替えたくない場合は設定で変えられる

/configで「switch models when a message is flagged」をオフにします。

フラグ時にセッションが一時停止し、「フォールバックモデルへ切り替え」か「プロンプトを編集して現行モデルで再試行」を選べます。

ペネトレーションテスト・CTF・生物学隣接コードベースでは頻繁な発火が「仕様どおり」

アカウントにフラグが付いたわけではありません。

Fable級の能力がこの領域で必要な組織向けには、Anthropicのtrusted access programs（CVP等）が案内されています。

なお、Claude Codeの拒否まわりでは過去に紛らわしい不具合もありました。「usage policy violation」表示の対処はこちらの記事にまとめてあります。

15. 1Mコンテキストとopusplan

1Mコンテキストの扱いは4.8時代の枠組みを引き継ぎつつ、Opus 5では「1Mがデフォルトかつ最大」なのでさらに単純になりました。

• Anthropic APIでは、Opus 5（および4.7以降のOpus・Sonnet 5・Fable 5）は常に1Mウィンドウで動作
• Max / Team / Enterpriseプランでは、Opusが追加設定なしで自動的に1Mへアップグレード（サブスクリプションに含まれ、200k超のプレミアム課金なし）
• 完全に無効化するならCLAUDE_CODE_DISABLE_1M_CONTEXT=1

opusplan（プランモードはopus、実行はsonnetエイリアスに自動切り替えするエイリアス）は、Anthropic APIでは計画をOpus 5、実行をSonnet 5が担う構成になりました。

実際の組み合わせは第11章で説明したプロバイダーごとのエイリアス解決に従います。Claude Platform on AWSではOpus 5とSonnet 4.6、BedrockとGoogle Cloud Agent PlatformではOpus 5とSonnet 4.5、FoundryではOpus 4.6とSonnet 4.5になる点に注意してください。

Sonnet 5は「最もエージェンティックなSonnet」としてOpus級に迫る実行能力を謳っており、しかも8月31日までは導入価格$2/$10です。

「設計はOpus 5にじっくり考えさせ、コード生成はSonnet 5に流す」構成はコスト面で魅力があります。

Anthropic APIで実行側がSonnet 5になる場合、Sonnet 5は常時1Mウィンドウで、デフォルトでは約967kトークンで自動コンパクションが入ります（Claude Codeのモデル設定ドキュメント記載。CLAUDE_CODE_AUTO_COMPACT_WINDOWで閾値を変更可能です）。

16. 日常運用のリズム

第10章のプロンプティング変化は、Claude Codeの日常運用にそのまま効いてきます。

運用の型として3点にまとめます。

(1) CLAUDE.mdの検証指示を仕分けする

プロジェクトのCLAUDE.mdやスキルの検証まわりの指示を、2種類に分けてください。

ひとつは必須の受入条件（指定テストスイートの実行・lint・型検査・Definition of Done）。もうひとつはモデルの自己確認に重なるだけの指示（「完了前にダブルチェック」「最後にもう一度検証」）です。

Opus 5で削除してよいのは後者だけです。前者はプロジェクトの完了条件なので残します。

Opus 5は言われなくても自分の変更を確認するため、後者を残すと過剰検証でトークンを浪費します。

逆に、検証してほしくない場面（ドラフト段階の高速イテレーションなど）でこそ明示が必要になる、という逆転も起きています。

(2) 初回プロンプトへの情報集約は引き続き最重要

「完全なタスク仕様を最初に渡して、あとは走らせておくのが最良」という特性は4.8からさらに強化されています。

意図・完了条件・触ってよい範囲・制約を最初に書き切る運用は変わらず有効です。

一方、途中経過の報告は増える方向に変わったので、静かに走らせたければ第10章のナレーション抑制プロンプトをCLAUDE.mdに入れます。

(3) モデルの使い分けを再設計する

Opus 5の登場で、Claude Code内の現実的な使い分けはこうなりました。

「とりあえず全部Fable 5」はコスト的にも（Fable 5のコストと展望）、分類器の介入頻度的にも割に合わない場面が増えました。

Fable 5は最難関のタスクに絞り、日常の上限をOpus 5に置くのが、現時点のバランスだと考えています。

まだわかっていないこと・未確認事項

誠実性のため、現時点で確認できていないことを明示しておきます。

• Frontier-Benchのeffortレベル別チャートの各点（xhigh時は約44%とする読み取りが報道にあります）は画像形式でのみ示されており、テキスト形式では確認できていません。本稿の43.3%はSystem Cardの評価サマリー表に記載された値を採用しています
• 独立評価はまだ出揃っていません。Arena系ブラインド投票やArtificial Analysis等でのOpus 5の位置は、本稿執筆時点（リリース3日後）では確認できませんでした。8月のLLMランキングシリーズで答え合わせをする予定です
• Priority TierとWeb FetchのOpus 5対応時期はアナウンスされていません
• Fast mode・Task budgets・mid-conversation tool changes・fallbacksはいずれもbeta/リサーチプレビューであり、仕様・価格が変わる可能性があります

まとめ

一言でまとめると「Opus 5は最上位モデルではないのに、実務の本命になった」。これが今回のリリースの本質です。

実務で押さえるべき要点は次の5つに集約されます。

1. 移行は「ID差し替えだけ」ではない

thinkingがデフォルトONになり、thinking無効化はeffort high以下限定になりました（400エラー）。Web FetchとPriority Tierの非対応も含め、max_tokensと該当リクエストの監査が必要です。

2. effortは持ち越さず測り直す

デフォルトは変わらずhigh。公式の推奨スタート地点が「コーディングはxhigh」から「highで開始、要求の厳しい作業のみxhigh」に変わり、low/mediumの実用域が広がりました。Claude CodeではOpus 5だけ旧effort設定が引き継がれる点にも注意です。

3. 重複する再検証指示を消す

Opus 5は勝手に自己検証します。「ダブルチェックせよ」系の指示は過剰検証によるトークン浪費の原因になります。ただし必須テスト・lint等の受入条件は残します。

4. 安全分類器の搭載を理解して選ぶ

Opus 5には4.8にないモデル固有分類器（サイバー・生物学）が搭載されました。4.8からの移行では制約の追加であり、セキュリティ系ワークロードは4.8継続も選択肢です。Fable 5と比べれば介入は85%少なく、30日保持要件もなく、フォールバックもあるため、Fable 5からの乗り換え先としては扱いやすいモデルです。

5. 使い分けの再設計

日常はSonnet 5、主力はOpus 5（Maxのデフォルト）、最難関はFable 5。ナレッジカットオフ最新（2026年5月）はOpus 5だけの隠れた強みです。

Fable 5の停止事件からわずか6週間でこの布陣を整えてきたAnthropicの速度には驚かされます。

独立評価が出揃ったら、恒例のランキング記事で改めて検証します。

それでは、また次回、お会いしましょう！

出典

本記事の情報は2026年7月27日時点の公式ドキュメント・公式発表・報道に基づきます。

beta機能・リサーチプレビューの仕様は変更される可能性があるため、最新情報は各出典をご確認ください。

こんにちは！

新しい GPU を手に入れてワクワクしながら既存の推論環境を載せ替えたら、

昨日まで普通に動いていたものが軒並みエラーで止まった

そんな経験はないでしょうか。NVIDIA RTX 50 系、NVIDIA RTX PRO 系（Blackwell 世代）への移行では、これがかなりの高確率で起きます。

そして厄介なことに、エラーで止まってくれるのは、まだ親切なほうで、、TensorRT の世界には

「ビルドは通る、実行も通る、速度もちゃんと出る、けれど出力だけが静かに壊れている」

という、いちばん見つけにくい失敗の仕方が存在します。

本記事はその全体像を扱うシリーズの前編です。

対象環境
OS: Ubuntu 24.04 (WLS)
GPU: NVIDIA RTX PRO 4000 Blackwell・GeForce RTX 5060 Ti
（ともに Compute Capability 12.0 = sm_120）
Stack: PyTorch 2.11.0 + cu128 ／ TensorRT 10.16.1.11。

前編では次の 3 つをお届けします。

1. そもそも TensorRT 化とは何なのか
   なぜ PyTorch のまま動かすより速くなるのか。そして何を代償に払うのか
   
2. Blackwell（RTX 50系、RTX PRO 系）で既存資産が動かなくなる理由
   確認すべき領域は 1 つではなく、大きく 3 つあります
   
3. 最小構成で TensorRT 10 化を通す手順
   環境構築からエンジンビルド、数値照合、速度計測まで、本文のコードを順番に実行すれば再現できる形で

題材には、特定の製品に依存せず同じ検証手順を追えるよう、この記事の中に全コードを載せた小さなダミーモデルを使います。

特定の製品やモデルの話ではなく、TensorRT 化そのものの話として読んでいただけます。

本稿に掲載している数値・エラーログ・挙動は、実際に走らせた結果です。なおコードは TensorRT 10.x の API を対象としています。
TensorRT 11 では precision flag（`BuilderFlag.FP16` 等）を含む一部 API が変更・削除されているため、そのままでは動きません。
既存資産の移行過程を再現するため、意図的に 10.16 を使っています。

なお、お手元の GPU がどの世代（SM いくつ）なのかは、当社が公開している「2026年 NVIDIA GPU 一発検索ツール」で調べられます。本記事の話が自分の環境に当てはまるかどうかは、まずそこからご確認ください。

第1部: TensorRT 化とは何か ～ なぜ PyTorch より速いのか

一言でいうと「事前コンパイル」

PyTorch を普通に（torch.compile や CUDA Graphs を使わない eager 実行で）推論するとき、GPU の中で何が起きているかを思い出してみます。

演算子が呼ばれるたびにディスパッチが走り、演算ごとに GPU カーネルが起動されます。融合されていない演算のあいだでは、中間結果が GPU のメモリ（VRAM)へ書き出され、次の演算がまたそれを読み直します。

TensorRT 化とは、この実行の仕方を根本から変えることです。

モデルの計算グラフ全体を、あらかじめ「その GPU 専用の実行計画」へコンパイルしておき、推論時はホスト側からその実行計画を 1 回の呼び出しで投入するだけにします。

この事前コンパイル済みの成果物を、TensorRT ではエンジン（engine / plan）と呼びます。

なお本記事の比較対象はあくまで PyTorch の eager 実行です。PyTorch 自身にも torch.compile や CUDA Graphs といった高速化経路があり、それらを使った場合の差はまた別の話になります。

ソースコードをインタプリタで 1 行ずつ解釈しながら実行するのと、事前にネイティブバイナリへコンパイルしておいて実行するのと、その違いに近いイメージです。

速くなる 5 つの仕組み

「なぜ速いのか」を分解すると、だいたい次の 5 つに整理できます。

【代償】 TensorRT 化で何を失うか

TensorRT の記事は「速くなりました！」で終わりがちですが、
実務では失うものを把握しておくほうが重要です。

1. ビルドに時間がかかる —
   実機でカーネルを実測して選ぶため、モデルによっては数分から数十分かかります
   
2. エンジンの移植性が低い —
   既定設定でビルドしたエンジンは、作成時の TensorRT バージョンと GPU への依存が強く、「開発機で作ったエンジンを本番機にコピーする」は原則できません。version compatibility や hardware compatibility といった互換モードで対象範囲を広げることもできますが、性能や使える機能に制約が生じます
   
3. 未対応の演算があると、そもそもビルドが落ちる
   本記事の第4部がまさにこれです
   
4. 数値が変わる。ときには静かに壊れる
   精度が落ちるだけでなく、演算の意味そのものがすり替わることすらあります（中編の主題です）
   
5. 固定形状が最も扱いやすい —
   可変形状も optimization profile で正式に扱えますが、対応範囲を広く取りすぎると形状ごとの最適な実装を選びにくくなったり、メモリが増えたりする場合があります
   
6. デバッグしづらい
   PyTorch のようにモデルの途中に print を挟んで中身を覗く、ということができません

「TensorRT 化すべきか」の判断基準

以上を踏まえると、判断はかなりはっきりします。

効きやすいケース

• CPU 実行のままの ONNX モデルがパイプラインに残っている
  （最優先。効果が桁で違います）
  
• 小さな演算が大量にあり、カーネル起動のオーバーヘッドがボトルネックになっているモデル
  
• 入力形状が固定で、同じモデルを大量に回し続ける推論サービス

効きにくい、あるいは慎重に判断すべきケース

• 計算そのものに時間の大半を使っているモジュール …主要演算の計算時間がすでに支配的で、、単純な ONNX → TensorRT 変換による 1 件あたりのレイテンシ改善は限定的でした
  （バッチを増やしても 1 件あたりの時間はほぼ不変。ただしこれはこのモジュールでの結果で、量子化や専用カーネルまで含めれば話は変わりますし、スループットはまた別の指標です）
  
• 形状の変動範囲が大きく、optimization profile の設計や複数エンジンの管理コストが効果に見合わない用途
  
• TensorRT 非対応の演算を含む
  （→ 第4部のハイブリッド構成で部分適用する）
  
• バッチ処理でよい用途
  ここは強調しておきたい点です。カーネル起動のオーバーヘッドがボトルネックなら、TensorRT 化しなくても PyTorch 側でバッチを組むだけで数倍取れることがあります。
  私たちのケースでは、あるモジュールをバッチで回したところ 1 フレームあたり 2 倍以上まで縮み、わざわざ TensorRT 化した構成より速いという結果になりました。「リアルタイムで 1 フレームずつ処理する」用途と「まとめて書き出す」用途では、最適解が変わります

つまり

TensorRT は万能の高速化ボタンではなく、
「どの段が・何に時間を食われているか」を実測してから当てる道具

です。ここを飛ばして全段 TensorRT 化に突っ込むと、ビルドの苦労に見合わない結果になります。

第2部: なぜ「昨日まで動いていた資産」が Blackwell で動かないのか

さて、ここからが Blackwell の話です。

RTX 50 系と、今回検証した RTX PRO Blackwell ワークステーション GPU は sm_120（Compute Capability 12.0） という新しい世代で、既存資産が動かなくなる原因はここに集約されます
（なお Blackwell ファミリー全体ではデータセンター向けに別の Compute Capability を持つ製品もあります。製品ごとの世代は冒頭で紹介した GPU 検索ツールで確認できます）。

私たちの検証環境では、次の 3 つの領域で問題が発生しました。

• TensorRT
  sm_120 に初対応したのは TensorRT 10.8.0 です（リリースノートに "supports NVIDIA Blackwell GPUs, such as the GeForce 50-series" と明記されています）。
  裏を返すと、
  既定設定でビルドされた TensorRT 8 系の `.engine` / `.plan` は互換性チェックを通らず、sm_120 では原則として再利用できません
  （TensorRT 8.6 以降で version compatibility と hardware compatibility を有効にして構築したエンジンは例外になり得ますが、互換設定が確認できない既存資産は再ビルド前提が安全です）
  
• PyTorch
  Blackwell ネイティブ対応の最初の安定版は 2.7.0（CUDA 12.8 wheel = cu128） です。それ以前の wheel を入れると sm_120 is not compatible with the current PyTorch installation. のように弾かれます
  
• onnxruntime: 私たちの検証環境（onnxruntime 1.27）では、CUDAExecutionProvider が初期化できず CPU 実行にフォールバックしました。
  エラーで止まらないので気づきにくく、「なんだか遅い」だけが症状として残ります。
  ただしこれは onnxruntime のバージョン・配布ビルド・CUDA の組み合わせに依存する話で、Blackwell で公式 wheel が一律に動かないという意味ではありません。お使いのバージョンで実際に確認してください
  

つまり Blackwell 移行とは、単に GPU を挿し替える話ではなく、

「PyTorch を cu128 世代へ」
「TensorRT を 10.x 世代へ」に加えて
「onnxruntime などの周辺ランタイムが実際にどのバックエンドで動いているかを見直す」
を同時に走らせる作業

です。

3 番目の onnxruntime については「CUDA で動かないなら CPU のままでいいか」と放置されがちですが、そこがパイプライン全体のボトルネックになっている可能性が高いので要注意です。
まずは providers を実際に出力して、CPU に落ちていないか確認してください。

import onnxruntime as ort
print(ort.__version__)
print(ort.get_available_providers())   # CUDAExecutionProvider が無ければ、この環境では CUDA EP を利用できない

sess = ort.InferenceSession("model.onnx",
                            providers=["CUDAExecutionProvider", "CPUExecutionProvider"])
print(sess.get_providers())            # セッションに登録された provider と優先順位

1 点だけ注意です。
sess.get_providers() で分かるのは「セッションにどの provider が登録されたか」までで、全ノードが GPU で実行された証明にはなりません
（一部のノードだけ CPU に割り当てられることがあります）。ノード単位の配置まで確認したい場合は、onnxruntime のプロファイリングや詳細ログを使ってください。

第3部: 最小構成で TensorRT 10 化を通す ～5 ステップ

ここからは実際に手を動かします。

いきなり本命のモデルを変換しないでください。

まずは数十行の最小モデルで「export → build → 実行 → 数値照合 → 速度計測」の 5 ステップを通し、環境そのものが健全であることを確認します。

この自己診断を挟んでおくと、後で本命モデルが失敗したときに「環境のせいか、モデルのせいか」を即座に切り分けられます。

環境構築 ～ ここに最初の罠があります

検証はすべて WSL2（Ubuntu 24.04）上で行いました。

WSL2 を選ぶのは、CUDA / TensorRT まわりの Linux 前提のツールチェーンがそのまま使えるためです。venv は uv で立て、システムの Python には触りません。

# 作業用 venv を uv で作成（システム Python 非侵襲）
uv venv ~/work/trt_venv --python 3.11
source ~/work/trt_venv/bin/activate

# PyTorch は cu128（CUDA 12.8）世代を明示（2026-07-23 時点では 2.11.0 が入ることを確認）
uv pip install torch --index-url https://download.pytorch.org/whl/cu128

# TensorRT は 10.x の cu12 ビルドにピンする（★理由は下記）
uv pip install "tensorrt-cu12==10.16.1.11"
# onnxscript は PyTorch の新しい exporter（dynamo=True）が必要とする
uv pip install onnx onnxscript numpy

罠その1: pip install tensorrt が CUDA 13 系を連れてくる

素の pip install tensorrt は、検証時点で TensorRT 11.1.0.106（CUDA 13 系ビルド） に解決されました。

一方、本記事の PyTorch 環境は cu128（CUDA 12.8）です。異なる CUDA メジャー系列のライブラリが同じ環境に存在すること自体が直ちに不正というわけではありませんが、依存関係や障害の切り分けが複雑になります。

そして何より、本記事のコードは TensorRT 11 の API では動きません。

そこで検証条件を揃えるため、torch の CUDA 系列に TensorRT の CUDA 系列を合わせて、TensorRT 10.16 の cu12 ビルドを明示的にピンします。

「最新版を入れれば良い」ではありません。

環境が整ったら、GPU が本当に sm_120 として認識されているかを先に確認しておきます。

import torch
print(torch.__version__, torch.version.cuda)   # 例: 2.11.0+cu128 / 12.8
print(torch.cuda.is_available())               # True であること
print(torch.cuda.get_device_capability())      # RTX 50 系・今回の検証 GPU なら (12, 0)

ステップ 1: 題材となるダミーモデルを用意する

小さな畳み込みブロックを用意します。特定の製品とは無関係の、ただの Conv + BatchNorm + ReLU の積み上げです。

# tiny_model.py
import torch
import torch.nn as nn

class TinyBlock(nn.Module):
    """TensorRT 化の動作確認用の最小モデル（Conv+BN+ReLU ×3）。
    レイヤ融合の効果が分かりやすいよう、あえて小さな演算を並べている。"""
    def __init__(self, ch=64):
        super().__init__()
        layers = []
        for _ in range(3):
            layers += [nn.Conv2d(ch, ch, 3, padding=1), nn.BatchNorm2d(ch), nn.ReLU(inplace=True)]
        self.body = nn.Sequential(*layers)

    def forward(self, x):
        return self.body(x)

INPUT_SHAPE = (1, 64, 256, 256)   # 固定形状で扱う

ステップ 2: ONNX へ export する

後のステップで「export したモデルそのもの」と数値を突き合わせるので、`model` と `x` はここで作ったものをこの後もずっと使い回します。

シードも固定しておくと、結果を再現できます。

torch.manual_seed(0)
model = TinyBlock().eval().cuda().float()
x = torch.randn(*INPUT_SHAPE, device="cuda")

torch.onnx.export(
    model, (x,), "tiny.onnx",
    input_names=["x"], output_names=["y"],
    opset_version=20,
    dynamo=True,          # PyTorch 2.x の新しい exporter（onnxscript が必要）
)

入力が複数あるモデルでは、ここに極めて見つけにくい事故の種があります。

torch.onnx.export に渡す args はタプルで、位置引数として順に束縛されます。

モデルの forward の引数順を勘違いしていると、ONNX の中で引数が入れ替わったまま、エラーも警告も出さずに export が成功します。

この事故と恒久的な回避策は中編で詳しく扱います。

ステップ 3: TensorRT エンジンをビルドする

import tensorrt as trt

TRT_LOGGER = trt.Logger(trt.Logger.WARNING)

def build_engine(onnx_path, engine_path, fp16=True, workspace_gb=4, tf32=True):
    builder = trt.Builder(TRT_LOGGER)
    # TensorRT 10 では explicit batch が既定。下記フラグは後方互換で残っているもの
    network = builder.create_network(1 << int(trt.NetworkDefinitionCreationFlag.EXPLICIT_BATCH))
    parser = trt.OnnxParser(network, TRT_LOGGER)

    # parse_from_file を使うと、大きなモデルの外部データ（.onnx.data）も
    # ONNX と同じディレクトリから自動で解決してくれる
    if not parser.parse_from_file(onnx_path):
        errs = [str(parser.get_error(i)) for i in range(parser.num_errors)]
        raise RuntimeError("ONNX parse failed:\n" + "\n".join(errs))

    config = builder.create_builder_config()
    config.set_memory_pool_limit(trt.MemoryPoolType.WORKSPACE, workspace_gb * (1 << 30))

    if fp16:
        # FP16 の実装候補（tactic）を選択肢に加える。全層が FP16 になる保証ではなく、
        # 層によっては FP32 が選ばれる。実際の実行精度はレイヤ情報のダンプで確認できる
        config.set_flag(trt.BuilderFlag.FP16)

    # ★ TensorRT は fp32 ビルドでも既定で TF32（仮数 10bit）を使う。
    #    忠実度を厳密に検証したいときは無効化する（詳細は中編）
    if not tf32:
        config.clear_flag(trt.BuilderFlag.TF32)

    plan = builder.build_serialized_network(network, config)
    if plan is None:
        raise RuntimeError("build_serialized_network returned None（エンジンのビルドに失敗）")
    with open(engine_path, "wb") as f:
        f.write(plan)
    return engine_path

build_engine("tiny.onnx", "tiny_fp16.plan", fp16=True)

コメントに書いたとおり、BuilderFlag.FP16 は「全部を fp16 にする」指定ではなく、「FP16 の実装候補を許可する」指定です。以降、本文で「fp16 でビルド」と書いたときは、この「FP16 tactic を許可してビルド」の意味だと読んでください。

ステップ 4: エンジンを実行する（PyTorch テンソルを直接渡す）

ここが実務上いちばん知りたいところだと思います。

device・dtype・形状・メモリ配置（contiguous）があらかじめエンジンの要求と一致していれば、PyTorch テンソルの GPU メモリアドレス（`data_ptr()`）を TensorRT にそのまま登録でき、境界での追加コピーを避けられます。

これができると、「モデルの一部だけ TensorRT 化して、残りは PyTorch のまま」というハイブリッド構成が現実的になります（第4部で使います）。

以下のサンプルは安全のため dtype と device を自動で合わせてから渡します
（条件が合わない場合はそこで変換コピーが発生します。なぜこの自動変換が要るのかは、すぐ後の罠で説明します）。

_TRT2TORCH = {
    trt.float32: torch.float32, trt.float16: torch.float16,
    trt.int32: torch.int32, trt.int64: torch.int64,
    trt.int8: torch.int8, trt.bool: torch.bool,
}

class TRTRunner:
    """エンジンをロードし、PyTorch テンソルを入出力に使って実行する（固定形状前提）"""

    def __init__(self, engine_path, device="cuda:0"):
        self.device = torch.device(device)
        # Runtime / engine / context はカレント CUDA デバイスに紐づくため、
        # 対象デバイスを明示して作成する（cuda:0 以外を使う場合に必須）
        with torch.cuda.device(self.device):
            self.runtime = trt.Runtime(TRT_LOGGER)
            with open(engine_path, "rb") as f:
                self.engine = self.runtime.deserialize_cuda_engine(f.read())
            if self.engine is None:
                raise RuntimeError(f"deserialize failed: {engine_path}")
            self.ctx = self.engine.create_execution_context()

        self.inputs, self.outputs = [], []
        for i in range(self.engine.num_io_tensors):
            name = self.engine.get_tensor_name(i)
            if self.engine.get_tensor_mode(name) == trt.TensorIOMode.INPUT:
                self.inputs.append(name)
            else:
                self.outputs.append(name)

    def prepare(self, feed: dict):
        """入力の形状とアドレスを設定し、出力バッファを確保する。
        入力バッファを使い回すなら 1 回で足りる（速度計測ではここを計測の外に出す）"""
        self._feed = {}
        for name, t in feed.items():
            # ★ FP16 tactic を許可してビルドしても、エンジンの入出力型は ONNX の定義のまま（多くは fp32）。
            #   half テンソルのアドレスをそのまま渡すと、fp16 のビット列が fp32 として
            #   読まれて出力が壊れる。しかも例外は出ない（詳細は下記）
            want = _TRT2TORCH[self.engine.get_tensor_dtype(name)]
            t = t.to(device=self.device, dtype=want).contiguous()
            # set_* 系も bool を返す。失敗の握りつぶしはこの記事のテーマ的に厳禁
            if not self.ctx.set_input_shape(name, tuple(t.shape)):
                raise RuntimeError(f"set_input_shape failed: {name}, shape={tuple(t.shape)}")
            if not self.ctx.set_tensor_address(name, t.data_ptr()):
                raise RuntimeError(f"set_tensor_address failed: {name}")
            self._feed[name] = t

        self._outs = {}
        for name in self.outputs:
            shape = tuple(self.ctx.get_tensor_shape(name))
            if any(d < 0 for d in shape):
                raise RuntimeError(f"output shape unresolved: {name} {shape}")
            dtype = _TRT2TORCH[self.engine.get_tensor_dtype(name)]
            o = torch.empty(shape, dtype=dtype, device=self.device).contiguous()
            self._outs[name] = o
            if not self.ctx.set_tensor_address(name, o.data_ptr()):
                raise RuntimeError(f"set_tensor_address failed: {name}")
        return self._outs

    def enqueue(self):
        """現在のストリームに実行を積む（非同期）。★ 戻り値を必ず確認すること"""
        ok = self.ctx.execute_async_v3(torch.cuda.current_stream(self.device).cuda_stream)
        if not ok:
            raise RuntimeError("TensorRT enqueue failed: エンジンと実行環境の不一致等の可能性。"
                               "出力は信頼できないため処理を停止する")

    def run(self, feed: dict):
        """検証用の簡便版（毎回 prepare + 同期する）。速度計測には使わない"""
        outs = self.prepare(feed)
        self.enqueue()
        torch.cuda.current_stream(self.device).synchronize()
        return outs

罠その2: FP16 tactic を許可してビルドしても、エンジンの入出力は fp32 のまま

これは今回の検証で実際に踏んだものです。

config.set_flag(trt.BuilderFlag.FP16) を有効にすると TensorRT は FP16 の実装候補を選択肢に加えますが（全層が fp16 になるわけではありません）、

ネットワークの入出力テンソルの型は ONNX の定義に従うため、この例では fp32 のままです。

ここに PyTorch の half テンソルのアドレスをそのまま渡すと、TensorRT はその領域を「fp32 要素が並ぶ入力バッファ」として扱います。fp16 は 1 要素 2 バイト・fp32 は 4 バイトなので、値の解釈が変わるだけでなく、TensorRT が PyTorch 側の確保範囲を超えて読み出す可能性もあります。

挙動は未定義で、出力の破損だけでなく、環境によっては CUDA エラーやクラッシュも起こり得ます
（set_tensor_address はポインタを登録するだけで、バッファのサイズまでは伝えないためです）。

実測すると、こうなりました。

• 正しく dtype を合わせた場合:
  最大絶対誤差 約 0.001
  （今回の FP16 tactic 許可設定では、大きな数値破綻は見られません）
  
• half のアドレスをそのまま渡した場合
  最大絶対誤差 約 13.8
  （出力の値域が 0.5 弱のモデルで、です。なおこの値は今回の環境で観測された一例で、再現可能な誤差量を意味しません）

そして最悪なのは、今回の実測ではこの状態でも `execute_async_v3` が `True`（成功）を返し、NaN も出ず、例外も飛ばなかったことです。上のコードで want = _TRT2TORCH[...] の 2 行を入れているのは、この沈黙劣化を防ぐためです。

罠その3: `execute_async_v3` の戻り値を捨ててはいけない

このメソッドは失敗しても例外を投げず、`False` を返すだけです。

放置すると、更新されなかった出力バッファ（＝ゴミ、あるいは直前のフレームの値）がそのまま下流へ流れていきます。

処理は「成功」に見えたまま、出力だけが壊れるという最悪の形になります。上のコードのように False を即例外にしておくことを強くおすすめします。

ステップ 5: 数値を突き合わせてから、速度を測る

速度を測る前に、まず数値が合っているかを確認します。
順序を逆にしてはいけません。

照合の基準は、ステップ 2 で export に使った fp32 の `model` と `x` そのものです。ここで新しくモデルを作り直してはいけませんし
（ランダム初期化された「別の重み」と比較することになります）、fp16 化した別のモデルを基準にしてもいけません（「export とエンジンが正しいか」の検証になりません）。

# model / x はステップ 2 で export に使った fp32 のものをそのまま使う
with torch.inference_mode():
    torch_ref = model(x)

runner = TRTRunner("tiny_fp16.plan")
trt_out = runner.run({"x": x})["y"]

diff = trt_out.float() - torch_ref.float()
print("max_abs :", diff.abs().max().item())
print("nRMSE   :", (diff.norm() / torch_ref.norm()).item())

出力の値域そのものを併記しないと、最大絶対誤差の大小は判定できません。学習済みでないダミーモデルは値域が実モデルと違うので、正規化した相対誤差（nRMSE）を併せて見るのが安全です。

今回の TinyBlock では max_abs 約 0.001・nRMSE 約 0.0016 で、FP16 tactic を許可したエンジンの、今回の設定における誤差として小さい水準でした。

計測は 専用の CUDA ストリーム + CUDA Event で行います。time.time() では GPU の非同期実行を正しく測れません。

import numpy as np

def bench_callable(fn, n_warmup=30, n_iter=200, device="cuda:0"):
    """fn() を計測して mean/median/min/max（ミリ秒）を返す。
    専用ストリームを使うことで、PyTorch と TensorRT を同じ条件で公平に比較できる"""
    dev = torch.device(device)
    # これ以前に別ストリームへ積まれた処理（モデル変換・prepare 等）を完了させる。
    # ストリーム間は明示的に同期しない限り実行順序が保証されない
    torch.cuda.synchronize(dev)
    stream = torch.cuda.Stream(dev)
    with torch.cuda.stream(stream):
        for _ in range(n_warmup):      # ウォームアップは必須（初回は遅い）
            fn()
        stream.synchronize()

        times = []
        for _ in range(n_iter):
            s = torch.cuda.Event(enable_timing=True)
            e = torch.cuda.Event(enable_timing=True)
            s.record(stream)
            fn()
            e.record(stream)
            stream.synchronize()
            times.append(s.elapsed_time(e))

    t = np.array(times)
    return {"mean": float(t.mean()), "median": float(np.median(t)),
            "min": float(t.min()), "max": float(t.max())}

速度計測では、PyTorch 側の実運用候補として fp16 化したモデルを使います。照合に使った fp32 の model はそのまま残したいので、コピーしてから fp16 化します。ポイントは、TensorRT 側は `prepare()`（バッファ確保・アドレス登録）を計測の外で 1 回だけ行い、計測中は `enqueue()` だけを呼ぶことです。

毎回 run() を呼ぶと、dtype 変換・出力確保・同期まで TensorRT の時間に含まれてしまい、公平な比較になりません。

import copy

# 速度計測用の fp16 モデルは、export に使った fp32 model を保つため deepcopy で別に作る
model_half = copy.deepcopy(model).half()
x_half = x.half()

# PyTorch 側（eager + inference_mode・fp16）
def torch_fn():
    with torch.inference_mode():
        model_half(x_half)

# TensorRT 側: prepare は計測の外で 1 回だけ。計測中は enqueue のみ
runner.prepare({"x": x})
def trt_fn():
    runner.enqueue()

print("torch:", bench_callable(torch_fn))
print("trt  :", bench_callable(trt_fn))

結果はこうなりました。

計測条件: GeForce RTX 5060 Ti ／ batch=1 ／ PyTorch 2.11 eager + inference_mode・fp16 モデル ／ TensorRT 10.16・fp32 入出力・FP16 tactic 有効。TensorRT は入出力バッファを事前確保し enqueue 部分のみを計測。各 200 回・ウォームアップ 30 回の median。

Conv + BatchNorm + ReLU を 3 段重ねただけの小さなモデルで、GPU 実行区間では約 2.5 倍の差が出ました。

ただしこの数字の読み方には注意が要ります。

これは「PyTorch の全面 fp16 eager」と「fp32 入出力 + FP16 tactic を許可した TensorRT エンジン」を、事前の dtype 変換とバッファ準備を除いた GPU 実行区間で比べた結果です。

同一精度条件どうしの比較でも、パイプライン全体のエンドツーエンド高速化率でもありません。

それでも、同じモデル構造をそれぞれの実運用候補となる設定で実行したときにこれだけ差が出る、というのは第1部で挙げたレイヤ融合・カーネル選択・実行時オーバーヘッド削減などの効果と整合的な結果です。

比較は median で見ます。

平均はときどき混ざる外れ値に引きずられます。

また、計測中はその GPU を単独で占有してください。他の推論プロセスやデスクトップ描画が同じ GPU に乗っていると、数値は簡単に数十パーセント変動し、比較の意味がなくなります。

第4部: 最初の壁 ～ grid_sample の次元でビルドが落ちる

本命のモデルを変換し始めると、多くの方が最初にぶつかるのがこれです。モデルの中に 5 次元（volumetric）の `grid_sample` が入っていると、TensorRT のビルドが通りません。

3D ボリュームを変形させる処理は、医用画像のレジストレーション、NeRF 系、3D 特徴のワーピングなど、いろいろな領域で使われています。再現用の最小モジュールは次のとおりです。

import torch.nn.functional as F

class VolumetricWarp(nn.Module):
    """5D（volumetric）grid_sample を含む最小モジュール。
    input: [N, C, D, H, W] / grid: [N, D, H, W, 3]"""
    def forward(self, vol, grid):
        return F.grid_sample(vol, grid, align_corners=False)

VOL_SHAPE  = (1, 32, 16, 64, 64)
GRID_SHAPE = (1, 16, 64, 64, 3)

export とビルドは、ステップ 2〜3 と同じ道具立てでそのまま試せます。

warp_model = VolumetricWarp().eval().cuda()
vol = torch.randn(*VOL_SHAPE, device="cuda")
grid = torch.rand(*GRID_SHAPE, device="cuda") * 2 - 1

torch.onnx.export(
    warp_model, (vol, grid), "volumetric_warp.onnx",
    input_names=["vol", "grid"], output_names=["y"],
    opset_version=20, dynamo=True,
)

# ONNX export は成功する。落ちるのは次の build のほう
build_engine("volumetric_warp.onnx", "volumetric_warp.plan", fp16=False)

実行すると、次のエラーで落ちます（実機のログそのままです）。

[TRT] [E] INetworkDefinition::addGridSample: Error Code 3: API Usage Error
    (Parameter check failed, condition: input.getDimensions().nbDims == 4.
     In addGridSample at /_src/optimizer/api/network.cpp:1803)
[TRT] [E] ModelImporter.cpp:138: While parsing node number 0 [GridSample -> "y"]:
[TRT] [E] ModelImporter.cpp:149: ERROR: ModelImporter.cpp:490 In function parseNode:
[6] Invalid Node - node_GridSample_0

input.getDimensions().nbDims == 4

つまり TensorRT 10.16 のネイティブ `GridSample` は 4 次元入力しか受け付けません。

5D の呼び出しは、パーサがノードを追加する時点で拒否されます。

これは一次情報とも一致します。onnx-tensorrt の operators ドキュメントは GridSample について "Input must be 4D input." と明記しており、5D 対応の要望は NVIDIA/TensorRT の issue #3890 として存在しますが、open / triaged のままネイティブ対応は提供されていません。

「ONNX の opset を上げれば通る」は誤りです

ここは混乱しやすいところなので明確にしておきます。

ONNX の標準仕様では opset 16 で 4D、opset 20 で 5D（volumetric）の grid_sample が定義されています。

ですから PyTorch からの export は opset 20 で問題なく成功し、ONNX ファイルの中に 5D の GridSample ノードがちゃんと生成されます。実際、上のエラーログは「export は成功したあと、ビルドの段階で落ちている」ことを示しています。

落ちているのは export ではなく、TensorRT 側の build です。ONNX に書けることと、TensorRT が食えることは別問題です。

現実解 — 通らないモジュールだけ PyTorch に残す

回避策のひとつは、TensorRT が持っていない演算を自分で CUDA カーネルとして書き、プラグインとして登録することです。5D grid_sample には既存の OSS 実装（grid-sample3d-trt-plugin など）があり、これを新しい CUDA / TensorRT 世代向けにビルドし直すアプローチが取れます。

ただしこれはエキスパート作業なので、本シリーズの後編で扱います。

プラグインを書き上げるまで移行が 1 ミリも進まない、というのは現実的ではありません。そこで有効なのがハイブリッド構成です。考え方はいたってシンプルで、TensorRT で通るモジュールだけ TensorRT にし、通らないモジュールは PyTorch のまま残すというものです。

# 構成イメージ（head_fp16.plan は「後段を TensorRT 化したエンジン」の意味の仮の名前です）
warp = VolumetricWarp().eval().cuda()      # 5D grid_sample → PyTorch のまま
head = TRTRunner("head_fp16.plan")         # 後段 → TensorRT エンジン

def forward(vol, grid):
    with torch.no_grad():
        feat = warp(vol, grid)             # PyTorch が GPU 上に出力を作り
    return head.run({"x": feat})["y"]      # そのアドレスをそのまま TensorRT へ渡す

ステップ 4 で見たとおり、dtype・device・形状が一致していれば、PyTorch テンソルと TensorRT は同じデバイス・同じストリーム上でアドレスを渡し合えるので、両者の橋渡しに追加のコピーを発生させずに済みます。

私たちのケースでは、プラグインを一切書かずにこの構成だけで 2 倍近く改善し、TensorRT にクリーンに載るモジュールを順に置き換えていくと、プラグイン不要の範囲だけでパイプライン全体が 2 倍程度に到達しました。

「まず低リスクな範囲で確実に速くする。カスタムプラグインは別プロジェクトとして切り出す」

これが移行の現実的な進め方だと考えています。

まだ確かめていないこと

誠実に書いておきます。本記事の検証は「TensorRT 10.16・PyTorch 2.11 + cu128」という単一のソフトウェア構成で行ったものです。次の点は本記事では確認していません。

• 他の TensorRT バージョンでの再現性
  特に 4D grid_sample の挙動（中編で扱います）は、将来のバージョンで修正される可能性があります。また TensorRT 11 系は API が変わっており（strong typing 化）、本記事のコードはそのままでは動きません
  
• torch.compile や CUDA Graphs を使った PyTorch との比較
  本記事の比較対象は eager 実行のみです
  
• int8 量子化との組み合わせ
  本記事は fp16 / fp32 のみを扱っています
  
• 可変形状（dynamic shape）でのビルド
  本記事はすべて固定形状です。
  optimization profile を使う場合の速度・精度は別途検証が必要です
  
• 5D grid_sample プラグインを Blackwell 向けにビルドした場合の数値と速度
  後編で扱う予定です

まとめ

一言でまとめると、

「Blackwell 移行は GPU の差し替えではなく、PyTorch と TensorRT の対応状況の更新に加えて、周辺ランタイムが実際にどの実行バックエンドで動いているかを再確認する作業であり、TensorRT 化はそこに乗せる別の投資判断である」

ということです
（まったく一言にならなかったですが（笑）　
ちなみに、私たちの環境では onnxruntime の CPU フォールバックも発生しました）

さて、ここでまとめとして大事なポイントを再掲いたしますね。

1. GPU の Compute Capability を最初に確認する
   （RTX 50 系は sm_120。Blackwell の他製品群は別の値を持つので製品ごとに確認する）
   
2. PyTorch は cu128 世代
   （安定版は 2.7.0 以降）
   
3. TensorRT は 10.8 以降を使う。
   既存の TensorRT 8 エンジンは互換設定と対象 GPU を確認のうえ、原則として再ビルドする
   
4. TensorRT の CUDA 系列を torch に合わせる（cu12 にピン）
   
5. onnxruntime が CPU に落ちていないか、バージョンと providers を実際に出力して確認する。落ちていれば最優先の TensorRT 化候補
   
6. 最小モデルで自己診断してから本命へ進む
   
7. エンジンの入出力 dtype に合わせてテンソルを渡す
   （FP16 tactic を許可したビルドでも入出力は fp32 のことが多い）
   
8. execute_async_v3 や set_input_shape / set_tensor_address の戻り値を必ず確認する
   （失敗しても例外は飛ばない）
   
9. 数値照合は速度計測より先に、export に使ったモデルと同じ重み・同じ入力で行う
   
10. モデル内の grid_sample の次元を確認する
    （5D はネイティブでは通らない。opset を上げても解決しない）
    
11. 通らないモジュールは切り出してハイブリッド化する
    
12. 計測は GPU を単独占有して CUDA Event の median で見る。エンジン単体の比較ではバッファ準備を分離して enqueue 区間を測り、実運用の判断では dtype 変換・モジュール境界・同期を含むエンドツーエンド時間も別途はかる

次回予告（中編）～ ビルドが通っても、正しいとは限らない

次回は後編ではなく中編です。

今回の前編で扱ったのは、エラーで止まってくれる種類の問題でした。

移行作業で本当に怖いのはその先です。

私たちが実際に踏んだ「沈黙劣化」を扱います。

• ビルドも実行も成功していて、出力の形も値も「それらしい」。しかし演算の意味が別物にすり替わっているケース
  （これは今回、公開できるダミーモデルで完全に再現できました）
  
• ビルド成功・速度も良好、なのに実データを入れた瞬間に出力が壊れるモジュール
• 開発機で完璧に動いたエンジンが、同じ世代の別の GPU では静かにゴミを出す現象
• fp32 でビルドしたのに、実は fp32 ではなかったという話
• そして私たちが最も泣いたexport 時の引数取り違え事故

どれも「速くなったので OK」と報告した後に発覚すると非常に厄介なものばかりですので、お楽しみに～

それでは、また次回お会いしましょう！

参考資料（一次情報・主要ソース）

• NVIDIA TensorRT ドキュメント（Release Notes 10.8.0 — Blackwell 対応の記載）
• NVIDIA 公式フォーラム: Software Migration Guide for NVIDIA Blackwell RTX GPUs（CUDA 12.8 / PyTorch / TensorRT）
• PyTorch issue #159207: sm_120 is not compatible with the current PyTorch installation
• onnxruntime issue #27875: Blackwell 環境での CUDAExecutionProvider 初期化に関する報告
• NVIDIA/TensorRT issue #3890: 5D GridSample のネイティブ対応要望
• SeanWangJS/grid-sample3d-trt-plugin（5D grid_sample のカスタムプラグイン実装）
• ONNX Operators: GridSample（opset 16 / 20 の仕様）
• 当社関連記事: 2026年 NVIDIA GPU 一発検索ツール