风格化头像生成器 — Z-Image-Turbo + OpenVINO

基于 modelscope-workshop 项目，使用 OpenVINO 运行 Z-Image-Turbo，根据文字描述生成多种风格的头像图片。

前置条件

• 虚拟环境已激活：source ~/modelscope-workshop/ov_workshop/bin/activate
• 模型目录存在：~/modelscope-workshop/lab4-image-generation/Z-Image-Turbo-int4-ov/

---

加载模型

import os
from optimum.intel import OVZImagePipeline

model_dir = os.path.expanduser("~/modelscope-workshop/lab4-image-generation/Z-Image-Turbo-int4-ov")

ov_pipe = OVZImagePipeline.from_pretrained(model_dir, device="CPU")
print("✅ 模型加载完成")

若模型不存在，先下载：

from pathlib import Path
from modelscope import snapshot_download
model_dir = Path("~/modelscope-workshop/lab4-image-generation/Z-Image-Turbo-int4-ov").expanduser()
if not model_dir.exists():
 snapshot_download("snake7gun/Z-Image-Turbo-int4-ov", local_dir=str(model_dir))

设备可选 CPU、GPU、AUTO，默认 CPU 兼容性最好。

---

风格化头像生成

核心函数

import torch
from typing import Tuple
from PIL import Image

STYLE_TEMPLATES = {
    "写实证件风": "clean studio portrait, natural skin texture, sharp focus, soft key light, neutral background",
    "国风古装": "traditional Chinese hanfu portrait, elegant headpiece, cinematic lighting, rich textile details",
    "二次元插画": "anime portrait, clean line art, vivid color palette, expressive eyes, high detail",
    "赛博朋克": "cyberpunk portrait, neon rim light, futuristic accessories, moody atmosphere",
    "油画艺术": "oil painting portrait, visible brush strokes, museum grade color harmony, artistic texture",
}


def build_avatar_prompt(
    subject: str,
    style_name: str,
    mood: str,
    background: str,
    extra_prompt: str = "",
) -> str:
    """拼装头像生成提示词。"""
    style_prompt = STYLE_TEMPLATES.get(style_name, STYLE_TEMPLATES["写实证件风"])
    parts = [
        f"Portrait of {subject}",
        style_prompt,
        f"mood: {mood}",
        f"background: {background}",
        "head and shoulders framing, centered composition, high quality",
        extra_prompt.strip(),
    ]
    return ", ".join([p for p in parts if p])


def generate_avatar(
    subject: str,
    style_name: str,
    mood: str = "confident",
    background: str = "simple gradient",
    extra_prompt: str = "",
    width: int = 512,
    height: int = 512,
    steps: int = 9,
    seed: int = 42,
) -> Tuple[Image.Image, str]:
    """风格化头像生成：输入主体描述和风格，输出头像图片及最终提示词。"""
    prompt = build_avatar_prompt(subject, style_name, mood, background, extra_prompt)
    image = ov_pipe(
        prompt=prompt,
        height=height,
        width=width,
        num_inference_steps=steps,
        guidance_scale=0.0,
        generator=torch.Generator("cpu").manual_seed(int(seed)),
    ).images[0]
    return image, prompt

使用示例

# 生成国风古装头像
image, prompt = generate_avatar(
    subject="a young woman",
    style_name="国风古装",
    mood="calm and elegant",
    background="misty garden at dusk",
    extra_prompt="high detail face, natural beauty",
    width=512,
    height=512,
    steps=9,
    seed=42,
)
print(prompt)
image.save("avatar_guofeng.png")

# 生成赛博朋克头像
image, prompt = generate_avatar(
    subject="a male hacker",
    style_name="赛博朋克",
    mood="mysterious",
    background="neon city street",
)

# 查看所有可用风格
print(list(STYLE_TEMPLATES.keys()))
# → ["写实证件风", "国风古装", "二次元插画", "赛博朋克", "油画艺术"]

---

Gradio 交互式演示

import random
import gradio as gr


def generate_avatar_for_ui(subject, style_name, mood, background, extra_prompt, resolution, steps, seed, random_seed):
    if random_seed:
        seed = random.randint(1, 1_000_000)

    width, height = [int(x) for x in resolution.split("x")]
    image, final_prompt = generate_avatar(
        subject=subject,
        style_name=style_name,
        mood=mood,
        background=background,
        extra_prompt=extra_prompt,
        width=width,
        height=height,
        steps=int(steps),
        seed=int(seed),
    )
    return image, final_prompt, int(seed)


with gr.Blocks(title="Stylized Avatar App") as demo:
    gr.Markdown("# 风格化头像应用 (Z-Image-Turbo + OpenVINO)")
    with gr.Row():
        with gr.Column(scale=1):
            subject = gr.Textbox(label="主体描述", value="a young professional", lines=1)
            style_name = gr.Dropdown(label="风格", choices=list(STYLE_TEMPLATES.keys()), value="写实证件风")
            mood = gr.Textbox(label="情绪/氛围", value="confident and friendly", lines=1)
            background = gr.Textbox(label="背景", value="clean studio background", lines=1)
            extra_prompt = gr.Textbox(label="附加提示词", placeholder="例如：wearing glasses, soft smile", lines=2)

            with gr.Row():
                resolution = gr.Dropdown(label="分辨率", choices=["512x512", "768x768", "512x768", "768x512"], value="512x512")
                steps = gr.Slider(label="推理步数", minimum=1, maximum=20, step=1, value=9)

            with gr.Row():
                seed = gr.Number(label="Seed", value=42, precision=0)
                random_seed = gr.Checkbox(label="随机 Seed", value=True)

            run_btn = gr.Button("生成头像", variant="primary")

        with gr.Column(scale=1):
            out_img = gr.Image(label="生成结果", type="pil")
            out_prompt = gr.Textbox(label="最终提示词", lines=5)
            used_seed = gr.Number(label="本次 Seed", precision=0)

    run_btn.click(
        generate_avatar_for_ui,
        inputs=[subject, style_name, mood, background, extra_prompt, resolution, steps, seed, random_seed],
        outputs=[out_img, out_prompt, used_seed],
    )

demo.launch(share=False)   # 浏览器打开 http://127.0.0.1:7860

---

参数说明

generate_avatar 参数

| 参数 | 类型 | 默认值 | 说明 | | -------------- | ------ | ------------------- | ---------------------------------- | | subject | string | — | 主体描述，如 "a young woman" | | style_name | string | — | 风格名称，可选见下方风格列表 | | mood | string | "confident" | 情绪/氛围描述 | | background | string | "simple gradient" | 背景描述 | | extra_prompt | string | "" | 附加提示词 | | width | int | 512 | 图片宽度 | | height | int | 512 | 图片高度 | | steps | int | 9 | 推理步数（1~20，越大越精细但越慢） | | seed | int | 42 | 随机种子，相同种子生成相同图片 |

可用风格

| 风格名称 | 英文关键词 | 效果 | | ------------ | ------------------------- | ------------------------ | | 写实证件风 | clean studio portrait | 自然肤色、柔光、简洁背景 | | 国风古装 | traditional Chinese hanfu | 汉服、头饰、电影级光影 | | 二次元插画 | anime portrait | 动漫线条、鲜艳配色、大眼 | | 赛博朋克 | cyberpunk portrait | 霓虹边光、未来配饰、暗调 | | 油画艺术 | oil painting portrait | 笔触肌理、美术馆级配色 |

---

常见错误排查

| 错误 | 原因 | 解决方法 | | ------------------------------ | --------------- | ---------------------------------------- | | FileNotFoundError: model_dir | 模型未下载 | 确认模型目录路径正确，或运行上方下载代码 | | 生成图片模糊 | 推理步数太少 | 调大 steps（推荐 9~12） | | 生成速度慢 | 使用 CPU 推理 | 切换 device="GPU" 或 "AUTO" | | Gradio 端口占用 | 7860 端口被占用 | demo.launch(server_port=7861) |