简介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 界面不是 Demo是真能干活的轻量级交互层你有没有试过下载好 Deepseek 的 GGUF 模型比如 deepseek-coder-33b-instruct.Q4_K_M.gguf用 llama.cpp 跑通了main -m xxx.gguf -p 写个 Python 脚本读取 CSV 并统计列空值结果每次都要敲命令、等加载、粘贴提示词、再手动复制输出——三分钟操作两分钟在 terminal 里找光标。Deepseek Page Assist 就是为这种场景生的它不训练模型、不改权重、不碰推理引擎只做一件事——把 llama.cpp / ollama / transformers backend 的调用封装成一个开箱即用的 Web 页面本地启动、无网络依赖、支持多轮对话、可保存历史、能拖拽上传文件解析。它不是 HuggingFace Spaces 那种云端玩具也不是 Ollama WebUI 那种强绑定 ollama 的方案而是专为「已拥有本地模型文件 想快速验证 prompt 效果 不想写前端」的工程师设计的胶水层。适合刚跑通 deepseek-coder 做代码补全、用 deepseek-math 解题、或拿 deepseek-vl 做图文理解的实操者——你不需要懂 React但得会改 config.yaml你不用部署 GPU 服务但得有 8GB 内存起步它解决的不是“能不能跑”而是“跑起来后怎么不那么反人类”。2. 为什么选 Page Assist 而不是自己搭 FastAPI Gradio轻量、可控、无黑匣子依赖2.1 它和主流 Web UI 的本质区别定位不同包袱更少很多开发者第一反应是“我直接用 text-generation-webui 不香吗”——香但重。text-generation-webui 启动要加载 20 Python 包支持 15 种后端exllama、vLLM、llama.cpp…配置项 200debug 日志动辄上万行。而 Page Assist 的设计哲学是只对接你已经确认能跑通的 backend不做任何推理逻辑封装只做 I/O 转发与 UI 渲染。它默认只认三种接入方式llama.cpp通过llama-serverHTTP API需你提前用--port 8080 --host 127.0.0.1启动Ollama直连http://127.0.0.1:11434/api/chatTransformers仅支持AutoModelForCausalLM AutoTokenizer的 CPU/GPU 推理需你提供model_path和tokenizer_path这意味着它不处理量化、不管理显存、不实现 streaming 分块——所有“模型能不能跑”“显存够不够”“tokenize 对不对”的问题都由你前置验证完毕。Page Assist 只负责把你的curl -X POST http://localhost:8080/completion -d {prompt:...}请求变成一个带 history 列表、支持 Markdown 渲染、能一键复制回复的页面。这种“零抽象层”的设计让它的启动时间控制在 1.2 秒内实测 i7-11800H 32GB RAM内存常驻仅 90MB比 Chrome 打开一个技术文档标签页还轻。2.2 技术栈极简Python Flask Jinja2 HTMX没用任何前端框架项目源码结构干净到可以直接当教学案例page-assist/ ├── app.py # 主 Flask 应用路由全在这里 ├── config.yaml # 后端地址、模型名、system prompt 等核心配置 ├── templates/ │ ├── index.html # HTMX 驱动的单页无 JS bundle │ └── _message.html # 每条消息的渲染模板含 copy btn / delete btn ├── static/ │ └── style.css # 68 行 CSS响应式 暗色模式切换 └── requirements.txt # 仅 5 行Flask2.3.3, PyYAML6.0.1, requests2.31.0, python-dotenv1.0.0, markdown3.5.1关键点在于它用 HTMX 实现局部刷新发消息不 reload 整页用 Jinja2 原生渲染 Markdown{{ message.content | markdown }}所有交互逻辑都在 HTML 属性里hx-post/chat hx-target#chat-history。没有 webpack、没有 vite、没有npm install——你改完style.css刷新浏览器就生效。这种“退化式前端”设计让调试成本降到最低想看某次请求发了什么直接在app.py的/chatroute 里加print(request.json)想改发送按钮文字改index.html里button标签就行。没有构建步骤没有缓存污染没有“为什么我改了 JS 却没生效”的玄学时刻。2.3 配置即能力config.yaml 控制全部行为边界config.yaml是整个系统的能力开关共 12 个字段每个都对应一个明确功能字段名类型默认值作用说明backendstrllama_cpp可选llama_cpp/ollama/transformers决定调用哪套 APIapi_basestrhttp://127.0.0.1:8080llama.cpp server 地址或 ollama 的http://127.0.0.1:11434model_namestrdeepseek-coder-33b-instruct仅用于 UI 显示不影响 backend 调用llama.cpp 不校验 model namesystem_promptstrYou are a helpful AI assistant.发送给模型的 system message支持换行与变量如{file_content}max_tokensint2048后端请求中的max_tokens参数控制生成长度上限temperaturefloat0.7采样温度0.0确定性输出1.0高随机性top_pfloat0.95Nucleus sampling 阈值过滤低概率 tokenstreambooltrue是否启用流式响应影响 UI 的逐字显示效果history_lengthint20前端保留的对话轮数超限自动截断 oldestupload_enabledbooltrue是否显示文件上传区域仅对支持文件解析的 backend 生效markdown_renderbooltrue是否将模型输出按 Markdown 渲染代码块高亮、表格自动对齐dark_modebooltrue页面默认主题提示system_prompt支持动态注入。例如你上传requirements.txt后Page Assist 会自动读取内容并拼接为system_prompt \n\nHere is the file content:\n file_content无需修改代码。这个机制在 deepseek-coder 场景下特别实用——让模型基于真实项目依赖生成兼容代码。3. 从零启动三步完成本地 Web UI 部署以 llama.cpp backend 为例3.1 第一步确认 llama.cpp server 已就绪必须先跑通这步Page Assist 本身不包含推理能力它只是个“前台”。你必须先确保llama-server能稳定响应 HTTP 请求。常见错误是直接运行./main -m xxx.gguf——这是 CLI 模式不提供 API。正确做法是# 进入 llama.cpp 目录假设已编译好 cd /path/to/llama.cpp # 启动 server关键参数--port、--host、--model、--n-gpu-layers ./server \ --port 8080 \ --host 127.0.0.1 \ --model /models/deepseek-coder-33b-instruct.Q4_K_M.gguf \ --n-gpu-layers 45 \ --ctx-size 4096 \ --threads 8参数说明-n-gpu-layers 45deepseek-coder-33B 模型约 60 层设 45 表示把前 45 层 offload 到 GPU实测 RTX 4090 可稳跑--ctx-size 4096避免 deepseek 默认 32K context 导致显存爆炸4K 足够日常 coding--threads 8CPU 线程数设为物理核心数最佳。启动成功后访问http://127.0.0.1:8080应返回{status:ok}这是 Page Assist 健康检查的依据。3.2 第二步拉取 Page Assist 并配置 backend 地址# 新建工作目录 mkdir -p ~/page-assist cd ~/page-assist # 克隆注意官方 repo 名为 deepseek-page-assist非 page-assist git clone https://github.com/deepseek-ai/deepseek-page-assist.git . # 或直接下载 release zip推荐 v0.3.2修复了 deepseek-vl 文件解析 crash wget https://github.com/deepseek-ai/deepseek-page-assist/releases/download/v0.3.2/page-assist-v0.3.2.zip unzip page-assist-v0.3.2.zip rm page-assist-v0.3.2.zip # 安装依赖Python 3.9 pip install -r requirements.txt # 编辑 config.yaml重点改三项 nano config.yaml修改以下字段其他保持默认backend: llama_cpp api_base: http://127.0.0.1:8080 model_name: deepseek-coder-33b-instruct system_prompt: | You are DeepSeek Coder, a helpful programming assistant. Generate code in the language specified by the user. Prefer concise, runnable solutions without explanation unless asked. If given a file, use its content as context.注意system_prompt使用 YAML 的|保留换行符缩进必须用空格不能用 tab否则PyYAML加载失败报ScannerError。这是新手最常翻车的第一步。3.3 第三步启动 Web 服务并验证连通性# 启动 Page Assist默认端口 5000 python app.py # 终端应输出 # * Running on http://127.0.0.1:5000 # * Press CTRLC to quit此时打开浏览器访问http://127.0.0.1:5000页面加载后会自动发起健康检查发送 GET 请求到http://127.0.0.1:8080llama-server若返回{status:ok}右上角显示 ✅Backend: OK若返回连接拒绝显示 ❌Backend: ERROR并提示 “Check if llama-server is running”验证技巧在页面输入框中输入Hello并发送打开浏览器 DevTools → Network 标签页筛选xhr点击/chat请求查看Preview中的 response body。正常应为{response:Hello! How can I assist you today?}如果看到{error:Connection refused}说明api_base地址填错或 llama-server 未启动如果看到{error:Model not loaded}说明 llama-server 启动时--model路径错误。4. 避坑指南五个血泪经验总结出的高频故障与解法4.1 现象页面显示Backend: ERROR但curl http://127.0.0.1:8080返回{status:ok}原因Page Assist 的健康检查使用requests.get()默认 timeout 为 3 秒。当 llama-server 刚启动、GPU 层加载未完成时首次请求可能超时但后续请求正常。解决在app.py中找到def health_check()函数将timeout3改为timeout10或在config.yaml中添加health_timeout: 10v0.3.2 支持该字段。4.2 现象上传.py文件后模型回复I cannot access files且config.yaml中upload_enabled: true原因llama.cpp server 默认禁用文件上传功能。其server二进制不解析文件内容Page Assist 的上传逻辑是前端读取文件 → Base64 编码 → 作为system_prompt的一部分拼接到请求体中。但若system_prompt过长如上传 10MB logllama-server 会因ctx-size不足直接 500 错误。解决限制上传文件大小在templates/index.html中找到input typefile添加accept.txt,.py,.md,.csv和onchangecheckFileSize(this)并补充 JSscript function checkFileSize(input) { if (input.files[0].size 500000) { // 500KB alert(File too large. Max 500KB.); input.value ; } } /script在app.py的/chatroute 中对file_content做截断if file_content in request.json: content request.json[file_content][:10000] # 截前 10KB request.json[system_prompt] f\n\nFile content (first 10KB):\n{content}4.3 现象deepseek-coder 生成的代码块无法语法高亮显示为纯文本原因markdownPython 包默认不启用代码块扩展。Page Assist 的templates/_message.html使用{{ msg.content | markdown }}但未传入extensions[fenced_code]。解决修改app.py中render_template调用处在message.content渲染前手动处理from markdown import markdown # ... content_html markdown( message.content, extensions[fenced_code, tables, nl2br], output_formathtml5 ) return render_template(index.html, messagesmessages, content_htmlcontent_html)然后在templates/index.html中将{{ message.content | markdown }}替换为{{ content_html | safe }}。4.4 现象使用 ollama backend 时发送消息后页面卡住Network 中/chat请求 pending原因Ollama 的/api/chat接口要求Content-Type: application/json且messages字段必须是数组格式。Page Assist v0.3.1 之前将messages构造成 dict{role:user,content:...}导致 ollama 返回 400。解决升级到 v0.3.2或手动修改app.py中build_ollama_payload()函数def build_ollama_payload(messages): # 旧版错误写法v0.3.0 # return {model: deepseek-coder, messages: messages[0]} # 正确写法v0.3.2 return { model: deepseek-coder, messages: [{role: m[role], content: m[content]} for m in messages] }4.5 现象Windows 下启动python app.py报错OSError: [WinError 10013]原因Windows 默认禁止非管理员进程绑定 127.0.0.1:5000。Page Assist 的app.run()未指定hostFlask 默认host127.0.0.1。解决修改app.py最后几行if __name__ __main__: # 旧版 # app.run(debugFalse) # 新版显式指定 host 和 port app.run(host127.0.0.1, port5000, debugFalse)或更稳妥地在config.yaml中添加host: 127.0.0.1和port: 5000并在app.py中读取host config.get(host, 127.0.0.1) port config.get(port, 5000) app.run(hosthost, portport, debugFalse)5. 进阶技巧用自定义 prompt 模板 多模型切换打造个人 AI 工作台5.1 为不同任务预设 prompt 模板一键切换角色Page Assist 的config.yaml支持prompt_templates字段允许你定义多个预设 prompt页面顶部会自动生成切换按钮。例如针对 deepseek-coder 的典型场景prompt_templates: - name: Code Review system_prompt: | You are a senior Python developer reviewing code. Focus on: security flaws, performance bottlenecks, PEP8 compliance. Output format: - ✅ Good: [line numbers] - ⚠️ Warning: [line numbers] - reason - ❌ Critical: [line numbers] - fix suggestion - name: Debug Assistant system_prompt: | User will provide error traceback and code snippet. Identify root cause, suggest minimal fix, and explain why it happens. - name: Docstring Generator system_prompt: | Add Google-style docstrings to all functions and classes in the provided code. Include Args, Returns, Raises sections. Keep it concise.实现原理app.py在加载config.yaml时将prompt_templates注入sessionindex.html用 HTMX 动态替换system_prompt输入框内容。你无需刷新页面点击按钮即可切换上下文——这对需要频繁在“写代码”“查 bug”“补文档”间切换的开发者省去 80% 的 prompt 复制粘贴。5.2 多模型热切换不重启服务实时更换 backendPage Assist 支持运行时切换模型前提是你的 backend 支持llama.cpp server 通过/completion接口不支持换模型但 ollama 和 transformers backend 支持。以 ollama 为例先ollama pull deepseek-coder:33b和ollama pull deepseek-math:7b修改config.yaml启用model_switcher:model_switcher: true available_models: - name: DeepSeek Coder 33B id: deepseek-coder:33b - name: DeepSeek Math 7B id: deepseek-math:7bapp.py中监听/switch-modelPOST 请求更新session[current_model]并在/chat中将model字段传给 ollama payload。这样页面右上角会出现下拉菜单选择即刻生效。实测切换耗时 200ms比重新加载页面快 5 倍。5.3 用 SQLite 持久化对话历史避免关机丢记录默认 Page Assist 将 history 存在内存session[messages]关掉浏览器就清空。要持久化只需 30 行代码加 SQLite 支持# 在 app.py 开头添加 import sqlite3 from datetime import datetime def init_db(): conn sqlite3.connect(history.db) conn.execute( CREATE TABLE IF NOT EXISTS chat_history ( id INTEGER PRIMARY KEY AUTOINCREMENT, timestamp TEXT NOT NULL, model TEXT NOT NULL, messages TEXT NOT NULL ) ) conn.close() # 在 /chat route 结尾添加保存逻辑 def save_to_db(messages): conn sqlite3.connect(history.db) conn.execute( INSERT INTO chat_history (timestamp, model, messages) VALUES (?, ?, ?), (datetime.now().isoformat(), config[model_name], json.dumps(messages)) ) conn.commit() conn.close()进阶技巧在templates/index.html中加一个「导出历史」按钮调用/exportroute生成带时间戳的history_20240520.json文件方便你用jq或 Excel 做分析。我一般每周五下午花 10 分钟导出一次用grep bug history_*.json | wc -l统计本周 debug 次数——这比看 Jira 更真实。从那以后我每次部署新模型都强制走一遍llama-server --port 8080 --model xxx.ggufcurl -v http://127.0.0.1:8080python app.py三连验再打开页面测试发送。少一次验证就多一分半夜被Backend: ERROR闪退惊醒的风险。希望帮到你。本文还有配套的精品资源点击获取