ComfyUIの「V3 Schema」とは？＠カスタムノード作成者に影響がある内容でした
ComfyUIのGithubページのPRを見ると、最近「V3 Schema」にコンバートしたというものが多く見られます。
なんとなく、今後「V3 Schema」が採用されていく流れになりそうだなと見ていると感じてしまいます。
しかし、「V3 Schema」になると何が変わるのでしょうか？
ということで、「V3 Schema」について調べて自分なりに内容をまとめてみました。
ちなみに、PRのところで「V3 Schema」と調べると最初の方に以下のような内容があり、これが最初のものの様です。
なお、2025/9/28での「V3 Schema」の状態についてですが、ComfyUIの一部のスクリプトはすでに移行が始まっています。
さて「V3 Schema」については、ComfyUIのblogでも記事がありました。
これは6月8日に出ていたので、すでに3か月以上も前に告知されていました。。。。。
ちゃんと読んでなかったということになります。
この「V3 Schema」の変更がどのような影響があるかユーザー視点と開発者視点で少し変わりそうかなという印象です。
ユーザー視点からは、「V3 Schema」に対応したカスタムノードは非常にありがたいものになりそうです。
具体的には依存関係の問題が劇的に少なくなるという点です。
これはカスタムノード側で適切に対応した設定にしている必要があります。
また、「V3 Schema」を採用した場合はComfyUIのアップデートの影響が受けにくくカスタムノードが使えなくなるリスクが無くなるので安心して使えます。
開発者側は、「V3 Schema」にする場合に、かなりの程度スクリプトを変更する必要がありそうです。
Geminiにまとめてもらった内容は以下
V3スキーマへの変換ロジックの要点
変換の核となるルールは以下の通りです。
クラスの継承:
変換対象のノードクラスは、comfy_api.latest.io.ComfyNode を継承します。
class MyNode: → class MyNode(io.ComfyNode):
INPUT_TYPES から define_schema へ:
クラスメソッド INPUT_TYPES は完全に削除されます。
代わりに、@classmethod def define_schema(cls): という新しいメソッドを定義します。
このメソッドは io.Schema(...) オブジェクトを返します。
Schema オブジェクトの構成:
node_id: ノードの内部的なクラス名 ("HyperTile") を指定します。
category: 従来の CATEGORY 文字列 ("model_patches/unet") を指定します。
inputs: INPUT_TYPES の "required" や "optional" で定義されていた各入力を、io モジュールの型クラス（io.Int.Input, io.Model.Input など）のリストとして定義します。
例: ("tile_size", ("INT", {"default": 256})) → io.Int.Input("tile_size", default=256)
outputs: 従来の RETURN_TYPES を、io モジュールの型クラス（io.Model.Output など）のリストとして定義します。
実行メソッドの更新:
FUNCTION で指定されていたメソッド（例: patch）に @override デコレータを追加します。
メソッドの引数に、Schemaで定義した入力に対応する型ヒントを追加します (model: io.Model, tile_size: io.Int, ...)。
メソッドの戻り値に、Schemaで定義した出力に対応する型ヒントを追加します (-> tuple[io.Model]:)。
ノードの登録方法の変更:
従来の NODE_CLASS_MAPPINGS による登録は廃止されます。
代わりに、ComfyExtension を継承したクラスを作成し、get_node_list メソッドでノードクラスのリストを返します。
async def comfy_entrypoint() 関数を定義し、この拡張クラスのインスタンスを返すことで、ComfyUIにノードを登録します。
以下の「comfy_api/latest/init.py」、「comfy_api/latest/_io.py」が、そのメインとなるスクリプトの様です。
変更されているスクリプトを見ると、この２つをインポートしています。
例えば、上の「Hypertile」のスクリプト変更についてみていきます。
①インポートの追加
先程あった、スクリプトが追加でインポートされています。
②クラス名の変更と、INPUTとかの部分は全面的に改訂
③クラスマッピングは削除されて別な登録方法となる
このスクリプト自体は98行のものですが、以下のように39行が追加、22行が削除された更新となりました。
この「V3 Schema」への変更自体は、2025/6ぐらいから始まった最近の動きなので、私のようなGeminiとかGPTを使用してカスタムノードを作成していた人間からするとダメージが大きいものになりそうです。
現時点では、Geminiとかにカスタムノードの作成を依頼するとV1スキーマでのスクリプト提案になってしまうからです。
そのため、V3スキーマにする際は、適切な指示が必要になるということになります。
軽く取り掛かった記事でしたが、自分がこの変更の大きさを理解するまでにかなり時間がかかってしまいました。
自作のカスタムノードをいじりつつ、この「V3 Schema」に取り掛かってみたいとは思っています。