企业官网建设流程全解析

InvokeAI 外部模型提供商集成指南：从 StarterModel 定义到全新 Provider 适配

【免费下载链接】InvokeAIInvoke is a leading creative engine for Stable Diffusion models, empowering professionals, artists, and enthusiasts to generate and create visual media using the latest AI-driven technologies. The solution offers an industry leading WebUI, and serves as the foundation for multiple commercial products.项目地址: https://gitcode.com/GitHub_Trending/in/InvokeAI

本篇技术指南围绕 InvokeAI 的External Provider（外部生成提供商）集成机制展开，完整讲解如何为已有提供商（OpenAI、Gemini、阿里云等）新增外部模型，以及如何从零接入一个全新的外部提供商（配置字段 + Provider 适配器 + UI 注册）。读完本文，你将掌握外部模型的StarterModel定义规范、能力矩阵（Capabilities）字段语义、API Key 存储机制、Provider 子类化实现步骤，以及手动安装外部模型的 API 调用方式。

外部提供商机制概述

InvokeAI 除了在本地推理 Stable Diffusion / Flux 等模型外，还支持把OpenAI、Google Gemini、阿里云 DashScope、Seedream等云端图像生成 API 接入为"外部模型"。这类模型不在本地下载权重，而是通过 HTTP 调用厂商接口生成图像，因此被称为External Image Generator。

从源码结构看，整个机制由三层构成：

• 模型注册层：外部模型以StarterModel形式登记在 invokeai/backend/model_manager/starter_models.py 中，base=BaseModelType.External、format=ModelFormat.ExternalApi，是前端"External Providers"面板的展示数据源；
• 配置与凭据层：非敏感的提供商设置存放在invokeai.yaml，API Key 则独立存放在api_keys.yaml（参见 invokeai/app/services/config/config_default.py 中的load_external_api_keys）；
• 运行适配层：每个提供商实现一个ExternalProvider子类（位于 invokeai/app/services/external_generation/providers/），负责把统一的生成请求翻译成各厂商的 API 调用。

外部模型的核心类型定义在 invokeai/backend/model_manager/configs/external_api.py：ExternalGenerationMode限定为"txt2img"、"img2img"、"inpaint"三种模式；ExternalApiModelConfig则承载provider_id、provider_model_id、capabilities、default_settings、panel_schema等字段，并在_populate_external_fields中自动回填path（external://<provider_id>/<provider_model_id>）、source与hash（external:<provider_id>:<provider_model_id>）。也就是说，外部模型不经过磁盘探测（from_model_on_disk直接抛出NotAMatchError），其一切信息都由配置声明，而非从文件推断。

场景一：为已有提供商添加新外部模型（最常见）

这是最常见的集成场景——你使用的厂商（如 OpenAI、Gemini）已经被 InvokeAI 接入，只需把该厂商新发布的模型补充进系统。

定义 StarterModel

外部模型的"事实来源"（source of truth）是invokeai/backend/model_manager/starter_models.py。一个完整的StarterModel需要声明以下字段：

参考文档给出的完整示例：

new_external_model = StarterModel( name="Provider Model Name", base=BaseModelType.External, source="external://openai/my-model-id", description=( "Provider model (external API). " "Requires a configured OpenAI API key and may incur provider usage costs." ), type=ModelType.ExternalImageGenerator, format=ModelFormat.ExternalApi, capabilities=ExternalModelCapabilities( modes=["txt2img", "img2img", "inpaint"], supports_negative_prompt=False, supports_seed=False, supports_guidance=False, supports_steps=False, supports_reference_images=True, max_images_per_request=4, ), default_settings=ExternalApiModelDefaultSettings( width=1024, height=1024, num_images=1, ), )

定义完成后，把该对象追加到STARTER_MODELS列表即可。

仓库中真实的 Gemini 模型定义可作为最佳实践参照（starter_models.py）：

gemini_flash_image = StarterModel( name="Gemini 2.5 Flash Image", base=BaseModelType.External, source="external://gemini/gemini-2.5-flash-image", description="Google Gemini 2.5 Flash image generation model (external API). Requires a configured Gemini API key and may incur provider usage costs.", type=ModelType.ExternalImageGenerator, format=ModelFormat.ExternalApi, capabilities=ExternalModelCapabilities( modes=["txt2img"], supports_seed=True, supports_reference_images=True, max_images_per_request=1, allowed_aspect_ratios=["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"], aspect_ratio_sizes={ "1:1": ExternalImageSize(width=1024, height=1024), "2:3": ExternalImageSize(width=832, height=1248), "3:2": ExternalImageSize(width=1248, height=832), "3:4": ExternalImageSize(width=864, height=1184), "4:3": ExternalImageSize(width=1184, height=864), "4:5": ExternalImageSize(width=896, height=1152), "5:4": ExternalImageSize(width=1152, height=896), "9:16": ExternalImageSize(width=768, height=1344), "16:9": ExternalImageSize(width=1344, height=768), "21:9": ExternalImageSize(width=1536, height=672), }, ), default_settings=ExternalApiModelDefaultSettings(width=1024, height=1024, num_images=1), panel_schema=ExternalModelPanelSchema(prompts=[{"name": "reference_images"}], image=[{"name": "dimensions"}]), )

对比可见，真实模型还使用了allowed_aspect_ratios、aspect_ratio_sizes、max_reference_images、panel_schema等进阶字段（定义见 external_api.py），用于在 UI 中呈现受限的分辨率/比例选项和面板控件。

描述文本的强制要求

外部模型（external starter model）的description必须清楚声明两件事：

1. 需要配置 API Key（"Requires a configured ... API key"）；
2. 调用可能产生厂商侧费用（"may incur provider usage costs"）。

这一要求在仓库所有外部模型定义中保持一致，例如 Qwen Image 2.0 Pro 的描述是 "Requires a configured Alibaba Cloud DashScope API key and may incur provider usage costs"。

能力矩阵必须精确

ExternalModelCapabilities中这几个布尔标志直接控制 UI 可见性和请求载荷字段（完整字段见 external_api.py）：

• supports_negative_prompt：是否支持负面提示词；
• supports_seed：是否支持指定随机种子；
• supports_guidance：是否支持引导强度（CFG）；
• supports_steps：是否支持步数控制；
• supports_reference_images：是否支持参考图（垫图）。

其中supports_steps尤为关键：如果设为False，该模型的步数控件会被隐藏，且请求时steps字段会以null发送。同理，supports_negative_prompt=False时不会向请求注入负面提示词字段。其它进阶字段还包括：

• modes：允许的生成模式列表，默认["txt2img"]；
• max_images_per_request：单次请求最大出图数；
• max_image_size/allowed_aspect_ratios/aspect_ratio_sizes/resolution_presets：尺寸与比例限制；
• max_reference_images：最大参考图数量；
• mask_format：蒙版格式（"alpha"/"binary"/"none"）；
• input_image_required_for：哪些模式强制要求输入图。

能力矩阵不准确会直接导致 UI 上出现不可用的控件，或在运行时被外部生成服务拒绝，因此必须逐项核对厂商 API 文档后填写。

source 字符串的稳定性

外部模型的覆盖（override）匹配依赖source（即external://provider/model-id）。该值一旦发布就应保持稳定，因为：

• 运行时的能力/默认值覆盖（starter override）依赖它定位模型；
• Starter 模型 API 的安装检测（installation detection）依赖它判断模型是否已安装。

STARTER_MODELS内部通过断言强制source全局唯一，重复定义会直接抛错。

安装行为说明

外部模型与本地模型在安装行为上有三点差异：

1. 外部模型在External Providers 设置面板中管理，而不是常规的 Starter Models 标签页；
2. 当某个提供商完成配置（填入 API Key）后，该提供商的全部外部模型自动安装；
3. 移除提供商 API Key 后，该提供商已安装的外部模型会被一并移除。

后端行为与之一致：在 invokeai/app/api/dependencies.py 中，只有is_configured()返回True的提供商才会出现在configured_provider_ids中，未配置的提供商模型自然不可用。

凭据与配置管理

API Key 独立存储

外部提供商的 API Key不写入invokeai.yaml，而是单独存放在一个 YAML 文件中：

• 默认路径：~/invokeai/api_keys.yaml
• 解析后路径：<INVOKEAI_ROOT>/api_keys.yaml

从 config_default.py 的load_external_api_keys实现看，该文件会按EXTERNAL_PROVIDER_CONFIG_FIELDS中登记的字段名逐个读取，且只接受字符串值（非字符串或非映射结构会抛出RuntimeError），空值与缺失字段会被安全跳过。示例：

# ~/invokeai/api_keys.yaml external_openai_api_key: sk-xxxxxxxx external_gemini_api_key: AIzaXXXXXXXX external_alibabacloud_api_key: sk-xxxxxxxx external_seedream_api_key: xxxxxxxx

非敏感的提供商设置（例如 base URL 覆盖）则保留在invokeai.yaml中，对应的字段是external_<provider>_api_key与external_<provider>_base_url（config_default.py）。

环境变量兜底

环境变量仍然受支持，优先级按pydantic-settings的标准合并机制生效，例如：

export INVOKEAI_EXTERNAL_GEMINI_API_KEY="AIzaXXXXXXXX" export INVOKEAI_EXTERNAL_OPENAI_API_KEY="sk-xxxxxxxx"

场景二：新增一个完整的外部提供商（仅在必要时）

如果目标模型使用的厂商尚未被 InvokeAI 集成，就需要按以下 6 步接入一个全新提供商：

1. 在默认配置中增加配置字段

在 invokeai/app/services/config/config_default.py 中新增external_<provider>_api_key字段，以及可选的external_<provider>_base_url字段。同时要把字段名登记进EXTERNAL_PROVIDER_CONFIG_FIELDS，load_external_api_keys才会从api_keys.yaml中读取它。

2. 在 app_info 路由中登记字段映射

在 invokeai/app/api/routers/app_info.py 的EXTERNAL_PROVIDER_FIELDS字典中，为新的provider_id添加(api_key_field, base_url_field)元组映射。当前已登记的提供商为：

EXTERNAL_PROVIDER_FIELDS: dict[str, tuple[str, str]] = { "alibabacloud": ("external_alibabacloud_api_key", "external_alibabacloud_base_url"), "gemini": ("external_gemini_api_key", "external_gemini_base_url"), "openai": ("external_openai_api_key", "external_openai_base_url"), "seedream": ("external_seedream_api_key", "external_seedream_base_url"), }

该映射服务于前端的提供商配置查询（返回ExternalProviderConfigModel：provider_id、api_key_configured、base_url）。

3. 实现 Provider 适配器

在 invokeai/app/services/external_generation/providers/ 目录下新建适配器，子类化抽象基类ExternalProvider（定义见 external_generation_base.py）。基类要求：

• 声明类属性provider_id: str；
• 实现is_configured() -> bool：返回该提供商是否已配置（通常检查 API Key 是否非空）；
• 实现generate(request: ExternalGenerationRequest) -> ExternalGenerationResult：把统一的生成请求翻译为厂商 API 调用。

基类还提供了get_status()的默认实现，返回ExternalProviderStatus(provider_id=..., configured=...)。请求/响应数据类定义在 external_generation_common.py：ExternalGenerationRequest携带模型配置、模式、提示词、种子、尺寸、初始化图像、蒙版、参考图列表与provider_options；ExternalGenerationResult返回生成图像列表、实际使用的种子、提供商请求 ID 与元数据。

4. 在依赖注入中注册提供商

在 invokeai/app/api/dependencies.py 构建ExternalGenerationService时，把新适配器实例加入providers字典。当前注册了 AlibabaCloudProvider、GeminiProvider、OpenAIProvider、SeedreamProvider 四个：

external_generation = ExternalGenerationService( providers={ AlibabaCloudProvider.provider_id: AlibabaCloudProvider(app_config=configuration, logger=logger), GeminiProvider.provider_id: GeminiProvider(app_config=configuration, logger=logger), OpenAIProvider.provider_id: OpenAIProvider(app_config=configuration, logger=logger), SeedreamProvider.provider_id: SeedreamProvider(app_config=configuration, logger=logger), }, )

5. 添加 Starter 模型条目

按照场景一的方式，用source="external://<provider>/<model-id>"添加该提供商下的模型定义，并追加进STARTER_MODELS。

6. 可选：调整 UI 排序

如需控制前端 External Providers 面板中提供商的展示顺序，可修改 invokeai/frontend/web/src/features/modelManagerV2/subpanels/AddModelPanel/ExternalProviders/ExternalProvidersForm.tsx 中的PROVIDER_SORT_ORDER。

可选：手动安装外部模型

除了通过 UI 自动安装，外部模型也可以直接通过 REST API 手动安装：

POST /api/v2/models/install?source=external://<provider_id>/<provider_model_id>

关于该接口有两点实现细节值得注意：

• 字段自动回填：当path、source、hash被省略时，ExternalApiModelConfig._populate_external_fields（external_api.py）会自动生成——path与source均为external://<provider_id>/<provider_model_id>，hash为external:<provider_id>:<provider_model_id>；
• 能力校验在运行时强制执行：手动安装时应保守设置capabilities，因为外部生成服务会在运行时对能力矩阵做检查，能力声明过宽会在实际调用时被拒绝。

最佳实践小结

1. 新增模型优先走场景一：绝大多数情况只需在 starter_models.py 增加一个StarterModel并追加到STARTER_MODELS，无需触碰任何后端服务代码；
2. 描述文本必须声明 API Key 与费用，这是对外部模型的基本合规要求；
3. 能力矩阵宁保守勿激进，supports_*标志直接决定 UI 控件与请求字段，supports_steps=False时会发送steps=null；
4. source一旦发布保持稳定，它同时是覆盖匹配与安装检测的键，且STARTER_MODELS强制其唯一；
5. API Key 只进api_keys.yaml或环境变量，不要写入invokeai.yaml；base URL 等非敏感设置留在invokeai.yaml；
6. 新增完整提供商是 6 步联动：配置字段 → app_info 映射 → Provider 适配器 → 依赖注入注册 → Starter 模型条目 →（可选）UI 排序，任何一步缺失都会导致模型在前端不可见或运行时调用失败。

【免费下载链接】InvokeAIInvoke is a leading creative engine for Stable Diffusion models, empowering professionals, artists, and enthusiasts to generate and create visual media using the latest AI-driven technologies. The solution offers an industry leading WebUI, and serves as the foundation for multiple commercial products.项目地址: https://gitcode.com/GitHub_Trending/in/InvokeAI