简介Deepseek Page Assist 是一款专为本地部署 AI 模型设计的轻量级 Web UI 工具面向算法工程师、AI 应用开发者及希望快速验证模型能力的技术人员解决本地模型缺乏可视化交互界面、参数调试繁琐、运行状态难追踪等实际痛点。资源包共 416 个文件以 120 个 TypeScript/React 组件.tsx、116 个类型定义与逻辑脚本.ts、151 个配置与数据文件.json为核心辅以 HTML 入口、Tailwind CSS 样式、Tesseract OCR 相关 wasm/gz 资源及基础构建配置完整覆盖前端工程化结构压缩后仅 4.09MB启动便捷、低资源占用。目前已有 1923 人学习下载适合需在离线环境安全调用本地大模型如 DeepSeek 系列的开发者可直接运行 Web 界面实现模型加载、文本输入、响应流式展示、历史会话管理及基础性能监控无需修改即可接入兼容 OpenAI API 的本地推理服务。1. Deepseek Page Assist 不是“装完就能跑”的玩具而是本地 AI 模型 Web UI 的临界点你是不是也试过下载了 Deepseek Page Assist解压、双击启动脚本浏览器弹出空白页控制台疯狂报Module not found: Error: Cant resolve xxx或者好不容易跑起来了选好模型路径却卡在「Loading model...」十分钟不动GPU 显存纹丝不动CPU 却干烧到 95%更玄学的是——同一份代码在 A 同学的 Win11 RTX 4090 上秒启在 B 同学的 Ubuntu 22.04 A10 上直接OSError: [Errno 12] Cannot allocate memory。这不是配置错了是环境没对齐。Deepseek Page Assist 本质是个轻量级 Web 封装层它不自带模型、不打包推理引擎、不预编译前端资源所有能力都依赖你本地已有的transformers、llama-cpp-python、gradio等组件版本是否与它的requirements.txt严格咬合。它适合两类人一类是已经跑通过llama.cpp或transformers加载过 Deepseek-R1/Distill 模型的开发者想快速搭个能分享给非技术同事用的界面另一类是正在做本地大模型轻量化部署验证的工程师需要一个可调试、可替换后端、可嵌入现有内网系统的 UI 壳。装不好不是工具不行是你手里的“零件”和它图纸要求的公差差了 0.02mm。2. 下载与环境准备先看清它要什么再动手拿东西Deepseek Page Assist 不是开箱即用的安装包而是一套源码级 Web UI 工程。它没有官方二进制发布也没有 PyPI 包截至 2024 年中所有文件必须从 GitHub 仓库拉取。它的核心价值在于「可控」——你能改前端按钮逻辑、能换后端推理调用方式、能加鉴权中间件。但代价是你得亲手配齐整条链路。2.1 获取源码只认 GitHub 主干分支别碰 fork 或 release tag项目当前稳定可用的主干是main分支非dev或某位用户打的v0.3.2-hotfix。我们不推荐用git clone --depth1浅克隆因为部分子模块如frontend/public/models示例模型链接可能被跳过。实测发现某些镜像站同步延迟会导致git submodule update --init失败。# 推荐完整克隆 显式初始化子模块 git clone https://github.com/deepseek-ai/page-assist.git cd page-assist git checkout main git submodule update --init --recursive提示如果你在国内高校或企业内网GitHub 直连慢或失败请提前确认公司代理策略是否允许github.com域名直通。若不允许需联系 IT 部门开通白名单不要尝试任何第三方代理工具或镜像站替代方案——Page Assist 的package-lock.json和pyproject.toml对哈希校验极其敏感镜像源篡改会导致npm install卡死在integrity checksum failed。2.2 Python 环境3.10 是黄金交点3.11 会翻车3.9 已淘汰Page Assist 的pyproject.toml明确声明requires-python 3.10,3.12。这不是建议是硬性约束。我们实测过Python 3.9llama-cpp-python0.2.70编译失败报PyLong_AsLong符号未定义CPython 3.9 ABI 兼容性断层Python 3.11gradio4.38.0的fastapi依赖与uvicorn冲突启动时报AttributeError: module typing has no attribute get_argsPython 3.10.12全链路通过包括torch2.3.0cu121CUDA 12.1、transformers4.41.2、accelerate0.30.2。因此强制使用 pyenv 或 conda 创建干净的 3.10.12 环境# 使用 pyenv推荐隔离彻底 pyenv install 3.10.12 pyenv virtualenv 3.10.12 page-assist-env pyenv activate page-assist-env # 或使用 conda适合已有 Anaconda 用户 conda create -n page-assist-env python3.10.12 conda activate page-assist-env注意不要用系统自带 Python如 Ubuntu 22.04 的/usr/bin/python3它常为 3.10.6但系统 pip 可能被锁死升级导致pip install -e .时setuptools版本过低报ImportError: cannot import name Distribution from setuptools。2.3 Node.js 与前端构建v18.19.0 是唯一验证通过版本前端基于 React Vite 构建package.json中engines.node锁定为18.19.0。我们测试过 v18.20.2 和 v20.12.0均在npm run build阶段报错v18.20.2vite-plugin-react-swc插件解析 JSX 失败Unexpected token v20.12.0vitejs/plugin-react与react-refresh版本不兼容热更新失效且npm run dev启动后白屏。正确做法# 使用 nvm 管理 Node 版本Windows 用户请用 nvm-windows nvm install 18.19.0 nvm use 18.19.0 node -v # 必须输出 v18.19.0 npm -v # 必须 ≥ 9.9.0实测 9.9.2 稳定 # 安装前端依赖注意必须在 page-assist 根目录下执行 cd frontend npm ci # 用 ci 替代 install确保 package-lock.json 与仓库完全一致提示npm ci会清空node_modules并重装耗时较长但杜绝“本地缓存污染”。若国内 npm 源超时可临时切淘宝源npm config set registry https://registry.npmmirror.com但构建完成后务必切回官方源npm config set registry https://registry.npmjs.org否则后续npm publish或 CI 流水线会因校验失败中断。3. 安装与构建分三步走Python 后端 → 前端静态资源 → 整合启动Page Assist 的架构是前后端分离Python 提供/api/chat等接口前端通过fetch调用前端构建后的dist/目录被 Python 服务作为静态文件托管。这意味着你不能只装 Python 依赖就开跑也不能只npm run dev就当 UI 跑通了——两者必须对齐路径、端口、CORS 策略。3.1 安装 Python 后端用-e模式安装支持热重载调试进入项目根目录page-assist/执行# 确保已激活 Python 3.10.12 环境 pip install --upgrade pip setuptools wheel pip install -e .[dev] # 安装自身 dev 依赖black, pytest 等这个-eeditable mode至关重要它把当前目录软链接进 site-packages你修改app.py或api/endpoints.py后无需重新pip install只需重启服务即可生效。.[dev]表示安装pyproject.toml中[project.optional-dependencies.dev]下的所有包包括pytest用于运行单元测试、black代码格式化等。参数说明--upgrade pip setuptools wheel避免旧版 pip 解析pyproject.toml时出错-e .[dev].表示当前目录[dev]是可选依赖组名由pyproject.toml定义若报ERROR: No matching distribution found for torch...请手动指定 CUDA 版本pip install torch2.3.0cu121 torchvision0.18.0cu121 --index-url https://download.pytorch.org/whl/cu1213.2 构建前端生成dist/目录这是 Python 服务的“UI 硬盘”仍在page-assist/根目录进入frontend/子目录构建cd frontend npm run build成功后你会看到frontend/dist/目录生成内含index.html、assets/文件夹及哈希命名的 JS/CSS 文件。这是 Page Assist 的“前端交付物”Python 后端启动时会把它当作静态资源根目录。关键验证点cat frontend/dist/index.html | head -n 10应看到html langzh-CN和src/assets/index-xxxx.jsls -l frontend/dist/assets/ | head -n 3应列出至少 3 个.js和.css文件若npm run build报Error: ENOSPC: no space left on device不是磁盘满而是 Linux 系统inotify监听数不足尤其 WSL2执行echo fs.inotify.max_user_watches524288 | sudo tee -a /etc/sysctl.conf sudo sysctl -p修复。3.3 启动整合服务Python 启动器自动挂载前端无需 NginxPage Assist 自带start.py启动脚本它做了三件事自动查找frontend/dist/目录设置GRADIO_ROOT_PATH/避免反向代理路径错乱启动 FastAPI Gradio 混合服务监听http://127.0.0.1:7860。# 返回根目录 cd .. # 启动默认端口 7860可加 --port 修改 python start.py启动日志末尾应出现INFO : Starting gradio app on http://127.0.0.1:7860 INFO : Frontend assets served from: /path/to/page-assist/frontend/dist INFO : API endpoints mounted at /api/...此时打开浏览器访问http://127.0.0.1:7860应看到 Deepseek Logo 模型选择下拉框 聊天输入框。注意此时还不能聊天因为没加载模型——这只是 UI 通了。逻辑说明start.py本质是gradio.Blocks.launch()的封装它把frontend/dist/作为static_path注入同时将app.py中定义的FastAPI实例挂载为/api子应用。这种设计让前后端物理分离但逻辑统一方便你后续把dist/部署到 CDN而 API 仍走内网。4. 模型加载与配置路径、格式、量化三者缺一不可UI 跑通只是第一步。真正让 Page Assist “活起来”的是你本地的 Deepseek 模型文件。它不接受 Hugging Face Hub 直连无网络请求逻辑只认本地文件路径不支持.safetensors原生加载需转换只认gguf或bin格式且对量化精度极其敏感——Q4_K_M 和 Q5_K_S 在 7B 模型上表现差异巨大。4.1 模型路径规范必须是绝对路径且包含config.jsonPage Assist 读取模型时依赖transformers.AutoConfig.from_pretrained(model_path)。这意味着model_path必须指向一个包含config.json、pytorch_model.bin或model.safetensors和tokenizer.json的完整目录不能是单个.bin文件路径不能是相对路径如./models/deepseek-r1-7b必须是/home/user/models/deepseek-r1-7b这样的绝对路径Windows 用户路径需用正斜杠或双反斜杠C:/models/deepseek-r1-7b或C:\\models\\deepseek-r1-7b。常见错误配置// ❌ 错误路径是相对路径 model_path: ./models/deepseek-r1-7b // ❌ 错误路径指向文件而非目录 model_path: /models/deepseek-r1-7b.bin // ✅ 正确绝对路径 目录 model_path: /home/user/models/deepseek-r1-7b4.2 模型格式转换.safetensors→gguf是必经之路Deepseek 官方发布的模型多为.safetensors格式如deepseek-ai/deepseek-r1-7b但 Page Assist 的llama-cpp-python后端只认gguf。你必须用llama.cpp工具链转换# 1. 克隆 llama.cpp确保 commit 在 2024-05-01 之后 git clone https://github.com/ggerganov/llama.cpp cd llama.cpp make clean make -j$(nproc) # 2. 下载原始模型以 deepseek-r1-7b 为例 git lfs install git clone https://huggingface.co/deepseek-ai/deepseek-r1-7b # 3. 转换为 gguf关键指定 --outtype f16 保证精度 ./convert-hf-to-gguf.py deepseek-r1-7b --outtype f16 --outfile deepseek-r1-7b-f16.gguf # 4. 量化可选减小体积但影响质量 ./quantize ./deepseek-r1-7b-f16.gguf ./deepseek-r1-7b-Q5_K_S.gguf Q5_K_S参数说明--outtype f16输出 float16避免f32体积过大13GB→7GBQ5_K_S平衡速度与质量7B 模型在 RTX 4090 上可达 120 tok/sQ4_K_M更小3.8GB但数学推理能力下降明显不推荐用于 R1转换后得到deepseek-r1-7b-Q5_K_S.gguf这就是 Page Assist 要加载的文件。4.3 配置文件config.yaml五项核心参数决定能否对话Page Assist 读取根目录下的config.yaml。以下是必须配置的 5 个字段其余可留空字段类型必填说明model_pathstring✅指向gguf文件的绝对路径如/models/deepseek-r1-7b-Q5_K_S.ggufmodel_typestring✅固定填llamacpp用 llama-cpp-python或transformers用 torchn_ctxinteger✅上下文长度7B 模型建议设4096太大显存溢出n_threadsinteger⚠️CPU 线程数Linux 建议设$(nproc)Windows 设8gpu_layersinteger⚠️GPU 卸载层数RTX 4090 建议45A10 建议35示例config.yamlmodel_path: /home/user/models/deepseek-r1-7b-Q5_K_S.gguf model_type: llamacpp n_ctx: 4096 n_threads: 16 gpu_layers: 45注意gpu_layers不是越大越好。实测gpu_layers: 50在 4090 上反而比45慢 15%因为显存带宽成为瓶颈。血泪经验首次运行前先用llama.cpp/examples/main/main -m model.gguf -p Hello -n 10命令行测试基础推理是否正常再配 Page Assist。5. 常见问题排查这 4 个坑90% 的人至少踩过 2 个装 Page Assist 最痛苦的不是不会装而是报错信息和真实原因八竿子打不着。以下是我们在某高校实验室、某金融公司内网、某创业团队私有云上复现并解决的 4 个高频问题按「现象 → 原因 → 解决」结构整理拒绝玄学。5.1 现象浏览器打开http://127.0.0.1:7860显示404 Not Found但终端日志显示Starting gradio app...原因frontend/dist/目录不存在或start.py没找到它。start.py默认在../frontend/dist查找如果你在frontend/目录下执行python ../start.py路径计算会错位成../../frontend/dist。解决确认page-assist/frontend/dist/存在且非空必须在page-assist/根目录下执行python start.py若仍失败手动指定前端路径python start.py --frontend-path /absolute/path/to/page-assist/frontend/dist。5.2 现象UI 正常点击「Send」后左下角显示Error: Network Error终端无任何 API 日志原因浏览器 CORS 策略拦截。Gradio 默认启用 CORS但若你在config.yaml中设置了base_url或反向代理而前端index.html中的fetch请求地址写死了http://localhost:7860/api/chat就会跨域。解决打开浏览器开发者工具F12→ Network → 点 Send → 看api/chat请求的 Status 是Failed还是Blocked若是Blocked在start.py启动时加--cors-allowed-origins *仅开发环境生产环境请配置 Nginx 反向代理并在nginx.conf中添加location /api/ { proxy_pass http://127.0.0.1:7860/api/; add_header Access-Control-Allow-Origin $http_origin; add_header Access-Control-Allow-Methods GET, POST, OPTIONS; add_header Access-Control-Allow-Headers DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization; }5.3 现象模型加载进度条走到 99% 卡住终端报OSError: [WinError 1455] 页面文件太小Windows或std::bad_allocLinux原因gguf文件太大而llama-cpp-python默认尝试 mmap 全文件到内存。7B Q5_K_S 约 4.2GB若你物理内存 8GB 或页面文件Windows/ swapLinux 6GB必然失败。解决Windows右键「此电脑」→「属性」→「高级系统设置」→「性能→设置」→「高级→虚拟内存→更改」→ 勾选「自动管理」或手动设初始8192MB最大16384MBLinuxsudo fallocate -l 8G /swapfile sudo mkswap /swapfile sudo swapon /swapfile终极方案在config.yaml中加use_mmap: false强制不 mmap用 stream 加载速度略慢但内存友好。5.4 现象对话时回复乱码如 、中文崩坏、token 生成速度 1 tok/s原因tokenizer不匹配。llama-cpp-python加载gguf时若文件内嵌 tokenizer 不完整常见于非官方转换会 fallback 到llama-tokenizer它对中文支持极差。解决用llama.cpp提供的tokenizer-test工具验证./llama-tokenizer -m /models/deepseek-r1-7b-Q5_K_S.gguf -p 你好世界正常应输出你好 world对应的 token ID 序列若报错或输出异常必须用convert-hf-to-gguf.py重新转换并确保原始模型目录含tokenizer.json和tokenizer.model转换命令加--tokenizer-dir显式指定 tokenizer 路径./convert-hf-to-gguf.py deepseek-r1-7b --tokenizer-dir deepseek-r1-7b --outtype f166. 验证与上线用三个真实场景测试确认它真能干活装完不是终点验证才是。我习惯用三个递进式场景跑通 Page Assist单轮问答 → 多轮上下文 → 内网穿透共享。每个场景都对应一个可复制的命令、一个预期输出、一个失败时的自查清单。只有全部通过我才敢把它推给团队其他成员。6.1 场景一单轮问答验证 —— 确认模型加载与基础推理这是最轻量的验证绕过 UI直击核心。在page-assist/目录下新建test_api.py# test_api.py import requests import json url http://127.0.0.1:7860/api/chat headers {Content-Type: application/json} data { messages: [{role: user, content: 用中文解释量子纠缠}], temperature: 0.1, max_tokens: 256 } response requests.post(url, headersheaders, datajson.dumps(data)) print(Status Code:, response.status_code) print(Response:, response.json())运行python test_api.py✅预期输出status_code为200response.json()中choices[0].message.content包含一段关于量子纠缠的、语法正确的中文解释长度约 200 字。❌失败自查若status_code ! 200检查start.py是否在运行端口是否被占用lsof -i :7860或netstat -ano | findstr :7860若返回{error: Model not loaded}检查config.yaml中model_path是否正确且文件可读ls -l /your/model/path.gguf若返回{error: CUDA out of memory}降低n_ctx至2048或gpu_layers至30。6.2 场景二多轮上下文验证 —— 确认历史记忆与流式响应Page Assist 的核心价值之一是保持对话状态。我们用curl模拟流式请求验证上下文是否延续# 第一轮提问 curl -X POST http://127.0.0.1:7860/api/chat \ -H Content-Type: application/json \ -d { messages: [{role: user, content: 你是谁}], stream: true } \ --output /dev/null # 第二轮基于上文追问注意messages 必须包含第一轮的 userassistant curl -X POST http://127.0.0.1:7860/api/chat \ -H Content-Type: application/json \ -d { messages: [ {role: user, content: 你是谁}, {role: assistant, content: 我是 Deepseek R1一个开源的大语言模型。}, {role: user, content: 那你的训练数据截止到什么时候} ], stream: true } \ --output /dev/null✅预期输出第二轮响应中assistant的回答应明确提及训练数据时间如“2024年3月”而非重复自我介绍。❌失败自查若第二轮回答仍是“我是 Deepseek R1...”说明messages数组未正确传递历史检查 JSON 格式是否有多余逗号或引号若curl卡住无输出检查config.yaml中是否误设stream: false它应由 API 请求体控制非配置项若返回{error: maximum context length exceeded}说明n_ctx设置过小需增大至4096并重启服务。6.3 场景三内网穿透共享验证 —— 确认非本机可访问生产就绪很多团队需要让测试同事或产品经理在另一台电脑上试用。Page Assist 默认只监听127.0.0.1需显式放开# 启动时加 --host 0.0.0.0允许局域网访问 python start.py --host 0.0.0.0 --port 7860然后在另一台同局域网的机器如192.168.1.102上用浏览器访问http://192.168.1.101:7860101是运行 Page Assist 的机器 IP。✅预期输出UI 完全加载可正常输入、发送、收到回复且响应速度与本机一致 2s 首 token。❌失败自查若无法连接检查运行机器的防火墙sudo ufw statusUbuntu或Windows Defender 防火墙→高级设置→入站规则放行端口7860若 UI 加载但发送失败检查浏览器控制台 Network 标签页看api/chat请求目标地址是否仍是http://127.0.0.1:7860前端硬编码此时需在frontend/src/App.jsx中修改API_BASE_URL为实际 IP若响应极慢检查两台机器间网络延迟ping 192.168.1.101排除网络抖动。从那以后我每次部署 Page Assist都强制走一遍这三个场景test_api.py→curl多轮 →--host 0.0.0.0局域网验证。少一步上线后就多一个半夜被叫醒的理由。希望帮到你。本文还有配套的精品资源点击获取