跪拜 Guibai
← Back to the summary

A WebGPU-Powered DeepSeek-R1 Demo Runs a 1.5B Model Entirely in the Browser

Recently, I've been researching how to run large models in the browser and plan to build a lightweight inference demo page for DeepSeek-R1. The entire project uses Vite as the build tool, paired with React and TypeScript for page logic, Tailwind CSS for all styling, and WebGPU for local model computation. The setup process involves many foundational front-end concepts combined with AI. Using this hands-on project, I'll explain the underlying principles and practical steps clearly. Whether you're new to React or a developer looking to get into front-end AI, you should find something useful.

1. Initializing a Project from Scratch and Understanding Vite's Basic Usage Logic

To start development, the first step is to initialize the project. Open the terminal and enter the code:

npm init vite

After execution, the console will display a list of options. Select React for the framework and TypeScript for the language template. Once selected, enter the project folder, run npm install to install the base dependencies, and after the installation is complete, run npm run dev to start the local development server.

Here's the advantage of Vite. Many developers accustomed to Webpack will immediately notice the difference. Webpack bundles all files at startup, and as the project grows, the startup speed becomes noticeably slower. Vite leverages the browser's native ES Module capabilities and does not perform a full bundle in the development environment. Only the files being accessed are compiled in real-time, resulting in extremely fast hot module replacement response times, saving a lot of waiting time during daily development.

2. Installing and Configuring Tailwind CSS, Understanding the Principles of Atomic CSS

The drawbacks of hand-writing native CSS are magnified in complex pages: repeatedly writing margin, size, and typography styles leads to severe file redundancy, and you have to switch back and forth between CSS and business component files when modifying styles. Tailwind, as an atomic CSS framework, solves these pain points. Let's set up the environment first.

  1. Install dependencies

Run the installation command in the project root directory to create the project:

npm install tailwindcss @tailwindcss/vite

Open the index.css file and replace its contents with:

@import "tailwindcss";

Find the vite.config.ts file in the project and replace its contents with:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),
  ],
})

After configuration, you can directly concatenate various styles in the className attribute of component tags, without needing to create separate style files and write selector rules.

Many beginners wonder why HTML tags use class, but in React JSX, it must be replaced with className. The underlying logic here is critical. class is a reserved keyword in JavaScript, specifically used for declaring classes. When the compiler parses JSX, writing class directly will be flagged as a syntax error. React specifically designed the className attribute to pass style class names, avoiding keyword conflicts. This is a strict rule of JSX.

Let's talk about Tailwind's operating mechanism. It's a completely different approach from traditional CSS. Traditional development requires manually writing selectors and style key-value pairs, with a lot of repetitive code that is hard to maintain. Tailwind relies on a Vite plugin to scan the entire project, collect the atomic classes actually used on the page, and inject only the corresponding styles into the final code. Unused classes are directly discarded, adding no extra bundle size. During development, we just combine semantic class names, like flex for flexible layout, text-4xl for font size, and mb-1 for margin-bottom. One line of code completes the layout and styling, greatly improving development efficiency. Mainstream front-end UI component libraries today, such as Vibe UI and ShadCN UI, are built on top of Tailwind. Mastering this approach makes it much easier to integrate with various component libraries.

3. React Functional Components and Hooks, Understanding the Core Logic of Reactivity

The page logic for this project is entirely written in App.tsx, using React functional components with TypeScript static type constraints. The two basic Hooks, useState and useEffect, run through the entire page logic, which is also the core knowledge of React development.

useState: Implementing Data-Driven Views

Hooks uniformly start with use. The role of useState is to define reactive data. The standard syntax is [dataVariable, updateFunction] = useState(initialValue). There is a common pitfall here: directly modifying the variable itself will not update the page view. Only by calling the corresponding update function will React perceive the data change and re-render the page. This is what is often called data-driven views in front-end development.

Combined with the business scenario of WebGPU model loading, I defined multiple sets of state variables: page running status status, error message error, loading text loadingMessage, and model download progress progressItems. Different states correspond to different page display effects, similar to a Sichuan opera face-changing act, where one page switches between multiple views based on the data, without needing to write duplicate DOM structures.

import { useState, useEffect } from 'react';

function App() {
  // Page running status
  const [status, setStatus] = useState(null);
  // Error message state
  const [error, setError] = useState(null);
  // Loading prompt text
  const [loadingMessage, setLoadingMessage] = useState("");
  // Model download progress object
  const [progressItems, setProgressItems] = useState([{
    file: 'model.onnx',
    progress: 0,
    total: 34353543453
  }]);
  // Check if the browser supports WebGPU
  const IS_WEBGPU_AVALABLE = !!navigator.gpu;

The code !!navigator.gpu uses a double negation operation. Here's the explanation: some older browsers do not have the navigator.gpu API, so its value is undefined. A single negation would result in the boolean value true, but a double negation stably outputs the standard boolean value true or false, avoiding subsequent TypeScript type-checking errors.

useEffect: Handling Component Side Effect Logic

In front-end development, side effects refer to operations unrelated to page rendering, such as printing logs, API requests, timers, and resource initialization. This logic should be placed inside useEffect for execution.

The function's second parameter is the dependency array. When the array is empty, the internal code executes only once after the component is initially rendered and mounted, which is very suitable for page initialization operations. Whenever any reactive data within the component updates, the entire App function will re-execute. The print statement console.log('Component function executing') at the top of the function will trigger repeatedly, allowing us to observe the timing of component re-renders using this log.

useEffect(() => {
  console.log('Component has been mounted');
}, [])

JSX Syntax: The Core Carrier for Describing Pages in React

The content wrapped in the return statement of a functional component is JSX syntax. It allows us to write XML-like structured tags directly within JavaScript code, which are automatically converted into native DOM operations during compilation. This is one of React's most core features.

return (
  IS_WEBGPU_AVALABLE?(<div className="flex flex-col h-screen mx-auto items-center justify-end text-gray-800 bg-white">
    <div className="h-full overflow-auto  flex justify-center items-center flex-col relative">
      <div className="flex flex-col items-center mb-1 max-w-[400px] text-center">
        <h1 className="text-4xl font-bold mb-1">DeepSeek-R1 WebGPU</h1>
        <h2 className="font-semibold">
          A next generation reasoning model that runs locally in
          your browser with WebGPU acceleration.
        </h2>
      </div>
      <div className="flex flex-col items-center px-4">
        <p className="max-w-[510px] mb-4">
          <br />
          You are about to load
          <a
            href="https://huggingface.co/onnx-community/DeepSeek-R1-Distill-Qwen-1.5B-ONNX"
            target="_blank"
            rel="noreferrer"
            className="font-medium underline"
          >
            DeepSeek-R1-Distill-Qwen-1.5B
          </a>
          , a 1.5B parameter reasoning LLM optimized for in-browser
            inference. Everything runs entirely in your browser with
          <a
            href="https://huggingface.co/docs/transformers.js"
            target="_blank"
            rel="noreferrer"
            className="underline"
          >
            🤗&nbsp;Transformers.js
          </a>{" "}
          and ONNX Runtime Web, meaning no data is sent to a server. Once
          loaded, it can even be used offline. The source code for the demo
          is available on{" "}
        </p>
        {
          error && (
            <div className="text-red-500 text-center mb-2">
              <p className="mb-1">
                Unable to load model due to the following error:
              </p>
              <p className="text-sm">{error}</p>
            </div>
          )
        }
      </div>
    </div>
  </div>):(
    <div>Your browser does not support WebGPU yet</div>
  )
)

We can embed ternary expressions in JSX for conditional rendering, displaying different pages based on WebGPU support. We can also embed JS expressions using the {variable} form, such as showing an error prompt module when error has a value. The page layout is entirely implemented using Tailwind atomic classes: flex controls flexible layout, h-screen makes the container fill the screen height, and text-red-500 sets the text color, all without writing a separate stylesheet.

Finally, export the component with export default App so that the project entry file can import and render this page component, completing the full component chain.

4. The Difference Between WebGPU On-Device Models and Cloud APIs

The biggest highlight of this project is running a large model directly in the browser locally, bypassing cloud APIs. Here's a comparison of the two mainstream AI invocation methods to help understand the application scenarios.

Currently, the vast majority of AI conversation tools call remote APIs from vendors. The user's input conversation content is fully uploaded to a remote server for computation. On one hand, this poses a risk of privacy leakage for the conversation data; on the other hand, high-frequency calls incur additional costs, and the service is completely unusable without an internet connection.

This project relies on WebGPU paired with Transformers.js to run the 1.5 billion parameter distilled version of the DeepSeek-R1 model locally in the browser. After the initial model file download, all inference computations are executed using the local GPU's computing power. Conversation data is not transmitted externally, and it works normally in an offline environment. An ordinary home computer can run it smoothly without a high-end graphics card.

A similar local deployment tool is Ollama, but Ollama requires installing a separate client application on the device, which has a higher barrier to entry. The WebGPU solution only requires a modern browser; it works by simply opening a web page, lowering the barrier for distribution and use. On a resume, this project stands out from typical backend management systems or static display pages, covering multiple areas like front-end engineering, TS type checking, hardware interface adaptation, and front-end AI inference, making it much more competitive.

Solution Data Privacy Network Requirement Barrier to Entry
Cloud API Conversations uploaded to server Requires constant internet connection Just need to call the interface
WebGPU Local Inference Data stays on the local machine Offline capable after initial model download Requires a modern browser with WebGPU support

5. Thoughts on Tech Stack Selection, Clarifying Suitable Scenarios for Different Solutions

Vite + React + TypeScript

React has the most mature ecosystem in front-end AI-related projects. Inference tools like Transformers.js and ONNX Runtime Web are optimized for React first. TypeScript adds static type checking, intercepting type errors during the development phase. Enterprise collaboration projects typically pair it with ESLint to unify code standards. Vite optimizes the development experience, significantly reducing startup and hot module replacement times.

Tailwind CSS

The atomic CSS framework drastically reduces the workload of style development and is suitable for the vast majority of business pages. Mainstream UI libraries on the market are basically developed based on it. Once learned, various component templates can be quickly reused.

WebGPU

This is a cutting-edge front-end technology that opens a communication channel between the browser and the device's GPU, transplanting model inference, which was previously only possible in backend Python environments, to the front end. It's a great entry point for front-end developers to break into the AI field.

Final Words

This article only set up the basic project page, completing the environment check and project introduction module. In the future, features like a conversation input box, real-time download progress, and inference parameter adjustment can be expanded. The entire tech stack is highly versatile and can be reused whether for learning and practice or for developing front-end AI tools.

The front-end industry is now increasingly intertwined with AI. Simply mastering page building is no longer enough to create a gap. Cross-disciplinary knowledge points like WebGPU local inference are worth spending more time exploring. It can solidify front-end fundamentals while also broadening your technical horizons.