把树莓派、本地大模型和一个终端里的编程智能体放在一起就是我最近一直在折腾的 pi coding agent 玩法。说白了它让一块巴掌大的 ARM 开发板变成一个能帮我写单元测试、修 bug、补注释的“代码副驾驶”。没有昂贵的云服务账单不需要把仓库内容上传到第三方平台只要本地跑一个量化模型加一个支持自然语言改代码的命令行助手就能实现最基本的自动编码闭环。这篇文章写给两类人一类是手头有树莓派 4 或 5、想让它干点正经活的玩家另一类是平时写代码已经离不开 AI 辅助但出于隐私或成本考虑想完全本地化完整体验的开发者。我会从方案选型、系统配置、模型接入、实际编码任务再到性能调优和踩坑记录把一条完整可复现的路线讲清楚。你不需要高端显卡也不需要订阅任何付费 API关键就是愿意折腾。1. 为什么我会在树莓派上硬跑 AI 编程智能体1.1 纯云端方案的两类痛点先说一个很现实的问题现在随便打开一个网页或者 IDE 插件都能用 GPT 级别的模型帮你补全代码、改 bug体验确实不错。但真放到生产项目里我遇到过两类让我很不舒服的场景。第一类是代码隐私。公司的老代码里经常藏着内部账号、密钥占位符、特殊业务规则甚至是一些还没上线的算法思路。把这些内容通过插件或命令行丢给云端接口等于每次都在做一次无法撤回的“情报同步”。哪怕服务商承诺不留存作为一个长期维护私有仓库的人我心里始终没底。第二类是成本焦虑。用到“智能体”级别的时候不是简单一问一答而是把任务拆成多个步骤每一步都可能触发一次接口调用。你让它在仓库里找三处调用点并同步修改它可能读了十几个文件、产生十几轮对话。按 token 计费虽然单次不贵但一天下来几十块很常见。如果项目小组有五个人天天这么用一个月就是一笔不能忽视的开销。所以我一直在想能不能在本地搭一套“有来有回、能改文件、能跑测试”的编码智能体。答案是可以的而且树莓派就是最容易入门的本地硬件平台。它功耗低、占地小、常年开机不心疼跑一个量化过的 7B 代码模型虽然不能和云端大模型比速度但胜在私密、免费、离线可用。1.2 板子不是越贵越好型号怎么选我最初拿树莓派 4B 的 4GB 版本试过结论是能跑但只适合 3B 级小模型。一旦上 7B 量化模型内存会被吃得很满模型加载后系统剩余可用内存几乎见底运行一段时间就会出现明显卡顿。后来换了树莓派 5 的 8GB 版本同样是跑 7B 量化模型体验就完全不同。下面是两张板子的核心区别项目树莓派 4B8GB树莓派 58GB / 16GBCPU四核 Cortex-A72 1.8GHz四核 Cortex-A76 2.4GHz内存类型LPDDR4-3200LPDDR4X-4266推荐电源5V/3A5V/5A官方 PD 电源适合模型1.5B~3B 量化7B 量化16GB 可尝试更大参数AI代码补全体验约 3~6 token/s约 7~12 token/s7B 量化树莓派 5 最让我满意的其实是 16GB 版本。跑 qwen2.5-coder 7B 量化模型时模型本身占 4~5GB系统与智能体再占 2GB 左右16GB 内存仍然游刃有余甚至能在后台同时跑一个轻量代码索引服务。如果你预算有限8GB 版本也能跑 7B 模型只是要更注意内存回收但最终体验完全可以接受。还有一个容易忽略的点树莓派 5 的发热明显比 4B 激进。如果你打算长期开机组装本地 coding agent就不要省那个主动散热套件。我发现如果只用普通散热片跑模型时 CPU 温度很容易逼近 80 度然后系统开始降频token 生成速度肉眼可见地往下掉。1.3 模型先定 7B 量化再谈其他本地跑大模型第一个绕不开的词就是量化。它像一个压缩算法把模型权重的精度从 16 位压缩到 8 位甚至 4 位换来的是更小的内存占用和更快的推理速度代价是生成质量会有轻微损失。对写代码这类任务来说这几年主流量化模型的表现已经足够稳。我在树莓派上试过几类模型最后长期用的是 Qwen2.5 Coder 7B 的 Q4_K_M 量化版本。Q4_K_M 是 4 位量化里兼顾质量与速度的一种格式比 Q4_0 保留更多关键权重信息又不像 Q5 或 Q8 那样让树莓派内存吃紧。下面是我整理的选型经验模型规模内存需求量化后适用任务树莓派 5 体验1.5B约 1GB简单补全、解释代码非常流畅能达到 15 token/s 左右3B约 2~3GB小函数生成、文档注释流畅日常可用7B约 4~5GB单元测试、多文件修改、代码重构可接受明显有等待感14B约 9~11GB复杂架构设计、长上下文理解只有 16GB 版本勉强能跑速度较慢如果你只想要一个“自动补全代码”的工具3B 模型足够用速度快到会让你忘记这是树莓派。但如果你想要的是 coding agent——也就是让它读多个文件、理解目录结构、自主提出修改方案——我建议至少上 7B 模型。参数规模直接决定它在多文件任务中的推理连贯性太小了容易“说完前半段忘记后半段”。2. 环境配置先把底座夯实再谈代码智能2.1 系统精简、内存与交换分区在树莓派上跑模型最怕的不是算力不够而是系统被其他线程抢资源。我建议使用 Raspberry Pi OS Lite也就是没有桌面环境的精简版能省下几百 MB 内存和大量 CPU 开销。如果你非要图形界面至少别在跑模型时打开浏览器。装好系统后第一件事是把 GPU 内存显式调低。树莓派的内存是统一内存架构GPU 和 CPU 共享同一块内存默认给 GPU 划分 64MB但我们的模型推理根本不需要 GPU 显存。在/boot/firmware/config.txt中加一行gpu_mem16改完重启后系统可用内存会比默认多出一截。这一步体感不明显但在 8GB 版本上跑 7B 模型时往往就差这几十 MB 就能避免触发 OOM。然后是交换分区。树莓派默认的 swap 不大跑模型时一旦内存吃紧进程可能直接被 kill。我建议把 swap 提到 4GB同时配置vm.swappiness防止系统过早把活跃进程换到磁盘。编辑/etc/sysctl.confvm.swappiness10swappiness10的意思是只有内存压力较大时才使用 swap。这样模型推理时的热数据尽量留在内存中不会因为频繁换页导致速度雪崩。另外有条件的话把系统装在外接 USB SSD 上别用 microSD 卡。推理过程中就频繁读取模型文件SD 卡的随机读写性能实在太差SSD 提升非常明显。2.2 安装 Ollama 并拉取模型Ollama 是目前在树莓派上跑本地大模型最省事的工具。它把模型管理、API 服务、设备加速封装成一套命令只需两步就能把模型跑起来。curl -fsSL https://ollama.com/install.sh | sh安装完成后先确认服务状态systemctl status ollama正常会显示一个 active 的服务。接着拉取代码模型。这里我推荐两个标签按你的内存版本决定# 8GB 内存版本推荐 3B 模型快速稳定 ollama pull qwen2.5-coder:3b-instruct-q4_K_M # 16GB 内存版本推荐 7B 模型智能体体验更完整 ollama pull qwen2.5-coder:7b-instruct-q4_K_M拉取完成后用下面命令快速测试模型是否正常工作ollama run qwen2.5-coder:7b-instruct-q4_K_M输入一个简单问题比如“给一个 Python 函数写单元测试”。如果它能正常返回代码说明模型本身没问题。这一步不要跳过因为后面所有智能体功能都建立在模型能稳定推理的基础上。2.3 让局域网内其他设备也能访问Ollama 默认只监听本机回环地址127.0.0.1这意味着 Aider 在同一个树莓派上运行没问题但如果我想在笔记本上编辑代码、让树莓派的模型接管生成就需要把服务暴露到局域网。修改 Ollama 的 systemd 服务配置sudo systemctl edit ollama在打开的配置段中写入[Service] EnvironmentOLLAMA_HOST0.0.0.0:11434 EnvironmentOLLAMA_KEEP_ALIVE-1OLLAMA_HOST0.0.0.0:11434表示监听所有网卡接口OLLAMA_KEEP_ALIVE-1让模型一直驻留在内存里避免每次对话都要重新加载模型。由于模型加载往往要等几十秒这个设置对实际体验影响极大。保存后重启sudo systemctl daemon-reload sudo systemctl restart ollama然后从另一台电脑访问测试curl http://树莓派IP:11434/api/tags如果返回一段包含模型列表的 JSON说明局域网访问已经打通。这里要特别提醒Ollama 的 HTTP 接口本身没有鉴权千万不要把它直接暴露到公网。把端口映射到外网等于给全社会开放了你的电脑哪怕只是家庭宽带也不值得冒险。它只应在可信的内网环境里使用。3. 实操把 Coding Agent 真正接入工作流3.1 为什么选 Aider 而不是图形界面搭建好了模型服务下一步就是找一个能“自动改写文件”的智能体客户端。市面上的方案不少我在树莓派上试过几种最终推荐 Aider。Aider 是一个终端里的 AI 结对编程工具它与其他补全插件的本质区别在于它会读取你的本地 git 仓库理解文件结构然后根据你的自然语言要求修改文件、创建新文件甚至自动提交 commit。整个流程都发生在本地模型只在背后负责生成补丁文件读写和版本控制由 Aider 自己管理。我为什么不在树莓派上用 OpenHands 这类图形化智能体因为它们是完整的应用框架通常还要启动 Docker 容器、Web 界面、后端任务队列树莓派的内存和 CPU 根本吃不消。Aider 非常轻量只是一个 Python 程序依赖少启动快特别适合低算力硬件。而且它支持通过 OpenAI 兼容接口连接 Ollama配置起来非常简单。3.2 关键配置模型连接与命令参数安装 Aider 前建议先建一个独立的 Python 虚拟环境避免污染系统环境python3 -m venv ~/aider-venv source ~/aider-venv/bin/activate pip install aider-chat然后设置连接 Ollama 的环境变量export OPENAI_API_BASE_URLhttp://localhost:11434/v1 export OPENAI_API_KEYollama export OLLAMA_API_BASE_URLhttp://localhost:11434OPENAI_API_BASE_URL指向 Ollama 的 OpenAI 兼容端点后面的/v1很关键漏掉它会导致连接失败。OPENAI_API_KEY随便填一个非空字符串即可因为 Ollama 本地服务不做密钥校验。启动 Aideraider --model openai/qwen2.5-coder:7b-instruct-q4_K_M第一次启动时可以先用aider --list-models ollama_chat查看当前支持的前缀格式不同版本对模型名的要求会有细微差别。我自己的经验是现代版本直接用openai/模型名最省事。如果不想每次启动都输命令可以把常用参数写在/root/.aider.conf.yml或项目根目录的.aider.conf.yml里。我习惯写这样一个精简配置model: openai/qwen2.5-coder:7b-instruct-q4_K_M openai-api-base: http://localhost:11434/v1 openai-api-key: ollama no-auto-commits: falseno-auto-commits: false的意思是保留自动提交功能。Aider 每完成一次修改会把变更自动 commit 到 git这让每一步操作都可回滚。如果项目本身不适合频繁提交也可以改成true。3.3 实战演示让 Agent 帮我补测试并改 bug下面用一个具体例子说明真实工作流。我在树莓派的~/demo-project目录下建了一个仓库里面只有一个calc.py文件初始内容是有问题的def add(a, b): return a b def divide(a, b): return a / b我进入仓库目录确保已经过 git init 初始化然后启动 Aidercd ~/demo-project aider在 Aider 的交互提示符里输入这样一段要求请给 calc.py 里的 divide 函数增加除数为 0 时的错误处理抛出一个 ValueError 异常然后再帮我新建 tests/test_calc.py包含 add 和 divide 两个函数的单元测试测试要能通过 pytest 命令运行。Aider 会先读取仓库文件列表再按需打开calc.py然后生成修改方案。我实测时它很快理解了任务生成的核心修改是def divide(a, b): if b 0: raise ValueError(divisor cannot be zero) return a / b同时tests/test_calc.py里生成了标准 unittest 风格的测试用例包含正常除法、除数为零抛出异常、两数相加等场景。接着我让 Aider 帮我跑测试现在运行 pytest如果失败就修复代码。Aider 会执行命令并读取结果。它甚至会把测试输出里的AssertionError定位到具体行号再决定是否需要修改代码。这就是 coding agent 和普通补全工具最大的不同它是先理解任务、再动手改文件、最后验证结果的循环而不是只给你一段猜测代码。在对话过程中Aider 会自动提交每一次修改。我查看 git log 时能看到类似“add error handling and tests for calc”的提交记录整个过程可以被审计这一点在团队协作里尤其重要。4. 性能调优与问题排查实录4.1 参数调优想让回复又快又准跑本地模型默认参数只是起点。我用一段时间的体会是想让 coding agent 在树莓派上同时满足“可用”和“准确”需要调整两类参数推理参数和上下文参数。推理参数里最重要的是 temperature它控制生成结果随机性。代码任务和聊天不同过程中每个 token 都需要逻辑严谨太高的随机性会导致生成函数名跳跃、语法建议不稳定。我一般把它固定在 0.2。通过创建 Ollama Modelfile 实现cat Modelfile EOF FROM qwen2.5-coder:7b-instruct-q4_K_M PARAMETER temperature 0.2 PARAMETER num_ctx 4096 EOF ollama create pi-coder-local -f Modelfile创建完成后把 Aider 的模型参数指向openai/pi-coder-local即可。num_ctx 4096的意思是上下文窗口保留 4096 个 token对单文件修改和小仓库重构足够。如果你硬要开 8192树莓派内存和推理速度会立刻变得很难看。第二个影响体感的是OLLAMA_KEEP_ALIVE。我之前在 2.3 节提到-1表示模型常驻内存。这样做的好处是对话之间不需要重新加载模型Aider 响应速度会快很多。但代价是内存一直被模型占用如果同时跑其他服务需要斟酌取舍。另外建议关闭 Aider 每次对话都检索整个仓库的功能至少在低配机器上。我只让它操作当前已打开的文件避免它反复扫描整个项目。配置方式是在.aider.conf.yml中只启动需要的参数不给它“主动探索所有目录”的额外暗示。用户也可以直接在对话里用 **/read-only 指定文件减少无关文件的上下文污染。4.2 内存、交换分区以及存储介质的影响树莓派跑本地大模型瓶颈永远是内存和存储带宽而不是 CPU 主频。当我从 8GB 换到 16GB 设计时最明显的改善就是不再频繁触发交换。如果你在运行 Aider 时看到系统日志里出现oom-killer说明物理内存已经耗尽最常见的原因是内存版本只有 4GB 还强行加载 7B 模型。一个务实建议是做一个简单的压力测试启动 Aider 后同时打开htop观察内存占用。如果 MEM 稳定在 80% 以下说明你的模型和上下文大小搭配合理如果超过 90%马上减小num_ctx或换小一档的量化模型不要等进程被杀。存储介质的影响也很容易被忽视。我最初用普通 microSD 卡跑 Ollama模型启动要几十秒生成 token 时偶发卡顿大部分时间都花在读取内存页。后来换成了 USB SSD 并设为系统盘模型加载时间缩短了一半以上整体生成过程也更稳定。如果你的树莓派要长期当 coding agent一块好的 SSD 比疯狂超频更有效。4.3 常见问题速查表实操中我把最容易碰到的问题整理成了一张速查表每次重装环境都能省很多时间现象常见原因解决办法model not found拉取的模型标签写错用ollama list查确切名称再复制到 Aider 配置里Aider 连接失败漏了/v1路径检查OPENAI_API_BASE_URL是否以/v1结尾回答速度越来越慢OLLAMA_KEEP_ALIVE未设置导致反复加载模型设置OLLAMA_KEEP_ALIVE-1并重启服务输入长文件后被截断num_ctx太小在 Modelfile 中调大但不建议超过 8192系统进入 OOM 或被杀内存不足换 3B 模型或降低量化精度扩大 swap树莓派频繁热降频散热不足加装主动散热器检查室温必要时降低 CPU 频率Ollama 启动失败服务文件被覆盖用systemctl status ollama查看日志检查环境变量格式排查逻辑其实很简单先确认模型能否单独运行再确认 Aider 能否连接模型最后才排查具体任务的上下文问题。模型单独不行后面全白搭。如果遇到 Aider 生成内容时出现了偏离需求的代码我也会先看是不是 temperature 太高。给 coding agent 太低随机性确实能减少离谱输出但临时需要创意方案时我会临时调一下 Modelfile 里的参数再重新创建模型。好在 Ollama 创建模型很快这个操作成本非常低。5. 一些额外的体验和不成熟建议最后分享一个我实际摸索出来的小经验。刚开始用树莓派跑 coding agent 时我把所有任务都往里丢结果一个大型重构指令让它读了几十个文件不仅慢还会在某个文件上卡住。后来我把任务拆小一次只做一件事要么是“给这个函数补测试”要么是“重构某个模块的命名”它完成质量和速度都显著上升。还有一点是别把它当成 GPT 替代品。它在树莓派上的定位更像是“本地、私有、可自动执行小任务的代码小伙伴”。复杂架构设计、跨多个服务的全局重构它做不来但日常的补测试、改 bug、写注释、生成样例数据这些琐碎工作它可以一直干还不花钱。如果后续你有兴致还可以在这个基础上做一些扩展通过树莓派的 GPIO 和 SPI 接口接一些传感器让 coding agent 自动生成读取硬件的 Python 脚本或者把 Ollama 接入 VSCode 的 Continue 插件让图形界面也能复用同一套本地模型。我的感受是树莓派屏幕虽小但真正折腾起来它能给你带来的收获比想象中大。每次看到一块小板子在你面前逐字生成代码都会觉得这个时代确实不一样了。