README.md

---
license: apache-2.0
library_name: transformers
pipeline_tag: image-text-to-text
tags:
  - anime
  - image-to-prompt
  - image-tagging
  - danbooru
  - qwen3.5
  - vision-language
---

# Anime_Image2Prompt

[English](#english) | [中文说明](#中文说明)

## English

### Model overview

**Anime_Image2Prompt** is a Qwen3.5-2B-based vision-language model that converts a single anime, illustration, or anime-style image into Danbooru-style prompt tags. It separates general visual attributes, character identities, and copyrights/franchises, making it useful for image organization, dataset annotation, and prompt extraction in generative-image workflows.

The repository contains all weights required for inference; no base model or separate adapter is needed. The model is stored in BF16, occupies approximately 4.12 GiB, and has 2,213,241,664 parameters. The included program loads local files from this directory by default.

### Original-to-regeneration comparison

The following two pairs demonstrate the complete workflow. `01.png` and `02.png` are the original images. Each original was processed by **Anime_Image2Prompt**, and the extracted prompt was passed without manual rewriting directly to [WAI-illustrious-SDXL v15.0](https://civitai.red/models/827184/wai-illustrious-sdxl?modelVersionId=2167369). The resulting images are `01-regen.png` and `02-regen.png`, respectively.

<table>
  <tr>
    <th width="50%">01 · Original</th>
    <th width="50%">01 · Prompt regeneration</th>
  </tr>
  <tr>
    <td><img src="images/01.png" alt="Example 01 original" width="100%"></td>
    <td><img src="images/01-regen.png" alt="Example 01 prompt regeneration" width="100%"></td>
  </tr>
  <tr>
    <th width="50%">02 · Original</th>
    <th width="50%">02 · Prompt regeneration</th>
  </tr>
  <tr>
    <td><img src="images/02.png" alt="Example 02 original" width="100%"></td>
    <td><img src="images/02-regen.png" alt="Example 02 prompt regeneration" width="100%"></td>
  </tr>
</table>

These examples illustrate how the model captures major semantics such as character identity, clothing, scene, and composition. Prompt regeneration is not image-to-image or pixel-level reconstruction; the final image also depends on the generation model, random seed, and sampling settings.

### Output format

The model's native output is a fixed JSON object:

```json
{
  "general_tags": ["1girl,long hair,blue eyes"],
  "character_tags": ["example character"],
  "copyright_tags": ["example copyright"]
}
```

- `general_tags`: counts, appearance, clothing, actions, composition, and scene attributes.
- `character_tags`: character names recognized by the model.
- `copyright_tags`: recognized works or franchises.
- Each non-empty category contains one comma-separated string. An unknown category is returned as an empty array, `[]`.

The included program can also combine all categories into a flat prompt:

```text
1girl, long hair, blue eyes, example character, example copyright
```

### Requirements

- Python 3.10 or newer; Python 3.11 is recommended.
- An NVIDIA GPU with at least 8 GB of VRAM is recommended. More VRAM provides additional headroom.
- CPU inference is supported but slow; at least 16 GB of system RAM is recommended.
- The weight file is larger than 4 GB. Use a large-file-capable filesystem such as NTFS, exFAT, APFS, or ext4 instead of FAT32.

### Installation

Create a virtual environment inside the model directory:

```bash
python -m venv .venv
```

Windows PowerShell:

```powershell
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

Linux / macOS:

```bash
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

If you need a specific CUDA build, install the PyTorch build matching your GPU driver from the [official PyTorch selector](https://pytorch.org/get-started/locally/) before installing the remaining requirements.

### Quick start

The script resides beside the model files, so no model path is required:

```bash
python inference.py /path/to/image.png
```

The default output is structured JSON. Save it to a file with:

```bash
python inference.py /path/to/image.png --output result.json
```

Print a flat, copy-ready prompt instead:

```bash
python inference.py /path/to/image.png --format prompt
```

Useful options:

```bash
# Force CPU inference
python inference.py image.png --device cpu

# Reduce image tokens and peak VRAM usage
python inference.py image.png --low-vram

# Show every option
python inference.py --help
```

The program applies EXIF orientation and RGB conversion automatically and accepts common image formats supported by Pillow. Model loading uses `local_files_only=True`, so it does not download additional weights.

### Python API

```python
from inference import AnimeImage2Prompt

tagger = AnimeImage2Prompt()
result = tagger.predict("image.png")

print(result)
print(tagger.to_prompt(result))
```

Reuse the same `AnimeImage2Prompt` instance for multiple images to avoid reloading the model.

### Limitations

- The model is intended primarily for anime and illustration images. Performance may degrade on photographs or images far outside its training distribution.
- Tags are not guaranteed to be exhaustive or correct. Character and franchise recognition can be especially uncertain.
- The model may return tags describing sensitive content. Apply content filtering appropriate to your use case and follow applicable laws and platform policies.
- Do not use the model as the sole basis for safety moderation, identity decisions, or other high-impact decisions.

### License

This repository is released under the Apache License 2.0. See [`LICENSE`](LICENSE) for details.

---

## 中文说明

### 模型简介

**Anime_Image2Prompt** 是一个基于 Qwen3.5-2B 的动漫图像理解模型，可将单张动漫、插画或二次元风格图片转换为 Danbooru 风格的提示词。模型会分别识别画面通用特征、角色名称和作品来源，适合用于图片归档、数据集标注和生成式图像工作流中的提示词提取。

模型权重已完整包含在本仓库中，无需额外下载基础模型或适配器。权重以 BF16 保存，约 4.12 GiB，共 2,213,241,664 个参数。推理程序默认只读取当前目录中的本地文件。

### 原图与提示词重绘对比

下面展示两组端到端效果对比。`01.png` 和 `02.png` 是原图；处理流程为：将原图输入 **Anime_Image2Prompt**，把模型提取出的提示词不经人工改写，直接交给 [WAI-illustrious-SDXL v15.0](https://civitai.red/models/827184/wai-illustrious-sdxl?modelVersionId=2167369) 绘制，对应结果分别为 `01-regen.png` 和 `02-regen.png`。

<table>
  <tr>
    <th width="50%">01 · 原图</th>
    <th width="50%">01 · 提示词重绘</th>
  </tr>
  <tr>
    <td><img src="images/01.png" alt="示例 01 原图" width="100%"></td>
    <td><img src="images/01-regen.png" alt="示例 01 提示词重绘结果" width="100%"></td>
  </tr>
  <tr>
    <th width="50%">02 · 原图</th>
    <th width="50%">02 · 提示词重绘</th>
  </tr>
  <tr>
    <td><img src="images/02.png" alt="示例 02 原图" width="100%"></td>
    <td><img src="images/02-regen.png" alt="示例 02 提示词重绘结果" width="100%"></td>
  </tr>
</table>

这些示例用于观察模型对角色、服饰、场景和构图等主要语义的提取能力。提示词重绘并非图生图或像素级复刻，具体画面仍会受到绘图模型、随机种子和采样参数影响。

### 输出格式

模型原生输出固定为 JSON：

```json
{
  "general_tags": ["1girl,long hair,blue eyes"],
  "character_tags": ["example character"],
  "copyright_tags": ["example copyright"]
}
```

- `general_tags`：人物数量、外观、服饰、动作、构图和场景等通用标签。
- `character_tags`：模型能够识别的角色名称。
- `copyright_tags`：模型能够识别的作品或系列名称。
- 每个非空类别包含一个以英文逗号连接的字符串；无法识别时返回空数组 `[]`。

随附程序也可以把三个类别合并为常用的扁平提示词：

```text
1girl, long hair, blue eyes, example character, example copyright
```

### 环境要求

- Python 3.10 或更高版本，推荐 Python 3.11。
- 推荐使用具有 8 GB 或更多显存的 NVIDIA GPU；显存越大，运行越稳定。
- CPU 可以运行，但速度较慢，建议至少准备 16 GB 系统内存。
- 模型文件大于 4 GB，请使用 NTFS、exFAT、APFS、ext4 等支持大文件的文件系统，不要使用 FAT32。

### 安装

在模型目录中创建虚拟环境并安装依赖：

```bash
python -m venv .venv
```

Windows PowerShell：

```powershell
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

Linux / macOS：

```bash
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```

如果需要特定 CUDA 版本，请先按照 [PyTorch 官方安装说明](https://pytorch.org/get-started/locally/) 安装与显卡驱动匹配的 PyTorch，再执行依赖安装命令。

### 快速使用

推理脚本与模型放在同一目录，因此无需填写模型路径：

```bash
python inference.py /path/to/image.png
```

默认在终端输出结构化 JSON。保存结果：

```bash
python inference.py /path/to/image.png --output result.json
```

直接输出可复制的扁平提示词：

```bash
python inference.py /path/to/image.png --format prompt
```

常用选项：

```bash
# 强制使用 CPU
python inference.py image.png --device cpu

# 降低图像 token 数以减少峰值显存占用
python inference.py image.png --low-vram

# 查看全部参数
python inference.py --help
```

程序会自动处理图片的 EXIF 方向并转换为 RGB，支持 Pillow 可读取的常见图片格式。加载模型时使用 `local_files_only=True`，不会联网下载其他权重。

### Python 调用

```python
from inference import AnimeImage2Prompt

tagger = AnimeImage2Prompt()
result = tagger.predict("image.png")

print(result)
print(tagger.to_prompt(result))
```

同一个 `AnimeImage2Prompt` 实例可连续处理多张图片，模型只会加载一次。

### 使用限制

- 本模型主要面向动漫和插画图片，真实照片或与训练分布差异较大的图片可能表现较差。
- 标签并不保证完整或完全准确，角色与作品来源尤其可能发生误识别。
- 模型可能输出敏感内容标签。使用者应根据应用场景进行内容过滤，并遵守当地法律及平台规则。
- 本模型不应作为安全审核、身份判断或其他高风险决策的唯一依据。

### 许可证

本仓库依据 Apache License 2.0 发布，详情见 [`LICENSE`](LICENSE)。