探索 AI 模型内部机制时最常见的困境是结构图看了很多但数据真正在层与层之间如何流动始终缺一个直观载体。3D Neural Decode 这个方向就是把神经网络中的层、神经元、权重和激活状态渲染成一个可旋转、可点击、可动态观察的 3D 网站让理解 AI 模型从看论文截图变成亲手探索。下面给出这条 3D 模型可视化网站从零到可运行的完整实现路径技术栈以 Three.js 和原生前端为主。投入一个下午跑完这套代码后你可以得到自己的神经网络交互演示页后续接入真实模型数据或扩展成教学系统都会更容易。理解这个项目的关键不在 Three.js API 本身而在于把什么数据映射成什么视觉元素。网络层级映射为空间中的纵向坐标同一层神经元映射为同一平面上的球体层与层之间的权重映射为连线激活值映射为球体的亮度和颜色。用户拖拽旋转场景观察全局结构悬停读取神经元详情点击查看权重关系再通过参数面板触发一次前向传播动画观察数据逐层流动。整篇文章按概念、环境、实现、验证、排错、扩展的顺序展开代码会尽量给出可直接运行的最小闭环。1. 3D 神经网络可视化到底在解决什么问题1.1 神经网络的组成和可视化目标一个常见的全连接神经网络由输入层、若干隐藏层和输出层组成。每一层有若干神经元相邻层的神经元通过带权重的边相连每个神经元通常还有一个偏置项。前向传播时输入值进入第一层经过加权求和、加偏置、激活函数处理后传递给下一层逐层推进直到输出层。可视化要回答的问题有三个网络长什么样、运算流如何流动、某个神经元或连接起了什么作用。传统结构图适合表达第一个问题训练曲线适合表达整体误差变化但第二个和第三个问题需要更强的时间维度和交互维度。3D 可视化把网络规模、连接密度、激活强度的变化放在同一空间中呈现比 2D 图更容易形成空间记忆。1.2 2D 可视化与 3D 可视化的差异2D 可视化通常把网络画成从左到右的列适合论文配图但层数一多、神经元一多连线重叠严重用户很难看出哪些路径对输出影响更大。3D 可视化可以绕 Y 轴旋转把密集连线分散到不同深度方向视觉上更舒展同时观察者可以自由选择视角从层间关系、神经元分布、连接强度三个维度切换观察重点。需要注意3D 不是 2D 的简单升级它同时引入了交互成本和渲染复杂度。因此在没有明确的多人协作、教学演示、大屏展示或多层深网络需求时2D 仍然可能是更务实的选择。3D 可视化适合以下场景讲解课程时需要让学生快速建立整体结构认知论文或产品需要生成有冲击力的展示页面模型规模较大时希望借助空间维度降低视觉重叠。1.3 交互式探索网站的产品边界一个交互式 3D 可视化网站不是模型训练平台也不是完整推理框架。它的核心价值是让访问者通过观察和操作快速理解某个模型的宏观行为。因此产品边界应该尽量收敛支持加载模型结构数据支持旋转、缩放、平移支持悬停和点击查看细节支持简单的参数输入并演示前向传播。至于训练、调参、导出模型则交给后端或外部工具处理。把边界划清楚前端的数据结构设计就会简单很多。这个项目只需要一份描述网络结构的数据文件不需要任何后端服务。模型数据的获取方式可以是手写 JSON、从训练脚本导出也可以是从 PyTorch 或 ONNX 模型转换得到。下面先从最易控制的自定义 JSON 开始。2. 技术选型和环境准备从 Vite 到 Three.js2.1 技术栈为什么这样选实现浏览器端 3D 可视化主流方案有 Three.js、Babylon.js 和原生 WebGL。Three.js 社区资料最多API 稳定能快速完成场景、相机、灯光、交互和动画最适合这类教学型项目。构建工具选择 Vite启动速度快开发体验好打包配置简单。React 或 Vue 不是必须的这个项目状态量不大用原生 JavaScript 反而能减少框架嵌套让 Three.js 的渲染逻辑更清晰。如果需要和 React 生态集成也可以参考相同的渲染思路把 Three.js 场景封装成独立类通过 useEffect 初始化并把用户操作的参数通过事件通知 React 更新 UI。本文以原生 JavaScript 版本为例原理完全一致。2.2 初始化项目与安装依赖执行以下命令创建一个 Vite 项目并安装 Three.js 和 lil-gui。lil-gui 用于生成参数面板方便调节输入值和动画速度。npm create vitelatest neural-decode-web -- --template vanilla cd neural-decode-web npm install npm install three lil-gui npm run dev安装完成后浏览器访问终端提示的地址默认会看到 Vite 初始化页面。确认package.json中已经出现three和lil-gui依赖即可。2.3 项目目录结构为了让后续扩展清楚把网络数据、场景创建、交互逻辑和入口文件分开。neural-decode-web/ ├── index.html ├── package.json └── src/ ├── main.js ├── data/ │ └── network.js ├── scene/ │ ├── createScene.js │ ├── createNetwork.js │ ├── interaction.js │ └── forward.js └── style.cssdata/network.js负责提供网络结构数据scene/createScene.js负责场景、相机、灯光和控制器scene/createNetwork.js负责把数据生成球体和连线scene/interaction.js负责鼠标拾取和面板信息更新scene/forward.js负责前向传播动画。在真实项目中网络数据建议从layer.json、weights.json等独立文件读取方便与模型导出流程对接。3. 核心实现把神经网络数据画成 3D 场景3.1 定义可复用的网络数据 JSON网络数据是渲染的基础结构必须同时满足两个条件一是人能读懂二是程序能直接遍历。下面用一个小型网络做示例网络结构为 2 个输入、3 个隐藏神经元、1 个输出等价于一个可以拟合异或逻辑的最小全连接网络。export const networkData { layers: [ { name: 输入层, type: input, bias: 0, neurons: [ { id: x0, label: X1, desc: 第一个输入特征 }, { id: x1, label: X2, desc: 第二个输入特征 } ] }, { name: 隐藏层, type: hidden, bias: -0.2, neurons: [ { id: h0, label: H1, desc: 隐藏神经元 1 }, { id: h1, label: H2, desc: 隐藏神经元 2 }, { id: h2, label: H3, desc: 隐藏神经元 3 } ] }, { name: 输出层, type: output, bias: 0.1, neurons: [ { id: y0, label: OUT, desc: 模型输出 } ] } ], weights: [ { from: x0, to: h0, value: 0.8 }, { from: x0, to: h1, value: -0.3 }, { from: x0, to: h2, value: 0.5 }, { from: x1, to: h0, value: -0.4 }, { from: x1, to: h1, value: 0.9 }, { from: x1, to: h2, value: 0.2 }, { from: h0, to: y0, value: 0.7 }, { from: h1, to: y0, value: -0.6 }, { from: h2, to: y0, value: 0.3 } ] };这个结构把神经元统一按 ID 管理层只是归属关系权重通过from和to引用神经元 ID。这样做的优势是即使以后网络层数变多视图层代码不需要改动只要数据结构和渲染逻辑一致即可。3.2 搭建场景、相机、灯光与控制器Three.js 渲染必须要有场景、相机和渲染器三件套。为了让用户可以旋转视角还需要 OrbitControls。import * as THREE from three; import { OrbitControls } from three/examples/jsm/controls/OrbitControls.js; export function createScene(container) { const scene new THREE.Scene(); scene.background new THREE.Color(0x0b1026); const camera new THREE.PerspectiveCamera(45, container.clientWidth / container.clientHeight, 0.1, 100); camera.position.set(8, 6, 12); const renderer new THREE.WebGLRenderer({ antialias: true }); renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)); renderer.setSize(container.clientWidth, container.clientHeight); container.appendChild(renderer.domElement); const controls new OrbitControls(camera, renderer.domElement); controls.enableDamping true; controls.dampingFactor 0.08; controls.minDistance 3; controls.maxDistance 30; const ambientLight new THREE.AmbientLight(0xffffff, 0.6); const directionalLight new THREE.DirectionalLight(0xffffff, 1.2); directionalLight.position.set(5, 8, 6); scene.add(ambientLight, directionalLight); window.addEventListener(resize, () { camera.aspect container.clientWidth / container.clientHeight; camera.updateProjectionMatrix(); renderer.setSize(container.clientWidth, container.clientHeight); }); return { scene, camera, renderer, controls }; }这里有两个容易忽略的设置。antialias: true如果不开启边缘锯齿会非常明显尤其在高分屏上setPixelRatio(Math.min(window.devicePixelRatio, 2))是为了避免高密度屏上渲染开销翻倍移动端尤其需要限制像素比上限。3.3 将网络数据映射为球体和连线把神经元映射为球体时需要考虑空间布局。层与层之间沿 X 轴排列同一层的神经元沿 Y 轴排列这样符合从左到右阅读结构图的直觉。import * as THREE from three; const NEURON_COLOR 0x3b82f6; const POSITIVE_LINE_COLOR 0x4f8cff; const NEGATIVE_LINE_COLOR 0xff6b6b; export function createNetwork(scene, modelData) { const meshMap new Map(); const layerSpacing 4; const neuronSpacing 1.6; modelData.layers.forEach((layer, layerIndex) { layer.neurons.forEach((neuron, neuronIndex) { const x (layerIndex - (modelData.layers.length - 1) / 2) * layerSpacing; const y (neuronIndex - (layer.neurons.length - 1) / 2) * neuronSpacing; const mesh createNeuronMesh(x, y, 0, 0.45); mesh.userData { neuronId: neuron.id, label: neuron.label, desc: neuron.desc, layerName: layer.name, baseColor: new THREE.Color(NEURON_COLOR) }; scene.add(mesh); meshMap.set(neuron.id, mesh); }); }); modelData.weights.forEach((w) { const fromMesh meshMap.get(w.from); const toMesh meshMap.get(w.to); if (!fromMesh || !toMesh) return; const line createWeightLine(fromMesh.position, toMesh.position, w.value); scene.add(line); }); return { meshMap }; } function createNeuronMesh(x, y, z, radius) { const geometry new THREE.SphereGeometry(radius, 32, 32); const material new THREE.MeshStandardMaterial({ color: NEURON_COLOR, emissive: NEURON_COLOR, emissiveIntensity: 0.2 }); const mesh new THREE.Mesh(geometry, material); mesh.position.set(x, y, z); return mesh; }刚渲染出来的模型是静态的。为了让网络有层次感可以给不同层设置不同的基础色例如输入层用蓝色、隐藏层用紫色、输出层用橙色视觉区分度更高。颜色选取要注意背景对比度深色背景下明亮冷色系更耐看。3.4 绘制权重连线并编码正负与强度权重同样需要映射成视觉信息。权重为正和权重为负对输出的影响方向相反必须用不同颜色区分权重绝对值越大连线应该越醒目。function createWeightLine(start, end, weight) { const direction new THREE.Vector3().subVectors(end, start); const length direction.length(); const mid new THREE.Vector3().addVectors(start, end).multiplyScalar(0.5); const geometry new THREE.CylinderGeometry(0.02, 0.02, length, 8); const color weight 0 ? POSITIVE_LINE_COLOR : NEGATIVE_LINE_COLOR; const material new THREE.MeshBasicMaterial({ color: color, transparent: true, opacity: 0.15 Math.min(0.85, Math.abs(weight)) }); const cylinder new THREE.Mesh(geometry, material); cylinder.position.copy(mid); cylinder.quaternion.setFromUnitVectors(new THREE.Vector3(0, 1, 0), direction.clone().normalize()); return cylinder; }这里特意使用CylinderGeometry而不是LineBasicMaterial原因会在排查章节详细说明。连线透明度由权重的绝对值决定正负由颜色决定这样用户只看一眼就能判断哪些连接在推动正向输出、哪些在抑制输出。3.5 参数说明表这一节涉及的视觉参数建议集中管理方便统一调整。参数推荐值含义调大影响调小影响层间距 layerSpacing4相邻层在 X 轴的间隔结构更舒展场景更大结构紧凑连线更密神经元间距 neuronSpacing1.6同层神经元在 Y 轴间隔神经元不重叠密集网络更紧凑球体半径0.45神经元球体大小更容易点击细颗粒度展示相机 FOV45视野范围看到更多内容透视变形弱局部放大效果好连线透明度下限0.15弱权重的视觉下限弱连接仍可见弱连接几乎消失像素比上限2渲染分辨率上限更清晰耗性能更省电锯齿多这些参数在开发阶段可以放进config对象统一管理。生产环境如果数据来自真实模型建议根据网络层数和神经元数量动态计算间距而不是固定写死。4. 交互细节拾取、信息面板与前向传播动画4.1 鼠标悬停显示神经元信息3D 场景中的拾取依赖 Raycaster。思路是把鼠标屏幕坐标换算成标准化设备坐标从相机位置发射一条射线检测射线与神经元的交点。射线拾取有一个常见陷阱用户快速移动鼠标时即使上一个悬停高亮已经移除射线检测仍在每帧执行浪费性能。建议在pointermove事件中只用节流函数控制射线检测频率。import * as THREE from three; export function createInteraction(camera, meshMap, infoPanel) { const raycaster new THREE.Raycaster(); const pointer new THREE.Vector2(); const meshes Array.from(meshMap.values()); window.addEventListener(pointermove, (event) { pointer.x (event.clientX / window.innerWidth) * 2 - 1; pointer.y -(event.clientY / window.innerHeight) * 2 1; }); window.addEventListener(pointerdown, () { raycaster.setFromCamera(pointer, camera); const hits raycaster.intersectObjects(meshes, false); if (hits.length 0) { const data hits[0].object.userData; infoPanel.innerHTML strong${data.label}/strongbr${data.desc}br所属层${data.layerName}; } }); }这里pointer事件同时兼容鼠标和触摸屏。如果使用传统的mousedown、touchstart两套事件代码会冗余而且容易漏处理触摸后的pointerup状态。4.2 点击神经元查看权重连接点击神经元时最好把与它相关的连接高亮出来帮助用户理解当前节点影响了哪些下游节点、被哪些上游节点影响。实现方式是遍历networkData.weights找到from或to等于当前节点 ID 的权重然后改变对应连线的颜色和透明度。export function highlightConnections(modelData, lineMap, neuronId) { Object.values(lineMap).forEach(line { line.userData.active false; line.material.opacity 0.05; }); modelData.weights.forEach(w { if (w.from neuronId || w.to neuronId) { const line lineMap[${w.from}_${w.to}]; if (line) { line.userData.active true; line.material.opacity 0.9; } } }); }为了方便查找在创建连线时把所有CylinderMesh存进lineMap键名是from和to拼接成的字符串。高亮只对相关连线生效其余连线降为透明可以在不打断整体视角的情况下突出局部关系。4.3 前向传播逐层动画前向传播动画的难点在于时间控制。如果在每次参数变化时同步计算全部层并立即更新用户看不到过程如果使用setTimeout层层推进又要时刻清理定时器避免连续点击造成动画错乱。let timer null; export function runForwardAnimation(modelData, inputs, meshMap, speed) { if (timer) clearInterval(timer); const values computeForwardValues(modelData, inputs); const network buildLayerTimeline(modelData, values); let step 0; timer setInterval(() { if (step network.length) { clearInterval(timer); timer null; return; } const layerValues network[step]; Object.entries(layerValues).forEach(([id, value]) { const mesh meshMap.get(id); if (mesh) updateNeuronVisual(mesh, value); }); step 1; }, 600 / speed); }每次点击播放按钮时先clearInterval再启动新动画能避免多个定时器并发导致节点状态互相覆盖。动画结束后可以把定时器置空供后续状态判断使用。4.4 用激活值驱动神经元亮度前向传播计算得到的激活值只是一个数字要让它变成视觉反馈需要把激活值映射到颜色和亮度上。使用 MeshStandardMaterial 时直接控制emissiveIntensity和颜色明度是最直观的方式。export function updateNeuronVisual(mesh, value) { const baseColor mesh.userData.baseColor; const intensity 0.15 Math.max(0, value) * 0.85; const color baseColor.clone(); color.multiplyScalar(intensity); mesh.material.color.copy(color); mesh.material.emissiveIntensity intensity; mesh.userData.value value; }Math.max(0, value)是为了限制负激活值不会让球体发黑因为可视化关注的是激活强度。如果希望负值也参与展示可以把颜色映射改为三段式负值用冷色、零值用中性色、正值用暖色。颜色转换过程尽量避免每帧创建新对象可以先申请临时 Color 实例复用减少 GC 压力。5. 运行验证与效果检查5.1 启动命令和预期效果在项目根目录执行npm run dev浏览器打开 Vite 输出的地址。正常效果如下页面中心出现一个由球体和连线组成的 3D 网络结构为左、中、右三列。鼠标拖拽可以旋转视角滚轮可以缩放右键或双指可以平移。点击任意神经元右侧信息面板显示节点标签、描述和所属层。在参数面板调整 X1、X2 后点击播放可以看到球体从输入层开始逐层变亮或变暗。如果以上现象都出现说明核心链路已经跑通。接下来要做的是数据正确性验证。5.2 用异或数据验证前向传播结果为了确认可视化没有骗人可以选一组可手工推算的输入来验证。取 X11、X20按上一章的网络权重和偏置手工计算得到输出应该接近 0 到 1 之间的某个确定值。代码层面可以临时在控制台打印computeForwardValues的结果再和手工计算对照。export function computeForwardValues(modelData, inputs) { const values new Map(); modelData.layers[0].neurons.forEach((n, index) { values.set(n.id, inputs[index] ?? 0); }); for (let layerIndex 1; layerIndex modelData.layers.length; layerIndex) { const layer modelData.layers[layerIndex]; layer.neurons.forEach((neuron) { let sum layer.bias || 0; modelData.weights .filter(w w.to neuron.id) .forEach(w { sum (values.get(w.from) || 0) * w.value; }); values.set(neuron.id, 1 / (1 Math.exp(-sum))); }); } return values; }计算逻辑要注意偏置项的处理。每个隐藏层可以有自己的偏置也可以每个神经元独立偏置数据结构必须和计算逻辑保持一致。这里把偏置挂到层上是为了示例简单真实模型导出时通常每个神经元都有独立 bias需要按神经元 ID 存储。5.3 性能与显示检查可视化页面最容易出现的问题是看起来正确但实际性能不佳。建议从三个维度检查。第一打开浏览器开发者工具的 Performance 面板录制 5 秒旋转操作的性能数据观察帧率是否稳定在 30 以上。第二拖动窗口改变尺寸确认不会出现画面拉伸或黑边说明 resize 监听和相机投影矩阵更新正常。第三在移动设备模拟器或者真机上测试触摸交互确认旋转和缩放手势正常。若页面只在桌面端可用产品定位就要明确写清楚避免移动端用户误入。6. 常见问题排查黑屏、卡顿和交互失效6.1 问题现象与排查方向问题现象常见原因检查方式处理建议页面黑屏相机朝向错误或容器高度为 0检查 container.clientHeight 是否为 0检查相机 position给容器设置固定高度或初始化后重新计算包围盒线条特别细甚至看不见LineBasicMaterial 的 linewidth 在多数平台不生效打开代码确认使用哪种材质改用 CylinderGeometry 或 TubeGeometry 生成可设置粗细的管线鼠标点击选不中神经元射线检测时未更新 pointer 坐标或目标太小打印 pointer 和射线方向使用 pointermove 更新坐标为球体额外维护一个较大的不可见碰撞体动画卡顿每帧创建新对象或主线程被阻塞打开 Performance 观察 GC 和 JS 耗时复用 Color、Vector3减少请求动画帧中的对象创建手机端无法交互只监听了 mousedown未处理 pointer 或 touch 事件查看事件监听代码统一改用 PointerEvent权重颜色看不出正负正负线颜色对比度不足或透明度遮挡严重检查颜色值和透明度映射公式提高色相差异避免同时使用相近的蓝紫6.2 三个高频坑的底层原因第一个高频坑是线条不可控。很多人第一次用 Three.js 画网络连接会直接用LineBasicMaterial但 WebGL 对线宽的支持非常有限大多数浏览器和显卡上linewidth最终会被忽略结果线条细得像发丝。换成CylinderGeometry后线的粗细是真实几何体属性任何平台都能正常显示代价是绘制大量圆柱会占用更多顶点需要控制精度参数。第二个高频坑是射线拾取不稳定。原因是射线检测依赖正确的 NDC 坐标而 NDC 坐标的计算公式为(clientX / width) * 2 - 1很多新手会漏掉减 1 或乘 2 的步骤。另外如果场景里同时有大量球体快速移动鼠标时射线检测每帧执行会因为频繁遍历网格列表而掉帧。推荐做法是在pointermove中只更新坐标在requestAnimationFrame中使用节流策略执行射线检测。第三个高频坑是前向传播动画状态错乱。连续点击播放按钮时如果没有先清除上一个定时器两套动画会同时修改相同节点的材质视觉上表现为亮度跳动、无法稳定停在最终结果。推荐做法是动画开始时先clearInterval并把定时器句柄存为模块级变量动画结束后置空。6.3 推荐的排错顺序遇到问题不要先怀疑 Three.js按下面的顺序排查更高效先确认数据是否正确。打印networkData检查神经元 ID、权重连接是否完整很多异常都是数据里引用了不存在的 ID。再确认容器尺寸。很多黑屏问题最后查出来是外层容器的 height 为 0。然后确认相机和控制器参数。确认相机朝向、远近裁剪面是否覆盖目标对象。继续确认事件坐标换算。对比pointer的值是否符合预期。最后检查浏览器控制台是否有 WebGL 上下文创建失败、着色器编译报错等日志。7. 生产环境落地与扩展方向7.1 学习和生产环境的差异本文写的版本是典型学习环境数据手写、页面单机启动、不需要处理异常。如果要把它部署到团队内部或对外发布需要补齐一组生产级能力能力学习环境生产环境数据来源手写 JSON从模型导出脚本生成或从后端接口加载配置写在代码里外置为配置文件或通过接口下发容错直接报错网络数据缺失、格式错误时有友好提示日志无用户交互埋点、前端异常上报性能小网络足够大网络需要合并几何体、按需渲染部署本地 dev server构建产物压缩、CDN 加速生产环境还有一个不能忽略的问题如果网站支持上传用户自己的模型数据前端必须做格式校验和大小限制防止异常文件导致页面崩溃。网络数据的 schema、最大层数、最大神经元数都应该有约束和提示。7.2 性能优化清单当网络规模变大从几百个节点增加到几千个节点时原来的一个节点一个 Mesh 的方案会撑不住。下面是一份可以提前执行的优化清单静态结构只创建一次不要在每次参数变化时重建所有球体和连线。同一层的球体如果不是单独交互可以合并为一个 InstancedMesh大幅减少 draw call。连线使用 InstancedMesh 或合并几何体避免数千条圆柱都是独立 Mesh。射线检测建立事件节流避免每帧遍历全部网格。限制devicePixelRatio上限为 2移动端可以限制为 1.5。降低低端设备的球体分段数从 32 降低到 16视觉差异很小但顶点数减少约四分之三。动画结束后立即把定时器置空避免定时器在页面隐藏后继续执行。7.3 扩展方向从全连接网络到更多模型结构这套 3D 可视化框架不止能展示全连接网络。把数据表达方式扩展后可以覆盖更多模型类型。卷积神经网络的典型可视化方向是特征图体素化把每个通道的特征图映射为 3D 体素块旋转时可以观察不同深度特征的变化。Transformer 模型可以绘制注意力头和注意力权重的 3D 连线权重大的连接更亮交互时选择某个 token 会高亮它对其他 token 的注意力分布。最近关注度较高的 3D Gaussian Splatting 则属于另一种可视化形态适合做三维场景理解模型的结果展示可以和对齐网络的嵌入空间可视化结合起来。从工程角度看下一步值得投入的方向是模型数据转换工具链。手写 JSON 只能应付演示真实项目需要从 PyTorch、ONNX 或 TensorFlow 导出模型结构再转换成前端可用的标准化数据格式。已经有了这一步3D 可视化页面就变成了模型分析基础设施的一部分可以在模型讲解、论文配图、算法评审和线上产品中持续复用。对新手来说最有价值的练习不是继续堆功能而是把当前这个最小闭环里的场景创建、数据映射、射线拾取、动画管理和数据验证每个环节都吃透之后换任何 3D 框架都能快速迁移。