docs(config): disclose legacy device precedence in generation_devices auto copy

docs/src/content/docs/configuration/invokeai-yaml.mdx

@@ -126,7 +126,7 @@ generation_devices: auto # default value
 
 | Value                      | Behavior                                                                                                                |
 | -------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `auto`                          | Use every available CUDA GPU, running one generation session per GPU concurrently. This is the default.             |
+| `auto`                          | Use every available CUDA GPU, running one generation session per GPU concurrently. This is the default. Exception: if the legacy `device` setting is pinned to a specific device, `auto` uses only that device (see Notes below). |
 | `[cuda:0,cuda:1]`         | Use the specific devices listed, one session per device. Useful for reserving a GPU for other work.                 |
 | `[cuda:0]`                | Use a single specific device. Generation runs serially, as it did before multi-GPU support.                                 |
 

docs/src/generated/settings.json

@@ -515,7 +515,7 @@
     {
       "category": "DEVICE",
       "default": "auto",
-      "description": "Devices to use for parallel generation. `auto` (the default) uses every available GPU, running one generation session per GPU concurrently and distributing jobs fairly across users. Provide an explicit list (e.g. `[cuda:0, cuda:1]`) to use specific devices, or a single-device list (e.g. `[cuda:0]`) to run serially. On systems without a GPU, `auto` resolves to the single `cpu`/`mps` device.<br>Valid values: `auto`, or a list whose entries are each `cpu`, `cuda`, `mps`, or `cuda:N` (where N is a device number)",
+      "description": "Devices to use for parallel generation. `auto` (the default) uses every available GPU, running one generation session per GPU concurrently and distributing jobs fairly across users \u2014 unless the legacy `device` setting is pinned to a specific device, in which case `auto` uses only that device (preserving configs that pinned `device` before multi-GPU support existed). Provide an explicit list (e.g. `[cuda:0, cuda:1]`) to use specific devices regardless of `device`, or a single-device list (e.g. `[cuda:0]`) to run serially. On systems without a GPU, `auto` resolves to the single `cpu`/`mps` device.<br>Valid values: `auto`, or a list whose entries are each `cpu`, `cuda`, `mps`, or `cuda:N` (where N is a device number)",
       "env_var": "INVOKEAI_GENERATION_DEVICES",
       "literal_values": [],
       "name": "generation_devices",

invokeai/app/services/config/config_default.py

@@ -214,7 +214,7 @@ class InvokeAIAppConfig(BaseSettings):
 
     # DEVICE
     device:                      str = Field(default="auto",                description="Preferred execution device. `auto` will choose the device depending on the hardware platform and the installed torch capabilities.<br>Valid values: `auto`, `cpu`, `cuda`, `mps`, `cuda:N` (where N is a device number)", pattern=r"^(auto|cpu|mps|cuda(:\d+)?)$")
-    generation_devices: Union[Literal["auto"], list[str]] = Field(default="auto", description="Devices to use for parallel generation. `auto` (the default) uses every available GPU, running one generation session per GPU concurrently and distributing jobs fairly across users. Provide an explicit list (e.g. `[cuda:0, cuda:1]`) to use specific devices, or a single-device list (e.g. `[cuda:0]`) to run serially. On systems without a GPU, `auto` resolves to the single `cpu`/`mps` device.<br>Valid values: `auto`, or a list whose entries are each `cpu`, `cuda`, `mps`, or `cuda:N` (where N is a device number)")
+    generation_devices: Union[Literal["auto"], list[str]] = Field(default="auto", description="Devices to use for parallel generation. `auto` (the default) uses every available GPU, running one generation session per GPU concurrently and distributing jobs fairly across users — unless the legacy `device` setting is pinned to a specific device, in which case `auto` uses only that device (preserving configs that pinned `device` before multi-GPU support existed). Provide an explicit list (e.g. `[cuda:0, cuda:1]`) to use specific devices regardless of `device`, or a single-device list (e.g. `[cuda:0]`) to run serially. On systems without a GPU, `auto` resolves to the single `cpu`/`mps` device.<br>Valid values: `auto`, or a list whose entries are each `cpu`, `cuda`, `mps`, or `cuda:N` (where N is a device number)")
     offload_text_encoders_to_idle_gpus: bool = Field(default=True,          description="When running on multiple GPUs, load text encoders onto a currently-idle GPU instead of the one running the denoise pipeline. This avoids churning the denoise model in and out of VRAM to make room for the encoder, and lets a cached encoder be reused across generations. Has no effect unless at least two `generation_devices` are configured and a GPU is idle; under full load encoders run on the session's own GPU as before.")
     precision:                PRECISION = Field(default="auto",             description="Floating point precision. `float16` will consume half the memory of `float32` but produce slightly lower-quality images. The `auto` setting will guess the proper precision based on your video card and operating system.")
 

invokeai/frontend/web/openapi.json

@@ -49112,7 +49112,7 @@
               }
             ],
             "title": "Generation Devices",
-            "description": "Devices to use for parallel generation. `auto` (the default) uses every available GPU, running one generation session per GPU concurrently and distributing jobs fairly across users. Provide an explicit list (e.g. `[cuda:0, cuda:1]`) to use specific devices, or a single-device list (e.g. `[cuda:0]`) to run serially. On systems without a GPU, `auto` resolves to the single `cpu`/`mps` device.<br>Valid values: `auto`, or a list whose entries are each `cpu`, `cuda`, `mps`, or `cuda:N` (where N is a device number)",
+            "description": "Devices to use for parallel generation. `auto` (the default) uses every available GPU, running one generation session per GPU concurrently and distributing jobs fairly across users \u2014 unless the legacy `device` setting is pinned to a specific device, in which case `auto` uses only that device (preserving configs that pinned `device` before multi-GPU support existed). Provide an explicit list (e.g. `[cuda:0, cuda:1]`) to use specific devices regardless of `device`, or a single-device list (e.g. `[cuda:0]`) to run serially. On systems without a GPU, `auto` resolves to the single `cpu`/`mps` device.<br>Valid values: `auto`, or a list whose entries are each `cpu`, `cuda`, `mps`, or `cuda:N` (where N is a device number)",
             "default": "auto"
           },
           "offload_text_encoders_to_idle_gpus": {

invokeai/frontend/web/public/locales/en.json

@@ -1962,8 +1962,8 @@
         "general": "General",
         "generation": "Generation",
         "generationDevices": "Generation Devices",
-        "generationDevicesAuto": "Auto (all GPUs)",
-        "generationDevicesHelp": "Select which devices to use for parallel generation, one session per device. \"Auto\" uses every available GPU.",
+        "generationDevicesAuto": "Auto",
+        "generationDevicesHelp": "Select which devices to use for parallel generation, one session per device. \"Auto\" uses every available GPU — unless the legacy 'device' setting in invokeai.yaml pins a specific device, in which case only that device is used. An explicit selection here overrides 'device'.",
         "generationDevicesRestart": "Restart InvokeAI for changes to take effect.",
         "generationDevicesSaveFailed": "Failed to save Generation Devices",
         "imageSubfolderStrategy": "Image Subfolder Strategy",

invokeai/frontend/web/src/services/api/schema.ts

@@ -19236,7 +19236,7 @@ export type components = {
             device?: string;
             /**
              * Generation Devices
-             * @description Devices to use for parallel generation. `auto` (the default) uses every available GPU, running one generation session per GPU concurrently and distributing jobs fairly across users. Provide an explicit list (e.g. `[cuda:0, cuda:1]`) to use specific devices, or a single-device list (e.g. `[cuda:0]`) to run serially. On systems without a GPU, `auto` resolves to the single `cpu`/`mps` device.<br>Valid values: `auto`, or a list whose entries are each `cpu`, `cuda`, `mps`, or `cuda:N` (where N is a device number)
+             * @description Devices to use for parallel generation. `auto` (the default) uses every available GPU, running one generation session per GPU concurrently and distributing jobs fairly across users — unless the legacy `device` setting is pinned to a specific device, in which case `auto` uses only that device (preserving configs that pinned `device` before multi-GPU support existed). Provide an explicit list (e.g. `[cuda:0, cuda:1]`) to use specific devices regardless of `device`, or a single-device list (e.g. `[cuda:0]`) to run serially. On systems without a GPU, `auto` resolves to the single `cpu`/`mps` device.<br>Valid values: `auto`, or a list whose entries are each `cpu`, `cuda`, `mps`, or `cuda:N` (where N is a device number)
              * @default auto
              */
             generation_devices?: "auto" | string[];

tests/app/services/config/test_config_generation_devices.py

@@ -36,3 +36,33 @@ def test_empty_list_is_rejected():
 def test_invalid_device_name_is_rejected():
     with pytest.raises(ValidationError):
         InvokeAIAppConfig(generation_devices=["gpu0"])
+
+
+def test_auto_copy_documents_legacy_device_precedence():
+    """`generation_devices: auto` resolves to the single pinned legacy `device` when one is set
+    (see TorchDevice.get_generation_devices), so every user-facing description of `auto` must
+    disclose that exception instead of promising "every available GPU" unconditionally. Checks the
+    schema description (source of the API docs and generated settings docs), the generated docs
+    settings.json, the Settings UI copy, and the configuration guide's behavior table."""
+    import json
+    from pathlib import Path
+
+    repo_root = Path(__file__).parents[4]
+
+    field_description = InvokeAIAppConfig.model_fields["generation_devices"].description
+    assert field_description is not None
+    assert "legacy `device`" in field_description
+
+    generated_settings = json.loads((repo_root / "docs/src/generated/settings.json").read_text())
+    generated_description = next(
+        s["description"] for s in generated_settings["settings"] if s["name"] == "generation_devices"
+    )
+    assert "legacy `device`" in generated_description
+
+    locales = json.loads((repo_root / "invokeai/frontend/web/public/locales/en.json").read_text(encoding="utf-8"))
+    assert locales["settings"]["generationDevicesAuto"] == "Auto"  # not "Auto (all GPUs)"
+    assert "'device'" in locales["settings"]["generationDevicesHelp"]
+
+    guide = (repo_root / "docs/src/content/docs/configuration/invokeai-yaml.mdx").read_text(encoding="utf-8")
+    auto_row = next(line for line in guide.splitlines() if line.startswith("| `auto`"))
+    assert "legacy `device`" in auto_row