> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-docs-robin-i18n-sync.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# V3 移行ガイド

> 既存の V1 ノードを新しい V3 スキーマに移行する方法。

## 概要

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

## 核心概念

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

```python theme={null}
# 最新の 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 (レガシー)

```python theme={null}
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 (モダン)

```python theme={null}
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:**

```python theme={null}
class Example:
    def __init__(self):
        pass
```

**V3:**

```python theme={null}
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:**

```python theme={null}
@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:**

```python theme={null}
@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:**

```python theme={null}
def test(self, image, string_field, int_field):
    # 処理
    image = 1.0 - image
    return (image,)
```

**V3:**

```python theme={null}
@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:**

```python theme={null}
@classmethod
def VALIDATE_INPUTS(s, **kwargs):
    # 検証ロジック
    return True
```

**V3:**

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

#### 遅延評価 (V1 → V3)

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

**V1:**

```python theme={null}
def check_lazy_status(self, image, string_field, ...):
    if condition:
        return ["string_field"]
    return []
```

**V3:**

```python theme={null}
@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:**

```python theme={null}
@classmethod
def IS_CHANGED(s, **kwargs):
    return "unique_value"
```

**V3:**

```python theme={null}
@classmethod
def fingerprint_inputs(cls, **kwargs):
    return "unique_value"
```

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

ノード ID をノードクラス/表示名にリンクするための辞書を定義する代わりに、`ComfyExtension` クラスと定義が期待される `comfy_entrypoint` 関数ができました。

将来、`get_node_list` を介してノード以外を登録するために、ComfyExtension により多くの関数が追加される可能性があります。

`comfy_entrypoint` は非同期でも同期でも構いませんが、`get_node_list` は非同期として定義する必要があります。

**V1:**

```python theme={null}
NODE_CLASS_MAPPINGS = {
    "Example": Example
}

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

**V3:**

```python theme={null}
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` | 各生成後に値がランダム化。   |

```python theme={null}
# 制御ウィジェットを有効化（ユーザーが 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:**

```python theme={null}
"mode": (["option1", "option2", "option3"],)
```

**V3:**

```python theme={null}
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`  | 入力を遅延評価としてマーク（[遅延評価](#遅延評価-v1--v3) を参照）。 |
| `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 の場合、ウィジェットをソケット入力として表示することを強制。  |