# 文本反转

Textual Inversion 是一种通过从少量示例图像中学习新的文本嵌入来个性化模型的训练方法。训练生成的文件极小（仅几 KB），并且可以将新的嵌入加载到文本编码器中。

`TextualInversionLoaderMixin` 提供了一个函数，用于从 Diffusers 和 Automatic1111 加载 Textual Inversion 嵌入到文本编码器中，并加载一个特殊标记以激活这些嵌入。

> [!TIP]
> 要了解如何加载 Textual Inversion 嵌入，请参阅 [Textual Inversion](../../using-diffusers/legacy_adapters#textual-inversion) 加载指南。

## TextualInversionLoaderMixin[[diffusers.loaders.TextualInversionLoaderMixin]]

#### diffusers.loaders.TextualInversionLoaderMixin[[diffusers.loaders.TextualInversionLoaderMixin]]

```python
diffusers.loaders.TextualInversionLoaderMixin()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/textual_inversion.py#L118)

将 Textual Inversion 的 token 和嵌入加载到 tokenizer 和文本编码器中。

#### load_textual_inversion[[diffusers.loaders.TextualInversionLoaderMixin.load_textual_inversion]]

```python
load_textual_inversion(pretrained_model_name_or_path: str | list[str] | dict[str, torch.Tensor] | list[dict[str, torch.Tensor]], token: str | list[str] | None = None, tokenizer: 'PreTrainedTokenizer' | None = None, text_encoder: 'PreTrainedModel' | None = None, **kwargs)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/textual_inversion.py#L271)

**参数：**

pretrained_model_name_or_path (`str` 或 `os.PathLike` 或 `list[str or os.PathLike]` 或 `Dict` 或 `list[Dict]`) : 可以是以下其中一种，也可以是它们的列表： - 一个字符串，即托管在 Hub 上的预训练模型的 *model id*（例如 `sd-concepts-library/low-poly-hd-logos-icons`）。 - 指向包含文本反转（textual inversion）权重的*目录*的路径（例如 `./my_text_inversion_directory/`）。 - 指向包含文本反转权重的*文件*的路径（例如 `./my_text_inversions.pt`）。 - 一个 [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict)。

token (`str` 或 `list[str]`，*可选*) : 用于覆盖文本反转权重所使用的 token。如果 `pretrained_model_name_or_path` 是一个列表，则 `token` 也必须是一个长度相等的列表。

text_encoder ([CLIPTextModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTextModel)，*可选*)：冻结的文本编码器（[clip-vit-large-patch14](https://huggingface.co/openai/clip-vit-large-patch14)）。如果未指定，函数将使用 self.tokenizer。

tokenizer ([CLIPTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/clip#transformers.CLIPTokenizer)，*可选*)：用于对文本进行分词的 `CLIPTokenizer`。如果未指定，函数将使用 self.tokenizer。

weight_name (`str`, *可选*) : 自定义权重文件的名称。在以下情况下应使用此参数： - 保存的文本反转文件采用 🤗 Diffusers 格式，但保存时使用了特定的权重名称，例如 `text_inv.bin`。 - 保存的文本反转文件采用 Automatic1111 格式。

cache_dir (`str | os.PathLike`，*可选*)：如果未使用标准缓存，则已下载的预训练模型配置将缓存到的目录路径。

force_download (`bool`，*可选*，默认为 `False`)：是否强制（重新）下载模型权重和配置文件，如果存在缓存版本则覆盖它们。

proxies (`dict[str, str]`，*可选*)：一个字典，用于按协议或端点指定要使用的代理服务器，例如 `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`。每次请求都会使用这些代理。

local_files_only (`bool`，*可选*，默认为 `False`)：是否仅加载本地模型权重和配置文件。如果设置为 `True`，则不会从 Hub 下载模型。

hf_token (`str` 或 *bool*，*可选*) : 用于远程文件的 HTTP 承载者授权令牌。如果为 `True`，则使用由 `diffusers-cli login` 生成的令牌（存储在 `~/.huggingface` 中）。

revision (`str`，*可选*，默认为 `"main"`)：要使用的特定模型版本。它可以是分支名称、标签名称、提交 ID，或 Git 允许的任何标识符。

subfolder (`str`，*可选*，默认为 `""`)：模型文件在 Hub 或本地的大型模型仓库中的子文件夹位置。

mirror (`str`, *可选*) : 用于解决在中国下载模型时可能遇到的访问问题的镜像源。我们不保证该源的时效性或安全性，详情请参阅镜像站点。

将 Textual Inversion 嵌入加载到 [StableDiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/text2img#diffusers.StableDiffusionPipeline) 的文本编码器中（同时支持 🤗 Diffusers 和 Automatic1111 格式）。

示例：

要在 🤗 Diffusers 格式中加载 Textual Inversion 嵌入向量：

```py
from diffusers import StableDiffusionPipeline
import torch

model_id = "stable-diffusion-v1-5/stable-diffusion-v1-5"
pipe = StableDiffusionPipeline.from_pretrained(model_id, torch_dtype=torch.float16).to("cuda")

pipe.load_textual_inversion("sd-concepts-library/cat-toy")

prompt = "A <cat-toy> backpack"

image = pipe(prompt, num_inference_steps=50).images[0]
image.save("cat-backpack.png")
```

要在 Automatic1111 格式中加载 Textual Inversion 嵌入向量，请先下载该向量（例如从 [civitAI](https://civitai.com/models/3036?modelVersionId=9857) 下载），然后加载该向量

本地：

```py
from diffusers import StableDiffusionPipeline
import torch

model_id = "stable-diffusion-v1-5/stable-diffusion-v1-5"
pipe = StableDiffusionPipeline.from_pretrained(model_id, torch_dtype=torch.float16).to("cuda")

pipe.load_textual_inversion("./charturnerv2.pt", token="charturnerv2")

prompt = "charturnerv2, multiple views of the same character in the same outfit, a character turnaround of a woman wearing a black jacket and red shirt, best quality, intricate details."

image = pipe(prompt, num_inference_steps=50).images[0]
image.save("character.png")
```

#### maybe_convert_prompt[[diffusers.loaders.TextualInversionLoaderMixin.maybe_convert_prompt]]

```python
maybe_convert_prompt(prompt: str | list[str], tokenizer: 'PreTrainedTokenizer')
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/textual_inversion.py#L123)

**参数：**

prompt (`str` 或 `str` 列表)：用于引导图像生成的提示词或提示词列表。

tokenizer (`PreTrainedTokenizer`)：负责将提示词编码为输入 token 的分词器。

**返回：** `str` 或 `str` 列表

转换后的提示

处理包含特殊标记的提示词，该特殊标记对应于多向量文本反转嵌入，需将其替换为多个特殊标记，每个标记对应其中一个向量。如果提示词中没有文本反转标记，或者文本反转标记为单向量，则返回原始输入提示词。

#### unload_textual_inversion[[diffusers.loaders.TextualInversionLoaderMixin.unload_textual_inversion]]

```python
unload_textual_inversion(tokens: str | list[str] | None = None, tokenizer: 'PreTrainedTokenizer' | None = None, text_encoder: 'PreTrainedModel' | None = None)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/textual_inversion.py#L467)

从 [StableDiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_diffusion/text2img#diffusers.StableDiffusionPipeline) 的文本编码器中卸载 Textual Inversion 嵌入

示例：
```py
from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")

# Example 1
pipeline.load_textual_inversion("sd-concepts-library/gta5-artwork")
pipeline.load_textual_inversion("sd-concepts-library/moeb-style")

# Remove all token embeddings
pipeline.unload_textual_inversion()

# Example 2
pipeline.load_textual_inversion("sd-concepts-library/moeb-style")
pipeline.load_textual_inversion("sd-concepts-library/gta5-artwork")

# Remove just one token
pipeline.unload_textual_inversion("<moe-bius>")

# Example 3: unload from SDXL
pipeline = AutoPipelineForText2Image.from_pretrained("stabilityai/stable-diffusion-xl-base-1.0")
embedding_path = hf_hub_download(
    repo_id="linoyts/web_y2k", filename="web_y2k_emb.safetensors", repo_type="model"
)

# load embeddings to the text encoders
state_dict = load_file(embedding_path)

# load embeddings of text_encoder 1 (CLIP ViT-L/14)
pipeline.load_textual_inversion(
    state_dict["clip_l"],
    tokens=["<s0>", "<s1>"],
    text_encoder=pipeline.text_encoder,
    tokenizer=pipeline.tokenizer,
)
# load embeddings of text_encoder 2 (CLIP ViT-G/14)
pipeline.load_textual_inversion(
    state_dict["clip_g"],
    tokens=["<s0>", "<s1>"],
    text_encoder=pipeline.text_encoder_2,
    tokenizer=pipeline.tokenizer_2,
)

# Unload explicitly from both text encoders and tokenizers
pipeline.unload_textual_inversion(
    tokens=["<s0>", "<s1>"], text_encoder=pipeline.text_encoder, tokenizer=pipeline.tokenizer
)
pipeline.unload_textual_inversion(
    tokens=["<s0>", "<s1>"], text_encoder=pipeline.text_encoder_2, tokenizer=pipeline.tokenizer_2
)
```