Hugging Face's logo

Diffusers documentation

Shap-E

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Shap-E

Mô hình Shap-E được đề xuất trong Shap-E: Generating Conditional 3D Implicit Functions bởi Alex Nichol và Heewoo Jun từ OpenAI.

Tóm tắt từ bài báo là:

Chúng tôi giới thiệu Shap-E, một mô hình sinh có điều kiện cho tài sản 3D. Khác với các công trình gần đây về mô hình sinh 3D chỉ tạo ra một biểu diễn đầu ra duy nhất, Shap-E trực tiếp tạo ra các tham số của các hàm ẩn, có thể được render dưới dạng cả lưới có kết cấu (textured meshes) và trường bức xạ thần kinh (neural radiance fields). Chúng tôi huấn luyện Shap-E qua hai giai đoạn: đầu tiên, chúng tôi huấn luyện một bộ mã hóa (encoder) ánh xạ tất định các tài sản 3D thành các tham số của một hàm ẩn; thứ hai, chúng tôi huấn luyện một mô hình khuếch tán có điều kiện (conditional diffusion model) trên các đầu ra của bộ mã hóa. Khi được huấn luyện trên một tập dữ liệu lớn gồm các cặp dữ liệu 3D và văn bản, các mô hình kết quả của chúng tôi có khả năng tạo ra các tài sản 3D phức tạp và đa dạng chỉ trong vài giây. Khi so sánh với Point-E, một mô hình sinh tường minh (explicit generative model) trên các đám điểm (point clouds), Shap-E hội tụ nhanh hơn và đạt chất lượng mẫu tương đương hoặc tốt hơn, bất chấp việc mô hình hóa một không gian đầu ra đa chiều, đa biểu diễn hơn.

Mã nguồn gốc có thể được tìm thấy tại openai/shap-e.

Xem phần tái sử dụng các thành phần giữa các pipeline để tìm hiểu cách nạp các thành phần giống nhau vào nhiều pipeline một cách hiệu quả.

Hãy đảm bảo bạn đã cài đặt các thư viện sau.

# uncomment to install the necessary libraries in Colab
#!pip install -q diffusers transformers accelerate trimesh

Text-to-3D

Để tạo một gif của một đối tượng 3D, hãy truyền một prompt văn bản vào ShapEPipeline. Pipeline sẽ tạo ra một danh sách các khung hình được sử dụng để tạo đối tượng 3D.

import torch
from diffusers import ShapEPipeline

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

pipe = ShapEPipeline.from_pretrained("openai/shap-e", dtype=torch.float16, variant="fp16")
pipe = pipe.to(device)

guidance_scale = 15.0
prompt = ["A firecracker", "A birthday cupcake"]

images = pipe(
    prompt,
    guidance_scale=guidance_scale,
    num_inference_steps=64,
    frame_size=256,
).images

Bây giờ hãy sử dụng hàm export_to_gif() để chuyển đổi danh sách các khung hình ảnh thành một tệp gif của đối tượng 3D.

from diffusers.utils import export_to_gif

export_to_gif(images[0], "firecracker_3d.gif")
export_to_gif(images[1], "cake_3d.gif")
prompt = "Một quả pháo"
prompt = "A birthday cupcake"

Hình ảnh sang 3D

Để tạo một đối tượng 3D từ một hình ảnh khác, hãy sử dụng ShapEImg2ImgPipeline. Bạn có thể sử dụng một hình ảnh có sẵn hoặc tạo một hình ảnh hoàn toàn mới. Hãy sử dụng mô hình Kandinsky 2.1 để tạo một hình ảnh mới.

from diffusers import DiffusionPipeline
import torch

prior_pipeline = DiffusionPipeline.from_pretrained("kandinsky-community/kandinsky-2-1-prior", dtype=torch.float16, use_safetensors=True).to("cuda")  # or "mps", "xpu", "cpu"
pipeline = DiffusionPipeline.from_pretrained("kandinsky-community/kandinsky-2-1", dtype=torch.float16, use_safetensors=True).to("cuda")

prompt = "A cheeseburger, white background"

image_embeds, negative_image_embeds = prior_pipeline(prompt, guidance_scale=1.0).to_tuple()
image = pipeline(
    prompt,
    image_embeds=image_embeds,
    negative_image_embeds=negative_image_embeds,
).images[0]

image.save("burger.png")

Truyền cheeseburger vào ShapEImg2ImgPipeline để tạo ra biểu diễn 3D của nó.

from PIL import Image
from diffusers import ShapEImg2ImgPipeline
from diffusers.utils import export_to_gif

pipe = ShapEImg2ImgPipeline.from_pretrained("openai/shap-e-img2img", dtype=torch.float16, variant="fp16").to("cuda")  # or "mps", "xpu", "cpu"

guidance_scale = 3.0
image = Image.open("burger.png").resize((256, 256))

images = pipe(
    image,
    guidance_scale=guidance_scale,
    num_inference_steps=64,
    frame_size=256,
).images

gif_path = export_to_gif(images[0], "burger_3d.gif")
cheeseburger
Bánh burger phô mai 3D

Tạo lưới

Shap-E là một mô hình linh hoạt, có thể tạo ra các đầu ra lưới (mesh) có kết cấu để hiển thị cho các ứng dụng tiếp theo. Trong ví dụ này, bạn sẽ chuyển đổi đầu ra thành tệp glb vì thư viện 🤗 Datasets hỗ trợ trực quan hóa lưới của các tệp glb, có thể được hiển thị bởi Dataset viewer.

Bạn có thể tạo ra đầu ra dạng lưới (mesh) cho cả ShapEPipeline và ShapEImg2ImgPipeline bằng cách chỉ định tham số output_type là "mesh":

import torch
from diffusers import ShapEPipeline

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

pipe = ShapEPipeline.from_pretrained("openai/shap-e", dtype=torch.float16, variant="fp16")
pipe = pipe.to(device)

guidance_scale = 15.0
prompt = "A birthday cupcake"

images = pipe(prompt, guidance_scale=guidance_scale, num_inference_steps=64, frame_size=256, output_type="mesh").images

Sử dụng hàm export_to_ply() để lưu kết quả lưới dưới dạng tệp ply:

Bạn có thể tùy chọn lưu đầu ra lưới dưới dạng tệp obj bằng hàm export_to_obj(). Khả năng lưu đầu ra lưới ở nhiều định dạng khác nhau giúp việc sử dụng ở các bước tiếp theo linh hoạt hơn!

from diffusers.utils import export_to_ply

ply_path = export_to_ply(images[0], "3d_cake.ply")
print(f"Saved to folder: {ply_path}")

Sau đó, bạn có thể chuyển đổi tệp ply sang tệp glb bằng thư viện trimesh:

import trimesh

mesh = trimesh.load("3d_cake.ply")
mesh_export = mesh.export("3d_cake.glb", file_type="glb")

Mặc định, đầu ra lưới được tập trung từ góc nhìn phía dưới, nhưng bạn có thể thay đổi góc nhìn mặc định bằng cách áp dụng phép biến đổi xoay:

import trimesh
import numpy as np

mesh = trimesh.load("3d_cake.ply")
rot = trimesh.transformations.rotation_matrix(-np.pi / 2, [1, 0, 0])
mesh = mesh.apply_transform(rot)
mesh_export = mesh.export("3d_cake.glb", file_type="glb")

Tải tệp mesh lên kho dữ liệu của bạn để xem trực quan hóa nó với Dataset viewer!

ShapEPipeline

lớp diffusers.ShapEPipeline

< >

( prior: PriorTransformertext_encoder: CLIPTextModelWithProjectiontokenizer: CLIPTokenizerscheduler: HeunDiscreteSchedulershap_e_renderer: ShapERenderer )

Tham số

  • prior (PriorTransformer) — Prior chuẩn của unCLIP để xấp xỉ embedding ảnh từ embedding văn bản.
  • text_encoder (CLIPTextModelWithProjection) — Bộ mã hóa văn bản đóng băng.
  • tokenizer (CLIPTokenizer) — Một CLIPTokenizer để tách token cho văn bản.
  • scheduler (HeunDiscreteScheduler) — Một scheduler được sử dụng kết hợp với mô hình prior để tạo embedding ảnh.
  • shap_e_renderer (ShapERenderer) — Trình render Shap-E chiếu các latent đã tạo thành các tham số của một MLP để tạo ra các đối tượng 3D bằng phương pháp render NeRF.

Pipeline để tạo biểu diễn ẩn của tài sản 3D và render bằng phương pháp NeRF.

Mô hình này kế thừa từ DiffusionPipeline. Xem tài liệu của lớp cha để biết các phương thức chung được triển khai cho tất cả các pipeline (tải xuống, lưu, chạy trên một thiết bị cụ thể, v.v.).

__call__

< >

( prompt: strnum_images_per_prompt: int = 1num_inference_steps: int = 25generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneguidance_scale: float = 4.0frame_size: int = 64output_type: str | None = 'pil'return_dict: bool = True ) → ShapEPipelineOutput or tuple

Tham số

  • prompt (str hoặc list[str]) — Prompt hoặc các prompt để định hướng việc tạo ảnh.
  • 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.
  • num_inference_steps (int, tùy chọn, mặc định là 25) — 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.
  • generator (torch.Generator hoặc list[torch.Generator], tùy chọn) — Một torch.Generator để làm cho quá trình sinh ra kết quả xác đị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ụng generator ngẫu nhiên được cung cấp.
  • guidance_scale (float, tùy chọn, mặc định là 4.0) — Giá trị guidance scale cao hơn khuyến khích mô hình tạo ra các hình ảnh gắn kết chặt chẽ với prompt văn bản, với cái giá là chất lượng hình ảnh thấp hơn. Guidance scale được kích hoạt khi guidance_scale > 1.
  • frame_size (int, tùy chọn, mặc định là 64) — Chiều rộng và chiều cao của mỗi khung hình trong kết quả 3D được tạo ra.
  • 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.Image), "np" (np.array), "latent" (torch.Tensor), hoặc mesh (MeshDecoderOutput).
  • return_dict (bool, tùy chọn, mặc định là True) — Có nên trả về một ShapEPipelineOutput thay vì một tuple thông thường hay không.

Trả về

ShapEPipelineOutput hoặc tuple

Nếu return_dict là True, ShapEPipelineOutput sẽ được trả về, ngoài ra một tuple sẽ được trả về trong đó phần tử đầu tiên là một danh sách chứa các hình ảnh đã được tạo.

Hàm gọi call của pipeline để tạo nội dung.

Ví dụ:

>>> import torch
>>> from diffusers import DiffusionPipeline
>>> from diffusers.utils import export_to_gif

>>> device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

>>> repo = "openai/shap-e"
>>> pipe = DiffusionPipeline.from_pretrained(repo, torch_dtype=torch.float16)
>>> pipe = pipe.to(device)

>>> guidance_scale = 15.0
>>> prompt = "a shark"

>>> images = pipe(
...     prompt,
...     guidance_scale=guidance_scale,
...     num_inference_steps=64,
...     frame_size=256,
... ).images

>>> gif_path = export_to_gif(images[0], "shark_3d.gif")

ShapEImg2ImgPipeline

lớp diffusers.ShapEImg2ImgPipeline

< >

( prior: PriorTransformerimage_encoder: CLIPVisionModelimage_processor: CLIPImageProcessorPilscheduler: HeunDiscreteSchedulershap_e_renderer: ShapERenderer )

Tham số

  • prior (PriorTransformer) — Prior chuẩn của unCLIP để xấp xỉ embedding ảnh từ embedding văn bản.
  • image_encoder (CLIPVisionModel) — Bộ mã hóa ảnh được đóng băng.
  • image_processor (CLIPImageProcessor) — Một CLIPImageProcessor để xử lý hình ảnh.
  • scheduler (HeunDiscreteScheduler) — Một scheduler được sử dụng kết hợp với mô hình prior để tạo embedding ảnh.
  • shap_e_renderer (ShapERenderer) — Trình render Shap-E chiếu các latent đã tạo thành các tham số của một MLP để tạo ra các đối tượng 3D bằng phương pháp render NeRF.

Pipeline để tạo biểu diễn ẩn của tài sản 3D và render bằng phương pháp NeRF từ một hình ảnh.

Mô hình này kế thừa từ DiffusionPipeline. Xem tài liệu của lớp cha để biết các phương thức chung được triển khai cho tất cả các pipeline (tải xuống, lưu, chạy trên một thiết bị cụ thể, v.v.).

__call__

< >

( image: PIL.Image.Image | list[PIL.Image.Image]num_images_per_prompt: int = 1num_inference_steps: int = 25generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneguidance_scale: float = 4.0frame_size: int = 64output_type: str | None = 'pil'return_dict: bool = True ) → ShapEPipelineOutput or tuple

Tham số

  • image (torch.Tensor, PIL.Image.Image, np.ndarray, list[torch.Tensor], list[PIL.Image.Image] hoặc list[np.ndarray]) — Image hoặc tensor đại diện cho một lô ảnh (image batch) được sử dụng làm điểm khởi đầu. Cũng có thể nhận các image latents dưới dạng image, nhưng nếu truyền trực tiếp latents thì chúng sẽ không được mã hóa lại.
  • 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.
  • num_inference_steps (int, tùy chọn, mặc định là 25) — 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.
  • generator (torch.Generator hoặc list[torch.Generator], tùy chọn) — Một torch.Generator để làm cho quá trình sinh ra kết quả xác đị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ụng generator ngẫu nhiên được cung cấp.
  • guidance_scale (float, tùy chọn, mặc định là 4.0) — Giá trị guidance scale cao hơn khuyến khích mô hình tạo ra các hình ảnh gắn kết chặt chẽ với prompt văn bản, với cái giá là chất lượng hình ảnh thấp hơn. Guidance scale được kích hoạt khi guidance_scale > 1.
  • frame_size (int, tùy chọn, mặc định là 64) — Chiều rộng và chiều cao của mỗi khung hình trong kết quả 3D được tạo ra.
  • 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.Image), "np" (np.array), "latent" (torch.Tensor), hoặc mesh (MeshDecoderOutput).
  • return_dict (bool, tùy chọn, mặc định là True) — Có nên trả về một ShapEPipelineOutput thay vì một tuple thông thường hay không.

Trả về

ShapEPipelineOutput hoặc tuple

Nếu return_dict là True, ShapEPipelineOutput sẽ được trả về, ngoài ra một tuple sẽ được trả về trong đó phần tử đầu tiên là một danh sách chứa các hình ảnh đã được tạo.

Hàm gọi call của pipeline để tạo nội dung.

Ví dụ:

>>> from PIL import Image
>>> import torch
>>> from diffusers import DiffusionPipeline
>>> from diffusers.utils import export_to_gif, load_image

>>> device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

>>> repo = "openai/shap-e-img2img"
>>> pipe = DiffusionPipeline.from_pretrained(repo, torch_dtype=torch.float16)
>>> pipe = pipe.to(device)

>>> guidance_scale = 3.0
>>> image_url = "https://hf.co/datasets/diffusers/docs-images/resolve/main/shap-e/corgi.png"
>>> image = load_image(image_url).convert("RGB")

>>> images = pipe(
...     image,
...     guidance_scale=guidance_scale,
...     num_inference_steps=64,
...     frame_size=256,
... ).images

>>> gif_path = export_to_gif(images[0], "corgi_3d.gif")

ShapEPipelineOutput

lớp diffusers.pipelines.shap_e.pipeline_shap_e.ShapEPipelineOutput

< >

( images: list[list[PIL.Image.Image]] | list[list[numpy.ndarray]] )

Tham số

  • images (torch.Tensor) — Một danh sách các hình ảnh để render 3D.

Lớp đầu ra cho ShapEPipeline và ShapEImg2ImgPipeline.

Update on GitHub

←SANA-WM Stable Cascade→