企业官网建设流程全解析

• AI 应用
• 媒体生成

本指南以 imaginairy 仓库中的imagineCLI 文档为骨架，结合 imaginairy/cli/imagine.py、imaginairy/cli/shared.py、imaginairy/config.py 等源码展开。读完本文，你将掌握imagine/aimg imagine的全部常用参数、ControlNet 控制信号、图生图与蒙版修复、外扩（outpainting）、平铺（tile）、参数调度（arg-schedule）与视频生成等进阶玩法，并能把命令行参数与底层 ImaginePrompt 数据模型一一对应起来，方便后续迁移到 Python API。

imagine是 imaginAIry 的核心文生图命令，既可以独立运行（imagine），也可以作为交互式 shell（aimg）的子命令使用。它支持一次批量生成多张图片、多个提示词、多张初始化图片以及 ControlNet 结构化控制，还内置了--videogen将生成结果直接变为视频。下面按“入口与整体流程 → 高频参数 → 结构化控制 → 进阶玩法 → 底层原理”的顺序展开。

命令入口与整体调用链

两种调用方式

• 独立命令：imagine "a scenic landscape"，等价于aimg imagine ...（源码中的 docstring 明确指出 “Can be invoked via eitheraimg imagineor justimagine”，见 imaginairy/cli/imagine.py）。
• 交互式 shell：直接运行aimg进入🤖🧠>提示符，模型可常驻内存，多次生成/编辑更快（imaginairy/cli/main.py）。aimg命令组注册了imagine、edit、upscale、describe、colorize、videogen、server等子命令。

从 CLI 到 Python API 的调用链

imagine_cmd首先收集并解析 ControlNet 输入，然后委托给 imaginairy/cli/shared.py 中的_imagine_cmd（第 32-267 行）。核心流程如下：

1. 提示词展开：对每个 prompt 调用expand_prompts，支持{}随机选词、{_category_}短语库语法（imaginairy/enhancers/prompt_expansion.py）。
2. 构造 ImaginePrompt：把 CLI 参数映射为 imaginairy/schema.py 中的 Pydantic 模型，进行校验与默认值填充（如init_image_strength默认为 0.2、步骤数按 solver 决定等）。
3. 批量生成：调用imagine_image_files(prompts, outdir=..., record_step_images=..., make_gif=..., make_compare_gif=..., videogen=...)（imaginairy/api/generate.py），输出目录结构为outdir/generated（生成图）、outdir/steps（过程图）、outdir/gif（动画）等。

输出文件命名规则

从 imaginairy/api/generate.py 可以看出，输出文件名高度结构化：

{序号:06d}_{seed}_{solver}{steps}_PS{prompt_strength}[_img2img-{init_image_strength}]_{prompt}[_{type}].{ext}

例如000066_801493266_PLMS40_PS7.5_gold_coins.jpg表示：序号 66、seed 801493266、PLMS solver、40 步、提示词强度 7.5、提示词 “gold coins”。文件名即元数据，仓库docs/assets/下大量示例文件（如 docs/assets/000066_801493266_PLMS40_PS7.5_gold_coins.jpg）就是这种命名的真实产物。

高频基础参数详解

下表覆盖了imagine最常用的参数（定义见 imaginairy/cli/shared.py 的common_options与imagine_cmd专属选项）：

负提示词的内置默认值

即使不传--negative-prompt，CLI 也会套用config.DEFAULT_NEGATIVE_PROMPT（imaginairy/config.py）来降低畸形手、坏解剖、模糊水印等常见瑕疵；该默认值在ImaginePrompt的validate_negative_prompt中完成填充（imaginairy/schema.py）。OpenJourney 系列模型则将默认负提示词替换为poor quality（imaginairy/config.py）。

尺寸解析：--size的三种写法

--size由 imaginairy/utils/named_resolutions.py 的normalize_image_size解析，支持：

1. WIDTHxHEIGHT或WIDTH,HEIGHT，如512x512、1920x1080；
2. 单个整数，如512表示 512×512；
3. 命名分辨率，如720p、1080p、4K、UHD、HD、FHD等（完整映射表见 imaginairy/utils/named_resolutions.py）。

建议尺寸为 8 的倍数；不同架构有默认尺寸（如 sd15 默认 512、sdxl 默认 1024，见 imaginairy/config.py）。

结构化控制：ControlNet 与--control-*参数

imagine的独门优势在于把 ControlNet 控制信号做成了 CLI 一等公民（参数定义见 imaginairy/cli/imagine.py）：

--control-mode支持的取值（同时是aimg model-list中展示的 CONTROL MODES，见 imaginairy/cli/main.py）：

canny depth details normal hed openpose shuffle edit inpaint colorize qrcode densepose

它们与 imaginairy/config.py 的CONTROL_CONFIGS一一对应，每个模式都有独立的权重下载地址与配置文件（如configs/control-net-v15.yaml、configs/control-net-v15-pool.yaml）。

多控制源组合

CLI 通过记录参数的输入顺序（ImagineColorsCommand._option_order）将--control-image、--control-image-raw、--control-strength、--control-mode按位置配对（imaginairy/cli/imagine.py），因此可以同时叠加多个控制信号：

imagine \ --control-image person.jpg --control-mode openpose --control-strength 0.8 \ --control-image scene.jpg --control-mode depth --control-strength 0.5 \ "a character standing in a room"

实战示例（源自 README，可在docs/assets/验证效果）

• OpenPose 姿态控制：imagine --control-image assets/indiana.jpg --control-mode openpose --caption-text openpose "photo of a polar bear"（输入见 docs/assets/indiana.jpg，姿态图 docs/assets/indiana-pose.jpg，生成结果 docs/assets/indiana-pose-polar-bear.jpg）。
• Canny 边缘控制：imagine --control-image assets/lena.png --control-mode canny "photo of a woman with a hat looking at the camera"（边缘图 docs/assets/lena-canny.jpg、生成图 docs/assets/lena-canny-generated.jpg）。
• 深度图控制：imagine --control-image fancy-living.jpg --control-mode depth "a modern living room"（深度图 docs/assets/fancy-living-depth.jpg、生成图 docs/assets/fancy-living-depth-generated.jpg）。
• HED 边缘控制：imagine --control-image dog.jpg --control-mode hed "photo of a dalmation"（生成图 docs/assets/dog-hed-boundary-dalmation.jpg）。
• 编辑指令控制（edit）：imagine --control-image pearl-girl.jpg --control-mode edit --init-image-strength 0.01 --steps 30 --negative-prompt "" --model openjourney-v2 "make it anime" "make it at the beach"（效果见 docs/assets/pearl_anime_019537_521829407_kdpmpp2m30_PS9.0_img2img-0.01_make_it_anime.jpg）。
• 细节补充（details）：imagine --control-image "assets/wishbone.jpg" --control-mode details "sharp focus, high-resolution" --init-image-strength 0.2 --steps 30 -w 2048 -h 2048（对比见 docs/assets/wishbone_headshot_badscale.jpg 与 docs/assets/wishbone_headshot_details.jpg）。

注意：README 明确说明 ControlNet 目前不适用于 SDXL 模型，结构化控制请使用 SD 1.5 系列（sd15、openjourney-*等）。

底层校验方面，ControlInput模型要求mode必须是合法模式、image与image_raw二选一，且strength取值 0-1000（默认 1），见 imaginairy/schema.py。若未指定--init-image而给了--control-image，ImaginePrompt会自动把控制图作为起始图使用（imaginairy/schema.py）。

图生图、蒙版修复与外扩（inpainting / outpainting）

基础图生图

imagine --init-image girl_with_a_pearl_earring_large.jpg --init-image-strength 0.05 \ "professional headshot photo of a woman with a pearl earring" \ -r 4 -w 1024 -h 1024 --steps 50

--init-image支持本地路径、URL（LazyLoadingImage惰性加载，见 imaginairy/schema.py）以及textimg=前缀文本图像。--init-image-strength取值 0-1：0.05 表示几乎完全重绘、仅保留构图/色彩线索；1.0 则接近原图微调。当存在控制信号或蒙版时，该值自动回退为 0.0（imaginairy/schema.py）。

基于文本的蒙版（--mask-prompt）

用文字描述要修补的区域，支持布尔逻辑与强度修饰符（由 clipseg 实现，README “Prompt Based Masking” 一节有完整语法说明）：

• 关键词AND、OR、NOT必须大写，支持括号；
• 修饰符：{+n}扩张 n 像素、{-n}收缩、{*n}放大强度（扩到弱匹配区）、{/n}缩小强度；
• 像素强度取值 0-1，写修饰符时注意量级。

imagine \ --init-image pearl_earring.jpg \ --mask-prompt "face AND NOT (bandana OR hair OR blue fabric){*6}" \ --mask-mode keep \ --init-image-strength .2 \ --fix-faces \ "a modern female president" "a female robot" "a female doctor" "a female firefighter"

相关参数：--mask-image（直接给蒙版图，白=重绘、黑=保留）、--mask-mode keep|replace（保留还是替换蒙版区域）、--mask-modify-original（修复后把改动叠加回原图）。对应效果图见 docs/assets/mask_examples/ 目录（如珍珠耳环少女系列 docs/assets/mask_examples/pearl_pres.png、docs/assets/mask_examples/pearl_robot.png）。

校验规则：mask_image与mask_prompt不能同时使用；使用蒙版必须提供init_image；若未显式指定模型，蒙版/外扩任务会自动切换到对应 inpainting 权重（如sd15inpaint、sdxl-inpaint），见 imaginairy/schema.py。

外扩（Outpainting）

imagine --init-image pearl-earring.jpg --init-image-strength 0 --outpaint all250,up0,down600 "woman standing"

--outpaint语法（帮助文本与 imaginairy/utils/outpaint.py 的outpaint_arg_str_parse校验一致）：

• --outpaint up10,down300,left50,right50（或缩写u10,d300,l50,r50）；
• --outpaint all200（或a200）表示四边各扩 200；
• 扩展值会自动吸附，使输出尺寸为 8 的倍数。

示例效果见 tests/expected_output/test_outpainting_outpaint_.png。

平铺与 360° 全景生成

--tile/--tile-x/--tile-y使生成图像在 X/Y 方向无缝平铺（对应ImaginePrompt.tile_mode的xy/x/y，校验见 imaginairy/schema.py）：

# 四向无缝平铺素材 imagine "gold coins" "a lush forest" "piles of old books" leaves --tile # 360 度等距柱状全景（横向平铺） imagine --tile-x -w 1024 -h 512 "360 degree equirectangular panorama photograph of the desert" --upscale

仓库示例：平铺金币 docs/assets/000066_801493266_PLMS40_PS7.5_gold_coins.jpg、沙漠全景 docs/assets/desert_360.jpg。

提示词工程与批量玩法

提示词展开（随机词 / 短语库）

• {a|b|c}：不重复地随机抽取，imagine "a {lime|blue|silver|aqua} colored dog" -r 4 --seed 0会依次生成四种颜色的狗（示例见 docs/assets/000184_0_plms40_PS7.5_a_silver_colored_dog_[generated].jpg）。
• {_category_}：从内置短语库抽取，如{_color_}、{_animal_}、{_art-scene_}、{_artist_}、{_painting-style_}。短语库文件位于 imaginairy/enhancers/phraselists/ 与 imaginairy/vendored/noodle_soup_prompts/。
• --prompt-library-path：可多次指定自定义短语库文件夹（.txt 文件），在提示词中用{_文件名_}引用。

# 无限生成 8K 艺术画 aimg 🤖🧠> imagine -w 1920 -h 1080 --upscale "{_art-scene_}. {_painting-style_} by {_artist_}" -r 1000 --steps 30 --model sd21v # 无限生成桌面壁纸 🤖🧠> imagine --tile "{_desktop-background_}" -r 100

参数调度--arg-schedule

在一次运行中让参数按序列变化，两种格式（解析实现见 imaginairy/cli/arg_schedule.py）：

• 区间式：--arg-schedule arg_name[start:end:increment]，如prompt-strength[2:8:0.5]；
• 列举式：--arg-schedule arg_name[val,val2,val3]，如model[sd14,sd15,sd20,sd21,openjourney-v1,openjourney-v2]。

所有调度必须长度一致。典型用法（来自 README）：

imagine "valley, fairytale treehouse village ..., matte painting, ..." \ --steps 60 --seed 1 \ --arg-schedule model[sd14,sd15,sd20,sd21,openjourney-v1,openjourney-v2] \ --arg-schedule "caption-text[sd14,sd15,sd20,sd21,openjourney-v1,openjourney-v2]"

对比效果见 docs/assets/fairytale-treehouse-sd15.jpg 等一组同提示词不同模型的生成图。

动画与视频

• --gif：生成扩散过程 GIF（保存在outdir/gif，见 imaginairy/api/generate.py）；
• --compare-gif：原图与生成结果对比动画（需--init-image）；
• --compilation-anim gif|mp4：把本次运行所有生成图做成幻灯片动画（实现见 imaginairy/cli/shared.py）；
• --videogen：生成图片后立即用 Stable Video Diffusion 产出短视频（imaginairy/cli/imagine.py 与 imaginairy/api/generate.py）；
• --caption-text：把指定文字叠印到图上（如--caption-text openpose）。

常用模型与自定义权重

内置模型别名一览（完整定义见 imaginairy/config.py）：

• 查看全部：aimg model-list会打印权重别名表与 ControlNet 模式表（imaginairy/cli/main.py）。
• 自定义权重：--model /path/to/weights.safetensors --model-architecture sd15，也支持 diffusers 目录模型（如 Hugging Face 模型仓库路径）。CLI 中未匹配到内置别名时，会将其包装为自定义权重配置（imaginairy/cli/shared.py）。

测试与验证：CLI 的可信度来自哪里

仓库测试 tests/test_cli/test_cmds.py 覆盖了核心 CLI 行为：

• test_cmd_help_time：逐个子命令执行--help，校验退出码为 0 且帮助输出耗时 < 1 秒（tests/test_cli/test_cmds.py）；
• test_imagine_cmd：真实调用imagine_cmd生成 “gold coins”（2 步、固定 seed 703425280），断言成功（tests/test_cli/test_cmds.py）；
• test_aimg_shell：验证aimg无参数时进入交互 shell（tests/test_cli/test_cmds.py）。

tests/expected_output/目录中大量命名规范的 PNG（如test_imagine[ddim]_.png、test_img2img_beach_to_sunset[dpmpp]_.png）进一步印证了本文所述的参数组合与输出行为。

环境要求与安装

• Python 优先 3.10；Linux / macOS(M1) 开箱即用，Windows 需先按官方指引安装 torch。
• 硬件：建议 CUDA GPU ≥ 11GB 显存（或 M1），首次运行会自动下载模型权重（约 10GB 空间），无需 Hugging Face 账号。
• 安装：pip install imaginairy；macOS 需先安装 rust（编译tokenizer依赖）。
• 缓存目录：可通过HUGGINGFACE_HUB_CACHE环境变量修改模型缓存位置；缓存位于~/.cache/imaginairy、~/.cache/clip、~/.cache/torch、~/.cache/huggingface。
• Docker：仓库根目录提供 Dockerfile，运行时建议映射 GPU 与缓存目录。

小结

imagine把 imaginAIry 的核心能力压缩进了一条命令：文生图、图生图、蒙版修复、外扩、ControlNet 结构化控制、平铺、批量化提示词、参数调度、人脸修复与视频生成。理解 CLI 参数与ImaginePrompt/ControlInput数据模型的对应关系后，你可以轻松地把命令行经验迁移到 Python API（from imaginairy import imagine, imagine_image_files, ImaginePrompt），实现可编程、可批量的生成管线。

• AI 应用
• 媒体生成