제 포스팅은 AI가 작성한게 아닌 한글자 한글자 타자를 쳐서 작성한 포스팅입니다. 구독 좋아요 댓글은 힘이됩니다.
안녕하세요~~~!!!
이번에 포스팅을 할 주제는!
깃 페이지 안에서 LLM 구현하고 작동시키기!!!
요즘 AI AI 떠드는데 막상 구글 API 연동해서 띡 돈내고 그냥 다 돈이고 참 피곤하셨죠ㅠㅠ딱해요ㅠAI 쓸라면 다 돈이고 ㅠ
최근 서버나 API 호출 없이 오직 사용자의 웹 브라우저 리소스(WebGPU)만으로 100% 로컬 AI 인퍼런스를 수행하는 에코시스템 대시보드, AMEVA Neural Fabric을 개발했습니다!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
AMEVA Neural Fabric — Edge-Native AI Dashboard
AMEVA Neural Fabric — Edge-Native AI Dashboard
Your browser does not support WebGPU, which is strictly required for the local LLM engine. We've switched you to Codex Mode so you can explore the network without local AI.
uno-km.github.io
개발 과정에서 900MB에 달하는 LLM 가중치 파일을 서빙하고 클라이언트의 극한 환경에 대응하면서 마주한 네트워크 대역폭 제한, CORS 필터링, 그리고 VRAM 충돌(OOM) 문제를 어떻게 우아한 Fallback 전략으로 해결했는지 그 엔지니어링 정수를 공유합니다.
챗봇을 누른다.
캐싱을 하는중입니다. 이건 어디 직접 바탕화면이나 그런데 쌓이지 않아요.
이렇게 물어볼수있습니다.
생성된 답변 하단엔 참조된 링크가 있습니다. 해당링크를 누르면 직접 해당 프로젝트 리포지토리를 구경하실수 있습니다.
코어 아키텍처: WebGPU + WebLLM을 활용한 Edge-Native AI
우리의 목표는 명확했습니다.
클라우드 서버나 OpenAI 등의 외부 유료 API에 1원도 쓰지 않고,
오프라인 환경에서도 구동되는 완벽한 엣지 네이티브 챗봇을 만드는 것
이었습니다.
이를 위해 사용한 기술 스택은 다음과 같습니다.
WebGPU: WebGL을 넘어 그래픽카드(GPU)의 연산 유닛에 로우레벨로 접근할 수 있게 해주는 현대 브라우저 표준 API입니다.
WebLLM (by MLC-AI): WebAssembly와 TVM 컴파일러 툴체인을 통해 양자화된 LLM(Qwen 2.5 1.5B Instruct - q4f16_1)을 브라우저 메모리에 올려 구동하는 엔진입니다.
하지만 기술 검증 단계를 넘어 실제 웹 서비스로 배포하는 과정에서 크나큰 장벽들을 마주하게 되었습니다.
난제 1: GitHub LFS의 밴드위스(대역폭) 지옥과 CORS의 덫
1) 100% 독립 호스팅을 향한 고집과 실패
완전한 소버린 호스팅을 추구하고자 900MB 크기의 모델 가중치를 우리 GitHub 저장소의 LFS(Large File Storage)에 업로드하여 서빙하려 했습니다.
그러나 GitHub 무료 플랜의 LFS 대역폭 제한은 월 1GB에 불과합니다. 개발 중 단 두 번의 테스트 로드만으로 한도가 초과되었고, 깃허브는 실제 모델 파일 대신 134바이트짜리 LFS 포인터 텍스트 파일을 반환하기 시작했습니다.
2) CORS 정책으로 인한 파일 크기 감지 불능
WebLLM 엔진은 134바이트짜리 포인터 파일을 진짜 116MB 크기의 가중치 파일 파드로 착각하고 다운로드하여 파싱하려다 Size Mismatch 오류로 크래시가 났습니다.
이를 사전에 방지하고자 파일의 실제 용량을 검사하려 했으나, 외부 원격 서버(raw.githubusercontent.com)로 보낸 HEAD 요청은 브라우저의 보안 통제인 CORS 정책으로 인해 파일 크기 헤더 정보를 차단당했습니다.
3) 돌파구: Streaming First-Chunk Cancel (첫 청크 스트리밍 취소 기법)
이 문제를 해결하기 위해 실제 GET 요청으로 스트림을 열되, 데이터를 전부 다운로드하지 않고 첫 번째 청크(앞부분 8바이트)만 읽은 뒤 즉시 스트림을 파괴하는 방어 로직을 설계했습니다.
async function checkLocalLfsHealth(url) {
try {
// 1. 전체 파일을 다 받지 않고 연결만 엽니다.
const res = await fetch(url + 'params_shard_0.bin');
if (!res.ok) return false;
// 2. ReadableStream 리더를 획득하여 첫 청크만 획득합니다.
const reader = res.body.getReader();
const { value } = await reader.read();
reader.cancel(); // 3. 그 즉시 다운로드를 중단(Cancel)하여 밴드위스 낭비를 차단합니다.
if (value && value.length >= 8) {
const text = new TextDecoder().decode(value.slice(0, 8));
// 만약 첫 8바이트가 LFS 포인터의 시작 규격인 "version " 이라면 대역폭 초과 상태!
if (text === "version ") {
console.warn("LFS 대역폭이 소진되어 포인터 파일이 반환되었습니다.");
return false;
}
}
return true;
} catch (e) {
return false;
}
}이 로직을 통해 1Byte의 데이터 낭비도 없이 원격 파일이 LFS 포인터인지 실제 가중치 바이너리인지 정확하게 구별해 냈고, 문제가 생겼을 때 Hugging Face CDN(무제한 트래픽) 경로로 즉시 우회하는 하이브리드 로드 아키텍처를 구축했습니다.
난제 2: IndexedDB 캐시 오염(Cache Poisoning)과 동적 모델 ID
우회 다운로드 처리를 했음에도 브라우저가 계속 죽는 또 다른 지옥을 만났습니다.
초기 다운로드 실패 과정에서 WebLLM 내부적으로 잘못 받아온 134바이트짜리 LFS 포인터 텍스트를 정상 모델로 인지하여 브라우저 저장소인 IndexedDB(캐시 레이어)에 저장해 버렸기 때문입니다.
이로 인해 경로를 Hugging Face로 돌렸음에도 이미 오염된 IndexedDB의 깨진 가중치를 계속 불러오며 무한 크래시 루프에 빠졌습니다.
해결책: Dynamic Model ID (동적 모델 ID 접미사)
사용자에게 "F12 개발자 도구를 열고 애플리케이션 캐시를 비우세요"라고 할 수는 없었습니다....
이를 해결하기 위해 Hugging Face Fallback 경로 진입 시, WebLLM 엔진에 전달하는 Model ID 뒤에 -HF 라는 접미사를 실시간으로 결합하도록 개발했습니다.
// Fallback 발생 시 기존 IndexedDB 캐시 명칭(Qwen2.5-1.5B...) 대신
// 새로운 네임스페이스(Qwen2.5-1.5B...-HF)를 사용하도록 유도
const appConfigHF = {
model_list: [
{
...defaultModelConfig,
model_id: modelId + "-HF"
}
]
};결과적으로 브라우저는 물리적으로 격리된 새로운 DB 테이블에 정상 가중치를 캐싱하게 되었고, 캐시 오염 문제가 소프트웨어 레벨조치완료 되었습니다.
난제 3: 클라이언트 기기의 한계와 OOM 방지용 하드웨어 폴백
PC 브라우저 환경에서는 1.5B 모델이 가볍게 돌지만, 저사양 노트북이나 일반 모바일 기기(아이폰, 갤럭시 등)에서 1.5GB가 넘는 VRAM을 브라우저에 할당하려고 시도하면 탭 자체가 강제 종료(OOM Crash)되는 현상이 비일비재했습니다.
해결책: 투 트랙(Two-Track) 사용자 경험 설계
접속 기기를 강제로 차단하여 사용자 경험을 단절하는 대신, 클라이언트 브라우저의 GPU 가속 여부를 판단하여 동적으로 인터페이스를 변경하는 투 트랙 Fallback을 구성했습니다.
WebGPU 가속 지원 기기 (High-End PC 등):
로컬 AI 모델을 가동하여 RAG 시스템과 실시간 대화가 가능한 "AMEVA Cortex" 활성화.
WebGPU 미지원 또는 모바일 기기 (Fallback):
로컬 AI 서빙을 비활성화하고, 생태계를 시네마틱 노드 그래프로 둘러보며 브라우저 내부 음성 엔진으로 해설을 듣는 도감 모드 "AMEVA Codex"로 전환.
클라우드 인프라 비용이 단 1원도 들지 않는 서버리스(Serverless) AI는 이제 개념을 넘어 현실이 되었습니다.
그것도 깃 페이지에서 말이지여ㅋㅋㅋ
우리가 설계한 LFS 스트리밍 판별 기법, 동적 캐싱 네임스페이스 스위칭, 그리고 D3 시각화와 결합된 하드웨어 폴백 기술은 제한된 컴퓨팅 자원과 불안정한 네트워크 속에서도 어떻게든 생각하고 진화하는 엣지 네이티브 시스템의 이정표입니다.
외부 서버 없이도 브라우저만으로 완전무결하게 돌아가는 포트폴리오를 구성하고 싶다면, WebGPU와 지능형 클라이언트 폴백 전략은 훌륭한 해답이 될 것입니다.
언젠간 빅테크 게섯거라...!!!
zhfldk014745@naver.com 으로 더 자세한 사항은 문의해주세요.
제 포스팅은 AI가 작성한게 아닌 한글자 한글자 타자를 쳐서 작성한 포스팅입니다. 구독 좋아요 댓글은 힘이됩니다.
댓글