chore(brain): ASTRA 성장 자산 동기화 — 기능 인벤토리·growth(약점프로필/학습큐)·일화기억·장기기억·회의록 원문

2026-06-12 16:37:41 +09:00
parent a97fc7be07
commit 89fb05a28a
781 changed files with 138546 additions and 47 deletions
@@ -0,0 +1,197 @@
+---
+id: wiki-2026-0508-webgpu
+title: WebGPU
+category: 10_Wiki/Topics
+status: verified
+canonical_id: self
+aliases: [WebGPU API, WGSL, GPU Web]
+duplicate_of: none
+source_trust_level: A
+confidence_score: 0.9
+verification_status: applied
+tags: [graphics, gpu, web, wgsl, compute]
+raw_sources: []
+last_reinforced: 2026-05-10
+github_commit: pending
+tech_stack:
+  language: typescript
+  framework: webgpu
+---
+
+# WebGPU
+
+## 매 한 줄
+> **"매 modern explicit GPU API 매 browser 에 — Vulkan / Metal / D3D12 의 매 abstraction"**. 매 WebGL 의 매 후계자, 매 2023 매 Chrome 113 ship, 매 2026 매 Safari 18 / Firefox 130 stable, ML inference (transformers.js, ONNX Runtime Web) 와 high-end browser game 의 standard.
+
+## 매 핵심
+
+### 매 vs WebGL
+- WebGL: OpenGL ES 2.0 / 3.0 기반 — implicit state, fixed pipeline parts.
+- WebGPU: Vulkan / Metal style — explicit pipeline state object, compute shader native.
+- WGSL (WebGPU Shading Language): Rust-like syntax, browser 매 portable.
+
+### 매 핵심 객체
+- **Adapter**: physical GPU.
+- **Device**: logical handle — buffer, texture, pipeline 만들기 사용.
+- **Queue**: command submission.
+- **Buffer / Texture**: GPU memory.
+- **BindGroup**: shader 매 resource binding.
+- **RenderPipeline / ComputePipeline**: compiled shader + state.
+- **CommandEncoder → CommandBuffer**: GPU 명령 record + submit.
+
+### 매 응용
+1. transformers.js / ONNX Runtime Web: GPU-accelerated LLM in browser.
+2. Babylon.js / Three.js (WebGPURenderer): high-end web 3D.
+3. Figma / Canva: GPU-accelerated 2D.
+4. Stable Diffusion Web (web-stable-diffusion).
+5. Real-time particle / fluid sim (GPGPU).
+
+## 💻 패턴
+
+### Init + clear screen
+```ts
+const adapter = await navigator.gpu.requestAdapter();
+if (!adapter) throw new Error("No WebGPU adapter");
+const device = await adapter.requestDevice();
+
+const canvas = document.querySelector("canvas")!;
+const ctx = canvas.getContext("webgpu")!;
+const format = navigator.gpu.getPreferredCanvasFormat();
+ctx.configure({ device, format, alphaMode: "premultiplied" });
+
+const enc = device.createCommandEncoder();
+const pass = enc.beginRenderPass({
+  colorAttachments: [{
+    view: ctx.getCurrentTexture().createView(),
+    clearValue: { r: 0.1, g: 0.1, b: 0.15, a: 1 },
+    loadOp: "clear", storeOp: "store",
+  }],
+});
+pass.end();
+device.queue.submit([enc.finish()]);
+```
+
+### Triangle render pipeline
+```ts
+const shader = device.createShaderModule({ code: `
+  @vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {
+    let p = array(vec2f(0,0.5), vec2f(-0.5,-0.5), vec2f(0.5,-0.5));
+    return vec4f(p[i], 0, 1);
+  }
+  @fragment fn fs() -> @location(0) vec4f { return vec4f(1, 0.4, 0.2, 1); }
+`});
+
+const pipeline = device.createRenderPipeline({
+  layout: "auto",
+  vertex:   { module: shader, entryPoint: "vs" },
+  fragment: { module: shader, entryPoint: "fs", targets: [{ format }] },
+  primitive: { topology: "triangle-list" },
+});
+```
+
+### Uniform buffer + bind group
+```ts
+const uniform = device.createBuffer({
+  size: 16, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+});
+device.queue.writeBuffer(uniform, 0, new Float32Array([0.5, 0.2, 0.8, 1]));
+
+const bg = device.createBindGroup({
+  layout: pipeline.getBindGroupLayout(0),
+  entries: [{ binding: 0, resource: { buffer: uniform } }],
+});
+```
+
+### Compute shader (vector add)
+```ts
+const code = `
+  @group(0) @binding(0) var<storage, read>       a: array<f32>;
+  @group(0) @binding(1) var<storage, read>       b: array<f32>;
+  @group(0) @binding(2) var<storage, read_write> out: array<f32>;
+  @compute @workgroup_size(64)
+  fn main(@builtin(global_invocation_id) id: vec3u) {
+    let i = id.x;
+    if (i >= arrayLength(&out)) { return; }
+    out[i] = a[i] + b[i];
+  }
+`;
+const cs = device.createShaderModule({ code });
+const cp = device.createComputePipeline({
+  layout: "auto", compute: { module: cs, entryPoint: "main" },
+});
+// dispatch: workgroups = ceil(N / 64)
+```
+
+### Storage buffer readback
+```ts
+async function readBuffer(src: GPUBuffer, size: number) {
+  const staging = device.createBuffer({
+    size, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+  });
+  const enc = device.createCommandEncoder();
+  enc.copyBufferToBuffer(src, 0, staging, 0, size);
+  device.queue.submit([enc.finish()]);
+  await staging.mapAsync(GPUMapMode.READ);
+  const data = new Float32Array(staging.getMappedRange().slice(0));
+  staging.unmap();
+  return data;
+}
+```
+
+### Texture upload (ImageBitmap)
+```ts
+const bmp = await createImageBitmap(await (await fetch("/img.png")).blob());
+const tex = device.createTexture({
+  size: [bmp.width, bmp.height], format: "rgba8unorm",
+  usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
+});
+device.queue.copyExternalImageToTexture({ source: bmp }, { texture: tex }, [bmp.width, bmp.height]);
+```
+
+### Device-lost handling
+```ts
+device.lost.then((info) => {
+  console.error("Device lost:", info.message, info.reason);
+  if (info.reason !== "destroyed") {
+    // 매 reinit pipeline
+  }
+});
+```
+
+## 매 결정 기준
+| 상황 | Approach |
+|---|---|
+| 2D canvas, simple chart | Canvas2D / SVG |
+| Standard 3D (low-mid) | Three.js (auto WebGL/WebGPU) |
+| GPGPU / ML inference | WebGPU + WGSL compute |
+| Cutting-edge graphics demo | WebGPU direct |
+| Wide compatibility (old Safari, Android Go) | WebGL2 fallback 유지 |
+
+**기본값**: 신규 project 매 WebGPU + WebGL2 fallback (Three.js / Babylon 매 자동).
+
+## 🔗 Graph
+- 변형: [[WebGL]] · [[WebGL 20|WebGL2]] · [[Vulkan]] · [[Metal]]
+- 응용: [[Three.js WebGPU]] · [[Babylon.js]]
+- Adjacent: [[WGSL]] · [[GPGPU]] · [[Compute Shader]]
+
+## 🤖 LLM 활용
+**언제**: Browser-side ML, high-end web visualization, GPGPU port to browser.
+**언제 X**: Old browser support 필수 (use WebGL2), simple UI animation (CSS / Canvas2D 충분).
+
+## ❌ 안티패턴
+- **WebGPU global singleton 매 sync init**: 매 async — `await requestAdapter`.
+- **Buffer leak**: `destroy()` 안 부름 — long-running app 매 OOM.
+- **Per-frame pipeline create**: 매 expensive — 매 cache.
+- **Bind group mismatch**: layout/binding index mismatch 매 silent error 의 매 source.
+- **No fallback path**: 매 unsupported environment 매 blank screen — feature detect 필수.
+- **Texture without proper usage flags**: 매 runtime validation error.
+
+## 🧪 검증 / 중복
+- Verified (W3C WebGPU spec 2024 CR, Chrome 130 release notes, Safari 18 WebGPU enablement).
+- 신뢰도 A.
+
+## 🕓 Changelog
+| 날짜 | 변경 |
+|---|---|
+| 2026-05-08 | Phase 1 |
+| 2026-05-10 | Manual cleanup — pipeline init, compute shader, ML inference patterns |