企业官网建设流程全解析

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+ 浏览器（支持 WebGPU）
• Node.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 --mode=production", "dev": "webpack --mode=development --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 charset="utf-8"> <link rel="stylesheet" href="popup.css"> </head> <body> <div class="container"> <header> <h1>本地 LLM 助手</h1> <div class="status" id="status">模型未加载</div> </header> <div class="model-selector"> <label for="model-select">选择模型:</label> <select id="model-select"> <option value="tiny-llama">TinyLlama-1.1B</option> <option value="phi-2">Phi-2-3B</option> </select> </div> <div class="progress-container" id="progress-container" style="display: none;"> <progress id="model-progress" value="0" max="100"></progress> <span id="progress-text">0%</span> </div> <div class="chat-interface"> <div class="messages" id="messages"></div> <div class="input-area"> <textarea id="user-input" placeholder="输入您的问题..."></textarea> <button id="send-btn">发送</button> </div> </div> <div class="settings"> <button id="settings-btn">设置</button> </div> </div> <script src="popup.js"></script> </body> </html>

5.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', '[role="main"]' ]; 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 --mode=production", "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-dir=dist", "test": "web-ext lint --source-dir=dist" } }

10.2 发布到 Chrome 网上应用店

准备发布材料：

1. 扩展截图：准备 1280x800 和 640x400 两种尺寸的截图
2. 宣传图：440x280 的促销图片
3. 详细描述：包含功能特点和安装说明
4. 隐私政策：说明数据收集和使用情况

发布检查清单：

• [ ] 所有功能测试通过
• [ ] 隐私政策文档完善
• [ ] 截图和描述材料准备齐全
• [ ] 符合 Chrome 网上应用店政策要求
• [ ] 错误处理机制完善

通过本文的完整实现方案，你不仅能够构建一个功能完备的本地 LLM 浏览器扩展，还掌握了现代浏览器扩展开发的最佳实践。这种技术方案为需要在本地环境中运行 AI 功能的场景提供了可靠的解决方案，既保障了用户隐私，又提供了出色的用户体验。

在实际项目中，建议根据具体需求调整模型大小和功能组合，平衡性能与功能丰富度。随着 WebGPU 技术的不断成熟和本地 AI 推理技术的进步，这类本地化 AI 扩展的应用前景将更加广阔。