starmen1265
042bebe9d7
- 默认模型改为 glm-5.1，API地址改为 coding 套餐端点
- 默认批次大小 20→5，增加 max_tokens=4096
- 优化 prompt 模板，明确要求返回 {"results": [...]} 格式
- 修复全批失败时 ai_inference_metadata 的 KeyError
- 输出目录从 <project>/output/ 统一到 <tool>/outputs/
- 新增 README.md（Pipeline流程、环境变量、CLI参数说明）
162 lines
6.9 KiB
Markdown
162 lines
6.9 KiB
Markdown
# Asset Catalog — UE5 资产扫描与语义增强工具
|
||
|
||
扫描 UE5 项目中的 StaticMesh / Material / Blueprint 资产，提取几何与材质数据，再通过 GLM API 批量推断语义信息（朝向、功能、交互属性等），生成一份可直接用于关卡搭建的资产数据库。
|
||
|
||
## Pipeline 流程
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ 阶段 1：UE5 扫描（需要 UE5 编辑器） │
|
||
│ │
|
||
│ run_all.bat │
|
||
│ └─ 启动 UE5 无头模式，执行 run_all.py │
|
||
│ ├─ discover → outputs/index.json （资产清单） │
|
||
│ ├─ mesh → outputs/meshes/*.json （几何数据） │
|
||
│ ├─ material → outputs/materials/*.json （材质参数） │
|
||
│ └─ blueprint → outputs/blueprints/*.json （蓝图结构） │
|
||
└──────────────────────────┬──────────────────────────────────────────┘
|
||
│
|
||
┌──────────────────────────▼──────────────────────────────────────────┐
|
||
│ 阶段 2：离线汇总（不需要 UE5） │
|
||
│ │
|
||
│ python build_database.py │
|
||
│ └─ 合并 meshes/*.json → outputs/asset_database.json │
|
||
└──────────────────────────┬──────────────────────────────────────────┘
|
||
│
|
||
┌──────────────────────────▼──────────────────────────────────────────┐
|
||
│ 阶段 3：AI 语义增强（离线，需要 GLM_API_KEY） │
|
||
│ │
|
||
│ python ai_inference.py │
|
||
│ └─ 调用 GLM API，为每个资产推断： │
|
||
│ facing_direction / surface_height_cm / function_description │
|
||
│ placement_notes / interaction_hints / plausible_substitutes │
|
||
│ └─ 就地更新 outputs/asset_database.json │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 前置条件
|
||
|
||
| 依赖 | 说明 |
|
||
|------|------|
|
||
| **Unreal Engine 5.7** | 阶段 1 需要，阶段 2/3 纯离线 |
|
||
| **Python 3.10+** | 脚本运行环境 |
|
||
| **openai 包** | `pip install openai`（ai_inference.py 依赖） |
|
||
| **GLM API Key** | 智谱开放平台 API Key，[获取地址](https://open.bigmodel.cn) |
|
||
|
||
## 使用步骤
|
||
|
||
### 1. 扫描资产
|
||
|
||
```cmd
|
||
cd tools\asset-catalog
|
||
run_all.bat
|
||
```
|
||
|
||
启动 UE5 无头模式，自动执行 discover → mesh → material → blueprint 四步扫描。
|
||
完成后编辑器自动关闭，结果写入 `outputs/` 目录。
|
||
|
||
> **自定义扫描范围：**
|
||
> ```cmd
|
||
> set AC_SCAN_ROOT=/Game/MyFolder
|
||
> set AC_STEPS=discover,mesh
|
||
> run_all.bat
|
||
> ```
|
||
|
||
### 2. 汇总数据库
|
||
|
||
```cmd
|
||
python build_database.py
|
||
```
|
||
|
||
将所有 `outputs/meshes/*.json` 合并为单一的 `outputs/asset_database.json`。
|
||
|
||
### 3. AI 语义增强
|
||
|
||
```cmd
|
||
set GLM_API_KEY=你的密钥
|
||
python ai_inference.py
|
||
```
|
||
|
||
按类别分批调用 GLM API，为每个资产推断语义字段。支持断点续跑——中断后重新执行只会处理未完成的资产。
|
||
|
||
先预览批次划分（不调用 API）：
|
||
|
||
```cmd
|
||
python ai_inference.py --dry-run
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
### UE5 扫描阶段
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `AC_SCAN_ROOT` | `/Game/BlockingStarterPack` | 要扫描的 UE5 Content 路径 |
|
||
| `AC_OUTPUT_DIR` | `<工具目录>/outputs` | JSON 输出目录 |
|
||
| `AC_STEPS` | `discover,mesh,material,blueprint` | 要执行的步骤（逗号分隔） |
|
||
| `AC_NO_QUIT` | `0` | 设为 `1` 扫描完成后不关闭编辑器 |
|
||
| `UE5_ROOT` | 自动检测 | UE5 安装根目录（如 `C:\Program Files\Epic Games\UE_5.7`） |
|
||
|
||
### AI 推理阶段
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `GLM_API_KEY` | — | **（必填）** 智谱 API Key |
|
||
| `GLM_API_BASE` | `https://open.bigmodel.cn/api/coding/paas/v4` | API 地址 |
|
||
| `GLM_MODEL` | `glm-5.1` | 使用的模型名称 |
|
||
|
||
## 输出目录结构
|
||
|
||
```
|
||
outputs/
|
||
├── index.json # 资产清单（644 个资产的分类索引）
|
||
├── catalog_log.json # 扫描运行日志（耗时、状态）
|
||
├── asset_database.json # ⭐ 最终产物：425 个 Mesh 的完整数据库
|
||
├── meshes/ # 每个子文件夹一个 JSON
|
||
│ ├── Architecture_Walls.json
|
||
│ ├── Furniture.json
|
||
│ └── ...
|
||
├── materials/ # 每个子文件夹一个 JSON
|
||
│ ├── MI_Architecture.json
|
||
│ └── ...
|
||
└── blueprints/ # 每个子文件夹一个 JSON
|
||
├── BP_Doors.json
|
||
└── ...
|
||
```
|
||
|
||
## CLI 参数
|
||
|
||
### build_database.py
|
||
|
||
```
|
||
python build_database.py [--input DIR] [--output FILE]
|
||
|
||
--input 扫描输出目录，默认 tools/asset-catalog/outputs
|
||
--output 输出文件路径，默认 <input>/asset_database.json
|
||
```
|
||
|
||
### ai_inference.py
|
||
|
||
```
|
||
python ai_inference.py [--input FILE] [--output FILE] [--batch-size N] [--dry-run]
|
||
|
||
--input 输入 asset_database.json 路径，默认 outputs/asset_database.json
|
||
--output 输出路径，默认就地更新
|
||
--batch-size 每批资产数量，默认 5
|
||
--dry-run 只打印批次信息，不调用 API
|
||
```
|
||
|
||
## 文件清单
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `run_all.bat` | 入口：启动 UE5 无头模式 |
|
||
| `run_all.py` | UE5 内编排器：依次调用各分析脚本 |
|
||
| `_common.py` | 共享模块：环境变量、JSON I/O、工具函数 |
|
||
| `discover_assets.py` | 步骤 discover：资产发现与分类 |
|
||
| `analyze_meshes.py` | 步骤 mesh：StaticMesh 几何分析 |
|
||
| `analyze_materials.py` | 步骤 material：材质参数提取 |
|
||
| `analyze_blueprints.py` | 步骤 blueprint：蓝图结构分析 |
|
||
| `build_database.py` | 离线汇总：合并为 asset_database.json |
|
||
| `ai_inference.py` | 离线推理：GLM API 语义增强 |
|