树莓派5部署本地AI聊天服务实操指南
作者:菠萝爱吃肉2026.11.16 11:26浏览量:0简介:本文以树莓派5为例,讲解如何用Ollama和Open WebUI在单板计算机上搭建本地AI聊天服务。内容包括按内存选模型、Docker Compose部署、端口隔离与账号认证、备份恢复和常见故障排查。按步骤操作后,你能得到一套限于内网访问、保留会话历史的聊天环境。
一、适用范围与前提
本文面向在单板计算机上部署本地大模型聊天界面的开发者。示例设备为Raspberry Pi 5,系统为64位Raspberry Pi OS,并已安装Docker与Docker Compose插件。其他arm64单板计算机的步骤基本相同,但内存、存储和散热能力会直接影响使用体验。
部署前请先确认以下风险:
- 供电:Pi 5建议使用官方27W USB-C电源。供电不足时,系统会降频,甚至自动重启。
- 散热:模型推理会让CPU长时间满载。没有散热片或风扇时,温度升高会触发降频,生成速度随之下降。
- 存储:SD卡的写入寿命有限,而模型文件体积较大。建议把数据目录放在通过USB 3.0连接的SSD上,并定期检查系统日志中是否有存储错误。
- 内存:可用内存不足时,Linux内核会终止占用内存最多的进程,表现为容器突然退出。
二、选型:Ollama与Open WebUI的分工
本地AI交互服务由两部分组成。推理引擎负责加载模型并完成计算。Web应用负责浏览器聊天界面、会话历史和账号管理。
Ollama是常用的本地推理运行时。它提供模型下载、加载和推理的命令行工具,并在11434端口提供HTTP接口。Ollama本身没有聊天界面,也不提供用户认证。
Open WebUI是开源的Web聊天界面。它连接Ollama的接口,提供会话历史、多用户账号、提示词模板和文件上传。会话数据保存在本地数据目录中,服务重启后仍可查看历史记录。
两者组合的理由是职责分明:推理交给Ollama,界面和数据管理交给Open WebUI。如果只在命令行里调用模型,单独使用Ollama即可。如果需要多人共用或保留历史记录,再加上Open WebUI。
其他方案各有取舍:
| 方案 | 适用场景 | 主要代价 |
|---|---|---|
| Ollama + Open WebUI | 需要网页界面、多账号和历史记录 | 占用更多内存,需要维护两个服务 |
| llama.cpp加自建前端 | 追求极致灵活性,需要定制接口 | 界面和账号体系需要自行开发 |
| 桌面类应用 | 设备连接显示器,有图形界面 | 不适合无头运行的单板计算机 |
三、硬件与模型选择
内存是最主要的限制。模型权重加载后会占用内存,对话越长,KV缓存占用的内存也越多。系统、Docker和Open WebUI自身同样需要几百MB内存。
量化是降低内存占用的常用手段。Ollama模型库中的多数模型默认使用4比特量化,例如Q4_K_M。以下数字为估算值,实际占用请以docker stats和free -h的测量结果为准:
- 1.5B参数模型,Q4权重约1GB。
- 3B参数模型,Q4权重约2GB。
- 7B至8B参数模型,Q4权重约4.5GB至5GB。
按内存容量给出的建议如下:
- 4GB内存:选用1.5B至3B模型,并控制对话长度。
- 8GB内存:可以尝试7B至8B模型。模型能够加载,但余量紧张。长对话会让KV缓存持续增长,可能导致进程被终止。
- 16GB内存:7B至8B模型运行较为从容,可以保留更长的对话。
请区分“能加载”和“长对话稳定”两个条件。第一个条件只说明模型能启动,第二个条件要求在目标对话长度下内存仍有富余。
生成速度取决于CPU、内存带宽和模型大小。单板计算机没有GPU加速,生成速度通常较慢。请在自己的设备上实测后再确定模型,不要直接套用他人公布的速度数据。
存储方面,每个模型都要占用数GB空间。建议预留至少20GB可用空间。模型可以通过以下命令清理:
docker exec -it ollama ollama listdocker exec -it ollama ollama rm <模型名>docker system dfdocker image prune
四、Docker Compose部署
先创建工作目录:
mkdir -p ~/local-ai && cd ~/local-aimkdir -p ollama open-webui
在工作目录中创建compose.yaml:
services:ollama:image: ollama/ollama:latestcontainer_name: ollamarestart: unless-stoppedvolumes:- ./ollama:/root/.ollamaports:- "127.0.0.1:11434:11434"environment:- OLLAMA_KEEP_ALIVE=5m- OLLAMA_NUM_PARALLEL=1- OLLAMA_MAX_LOADED_MODELS=1open-webui:image: ghcr.io/open-webui/open-webui:maincontainer_name: open-webuirestart: unless-stoppeddepends_on:- ollamavolumes:- ./open-webui:/app/backend/dataports:- "127.0.0.1:3000:8080"environment:- OLLAMA_BASE_URL=http://ollama:11434- ENABLE_SIGNUP=${ENABLE_SIGNUP:-false}- WEBUI_SECRET_KEY=${WEBUI_SECRET_KEY}
配置说明如下:
volumes把模型和会话数据保存到当前目录,容器删除后数据不会丢失。127.0.0.1表示端口只接受本机访问,这是默认的安全边界。OLLAMA_MAX_LOADED_MODELS=1让同一时间只驻留一个模型,适合内存有限的设备。
在同一目录生成密钥文件。密钥用于签名登录会话,不要把它写进compose文件或提交到代码仓库:
printf "WEBUI_SECRET_KEY=%s\nENABLE_SIGNUP=true\n" "$(openssl rand -hex 32)" > .envchmod 600 .env
启动服务并确认状态:
docker compose up -ddocker compose ps
拉取模型。下面以qwen2.5:3b为例,适用于8GB内存设备。4GB内存设备可改用qwen2.5:1.5b。模型名称以Ollama模型库中的实际名称为准:
docker exec -it ollama ollama pull qwen2.5:3bdocker exec -it ollama ollama listcurl http://127.0.0.1:11434/api/tags
访问验证。在树莓派上打开浏览器,访问http://127.0.0.1:3000。如果从另一台电脑访问,请使用SSH端口转发,不要直接开放端口:
ssh -L 3000:127.0.0.1:3000 pi@<树莓派的IP地址>
然后在本机浏览器打开http://127.0.0.1:3000。
五、端口隔离与账号认证
Ollama没有用户认证。它的11434端口一旦暴露给局域网,任何人都能调用模型。因此,Ollama端口只绑定到127.0.0.1,并且不要改成0.0.0.0。
Open WebUI的账号认证依赖首次注册的管理员账号。推荐按以下顺序设置:
- 保持
.env中ENABLE_SIGNUP=true,启动服务。 - 在浏览器中注册第一个账号。该账号会成为管理员。
- 把
.env中的ENABLE_SIGNUP改为false,然后执行docker compose up -d使配置生效。 - 在管理后台创建其他用户

登录后可评论,请前往 登录 或 注册