| name | browser-local-ai-webllm |
| description | Run local LLMs directly in the browser via WebLLM (WebGPU) with NO middleware app — no Ollama, no PocketPal, no PC. Covers lazy-loading the ESM lib, WebGPU/HTTPS requirements, device analysis (RAM/VRAM), model-fit ranking, the Chrome 8GB deviceMemory cap, and OpenAI-compatible call/stream. ALWAYS use when adding in-browser local AI, running models client-side without a server, or the user says: локальний AI у браузері, WebLLM, без посередників, модель прямо в застосунку, WebGPU AI, браузерний AI, офлайн модель у браузері, run model in browser, on-device browser inference. Also triggers for: device analysis for model fit, VRAM detection, prebuiltAppConfig, MLCEngine. DO NOT use for server-side inference, native mobile inference, or when Ollama/LM Studio is the intended runtime (those are external providers). |
| license | Proprietary |
| metadata | {"version":"1.2.5","author":"Melania (Master Administrator)","category":"browser-ai","created":"2026-06-02T00:00:00.000Z","last_updated":"2026-07-26T00:00:00.000Z"} |
Browser-Local AI via WebLLM — v1.2.5
Напрацьовано на AI Gateway. Реальне рішення локального AI БЕЗ посередників: модель працює прямо в браузері/застосунку через WebGPU. Підтверджено тестуванням @mlc-ai/web-llm v0.2.84 (163 моделі, OpenAI-сумісний API).
Українською-перша: пояснення й приклади — українською за замовчуванням; код та технічні ідентифікатори лишаються англійською. Перемикання мови лише слідом за користувачем.
Неофіційний. Не пов'язаний з, не схвалений відкритим проєктом WebLLM / MLC AI. «WebLLM» — назва відкритого проєкту (MLC AI, Apache-2.0); вжита суто референційно (опис сумісності).
🛡️ Протокол Збереження Перед Оновленням (ОБОВ'ЯЗКОВО)
Обов'язковий перед БУДЬ-ЯКОЮ зміною цього скіла. Канонічне джерело (не дублювати тут): melania — секції «🛡️ Протокол Збереження Перед Оновленням» + «Update Workflow» + «Core Rule 10 — Re-Read Before Update».
Стисло: re-read диску → порівняти версії (диск новіший → диск база) → integrity-diff → validation-mesh → safety-compliance-gate (перед пакуванням/публікацією) → backup/snapshot → merge-not-replace → bump+CHANGELOG → показати diff і чекати явного схвалення MA (Закон II).
Core Rule
WebLLM працює ТІЛЬКИ в secure context (HTTPS або localhost) бо потребує WebGPU. На content:///file:// НЕ запуститься — це обмеження браузера, не коду. Завжди перевіряй navigator.gpu && window.isSecureContext перед спробою. (Канон secure-context правила — pwa-to-android-app Core Rule; тут лише WebGPU-специфічна перевірка.)
Critical Facts (підтверджено, не припущення)
- [C] PocketPal НЕ має локального API-сервера (open feature request) — не може бути middleware. WebLLM — реальна альтернатива.
- [C] window.ai / Gemini Nano НЕ працює на Android (desktop/ChromeOS only).
- [C] Chrome навмисне обмежує
navigator.deviceMemory до МАКС 8GB (приватність). Це НЕ баг. Дай користувачу ручне коригування. У нативному APK буде справжнє значення.
- [C] Список моделей фіксований версією WebLLM (тільки MLC-конвертовані). Довільну модель додати НЕ можна — для широкого вибору потрібні зовнішні Ollama/LM Studio або нативний застосунок.
Pattern 1 — Engine wrapper (ізольований для майбутньої заміни)
const WebLLMEngine={
_engine:null,_loadedModel:null,_lib:null,
CDN:"https://esm.run/@mlc-ai/web-llm@0.2.84",
isSupported(){return !!navigator.gpu && window.isSecureContext===true;},
async _loadLib(){
if(this._lib)return this._lib;
const imp=new Function("u","return import(u)");
return this._lib=await imp(this.CDN);
},
async getModels(){ const lib=await this._loadLib();
return (lib.prebuiltAppConfig?.model_list||[]).map(m=>({id:m.model_id,:m.,:!!m.}));
},
(){ lib= .();
=p=>onProgress?.(p.||,p.||);
(.) ..(modelId);
.= lib.(modelId,{:cb});
.=modelId; .;
},
(){ { lib= .(); lib.(id);}{ ;} },
(){ e= .(modelId);
r= e...({:sys?[{:,:sys},...msgs]:msgs,:mt,:});
{:r.[]..,:r.?.||};
},
*(){ e= .(modelId);
ch= e...({:sys?[{:,:sys},...msgs]:msgs,:mt,:});
(){ t=c.?.[]?.?.;(t) t;}
},
};
API engine.chat.completions.create ІДЕНТИЧНИЙ OpenAI — інтеграція в існуючий провайдер-ланцюг тривіальна.
Pattern 2 — Device Analysis (за замовчуванням, для підбору моделі)
const DeviceAnalyzer={
_cache:null,
async analyze(){
if(this._cache)return this._cache;
const info={deviceMemoryGB:navigator.deviceMemory||null,cores:navigator.hardwareConcurrency||null,webgpu:false,estVramMB:null};
if(navigator.gpu){ try{ const a=await navigator.gpu.requestAdapter();
if(a){info.webgpu=true; info.maxStorageMB=a.limits?.maxStorageBufferBindingSize?Math.round(a.limits.maxStorageBufferBindingSize/1048576):null;}
}catch{} }
info.ramCapped=info.deviceMemoryGB===8;
const manual=localStorage.getItem("manualRamGB");
(manual){info.=+manual;info.=;info.=.(+manual**);}
(info.) info.=.(info.**);
info.=info.?:;
.=info;
},
(){.=;},
(){ (vramMB&&estVramMB)?vramMB<=estVramMB*:;},
};
estVRAM ≈ 45% RAM (консервативно для мобільних). Завжди дай кнопки ручного коригування RAM (4/6/8/12/16/24GB) бо браузер бреше про 8GB.
Pattern 3 — Model ranking (найновіші + придатні вгорі)
const MODEL_FAMILY_RANK={"Qwen3.5":100,"Qwen3":95,"Llama-3.2":90,"Phi-4":88,"gemma3":86,"Qwen2.5":82,...};
function rankModels(models, estVramMB){
return models.map(m=>({...m, fam:familyOf(m.id), fits:DeviceAnalyzer.fits(m.vram,estVramMB), sizeB:parseFloat((m.id.match(/(\d+(?:\.\d+)?)B/)||[])[1]||999)}))
.filter(m=>m.fam!=="other" && /q4f16/.test(m.id))
.sort((a,b)=> (a.fits!==b.fits ? (b.fits?1:0)-(a.fits?1:0) : b.-a. || b.-a.));
}
Behavior
| Ситуація | ✓ Дія | ✗ Ніколи |
|---|
| WebGPU/HTTPS відсутній | сховати браузерний AI, чітко пояснити «потрібен HTTPS» | мовчки дати обрати і не завантажити |
| RAM показує рівно 8GB | позначити ramCapped, дати ручне коригування | вірити що це справжній максимум |
| Користувач хоче будь-яку модель | пояснити: браузер обмежений MLC-форматом; для широкого вибору → Ollama/нативний | обіцяти довільні моделі в браузері |
| Завантаження моделі | показати прогрес (initProgressCallback) + кеш-статус | мовчазне очікування ~6GB |
| Перша спроба моделі | перевірити isCached → попередити про розмір | качати без попередження |
| Інтеграція в ланцюг | tier 9, OpenAI-сумісний call/stream | окремий несумісний інтерфейс |
Verify before integrating (завжди)
npm install @mlc-ai/web-llm@0.2.84
node -e "const w=require('@mlc-ai/web-llm');console.log('models:',w.prebuiltAppConfig.model_list.length);const e=new w.MLCEngine();console.log('OpenAI-compat:',typeof e.chat.completions.create);"
Coordinates with
multi-provider-ai-orchestration — WebLLM як вузол ланцюга (tier 9)pwa-to-android-app — WebGPU запрацює після HTTPS-розгортанняsurgical-code-refactoring — інтеграція движка в існуючий код
Рекомендовані Моделі 2026
| Модель | VRAM | Швидкість | Якість | Use case |
|---|
Llama-3.2-1B-Instruct-q4f16_1-MLC | ~1GB | ⚡⚡⚡ | добра | тригери, класифікація |
Llama-3.2-3B-Instruct-q4f16_1-MLC | ~2GB | ⚡⚡ | краща | чат, короткі відповіді |
Phi-3.5-mini-instruct-q4f16_1-MLC | ~2.5GB | ⚡⚡ | відмінна | розуміння коду |
Qwen2.5-7B-Instruct-q4f16_1-MLC | ~5GB | ⚡ | дуже добра | загальне завдання |
Llama-3.1-8B-Instruct-q4f32_1-MLC | ~6GB | ⚡ | відмінна | best for quality |
Llama-3.3-70B | ~40GB | — | найкраща | лише в серверних браузерах |
Авто-вибір по deviceMemory:
const mem = navigator.deviceMemory || 4;
const model = mem >= 8 ? "Llama-3.1-8B-Instruct-q4f32_1-MLC"
: mem >= 4 ? "Qwen2.5-7B-Instruct-q4f16_1-MLC"
: mem >= 2 ? "Phi-3.5-mini-instruct-q4f16_1-MLC"
: "Llama-3.2-1B-Instruct-q4f16_1-MLC";
Streaming з Progress
const engine = new mlc.MLCEngine();
await engine.reload(model, {
initProgressCallback: (p) => {
updateUI(`⬇ ${(p.progress*100).toFixed(0)}% — ${p.text}`);
}
});
const chunks = await engine.chat.completions.create({
messages: conversation,
stream: true,
temperature: 0.7,
max_tokens: 512
});
let reply = "";
for await (const chunk of chunks) {
const delta = chunk.choices[0]?.delta?.content || "";
reply += delta;
appendToChat(delta);
}
Service Worker — Кешування Ваг
self.addEventListener('fetch', event => {
if (event.request.url.includes('mlc-ai/web-llm')) {
event.respondWith(
caches.open('webllm-v1').then(cache =>
cache.match(event.request).then(cached =>
cached || fetch(event.request).then(res => {
cache.put(event.request, res.clone());
return res;
})
)
)
);
}
});
Після першого завантаження моделі — наступні запуски offline ✓
📎 Advanced Patterns (v4)
Read references/advanced-webllm.md WHEN you need: function calling, browser embeddings (RAG offline), multi-model, structured generation.
Load only on demand — not proactively.
Зміни
⚠ Історична примітка: окремі ранні записи нижче мають дубльовані номери версій (артефакт злиттів). Усі записи збережено; нумерацію НЕ переписано без верифікації джерел.
-
v1.2.5 (2026-07-26) — Core Rule 14 Claim-evidence: 4 факти в Critical Facts отримали теги [C] (PocketPal без API-сервера, window.ai не на Android, cap deviceMemory 8GB, фіксований список моделей) — усі із зовнішніх джерел, власного прогону під них нема. Лише тегування, тіло незмінне.
-
v1.2.4 (2026-07-19) — Self-Dev Wave 2 (аудит 2026-07-18): дубль secure-context правила замінено покажчиком на канон у pwa-to-android-app Core Rule (WebGPU-специфічна перевірка лишилась тут) [#46]; синхрон H1-банера (був v1.0 при 1.2.3) + last_updated [#21/#45]. Лише де-дублювання/метадані.
-
v1.2.3 (2026-06-26) — Stage 3 S-2: примітка про дубль v1.2.0 у changelog (вміст збережено, нумерацію не переписано). Лише додавання примітки.
-
v1.2.2 (2026-06-15) — B2 (safety-compliance-gate): дисклеймер неприналежності — WebLLM (MLC AI).
-
v1.2.1 (2026-06-15) — DRY: «Протокол Збереження» → тонкий міст на канон у melania (де-дублювання + усунення 8-варіантного дрейфу). Поведінка незмінна — гейт той самий, джерело єдине.
-
v1.2.0 (2026-06-02) — додано metadata/license-frontmatter + явну директиву «українською-перша»; додано в Routing Map семантичного роутера. (аудит Кластер 4: metadata + P9 + P-23)
-
v1.1.0 (2026-06-02) — model matrix 2026, auto-select by deviceMemory, streaming+progress, SW caching.
-
v1.2.0 (2026-06-02) — Pre-Update Preservation Protocol; advanced-webllm reference (function calling, embeddings, multi-model).
