Hướng dẫn FLUX.2 Klein: Xây dựng ứng dụng Tạo và Chỉnh sửa ảnh với Gradio

Bước 1: Thiết lập môi trường

Trước khi xây dựng ứng dụng tạo và chỉnh sửa ảnh, chúng ta cần thiết lập môi trường sạch với thư viện Diffusers mới nhất. Trong hướng dẫn này, chúng ta sẽ chạy mọi thứ trên Google Colab với GPU A100 để tạo ảnh nhanh hơn. Dù vậy, thiết lập tương tự cũng hoạt động trên các GPU vừa phải như T4, chỉ chậm hơn đôi chút.

Chúng ta bắt đầu bằng cách gỡ cài đặt bất kỳ phiên bản Diffusers nào đang có để tránh xung đột, rồi cài bản phát triển mới nhất trực tiếp từ GitHub. Ta cũng cài các thư viện hỗ trợ cần thiết cho việc tải mô hình, xử lý checkpoint và tăng tốc.

!pip -q uninstall -y diffusers
!pip -q install -U git+https://github.com/huggingface/diffusers.git
!pip -q install -U accelerate safetensors transformers huggingface_hubĐược hỗ trợ bởi

Sau khi cài đặt xong, chúng ta kiểm tra phiên bản Diffusers đã cài, rồi xác nhận có thể import lớp Flux2KleinPipeline thành công.

import diffusers
print("diffusers:", diffusers.__version__)
from diffusers import Flux2KleinPipeline
print("Flux2KleinPipeline import OK")Được hỗ trợ bởi

Điều này xác nhận môi trường đã được cấu hình đúng. Ở bước tiếp theo, chúng ta sẽ nạp mô hình FLUX.2 Klein lên GPU và chuẩn bị cho cả tạo ảnh cục bộ và quy trình chỉnh sửa ảnh qua API.

Bước 2: Nạp FLUX.2 Klein 4B 

Trước khi nạp mô hình, bạn cần một khóa API từ Black Forest Labs. Để bắt đầu, đăng nhập vào tài khoản Black Forest Labs của bạn và nạp credit trong thẻ Credits. Mức nạp tối thiểu khoảng mười đô la, tương đương xấp xỉ một nghìn credit. Khi đã nạp, nhấp Create Key, đặt tên mô tả và lưu trữ an toàn.

Khi đã có khóa API, bước tiếp theo là nạp mô hình FLUX.2 Klein 4B và chuẩn bị cho hai chế độ sử dụng khác nhau: tạo ảnh cục bộ và chỉnh sửa ảnh qua API. 

import os, time, base64, io, requests
import gradio as gr
import torch
import nest_asyncio
from PIL import Image
from diffusers import Flux2KleinPipeline
from google.colab import userdata
nest_asyncio.apply()
# =============================
# LOAD via API
# =============================
MODEL_ID = "black-forest-labs/FLUX.2-klein-4B"
BFL_API_KEY = userdata.get("BFL_API_KEY")
BFL_CREATE_URL = "https://api.bfl.ai/v1/flux-2-klein-4b"
print(f"Loading model to GPU: {torch.cuda.get_device_name(0)}")
# =============================
# LOAD via LOCAL HF PIPELINE
# =============================
dtype = torch.float16 
pipe = Flux2KleinPipeline.from_pretrained(MODEL_ID, torch_dtype=dtype).to("cuda")Được hỗ trợ bởi

Chúng ta thiết lập khóa API như một bí mật trong Colab, để nó không hiện trong mã notebook. Ta cũng định nghĩa ID mô hình và endpoint chỉnh sửa Klein sẽ gọi sau này. 

Tiếp theo, áp dụng nest_asyncio trước khi khởi chạy giao diện Gradio để tránh xung đột vòng lặp sự kiện.

Cuối cùng, nạp pipeline FLUX.2 Klein cục bộ để tạo ảnh nền. Chúng ta dùng Flux2KleinPipeline với float16 để tương thích rộng với GPU (A100 và T4 đều hoạt động tốt), rồi chuyển pipeline sang CUDA để suy luận nhanh. Pipeline cục bộ này chỉ dùng để tạo ảnh ban đầu, còn các chỉnh sửa được xử lý qua API.

Lưu ý: Lúc này, bạn có thể thắc mắc tại sao vừa nạp mô hình cục bộ vừa cấu hình truy cập API. Lý do là tách biệt năng lực:

• Pipeline Hugging Face cục bộ lý tưởng cho quá trình tạo text-to-image lặp và toàn quyền điều khiển thiết lập suy luận.
• API của Black Forest Labs cung cấp các tính năng chỉnh sửa ảnh nâng cao cho FLUX.2 Klein hiện chưa có trong bản mở trọng số, như chỉnh sửa ảnh dựa trên prompt với nhiều ảnh tham chiếu.

Bằng cách kết hợp cả hai, ta có được tốc độ tạo cục bộ và hỗ trợ chỉnh sửa tối ưu.

Bước 3: Các hàm trợ giúp

Trước khi nối mọi thứ vào giao diện Gradio, chúng ta cần một số hàm trợ giúp nhỏ. Vì ứng dụng tạo ảnh cục bộ nhưng chỉnh sửa qua API, ta cần cách mã hóa ảnh thành base64 cho yêu cầu API, cách tải ảnh chỉnh sửa trả về dưới dạng URL, và một hàm tạo cục bộ để sinh ảnh nền ban đầu.

def pil_to_b64_png(img: Image.Image) -> str:
    buf = io.BytesIO()
    img.convert("RGB").save(buf, format="PNG")
    return base64.b64encode(buf.getvalue()).decode()
def url_to_pil(url: str) -> Image.Image:
    r = requests.get(url, timeout=60)
    r.raise_for_status()
    return Image.open(io.BytesIO(r.content)).convert("RGB")
def local_generate(prompt: str):
    if not prompt.strip():
        raise gr.Error("Prompt is empty.")
    out = pipe(
        prompt=prompt.strip(),
        width=1024,
        height=1024,
        num_inference_steps=4,
        guidance_scale=1.0,
        output_type="pil",
    )
    return out.images[0].convert("RGB")Được hỗ trợ bởi

Đoạn mã trên định nghĩa ba hàm trợ giúp chính:

• Hàm pil_to_b64_png() chuyển một ảnh PIL thành chuỗi PNG mã hóa base64. Cần thiết vì API chỉnh sửa FLUX.2 chấp nhận ảnh nền và ảnh tham chiếu dưới dạng URL hoặc chuỗi base64. 
• Hàm url_to_pil() xử lý chiều ngược lại. API chỉnh sửa trả về URL có chữ ký cho đầu ra, nên ta tải URL đó bằng requests, kiểm tra phản hồi, rồi chuyển byte tải về thành ảnh PIL. Nhờ vậy kết quả chỉnh sửa có thể hiển thị trực tiếp trong Gradio và lưu vào lịch sử.
• Cuối cùng, local_generate() là điểm vào text-to-image cục bộ. Nó kiểm tra prompt không rỗng, rồi gọi Flux2KleinPipeline cục bộ với các thiết lập cố định như độ phân giải, số bước và hệ số hướng dẫn. Đầu ra trả về là ảnh PIL RGB sạch, trở thành ảnh nền cho các chỉnh sửa tiếp theo.

Bạn có thể thử thay đổi thiết lập pipeline Flux 2 như độ phân giải ảnh, số bước khuếch tán và hệ số hướng dẫn để khám phá các đánh đổi chất lượng-tốc độ và hiểu rõ hơn ảnh hưởng của từng tham số.

Tài liệu chỉnh sửa ảnh Flux 2 là nơi tốt để hiểu thêm về các thiết lập này.

Ở bước tiếp theo, chúng ta sẽ dùng các tiện ích này để triển khai chỉnh sửa ảnh qua API với FLUX.2 Klein.

Bước 4: Chỉnh sửa qua API của BFL

Bước này là khác biệt cốt lõi giữa quy trình chỉ dùng Hugging Face và cách tiếp cận lai trong hướng dẫn này. Thay vì cố gắng chạy chỉnh sửa cục bộ, ta ủy thác cho API, vốn xử lý chỉnh sửa dựa trên prompt và điều kiện hóa đa tham chiếu một cách ổn định.

Ở mức cao, API chỉnh sửa FLUX.2 Klein cần một prompt mô tả chỉnh sửa, một ảnh nền để thay đổi và các ảnh tham chiếu tùy chọn cung cấp thêm đầu vào. API chạy bất đồng bộ, nghĩa là ta gửi yêu cầu rồi truy vấn một URL trả về cho đến khi ảnh chỉnh sửa sẵn sàng.

POLL_INTERVAL_S = 1.0
POLL_TIMEOUT_S = 120
def bfl_edit(edit_prompt, base_img, ref_imgs=None):
    if not BFL_API_KEY:
        raise gr.Error("Missing BFL_API_KEY in Colab Secrets.") 
    payload = {
        "prompt": edit_prompt.strip(),
        "input_image": pil_to_b64_png(base_img),
        "output_format": "png",
    }
    if ref_imgs:
        for i, ref in enumerate(ref_imgs[:3], start=2):
            payload[f"input_image_{i}"] = pil_to_b64_png(ref)
    create = requests.post(
        BFL_CREATE_URL,
        headers={"x-key": BFL_API_KEY, "accept": "application/json"},
        json=payload,
        timeout=60,
    )
    create.raise_for_status()
    job = create.json()
    polling_url = job.get("polling_url")
    if not polling_url:
        raise gr.Error(f"API Error: {job}")
    t0 = time.time()
    while True:
        if time.time() - t0 > POLL_TIMEOUT_S:
            raise gr.Error("BFL API polling timed out.")  
        time.sleep(POLL_INTERVAL_S)
        res = requests.get(polling_url, headers={"x-key": BFL_API_KEY})
        res.raise_for_status()
        j = res.json()
        if j["status"] == "Ready":
            return url_to_pil(j["result"]["sample"])
        if j["status"] in ("Error", "Failed"):
            raise gr.Error(f"Generation Failed: {j}")Được hỗ trợ bởi

Hàm bfl_edit() làm ba việc quan trọng:

• Nhận ba đầu vào gồm prompt chỉnh sửa, ảnh nền cần sửa và danh sách ảnh tham chiếu tùy chọn. 
• Xây dựng payload JSON với prompt chỉnh sửa và ảnh nền mã hóa PNG base64. Nếu có ảnh tham chiếu, ta đính kèm theo định dạng đánh chỉ số của API. Cách này cho phép cung cấp tối đa ba ảnh tham chiếu bên cạnh ảnh nền, đủ cho nhiều quy trình thực tế như chuyển bảng màu, cố định phong cách hoặc gắn đối tượng.
• Tiếp theo, gửi yêu cầu đến endpoint API và phân tích phản hồi. API trả về polling_url mà ta phải truy vấn lặp cho đến khi xong. Ta hiện thực bằng vòng lặp polling đơn giản với hai rào chắn: khoảng thời gian truy vấn tránh gửi quá dày và thời hạn để tránh notebook chờ vô hạn.

Khi trạng thái thành Ready, phản hồi API chứa URL có chữ ký tới ảnh đầu ra. Ta tải ảnh đó bằng hàm trợ giúp url_to_pil() trước đó và trả về dạng ảnh PIL.

Ở bước tiếp theo, chúng ta sẽ triển khai lịch sử phiên để người dùng có thể xem lại bất kỳ đầu ra nào đã tạo hoặc chỉnh sửa.

Bước 5: Thêm lịch sử 

Lúc này, mảnh ghép cuối cùng trước khi xây dựng UI là một lớp bộ nhớ phiên nhẹ để người dùng có thể xem lại các đầu ra trước đó. Chúng ta triển khai lịch sử bằng hai đối tượng state của Gradio:

• base_img_state lưu ảnh đang làm việc hiện tại (ảnh mà các chỉnh sửa sau này sẽ áp dụng).
• history_state lưu mọi phiên bản đã tạo hoặc chỉnh sửa dưới dạng danh sách các từ điển, mỗi mục chứa một ảnh và nhãn ngắn.

def update_history(history):
    choices = [f"{i}: {h['label']}" for i, h in enumerate(history or [])]
    return gr.update(choices=choices, value=choices[-1] if choices else None)
def on_generate(prompt, history):
    img = local_generate(prompt)
    new_history = list(history or [])
    new_history.append({"img": img, "label": "Generated Base"})
    return img, img, new_history, update_history(new_history), "Base image generated."
def on_edit(edit_prompt, ref2, ref3, ref4, base_img, history):
    if base_img is None:
        raise gr.Error("Please generate a base image first.")
    refs = [r.convert("RGB") for r in (ref2, ref3, ref4) if r is not None]
    out = bfl_edit(edit_prompt, base_img, refs)
    new_history = list(history or [])
    new_history.append({"img": out, "label": f"Edit: {edit_prompt[:20]}..."})
    return out, out, new_history, update_history(new_history), "Edit successful."
def on_load(choice, history):
    if not history or not choice:
        return None, None, "No history to load."
    idx = int(choice.split(":")[0])
    img = history[idx]["img"]
    return img, img, f"Loaded entry #{idx}."
def on_clear():
    return None, None, [], gr.update(choices=[], value=None), "Cleared everything."Được hỗ trợ bởi

Các hàm trên tạo nên logic lõi để duy trì lịch sử ảnh trong bản demo:

• Hàm update_history() định dạng lịch sử phiên vào dropdown. Mỗi mục được gắn nhãn bằng chỉ số và mô tả ngắn, và dropdown tự động chọn mục mới nhất. Điều này giữ cho UI đồng bộ mà không cần logic làm mới thủ công.
• Callback on_generate() chạy local_generate() để tạo ảnh nền ban đầu. Sau đó thêm kết quả vào lịch sử dưới dạng {"img": img, "label": "Generated Base"}. Hàm trả về ảnh và state lịch sử đã cập nhật, cùng cập nhật dropdown để mục mới hiển thị ngay.
• Callback on_edit() tương tự, nhưng gọi bfl_edit(). Nó lấy ảnh đang làm việc hiện tại và các ảnh tham chiếu tùy chọn, áp dụng chỉnh sửa qua API và thêm đầu ra vào lịch sử. Nó cũng trả về đầu ra chỉnh sửa làm base_img_state mới, nghĩa là các chỉnh sửa tiếp theo áp dụng lên ảnh gần nhất trừ khi người dùng tải một phiên bản cũ hơn.
• Callback on_load() phân tích mục được chọn trong dropdown, lấy ảnh tương ứng từ history_state và đặt ảnh đó làm ảnh làm việc hiện tại. Điều này cho phép người dùng rẽ nhánh chỉnh sửa từ bất kỳ mốc trước đó.
• Cuối cùng, hàm on_clear() đặt lại mọi thứ. Nó xóa đầu ra, xóa state ảnh nền, đặt lại danh sách lịch sử và làm trống các lựa chọn dropdown.

Hãy nối các hàm này vào giao diện Gradio với hai hộp văn bản, tải lên tham chiếu tùy chọn và quy trình lịch sử.

Bước 6: Giao diện Gradio

Bước này kết nối logic tạo, chỉnh sửa và lịch sử vào một giao diện Gradio đơn giản. Giao diện được xây bằng gr.Blocks, cho phép kiểm soát bố cục chi tiết. 

with gr.Blocks() as demo:
    gr.Markdown("## FLUX.2 Klein: Generate & Edit Images")
    with gr.Row():
        with gr.Column(scale=1):
            gen_prompt = gr.Textbox(label="1. Generate Base Image", placeholder="A young boy riding a scooter...")
            gen_btn = gr.Button("Generate Base Image", variant="primary")
            edit_prompt = gr.Textbox(label="2. Describe Edits", placeholder="Add the red hat and yellow glasses from the references...")
            with gr.Accordion("Reference Images (Optional)", open=False):
                r2 = gr.Image(label="Ref 1", type="pil")
                r3 = gr.Image(label="Ref 2", type="pil")
                r4 = gr.Image(label="Ref 3", type="pil")
            edit_btn = gr.Button("Apply Edit", variant="secondary") 
            history_dd = gr.Dropdown(label="Session History", choices=[])
            with gr.Row():
                load_btn = gr.Button("Load Selected")
                clear_btn = gr.Button("Clear All")
            status = gr.Textbox(label="Status", interactive=False)
        with gr.Column(scale=1):
            output_view = gr.Image(label="Current Image", type="pil")
    base_img_state = gr.State(None)
    history_state = gr.State([])
    gen_btn.click(
        on_generate, 
        [gen_prompt, history_state], 
        [output_view, base_img_state, history_state, history_dd, status]
    ) 
    edit_btn.click(
        on_edit, 
        [edit_prompt, r2, r3, r4, base_img_state, history_state], 
        [output_view, base_img_state, history_state, history_dd, status]
    ) 
    load_btn.click(
        on_load, 
        [history_dd, history_state], 
        [output_view, base_img_state, status]
    )
    clear_btn.click(
        on_clear, 
        None, 
        [output_view, base_img_state, history_state, history_dd, status]
    )
demo.launch(share=True, inline=True, debug = True)Được hỗ trợ bởi

Chúng ta tổ chức UI thành hai cột: cột trái chứa đầu vào và thao tác, cột phải hiển thị ảnh hiện tại. Cách xây dựng ứng dụng Gradio như sau:

• Hộp văn bản đầu tiên thu thập prompt tạo, và nút Generate Base Image kích hoạt hàm on_generate(). Callback này chạy tạo cục bộ, lưu đầu ra vào lịch sử và cập nhật cả ảnh hiển thị lẫn ảnh làm việc hiện tại lưu trong base_img_state.
• Hộp văn bản thứ hai thu thập hướng dẫn chỉnh sửa. Khi người dùng nhấp Apply Edit, ta gọi on_edit(), dùng ảnh làm việc hiện tại làm ảnh nền và trả về ảnh đã chỉnh sửa. Ảnh này cũng được thêm vào lịch sử và trở thành ảnh làm việc cho các chỉnh sửa tiếp theo.
• Để quy trình nhận biết theo phiên, ta thêm dropdown Session History sao cho mỗi mục tương ứng một phiên bản ảnh đã lưu. Nút Load Selected kích hoạt on_load(), khôi phục ảnh lịch sử đã chọn và đặt lại làm ảnh làm việc. 
• Cuối cùng, nút Clear All đặt lại mọi thứ qua hàm on_clear(), gồm màn hình hiển thị, state ảnh nền và lịch sử đã lưu.

Hai đối tượng Gradio State sau giữ mọi thứ nhất quán:

• base_img_state đảm bảo mỗi chỉnh sửa áp dụng lên đúng ảnh.
• history_state lưu toàn bộ dòng thời gian đầu ra để phát lại và rẽ nhánh.

Cuối cùng, demo.launch() khởi chạy ứng dụng trong Colab, cung cấp liên kết chia sẻ, hiển thị inline và bật log gỡ lỗi để hỗ trợ chẩn đoán trong quá trình phát triển.

Ví dụ và ghi nhận với FLUX.2 Klein

Để hiểu cách FLUX.2 Klein hoạt động trong thực tế, tôi đã chạy một số thử nghiệm nhỏ bằng ứng dụng Tạo và Chỉnh sửa cuối cùng. Tôi kiểm thử ba kiểu tương tác chính: tạo ảnh nền, chỉnh sửa chỉ bằng prompt và chỉnh sửa có hướng dẫn tham chiếu bằng một hoặc nhiều ảnh. Tôi cũng xác thực quy trình lịch sử phiên để đảm bảo có thể khôi phục bất kỳ đầu ra trước đó và tiếp tục chỉnh sửa từ điểm đó.

Tạo ảnh

Tôi bắt đầu với một prompt tạo đơn giản để có ảnh nền sạch. Mô hình tạo ra chủ thể mạch lạc với ánh sáng nhất quán, chi tiết khuôn mặt sắc nét và bố cục cảnh ổn định. Ảnh nền trông tốt và hữu ích cho các chỉnh sửa sau, thay vì phải tạo lại.

Chỉnh sửa ảnh với một ảnh tham chiếu

Tiếp theo, tôi thử một ảnh tham chiếu làm nguồn màu và dùng hướng dẫn như “Đổi màu váy theo màu của ảnh tham chiếu.”. Chỉnh sửa đã chuyển đúng màu mong muốn đồng thời giữ phần lớn cấu trúc cảnh gốc.

Theo quan sát của tôi, chỉnh sửa với một tham chiếu hoạt động tốt nhất khi prompt hẹp và có giới hạn. Chuyển màu và đổi màu trang phục đặc biệt đáng tin cậy vì không đòi hỏi thay đổi hình học lớn. Khi hướng dẫn chỉnh sửa tập trung vào một thuộc tính, danh tính chủ thể và chi tiết hậu cảnh vẫn ổn định.

Chỉnh sửa ảnh chỉ với prompt

Sau đó tôi thử chỉnh sửa chỉ bằng prompt với thay đổi ngữ nghĩa, như “Thay hậu cảnh bằng bãi biển.” Mô hình xử lý việc thay hậu cảnh gọn gàng, trong khi vẫn giữ chủ thể tương đối nhất quán. 

Khi hậu cảnh thay đổi, mô hình thường điều chỉnh nhiệt độ màu và cường độ bóng đổ để giữ cảm giác chân thực. Đây thường là một điểm cộng, nhưng cũng có nghĩa ảnh đã chỉnh sửa có thể trông như một buổi chụp khác chứ không chỉ dán ghép đơn giản.

Dẫn hướng tư thế

Tôi thử chỉnh sửa dựa trên tư thế bằng một ảnh tham chiếu gợi ý vị trí cơ thể, kết hợp với prompt như “Khớp tư thế từ ảnh tham chiếu.” Ảnh kết quả dịch chuyển tư thế chủ thể trong khi vẫn giữ danh tính và phong cách tương tự.

Đây là ảnh tham chiếu tôi dùng để dẫn hướng tư thế:

Chỉnh sửa tư thế là khả thi, nhưng nhạy cảm hơn so với chỉnh màu. Bất kỳ thay đổi tư thế nào cũng có thể kéo theo thay đổi thứ cấp như độ rủ vải, vị trí tay chân và khung hình. Tôi mất vài lần thử để có tư thế đúng, và mô hình vẫn gặp khó với vị trí chân.

Chỉnh sửa ảnh với nhiều ảnh tham chiếu

Cuối cùng, tôi thử chỉnh sửa đa tham chiếu với nhiều đầu vào, như một tham chiếu bảng màu và prompt chỉnh sửa nêu rõ “Chỉ thay đổi màu nền bằng bảng màu từ ảnh tham chiếu. Không thay nền bằng nội dung ảnh tham chiếu.” 

Thật bất ngờ, chỉnh sửa đa tham chiếu

hiệu quả nhất khi mỗi ảnh tham chiếu có vai trò rõ ràng. 

Tham chiếu bảng màu hoạt động tốt khi prompt nêu rõ chỉ dùng bảng màu và tránh hướng dẫn mô hình dùng nội dung tham chiếu để thay thế. 

Khi tham chiếu mơ hồ, mô hình có thể mượn kết cấu hoặc gợi ý bố cục thay vì chỉ màu sắc. Trong lần chạy của tôi, tôi thấy một vài tạo tác nhỏ nơi các yếu tố giống ảnh tham chiếu hơi “rò rỉ” vào cảnh, nhưng tổng thể kết quả vẫn tốt và nhất quán về mặt thị giác.

Một lợi ích thực tế của bản demo này là mọi ảnh đã tạo và chỉnh sửa đều được lưu trong lịch sử phiên. Bạn có thể tải bất kỳ mục trước đó và tiếp tục chỉnh sửa đúng từ mốc đó. Điều này giúp thử nghiệm nhanh hơn nhiều: bạn có thể rẽ nhánh chỉnh sửa từ phiên bản sớm hơn, so sánh nhiều hướng chỉnh sửa và tránh mất một kết quả trung gian tốt. 

Kết luận

Trong hướng dẫn này, chúng ta đã xây dựng một quy trình hoàn chỉnh để tạo và chỉnh sửa ảnh bằng FLUX.2 Klein 4B. Bằng cách kết hợp tạo text-to-image cục bộ qua Diffusers với API chỉnh sửa được Black Forest Labs lưu trữ, chúng ta đã tạo được một trình chỉnh sửa ảnh tương tác.

Độ trễ thấp, khả năng thống nhất giữa tạo và chỉnh sửa, cùng hỗ trợ đa tham chiếu của FLUX.2 Klein khiến nó đặc biệt phù hợp cho quy trình tương tác kiểu này. Từ đây, bạn có thể mở rộng ứng dụng với chỉnh sửa hàng loạt, điều khiển tham số, lưu bền qua các phiên, hoặc thậm chí một agent LLM đề xuất chỉnh sửa tự động.