本地图像与视频生成模型部署与调用教程

nvidia-smi

# 创建并激活 conda 环境
conda create -n generation python=3.10 -y
conda activate generation

# 安装 uv（Python 包管理工具）
pip install uv

# 方法一：阿里云镜像直链（国内推荐）
uv pip install "https://mirrors.aliyun.com/pytorch-wheels/cu128/torch-2.8.0%2Bcu128-cp310-cp310-win_amd64.whl" "https://mirrors.aliyun.com/pytorch-wheels/cu128/torchvision-0.23.0%2Bcu128-cp310-cp310-win_amd64.whl"

# 方法二：PyTorch 官方源
uv pip install torch==2.8.0 torchvision --index-url https://download.pytorch.org/whl/cu128

import torch
print(torch.__version__)
print(f"CUDA available: {torch.cuda.is_available()}")
print(f"Device name: {torch.cuda.get_device_name(0)}")

cd generation-service
uv pip install -r requirements.txt --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 安装 modelscope 命令行工具（用于下载模型权重）
uv pip install modelscope --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# Windows PowerShell 设置 HF 镜像
$env:HF_ENDPOINT = "https://hf-mirror.com"

modelscope download --model AI-ModelScope/stable-diffusion-xl-base-1.0 --local_dir C:/models/sdxl-base

modelscope download --model AI-ModelScope/stable-diffusion-v1-5 --local_dir C:/models/sd15

modelscope download --model AI-ModelScope/LTX-Video --local_dir C:/models/ltx-video

modelscope download --model Wan-AI/Wan2.1-T2V-1.3B-Diffusers --local_dir C:/models/wan-t2v-1.3b

from diffusers import StableDiffusionXLPipeline
import torch

# 加载 SDXL 底模（本地目录 C:/models/sdxl-base）
pipe = StableDiffusionXLPipeline.from_pretrained(
    "C:/models/sdxl-base",
    torch_dtype=torch.float16,   # 半精度推理，节省显存
    use_safetensors=True,
)
pipe.enable_model_cpu_offload()  # 显存不足时自动卸载部分层到内存

image = pipe(
    prompt="a shiba inu wearing an astronaut helmet, high quality, photorealistic",   # 中文：一只戴着宇航员头盔的柴犬，高质量，写实风格
    negative_prompt="blurry, low quality, deformed",   # 中文：模糊，低质量，变形
    num_inference_steps=30,
    guidance_scale=7.5,
).images[0]

image.save("sdxl_dog.png")

from diffusers import StableDiffusionPipeline
import torch

pipe = StableDiffusionPipeline.from_pretrained(
    "C:/models/sd15",
    torch_dtype=torch.float16,
    use_safetensors=True,
)
pipe.enable_model_cpu_offload()

image = pipe(prompt="a shiba inu, high quality", num_inference_steps=30).images[0]   # 中文：一只柴犬，高质量
image.save("sd15_dog.png")

from diffusers import LTXPipeline
import torch

# 加载 LTX-Video 2B（本地目录 C:/models/ltx-video）
pipe = LTXPipeline.from_pretrained(
    "C:/models/ltx-video",
    torch_dtype=torch.bfloat16,   # 训练原生精度 bf16（RTX 20 系列改 fp16，见 4.3 提示）
)
pipe.enable_model_cpu_offload()  # 适配 8GB 显存

output = pipe(
    prompt="a golden retriever running on the grass",   # 中文：一只在草地上奔跑的金毛犬
    negative_prompt="blurry, low quality, broken motion",   # 中文：模糊，低质量，动作不连贯
    num_frames=121,          # LTX-Video 原生 121 帧
    guidance_scale=3.0,      # LTX 引导强度取值通常较小
    num_inference_steps=50,
    output_type="pil",       # 直接返回 PIL 帧列表，便于后续导出 GIF
)
frames = output.frames[0]   # 取第 0 组视频帧

from diffusers import WanPipeline
import torch

pipe = WanPipeline.from_pretrained(
    "C:/models/wan-t2v-1.3b",
    torch_dtype=torch.bfloat16,
)
pipe.enable_model_cpu_offload()

output = pipe(
    prompt="一只在草地上奔跑的金毛犬",
    negative_prompt="模糊，低质量，动作不连贯",
    num_frames=81,           # Wan2.1 默认 81 帧
    guidance_scale=5.0,
    num_inference_steps=50,
    output_type="pil",       # Wan 需显式指定返回 PIL 帧列表（LTX 默认即为 pil）
)
frames = output.frames[0]

torch.backends.cuda.enable_flash_sdp(False)
torch.backends.cuda.enable_math_sdp(False)
pipe = WanPipeline.from_pretrained("C:/models/wan-t2v-1.3b", torch_dtype=torch.float16)

from diffusers.utils import export_to_gif

# 导出为 GIF，fps 控制每秒播放帧数
export_to_gif(frames, "output_video.gif", fps=24)
print(f"已生成 {len(frames)} 帧视频")

# 仅 LTX / Wan 支持调大提示词长度
output = pipe(prompt=prompt, ..., max_sequence_length=1024)

generation-service/
├── config.py                  # 服务配置（端口、模型路径、默认参数）
├── img_gen.py                 # 图像生成服务（SDXL / SD1.5 封装）
├── video_gen.py               # 视频生成服务（LTX-Video / Wan2.1 封装）
├── main.py                    # FastAPI 后端，生成接口
├── cli.py                     # 命令行工具（子命令）
├── client.py                  # 客户端调用示例
├── requirements.txt           # 依赖管理
├── README.md                  # 项目说明
└── static/
    └── index.html             # 前端验证页面（浏览器访问 /）

# config.py（核心片段，完整代码请查看 generation-service/config.py）
PORT = 8000
DEVICE = "cuda"                # 推理设备：cuda / cpu

# 图像模型类型：sdxl（16GB 显存推荐）/ sd15（8GB 显存推荐）
IMG_MODEL_TYPE = "sdxl"

# 视频模型类型：ltx（LTX-Video 2B，8GB 显存即可）/ wan（Wan2.1-T2V-1.3B，16GB 推荐）
VIDEO_MODEL_TYPE = "ltx"

# 模型本地目录
IMG_SDXL_DIR = "C:/models/sdxl-base"         # SDXL 底模
IMG_SD15_DIR = "C:/models/sd15"              # SD1.5 底模
LTX_MODEL_DIR = "C:/models/ltx-video"        # LTX-Video 2B
WAN_MODEL_DIR = "C:/models/wan-t2v-1.3b"     # Wan2.1-T2V-1.3B

DEFAULT_STEPS = 30
DEFAULT_GUIDANCE = 7.5

# img_gen.py（核心片段，完整代码请查看 generation-service/img_gen.py）
class ImageGenerator:
    def __init__(self, model_type="sdxl", device=DEVICE):
        self.model_type = model_type
        self.device = device
        self.pipe = None

    def load(self):
        """首次调用时加载对应底模管线。"""
        dtype = torch.float16 if self.device == "cuda" else torch.float32
        if self.model_type == "sdxl":
            self.pipe = StableDiffusionXLPipeline.from_pretrained(
                IMG_SDXL_DIR, torch_dtype=dtype, use_safetensors=True)
        else:
            self.pipe = StableDiffusionPipeline.from_pretrained(
                IMG_SD15_DIR, torch_dtype=dtype, use_safetensors=True)
        if self.device == "cuda":
            self.pipe.enable_model_cpu_offload()
        else:
            self.pipe.to(self.device)
        return self

    def text_to_image(self, prompt, negative_prompt="", steps=DEFAULT_STEPS,
                      guidance=DEFAULT_GUIDANCE, width=None, height=None, seed=None):
        """文本生成图像，返回 PIL.Image 对象。"""
        ...

# video_gen.py（核心片段，完整代码请查看 generation-service/video_gen.py）
# 各视频模型的推荐帧数、帧率与引导强度
MODEL_DEFAULTS = {
    "ltx": {"frames": 121, "fps": 24, "guidance": 3.0},   # LTX-Video 原生 24fps
    "wan": {"frames": 81, "fps": 16, "guidance": 5.0},    # Wan2.1 原生 16fps
}

class VideoGenerator:
    def load(self):
        """首次调用时加载对应视频管线。"""
        if self.device == "cuda":
            # RTX 20 系列（Turing）无 FlashAttention，且 memory-efficient 内核
            # 在 Turing 上不支持 bf16，bf16 会让 SDPA 回退到 math 后端物化完整
            # attention 矩阵，Wan 视频序列较长时极易 OOM，需改用 fp16 并强制
            # memory-efficient 后端；更新的显卡保持 bf16（flash 自动生效）。
            if torch.cuda.get_device_capability(0)[0] < 8:
                dtype = torch.float16
                torch.backends.cuda.enable_flash_sdp(False)
                torch.backends.cuda.enable_math_sdp(False)
            else:
                dtype = torch.bfloat16
        else:
            dtype = torch.bfloat16
        if self.model_type == "ltx":
            self.pipe = LTXPipeline.from_pretrained(LTX_MODEL_DIR, torch_dtype=dtype)
        else:
            self.pipe = WanPipeline.from_pretrained(WAN_MODEL_DIR, torch_dtype=dtype)
        if self.device == "cuda":
            self.pipe.enable_model_cpu_offload()
            # VAE 解码切片 + 分块，降低视频解码阶段显存峰值
            self.pipe.vae.enable_slicing()
            self.pipe.vae.enable_tiling()
        else:
            self.pipe.to(self.device)
        return self

    def text_to_video(self, prompt, negative_prompt="", num_frames=None, steps=DEFAULT_STEPS,
                      guidance=None, fps=None, seed=None, output="output_video.gif"):
        """文本生成视频，返回 GIF 文件路径。"""
        ...
        result = self.pipe(
            prompt=prompt,
            negative_prompt=negative_prompt,
            num_frames=num_frames,
            num_inference_steps=steps,
            guidance_scale=guidance,
            generator=gen,
            output_type="pil",   # 直接返回 PIL 帧列表，供 export_to_gif 导出
        )
        frames = result.frames[0]
        ...   # 兜底：旧版 diffusers 可能返回 numpy/Tensor 帧，转成 PIL
        export_to_gif(frames, output, fps=fps)
        return output

# main.py（核心片段，完整代码请查看 generation-service/main.py）
@app.post("/api/image/generate")
async def generate_image(req: ImageRequest):
    """接收提示词，按 model 选择底模，生成并返回一张图像。"""
    gen = get_image_gen(req.model)
    img = gen.text_to_image(
        req.prompt, req.negative_prompt, req.steps, req.guidance,
        req.width, req.height, req.seed,
    )
    path = os.path.join(tempfile.gettempdir(), "generated_image.png")
    img.save(path)
    return FileResponse(path, media_type="image/png")

@app.post("/api/video/generate")
async def generate_video(req: VideoRequest):
    """接收提示词，按 model 选择视频模型，生成并返回一段 GIF 视频。"""
    gen = get_video_gen(req.model)
    path = gen.text_to_video(
        req.prompt, req.negative_prompt, req.num_frames,
        req.steps, req.guidance, req.fps, req.seed,
    )
    return FileResponse(path, media_type="image/gif")

# 生成图像（默认 SDXL，16GB 显存）—— 中文：一只柴犬，写实风格
python cli.py image --prompt "a shiba inu, photorealistic" --output dog.png

# 8GB 显存改用 SD1.5 —— 中文：一只柴犬
python cli.py image --prompt "a shiba inu" --model sd15

# 生成视频（默认 LTX-Video）—— 中文：一只在草地上奔跑的金毛犬
python cli.py video --prompt "a golden retriever running on the grass"

# 16GB 显存改用 Wan2.1 —— Wan 支持中文提示词，无需翻译
python cli.py video --prompt "一只在草地上奔跑的金毛犬" --model wan --fps 30

# client.py（核心片段，完整代码请查看 generation-service/client.py）
def generate_image(prompt, out="client_image.png"):
    """调用图像生成接口并保存结果。"""
    resp = requests.post(f"{BASE_URL}/api/image/generate", json={"prompt": prompt})
    resp.raise_for_status()
    with open(out, "wb") as f:
        f.write(resp.content)
    print(f"图像已保存: {out}")

def generate_video(prompt, out="client_video.gif"):
    """调用视频生成接口并保存结果。"""
    resp = requests.post(f"{BASE_URL}/api/video/generate", json={"prompt": prompt})
    resp.raise_for_status()
    with open(out, "wb") as f:
        f.write(resp.content)
    print(f"视频已保存: {out}")

conda activate generation
cd generation-service
uv pip install -r requirements.txt --index-url https://pypi.tuna.tsinghua.edu.cn/simple

python cli.py image --prompt "a shiba inu, photorealistic" --output dog.png   # 中文：一只柴犬，写实风格

python cli.py video --prompt "a golden retriever running on the grass"   # 中文：一只在草地上奔跑的金毛犬

python main.py

python client.py

curl.exe -X POST http://127.0.0.1:8000/api/image/generate -H "Content-Type: application/json" -d "{\"model\":\"sdxl\",\"prompt\":\"a cat, high quality\"}" --output cat.png   # 中文：一只猫，高清