使用说明

Hunyuan3D Mac本地安装指南（苹果硅）

本指南将指导您在苹果硅（M1/M2/M3/M4）的Mac上本地设置腾讯的浑源3D-2。这使得可以从图像中免费生成本地3D模型，而无需依赖云API。

需求

硬件

带苹果硅的Mac （M1、M2、M3或M4）
最低16GB RAM （建议使用32GB+以获得更好的性能）
50GB+可用磁盘空间 （适用于模型和缓存）

软件

macOS 12.0+ （蒙特利或更高版本，索诺玛推荐）
家酿（包管理器）
Python 3.10 （通过Homebrew安装）

安装

步骤1：安装Homebrew（如果尚未安装）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

第二步：安装Python 3.10

brew install python@3.10

步骤3：安装Rust（某些依赖项需要）

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

步骤4：创建项目目录和虚拟环境

# Create directory
mkdir -p ~/Hunyuan3D
cd ~/Hunyuan3D

# Create virtual environment with Python 3.10
/opt/homebrew/bin/python3.10 -m venv hy3d-venv

# Activate virtual environment
source hy3d-venv/bin/activate

第五步：克隆浑源3D-2库

git clone https://github.com/Tencent/Hunyuan3D-2.git
cd Hunyuan3D-2

步骤6：安装带有MPS支持的PyTorch

pip install --upgrade pip
pip install torch torchvision torchaudio

步骤7：安装依赖项

pip install -r requirements.txt

步骤8：验证MPS（金属性能着色器）是否可用

python -c "import torch; print(f'MPS available: {torch.backends.mps.is_available()}')"

您应该看到： MPS available: True

步骤9：下载预训练模型

模型将在首次使用时自动下载，但您可以预先下载：

python -c "
from huggingface_hub import snapshot_download
snapshot_download(repo_id='tencent/Hunyuan3D-2', local_dir='./weights/Hunyuan3D-2')
"

注：这将下载大约20-30GB的模型重量。

运行浑源3D

选项1：使用启动脚本（推荐）

在以下位置创建启动脚本 ~/Hunyuan3D/start_hunyuan3d.sh:

#!/bin/bash
# Hunyuan3D Startup Script for Mac M4
# Starts both the Gradio Web UI and the API Server

cd ~/Hunyuan3D
source hy3d-venv/bin/activate
cd Hunyuan3D-2

echo "=========================================="
echo "  Hunyuan3D Local Server for Mac M4"
echo "=========================================="
echo ""
echo "Starting servers..."
echo ""

# Start API server in background on port 8081
echo "[1/2] Starting API Server on port 8081..."
python api_server.py --device mps --port 8081 &
API_PID=$!
echo "      API Server PID: $API_PID"

# Give API server a moment to start
sleep 2

# Start Gradio UI on port 7860
echo "[2/2] Starting Gradio Web UI on port 7860..."
python gradio_app.py --device mps --port 7860 &
GRADIO_PID=$!
echo "      Gradio UI PID: $GRADIO_PID"

echo ""
echo "=========================================="
echo "  Servers Starting..."
echo "=========================================="
echo ""
echo "  Web UI:  http://localhost:7860"
echo "  API:     http://localhost:8081"
echo ""
echo "  Note: Texture generation is disabled (requires CUDA)"
echo "        Shape generation works on MPS!"
echo ""
echo "  Press Ctrl+C to stop both servers"
echo "=========================================="
echo ""

# Function to cleanup on exit
cleanup() {
    echo ""
    echo "Shutting down servers..."
    kill $API_PID 2>/dev/null
    kill $GRADIO_PID 2>/dev/null
    echo "Done."
    exit 0
}

# Trap Ctrl+C and call cleanup
trap cleanup SIGINT SIGTERM

# Wait for both processes
wait

使其可执行并运行：

chmod +x ~/Hunyuan3D/start_hunyuan3d.sh
~/Hunyuan3D/start_hunyuan3d.sh

选项2：单独运行服务器

仅限Gradio Web用户界面：

cd ~/Hunyuan3D
source hy3d-venv/bin/activate
cd Hunyuan3D-2
python gradio_app.py --device mps --port 7860

仅限API服务器：

cd ~/Hunyuan3D
source hy3d-venv/bin/activate
cd Hunyuan3D-2
python api_server.py --device mps --port 8081

选项3：添加外壳别名（方便）

添加到您的 ~/.zshrc:

echo 'alias hunyuan3d="~/Hunyuan3D/start_hunyuan3d.sh"' >> ~/.zshrc
source ~/.zshrc

现在，您可以通过键入以下内容来启动一切： hunyuan3d

用法

Web用户界面（Gradio）

打开浏览器 http://localhost:7860
上传图像（透明背景的PNG效果最好）
必要时调整设置：
- 八叉树决议： 更高=更详细（默认值：256）
- 推理步骤： 更多步骤=更好的质量（默认值：20）
- 指导规模： 控制对输入的遵守（默认值：5.5）
点击生成
下载结果 .glb 文件

API服务器

API服务器运行于 http://localhost:8081 并接受POST请求。

终点：

端点	方法	描述
`/generate`	POST	从图像生成3D模型
`/status/{uid}`	GET	检查生成状态

示例API调用（Python）：

import requests
import base64

# Load and encode image
with open("my_image.png", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

# Send request
response = requests.post(
    "http://localhost:8081/generate",
    json={
        "image": image_b64,
        "num_inference_steps": 20,
        "octree_resolution": 256,
        "guidance_scale": 5.5
    }
)

# Save result
with open("output.glb", "wb") as f:
    f.write(response.content)

Python脚本（直接使用）

from PIL import Image
from hy3dgen.rembg import BackgroundRemover
from hy3dgen.shapegen import Hunyuan3DDiTFlowMatchingPipeline

# Load pipeline
pipeline = Hunyuan3DDiTFlowMatchingPipeline.from_pretrained(
    'tencent/Hunyuan3D-2', 
    device='mps'
)

# Load and preprocess image
image = Image.open('my_image.png').convert('RGBA')
rembg = BackgroundRemover()
image = rembg(image)

# Generate 3D mesh
mesh = pipeline(image=image, num_inference_steps=30)[0]

# Export
mesh.export('output.glb')

与Blender MCP集成

如果你正在使用搅拌机MCP 插件：

在Blender中，按 N 打开侧边栏
找到 搅拌机MCP 面板
检查 “使用腾讯浑源3D模型生成”
将API URL设置为： http://localhost:8081
配置设置：
- 八叉树分辨率：256
- 推理步骤数：20
- 引导尺度：5.5

现在，您可以使用本地Hunyuan3D实例直接从Blender中生成3D模型！

局限性

Mac上的工作原理（MPS）

✅ 形状生成 -从图像生成完整的3D网格
✅ 背景移除 -通过rembg自动
✅ 多种型号变体 -全型、迷你型和涡轮增压型

什么在Mac上不起作用

❌ 纹理生成 -需要CUDA（仅限NVIDIA GPU）
- 自定义光栅化器需要CUDA进行编译
- 生成的网格将不进行纹理处理（白色/灰色）
⚠️ 演出 -比NVIDIA GPU慢（预计每代3-5分钟）

纹理解决方法

您可以在Blender中手动添加材质，也可以在生成后使用其他纹理工具。

故障排除

“MPS可用：错误”

确保你使用的是Homebrew的Python，而不是系统Python
重新安装PyTorch： pip install --force-reinstall torch torchvision torchaudio

“没有名为'custom_rasterizer'的模块”

这在Mac上是意料之中的——它只需要用于纹理生成
形状生成仍然有效

生成空网格/立方体网格

确保您的输入图像具有 透明或实心背景
使用背景去除器：具有复杂背景的图像可能会失败
尝试增加 num_inference_steps 至30

内存不足错误

关闭其他应用程序以释放RAM
尝试迷你型号：使用 tencent/Hunyuan3D-2mini 而
减少 octree_resolution 到128

端口已在使用中

检查现有流程： lsof -i :7860 或 lsof -i :8081
杀了他们： pkill -f gradio_app 或 pkill -f api_server

缓慢的一代

首次运行下载模式（~20GB）-后续运行速度更快
MPS比CUDA慢-预计每代3-5分钟
迷你涡轮模型速度更快，但质量较低

文件位置

项目	位置
虚拟环境	`~/Hunyuan3D/hy3d-venv/`
源代码	`~/Hunyuan3D/Hunyuan3D-2/`
启动脚本	`~/Hunyuan3D/start_hunyuan3d.sh`
模型缓存	`~/.cache/huggingface/hub/`
Gradio缓存	`~/Hunyuan3D/Hunyuan3D-2/gradio_cache/`

停止服务器

如果使用启动脚本，请按 Ctrl+C 停止两台服务器。

要手动停止，请执行以下操作：

pkill -f gradio_app.py
pkill -f api_server.py

积分

浑源3D-2 腾讯
搅拌机MCP 用于Blender集成

最后更新日期：2024年12月