Mozilla Orbit 替代方案手把手教你构建本地大语言模型浏览器扩展在 Mozilla 宣布停止 Orbit 项目后许多依赖其功能的开发者面临工具链断裂的困境。本文基于实际需求完整演示如何构建一个功能完备的本地大语言模型local-LLM浏览器扩展从环境搭建到核心功能实现提供可直接复用的代码方案。无论你是前端开发者希望集成 AI 能力还是对浏览器扩展开发感兴趣的技术爱好者都能通过本文掌握本地 LLM 扩展的开发全流程。我们将使用 WebLLM 技术栈确保所有推理过程在本地完成无需依赖外部 API 服务。1. 项目背景与技术选型1.1 Mozilla Orbit 项目回顾Mozilla Orbit 曾是备受期待的浏览器 AI 助手项目旨在为用户提供智能化的网页内容分析和交互支持。然而随着项目战略调整Mozilla 决定停止 Orbit 的后续开发这给已经集成或计划使用该技术的开发者带来了不小的挑战。Orbit 的核心价值在于它能够在浏览器本地环境中运行 AI 模型既保护了用户隐私又提供了低延迟的交互体验。这种本地化 AI 方案在当前数据安全日益重要的背景下显得尤为珍贵。1.2 本地 LLM 扩展的技术优势构建本地运行的 LLM 浏览器扩展具有多个显著优势隐私保护所有数据处理都在用户设备上完成敏感信息不会上传到云端服务器符合严格的数据保护法规要求。离线可用无需网络连接即可使用 AI 功能适合在网络环境不稳定或需要完全离线工作的场景。成本可控避免了按使用量计费的云服务成本对于高频使用的应用场景尤其经济。低延迟响应本地推理消除了网络传输延迟能够实现近乎实时的交互体验。1.3 技术栈选择WebLLM 浏览器扩展 API我们选择 WebLLM 作为核心推理引擎这是一个基于 WebGPU 的高性能 LLM 运行环境具有以下特点跨平台兼容支持主流浏览器和操作系统性能优化利用现代 GPU 加速推理过程模型丰富兼容多种开源 LLM 模型格式易于集成提供简洁的 JavaScript API浏览器扩展部分采用标准的 Manifest V3 规范确保扩展的稳定性和安全性。2. 开发环境准备2.1 系统要求与工具配置在开始开发之前需要确保开发环境满足以下要求硬件要求支持 WebGPU 的显卡NVIDIA/AMD/Intel 近三代产品至少 8GB 系统内存2GB 以上可用存储空间用于模型文件软件环境Chrome 113 或 Edge 113 浏览器支持 WebGPUNode.js 18.0 运行环境代码编辑器VS Code 推荐验证环境配置 打开浏览器开发者工具在控制台中运行以下代码验证 WebGPU 支持if (navigator.gpu) { console.log(WebGPU 支持已启用); } else { console.error(当前浏览器不支持 WebGPU); }2.2 项目初始化与目录结构创建项目基础目录结构local-llm-extension/ ├── manifest.json # 扩展配置文件 ├── background.js # 后台脚本 ├── content.js # 内容脚本 ├── popup/ │ ├── popup.html # 弹出窗口界面 │ ├── popup.js # 弹出窗口逻辑 │ └── popup.css # 弹出窗口样式 ├── libs/ │ └── webllm/ # WebLLM 库文件 ├── models/ # LLM 模型文件 └── icons/ # 扩展图标初始化 package.json 文件{ name: local-llm-extension, version: 1.0.0, description: 本地大语言模型浏览器扩展, type: module, scripts: { build: webpack --modeproduction, dev: webpack --modedevelopment --watch }, devDependencies: { webpack: ^5.88.0, webpack-cli: ^5.1.0 } }3. 扩展核心架构设计3.1 Manifest V3 配置详解创建完整的 manifest.json 配置文件{ manifest_version: 3, name: 本地 LLM 助手, version: 1.0.0, description: 基于 WebLLM 的本地大语言模型浏览器扩展, permissions: [ activeTab, storage ], host_permissions: [ http://*/*, https://*/* ], background: { service_worker: background.js }, content_scripts: [ { matches: [all_urls], js: [content.js], css: [content.css] } ], action: { default_popup: popup/popup.html, default_title: 本地 LLM 助手 }, icons: { 16: icons/icon-16.png, 48: icons/icon-48.png, 128: icons/icon-128.png }, web_accessible_resources: [ { resources: [models/*, libs/*], matches: [all_urls] } ] }3.2 模块化架构设计采用模块化设计确保代码的可维护性和扩展性核心模块划分模型管理模块负责 LLM 模型的加载、初始化和推理调度界面交互模块处理弹出窗口和内容脚本的用户交互存储管理模块管理扩展的配置数据和会话历史通信桥梁模块协调各模块间的数据交换和事件传递// core/ModelManager.js class ModelManager { constructor() { this.model null; this.isInitialized false; } async initializeModel(modelPath) { // 模型初始化逻辑 } async generateResponse(prompt, options {}) { // 推理生成逻辑 } async cleanup() { // 资源清理逻辑 } } // core/StorageManager.js class StorageManager { constructor() { this.storage chrome.storage.local; } async saveConfig(config) { // 配置保存逻辑 } async loadConfig() { // 配置加载逻辑 } }4. WebLLM 集成与模型配置4.1 WebLLM 库集成方案WebLLM 提供了现代化的 Web 端 LLM 运行环境我们通过以下方式集成库文件引入!-- popup.html 中引入 -- script src../libs/webllm/webllm.js/script异步加载策略// popup.js 中的加载逻辑 class LLMEngine { constructor() { this.engine null; this.modelLoaded false; } async loadModel(modelUrl) { try { // 创建 WebLLM 实例 this.engine await webllm.CreateWebLLMEngine(); // 加载模型文件 await this.engine.loadModel(modelUrl, { initProgressCallback: (progress) { this.updateProgress(progress); } }); this.modelLoaded true; return true; } catch (error) { console.error(模型加载失败:, error); return false; } } updateProgress(progress) { // 更新加载进度界面 const progressElement document.getElementById(model-progress); if (progressElement) { progressElement.value progress * 100; progressElement.textContent 加载进度: ${Math.round(progress * 100)}%; } } }4.2 模型选择与优化配置针对浏览器环境的特点选择适合的轻量级模型推荐模型配置const MODEL_CONFIGS { tiny-llama: { name: TinyLlama-1.1B, url: ./models/tinyllama-1.1b-webllm.wasm, contextLength: 2048, requiredMemory: 2, // GB description: 轻量级模型适合大多数场景 }, phi-2: { name: Phi-2-3B, url: ./models/phi-2-3b-webllm.wasm, contextLength: 4096, requiredMemory: 4, // GB description: 中等规模平衡性能与精度 } };模型初始化优化async initializeWithOptimization() { const config { maxWindowSize: 1024, prefillChunkSize: 512, contextLength: 2048, temperature: 0.7, top_p: 0.9 }; // 预热推理提高首次响应速度 await this.engine.prefill(Hello); await this.engine.decode([]); // 清空上下文 return config; }5. 用户界面与交互设计5.1 弹出窗口界面实现设计简洁高效的弹出窗口界面!-- popup/popup.html -- !DOCTYPE html html head meta charsetutf-8 link relstylesheet hrefpopup.css /head body div classcontainer header h1本地 LLM 助手/h1 div classstatus idstatus模型未加载/div /header div classmodel-selector label formodel-select选择模型:/label select idmodel-select option valuetiny-llamaTinyLlama-1.1B/option option valuephi-2Phi-2-3B/option /select /div div classprogress-container idprogress-container styledisplay: none; progress idmodel-progress value0 max100/progress span idprogress-text0%/span /div div classchat-interface div classmessages idmessages/div div classinput-area textarea iduser-input placeholder输入您的问题.../textarea button idsend-btn发送/button /div /div div classsettings button idsettings-btn设置/button /div /div script srcpopup.js/script /body /html5.2 样式设计与响应式布局/* popup/popup.css */ .container { width: 400px; height: 500px; display: flex; flex-direction: column; font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif; } header { background: #2c3e50; color: white; padding: 15px; text-align: center; } .status { font-size: 12px; margin-top: 5px; padding: 3px 8px; border-radius: 10px; background: #34495e; display: inline-block; } .chat-interface { flex: 1; display: flex; flex-direction: column; } .messages { flex: 1; overflow-y: auto; padding: 10px; } .message { margin: 10px 0; padding: 8px 12px; border-radius: 8px; max-width: 80%; } .user-message { background: #3498db; color: white; margin-left: auto; } .assistant-message { background: #ecf0f1; color: #2c3e50; } .input-area { display: flex; padding: 10px; border-top: 1px solid #ddd; } #user-input { flex: 1; resize: none; padding: 8px; border: 1px solid #ddd; border-radius: 4px; margin-right: 10px; } #send-btn { padding: 8px 16px; background: #27ae60; color: white; border: none; border-radius: 4px; cursor: pointer; }6. 核心功能实现6.1 模型推理与文本生成实现高效的文字生成功能// core/TextGenerator.js class TextGenerator { constructor(modelEngine) { this.engine modelEngine; this.conversationHistory []; this.maxHistoryLength 10; } async generate(prompt, options {}) { const { maxTokens 256, temperature 0.7, topP 0.9, stopSequences [\n\n] } options; // 构建完整的对话上下文 const fullPrompt this.buildContext(prompt); try { const response await this.engine.generate(fullPrompt, { maxGenLen: maxTokens, temperature: temperature, top_p: topP, stop: stopSequences }); // 更新对话历史 this.updateHistory(prompt, response); return { text: response, tokens: response.length, // 简化计算 timestamp: Date.now() }; } catch (error) { console.error(文本生成失败:, error); throw new Error(生成失败: ${error.message}); } } buildContext(currentPrompt) { if (this.conversationHistory.length 0) { return currentPrompt; } const recentHistory this.conversationHistory .slice(-this.maxHistoryLength) .map(entry 用户: ${entry.prompt}\n助手: ${entry.response}) .join(\n\n); return ${recentHistory}\n\n用户: ${currentPrompt}\n助手:; } updateHistory(prompt, response) { this.conversationHistory.push({ prompt, response, timestamp: Date.now() }); // 保持历史记录长度 if (this.conversationHistory.length this.maxHistoryLength) { this.conversationHistory.shift(); } } clearHistory() { this.conversationHistory []; } }6.2 实时交互与流式输出实现类似 ChatGPT 的流式输出体验// core/StreamingGenerator.js class StreamingGenerator { constructor(modelEngine) { this.engine modelEngine; this.isGenerating false; this.abortController null; } async *generateStream(prompt, options {}) { if (this.isGenerating) { throw new Error(已有生成任务在进行中); } this.isGenerating true; this.abortController new AbortController(); try { const fullPrompt this.buildPrompt(prompt); let accumulatedText ; // 模拟流式输出实际实现依赖 WebLLM 的流式 API for await (const chunk of this.engine.generateStream(fullPrompt, options)) { if (this.abortController.signal.aborted) { break; } accumulatedText chunk; yield { chunk: chunk, fullText: accumulatedText, isComplete: false }; } yield { chunk: , fullText: accumulatedText, isComplete: true }; } finally { this.isGenerating false; this.abortController null; } } abort() { if (this.abortController) { this.abortController.abort(); } } buildPrompt(prompt) { // 添加系统提示词优化输出质量 return 你是一个有帮助的AI助手。请用中文回答用户的问题保持回答简洁明了。 用户: ${prompt} 助手:; } }7. 高级功能扩展7.1 网页内容分析与智能摘要扩展与网页内容的深度集成// content.js - 网页内容分析功能 class ContentAnalyzer { constructor() { this.analyzeButton null; this.setupContentAnalysis(); } setupContentAnalysis() { // 在页面右下角添加分析按钮 this.createAnalysisButton(); // 监听扩展消息 chrome.runtime.onMessage.addListener((request, sender, sendResponse) { if (request.action analyzePageContent) { this.analyzePageContent().then(sendResponse); return true; } }); } createAnalysisButton() { this.analyzeButton document.createElement(button); this.analyzeButton.innerHTML 智能分析; Object.assign(this.analyzeButton.style, { position: fixed, bottom: 20px, right: 20px, zIndex: 10000, padding: 10px 15px, backgroundColor: #3498db, color: white, border: none, borderRadius: 20px, cursor: pointer, fontSize: 14px, boxShadow: 0 2px 10px rgba(0,0,0,0.2) }); this.analyzeButton.addEventListener(click, () { this.triggerContentAnalysis(); }); document.body.appendChild(this.analyzeButton); } async analyzePageContent() { const pageText this.extractMainContent(); if (!pageText || pageText.length 100) { throw new Error(页面内容过少无法进行分析); } // 使用 LLM 进行分析 const analysisPrompt 请分析以下网页内容提供: 1. 主要内容摘要100字以内 2. 关键要点3-5个 3. 可能的后续问题建议 网页内容: ${pageText.substring(0, 2000)}...; return await this.sendToLLM(analysisPrompt); } extractMainContent() { // 智能提取正文内容排除导航、广告等 const contentSelectors [ article, main, .content, .post-content, [rolemain] ]; for (const selector of contentSelectors) { const element document.querySelector(selector); if (element) { return element.textContent.trim(); } } // 回退方案提取所有段落文本 const paragraphs Array.from(document.querySelectorAll(p)) .map(p p.textContent.trim()) .filter(text text.length 50); return paragraphs.join(\n\n); } }7.2 多标签页会话管理实现跨标签页的会话管理功能// background.js - 会话管理 class SessionManager { constructor() { this.sessions new Map(); // tabId - sessionData this.setupSessionHandling(); } setupSessionHandling() { // 标签页创建时初始化会话 chrome.tabs.onCreated.addListener((tab) { this.initializeSession(tab.id); }); // 标签页激活时切换会话 chrome.tabs.onActivated.addListener((activeInfo) { this.switchToSession(activeInfo.tabId); }); // 标签页关闭时清理会话 chrome.tabs.onRemoved.addListener((tabId) { this.cleanupSession(tabId); }); } initializeSession(tabId) { this.sessions.set(tabId, { conversationHistory: [], settings: this.getDefaultSettings(), createdAt: Date.now(), lastActive: Date.now() }); } getSession(tabId) { if (!this.sessions.has(tabId)) { this.initializeSession(tabId); } return this.sessions.get(tabId); } async saveSessionToStorage(tabId) { const session this.sessions.get(tabId); if (session) { await chrome.storage.local.set({ [session_${tabId}]: session }); } } async loadSessionFromStorage(tabId) { const result await chrome.storage.local.get([session_${tabId}]); if (result[session_${tabId}]) { this.sessions.set(tabId, result[session_${tabId}]); } } }8. 性能优化与内存管理8.1 模型加载优化策略针对大模型文件的加载进行优化// utils/ModelLoader.js class ModelLoader { constructor() { this.cache new Map(); this.loadingPromises new Map(); } async loadModelWithCache(modelUrl, options {}) { // 检查缓存 if (this.cache.has(modelUrl)) { return this.cache.get(modelUrl); } // 防止重复加载 if (this.loadingPromises.has(modelUrl)) { return this.loadingPromises.get(modelUrl); } const loadPromise this._loadModel(modelUrl, options); this.loadingPromises.set(modelUrl, loadPromise); try { const model await loadPromise; this.cache.set(modelUrl, model); return model; } finally { this.loadingPromises.delete(modelUrl); } } async _loadModel(modelUrl, options) { // 实现分块加载和进度跟踪 const response await fetch(modelUrl); const contentLength response.headers.get(content-length); const totalSize parseInt(contentLength, 10); let loadedSize 0; const chunks []; const reader response.body.getReader(); while (true) { const { done, value } await reader.read(); if (done) break; chunks.push(value); loadedSize value.length; // 更新进度 if (options.onProgress totalSize) { const progress loadedSize / totalSize; options.onProgress(progress); } } // 合并 chunks const blob new Blob(chunks); return await this.initializeModel(blob); } }8.2 内存使用监控与自动清理// utils/MemoryManager.js class MemoryManager { constructor() { this.memoryUsage 0; this.cleanupThreshold 0.8; // 80% 内存使用率时触发清理 this.setupMemoryMonitoring(); } setupMemoryMonitoring() { // 定期检查内存使用情况 setInterval(() { this.checkMemoryUsage(); }, 30000); // 每30秒检查一次 } async checkMemoryUsage() { if (typeof performance ! undefined performance.memory) { const memoryInfo performance.memory; const usageRatio memoryInfo.usedJSHeapSize / memoryInfo.totalJSHeapSize; if (usageRatio this.cleanupThreshold) { await this.triggerCleanup(); } } } async triggerCleanup() { console.log(内存使用过高触发清理操作); // 清理对话历史 this.clearOldConversations(); // 强制垃圾回收如果可用 if (window.gc) { window.gc(); } // 清理模型缓存 await this.clearModelCache(); } clearOldConversations() { const now Date.now(); const oneHourAgo now - 60 * 60 * 1000; // 清理一小时前的对话记录 // 实现逻辑... } }9. 错误处理与调试方案9.1 全面错误处理机制建立完善的错误处理体系// utils/ErrorHandler.js class ErrorHandler { static setupGlobalErrorHandling() { // 全局错误捕获 window.addEventListener(error, (event) { this.logError(全局错误, event.error); }); // Promise 拒绝捕获 window.addEventListener(unhandledrejection, (event) { this.logError(未处理的 Promise 拒绝, event.reason); }); // 扩展特定错误处理 chrome.runtime.onMessage.addListener((request, sender, sendResponse) { if (request.action reportError) { this.handleReportedError(request.error); } }); } static logError(context, error) { const errorInfo { context, message: error.message, stack: error.stack, timestamp: new Date().toISOString(), userAgent: navigator.userAgent, extensionVersion: chrome.runtime.getManifest().version }; console.error(扩展错误:, errorInfo); // 保存到本地存储供调试使用 this.saveErrorToStorage(errorInfo); } static async saveErrorToStorage(errorInfo) { try { const errors await this.getStoredErrors(); errors.push(errorInfo); // 只保留最近的50个错误 if (errors.length 50) { errors.splice(0, errors.length - 50); } await chrome.storage.local.set({ errorLogs: errors }); } catch (storageError) { console.error(保存错误日志失败:, storageError); } } }9.2 调试工具与日志系统实现详细的调试支持// utils/DebugLogger.js class DebugLogger { constructor() { this.logLevel this.getLogLevel(); this.logs []; } getLogLevel() { // 从存储中获取日志级别设置 return localStorage.getItem(debugLogLevel) || info; } log(level, message, data null) { const timestamp new Date().toISOString(); const logEntry { level, message, data, timestamp, tabId: this.getCurrentTabId() }; this.logs.push(logEntry); // 控制台输出 if (this.shouldLog(level)) { console[level]([${timestamp}] ${message}, data || ); } // 存储日志生产环境可关闭 this.persistLog(logEntry); } shouldLog(level) { const levels [error, warn, info, debug]; const currentLevelIndex levels.indexOf(this.logLevel); const messageLevelIndex levels.indexOf(level); return messageLevelIndex currentLevelIndex; } exportLogs() { return JSON.stringify(this.logs, null, 2); } clearLogs() { this.logs []; } } // 使用示例 const logger new DebugLogger(); logger.log(info, 模型加载开始, { model: tiny-llama });10. 部署与发布指南10.1 扩展打包与测试创建完整的构建脚本{ scripts: { build: npm run build:js npm run build:css npm run copy:assets, build:js: webpack --modeproduction, build:css: postcss src/**/*.css --dir dist, copy:assets: cp -r icons dist/ cp -r models dist/, pack: npm run build web-ext build --source-dirdist, test: web-ext lint --source-dirdist } }10.2 发布到 Chrome 网上应用店准备发布材料扩展截图准备 1280x800 和 640x400 两种尺寸的截图宣传图440x280 的促销图片详细描述包含功能特点和安装说明隐私政策说明数据收集和使用情况发布检查清单[ ] 所有功能测试通过[ ] 隐私政策文档完善[ ] 截图和描述材料准备齐全[ ] 符合 Chrome 网上应用店政策要求[ ] 错误处理机制完善通过本文的完整实现方案你不仅能够构建一个功能完备的本地 LLM 浏览器扩展还掌握了现代浏览器扩展开发的最佳实践。这种技术方案为需要在本地环境中运行 AI 功能的场景提供了可靠的解决方案既保障了用户隐私又提供了出色的用户体验。在实际项目中建议根据具体需求调整模型大小和功能组合平衡性能与功能丰富度。随着 WebGPU 技术的不断成熟和本地 AI 推理技术的进步这类本地化 AI 扩展的应用前景将更加广阔。