简介：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: Can't 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 --depth=1浅克隆，因为部分子模块（如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.9：
llama-cpp-python>=0.2.70编译失败，报PyLong_AsLong符号未定义（CPython 3.9 ABI 兼容性断层）； - Python 3.11：
gradio==4.38.0的fastapi依赖与uvicorn冲突，启动时报AttributeError: module 'typing' has no attribute 'get_args'； - Python 3.10.12：全链路通过，包括
torch==2.3.0+cu121（CUDA 12.1）、transformers==4.41.2、accelerate==0.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 python=3.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.2：
vite-plugin-react-swc插件解析 JSX 失败，Unexpected token '<'； - v20.12.0：
@vitejs/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 等）这个-e（editable 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 torch==2.3.0+cu121 torchvision==0.18.0+cu121 --index-url https://download.pytorch.org/whl/cu121
3.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 lang="zh-CN">和src="/assets/index-xxxx.js"；ls -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_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p修复。
3.3 启动整合服务：Python 启动器自动挂载前端，无需 Nginx
Page 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.json
Page 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-7b"4.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→7GB）；Q5_K_S：平衡速度与质量，7B 模型在 RTX 4090 上可达 120 tok/s；Q4_K_M：更小（3.8GB），但数学推理能力下降明显，不推荐用于 R1；- 转换后得到
deepseek-r1-7b-Q5_K_S.gguf，这就是 Page Assist 要加载的文件。
4.3 配置文件config.yaml：五项核心参数决定能否对话
Page Assist 读取根目录下的config.yaml。以下是必须配置的 5 个字段（其余可留空）：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model_path | string | ✅ | 指向gguf文件的绝对路径，如/models/deepseek-r1-7b-Q5_K_S.gguf |
model_type | string | ✅ | 固定填llamacpp（用 llama-cpp-python）或transformers（用 torch） |
n_ctx | integer | ✅ | 上下文长度，7B 模型建议设4096，太大显存溢出 |
n_threads | integer | ⚠️ | CPU 线程数，Linux 建议设$(nproc)，Windows 设8 |
gpu_layers | integer | ⚠️ | GPU 卸载层数，RTX 4090 建议45，A10 建议35 |
示例config.yaml：
model_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_alloc（Linux）
原因：gguf文件太大，而llama-cpp-python默认尝试 mmap 全文件到内存。7B Q5_K_S 约 4.2GB，若你物理内存 < 8GB 或页面文件（Windows）/ swap（Linux）< 6GB，必然失败。
解决：
- Windows：右键「此电脑」→「属性」→「高级系统设置」→「性能→设置」→「高级→虚拟内存→更改」→ 勾选「自动管理」或手动设初始=8192MB，最大=16384MB；
- Linux：
sudo 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 f16
6. 验证与上线：用三个真实场景测试，确认它真能干活
装完不是终点，验证才是。我习惯用三个递进式场景跑通 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, headers=headers, data=json.dumps(data)) print("Status Code:", response.status_code) print("Response:", response.json())运行：
python test_api.py✅预期输出：status_code为200，response.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 必须包含第一轮的 user+assistant） 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:7860（101是运行 Page Assist 的机器 IP）。
✅预期输出：UI 完全加载，可正常输入、发送、收到回复，且响应速度与本机一致（< 2s 首 token）。
❌失败自查：
- 若无法连接，检查运行机器的防火墙：
sudo ufw status（Ubuntu）或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局域网验证。少一步，上线后就多一个半夜被叫醒的理由。希望帮到你。
本文还有配套的精品资源，点击获取
