1. 项目缘起与核心设计思路

1.1 为什么要在离线环境里折腾一个手摇AI盒子

第一次看到"CrankGPT"这个名字的时候，我脑子里蹦出来的画面是一台老式手摇发电机连着树莓派，屏幕上跑着一个大语言模型，你摇得越快它回答得越流畅。这个画面虽然有点荒诞，但它精准地戳中了一个真实存在的需求：在完全断网、没有稳定供电的场景下，能不能让AI继续工作？

这个问题的实际应用场景比想象中要多。比如野外科研考察、偏远地区的教学辅助、应急通信演练、甚至是展览馆里做一个"物理交互式AI装置"，这些场景的共同特点是：没有Wi-Fi、没有手机信号、插座可能是奢望。传统的云端AI方案在这里完全失效，而普通的离线AI方案又面临一个尴尬的问题——电池总有用完的时候。

CrankGPT的核心思路就是把这个链条补全：用人力发电驱动一台低功耗计算设备，在本地运行量化后的大语言模型，通过一块小屏幕完成人机交互。整个系统不依赖任何网络连接，不需要外部电源，你摇动手柄就是在给AI"充电"，同时也在给它提供"思考"的能量。

这个项目的技术栈选择非常明确：Raspberry Pi作为计算平台，llama.cpp作为推理引擎，OLED或小尺寸LCD作为显示输出，手摇发电机作为供电模块。这四个组件构成了一个完整的闭环，每一个环节都有成熟的社区方案可以借鉴，但把它们组合在一起并且做到"可用的交互体验"，才是这个项目真正有意思的地方。

1.2 硬件选型的逻辑与取舍

先说计算平台。为什么选Raspberry Pi而不是其他开发板？这里有几个硬性约束在起作用。

第一是内存容量。要在本地跑语言模型，哪怕是量化到4-bit的7B模型，也需要至少4GB的可用内存。Raspberry Pi 4B的4GB或8GB版本刚好卡在这个门槛上，而大多数微控制器（比如ESP32、STM32）的内存只有几百KB到几MB，根本不可能加载模型权重。Raspberry Pi 5虽然性能更强，但功耗也更高，对于手摇发电来说，每多一瓦都是额外的体力消耗。

第二是软件生态。llama.cpp在ARM64架构上的编译和优化已经非常成熟，Raspberry Pi OS自带的GCC工具链可以直接编译，社区里也有大量针对Pi的编译参数优化经验。如果换成一个冷门的开发板，光是让llama.cpp跑起来可能就要花掉大半的时间。

第三是功耗与性能的平衡。Raspberry Pi 4B在空闲状态下的功耗大约是3W左右，满载推理时可能冲到6-7W。这个数字对于手摇发电机来说是可以接受的——一个成年人持续手摇发电的输出功率大约在50-100W之间，扣除转换损耗后，驱动一台Pi加上屏幕和外围电路绰绰有余。但如果你换成一台x86迷你主机，功耗直接翻倍，手摇的体验就会从"锻炼身体"变成"体力劳动"。

显示模块的选择相对灵活。0.96寸OLED（SSD1306驱动）是最常见的选择，I2C接口，接线简单，功耗极低，但分辨率只有128x64，显示几行文字就到头了。如果想要更好的交互体验，可以考虑2.8寸或3.5寸的SPI接口TFT屏幕，分辨率能到320x480，可以显示更长的文本和简单的图形界面。我个人的建议是：如果你只是做一个概念验证，OLED足够了；如果你想让这个盒子真正"可用"，至少上2.8寸的屏幕。

手摇发电部分是这个项目最有"物理感"的环节。常见的方案有两种：一种是直接用成品的手摇发电机模块（比如那些带USB输出的应急手摇充电器），另一种是自己用直流电机加整流桥和稳压电路搭建。成品模块的好处是省事，输出通常是5V/1A左右，直接插到Pi的USB供电口就能用。但问题是，手摇发电的输出电压和电流会随着摇动速度剧烈波动，而Raspberry Pi对供电质量比较敏感，电压跌落可能导致系统重启甚至SD卡损坏。

所以这里必须加一级电源管理电路。我的做法是在手摇发电机和Pi之间加一个超级电容模组（比如5.5V 1F到10F的电容组）加上一个DC-DC稳压模块。超级电容的作用是"削峰填谷"：你摇得快的时候，多余的能量存进电容；你摇得慢或者停下来的时候，电容放电维持Pi的运行。这样即使你中途休息几秒钟，系统也不会断电。稳压模块则确保输出电压稳定在5.1V左右，满足Pi的供电要求。

1.3 软件架构的搭建思路

软件层面的核心是llama.cpp。这个项目的推理引擎选择几乎没有悬念——在ARM64平台上，llama.cpp是目前最成熟、最高效的本地推理方案。它支持GGUF格式的量化模型，可以在CPU上以可接受的速度运行7B甚至13B参数的模型。

整个软件栈从下往上大致是这样的：

• 底层：Raspberry Pi OS Lite（64-bit），最小化安装，去掉所有不必要的服务和图形界面，减少内存占用和CPU开销。
• 推理层：llama.cpp编译为ARM64原生二进制，启用NEON指令集优化和OpenBLAS加速。
• 模型层：GGUF格式的量化模型，通常选择Q4_K_M或Q4_0量化级别，在模型质量和推理速度之间取得平衡。
• 交互层：一个Python脚本或者Shell脚本，负责读取用户输入（通过物理按键或触摸屏），调用llama.cpp的API或命令行接口，然后把生成的文本输出到屏幕上。

这里有一个关键的设计决策：是用llama.cpp的server模式还是直接调用命令行？server模式的好处是可以保持模型常驻内存，每次推理不需要重新加载模型，响应速度更快。但server模式会占用更多的内存（因为要维护HTTP服务的开销），而且如果系统意外断电，重启后需要重新加载模型。命令行模式则更简单直接，每次调用都是一次独立的进程，但模型加载时间可能长达十几秒，对于交互体验来说是致命的。

我的建议是：如果你的Pi是4GB内存，用server模式，但把上下文长度限制在512或1024 tokens以内；如果是8GB内存，可以放宽到2048 tokens。另外，可以考虑用一个轻量级的进程守护工具（比如systemd服务）来管理llama.cpp server，确保它在系统启动后自动运行，并且在崩溃后自动重启。

2. 核心细节解析与实操要点

2.1 手摇发电与电源管理的具体实现

手摇发电这部分，我踩过的坑最多，值得展开说。

最开始我用的是一个标称"5V 1A"的手摇充电器，拆开一看里面就是一个直流电机加几个二极管和一个简单的稳压芯片。实际测试下来，空载电压能到7-8V，但一旦接上负载（比如Pi），电压立刻跌到4V以下，Pi直接掉电重启。原因很简单：手摇发电的内阻很大，输出电流能力有限，而Pi在启动瞬间的电流需求可能超过1A。

解决方案是加入超级电容缓冲。我选的是两个5.5V 10F的超级电容串联（注意串联后耐压翻倍但容量减半，变成11V 5F），然后通过一个降压模块（比如LM2596或MP1584）降到5.1V输出。超级电容的充电时间取决于手摇发电机的输出功率，实测下来，摇动大约30秒可以把电容从3V充到5V，足够Pi运行大约1-2分钟（取决于负载）。

这里有一个细节：超级电容的均压问题。两个电容串联时，由于个体差异，分压可能不均匀，导致其中一个过压损坏。所以需要在每个电容两端并联一个均压电阻（比如100Ω 1W），确保电压均匀分配。这个电阻会持续消耗少量电流，但对于10F的电容来说，漏电流可以忽略不计。

另一个细节是防反接保护。手摇发电机的输出极性取决于摇动方向，如果你反向摇动，输出电压极性会反转，可能损坏后续电路。加一个桥式整流器（比如MB10S）可以解决这个问题，代价是损失大约1.4V的压降。对于5V输出来说，这个损失是可以接受的。

注意：超级电容在初次使用前需要预充电。如果直接从一个满电的电源快速充电，可能会因为浪涌电流过大而损坏电容或电源。建议通过一个限流电阻（比如10Ω 5W）缓慢充电到额定电压后再接入电路。

2.2 llama.cpp在Raspberry Pi上的编译与优化

llama.cpp的编译过程本身不复杂，但要在Raspberry Pi上获得可用的推理速度，编译参数的调整至关重要。

首先，确保你的系统是64-bit的。Raspberry Pi OS的32-bit版本虽然也能编译llama.cpp，但ARM64架构在内存寻址和NEON指令集的支持上更完整，推理速度通常有20%-30%的提升。检查方法很简单，在终端输入uname -m，如果输出aarch64就是64-bit，如果是armv7l就是32-bit。

编译前的依赖安装：

sudo apt update sudo apt install -y build-essential cmake git libopenblas-dev

然后克隆llama.cpp仓库并编译：

git clone https://github.com/ggerganov/llama.cpp cd llama.cpp mkdir build && cd build cmake .. -DLLAMA_BLAS=ON -DLLAMA_BLAS_VENDOR=OpenBLAS -DLLAMA_NATIVE=ON make -j4

这里的几个关键参数值得解释：

• LLAMA_BLAS=ON：启用BLAS（基础线性代数子程序）加速。矩阵乘法是语言模型推理中最耗时的操作，BLAS库可以显著提升这部分的速度。
• LLAMA_BLAS_VENDOR=OpenBLAS：指定使用OpenBLAS作为BLAS后端。OpenBLAS对ARM64有专门的优化，比默认的参考实现快很多。
• LLAMA_NATIVE=ON：让编译器针对当前CPU的指令集进行优化。在Raspberry Pi 4B上，这会启用Cortex-A72支持的NEON和CRC扩展指令。
• -j4：使用4个线程并行编译。Raspberry Pi 4B有4个核心，这个数字刚好匹配。

编译完成后，你会得到main、server等可执行文件。建议把build/bin目录加到PATH里，方便后续调用。

模型的选择和量化是另一个关键点。GGUF格式的模型可以从Hugging Face等平台获取，常见的7B模型量化到Q4_K_M后大小约为4GB左右，刚好能塞进Raspberry Pi 4B的4GB内存（但要注意系统本身和其他进程也会占用内存，实际可用可能只有3.5GB左右）。如果内存紧张，可以考虑Q4_0量化或者更小的3B模型。

实测下来，Raspberry Pi 4B（4GB版本，未超频）运行Q4_K_M量化的7B模型，推理速度大约是每秒2-4个token。这个速度对于实时对话来说偏慢，但如果你把问题控制在50个token以内，等待时间大约15-25秒，勉强可以接受。如果换成3B模型，速度可以提升到每秒6-8个token，体验会好很多。

2.3 显示与交互模块的搭建

显示模块的选择直接决定了交互体验的上限。0.96寸OLED（SSD1306）是最经济的选择，I2C接口只需要两根信号线（SDA和SCL），供电3.3V或5V都可以。在Raspberry Pi上启用I2C后，可以用Python的luma.oled库或者Adafruit_SSD1306库来驱动。

但OLED的128x64分辨率意味着你最多只能显示4行、每行16个英文字符（或者8个中文字符）。对于简短的问答来说够用，但如果你想显示更长的回答，就需要做分页滚动。我的做法是：把llama.cpp的输出按每行16个字符自动换行，然后每页显示4行，通过物理按键翻页。这样虽然不够优雅，但至少能读完完整的回答。

如果预算允许，我强烈建议上2.8寸的SPI TFT屏幕（ILI9341驱动）。320x240的分辨率可以显示大约20行、每行40个字符，基本上一次就能显示完一个完整的回答。SPI接口需要更多的引脚（通常需要6-7根线），但刷新速度比I2C快得多，滚动和翻页的体验也更流畅。

交互输入方面，最简单的方案是几个物理按键：一个"确认/发送"键，一个"上翻"键，一个"下翻"键。如果要做文字输入，可以接一个USB小键盘，或者用 rotary encoder（旋转编码器）来做字符选择。旋转编码器的好处是只需要两个GPIO引脚（加上一个按键引脚），而且操作直观——旋转选择字符，按下确认。

实操心得：在OLED上做文字输入是一件非常痛苦的事情。我的建议是预置几个常用的提示词模板，比如"解释这个概念"、"翻译以下内容"、"总结要点"，用户只需要选择模板然后按确认，不需要逐字输入。如果确实需要自由输入，用USB键盘或者通过串口从另一台设备发送文本会更实际。

3. 完整实操流程与核心环节实现

3.1 硬件组装与接线

先把整个系统的硬件连接关系理清楚。核心组件包括：Raspberry Pi 4B、手摇发电机、超级电容模组、DC-DC稳压模块、显示屏幕、物理按键。

接线顺序如下：

1. 手摇发电机输出→ 桥式整流器（MB10S）→ 超级电容模组（两个5.5V 10F串联，带均压电阻）→ DC-DC降压模块（MP1584，输出调到5.1V）→ Raspberry Pi的USB-C供电口（或者GPIO的5V引脚）。

2. 显示屏幕：如果是I2C OLED，VCC接3.3V（Pin 1），GND接GND（Pin 6），SDA接GPIO2（Pin 3），SCL接GPIO3（Pin 5）。如果是SPI TFT，需要接更多的线，具体参考屏幕的引脚定义。

3. 物理按键：一端接GPIO引脚（比如GPIO17、GPIO27、GPIO22），另一端接GND。在软件中启用内部上拉电阻，按键按下时读取到低电平。

4. 散热：Raspberry Pi 4B在满载推理时发热量不小，建议加一个小型散热片或者5V风扇。风扇可以直接从Pi的5V引脚取电，但要注意风扇的功耗（通常0.1-0.2A），不要超过Pi的供电能力。

注意：如果你用的是USB-C供电口，确保DC-DC模块的输出电压稳定在5.1V左右。电压低于4.8V可能导致Pi工作不稳定，高于5.5V可能损坏Pi。用万用表在接上负载的情况下测量输出电压，确认在安全范围内。

3.2 系统配置与软件部署

Raspberry Pi OS Lite的安装和基本配置这里不展开，假设你已经有一个可以SSH登录的系统。接下来是关键的配置步骤。

第一步：启用I2C和SPI接口。

sudo raspi-config

在"Interface Options"中启用I2C和SPI。然后安装I2C工具：

sudo apt install -y i2c-tools sudo i2cdetect -y 1

如果OLED屏幕连接正确，你应该能看到地址0x3C的设备。

第二步：部署llama.cpp和模型。

把之前编译好的llama.cpp二进制文件复制到/usr/local/bin，模型文件放到/home/pi/models目录。然后创建一个systemd服务来管理llama.cpp server：

[Unit] Description=llama.cpp server After=network.target [Service] ExecStart=/usr/local/bin/llama-server -m /home/pi/models/model.gguf -c 1024 -t 4 --host 127.0.0.1 --port 8080 Restart=always User=pi [Install] WantedBy=multi-user.target

这里的参数说明：-c 1024表示上下文长度为1024个token，-t 4表示使用4个线程，--host 127.0.0.1表示只监听本地回环地址（不需要外部访问）。

第三步：编写交互脚本。

用Python写一个简单的交互循环，负责读取按键输入、调用llama.cpp server的API、把结果显示到屏幕上。核心逻辑大概是这样的：

import requests import json from luma.core.interface.serial import i2c from luma.oled.device import ssd1306 from luma.core.render import canvas import RPi.GPIO as GPIO # 初始化OLED serial = i2c(port=1, address=0x3C) device = ssd1306(serial) # 初始化按键 GPIO.setmode(GPIO.BCM) GPIO.setup(17, GPIO.IN, pull_up_down=GPIO.PUD_UP) def query_llama(prompt): url = "http://127.0.0.1:8080/completion" data = {"prompt": prompt, "n_predict": 128, "temperature": 0.7} response = requests.post(url, json=data) return response.json()["content"] def display_text(text): lines = [text[i:i+16] for i in range(0, len(text), 16)] for i in range(0, len(lines), 4): with canvas(device) as draw: for j, line in enumerate(lines[i:i+4]): draw.text((0, j*16), line, fill="white") # 等待按键翻页 while GPIO.input(17) == GPIO.HIGH: pass

这个脚本只是一个骨架，实际使用中还需要处理按键消抖、错误处理、超时重试等细节。但核心思路就是这样：按键触发查询，llama.cpp server返回结果，屏幕分页显示。

3.3 手摇发电的实测数据与调优

我用手摇发电机给整个系统供电，做了一组实测。测试条件：Raspberry Pi 4B（4GB），0.96寸OLED，llama.cpp server运行中（模型已加载），手摇发电机标称5V 1A。

从数据可以看出，中速摇动（大约每秒2圈）就足以维持整个系统的运行。如果你在等待模型生成回答的时候摇动，电容电压会保持稳定；如果你停下来休息，电容可以支撑大约90秒到2分钟，足够你读完一个简短的回答。

这里有一个经验：不要在模型推理的时候停止摇动。因为推理时CPU满载，功耗会从空闲的3W飙升到6-7W，电容的放电速度会明显加快。如果你在推理过程中停止摇动，可能不到30秒系统就会因为电压不足而重启。所以我的使用节奏是：摇动→输入问题→继续摇动→等待回答→停止摇动→阅读回答。

实操心得：超级电容的容量直接决定了你能"偷懒"多久。如果你用的是5F的电容组，停下来后大约能撑1分钟；如果你换成10F甚至20F，可以撑到3-5分钟。但电容越大，充电时间也越长。我的建议是5F到10F之间比较平衡，既能给你足够的阅读时间，又不会让你摇到手臂酸麻才能充好电。

4. 常见问题与排查技巧实录

4.1 系统稳定性问题排查

问题一：Pi频繁重启或无法启动。

这是最常见的问题，90%的情况是供电不足。排查步骤：

1. 用万用表测量Pi的5V引脚电压，在Pi启动的瞬间观察电压是否跌落到4.8V以下。如果是，说明电源的瞬时电流输出能力不够。
2. 检查DC-DC模块的额定输出电流。MP1584标称3A，但实际持续输出2A以上就会明显发热，效率下降。如果Pi在推理时电流需求超过2A，考虑换一个更大功率的模块（比如LM2596，标称3A）。
3. 检查超级电容的均压电阻是否焊接正确。如果均压电阻缺失或阻值过大，可能导致电容分压不均，实际可用容量下降。

问题二：llama.cpp server启动失败或推理时报错。

首先检查模型文件是否完整。GGUF文件在下载过程中可能损坏，用md5sum或sha256sum校验一下。然后检查内存是否足够：

free -h

如果可用内存小于模型文件的大小，server会在加载模型时被OOM killer杀掉。解决方法：换更小的模型，或者增加swap空间（但swap会严重拖慢推理速度，不推荐）。

问题三：OLED屏幕不亮或显示乱码。

I2C地址错误是最常见的原因。用i2cdetect -y 1确认地址，常见的SSD1306地址是0x3C或0x3D。如果地址正确但屏幕还是不亮，检查VCC电压——有些OLED模块标称支持3.3V-5V，但实际上3.3V时亮度很低，需要接5V。另外，I2C线太长（超过20cm）可能导致信号衰减，尽量缩短接线长度。

4.2 推理速度优化技巧

如果你觉得推理速度太慢，可以尝试以下几个优化方向：

第一，换更小的模型。7B模型在Pi 4B上的速度大约是2-4 token/秒，换成3B模型可以提升到6-8 token/秒，换成1B模型可以到15-20 token/秒。对于简单的问答任务，1B或3B模型的质量已经可以接受。

第二，调整量化级别。Q4_K_M是质量和速度的平衡点，如果你更看重速度，可以换成Q4_0或Q4_1，推理速度会有10%-20%的提升，但模型质量会有所下降。

第三，超频。Raspberry Pi 4B可以通过修改/boot/config.txt来超频CPU。在config.txt中添加：

over_voltage=2 arm_freq=1800

这会把CPU频率从1.5GHz提升到1.8GHz，推理速度大约提升15%-20%。但超频会增加功耗和发热，对于手摇发电的场景来说，需要权衡一下。而且超频可能导致系统不稳定，如果出现随机崩溃，把over_voltage降到1或者去掉超频配置。

第四，使用更小的上下文长度。llama.cpp的推理速度与上下文长度成正比。如果你把-c参数从2048降到512，推理速度会有明显提升。对于简短的问答来说，512的上下文通常够用了。

4.3 常见问题速查表

4.4 几个容易被忽略的细节

SD卡的选择。Raspberry Pi对SD卡的速度和可靠性比较敏感。建议用Class 10以上的卡，容量至少16GB（模型文件可能就有4-8GB）。另外，频繁断电可能导致文件系统损坏，建议在系统中启用overlayfs或者把根文件系统挂载为只读，减少SD卡的写入操作。

散热。Pi 4B在满载推理时，SoC温度可能达到70-80°C。如果温度超过85°C，Pi会自动降频，推理速度会明显下降。加一个散热片或者小风扇，可以把温度控制在60°C以下，保持稳定的推理性能。

手摇发电机的选择。不同型号的手摇发电机输出特性差异很大。有些标称5V 1A，但实际上在低转速下电压只有2-3V。建议选择那些带有稳压电路的成品模块，或者自己加一个升压模块（比如MT3608），确保在低转速下也能输出稳定的5V。

模型的提示词格式。不同的模型对提示词的格式要求不同。比如Llama 2系列需要用[INST]和[/INST]包裹指令，而Mistral系列则用<s>[INST]开头。如果提示词格式不对，模型的回答质量会大打折扣。建议在llama.cpp的server启动参数中加上--chat-template或者手动在Python脚本中格式化提示词。

这个项目从最初的概念到最终能跑起来，我大概花了两个周末的时间。最耗时的部分不是软件配置，而是电源管理的调试——手摇发电的不稳定性远超我的预期，超级电容的选型和均压电路的设计反复改了好几版。但当你摇动手柄，看到屏幕上慢慢浮现出一段完整的回答时，那种"用体力驱动AI"的满足感是插着电源跑模型完全比不了的。如果你也想做一个，我的建议是先从插电版本开始，把软件和交互调通，然后再把手摇发电部分加进来。这样你可以分阶段验证，不会一上来就被电源问题卡住。