# 古诗词意境图生成器

基于 LLM 古诗词分析 + Z-Image-Turbo 本地文生图的自动化工具。

输入一首古诗词（唐诗、宋词、元曲等均可），LLM 会以「信、雅、达」的标准分析意境，自动选择最合适的中国传统画风，并拆解为多个画面。然后调用本地 Z-Image-Turbo 模型逐一生成高质量图片。

## 特性

- 支持唐诗、宋词、元曲等所有中国古典诗词体裁
- LLM 自动识别体裁并匹配最佳画风（水墨写意、青绿山水、工笔花鸟等 9 种风格）
- 可选加载 LoRA 增强特定画风（如水墨风 LoRA）
- Z-Image-Turbo 本地推理，16GB 显存即可运行

## 环境要求

- Python >= 3.10
- GPU（至少 16GB 显存），支持以下任一：
  - NVIDIA CUDA GPU
  - Intel Arc GPU（A770 等，通过 XPU 支持）
  - Apple Silicon（MPS）
- 兼容 OpenAI API 的 LLM 端点

## 安装

```bash
pip install -r requirements.txt
```

> diffusers 需要从源码安装（requirements.txt 已配置）。

### Intel Arc GPU 额外步骤

```bash
# 安装 Intel Extension for PyTorch
pip install intel-extension-for-pytorch
```

将 `config.yaml` 中的 `device` 设为 `"auto"` 或 `"xpu"` 即可自动适配。脚本会自动将数据类型切换为 `float16`（Intel Arc 对 bfloat16 兼容性不佳）。

## 配置

编辑 `config.yaml`：

| 配置项 | 说明 |
|--------|------|
| `llm.base_url` | LLM API 端点地址（兼容 OpenAI 格式） |
| `llm.api_key` | API 密钥（也可通过环境变量 `LLM_API_KEY` 设置） |
| `llm.model` | 模型名称 |
| `image.model_id` | Z-Image-Turbo 的 HuggingFace ID 或本地 HF 格式目录 |
| `image.comfyui.*` | ComfyUI 拆分文件路径（见下方说明） |
| `image.device` | 推理设备：`auto` / `cuda` / `xpu` / `mps` / `cpu` |
| `lora.enabled` | 是否启用 LoRA |
| `lora.path` | LoRA 文件路径（.safetensors） |
| `output.dir` | 图片输出目录 |

### 模型加载方式

支持两种模型来源，在 `config.yaml` 中二选一：

**方式一：HuggingFace 格式**（默认）

```yaml
image:
  model_id: "Tongyi-MAI/Z-Image-Turbo"   # 或本地 HF 格式目录
```

**方式二：ComfyUI 拆分文件**

如果你已通过 ComfyUI 下载了模型，直接填写三个文件的路径即可：

```yaml
image:
  comfyui:
    text_encoder: "/path/to/ComfyUI/models/text_encoders/qwen_3_4b.safetensors"
    transformer: "/path/to/ComfyUI/models/diffusion_models/z_image_turbo_bf16.safetensors"
    vae: "/path/to/ComfyUI/models/vae/ae.safetensors"
```

> 首次运行 ComfyUI 模式时，脚本会自动从 HuggingFace 下载微型配置文件（< 100KB），之后自动缓存。

### LoRA 推荐

| LoRA | 风格 | 触发词 | 权重 | 来源 |
|------|------|--------|------|------|
| zyd232's Ink Style v1.2 | 水墨写意 | `ink style` | 0.6-1.2 | Civitai |
| Painterly - CE | 水彩/油画 | - | 0.8 | Civitai |

## 使用方法

### 交互式输入

```bash
python poetry_to_image.py
```

运行后按提示输入古诗词，输入空行结束。

### 命令行直接传入

```bash
# 唐诗
python poetry_to_image.py -p "床前明月光，疑是地上霜。举头望明月，低头思故乡。"

# 宋词
python poetry_to_image.py -p "明月几时有？把酒问青天。不知天上宫阙，今夕是何年。"
```

### 仅分析不生成图片

```bash
python poetry_to_image.py -p "大漠孤烟直，长河落日圆。" --analyze-only
```

### 指定配置文件和输出目录

```bash
python poetry_to_image.py -c my_config.yaml -o ./my_output -p "春江潮水连海平，海上明月共潮生。"
```

## 输出

- `output/poem_01.png` ... `poem_N.png` — 生成的图片
- `output/poem_01_prompt.txt` ... — 每张图片的 prompt 与画风记录
- `output/analysis.json` — LLM 完整分析结果（含体裁识别、风格选择）

## 工作流程

```
古诗词输入 → LLM 体裁识别 → 意境分析 & 画风匹配 → 生成 prompt → [可选 LoRA 增强] → Z-Image-Turbo 逐一生图 → 输出
```

## 支持的画风

LLM 会根据诗意自动选择：

| 画风 | 适用场景 |
|------|---------|
| 水墨写意 | 山水、边塞、禅意 |
| 青绿山水 | 春夏山水、壮丽河山 |
| 工笔花鸟 | 花卉、仕女、精致细腻 |
| 工笔重彩 | 华丽、宫廷、历史叙事 |
| 没骨画法 | 花卉、蔬果、清新淡雅 |
| 文人画 | 隐逸、高洁、书卷气 |
| 泼墨大写意 | 豪放、苍茫、气势磅礴 |
| 界画 | 楼阁、宫殿、城市 |
| 浅绛山水 | 秋冬山水、怀古 |