> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-zh/tu-xiang-sheng-cheng/stable-diffusion-3-5.md).

# Stable Diffusion 3.5

使用 Stable Diffusion 3.5 在 Clore.ai GPU 上生成高保真图像并准确渲染文本。

Stability AI 的 Stable Diffusion 3.5 是一个多模态扩散 Transformer（MMDiT），为开放权重图像生成设立了新标准。它有三个版本： **Large** （8B 参数）， **中等** （2.5B 参数），以及 **Large Turbo** （8B，经过 4 步推理蒸馏）。其突出特点是准确的文本渲染——SD 3.5 能够可靠地将可读文本放入生成图像中，而这是大多数早期模型都难以做到的能力。

在 [Clore.ai](https://clore.ai/) 你可以以低至 0.05 美元/小时的价格租用 SD 3.5 所需的 GPU 算力，每小时生成数百张图像。

## 主要特性

* **三个版本** —— Large（8B，最高质量）、Medium（2.5B，快速且轻量）、Large Turbo（8B，4 步蒸馏）。
* **准确的文本渲染** —— 在图像中生成可读文本、标牌、标签和排版。
* **MMDiT 架构** —— 图像-文本联合注意力，以实现更出色的提示词遵循。
* **1024×1024 原生分辨率** —— 无需放大技巧即可获得干净输出。
* **灵活的宽高比** —— 可处理非方形输出（768×1344、1344×768 等），且不损失质量。
* **原生支持 diffusers** — `StableDiffusion3Pipeline` 在 `diffusers >= 0.30`.
* **开源权重** —— Stability AI 社区许可；大多数商业用途免费。

## 需求

| 组件        | 最低            | 推荐                   |
| --------- | ------------- | -------------------- |
| GPU 显存    | 12 GB（Medium） | 24 GB（Large / Turbo） |
| 系统内存      | 16 GB         | 32 GB                |
| 磁盘        | 20 GB         | 40 GB                |
| Python    | 3.10+         | 3.11                 |
| CUDA      | 12.8+         | 12.8+                |
| diffusers | 0.30+         | 最新                   |

**Clore.ai GPU 推荐：** 一台 **RTX 4090** （24 GB，$0.14–0.42/小时）可全速运行所有三个版本。对于 Medium 模型， **RTX 3090** （24 GB，$0.07–0.21/小时）甚至 16 GB 显卡就足够，而且更便宜。

## 快速开始

```bash
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
pip install diffusers transformers accelerate sentencepiece protobuf

python -c "import torch; print(torch.cuda.get_device_name(0))"
```

## 使用示例

### SD 3.5 Large —— 最高质量

```python
import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large",
    torch_dtype=torch.bfloat16,
)
pipe.to("cuda")

image = pipe(
    prompt=(
        "一块风化的木牌，上面写着 '24小时营业'，悬挂在 "
        "霓虹灯照亮的餐馆外的一条生锈铁链，雨夜，反射 "
        "在湿漉漉的沥青路面上，电影感摄影"
    ),
    negative_prompt="模糊、变形的文字、低质量",
    guidance_scale=3.5,
    num_inference_steps=28,
    width=1024,
    height=1024,
    generator=torch.Generator("cuda").manual_seed(42),
).images[0]

image.save("diner_sign.png")
print("已保存 diner_sign.png")
```

### SD 3.5 Large Turbo —— 4 步快速生成

```python
import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large-turbo",
    torch_dtype=torch.bfloat16,
).to("cuda")

# Turbo 版本：只需 4 步，guidance_scale=0（蒸馏）
image = pipe(
    prompt="机械腕表机芯的微距照片，复杂齿轮，金色光线",
    guidance_scale=0.0,
    num_inference_steps=4,
    width=1024,
    height=1024,
).images[0]

image.save("watch_turbo.png")
```

### SD 3.5 Medium —— 轻量选项

```python
import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3.5-medium",
    torch_dtype=torch.float16,
).to("cuda")

image = pipe(
    prompt="温馨咖啡店内部的等距视图，像素艺术风格，暖色照明",
    guidance_scale=4.0,
    num_inference_steps=28,
    width=1024,
    height=1024,
).images[0]

image.save("coffee_shop_medium.png")
```

### 使用不同宽高比批量生成

```python
import torch
from diffusers import StableDiffusion3Pipeline

pipe = StableDiffusion3Pipeline.from_pretrained(
    "stabilityai/stable-diffusion-3.5-large",
    torch_dtype=torch.bfloat16,
).to("cuda")

jobs = [
    {"prompt": "一名宇航员站在向日葵花田中的肖像", "w": 768, "h": 1344},
    {"prompt": "冰岛高地的全景风光，阴沉的天空", "w": 1344, "h": 768},
    {"prompt": "大理石表面上香水瓶的产品照片", "w": 1024, "h": 1024},
]

for i, job in enumerate(jobs):
    img = pipe(
        prompt=job["prompt"],
        guidance_scale=3.5,
        num_inference_steps=28,
        width=job["w"],
        height=job["h"],
    ).images[0]
    img.save(f"batch_{i:03d}.png")
    print(f"[{i+1}/{len(jobs)}] {job['w']}x{job['h']} 已完成")
```

## 给 Clore.ai 用户的建议

1. **用于迭代用 Turbo，最终渲染用 Large** —— 使用 4 步 Turbo 版本快速探索提示词想法，然后切换到 Large（28 步）进行最终渲染。
2. **guidance\_scale=3.5** —— SD 3.5 Large 在较低的 CFG 下效果优于旧版 Stable Diffusion 模型。超过 5.0 往往会导致过度饱和。
3. **Turbo 需要 guidance\_scale=0** —— 蒸馏模型已经内置了引导；再额外添加会降低输出质量。
4. **图像中的文本** —— SD 3.5 的文本渲染能力很强，但并不完美。请用引号包住你想要的准确文本： `'24小时营业'`。保持简短（最多 3–5 个词）。
5. **缓存权重** ——将 `HF_HOME=/workspace/hf_cache` 到持久化存储中。Large 在磁盘上约占 16 GB。
6. **Large 用 bf16，Medium 用 fp16** —— 8B 模型以 bf16 训练；2.5B 的 Medium 在 fp16 下运行良好。
7. **高效批处理** —— 在 RTX 4090 上，SD 3.5 Large 生成一张 1024×1024 图像约需 3 秒。可通宵批量生成以实现大规模产出。
8. **接受 HF 许可** —— 在下载之前，你必须在 HuggingFace 模型页面上接受模型许可。使用 `huggingface-cli login`.

## 故障排查

| 问题                           | 修复                                                                                                     |
| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
| `OutOfMemoryError` 使用 Large  | 使用 `pipe.enable_model_cpu_offload()`；或者切换到 Medium 版本                                                   |
| 图像中文本乱码                      | 保持文本简短（3–5 个词）；在提示词中用引号括起来；提高 `推理步数` 到 35                                                              |
| 颜色过饱和                        | 将 `guidance_scale` —— Large 试试 2.5–3.5；Turbo 使用 0.0                                                    |
| 下载模型时出现 403 错误               | 在以下地址接受许可 `https://huggingface.co/stabilityai/stable-diffusion-3.5-large` 然后运行 `huggingface-cli login` |
| 首次运行较慢                       | 首次下载时 Large 约为 16 GB；后续运行将使用缓存                                                                         |
| `KeyError: 'text_encoder_3'` | 升级 diffusers： `pip install -U diffusers transformers`                                                  |
| 输出黑图                         | 确保 `torch_dtype=torch.bfloat16` 用于 Large/Turbo；fp32 在某些显卡上可能导致静默失败                                     |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/tu-xiang-sheng-cheng/stable-diffusion-3-5.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.