Image-to-3D 技术文档
基于腾讯混元 Hunyuan 3D API 的图片转 3D 模型服务
目录
0. 3D 模型基础知识
0.1 什么是 3D 模型
3D 模型是用三维坐标系统（X、Y、Z 轴）描述的虚拟物体，由以下核心元素组成：
| 元素 | 说明 |
|---|---|
| 顶点 (Vertex) | 3D 空间中的点，由 (x, y, z) 坐标定义 |
| 边 (Edge) | 连接两个顶点的线段 |
| 面 (Face) | 由 3 个或更多顶点围成的平面，通常为三角形 |
| 网格 (Mesh) | 由顶点、边、面组成的完整几何结构 |
| 法线 (Normal) | 垂直于面的向量，决定光照效果 |
| UV 坐标 | 2D 贴图映射到 3D 表面的坐标系统 |
0.2 常见 3D 文件格式
| 格式 | 扩展名 | 特点 | 适用场景 |
|---|---|---|---|
| OBJ | .obj |
开放格式，纯文本，广泛支持 | 通用交换格式 |
| MTL | .mtl |
OBJ 的材质定义文件 | 配合 OBJ 使用 |
| GLB/GLTF | .glb/.gltf |
现代 Web 标准，支持动画和 PBR | Web 3D、AR/VR |
| FBX | .fbx |
Autodesk 格式，支持动画和骨骼 | 游戏开发、影视 |
| USDZ | .usdz |
Apple 专用格式 | iOS AR Quick Look |
| STL | .stl |
仅几何数据，无颜色/材质 | 3D 打印 |
OBJ 文件结构示例
# 顶点定义
v 0.0 0.0 0.0
v 1.0 0.0 0.0
v 1.0 1.0 0.0
v 0.0 1.0 0.0
# 纹理坐标
vt 0.0 0.0
vt 1.0 0.0
vt 1.0 1.0
vt 0.0 1.0
# 法线
vn 0.0 0.0 1.0
# 面定义 (顶点/纹理/法线)
f 1/1/1 2/2/1 3/3/1 4/4/10.3 材质与贴图
传统材质属性
| 属性 | 说明 |
|---|---|
| Diffuse (漫反射) | 物体的基本颜色 |
| Specular (高光) | 反射光的颜色和强度 |
| Ambient (环境光) | 环境光照下的颜色 |
| Emissive (自发光) | 物体自身发出的光 |
PBR 材质 (基于物理的渲染)
PBR (Physically Based Rendering) 是现代 3D 渲染的标准，更真实地模拟光照：
| 贴图类型 | 说明 | 文件示例 |
|---|---|---|
| Albedo/Base Color | 基础颜色，不含光照信息 | texture_albedo.png |
| Normal Map | 法线贴图，模拟表面细节 | texture_normal.png |
| Metallic | 金属度，0=非金属，1=金属 | texture_metallic.png |
| Roughness | 粗糙度，0=光滑，1=粗糙 | texture_roughness.png |
| AO (Ambient Occlusion) | 环境光遮蔽，增加深度感 | texture_ao.png |
PBR 工作流程:
┌─────────────┐
│ Base Color │──┐
└─────────────┘ │
┌─────────────┐ │ ┌─────────────┐
│ Metallic │──┼───>│ PBR 着色器 │───> 最终渲染
└─────────────┘ │ └─────────────┘
┌─────────────┐ │
│ Roughness │──┤
└─────────────┘ │
┌─────────────┐ │
│ Normal │──┘
└─────────────┘0.4 3D 坐标系统
不同软件使用不同的坐标系统：
| 软件/引擎 | 上方向 | 前方向 | 坐标系 |
|---|---|---|---|
| Blender | +Z | -Y | 右手系 |
| Unity | +Y | +Z | 左手系 |
| Unreal | +Z | +X | 左手系 |
| Three.js/Babylon.js | +Y | -Z | 右手系 |
| OpenGL | +Y | -Z | 右手系 |
0.5 多边形与面数
| 术语 | 说明 |
|---|---|
| Polygon (多边形) | 由多个顶点组成的面 |
| Triangle (三角形) | 最基本的面，3 个顶点 |
| Quad (四边形) | 4 个顶点的面，渲染时会分成 2 个三角形 |
| Face Count (面数) | 模型的三角形总数 |
| Polycount | 多边形数量，影响渲染性能 |
面数参考：
| 用途 | 推荐面数 |
|---|---|
| 移动端游戏 | 1K - 10K |
| PC 游戏 | 10K - 100K |
| 影视级别 | 100K - 数百万 |
| 本项目默认 | 1,000,000 (100 万) |
0.6 AI 生成 3D 模型的原理
本项目使用的腾讯混元 3D API 基于以下技术：
┌─────────────────────────────────────────────────────────────┐
│ AI 3D 生成流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ 2D 图片 │───>│ 深度估计 │───>│ 点云生成 │ │
│ └─────────┘ │ (Depth Est.)│ │ (Point Cloud) │ │
│ └─────────────┘ └──────────┬──────────┘ │
│ │ │
│ ▼ │
│ ┌─────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ 3D 模型 │<───│ 网格重建 │<───│ 表面重建 │ │
│ │ + 贴图 │ │ (Meshing) │ │ (Surface Recon.) │ │
│ └─────────┘ └─────────────┘ └─────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘多视角输入的优势：
| 输入方式 | 优点 | 缺点 |
|---|---|---|
| 单图 | 简单快速 | 背面细节靠推测 |
| 多视角 | 更准确的几何形状 | 需要更多图片 |
0.7 Web 3D 渲染引擎
本项目前端使用 Babylon.js 进行 3D 渲染：
| 引擎 | 特点 | 适用场景 |
|---|---|---|
| Babylon.js | 功能全面，TypeScript 原生支持 | 企业级应用 |
| Three.js | 轻量灵活，社区活跃 | 创意项目 |
| PlayCanvas | 可视化编辑器 | 游戏开发 |
| A-Frame | 声明式 VR | WebVR 应用 |
Babylon.js 渲染管线：
场景 (Scene)
│
├── 相机 (Camera)
│ └── ArcRotateCamera (环绕相机)
│
├── 灯光 (Lights)
│ ├── HemisphericLight (半球光)
│ ├── DirectionalLight (方向光)
│ └── PointLight (点光源)
│
├── 网格 (Meshes)
│ ├── 导入的 3D 模型
│ └── 地面网格
│
└── 后处理 (Post-Processing)
├── FXAA 抗锯齿
├── 色调映射
└── 阴影1. 项目概述
1.1 业务背景
本项目旨在解决 2D 图片到 3D 模型转换的需求，主要应用场景包括：
- 电商产品展示：将产品图片转换为可交互的 3D 模型
- 室内设计：家具、装饰品的 3D 可视化
- 数字资产管理：统一管理和分享 3D 模型资源
1.2 核心功能
| 功能模块 | 描述 |
|---|---|
| 2D 转 3D | 上传图片自动生成 3D 模型（OBJ + PBR 贴图） |
| 多视角支持 | 支持主图 + 背/左/右视图，提升生成质量 |
| 3D 模型库 | 上传、管理、预览、分享 3D 模型资产 |
| 实时进度 | 任务进度百分比实时更新 |
| 多语言 | 中英文界面切换 |
| 插件生态 | Blender 插件支持 |
1.3 版本信息
- 当前版本: v1.1.0
- 最后更新: 2025-01-29
2. 系统架构
2.1 整体架构图
┌─────────────────────────────────────────────────────────────────┐
│ 用户层 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
│ │ Web 前端 │ │ Blender 插件│ │ MagicPlan (移动端) │ │
│ └──────┬──────┘ └──────┬──────┘ └───────────┬─────────────┘ │
└─────────┼────────────────┼─────────────────────┼────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ API 网关层 │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ FastAPI (RESTful API) ││
│ │ /api/tasks │ /api/models │ /api/plugins │ /health ││
│ └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 业务服务层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ TaskService │ │HunyuanService│ │ Scheduler │ │
│ │ 任务管理 │ │ API 适配器 │ │ 后台任务调度 │ │
│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────────────────────────────────┐
│ PostgreSQL │ │ 腾讯混元 Hunyuan 3D API │
│ 数据持久化 │ │ (外部 AI 服务) │
└─────────────────┘ └─────────────────────────────────────────────┘2.2 目录结构
.
├── backend/ # 后端服务
│ ├── main.py # FastAPI 入口
│ ├── config.py # 配置管理
│ ├── database.py # 数据库连接
│ ├── models/ # 数据模型 (SQLAlchemy + Pydantic)
│ ├── routers/ # API 路由
│ ├── services/ # 业务逻辑层
│ └── storage/ # 文件存储
├── frontend/ # 前端应用
│ ├── src/
│ │ ├── api/ # API 调用封装
│ │ ├── components/ # React 组件
│ │ ├── hooks/ # 自定义 Hooks
│ │ └── i18n/ # 国际化
│ └── ...
├── docs/ # 文档
├── scripts/ # 运维脚本
└── docker-compose.yml # Docker 编排3. 技术栈
3.1 后端技术
| 技术 | 版本 | 用途 |
|---|---|---|
| Python | 3.11+ | 主语言 |
| FastAPI | 0.100+ | Web 框架 |
| SQLAlchemy | 2.0+ | ORM |
| asyncpg | - | PostgreSQL 异步驱动 |
| Pydantic | 2.0+ | 数据验证 |
| httpx | - | 异步 HTTP 客户端 |
| aiofiles | - | 异步文件操作 |
3.2 前端技术
| 技术 | 版本 | 用途 |
|---|---|---|
| React | 18+ | UI 框架 |
| TypeScript | 5.0+ | 类型安全 |
| Vite | 5.0+ | 构建工具 |
| Tailwind CSS | 3.0+ | 样式框架 |
| Babylon.js | 6.0+ | 3D 渲染引擎 |
| Axios | - | HTTP 客户端 |
3.3 基础设施
| 组件 | 用途 |
|---|---|
| PostgreSQL 15 | 关系型数据库 |
| Docker | 容器化部署 |
| Nginx | 前端静态服务 |
4. 后端架构
4.1 分层设计
┌─────────────────────────────────────────────────────────────┐
│ Routers (路由层) │
│ tasks.py │ models.py │ plugins.py │
│ 处理 HTTP 请求/响应，参数验证，错误处理 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Services (服务层) │
│ task_service.py │ hunyuan_service.py │ scheduler.py │
│ 核心业务逻辑，事务管理，外部 API 调用 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Models (数据层) │
│ task.py │ model3d.py │ schemas.py │
│ 数据库模型定义，Pydantic 请求/响应模型 │
└─────────────────────────────────────────────────────────────┘4.2 核心服务
4.2.1 TaskService - 任务服务
负责 2D 转 3D 任务的完整生命周期管理：
python
class TaskService:
# 核心方法
async def create_task() # 创建任务，提交到 Hunyuan API
async def get_task() # 获取任务详情
async def get_tasks() # 分页查询任务列表
async def sync_task() # 同步任务状态
async def retry_task() # 重试失败任务
async def get_task_progress() # 获取任务进度
async def delete_task() # 删除任务关键特性：
- 支持多视角图片上传（主图 + 背/左/右视图）
- 自动计算预估耗时（基于历史任务平均值）
- 异步下载并解压结果文件（ZIP → OBJ + MTL + 贴图）
4.2.2 HunyuanService - API 适配器
封装腾讯混元 3D API 的调用：
python
class HunyuanService:
async def submit_job() # 提交 3D 生成任务
async def query_job() # 查询任务状态API 参数：
Model: "3.1" (模型版本)EnablePBR: true (启用 PBR 材质)FaceCount: 1000000 (面数限制)MultiViewImages: 多视角图片数组
4.2.3 Scheduler - 后台调度器
定时轮询未完成任务，自动同步状态：
python
class TaskScheduler:
interval = 30 # 轮询间隔（秒）
async def _sync_pending_tasks() # 同步所有 PENDING/PROCESSING 任务4.3 配置管理
python
class Settings:
# Hunyuan API
HUNYUAN_API_KEY: str
HUNYUAN_BASE_URL: str = "https://api.ai3d.cloud.tencent.com"
# 数据库
DATABASE_URL: str = "postgresql+asyncpg://..."
# 文件存储
UPLOADS_PATH: Path # 上传文件目录
RESULTS_PATH: Path # 结果文件目录
MODELS_PATH: Path # 模型库目录
# 上传限制
MAX_UPLOAD_SIZE: int = 4 * 1024 * 1024 # 4MB
MIN_RESOLUTION: int = 128
MAX_RESOLUTION: int = 50005. 前端架构
5.1 组件结构
src/
├── App.tsx # 主应用入口
├── api/
│ ├── tasks.ts # 任务 API 封装
│ └── models.ts # 模型库 API 封装
├── components/
│ ├── UploadWithPreview.tsx # 上传 + 预览组件
│ ├── ModelViewer.tsx # 3D 模型查看器
│ ├── TaskList.tsx # 任务列表
│ ├── TaskDetailModal.tsx # 任务详情弹窗
│ ├── ModelLibrary.tsx # 模型库页面
│ └── ...
├── hooks/
│ └── useTaskPolling.ts # 任务轮询 Hook
└── i18n/
├── translations.ts # 翻译文本
└── LanguageContext.tsx # 语言上下文5.2 核心组件
5.2.1 ModelViewer - 3D 渲染器
基于 Babylon.js 实现的 3D 模型查看器：
功能特性：
- 支持 OBJ/GLB/GLTF 格式
- 网格地面 + 坐标轴显示
- 模型尺寸显示
- 缩放/旋转控制
- 全屏模式
- PBR 材质渲染
- 软阴影效果
渲染配置：
typescript
// 灯光系统
- HemisphericLight (环境光)
- DirectionalLight (主方向光 + 阴影)
- PointLight x2 (补光 + 背光)
// 后处理
- FXAA 抗锯齿
- 色调映射
- 对比度/曝光调整5.2.2 useTaskPolling - 任务轮询
typescript
const POLL_INTERVAL = 5000 // 5秒轮询
const MAX_POLL_TIME = 600000 // 10分钟超时
function useTaskPolling(taskId, options) {
// 自动同步任务状态
// 状态变化时触发回调
// 完成/失败时停止轮询
}5.3 国际化
支持中英文切换，翻译文件结构：
typescript
const translations = {
zh: {
appTitle: 'Image to 3D',
generateBtn: '生成3D模型',
// ...
},
en: {
appTitle: 'Image to 3D',
generateBtn: 'Generate 3D Model',
// ...
}
}6. 数据模型
6.1 ER 图
┌─────────────────────┐ ┌─────────────────────┐
│ tasks │ │ task_files │
├─────────────────────┤ ├─────────────────────┤
│ id (PK, UUID) │──┐ │ id (PK, UUID) │
│ job_id (UNIQUE) │ │ │ task_id (FK) │──┐
│ status (ENUM) │ └───>│ file_type (ENUM) │ │
│ original_image_path │ │ filename │ │
│ back_image_path │ │ file_path │ │
│ left_image_path │ │ file_size │ │
│ right_image_path │ │ source_url │ │
│ thumbnail_path │ │ created_at │ │
│ model_path │ └─────────────────────┘ │
│ error_message │ │
│ task_cost │ ┌─────────────────────┐ │
│ estimated_cost │ │ models │ │
│ started_at │ ├─────────────────────┤ │
│ completed_at │ │ id (PK, UUID) │──┼──┐
│ created_at │ │ name │ │ │
│ updated_at │ │ sku │ │ │
└─────────────────────┘ │ category │ │ │
│ preview_model_path │ │ │
│ thumbnail_path │ │ │
│ storage_path │ │ │
│ created_at │ │ │
│ updated_at │ │ │
└─────────────────────┘ │ │
│ │
┌─────────────────────┐ │ │
│ model_files │ │ │
├─────────────────────┤ │ │
│ id (PK, UUID) │ │ │
│ model_id (FK) │<─┼──┘
│ file_type (ENUM) │ │
│ filename │ │
│ file_path │ │
│ file_size │ │
│ created_at │ │
└─────────────────────┘ │
│
CASCADE DELETE ──────────┘6.2 枚举类型
python
# 任务状态
class TaskStatus(str, Enum):
PENDING = "PENDING" # 等待处理
PROCESSING = "PROCESSING" # 处理中
DONE = "DONE" # 完成
FAILED = "FAILED" # 失败
# 任务文件类型
class FileType(str, Enum):
GLB = "glb"
OBJ = "obj"
MTL = "mtl"
TEXTURE = "texture"
PREVIEW = "preview"
# 模型文件类型
class ModelFileType(str, Enum):
OBJ = "obj"
GLB = "glb"
FBX = "fbx"
GLTF = "gltf"
MTL = "mtl"
TEXTURE = "texture"6.3 关键字段说明
| 字段 | 说明 |
|---|---|
job_id |
Hunyuan API 返回的任务 ID |
task_cost |
实际耗时（毫秒） |
estimated_cost |
预估耗时（基于历史平均值） |
started_at |
任务开始处理时间 |
completed_at |
任务完成时间 |
7. API 接口设计
7.1 任务接口
| 方法 | 路径 | 说明 |
|---|---|---|
POST |
/api/tasks |
创建任务（上传图片） |
GET |
/api/tasks |
获取任务列表 |
GET |
/api/tasks/{id} |
获取任务详情 |
POST |
/api/tasks/{id}/sync |
同步任务状态 |
POST |
/api/tasks/{id}/retry |
重试失败任务 |
GET |
/api/tasks/{id}/progress |
获取任务进度 |
GET |
/api/tasks/{id}/download |
打包下载文件 |
DELETE |
/api/tasks/{id} |
删除任务 |
创建任务请求示例
bash
curl -X POST http://localhost:8000/api/tasks \
-F "image=@main.jpg" \
-F "back_image=@back.jpg" \
-F "left_image=@left.jpg" \
-F "right_image=@right.jpg"任务响应结构
json
{
"task_id": "uuid",
"job_id": "hunyuan_job_id",
"status": "PENDING|PROCESSING|DONE|FAILED",
"original_image": "/files/uploads/{id}/image.jpg",
"back_image": "/files/uploads/{id}/back_image.jpg",
"model_path": "/files/uploads/{id}/model.obj",
"task_cost": 180000,
"estimated_cost": 180000,
"files": [
{ "type": "obj", "filename": "model.obj", "url": "...", "size": 1024 }
]
}7.2 模型库接口
| 方法 | 路径 | 说明 |
|---|---|---|
POST |
/api/models |
上传模型（文件夹） |
GET |
/api/models |
获取模型列表 |
GET |
/api/models/{id} |
获取模型详情 |
PUT |
/api/models/{id} |
更新模型信息 |
DELETE |
/api/models/{id} |
删除模型 |
GET |
/api/models/{id}/download/{type} |
下载模型文件 |
POST |
/api/models/from-task/{task_id} |
从任务创建模型 |
7.3 健康检查
bash
GET /health响应：
json
{
"status": "healthy",
"version": "1.1.0",
"timestamp": "2025-01-30T00:00:00Z",
"components": {
"database": { "status": "healthy", "latency_ms": 5 },
"hunyuan_api": { "status": "healthy", "configured": true },
"storage": { "status": "healthy", "free_space_gb": 50.5 }
}
}8. 核心业务流程
8.1 2D 转 3D 流程
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ 用户 │ │ 前端 │ │ 后端 │ │ Hunyuan │
└────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘
│ │ │ │
│ 1. 上传图片 │ │ │
│──────────────>│ │ │
│ │ 2. POST /tasks│ │
│ │──────────────>│ │
│ │ │ 3. 验证图片 │
│ │ │───────┐ │
│ │ │<──────┘ │
│ │ │ 4. 提交任务 │
│ │ │──────────────>│
│ │ │ 5. 返回 JobId │
│ │ │<──────────────│
│ │ 6. 返回任务 │ │
│ │<──────────────│ │
│ 7. 显示进度 │ │ │
│<──────────────│ │ │
│ │ │ │
│ │ 8. 轮询进度 │ │
│ │──────────────>│ │
│ │ │ 9. 查询状态 │
│ │ │──────────────>│
│ │ │ 10. 返回状态 │
│ │ │<──────────────│
│ │ │ │
│ │ │ [状态=DONE] │
│ │ │ 11. 下载文件 │
│ │ │──────────────>│
│ │ │ 12. ZIP 文件 │
│ │ │<──────────────│
│ │ │ 13. 解压保存 │
│ │ │───────┐ │
│ │ │<──────┘ │
│ │ 14. 返回完成 │ │
│ │<──────────────│ │
│ 15. 显示模型 │ │ │
│<──────────────│ │ │
│ │ │ │8.2 任务状态机
┌─────────────────────────────────┐
│ │
▼ │
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌───────┴─┐
│ PENDING │───>│PROCESSING│───>│ DONE │ │ FAILED │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
│ │ ▲
│ │ │
│ └──────────────────────────────┘
│ │
└─────────────────────────────────────────────┘
(API 调用失败)8.3 进度计算逻辑
python
def get_task_progress(task):
# 1. 获取预估耗时（默认 3 分钟）
estimated_cost = task.estimated_cost or 180000
# 2. 计算已耗时
start_time = task.started_at or task.created_at
elapsed_time = (now - start_time).total_seconds() * 1000
# 3. 计算进度百分比
if elapsed_time >= estimated_cost:
progress = 99 # 超时显示 99%
else:
progress = min(99, int(elapsed_time / estimated_cost * 100))
# 4. 完成时返回 100%
if task.status == DONE:
progress = 100
return progress8.4 文件处理流程
上传图片
│
▼
┌─────────────────────────────────────────────────────────┐
│ 1. 验证文件 │
│ - 格式检查 (JPG/PNG) │
│ - 总大小检查 (≤4MB) │
│ - 分辨率检查 (128-5000px) │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 2. 保存到 storage/uploads/{task_id}/ │
│ - main.jpg │
│ - back_xxx.jpg (可选) │
│ - left_xxx.jpg (可选) │
│ - right_xxx.jpg (可选) │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ 3. 转 Base64 提交到 Hunyuan API │
└─────────────────────────────────────────────────────────┘
│
▼ (任务完成后)
┌─────────────────────────────────────────────────────────┐
│ 4. 下载结果 ZIP 并解压 │
│ - xxx.obj (模型文件) │
│ - material.mtl (材质文件) │
│ - texture_pbr_*.png (PBR 贴图) │
└─────────────────────────────────────────────────────────┘9. 部署方案
9.1 Docker Compose 部署
yaml
version: '3.8'
services:
db:
image: postgres:15-alpine
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: image3d
volumes:
- postgres_data:/var/lib/postgresql/data
ports:
- "5432:5432"
backend:
build: ./backend
environment:
- DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/image3d
- HUNYUAN_API_KEY=${HUNYUAN_API_KEY}
volumes:
- ./backend/storage:/app/storage
ports:
- "8000:8000"
depends_on:
- db
frontend:
build: ./frontend
ports:
- "3000:80"
depends_on:
- backend9.2 环境变量
| 变量 | 必填 | 说明 |
|---|---|---|
HUNYUAN_API_KEY |
✅ | 腾讯混元 API Key |
DATABASE_URL |
✅ | PostgreSQL 连接串 |
VITE_API_BASE_URL |
❌ | 前端 API 地址（生产环境） |
9.3 本地开发
bash
# 后端
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python main.py
# 前端
cd frontend
npm install
npm run dev10. 扩展与优化
10.1 性能优化
后端优化
| 优化点 | 实现方式 |
|---|---|
| 异步 I/O | 全链路使用 async/await |
| 数据库连接池 | SQLAlchemy 异步引擎 |
| 文件异步读写 | aiofiles 库 |
| 预加载关联 | selectinload 避免 N+1 查询 |
| 后台任务 | 独立调度器轮询，不阻塞请求 |
前端优化
| 优化点 | 实现方式 |
|---|---|
| 3D 渲染 | Babylon.js 硬件加速 |
| 懒加载 | 模型按需加载 |
| 轮询优化 | 5 秒间隔 + 10 分钟超时 |
| 状态管理 | React Hooks 本地状态 |
10.2 安全考虑
| 风险 | 防护措施 |
|---|---|
| 文件上传攻击 | 类型白名单 + 大小限制 + 分辨率检查 |
| API Key 泄露 | 环境变量存储，不提交代码 |
| SQL 注入 | SQLAlchemy ORM 参数化查询 |
| CORS | 白名单配置 |
10.3 可扩展性
支持更多 AI 模型
python
# 抽象 AI 服务接口
class AI3DService(ABC):
@abstractmethod
async def submit_job(self, image_base64: str) -> str: ...
@abstractmethod
async def query_job(self, job_id: str) -> JobResult: ...
# 实现不同提供商
class HunyuanService(AI3DService): ...
class OpenAIService(AI3DService): ...
class StabilityService(AI3DService): ...支持更多文件格式
python
# 当前支持
MODEL_EXTENSIONS = {'.obj', '.glb', '.fbx', '.gltf'}
TEXTURE_EXTENSIONS = {'.png', '.jpg', '.jpeg', '.tga', '.bmp'}
# 可扩展
# - USDZ (Apple AR)
# - 3DS (3ds Max)
# - BLEND (Blender)10.4 监控与日志
日志配置
python
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
# 关键日志点
logger.info(f"📤 [SUBMIT] POST {url}")
logger.info(f"📥 [QUERY] Status: {status}")
logger.info(f"✅ 任务 {task_id} 完成")
logger.error(f"❌ 任务 {task_id} 失败: {error}")健康检查
python
@app.get("/health")
async def health_check():
return {
"status": "healthy" if all_healthy else "unhealthy",
"components": {
"database": await check_database(),
"hunyuan_api": await check_hunyuan_api(),
"storage": check_storage()
}
}附录
A. 常见问题
Q: 任务一直处于 PENDING 状态？
- 检查 Hunyuan API Key 是否正确配置
- 查看后端日志确认 API 调用是否成功
Q: 3D 模型加载失败？
- 确认模型文件格式正确（OBJ/GLB）
- 检查贴图文件是否完整
Q: 上传失败提示文件过大？
- 所有图片总大小不能超过 4MB
- 单张图片分辨率需在 128-5000px 之间
B. 参考链接
11. 总结
本项目是一个完整的 图片转 3D 模型 解决方案，基于腾讯混元 Hunyuan 3D API 构建。
核心价值
| 维度 | 说明 |
|---|---|
| 易用性 | 上传图片即可生成 3D 模型，支持多视角输入提升质量 |
| 专业性 | 输出 PBR 材质（法线、金属度、粗糙度贴图），满足专业渲染需求 |
| 可扩展 | 模块化架构，易于接入其他 AI 3D 生成服务 |
技术亮点
- 全异步架构：后端采用 FastAPI + asyncpg，高并发低延迟
- 实时进度：基于历史数据预估耗时，前端轮询展示进度
- Web 3D 渲染：Babylon.js 实现专业级 3D 预览，支持 PBR 材质和软阴影
- 多视角支持：主图 + 背/左/右视图，显著提升生成模型的几何精度
适用场景
电商产品展示 ──┐
│
室内设计可视化 ─┼──> Image-to-3D 平台 ──> 可交互 3D 模型
│
数字资产管理 ──┘快速开始
bash
# 1. 配置环境变量
cp .env.example .env
# 编辑 .env 填入 HUNYUAN_API_KEY
# 2. 启动服务
docker-compose up -d
# 3. 访问应用
open http://localhost:3000