V3 移行ガイド

概要

ComfyUI V3 スキーマは、ノードを定義するためのより整理された方法を導入しており、今後のノード機能の拡張は V3 スキーマでのみ追加されます。このガイドを使用して、既存の V1 ノードを新しい V3 スキーマに移行できます。

核心概念

V3 スキーマは新しいバージョン管理された Comfy API 上に維持されており、将来のスキーマの改訂は下位互換性があります。comfy_api.latest は開発中の最新番号付き API を指し、latest の前のバージョンが「安定版」と見なせます。バージョン v0_0_2 は現在（かつ最初）の API バージョンであるため、警告なしに変更が行われる可能性があります。安定版と見なされると、latest が指すために新しいバージョン v0_0_3 が作成されます。

# 最新の ComfyUI API を使用
from comfy_api.latest import ComfyExtension, io, ui

# 特定のバージョンの ComfyUI API を使用
from comfy_api.v0_0_2 import ComfyExtension, io, ui

V1 対 V3 アーキテクチャ

V3 スキーマの主な変更点は以下の通りです：

入力と出力が辞書ではなくオブジェクトで定義される。
実行メソッドは ‘execute’ という名前に固定され、クラスメソッドである。
def comfy_entrypoint() 関数が ComfyExtension オブジェクトを返し、NODE_CLASS_MAPPINGS/NODE_DISPLAY_NAME_MAPPINGS の代わりに公開ノードを定義する。
ノードオブジェクトは ‘state’ を公開しない - def __init__(self) はノードの関数で公開される内容に影響を与えない（すべてクラスメソッドであるため）。ノードクラスは実行前にもサニタイズされる。

V1 (レガシー)

class MyNode:
    @classmethod
    def INPUT_TYPES(s):
        return {"required": {...}}

    RETURN_TYPES = ("IMAGE",)
    FUNCTION = "execute"
    CATEGORY = "my_category"

    def execute(self, ...):
        return (result,)

NODE_CLASS_MAPPINGS = {"MyNode": MyNode}

V3 (モダン)

from comfy_api.latest import ComfyExtension, io

class MyNode(io.ComfyNode):
    @classmethod
    def define_schema(cls) -> io.Schema:
        return io.Schema(
            node_id="MyNode",
            display_name="My Node",
            category="my_category",
            inputs=[...],
            outputs=[...]
        )

    @classmethod
    def execute(cls, ...) -> io.NodeOutput:
        return io.NodeOutput(result)

class MyExtension(ComfyExtension):
    async def get_node_list(self) -> list[type[io.ComfyNode]]:
        return [MyNode]

async def comfy_entrypoint() -> ComfyExtension:
    return MyExtension()

移行ステップ

V1 から V3 への移行は、ほとんどの場合単純で、構文の変更のみです。

ステップ 1: ベースクラスの変更

すべての V3 スキーマノードは ComfyNode から継承する必要があります。継承チェーンのトップに ComfyNode 親があれば、複数の継承層でも問題ありません。 V1:

class Example:
    def __init__(self):
        pass

V3:

from comfy_api.latest import io

class Example(io.ComfyNode):
    # __init__ は不要

ステップ 2: INPUT_TYPES を define_schema に変換

ノード ID、表示名、カテゴリなどのノードプロパティは、以前は辞書やクラスプロパティなどコードの異なる場所に割り当てられていましたが、現在は Schema クラスを介して一緒に管理されます。 define_schema(cls) 関数は、V1 の INPUT_TYPES(s) とほぼ同じ方法で Schema オブジェクトを返すことが期待されます。サポートされているコア入力/出力型は comfy_api/{version} の _io.py に保存および文書化されており、デフォルトで io として名前空間化されています。入力/出力は辞書や文字列ではなくクラスで定義されるようになったため、カスタム型は独自のクラスを定義するか、io のヘルパー関数 Custom を使用することでサポートされます。カスタム型については、以下のセクションで詳しく説明します。型クラスには以下のプロパティがあります：

入力用の class Input（例：Model.Input(...)）
出力用の class Output（例：Model.Output(...)）。すべての型が出力としてサポートされているわけではないことに注意。
型の型ヒントを取得するための Type（例：Model.Type）。一部の型ヒントは単に any であり、将来更新される可能性があることに注意。これらの型ヒントは強制されず、有用なドキュメントとして機能するのみ。

V1:

@classmethod
def INPUT_TYPES(s):
    return {
        "required": {
            "image": ("IMAGE",),
            "int_field": ("INT", {
                "default": 0,
                "min": 0,
                "max": 4096,
                "step": 64,
                "display": "number"
            }),
            "string_field": ("STRING", {
                "multiline": False,
                "default": "Hello"
            }),
            # V1 での任意の型の処理
            "custom_field": ("MY_CUSTOM_TYPE",),
        },
        "optional": {
            "mask": ("MASK",)
        }
    }

V3:

@classmethod
def define_schema(cls) -> io.Schema:
    return io.Schema(
        node_id="Example",
        display_name="Example Node",
        category="examples",
        description="Node description here",
        inputs=[
            io.Image.Input("image"),
            io.Int.Input("int_field",
                default=0,
                min=0,
                max=4096,
                step=64,
                display_mode=io.NumberDisplay.number
            ),
            io.String.Input("string_field",
                default="Hello",
                multiline=False
            ),
            # V3 での任意の型の処理
            io.Custom("my_custom_type").Input("custom_input"),
            io.Mask.Input("mask", optional=True)
        ],
        outputs=[
            io.Image.Output()
        ]
    )

ステップ 3: 実行メソッドの更新

V3 のすべての実行関数は execute という名前で、クラスメソッドです。 V1:

def test(self, image, string_field, int_field):
    # 処理
    image = 1.0 - image
    return (image,)

V3:

@classmethod
def execute(cls, image, string_field, int_field) -> io.NodeOutput:
    # 処理
    image = 1.0 - image

    # オプションの UI プレビュー付きで返す
    return io.NodeOutput(image, ui=ui.PreviewImage(image, cls=cls))

ステップ 4: ノードプロパティの変換

以下にプロパティ名の例を示します。詳細は comfy_api.latest._io のソースコードを参照してください。

V1 プロパティ	V3 スキーマフィールド	備考
`RETURN_TYPES`	Schema の `outputs`	Output オブジェクトのリスト
`RETURN_NAMES`	Output の `display_name`	出力ごとの表示名
`FUNCTION`	常に `execute`	メソッド名が標準化
`CATEGORY`	Schema の `category`	文字列値
`OUTPUT_NODE`	Schema の `is_output_node`	布尔フラグ
`DEPRECATED`	Schema の `is_deprecated`	布尔フラグ
`EXPERIMENTAL`	Schema の `is_experimental`	布尔フラグ

ステップ 5: 特殊メソッドの処理

V1 と同じ特殊メソッドがサポートされていますが、より明確にするために小文字化または完全に改名されています。使用方法は同じです。

検証 (V1 → V3)

入力検証関数は validate_inputs に改名されました。 V1:

@classmethod
def VALIDATE_INPUTS(s, **kwargs):
    # 検証ロジック
    return True

V3:

@classmethod
def validate_inputs(cls, **kwargs) -> bool | str:
    # 有効な場合は True、無効な場合はエラー文字列を返す
    if error_condition:
        return "Error message"
    return True

遅延評価 (V1 → V3)

check_lazy_status 関数はクラスメソッドになり、それ以外は同じです。 V1:

def check_lazy_status(self, image, string_field, ...):
    if condition:
        return ["string_field"]
    return []

V3:

@classmethod
def check_lazy_status(cls, image, string_field, ...):
    if condition:
        return ["string_field"]
    return []

キャッシュ制御 (V1 → V3)

キャッシュ制御の機能は V1 と同じですが、元の関数名はどのように動作するかについて非常に誤解を招くものでした。 V1 の IS_CHANGED 関数は、戻り値がノードを前回実行したときと同じ場合、ノードの再実行をトリガーしないように信号を送ります。したがって、関数 IS_CHANGED は fingerprint_inputs に改名されました。開発者による最も一般的な間違いの 1 つは、True を返すとノードが常に再実行されると考えることでした。True が常に返されるため、ノードを 1 回だけ実行してキャッシュ値を再利用するという逆の効果になります。この関数を使用する例として、LoadImage ノードがあります。選択されたファイルのハッシュを返すため、ファイルが変更された場合、ノードは強制的に再実行されます。 V1:

@classmethod
def IS_CHANGED(s, **kwargs):
    return "unique_value"

V3:

@classmethod
def fingerprint_inputs(cls, **kwargs):
    return "unique_value"

ステップ 6: 拡張機能とエントリーポイントの作成

ノード ID をノードクラス/表示名にリンクするための辞書を定義する代わりに、ComfyExtension クラスと定義が期待される comfy_entrypoint 関数ができました。将来、get_node_list を介してノード以外を登録するために、ComfyExtension により多くの関数が追加される可能性があります。 comfy_entrypoint は非同期でも同期でも構いませんが、get_node_list は非同期として定義する必要があります。 V1:

NODE_CLASS_MAPPINGS = {
    "Example": Example
}

NODE_DISPLAY_NAME_MAPPINGS = {
    "Example": "Example Node"
}

V3:

from comfy_api.latest import ComfyExtension

class MyExtension(ComfyExtension):
    # 非同期として宣言する必要あり
    async def get_node_list(self) -> list[type[io.ComfyNode]]:
        return [
            Example,
            # ここにノードを追加
        ]

# 非同期または非非同期として宣言可能、両方機能します
async def comfy_entrypoint() -> MyExtension:
    return MyExtension()

入力型リファレンス

ステップ 2 ですでに説明しましたが、ここに V1 対 V3 の型リファレンス比較をいくつか示します。完全な型宣言は comfy_api.latest._io を参照してください。

基本型

V1 型	V3 型	例
`"INT"`	`io.Int.Input()`	`io.Int.Input("count", default=1, min=0, max=100)`
`"FLOAT"`	`io.Float.Input()`	`io.Float.Input("strength", default=1.0, min=0.0, max=10.0)`
`"STRING"`	`io.String.Input()`	`io.String.Input("text", multiline=True)`
`"BOOLEAN"`	`io.Boolean.Input()`	`io.Boolean.Input("enabled", default=True)`

control_after_generate

Int および Combo 入力は、各生成後に値を自動的に変更するための制御ウィジェットを追加する control_after_generate パラメータをサポートします。V1 ではこれは単純な bool でしたが、V3 では明示的な制御のために io.ControlAfterGenerate 列挙型を使用できます。True を渡すことは io.ControlAfterGenerate.randomize と同等です。

値	動作
`io.ControlAfterGenerate.fixed`	各生成後に値は同じまま。
`io.ControlAfterGenerate.increment`	各生成後に値がステップ分増加。
`io.ControlAfterGenerate.decrement`	各生成後に値がステップ分減少。
`io.ControlAfterGenerate.randomize`	各生成後に値がランダム化。

# 制御ウィジェットを有効化（ユーザーが UI でモードを選択）
io.Int.Input("seed", default=0, min=0, max=0xFFFFFFFFFFFFFFFF, control_after_generate=True)

# 特定のデフォルトモードを設定
io.Int.Input("seed", default=0, min=0, max=0xFFFFFFFFFFFFFFFF,
    control_after_generate=io.ControlAfterGenerate.randomize)

ComfyUI 型

V1 型	V3 型	例
`"IMAGE"`	`io.Image.Input()`	`io.Image.Input("image", tooltip="Input image")`
`"MASK"`	`io.Mask.Input()`	`io.Mask.Input("mask", optional=True)`
`"LATENT"`	`io.Latent.Input()`	`io.Latent.Input("latent")`
`"CONDITIONING"`	`io.Conditioning.Input()`	`io.Conditioning.Input("positive")`
`"MODEL"`	`io.Model.Input()`	`io.Model.Input("model")`
`"VAE"`	`io.VAE.Input()`	`io.VAE.Input("vae")`
`"CLIP"`	`io.CLIP.Input()`	`io.CLIP.Input("clip")`

Combo（ドロップダウン/選択リスト）

V3 の Combo 型には明示的なクラス定義が必要です。 V1:

"mode": (["option1", "option2", "option3"],)

V3:

io.Combo.Input("mode", options=["option1", "option2", "option3"])

スキーマリファレンス

Schema データクラスは V3 ノードのすべてのプロパティを定義します。以下に利用可能なすべてのフィールドの完全なリファレンスを示します：

フィールド	型	デフォルト	説明
`node_id`	`str`	必須	ノードのグローバル一意 ID。カスタムノードは競合を避けるためにプレフィックス/サフィックスを追加すべき。
`display_name`	`str`	`None`	UI に表示される名前。設定されていない場合、`node_id` にフォールバック。
`category`	`str`	`"sd"`	「ノードを追加」メニューのカテゴリ（例：`"image/transform"`）。
`description`	`str`	`""`	ノードにホバーしたときに表示されるツールチップ。
`inputs`	`list[Input]`	`[]`	入力定義のリスト。
`outputs`	`list[Output]`	`[]`	出力定義のリスト。
`hidden`	`list[Hidden]`	`[]`	要求する隠し入力のリスト（隠し入力を参照）。
`search_aliases`	`list[str]`	`[]`	検索の代替名。同義語や改名後の旧名に有用。
`is_output_node`	`bool`	`False`	ノードを出力ノードとしてマークし、それとその依存関係を実行させる。
`is_input_list`	`bool`	`False`	True の場合、いくつのアイテムが渡されても、すべての入力が `list[type]` になる。
`is_deprecated`	`bool`	`False`	ノードを非推奨としてフラグ付けし、ユーザーに代替手段を探すよう通知。
`is_experimental`	`bool`	`False`	ノードを実験的としてフラグ付けし、変更される可能性があることをユーザーに警告。
`is_dev_only`	`bool`	`False`	開発モードが有効でない限り、検索/メニューからノードを隠す。
`is_api_node`	`bool`	`False`	ノードを Comfy API サービスの API ノードとしてフラグ付け。
`not_idempotent`	`bool`	`False`	True の場合、ノードは常に再実行され、グラフ内の別の同一ノードからのキャッシュ出力を再利用しない。
`enable_expand`	`bool`	`False`	`NodeOutput` がノード拡張用の `expand` プロパティを含めることを許可。
`accept_all_inputs`	`bool`	`False`	True の場合、プロンプトからのすべての入力が schema で定義されていなくても kwargs として渡される。

共通入力パラメータ

すべての入力型はこれらの基本パラメータを共有します：

パラメータ	型	デフォルト	説明
`id`	`str`	必須	入力の一意識別子。`execute` での kwarg 名として使用。
`display_name`	`str`	`None`	UI に表示されるラベル。デフォルトは `id`。
`optional`	`bool`	`False`	入力がオプションかどうか。
`tooltip`	`str`	`None`	ホバー時のツールチップテキスト。
`lazy`	`bool`	`None`	入力を遅延評価としてマーク（遅延評価を参照）。
`raw_link`	`bool`	`None`	True の場合、解決された値ではなく生のリンク情報を渡す。
`advanced`	`bool`	`None`	True の場合、入力は UI の「詳細」トグルの背後に隠される。

ウィジェット入力（Int、Float、String、Boolean、Combo）は additionally サポート：

パラメータ	型	デフォルト	説明
`default`	様々	`None`	ウィジェットのデフォルト値。
`socketless`	`bool`	`None`	True の場合、入力ソケットを隠す（ウィジェットのみ、受信接続なし）。
`force_input`	`bool`	`None`	True の場合、ウィジェットをソケット入力として表示することを強制。

カスタムノードの構築

パッケージと公開

V3 移行ガイド

概要

核心概念

V1 対 V3 アーキテクチャ

V1 (レガシー)

V3 (モダン)

移行ステップ

ステップ 1: ベースクラスの変更

ステップ 2: INPUT_TYPES を define_schema に変換

ステップ 3: 実行メソッドの更新

ステップ 4: ノードプロパティの変換

ステップ 5: 特殊メソッドの処理

検証 (V1 → V3)

遅延評価 (V1 → V3)

キャッシュ制御 (V1 → V3)

ステップ 6: 拡張機能とエントリーポイントの作成

入力型リファレンス

基本型

control_after_generate

ComfyUI 型

Combo（ドロップダウン/選択リスト）

スキーマリファレンス

共通入力パラメータ

​概要

​核心概念

​V1 対 V3 アーキテクチャ

​V1 (レガシー)

​V3 (モダン)

​移行ステップ

​ステップ 1: ベースクラスの変更

​ステップ 2: INPUT_TYPES を define_schema に変換

​ステップ 3: 実行メソッドの更新

​ステップ 4: ノードプロパティの変換

​ステップ 5: 特殊メソッドの処理

​検証 (V1 → V3)

​遅延評価 (V1 → V3)

​キャッシュ制御 (V1 → V3)

​ステップ 6: 拡張機能とエントリーポイントの作成

​入力型リファレンス

​基本型

​control_after_generate

​ComfyUI 型

​Combo（ドロップダウン/選択リスト）

​スキーマリファレンス

​共通入力パラメータ

概要

核心概念

V1 対 V3 アーキテクチャ

V1 (レガシー)

V3 (モダン)

移行ステップ

ステップ 1: ベースクラスの変更

ステップ 2: INPUT_TYPES を define_schema に変換

ステップ 3: 実行メソッドの更新

ステップ 4: ノードプロパティの変換

ステップ 5: 特殊メソッドの処理

検証 (V1 → V3)

遅延評価 (V1 → V3)

キャッシュ制御 (V1 → V3)

ステップ 6: 拡張機能とエントリーポイントの作成

入力型リファレンス

基本型

control_after_generate

ComfyUI 型

Combo（ドロップダウン/選択リスト）

スキーマリファレンス

共通入力パラメータ