logo

树莓派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可用空间。模型可以通过以下命令清理:

  1. docker exec -it ollama ollama list
  2. docker exec -it ollama ollama rm <模型名>
  3. docker system df
  4. docker image prune

四、Docker Compose部署

先创建工作目录:

  1. mkdir -p ~/local-ai && cd ~/local-ai
  2. mkdir -p ollama open-webui

在工作目录中创建compose.yaml:

  1. services:
  2. ollama:
  3. image: ollama/ollama:latest
  4. container_name: ollama
  5. restart: unless-stopped
  6. volumes:
  7. - ./ollama:/root/.ollama
  8. ports:
  9. - "127.0.0.1:11434:11434"
  10. environment:
  11. - OLLAMA_KEEP_ALIVE=5m
  12. - OLLAMA_NUM_PARALLEL=1
  13. - OLLAMA_MAX_LOADED_MODELS=1
  14. open-webui:
  15. image: ghcr.io/open-webui/open-webui:main
  16. container_name: open-webui
  17. restart: unless-stopped
  18. depends_on:
  19. - ollama
  20. volumes:
  21. - ./open-webui:/app/backend/data
  22. ports:
  23. - "127.0.0.1:3000:8080"
  24. environment:
  25. - OLLAMA_BASE_URL=http://ollama:11434
  26. - ENABLE_SIGNUP=${ENABLE_SIGNUP:-false}
  27. - WEBUI_SECRET_KEY=${WEBUI_SECRET_KEY}

配置说明如下:

  • volumes把模型和会话数据保存到当前目录,容器删除后数据不会丢失。
  • 127.0.0.1表示端口只接受本机访问,这是默认的安全边界。
  • OLLAMA_MAX_LOADED_MODELS=1让同一时间只驻留一个模型,适合内存有限的设备。

在同一目录生成密钥文件。密钥用于签名登录会话,不要把它写进compose文件或提交到代码仓库:

  1. printf "WEBUI_SECRET_KEY=%s\nENABLE_SIGNUP=true\n" "$(openssl rand -hex 32)" > .env
  2. chmod 600 .env

启动服务并确认状态:

  1. docker compose up -d
  2. docker compose ps

拉取模型。下面以qwen2.5:3b为例,适用于8GB内存设备。4GB内存设备可改用qwen2.5:1.5b。模型名称以Ollama模型库中的实际名称为准:

  1. docker exec -it ollama ollama pull qwen2.5:3b
  2. docker exec -it ollama ollama list
  3. curl http://127.0.0.1:11434/api/tags

访问验证。在树莓派上打开浏览器,访问http://127.0.0.1:3000。如果从另一台电脑访问,请使用SSH端口转发,不要直接开放端口:

  1. 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的账号认证依赖首次注册的管理员账号。推荐按以下顺序设置:

  1. 保持.env中ENABLE_SIGNUP=true,启动服务。
  2. 在浏览器中注册第一个账号。该账号会成为管理员。
  3. 把.env中的ENABLE_SIGNUP改为false,然后执行docker compose up -d使配置生效。
  4. 在管理后台创建其他用户

发表评论

活动