React + WebGPU + ONNX：构建浏览器本地运行的隐私优先LLM应用-平芜编程栈

1. 项目概述：为什么我们要把LLM“请”到本地？

最近几个月，我身边不少做前端和全栈的朋友都在讨论同一个问题：如何在不依赖云端API的情况下，把大语言模型（LLM）的能力集成到自己的Web应用里。原因很简单，大家受够了。受够了调用OpenAI、Claude这些接口时，对网络延迟的焦虑，对每月账单的心疼，更关键的是，对数据隐私和安全性的深深担忧。一个简单的聊天记录，一次代码生成的请求，都可能在不经意间离开你的设备，去往一个你无法掌控的远方服务器。对于处理敏感信息的企业内部工具、教育软件，或者仅仅是追求极致隐私的个人项目，这都成了一个无法绕开的痛点。

于是，“本地部署LLM”从一个极客圈的小众话题，迅速变成了一个具有普遍性的工程需求。但传统的本地部署方案，比如用Python后端搭配PyTorch，对前端开发者来说门槛不低，环境配置复杂，资源消耗也大。直到WebGPU的出现，事情开始有了转机。WebGPU让我们可以直接在浏览器这个最普及的“客户端”里，调用GPU进行高性能通用计算。那么，一个大胆的想法自然浮现：能不能用React构建用户界面，用WebGPU在浏览器里直接运行一个精简版的LLM，实现真正的“开箱即用、数据不出本地”？

这个项目，就是对这个想法的一次完整实践和探索。它不只是一个技术Demo，而是一套可供参考的、用于构建下一代隐私优先、离线可用的AI Web应用的方案。如果你是一名React开发者，对AI应用感兴趣，又希望完全掌控数据和计算过程，那么接下来的内容，就是为你准备的“从零到一”实操指南。

2. 核心架构与工具选型：为什么是React + WebGPU + ONNX？

当我们决定在浏览器里跑模型，技术选型就变得非常关键。这不像在服务器端，有成熟的CUDA生态和丰富的框架。浏览器的沙箱环境、有限的资源和对安全性的苛刻要求，都意味着我们需要一套全新的工具链。

2.1 前端框架：为什么选择React？

选择React几乎是顺理成章的。它庞大的生态系统、声明式的UI构建方式，以及高效的虚拟DOM更新，非常适合构建复杂的交互式应用，比如一个聊天界面或者一个带有实时推理状态显示的AI工具。更重要的是，React社区有大量成熟的组件库（如MUI, Ant Design）和状态管理方案（Zustand, Redux Toolkit），能让我们快速搭建起美观且健壮的应用外壳，而把主要精力集中在核心的模型推理逻辑上。

一个典型的应用结构可能是：用React组件管理聊天消息列表、输入框和设置面板，用状态管理库来维护对话历史、模型加载状态和推理参数（如temperature, top_p）。React的响应式特性能让UI随着推理过程的进行（如token的逐个生成）而平滑更新。

2.2 计算引擎：为什么是WebGPU，而不是WebGL或WASM？

这是整个架构的基石。我们有几个候选：纯JavaScript（太慢）、WebAssembly（WASM）（有一定加速）、WebGL（为图形设计，通用计算别扭）、WebGPU（新一代通用计算API）。

WebGL：虽然可以通过图形API“伪装”成计算API（用纹理存储数据，用片元着色器进行计算），但这种方式极其晦涩，编程模型不直观，且对很多计算任务优化不足。它就像用螺丝刀去敲钉子，不是不行，但很费劲。
WASM：通过将C++/Rust编写的模型推理引擎（如GGML库）编译成WASM，可以在浏览器中获得不错的性能。这是目前很多“本地LLM”方案的选择（例如通过llama.cpp的WASM构建）。但它仍然主要依赖CPU进行计算，对于LLM这种计算密集型任务，无法利用现代设备中强大的GPU，性能天花板明显。
WebGPU：它是为现代GPU和通用计算而生的底层API。它提供了更接近Metal/Vulkan/DirectX 12的现代GPU编程模型，能够更高效地调度计算着色器（Compute Shader），直接操作GPU的并行计算单元。对于矩阵乘法（LLM推理的核心）这类任务，WebGPU能带来数量级级别的性能提升。简而言之，WebGPU是让我们能在浏览器中榨干设备GPU潜力的唯一标准途径。

注意：WebGPU的浏览器支持仍在推进中。截至2024年中，Chrome 113+、Edge 113+已默认开启，Firefox和Safari也在积极跟进。在项目启动前，务必检查你的目标用户群体的浏览器环境，或做好功能降级（回退到WASM）的准备。

2.3 模型格式：为什么是ONNX？

选定了计算引擎，接下来要决定用什么格式的模型。我们不可能直接把PyTorch的.pt或TensorFlow的.pb文件扔给浏览器。模型需要被转换成一个跨平台、高效且能被WebGPU轻松操作的格式。

ONNX（Open Neural Network Exchange）成为了我们的首选。它是一个开放的模型格式标准，几乎所有主流训练框架（PyTorch, TensorFlow等）都能将模型导出为ONNX格式。更重要的是，有一个非常关键的库：onnxruntime-web。这个库是微软ONNX Runtime的Web版本，它提供了一个统一的JavaScript API来加载和运行ONNX模型。而其最强大的特性在于，它内置了WebGPU后端执行提供程序（EP）。这意味着，当我们通过onnxruntime-web加载一个ONNX模型时，它可以自动（或在我们的配置下）尝试使用WebGPU来执行模型中的算子，如果失败则回退到WASM后端。

这样一来，我们就不需要自己用WGSL（WebGPU的着色器语言）去手写每一个神经网络层了。onnxruntime-web帮我们完成了最繁重的工作：将ONNX模型图翻译成高效的WebGPU计算管线。我们的代码只需要关注如何准备输入数据、调用会话（Session）进行推理，以及处理输出数据。

工具链总结：

模型准备：在Python环境中，使用torch.onnx.export将训练好的模型（如一个精简版的Llama 2 7B-Chat或Phi-2）转换为ONNX格式。这一步可能涉及模型裁剪、量化（如INT8量化）以减小模型体积和提升推理速度。
核心运行时：在React应用中，通过npm安装onnxruntime-web。
应用构建：使用React + TypeScript + Vite（或Webpack）构建项目，通过onnxruntime-web的API加载并运行ONNX模型，利用WebGPU加速。
模型分发：将转换好的ONNX模型文件（可能是分片的）放置在项目的public目录或通过CDN分发，供前端应用异步加载。

这个组合，构成了我们“零数据上传、离线可用”的坚实技术底座。

3. 从零开始：环境搭建与项目初始化

理论说完了，我们动手搭建一个最小的可运行项目。这里假设你已具备基本的Node.js和React开发环境。

3.1 创建React项目并安装核心依赖

我们使用Vite来快速搭建，因为它对现代前端工具链支持更好，构建速度更快。

npm create vite@latest local-llm-webgpu-app -- --template react-ts cd local-llm-webgpu-app npm install

接下来，安装最核心的依赖——onnxruntime-web。我们需要安装支持WebGPU的版本。

npm install onnxruntime-web

同时，我们安装一些辅助库，用于UI和状态管理，这里以Zustand和MUI为例：

npm install @mui/material @emotion/react @emotion/styled @mui/icons-material npm install zustand

3.2 配置Vite以处理WASM和资源文件

onnxruntime-web会依赖一些WASM二进制文件。我们需要配置Vite，确保这些文件能被正确打包和提供服务。

在vite.config.ts中添加以下配置：

import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' export default defineConfig({ plugins: [react()], assetsInclude: ['**/*.onnx'], // 告诉Vite，.onnx文件是资源 optimizeDeps: { exclude: ['onnxruntime-web'], // 避免预构建onnxruntime-web，防止出现问题 }, })

3.3 准备一个精简的ONNX模型

这是最具挑战性的一步。我们无法在浏览器中运行一个完整的700亿参数模型。我们需要一个小型、高效的模型。对于入门和演示，可以从以下途径获取：

Hugging Face Model Hub：搜索“onnx”和“small”标签，例如microsoft/phi-2的ONNX量化版本，或者一些专门为边缘设备优化的模型如Qwen/Qwen2.5-0.5B-Instruct-onnx。确保模型文件是.onnx格式。
自行转换：如果你有PyTorch模型，可以使用以下脚本进行转换和动态量化（以简化版模型为例）：

import torch import torch.onnx from transformers import AutoModelForCausalLM, AutoTokenizer # 1. 加载模型和分词器 (这里以一个超小模型为例，实际需替换) model_name = "microsoft/phi-2" tokenizer = AutoTokenizer.from_pretrained(model_name) model = AutoModelForCausalLM.from_pretrained(model_name, torch_dtype=torch.float32) # 为演示，我们只取模型的前几层，或者使用官方提供的精简版 # 这里假设我们有一个已经处理好的`tiny_model`（例如只有解码器的前几层） tiny_model = ... # 你的精简模型 # 2. 设置模型为评估模式 tiny_model.eval() # 3. 定义输入样例（维度：batch_size, sequence_length） dummy_input = torch.randint(0, tokenizer.vocab_size, (1, 16)) # 4. 导出为ONNX torch.onnx.export( tiny_model, dummy_input, "tiny_llm.onnx", input_names=["input_ids"], output_names=["logits"], dynamic_axes={ 'input_ids': {1: 'sequence_length'}, # 动态序列长度 }, opset_version=15, # 使用较高的opset版本 ) print("模型已导出为 tiny_llm.onnx")

重要提示：自行转换和量化是一个专业且复杂的过程，涉及模型结构修改、算子兼容性检查等。对于初学者，强烈建议先从Hugging Face下载现成的、已验证可在浏览器中运行的ONNX模型开始。将下载好的model.onnx文件放入项目的public/models/目录下。

4. 核心实现：在React中集成ONNX Runtime与WebGPU

现在，我们进入最核心的编码环节：创建一个自定义Hook来管理模型的加载和推理。

4.1 创建模型推理Hook

在src/hooks/useONNXModel.ts中，我们创建这个逻辑中心。

import { useState, useCallback, useRef } from 'react'; import { InferenceSession, Tensor } from 'onnxruntime-web'; interface UseONNXModelReturn { loading: boolean; error: string | null; loadModel: (modelPath: string) => Promise<void>; runInference: (inputIds: number[]) => Promise<number[]>; isReady: boolean; } export const useONNXModel = (): UseONNXModelReturn => { const [loading, setLoading] = useState(false); const [error, setError] = useState<string | null>(null); const sessionRef = useRef<InferenceSession | null>(null); const [isReady, setIsReady] = useState(false); const loadModel = useCallback(async (modelPath: string) => { setLoading(true); setError(null); try { // 关键配置：指定执行提供程序为‘webgpu’，并设置回退 const session = await InferenceSession.create(modelPath, { executionProviders: ['webgpu', 'wasm'], // 优先尝试WebGPU，失败则用WASM graphOptimizationLevel: 'all', // 启用所有图优化 }); sessionRef.current = session; setIsReady(true); console.log(`模型加载成功，使用执行提供程序: ${session.providers.join(', ')}`); } catch (err) { const errMsg = `模型加载失败: ${err}`; setError(errMsg); console.error(errMsg, err); } finally { setLoading(false); } }, []); const runInference = useCallback(async (inputIds: number[]): Promise<number[]> => { if (!sessionRef.current) { throw new Error('模型未加载，请先调用 loadModel'); } // 1. 准备输入Tensor // ONNX模型通常期望输入是Int64或Int32类型，形状为 [batch_size, sequence_length] const inputTensor = new Tensor('int64', BigInt64Array.from(inputIds.map(id => BigInt(id))), [1, inputIds.length]); // 2. 准备模型输入 feeds const feeds: Record<string, Tensor> = {}; // 这里需要根据你的具体ONNX模型的输入节点名来设置，可能是“input_ids” feeds['input_ids'] = inputTensor; // 3. 运行推理 const results = await sessionRef.current.run(feeds); // 4. 处理输出 // 输出节点名也可能是“logits”，需要根据模型定义调整 const outputTensor = results['logits']; // 将输出Tensor转换为JavaScript数组，这里简化处理，取最后一个token的logits const logitsData = outputTensor.data as Float32Array; // 假设输出形状是 [batch, seq, vocab_size]，我们取最后一个序列位置的logits const vocabSize = outputTensor.dims[2]; const startIdx = (inputIds.length - 1) * vocabSize; const lastTokenLogits = Array.from(logitsData.slice(startIdx, startIdx + vocabSize)); return lastTokenLogits; // 返回词汇表大小的概率分布 }, []); return { loading, error, loadModel, runInference, isReady }; };

这个Hook封装了模型的生命周期：loadModel负责异步加载模型文件并创建推理会话，runInference负责执行一次前向传播。关键在于executionProviders: ['webgpu', 'wasm']这个配置，它指示ONNX Runtime优先尝试使用WebGPU加速。

4.2 构建简单的文本生成循环

LLM的文本生成是一个自回归过程：根据已有的tokens预测下一个token，然后将这个token加入输入，继续预测下一个。我们需要实现这个循环。在src/utils/textGenerator.ts中：

import { useONNXModel } from '../hooks/useONNXModel'; // 假设我们有一个简单的分词器工具（实际中需要集成一个JS分词器，如`bert-tokenizer`或`sentencepiece`） import { simpleTokenizer } from './tokenizer'; export const useTextGenerator = (modelPath: string) => { const { loadModel, runInference, isReady, loading, error } = useONNXModel(); const [isGenerating, setIsGenerating] = useState(false); const [context, setContext] = useState<number[]>([]); // 存储当前的token ID序列 // 初始化加载模型 useEffect(() => { loadModel(modelPath); }, [modelPath, loadModel]); const generateNextToken = async (): Promise<number> => { if (!isReady || context.length === 0) { throw new Error('模型未就绪或上下文为空'); } const logits = await runInference(context); // 简单的采样策略：选择logits最大的token（贪心搜索） let maxIdx = 0; let maxVal = logits[0]; for (let i = 1; i < logits.length; i++) { if (logits[i] > maxVal) { maxVal = logits[i]; maxIdx = i; } } return maxIdx; }; const generateText = async (prompt: string, maxTokens: number = 50): Promise<string> => { setIsGenerating(true); try { // 1. 将提示词编码为token IDs let tokenIds = simpleTokenizer.encode(prompt); setContext(tokenIds); let generatedTokens: number[] = []; for (let i = 0; i < maxTokens; i++) { // 2. 预测下一个token const nextTokenId = await generateNextToken(); generatedTokens.push(nextTokenId); // 3. 更新上下文（在实际模型中，可能需要管理KV Cache，这里简化） tokenIds.push(nextTokenId); setContext([...tokenIds]); // 更新状态，可能会触发UI更新显示部分结果 // 4. 简单解码并检查终止条件（如遇到结束符） const token = simpleTokenizer.decode([nextTokenId]); if (token === '<|endoftext|>') { // 假设的结束符 break; } } // 5. 解码全部生成的tokens const fullText = simpleTokenizer.decode(generatedTokens); return fullText; } finally { setIsGenerating(false); } }; return { generateText, isGenerating, loading, error, isReady }; };

这个实现是高度简化的。一个生产级的实现需要考虑：

高效的KV Cache：避免每次推理都重新计算所有历史token的注意力，这是LLM推理优化的关键。
更复杂的采样：如Top-p (nucleus)采样、温度采样。
流式输出：逐个token生成并实时更新UI。
完整的分词器：集成一个真正的子词分词器（如Tiktoken的Web版本或SentencePiece）。

4.3 创建React UI组件

最后，我们创建一个简单的UI来连接这一切。在src/App.tsx中：

import { useState } from 'react'; import { Button, TextField, CircularProgress, Alert, Box, Typography } from '@mui/material'; import { useTextGenerator } from './utils/textGenerator'; function App() { const [prompt, setPrompt] = useState('你好，请介绍一下你自己。'); const [generatedText, setGeneratedText] = useState(''); const modelPath = '/models/tiny_llm.onnx'; // 模型在public目录下的路径 const { generateText, isGenerating, loading, error, isReady } = useTextGenerator(modelPath); const handleGenerate = async () => { if (!prompt.trim()) return; const text = await generateText(prompt, 100); setGeneratedText(text); }; return ( <Box sx={{ maxWidth: 800, margin: '40px auto', padding: 3 }}> <Typography variant="h4" gutterBottom> 本地LLM演示 (React + WebGPU) </Typography> {error && <Alert severity="error" sx={{ mb: 2 }}>{error}</Alert>} {loading && <Alert severity="info">正在加载模型...</Alert>} <TextField fullWidth multiline rows={4} label="输入提示词" value={prompt} onChange={(e) => setPrompt(e.target.value)} disabled={!isReady || isGenerating} sx={{ mb: 2 }} /> <Button variant="contained" onClick={handleGenerate} disabled={!isReady || isGenerating || loading} startIcon={isGenerating ? <CircularProgress size={20} /> : null} > {isGenerating ? '生成中...' : '生成文本'} </Button> {generatedText && ( <Box sx={{ mt: 4, p: 2, border: '1px solid #ccc', borderRadius: 1 }}> <Typography variant="h6">生成结果：</Typography> <Typography>{generatedText}</Typography> </Box> )} <Box sx={{ mt: 4, fontSize: '0.9em', color: 'gray' }}> <Typography variant="body2"> 状态: {isReady ? '模型就绪 (使用 ' + (window.navigator.gpu ? 'WebGPU' : 'WASM') + ')' : '未就绪'} </Typography> <Typography variant="body2"> 说明：这是一个演示项目，使用的模型能力有限。所有计算均在您的浏览器本地完成，无数据上传。 </Typography> </Box> </Box> ); } export default App;

至此，一个最基础的、能在浏览器中利用WebGPU（或回退到WASM）运行本地LLM的React应用就搭建起来了。运行npm run dev，打开浏览器（需支持WebGPU），你应该能看到界面。输入提示词并点击生成，就能体验到完全离线的AI文本生成。

5. 性能优化与生产级考量

上面的Demo跑通只是第一步。要让它真正可用，我们需要解决性能、体验和稳定性问题。

5.1 模型优化：量化与裁剪

浏览器环境对资源极其敏感。一个未经优化的7B参数模型，仅权重文件就可能超过14GB（FP16），这是不可接受的。

量化（Quantization）：这是最重要的优化手段。将模型权重从FP32或FP16转换为INT8甚至INT4，可以大幅减少模型体积和内存占用，同时推理速度也能提升。ONNX Runtime支持多种量化格式。在模型转换时，就应使用onnxruntime的量化工具进行处理。
模型裁剪（Pruning）：移除模型中不重要的权重，在精度损失可控的情况下减小模型大小。可以寻找已经过裁剪和量化的模型，如llama.cpp社区提供的GGUF格式模型，并尝试将其转换为ONNX。
选择小模型：从微型模型开始，如Phi-2 (2.7B)、Qwen2.5-0.5B、TinyLlama等。它们在有限的资源下能提供更有意义的输出。

5.2 推理优化：KV Cache与批处理

实现KV Cache：这是LLM推理的“标配”。在自回归生成中，每次前向传播都会为之前的token计算Key和Value向量并缓存起来，下次生成时直接复用，避免重复计算。ONNX模型需要支持past_key_values的输入和输出。你需要找到一个已经导出为支持KV Cache格式的ONNX模型，或者在导出时配置好。在推理循环中，你需要维护并传递这个Cache。
注意力优化：WebGPU对于矩阵乘法和注意力计算有天然优势。确保你的ONNX模型使用了高效的注意力算子（如FlashAttention的ONNX实现）。onnxruntime-web的WebGPU后端会尝试优化这些算子的执行。

5.3 用户体验优化

流式输出（Streaming）：不要等所有token生成完再一次性显示。利用React的状态更新，每生成一个或几个token就更新一次UI，让用户立即看到生成过程。这需要将generateText函数改造成一个异步生成器（async generator）。
模型分片与懒加载：大型模型可以分割成多个文件。在应用初始化时只加载必要的部分（如分词器和第一层），在用户首次触发推理时再按需加载其他分片。这可以显著缩短应用的首屏加载时间。
降级与兼容性处理：在InferenceSession.create时，我们配置了['webgpu', 'wasm']。如果WebGPU不可用，会自动降级到WASM。你应该在UI上明确告知用户当前使用的后端。WASM速度虽慢，但保证了基本功能的可用性。

5.4 安全与隐私强化

这是我们方案的核心优势，但仍需注意：

彻底的离线：确保所有资源（模型文件、分词器数据、wasm文件）都能在无网络环境下通过Service Worker缓存或打包在应用中。使用localStorage或IndexedDB缓存模型文件，避免重复下载。
输入输出审查：虽然数据不出本地，但应用本身（前端代码）是暴露的。避免在客户端代码中硬编码敏感逻辑。如果涉及非常敏感的处理，可以考虑与WebAssembly编写的、经过混淆的本地安全模块结合。

6. 常见问题与排查技巧实录

在实际开发和测试中，我遇到了不少坑。这里记录下最常见的问题和解决方法。

6.1 WebGPU初始化失败

问题：控制台报错Failed to create WebGPU device或navigator.gpu is undefined。排查：

浏览器不支持：访问chrome://gpu或about:gpu，查看“Graphics Feature Status”中“WebGPU”是否为“Enabled”。确保Chrome/Edge版本在113以上，并在chrome://flags中确认“Unsafe WebGPU”未被启用（正式版中不应需要）。
硬件或驱动问题：某些旧显卡或集成显卡可能不支持WebGPU所需的特性集。可以尝试更新显卡驱动。
安全上下文：WebGPU要求页面在安全上下文中运行，即通过https://或http://localhost访问。如果你在file://协议下打开，WebGPU将不可用。开发时务必使用localhost。

6.2 ONNX模型加载或推理错误

问题：InferenceSession.create失败或session.run抛出异常。排查：

模型路径错误：确保modelPath是相对于服务器根目录或public目录的正确路径。使用浏览器开发者工具的“网络（Network）”标签页，查看模型文件是否成功加载（状态码200）。
模型格式或Opset不兼容：ONNX模型有版本（opset）之分。确保onnxruntime-web支持的opset版本包含你的模型版本。尝试使用onnx库的version_converter工具将模型转换为较新的opset版本。
输入/输出名称不匹配：这是最常见的问题。session.run(feeds)中的feeds对象键名必须与模型输入节点名称完全一致。使用Netron（一个可视化工具）打开你的.onnx模型文件，查看输入（input）和输出（output）节点的名称。我们的示例代码中用的'input_ids'和'logits'只是示例，你必须替换成自己模型的实际名称。
输入数据类型或形状错误：同样使用Netron查看模型输入节点的数据类型（如int64,float32）和形状（如[1, -1]，其中-1表示动态维度）。在创建Tensor时，必须严格匹配。

6.3 推理速度极慢或内存溢出

问题：生成一个token需要好几秒，或者浏览器标签页崩溃。排查：

使用了WASM后端：在控制台查看模型加载时的日志，确认是否回退到了wasm后端。WASM后端在CPU上运行，对于大模型会非常慢。优先解决WebGPU的可用性问题。
模型太大：即使是量化后的模型，如果参数量过大（如超过3B），在消费级设备的GPU内存（通常4-8GB）中也可能放不下。尝试更小的模型，或进行更激进的量化（INT4）。
未启用KV Cache：每次推理都传入全部历史token，计算量随对话长度平方级增长。必须使用支持KV Cache的模型和推理逻辑。
浏览器内存限制：单个浏览器标签页的内存使用是有限制的。复杂的模型和长的上下文会消耗大量内存。监控浏览器的任务管理器，观察内存使用情况。

6.4 生成的文本质量差或无意义

问题：模型能跑通，但生成的文字是乱码或重复的废话。排查：

分词器不匹配：这是头号原因。ONNX模型只包含计算图，不包含分词器。你必须使用与模型原始训练时完全一致的分词器。如果模型是bert-base-uncased，你就必须使用对应的BertTokenizer。将正确的分词器（通常是vocab.json和merges.txt等文件）集成到前端项目中，并使用相同的编码/解码逻辑。
预处理/后处理错误：检查输入模型的token IDs是否正确。有些模型需要在输入前后添加特殊的token，如<s>,</s>,[CLS],[SEP]等。同样，解码时也要过滤掉这些特殊token。
采样策略过于简单：贪心搜索（总是选概率最大的）容易导致重复和枯燥的文本。实现温度采样（Temperature Sampling）和Top-p采样，能极大改善生成文本的多样性和创造性。
模型本身能力有限：你使用的可能是一个过于精简或训练不足的模型。尝试换一个公认能力更强的微型模型进行测试。

6.5 部署后资源加载问题

问题：本地开发一切正常，但部署到服务器后，模型或wasm文件加载失败（404错误）。排查：

路径问题（最常见）：生产构建后，资源文件的路径可能发生变化。在Vite中，使用new URL('./model.onnx', import.meta.url).href来获取资源的绝对URL，这在不同环境下都更可靠。
服务器MIME类型：确保你的服务器为.onnx和.wasm文件配置了正确的MIME类型（分别是application/octet-stream和application/wasm）。否则浏览器可能拒绝加载。
跨域问题（CORS）：如果模型文件存放在另一个域名下，需要配置CORS头（Access-Control-Allow-Origin: *）。

7. 进阶方向与生态展望

走通整个流程后，你可以在此基础上进行更多探索：

集成更成熟的推理引擎：直接使用onnxruntime-web是相对底层的。可以关注像Transformers.js这样的项目，它正在积极集成ONNX Runtime和WebGPU后端，旨在提供类似Hugging Facetransformers库的易用API，省去手动处理分词、模型流水线等繁琐工作。
探索WebLLM等封装方案：MLC社区推出的WebLLM项目是一个更高层次的解决方案。它基于Apache TVM，将LLM编译为WebGPU可执行的格式，并内置了聊天模板、流式输出等高级功能。你可以将其视为一个“开箱即用”的运行时，你的React应用只需通过RPC与之通信。
构建复杂AI应用：将本地LLM作为智能内核，结合浏览器的其他能力（如文件系统访问API、IndexedDB、WebRTC），可以构建出真正强大的离线AI应用。例如：
- 本地文档分析助手：用户上传PDF/Word，应用在本地提取文本，由LLM进行总结、问答。
- 私有化代码助手：在VS Code的Web版或本地IDE插件中，集成一个完全本地的代码补全和解释模型。
- 离线语言学习伙伴：一个完全离线的对话练习应用，所有语音识别（可用Web Speech API）、对话生成、语音合成均在本地完成。
模型管理与切换：设计一个模型管理器，允许用户动态加载、切换不同的本地模型（例如，一个用于聊天的小模型，一个用于代码生成的专业模型）。