AI助手-WebLLM和本地LLM聊天

一个生产就绪的AI助手，完全在浏览器中使用WebLLM（WebGPU）运行，Ollama作为可选后端。具有智能模型管理、硬件感知建议、HuggingFace集成、多提供商支持和TOON格式，可优化令牌使用。

特性

浏览器优先人工智能（WebLLM）

无需服务器：使用WebGPU直接在浏览器中运行LLM
隐私第一：所有推理都在本地进行，没有数据离开您的设备
多种模型：Qwen2.5，Llama 3.2，Phi 3.5，Gemma 2，SmolLM2
模型缓存：下载的模型将保留在浏览器存储中
一键加载：使用简单按钮加载、卸载和清除模型

Ollama集成（可选）

本地服务器：使用Olama进行更大的模型和更快的推理
智能检测：硬件感知模型建议
自动下载：从Ollama库中一键下载模型
网址搜索：从Ollama Hub查找并下载任何型号
40+型号目录：具有详细元数据的综合模型目录

拥抱面部整合

动态目录：从HuggingFace API获取50多种型号
按URL搜索模型：粘贴任何HuggingFace模型URL进行搜索
兼容性检查：自动硬件兼容性评估
Ollama地图：检测HF型号是否以Ollama格式提供
缓存结果：1小时TTL缓存以提高性能

在线法学硕士提供者

OpenRouter：访问300多种型号（GPT-4、克劳德、米斯特拉尔等）
开放人工智能：ChatGPT API集成
Anthropic：Claude API集成
API密钥管理：使用base64混淆保护本地存储

令牌优化（TOON）

代币减少约40%：使用TOON格式压缩对话历史记录
切换开/关：一键启用/禁用
自动：与WebLLM聊天透明地工作
持久：跨会话保存首选项

多回退聊天系统

强大的聊天功能：三层回退确保即使有上下文问题也能得到响应

1. 完整的上下文 /api/chat 1. 仅限最新消息 /api/chat 1. 扁平化提示 /api/generate

环境消毒：自动处理复杂的消息格式
错误恢复：使用面包屑进行详细记录

硬件检测

自动检测Mac硬件：芯片类型（M1/M2/M3/Intel）、RAM、CPU内核
智能推荐：基于系统规格的最佳模型
性能估算：每个模型的速度预测（令牌/秒）
所有兼容型号：列出可以使用性能指标运行的每个模型
后备安全：默认为 llama3.2:1b 如果检测失败

会话管理

历史：SQLite支持的对话存储
上下文窗口：LLM上下文的最后10条消息
意图检测：基于关键字的工具检测（Gmail、日历、Salesforce）
多用户框架：数据库支持多个用户（MVP使用单用户）

一键启动

单个文件：双击 🚀 Launch AI Assistant.command
自动设置：安装依赖项、启动服务、打开浏览器
WebGPU已启用：推出带有最佳WebGPU标志的Chrome
交叉平台的：适用于macOS和Linux

快速开始

选项1：一键启动（推荐）

双击 🚀 Launch AI Assistant.command
等待安装完成
启用WebGPU后，浏览器会自动打开
开始和WebLLM聊天（不需要服务器！）

选项2：手动设置

# Navigate to project
cd ai-assistant

# Backend setup
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Start server
python -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# Open in browser
open http://localhost:8000

选项3:仅WebLLM（无服务器）

只需打开 frontend-v2/index.html 在支持WebGPU的Chrome浏览器中：

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
    --enable-unsafe-webgpu \
    --enable-features=Vulkan,UseSkiaRenderer \
    --ignore-gpu-blocklist \
    "file:///path/to/ai-assistant/frontend-v2/index.html"

需求

适用于WebLLM（基于浏览器）

铬113+ 或支持WebGPU的Edge 113+
8GB+内存 推荐
图形处理器 支持WebGPU（大多数现代GPU）

Ollama（可选）

macOS 或Linux
Python 3.8+
奥拉玛 已安装(brew install ollama)

使用指南

切换提供商

使用标题中的按钮在WebLLM和Ollama之间切换：

Webllm：基于浏览器的推理，不需要服务器
奥拉玛：本地服务器，提供更大型号

管理模型

点击模型按钮用于：

查看下载的模型
下载新型号
加载/卸载模型
清除模型缓存
检查型号尺寸和性能等级
通过Ollama或HuggingFace网址搜索

使用TOON格式

点击卡通启用令牌优化的按钮（闪电）：

按钮激活时变为绿色
将对话历史压缩约40%
非常适合长时间对话
随时关闭标准格式

WebGPU故障排除

如果WebLLM加载失败：

启用硬件加速:

- 铬→ 设置→ 搜索“硬件” - 启用“可用时使用图形加速” - 完全重新启动Chrome

检查WebGPU支持:

- 访问 chrome://gpu - 寻找“WebGPU：硬件加速”

使用启动脚本:

- 这 🚀 Launch AI Assistant.command 使用正确的标志启动Chrome

可用模型

WebLLM模型（浏览器）

型号	尺寸	最适合
Qwen2.5-0.5B	~30MB	快速响应，基本任务
Qwen2.5-1.5B	~900MB	速度/质量平衡良好
Llama-3.2-1B	~700MB	一般对话
Llama-3.2-3B	~2GB	更高质量的响应
Phi-3.5-mini	~2.4GB	代码和推理
SmolLM2-1.7B	~ 1GB	高效、快速
Gemma-2-2B	~1.5GB	谷歌的高效模式

Ollama模型（服务器）

型号	尺寸	参数	性能	质量
llama3.2:1b	1.3GB	1b	最快	基本
骆驼3.2:3b	2.0GB	3b	快速	中等
phi3：迷你	2.3GB	3.8B	快速	中等
米斯特拉尔：7b	4.1GB	7b	快速	高
骆驼3.1:8b	4.7GB	8b	良好	高
gemma2:9b	5.5GB	9b	良好	高
qwen2:7b	4.4GB	7b	良好	高
codellama:7b	3.8GB	7b	良好	高
deepseek-r1:7b	4.7GB	7b	良好	高
混音：8x7b	26.0GB	8x7b	慢	高

完整目录包括30多种型号 包括Llama 3.1/3.2、Mistral、Phi 3、Gemma 2、Qwen 2、DeepSeek、CodeLlama等。

项目结构

ai-assistant/
├── frontend-v2/
│   └── index.html          # Main UI (WebLLM + Ollama)
├── frontend/
│   └── src/                 # Modular JS components
│       ├── webllm-integration.js
│       ├── provider-toggle.js
│       ├── api-key-manager.js
│       ├── online-llm-client.js
│       └── settings-panel.js
├── backend/
│   ├── main.py              # FastAPI server
│   ├── database.py          # SQLAlchemy ORM & models
│   ├── conversation_manager.py  # Chat history & intent detection
│   ├── hardware_detector.py # Mac hardware detection
│   ├── ollama_integration.py    # Ollama model catalog
│   ├── huggingface_integration.py # HuggingFace API
│   ├── shared_utils.py      # Common utilities
│   ├── logger.py            # Workflow logging
│   └── requirements.txt     # Python dependencies
├── config/
│   └── provider-config.json # Provider configuration
├── tests/
│   └── model_management/    # API tests
├── 🚀 Launch AI Assistant.command  # One-click launcher
├── run.command              # Alternative launcher
└── README.md                # This file

API终点

使用Ollama后端运行时：

健康与系统信息

端点	方法	描述
`/health`	GET	使用硬件信息进行系统健康检查
`/hardware`	GET	详细的硬件信息和兼容型号
`/api`	获取	API信息
`/`	GET	服务前端

模型管理

端点	方法	描述
`/models`	GET	列出下载的Olama车型
`/models/available`	获取	获取所有模特（Ollama+HuggingFace）
`/models/downloaded`	GET	获取本地安装的模型
`/models/download`	POST	从Ollama下载模型
`/models/download-from-hf`	POST	从HuggingFace URL下载
`/models/search-hf`	POST	搜索HuggingFace以获取模特信息
`/models/search-url`	POST	统一搜索（Ollama或HF URL）
`/models/{name}`	DELETE	删除/卸载模型

聊天和对话

端点	方法	描述
`/chat`	POST	使用多重回退发送消息
`/conversations/new`	POST	创建新对话
`/conversations/{id}`	GET	获取对话历史记录
`/conversations/{id}`	DELETE	删除对话
`/conversations`	GET	列出所有对话（限制：20）

技术细节

WebLLM架构

用途 @mlc-ai/web-llm 用于浏览器推理
WebGPU用于GPU加速
用于模型存储的IndexedDB/Cache API
用于非阻塞推理的Web Workers

后端架构

FastAPI 0.109.0：异步web框架
SQLAlchemy 2.0.25：使用SQLite/PPostgreSQL的ORM
httpx 0.26.0：异步HTTP客户端
Pydantic 2.5.3：数据验证

TOON格式

基于卡通格式/卡通:

表格表示法减少了JSON开销
标题中的字段名，行中的数据
对话令牌减少约40%
自动编码/解码

深色模式

默认情况下为全暗主题
优化以减少眼睛疲劳
所有组件的样式一致

数据库模式

后端使用SQLite和下表：

用户：多用户支持（id、电子邮件、created_at）
对话：JSON消息的聊天记录
工具连接：OAuth连接（Gmail、日历、Salesforce）
工作流：用户定义的自动化工作流
工作流执行：工作流运行历史和日志

配置

环境变量（.env）

# Ollama
OLLAMA_BASE_URL=http://localhost:11434
DEFAULT_LOCAL_MODEL=llama3.1

# Database
DATABASE_URL=sqlite:///./ai_assistant.db

# Server
HOST=0.0.0.0
PORT=8000
DEBUG=true

# OAuth (Future)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
SALESFORCE_CLIENT_ID=
SALESFORCE_CLIENT_SECRET=

# Security
SECRET_KEY=

提供者配置（Provider-config.json）

{
  "default_provider": "webllm",
  "providers": {
    "webllm": {
      "enabled": true,
      "default_model": "Llama-3.2-1B-Instruct-q4f16_1-MLC",
      "features": {
        "streaming": true,
        "offline_support": true,
        "privacy_focused": true
      }
    },
    "ollama": {
      "enabled": true,
      "base_url": "http://localhost:11434",
      "default_model": "llama3.2:1b",
      "features": {
        "streaming": true,
        "large_models": true,
        "higher_quality": true
      }
    }
  },
  "fallback_strategy": {
    "enabled": true,
    "order": ["webllm", "ollama"]
  },
  "toon_optimization": {
    "enabled": false,
    "auto_enable_threshold": 500
  }
}

本地存储密钥

ai-assistant-provider -当前提供者（webllm/ollama）
ai-assistant-toon -TOON启用状态
ai-assistant-api-keys -加密的API密钥
webllm-cached-{model} -模型缓存状态

故障排除

WebLLM未加载

检查Chrome版本（需要113+）
在Chrome设置中启用硬件加速
验证webgpu和 chrome://gpu
使用启动脚本获取正确的标志

Ollama连接失败

# Check if Ollama is running
curl http://localhost:11434/api/tags

# Start Ollama
ollama serve

模型下载卡住

# Check Ollama logs
tail -f ~/.ollama/logs/server.log

# Restart Ollama
pkill ollama && ollama serve

404型号未找到

模型自动从列表中删除
从可用型号重新下载
检查Ollama储存： ~/.ollama/models

聊天返回空响应

多重回退系统将尝试三种不同的方法。如果全部失败：

检查Ollama是否正在运行且反应灵敏
验证模型是否已完全下载
检查服务器日志以了解特定错误

性能提示

使用TOON 适合长时间交谈
从较小的型号开始 （0.5B-1B）用于测试
启用GPU 在Chrome设置中
关闭其他GPU应用程序 使用WebLLM时
使用Olama 对于参数>3B的模型
Apple Silicon用户 速度提高2-3倍

性能估算

RAM	苹果硅	英特尔
8GB	1-3B型号	1-2B型号
16GB	1-8B型号	1-5B型号
32GB	1-13B型号	1-8B型号
64GB+	所有型号	大多数型号

安全说明

API密钥：使用base64混淆（非加密）存储在localStorage中
跨域资源共享：允许MVP-限制生产
认证：单用户MVP-OAuth框架就绪
输入消毒：在LLM之前，所有聊天上下文都已净化
无服务器机密：后端没有敏感数据

即将推出的功能

基于数据库模式和代码结构：

MCP工具集成：Gmail、日历、Salesforce
OAuth身份验证：谷歌、Salesforce
工作流程自动化：创建和安排工作流
多用户支持：激活现有框架
高级意图检测：基于机器学习（目前基于关键字）
流媒体响应：实时令牌流
代币分析：使用情况跟踪和优化

贡献

分叉存储库
创建要素分支
进行更改
运行测试： cd tests && python -m pytest
提交拉取请求

许可证

MIT许可证-可自由用于个人或商业项目。

______________________________________________________________________

内置于：WebLLM、FastAPI、Ollama、HuggingFace、顺风CSS、SQLAlchemy、WebGPU

令牌优化：TOON格式，减少约40%

隐私：所有推理都在您的设备上本地运行

模型来源：Ollama Library（30+型号）+HuggingFace Hub（50+型号）

AI Assistant Public

快速接入

详细介绍