@react-llm/headless

易于使用的无头 React 钩子，可在浏览器中通过 WebGPU 运行大语言模型。简单到只需调用 useLLM() 即可。

在线演示

特性：

• 支持 Vicuna 7B
• 可自定义系统提示词以及“user:”和“assistant:”的角色名称
• 提供完成选项，如 max tokens 和 stop sequences
• 数据完全保留在浏览器内。借助 WebGPU 加速。
• 钩子设计为“自带 UI”，方便开发者自由定制界面
• 对话可持久化存储在浏览器本地存储中，并提供加载和保存对话的钩子
• 模型缓存功能，提升后续加载速度

安装

npm install @react-llm/headless

本仓库包含的包

• @react-llm/model - 编译后可在浏览器中运行的大语言模型及分词器
• @react-llm/retro-ui - 为这些钩子提供的复古风格 UI
• @react-llm/extension - 使用这些钩子的 Chrome 扩展程序
• @react-llm/headless - 用于在浏览器中运行大语言模型的无头 React 钩子

useLLM API

类型

// 模型初始化
init: () => void;

// 模型生成
send: (msg: string, maxTokens: number, stopSequences: string[]) => void;
onMessage: (msg: GenerateTextResponse) => void;
setOnMessage: (cb: (msg: GenerateTextResponse) => void) => void;

// 模型状态
loadingStatus: InitProgressReport;
isGenerating: boolean;
gpuDevice: GPUDeviceInfo;

// 模型配置
userRoleName: string;
setUserRoleName: (roleName: string) => void;
assistantRoleName: string;
setAssistantRoleName: (roleName: string) => void;

// 对话管理
conversation: Conversation | undefined;
allConversations: Conversation[] | undefined;
createConversation: (title?: string, prompt?: string) => void;
setConversationId: (conversationId: string) => void;
deleteConversation: (conversationId: string) => void;
deleteAllConversations: () => void;
deleteMessages: () => void;
setConversationTitle: (conversationId: string, title: string) => void;

钩子

import useLLM from '@react-llm/headless';

const MyComponent = () => {
  const {
    conversation,
    allConversations,
    loadingStatus,
    isGenerating,
    createConversation,
    setConversationId,
    deleteConversation,
    deleteAllConversations,
    deleteMessages,
    setConversationTitle,
    onMessage,
    setOnMessage,
    userRoleName,
    setUserRoleName,
    assistantRoleName,
    setAssistantRoleName,
    gpuDevice,
    send,
    init,
  } = useLLM();

  // 组件逻辑...

  return null;
};

Provider

import { ModelProvider } from "@react-llm/headless";

export default function Home() {
  return (
    <ModelProvider
      config={{
        kvConfig: {
          numLayers: 64,
          shape: [32, 32, 128],
          dtype: 'float32',
        },
        wasmUrl: 'https://your-custom-url.com/model.wasm',
        cacheUrl: 'https://your-custom-url.com/cache/',
        tokenizerUrl: 'https://your-custom-url.com/tokenizer.model',
        sentencePieceJsUrl: 'https://your-custom-url.com/sentencepiece.js',
        tvmRuntimeJsUrl: 'https://your-custom-url.com/tvmjs_runtime.wasi.js',
        maxWindowSize: 2048,
        persistToLocalStorage: true,
      }}
    >
      <Chat />
    </ModelProvider>
  );
}

包

• @react-llm/headless - 用于在浏览器中运行大语言模型的无头 React 钩子
• @react-llm/retro-ui - 为这些钩子提供的复古风格 UI

工作原理？

该库是一组 React 钩子，提供了一个简单的接口来在浏览器中运行大语言模型。它使用 Vicuna 13B。

• SentencePiece 分词器（通过 Emscripten 编译为浏览器版本）
• Vicuna 7B（转换为 Apache TVM 格式）
• Apache TVM 和 MLC Relax（通过 Emscripten 编译为浏览器版本）
• 使用主线程外的 WebWorker 来运行模型（随库一起打包）

模型、分词器和 TVM 运行时从 CDN（Hugging Face）加载。模型会被缓存在浏览器存储中，以便下次更快地加载。

示例

完整演示代码请参见 packages/retro-ui。以下是一个简单的使用示例。克隆仓库后，运行以下命令即可启动：

cd packages/retro-ui
pnpm install
pnpm dev

许可证

MIT

packages/headless/worker/lib/tvm 下的代码采用 Apache 2.0 许可证。

react-llm 快速上手指南

react-llm 是一个基于 React Hooks 的无头（Headless）库，允许你在浏览器中直接通过 WebGPU 运行大型语言模型（如 Vicuna 7B）。所有数据均在本地处理，无需离开浏览器。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：支持 WebGPU 的现代操作系统（Windows 10/11, macOS, Linux）。
• 浏览器：必须使用支持 WebGPU 的浏览器版本（推荐最新版的 Chrome 或 Edge）。
  • 注意：如果浏览器未默认开启 WebGPU，可能需要在 chrome://flags 中手动启用 "Unsafe WebGPU"。
• Node.js：建议安装 Node.js 16+ 版本。
• 硬件：拥有一定显存的 GPU 以获得最佳推理速度（模型会在本地缓存以加速后续加载）。

安装步骤

使用 npm 或 pnpm 安装核心包 @react-llm/headless：

npm install @react-llm/headless

或者使用 pnpm：

pnpm add @react-llm/headless

提示：目前官方资源托管于 HuggingFace CDN。若在国内网络环境下加载模型文件（WASM、Tokenizer 等）较慢，建议在 ModelProvider 配置中将 wasmUrl、cacheUrl 等地址替换为你自己的国内对象存储（如阿里云 OSS、腾讯云 COS）或加速镜像地址。

基本使用

1. 配置 Provider

首先，在你的应用根组件中包裹 ModelProvider，并配置模型资源的加载地址。

import { ModelProvider } from "@react-llm/headless";

export default function Home() {
  return (
    <ModelProvider
      config={{
        // 内存配置 (根据模型大小调整)
        kvConfig: {
          numLayers: 64,
          shape: [32, 32, 128],
          dtype: 'float32',
        },
        // 模型资源 URL (建议替换为国内加速地址)
        wasmUrl: 'https://your-custom-url.com/model.wasm',
        cacheUrl: 'https://your-custom-url.com/cache/',
        tokenizerUrl: 'https://your-custom-url.com/tokenizer.model',
        sentencePieceJsUrl: 'https://your-custom-url.com/sentencepiece.js',
        tvmRuntimeJsUrl: 'https://your-custom-url.com/tvmjs_runtime.wasi.js',
        
        maxWindowSize: 2048,
        persistToLocalStorage: true, // 启用本地存储以保存对话历史
      }}
    >
      <Chat />
    </ModelProvider>
  );
}

2. 使用 Hooks 进行交互

在子组件中引入 useLLM Hook，即可获取模型控制、状态管理和对话处理能力。

import useLLM from '@react-llm/headless';
import { useEffect, useState } from 'react';

const Chat = () => {
  const {
    init,
    send,
    onMessage,
    setOnMessage,
    loadingStatus,
    isGenerating,
    conversation,
    createConversation,
    userRoleName,
    setUserRoleName,
    assistantRoleName,
    setAssistantRoleName,
  } = useLLM();

  const [input, setInput] = useState('');
  const [response, setResponse] = useState('');

  // 初始化模型
  useEffect(() => {
    init();
    
    // 设置接收消息的回调
    setOnMessage((msg) => {
      // msg 包含生成的文本片段，可在此更新 UI
      setResponse(prev => prev + msg.text); 
    });

    // 可选：自定义角色名称
    setUserRoleName('user:');
    setAssistantRoleName('assistant:');
    
    // 创建新会话
    if (!conversation) {
      createConversation('新对话');
    }
  }, [init, conversation]);

  const handleSend = () => {
    if (!input.trim()) return;
    setResponse(''); // 清空上次回复
    // 发送消息：内容，最大 token 数，停止序列
    send(input, 512, ['\n']); 
    setInput('');
  };

  if (loadingStatus?.progress !== undefined && loadingStatus.progress < 1) {
    return <div>模型加载中... {Math.round(loadingStatus.progress * 100)}%</div>;
  }

  return (
    <div>
      <div style={{ minHeight: '100px', border: '1px solid #ccc', padding: '10px' }}>
        {response || (isGenerating ? '生成中...' : '等待输入...')}
      </div>
      <input 
        value={input} 
        onChange={(e) => setInput(e.target.value)} 
        placeholder="输入消息..."
        disabled={isGenerating}
      />
      <button onClick={handleSend} disabled={isGenerating}>发送</button>
    </div>
  );
};

export default Chat;

核心功能说明

• init(): 触发模型、Tokenizer 和 TVM 运行时的加载。
• send(msg, maxTokens, stopSequences): 发送用户消息并触发推理。
• onMessage / setOnMessage: 监听流式输出的文本片段。
• Conversation Management: 提供 createConversation, deleteConversation 等方法，自动利用浏览器本地存储持久化对话历史。
• Bring Your Own UI: 该库不包含 UI 组件，你需要根据 loadingStatus, isGenerating, conversation 等状态自行构建界面。