GLB ≠ 3DGS
两种素材不能混用
GLB 交给 GLB / glTF 加载器；3DGS 场景交给对应 Viewer 或嵌入组件。文件类型不同，查看器也不同。
AI 3D LEARNING SERIES · 07 / DAY 04
让 3D 资产
真正出现在网页里。
今天的核心不是“把 API 全部学会”，而是先分清手里的素材是什么，再选对网页展示方式。GLB 模型、3DGS 场景和 Aholo API 各有分工，别让它们互相顶替。
本课目标：分清 GLB 与 3DGS；理解 three.js、Aholo Viewer 与 API 的用途；写出清楚的 AI 编程需求；知道 API key 应该放在哪里；用电脑和手机实际验收网页。
ASSET → VIEWER → WEB
本页只整理知识与实操方法，不包含比赛、报名、奖金或赛事信息。
01 / KNOW YOUR ASSET
先看清手里是哪一种素材
最重要的判断：你现在只是要展示一个已经生成好的东西，还是要让程序调用服务生成、重建新的东西？这是两类不同任务。
| 素材 / 服务 | 它是什么 | 网页里怎么用 | 适合做什么 |
|---|---|---|---|
| GLB 模型 | 以网格为基础的三维物体，通常可携带材质与贴图。 | 用 three.js 的 GLTFLoader 加载。 | 展示杯子、摆件、角色道具等单件资产。 |
| 3DGS 场景 | 由许多带位置、形状、颜色和透明度的 3D 高斯表示的场景。 | 使用 Aholo 提供的嵌入代码或 Viewer。 | 浏览真实房间、校园角落、展厅等空间。 |
| Aholo API | 让程序向群核服务提交生成、重建等任务，并取得结果。 | 由服务器端发起请求，再把结果提供给网页。 | 批量生成资产、用户上传素材后自动重建等动态流程。 |
VIEW ≠ GENERATE
展示不等于调用 API
模型已经做好，只想在网页里旋转查看，直接加载文件即可。无需为了展示而申请 API key。
ZIP ≠ WEB GLB
网页优先用正确导出的 GLB
从 Lux3D 资产库下载时，确认导出格式是 GLB。不要随手把默认 ZIP 内部文件当作最终网页模型。
快速判断：单件物体 → GLB + GLTFLoader；可漫游的重建空间 → 3DGS + Aholo Viewer；需要“用户提交素材，系统自动生成结果” → 再考虑 Aholo API。
02 / PUT IT ON THE WEB
把素材放进网页，需要哪条技术路径？
网页展示的关键是加载正确的资源，并给用户可操作的视角控制。不同格式要走不同路径。
PATH A · GLB OBJECT
单件模型：three.js
model.glb模型文件
GLTFLoader读取模型
OrbitControls旋转查看
GLTFLoader 负责把 GLB 加载进 three.js 场景；OrbitControls 负责鼠标或触屏拖动旋转、缩放和平移。两者分工不同。
// 核心思路（示意）
const loader = new GLTFLoader();
loader.load('./model.glb', (gltf) => {
scene.add(gltf.scene);
});
const controls = new OrbitControls(camera, renderer.domElement);
PATH B · 3DGS SCENE
空间场景：Aholo Viewer
Reality 场景重建结果
嵌入代码或 Viewer
网页浏览换位查看
如果 Aholo Reality 项目页提供“获取嵌入代码”，可以将它放入网页。需要更细的查看器控制时，再看 Aholo Viewer 文档。
不要把 GLB 文件交给 3DGS Viewer，也不要用 GLTFLoader 去加载 3DGS 场景。
一个最小网页的组成MVP · 最小可用版本
01 / RESOURCE模型或场景
model.glb，或 Aholo Reality 的嵌入代码。
02 / VIEWER加载与控制
GLTFLoader + OrbitControls，或对应的 3DGS Viewer。
03 / CONTENT作品说明
名称、设计说明、操作提示，以及必要的加载状态。
03 / VIBE CODING
让 AI 改网页，先把需求说具体
Vibe Coding 不是“把一句模糊愿望扔给 AI”。它是用自然语言描述目标，再通过运行、观察、反馈持续修正。
A GOOD REQUEST HAS 5 PARTS
需求至少交代五件事
1. 当前材料文件夹里有什么？例如 model.glb、已有的 index.html。
2. 目标用户谁会打开网页？他想完成什么事？
3. 第一版功能只要求最重要的一条完整体验。
4. 明确不做什么先排除登录、上传、批量生成等非必要功能。
5. 验收方式网页怎么启动？用户怎样操作？什么现象算成功？
PROMPT BUILDER
生成一份可交给 AI 的网页需求
点击“生成需求文本”，把你的项目情况整理成 AI 能执行的需求。
核心原则：让 AI 先在本机启动预览，明确告诉你访问地址和检查方法。不要只看它回复“已经完成”，要亲自打开网页验证。
04 / AHOLO API & SECURITY
什么时候需要 API？密钥应该放哪里？
API 是程序调用服务的接口。它不是展示模型的必需品，也不是可以随手贴进网页的普通配置。
WHEN TO USE API
需要动态处理时再接 API
批量生成资产例如用户或任务系统提交多张图片，由程序批量调用 Lux3D 生成模型。
用户上传视频并重建网页接收视频，服务器调用 Aholo 重建服务，等待任务完成并返回场景结果。
不需要 API 的情况只展示一个已下载的 GLB，或嵌入一个已经重建好的 3DGS 场景。
API KEY IS A SECRET
API key 是账号调用凭证
可以放服务器环境变量，或本地不上传的 .env 文件。
不要放前端 JavaScript、公开仓库、网页源码、截图或 AI 对话中。
为什么前端代码会被访问者看到。密钥泄露后，别人可能冒用你的额度或权限。
安全的调用链KEY STAYS ON SERVER
用户网页提交图片 / 视频
你的服务器接收文件与请求
读取密钥AHOLO_API_KEY
调用 Aholo提交生成 / 重建任务
返回结果网页打开模型 / 场景
本地开发可将密钥保存在项目根目录的 .env 文件，并确保 .env 已加入 .gitignore。部署时使用平台提供的服务器环境变量。不要把密钥写进浏览器端代码。
SKILLS / MCP
让 AI 编程工具学会调用能力
Skills 或 MCP 可以把接口说明、调用步骤和工具能力提供给 AI 编程工具，减少手工拼接请求的工作。但安装后仍要检查它准备调用什么、消耗什么资源、输出保存在哪里。
OFFICIAL DOCS
遇到接口问题先查文档
优先核对 API 快速开始、认证方式、API 参考、Skills / MCP 文档，以及 Aholo Viewer 文档。把准确文档交给 AI，避免它凭印象编造接口参数。
05 / TEST BEFORE SHIP
网页做好了，怎样证明它真的能用？
电脑上能打开不等于手机能用；模型出现也不等于模型正确。用下面的清单逐项验收。
INTERACTION CHECKLIST
逐项勾选
已完成 0 / 7 项
DEBUG BY SYMPTOM
遇到问题，先定位是哪一层
模型完全不出现检查文件路径、文件名、网络请求和浏览器控制台错误。
模型发白 / 发黑 / 没贴图检查导出格式、材质贴图是否包含、资源路径是否正确。
模型出现但不能转检查 OrbitControls 是否绑定到正确的渲染画布，触屏事件是否可用。
电脑正常、手机卡顿检查模型体量、面数、贴图尺寸和设备性能，先缩小展示范围或优化资源。
API 请求失败检查服务端密钥、认证头、请求参数、文件上传状态和任务状态。
验收不是看 AI 的自我评价。打开页面、真实操作、换设备测试，再记录一个用户卡住的地方，这才是有效验证。
06 / ACTIVE RECALL
Day 4 · 翻面知识卡
先看问题，自己回答，再点击卡片翻面。不要急着看答案，主动回忆比重复阅读更能暴露知识漏洞。
点击任意卡片查看答案已翻开 0 / 12
07 / QUICK CHECK
自测：你真的分清了吗？
选择答案后会立即显示解析。答错也没关系，重点是知道自己混淆了哪一层。
Day 4 · 四道检查题已答对 0 / 4
01 / 已有一个 Lux3D 导出的模型，只想放进网页旋转查看，应该怎么做？
02 / Aholo API key 应该放在哪里？
03 / 第一次让 AI 编程工具改网页，哪种需求更可执行？
04 / 网页在电脑上能打开，怎样确认它真的可用？
本页整理自观猹《Day 4 · 调用群核 Aholo API》，知识学习版；接口能力以群核官方文档为准。