API 명세서 및 프로토콜 규격
클래스 시그니처, WebGPU 파이프라인 인터페이스, 반환값 및 에러 핸들링 (AMEVA-Forge)
Release: 
v1.0.1
핵심 가치 제안 (Why It Matters)
복잡한 셰이더 컴파일과 GPU 버퍼 바인딩을 추상화하여, 모던 웹 표준 API 1줄로 브라우저 상에서 LLM 및 딥러닝 모델을 직접 제어할 수 있는 표준 SDK 인터페이스입니다.
1. ForgeEngine 코어 API (TypeScript / JavaScript)
| 메서드 / 프로퍼티 | 시그니처 | 설명 및 엔지니어링 동작 |
|---|---|---|
ForgeEngine.init(options?) |
async init(opts?: ForgeOptions): Promise<WebGPUDeviceProfile> |
브라우저 WebGPU 어댑터를 초기화하고 WGSL 셰이더 모듈 및 파이프라인 레이아웃을 컴파일합니다. |
ForgeEngine.loadModel(source, onProgress?) |
async loadModel(src: string | File | Blob, cb?: (ratio: number) => void): Promise<ModelMetadata> |
Hugging Face URL 또는 로컬 파일에서 GGUF 가중치를 파싱하여 WebGPU VRAM에 바인딩합니다 (OPFS 캐시 지원). |
ForgeEngine.generate(prompt, options?) |
async *generate(prompt: string, opts?: GenOptions): AsyncGenerator<string> |
KV 캐시 기반 자동회귀 디코딩을 수행하며 생성된 토큰 문자열을 실시간 비동기 제너레이터로 스트리밍합니다. |
ForgeEngine.tokenize(text) |
tokenize(text: string): Int32Array |
Universal Byte-Level BPE 토크나이저를 구동하여 텍스트를 정수 토큰 ID 배열로 인코딩합니다. |
ForgeEngine.decode(tokens) |
decode(tokens: Int32Array | number[]): string |
토큰 ID 시퀀스를 원래의 UTF-8 문자열로 무손실 복원합니다. |
2. 브라우저 Autograd & 텐서 연산 API
| 함수 / 클래스 | 호출 형식 | 기능 설명 |
|---|---|---|
forge.tensor(data, shape, dtype?) |
forge.tensor([1, 2, 3, 4], [2, 2], 'float32') |
WebGPU 버퍼와 매핑되는 다차원 텐서 인스턴스를 생성합니다. |
forge.matmul(a, b) |
forge.matmul(tensorA, tensorB) |
타일드 WGSL 셰이더 커널을 통해 하드웨어 가속 행렬 곱셈을 수행합니다. |
tensor.backward() |
loss.backward() |
동적 연산 그래프(DAG)를 역방향 순회하여 모든 리프 텐서의 grad 버퍼를 갱신합니다. |
forge.optim.AdamW(params, lr) |
const opt = new forge.optim.AdamW(model.parameters(), 1e-3) |
WebGPU 가속 가중치 감쇠(Weight Decay) 모멘텀 최적화 알고리즘을 실행합니다. |
3. 에러 핸들링 및 예외 코드
| 예외 클래스 | 원인 및 발생 조건 | 권장 조치 방안 |
|---|---|---|
WebGPUNotSupportedError |
브라우저가 WebGPU를 지원하지 않거나 하드웨어 블랙리스트에 등록된 경우 | Chrome 113+ / Edge 113+ 브라우저 업데이트 안내 또는 하드웨어 가속 설정 확인. |
GGUFParseError |
GGUF 매직 헤더(GGUF) 불일치 또는 미지원 텐서 퀀트 타입 로드 시 |
Q4_K_M, Q8_0, F16 등 공식 지원 GGUF 모델 가중치 파일로 교체. |
VRAMAllocationLimitError |
요청한 KV 캐시 및 가중치 크기가 브라우저 WebGPU 버퍼 상한(maxBufferSize)을 초과한 경우 |
kvCacheBudgetMb 파라미터를 낮추거나 더 작은 모델(SmolLM-135M 등) 로드. |