Diffusers documentation
Flux2
Flux2
Flux.2 là loạt mô hình tạo hình ảnh mới nhất từ Black Forest Labs, kế thừa sau loạt Flux.1. Đây là một mô hình hoàn toàn mới với kiến trúc mới và được huấn luyện trước từ đầu!
Các checkpoint mô hình gốc của Flux có thể được tìm thấy tại đây. Mã suy luận gốc có thể được tìm thấy tại đây.
Flux2 có thể khá tốn kém khi chạy trên các thiết bị phần cứng tiêu dùng. Tuy nhiên, bạn có thể thực hiện một loạt các tối ưu hóa để chạy nó nhanh hơn và thân thiện hơn với bộ nhớ. Xem mục này để biết thêm chi tiết. Ngoài ra, Flux có thể được hưởng lợi từ lượng tử hóa để đạt hiệu quả bộ nhớ, với sự đánh đổi về độ trễ suy luận. Tham khảo bài đăng trên blog này để tìm hiểu thêm.
Caching cũng có thể tăng tốc suy luận bằng cách lưu trữ và tái sử dụng các kết quả trung gian.
Mẫu hóa lại chú thích
Flux.2 có khả năng tạo ra kết quả tốt hơn với các prompt tốt hơn. Chúng ta có thể “upsample” một prompt đầu vào bằng cách đặt đối số caption_upsample_temperature trong các đối số gọi pipeline. Thực hiện chính thức khuyến nghị giá trị này là 0.15.
Flux2Pipeline
lớp diffusers.Flux2Pipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: Mistral3ForConditionalGenerationtokenizer: AutoProcessortransformer: Flux2Transformer2DModel )
Tham số
- transformer (Flux2Transformer2DModel) — Kiến trúc Transformer có điều kiện (MMDiT) để khử nhiễu các latents ảnh đã mã hóa.
- scheduler (FlowMatchEulerDiscreteScheduler) —
Một scheduler được sử dụng kết hợp với
transformerđể khử nhiễu các latents ảnh đã được mã hóa. - vae (
AutoencoderKLFlux2) — Mô hình Variational Auto-Encoder (VAE) để mã hóa và giải mã hình ảnh sang và từ các biểu diễn ẩn (latent representations). - text_encoder (
Mistral3ForConditionalGeneration) — Mistral3ForConditionalGeneration - tokenizer (
AutoProcessor) — Tokenizer của lớp PixtralProcessor.
Pipeline Flux2 cho việc tạo hình ảnh từ văn bản.
Tham khảo: https://bfl.ai/blog/flux-2
__call__
< source >( image: PIL.Image.Image | list[PIL.Image.Image] | None = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float | None = 4.0num_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneoutput_type: str | None = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 512text_encoder_out_layers: tuple = (10, 20, 30)caption_upsample_temperature: float = None ) → ~pipelines.flux2.Flux2PipelineOutput or tuple
Tham số
- image (
torch.Tensor,PIL.Image.Image,np.ndarray,list[torch.Tensor],list[PIL.Image.Image]hoặclist[np.ndarray]) —Image, mảng numpy hoặc tensor đại diện cho một lô ảnh (image batch) được sử dụng làm điểm khởi đầu. Đối với cả mảng numpy và tensor pytorch, khoảng giá trị mong đợi nằm trong[0, 1]Nếu là tensor hoặc một danh sách các tensor, hình dạng mong đợi phải là(B, C, H, W)hoặc(C, H, W). Nếu là mảng numpy hoặc một danh sách các mảng, hình dạng mong đợi phải là(B, H, W, C)hoặc(H, W, C)Nó cũng có thể nhận các ảnh latents dưới dạngimage, nhưng nếu truyền trực tiếp latents thì chúng sẽ không được mã hóa lại. - prompt (
strhoặclist[str], tùy chọn) — Prompt hoặc các prompt để định hướng việc tạo ảnh. Nếu không được định nghĩa, bạn phải truyềnprompt_embedsthay thế. - guidance_scale (
float, tuỳ chọn, mặc định là 1.0) — Thang độ guidance nhúng được kích hoạt bằng cách đặtguidance_scale> 1. Giá trịguidance_scalecao hơn sẽ khuyến khích mô hình tạo ra hình ảnh phù hợp hơn vớipromptvới chi phí là chất lượng hình ảnh thấp hơn.Các mô hình Guidance-distilled xấp xỉ true classifer-free guidance cho
guidance_scale> 1. Tham khảo bài báo để tìm hiểu thêm. - height (
int, tùy chọn, mặc định là self.unet.config.sample_size * self.vae_scale_factor) — Chiều cao của hình ảnh được tạo ra, tính bằng pixel. Giá trị mặc định là 1024 để đạt kết quả tốt nhất. - width (
int, tùy chọn, mặc định là self.unet.config.sample_size * self.vae_scale_factor) — Chiều rộng của hình ảnh được tạo ra, tính bằng pixel. Giá trị mặc định là 1024 để đạt kết quả tốt nhất. - num_inference_steps (
int, tùy chọn, mặc định là 50) — Số bước khử nhiễu. Số bước khử nhiễu nhiều hơn thường dẫn đến hình ảnh có chất lượng cao hơn với chi phí là suy luận chậm hơn. - sigmas (
list[float], tùy chọn) — Các sigma tùy chỉnh để sử dụng cho quá trình khử nhiễu với các trình lập lịch hỗ trợ đối sốsigmastrong phương thứcset_timestepscủa chúng. Nếu không được định nghĩa, hành vi mặc định khinum_inference_stepsđược truyền sẽ được sử dụng. - num_images_per_prompt (
int, tùy chọn, mặc định là 1) — Số lượng hình ảnh cần tạo cho mỗi prompt. - generator (
torch.Generatorhoặclist[torch.Generator], tuỳ chọn) — Một hoặc một danh sách torch generator để đảm bảo quá trình sinh là tất định. - latents (
torch.Tensor, tùy chọn) — Các latents nhiễu đã được tạo trước, lấy mẫu từ phân phối Gaussian, dùng làm đầu vào cho việc tạo ảnh. Có thể dùng để tinh chỉnh cùng một quá trình tạo với các prompt khác nhau. Nếu không được cung cấp, một tensor latents sẽ được tạo bằng cách lấy mẫu sử dụnggeneratorngẫu nhiên được cung cấp. - prompt_embeds (
torch.Tensor, tùy chọn) — Các embedding văn bản đã được tạo trước. Có thể dùng để dễ dàng điều chỉnh đầu vào văn bản, vd. trọng số prompt. Nếu không được cung cấp, các embedding văn bản sẽ được tạo từ đối số đầu vàoprompt. - output_type (
str, tùy chọn, mặc định là"pil") — Định dạng đầu ra của hình ảnh được tạo. Chọn giữa PIL:PIL.Image.Imagehoặcnp.array. - return_dict (
bool, tùy chọn, mặc định làTrue) — Có nên trả về một~pipelines.qwenimage.QwenImagePipelineOutputthay vì một tuple thông thường hay không. - attention_kwargs (
dict, tùy chọn) — Một từ điển kwargs, nếu được chỉ định, sẽ được truyền đếnAttentionProcessornhư đã định nghĩa dướiself.processortrong diffusers.models.attention_processor. - callback_on_step_end (
Callable, tùy chọn) — Một hàm được gọi vào cuối mỗi bước khử nhiễu trong quá trình suy luận. Hàm này được gọi với các đối số sau:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargssẽ bao gồm danh sách tất cả các tensor như được chỉ định bởicallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, optional) — Danh sách các tensor đầu vào cho hàmcallback_on_step_end. Các tensor được chỉ định trong danh sách sẽ được truyền dưới dạng tham sốcallback_kwargs. Bạn chỉ có thể bao gồm các biến được liệt kê trong thuộc tính._callback_tensor_inputscủa lớp pipeline của bạn. - max_sequence_length (
int, mặc định là 512) — Độ dài tối đa của chuỗi để sử dụng vớiprompt. - text_encoder_out_layers (
tuple[int]) — Chỉ số các lớp cần sử dụng trongtext_encoderđể suy ra các prompt embeddings cuối cùng. - caption_upsample_temperature (
float) — Khi được chỉ định, chúng tôi sẽ cố gắng thực hiện caption upsampling để có thể cải thiện kết quả đầu ra. Chúng tôi khuyến nghị đặt giá trị này thành 0.15 nếu thực hiện caption upsampling.
Trả về
~pipelines.flux2.Flux2PipelineOutput hoặc tuple
~pipelines.flux2.Flux2PipelineOutput nếu
return_dict là True, ngược lại là một tuple. Khi trả về tuple, phần tử đầu tiên là một danh sách chứa các
ảnh đã được tạo.
Hàm được gọi khi gọi pipeline cho việc sinh.
Ví dụ:
>>> import torch
>>> from diffusers import Flux2Pipeline
>>> pipe = Flux2Pipeline.from_pretrained("black-forest-labs/FLUX.2-dev", torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> image = pipe(prompt, num_inference_steps=50, guidance_scale=2.5).images[0]
>>> image.save("flux.png")Flux2KleinPipeline
lớp diffusers.Flux2KleinPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: Qwen3ForCausalLMtokenizer: Qwen2Tokenizertransformer: Flux2Transformer2DModelis_distilled: bool = False )
Tham số
- transformer (Flux2Transformer2DModel) — Kiến trúc Transformer có điều kiện (MMDiT) để khử nhiễu các latents ảnh đã mã hóa.
- scheduler (FlowMatchEulerDiscreteScheduler) —
Một scheduler được sử dụng kết hợp với
transformerđể khử nhiễu các latents ảnh đã được mã hóa. - vae (
AutoencoderKLFlux2) — Mô hình Variational Auto-Encoder (VAE) để mã hóa và giải mã hình ảnh sang và từ các biểu diễn ẩn (latent representations). - text_encoder (
Qwen3ForCausalLM) — Qwen3ForCausalLM - tokenizer (
Qwen2TokenizerFast) — Tokenizer của lớp Qwen2TokenizerFast.
Pipeline Flux2 Klein cho việc tạo ảnh từ văn bản.
Tham khảo: https://bfl.ai/blog/flux2-klein-towards-interactive-visual-intelligence
__call__
< source >( image: list[PIL.Image.Image] | PIL.Image.Image | None = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 50sigmas: list[float] | None = Noneguidance_scale: float = 4.0num_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_prompt_embeds: str | list[str] | None = Noneoutput_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 512text_encoder_out_layers: tuple = (9, 18, 27) ) → ~pipelines.flux2.Flux2PipelineOutput or tuple
Tham số
- image (
torch.Tensor,PIL.Image.Image,np.ndarray,List[torch.Tensor],List[PIL.Image.Image]hoặcList[np.ndarray]) —Image, mảng numpy hoặc tensor đại diện cho một lô ảnh (image batch) được sử dụng làm điểm khởi đầu. Đối với cả mảng numpy và tensor pytorch, khoảng giá trị mong đợi nằm trong[0, 1]Nếu là tensor hoặc một danh sách các tensor, hình dạng mong đợi phải là(B, C, H, W)hoặc(C, H, W). Nếu là mảng numpy hoặc một danh sách các mảng, hình dạng mong đợi phải là(B, H, W, C)hoặc(H, W, C)Nó cũng có thể nhận image latents dưới dạngimage, nhưng nếu truyền trực tiếp latents thì chúng sẽ không được mã hóa lại. - prompt (
strhoặcList[str], tùy chọn) — Prompt hoặc các prompt để định hướng việc tạo ảnh. Nếu không được định nghĩa, bạn phải truyềnprompt_embedsthay thế. - guidance_scale (
float, tùy chọn, mặc định là 4.0) — Thang độ dẫn hướng như được định nghĩa trong Classifier-Free Diffusion Guidance.guidance_scaleđược định nghĩa làwcủa phương trình 2. trong Imagen Paper. Thang độ dẫn hướng được kích hoạt bằng cách đặtguidance_scale > 1. Thang độ dẫn hướng cao hơn khuyến khích tạo ra các hình ảnh gắn kết chặt chẽ vớipromptvăn bản, thường phải đánh đổi bằng chất lượng hình ảnh thấp hơn. Đối với các mô hình đã được chưng cất theo từng bước,guidance_scalesẽ bị bỏ qua. - height (
int, tùy chọn, mặc định là self.unet.config.sample_size * self.vae_scale_factor) — Chiều cao của hình ảnh được tạo ra, tính bằng pixel. Giá trị mặc định là 1024 để đạt kết quả tốt nhất. - width (
int, tùy chọn, mặc định là self.unet.config.sample_size * self.vae_scale_factor) — Chiều rộng của hình ảnh được tạo ra, tính bằng pixel. Giá trị mặc định là 1024 để đạt kết quả tốt nhất. - num_inference_steps (
int, tùy chọn, mặc định là 50) — Số bước khử nhiễu. Số bước khử nhiễu nhiều hơn thường dẫn đến hình ảnh có chất lượng cao hơn với chi phí là suy luận chậm hơn. - sigmas (
List[float], tùy chọn) — Các sigma tùy chỉnh để sử dụng cho quá trình khử nhiễu với các trình lập lịch hỗ trợ đối sốsigmastrong phương thứcset_timestepscủa chúng. Nếu không được định nghĩa, hành vi mặc định khinum_inference_stepsđược truyền sẽ được sử dụng. - num_images_per_prompt (
int, tùy chọn, mặc định là 1) — Số lượng hình ảnh cần tạo cho mỗi prompt. - generator (
torch.GeneratorhoặcList[torch.Generator], tùy chọn) — Một hoặc một danh sách torch generator để đảm bảo quá trình sinh là tất định. - latents (
torch.Tensor, tùy chọn) — Các latents nhiễu đã được tạo trước, lấy mẫu từ phân phối Gaussian, dùng làm đầu vào cho việc tạo ảnh. Có thể dùng để tinh chỉnh cùng một quá trình tạo với các prompt khác nhau. Nếu không được cung cấp, một tensor latents sẽ được tạo bằng cách lấy mẫu sử dụnggeneratorngẫu nhiên được cung cấp. - prompt_embeds (
torch.Tensor, tùy chọn) — Các embedding văn bản đã được tạo trước. Có thể dùng để dễ dàng điều chỉnh đầu vào văn bản, vd. trọng số prompt. Nếu không được cung cấp, các embedding văn bản sẽ được tạo từ đối số đầu vàoprompt. - negative_prompt_embeds (
torch.Tensor, tùy chọn) — Các embedding văn bản âm đã được tạo trước. Lưu ý rằng "" được sử dụng làm prompt âm trong pipeline này. Nếu không được cung cấp, chúng sẽ được tạo từ "". - output_type (
str, tùy chọn, mặc định là"pil") — Định dạng đầu ra của hình ảnh được tạo. Chọn giữa PIL:PIL.Image.Imagehoặcnp.array. - return_dict (
bool, tùy chọn, mặc định làTrue) — Có nên trả về một~pipelines.qwenimage.QwenImagePipelineOutputthay vì một tuple thông thường hay không. - attention_kwargs (
dict, tùy chọn) — Một từ điển kwargs, nếu được chỉ định, sẽ được truyền đếnAttentionProcessornhư đã định nghĩa dướiself.processortrong diffusers.models.attention_processor. - callback_on_step_end (
Callable, tùy chọn) — Một hàm được gọi vào cuối mỗi bước khử nhiễu trong quá trình suy luận. Hàm này được gọi với các đối số sau:callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict).callback_kwargssẽ bao gồm danh sách tất cả các tensor như được chỉ định bởicallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, optional) — Danh sách các tensor đầu vào cho hàmcallback_on_step_end. Các tensor được chỉ định trong danh sách sẽ được truyền dưới dạng tham sốcallback_kwargs. Bạn chỉ có thể bao gồm các biến được liệt kê trong thuộc tính._callback_tensor_inputscủa lớp pipeline của bạn. - max_sequence_length (
int, mặc định là 512) — Độ dài tối đa của chuỗi để sử dụng vớiprompt. - text_encoder_out_layers (
tuple[int]) — Chỉ số các lớp cần sử dụng trongtext_encoderđể suy ra các prompt embeddings cuối cùng.
Trả về
~pipelines.flux2.Flux2PipelineOutput hoặc tuple
~pipelines.flux2.Flux2PipelineOutput nếu
return_dict là True, ngược lại là một tuple. Khi trả về tuple, phần tử đầu tiên là một danh sách chứa các
ảnh đã được tạo.
Hàm được gọi khi gọi pipeline cho việc sinh.
Ví dụ:
>>> import torch
>>> from diffusers import Flux2KleinPipeline
>>> pipe = Flux2KleinPipeline.from_pretrained(
... "black-forest-labs/FLUX.2-klein-base-9B", torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> prompt = "A cat holding a sign that says hello world"
>>> # Depending on the variant being used, the pipeline call will slightly vary.
>>> # Refer to the pipeline documentation for more details.
>>> image = pipe(prompt, num_inference_steps=50, guidance_scale=4.0).images[0]
>>> image.save("flux2_output.png")Flux2KleinKVPipeline
lớp diffusers.Flux2KleinKVPipeline
< source >( scheduler: FlowMatchEulerDiscreteSchedulervae: AutoencoderKLFlux2text_encoder: Qwen3ForCausalLMtokenizer: Qwen2Tokenizertransformer: Flux2Transformer2DModelis_distilled: bool = True )
Tham số
- transformer (Flux2Transformer2DModel) — Kiến trúc Transformer có điều kiện (MMDiT) để khử nhiễu các latents ảnh đã mã hóa.
- scheduler (FlowMatchEulerDiscreteScheduler) —
Một scheduler được sử dụng kết hợp với
transformerđể khử nhiễu các latents ảnh đã được mã hóa. - vae (
AutoencoderKLFlux2) — Mô hình Variational Auto-Encoder (VAE) để mã hóa và giải mã hình ảnh sang và từ các biểu diễn ẩn (latent representations). - text_encoder (
Qwen3ForCausalLM) — Qwen3ForCausalLM - tokenizer (
Qwen2TokenizerFast) — Tokenizer của lớp Qwen2TokenizerFast.
Pipeline Flux2 Klein KV cho tạo ảnh từ văn bản với điều kiện ảnh tham chiếu được cache KV.
Ở bước khử nhiễu đầu tiên, các token của ảnh tham chiếu được đưa vào quá trình truyền thẳng và các phép chiếu K/V của chú ý (attention) của chúng được lưu vào bộ nhớ đệm. Ở các bước tiếp theo, các K/V đã được lưu trong bộ nhớ đệm sẽ được tái sử dụng mà không cần tính lại, giúp suy luận nhanh hơn khi sử dụng ảnh tham chiếu.
Tham khảo: https://bfl.ai/blog/flux2-klein-towards-interactive-visual-intelligence
__call__
< source >( image: list[PIL.Image.Image] | PIL.Image.Image | None = Noneprompt: str | list[str] = Noneheight: int | None = Nonewidth: int | None = Nonenum_inference_steps: int = 4sigmas: list[float] | None = Nonenum_images_per_prompt: int = 1generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneoutput_type: str = 'pil'return_dict: bool = Trueattention_kwargs: dict[str, typing.Any] | None = Nonecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], NoneType]] = Nonecallback_on_step_end_tensor_inputs: list = ['latents']max_sequence_length: int = 512text_encoder_out_layers: tuple = (9, 18, 27) )
Tham số
- image (
PIL.Image.ImagehoặcList[PIL.Image.Image], không bắt buộc) — Hình ảnh tham chiếu để điều kiện hóa. Ở bước khử nhiễu đầu tiên, các token tham chiếu được đưa vào quá trình truyền thẳng và K/V của chú ý của chúng được lưu vào bộ nhớ đệm. Ở các bước tiếp theo, K/V đã lưu trong bộ nhớ đệm được tái sử dụng mà không cần tính toán lại. - prompt (
strhoặcList[str], tùy chọn) — Prompt hoặc các prompt để định hướng việc tạo ảnh. - height (
int, tùy chọn) — Chiều cao của hình ảnh được tạo ra, tính bằng pixel. - width (
int, tùy chọn) — Chiều rộng của hình ảnh được tạo ra, tính bằng pixel. - num_inference_steps (
int, tùy chọn, mặc định là 4) — Số bước khử nhiễu. - sigmas (
List[float], tùy chọn) — Các sigma tùy chỉnh cho lịch trình khử nhiễu. - num_images_per_prompt (
int, tùy chọn, mặc định là 1) — Số lượng hình ảnh cần tạo cho mỗi prompt. - generator (
torch.GeneratorhoặcList[torch.Generator], tùy chọn) — Bộ sinh cho việc tạo ra nội dung có tính xác định. - latents (
torch.Tensor, tùy chọn) — Các latents nhiễu đã được tạo trước. - prompt_embeds (
torch.Tensor, tùy chọn) — Các vector nhúng văn bản đã được tạo trước. - output_type (
str, tùy chọn, mặc định là"pil") — Định dạng đầu ra:"pil"hoặc"np". - return_dict (
bool, tùy chọn, mặc định làTrue) — Có nên trả về mộtFlux2PipelineOutputhay một tuple thông thường. - attention_kwargs (
dict, tùy chọn) — Các kwargs bổ sung được truyền cho các bộ xử lý attention. - callback_on_step_end (
Callable, tùy chọn) — Hàm callback được gọi vào cuối mỗi bước khử nhiễu. - callback_on_step_end_tensor_inputs (
List, tùy chọn) — Đầu vào tensor cho hàm callback. - max_sequence_length (
int, mặc định là 512) — Độ dài tối đa của chuỗi cho prompt. - text_encoder_out_layers (
tuple[int]) — Chỉ số lớp để trích xuất trạng thái ẩn của text encoder.
Hàm được gọi khi gọi pipeline cho việc sinh.
Ví dụ:
>>> import torch
>>> from PIL import Image
>>> from diffusers import Flux2KleinKVPipeline
>>> pipe = Flux2KleinKVPipeline.from_pretrained(
... "black-forest-labs/FLUX.2-klein-9b-kv", torch_dtype=torch.bfloat16
... )
>>> pipe.to("cuda")
>>> ref_image = Image.open("reference.png")
>>> image = pipe("A cat dressed like a wizard", image=ref_image, num_inference_steps=4).images[0]
>>> image.save("flux2_kv_output.png")