轻松搭建鸟类追踪站！监测附近鸟类访客，还能实时展示
鸟类访客项目：从个人小项目到公开报告
一开始，项目发起者打算把“鸟类访客”项目当作个人项目，觉得这只是花一下午完成的小项目，发条推文记录就行。然而，Twitter上的反响让他改变想法，为想监测自家附近鸟类访客的人整理了这份简短报告。目前报告简洁明了，是为尽快分享，且这项工作是一系列与鸟类相关项目的一部分，后续还会有相关内容。
公寓鸟类：“鸟类访客”分支及物料清单
“鸟类访客”（Avian Visitors）是 [BirdNET - Pi] 的一个分支，添加了花鸟绘风格的拼贴覆盖层。BirdNET - Pi 负责音频采集和物种识别，用康奈尔大学的 [BirdNET] 声学分类器分析树莓派上 USB 麦克风采集的声音。可在 [bird.onethreenine.net] 查看运行效果。
搭建鸟类追踪站所需材料如下：
- 1 个树莓派（4B / 5 / Zero 2W），价格约 $35 - 80
- 1 个微型 SD 卡（≥32 GB），价格约 $10
- 1 个 USB 领夹式麦克风，价格 $16.95
- 1 个树莓派电源，价格约 $10
同时，还需获取 [Gemini API 密钥] 重新设计插图（免费套餐即可），以及 [eBird API 密钥] 按地区过滤物种。
本地 Birdnet：安装与配置
使用 [树莓派镜像写入工具] 将 SD 卡格式化，选择树莓派操作系统精简版（64 位），在自定义对话框设置用户名、Wi - Fi 网络名称和密码、主机名 `birdnet` 并启用 SSH 密码认证。
将 USB 麦克风插入树莓派，放在窗户旁或室外，作者把麦克风贴在朝向阳台的小窗户玻璃上，树莓派放室内避免受潮，然后启动树莓派。树莓派联网后，通过 SSH 登录并运行安装程序。安装程序默认使用无密码的 sudo，安装过程会克隆分支，运行 BirdNET - Pi 的安装程序，将“鸟类访客”的覆盖层符号链接到 Caddy Web 根目录，完成后自动重启，整个过程需 20 - 40 分钟。
树莓派重启后，拼贴页面位于 `http://birdnet.local/`，原始的 BirdNET - Pi UI 仍可通过 `http://birdnet.local/index.php` 访问。右上角菜单抽屉打开管理覆盖层，包含原生设置、系统、日志和工具面板，可在不离开拼贴页面的情况下调整分析器、监控服务和查看日志。
可选：将服务暴露到局域网外
Cloudflare Tunnel
可提供公共的 HTTPS URL，无需端口转发，不暴露家庭 IP 地址。需免费的 Cloudflare 账户，设置约 5 分钟。先在树莓派上安装 `cloudflared`，再进行认证并创建隧道，指向拥有的域名下的主机名，复制配置文件，安装并启动服务。若想在公共 URL 上设置密码保护，可设置 Cloudflare Access，也可通过 Caddy 本身使用 HTTP 基本认证。
Home Assistant REST 传感器
会在 Home Assistant 中将最近检测结果显示为 `sensor.latest_bird`，可集成到自动化操作。在 `configuration.yaml` 中添加相关内容，`recent` 端点返回的物种按数量降序排列，可按需修改 `value_template`。
MQTT 桥接
MQTT 桥接器每分钟轮询最近检测结果的端点，将新物种以 JSON 格式发布到 `birdnet/` 主题下。安装 paho - mqtt，复制桥接脚本和服务文件，并启用服务。去重仅在内存中进行，服务重启时桥接器会重新发布过去一小时的检测结果，下游消费者应具有幂等性。
插图与拼贴：生成与处理
拼贴页面附带 450 张常见北美鸟类的插图，由 Gemini 的 [`gemini - 2.5 - flash - image`] 模型生成，每个物种有栖息和飞行两种姿态。提示模板位于 [`avian/scripts/prompt.template.md`]，每次请求替换学名、俗名和姿态三个模板变量，重新设计图像集编辑文件后用 `--force` 参数重新运行预生成脚本。
传递 `--ebird - region` 参数时，预生成脚本会将 BirdNET 的完整物种列表与 eBird 报告的该区域内观察到的物种进行交集处理，可减少渲染的物种数量。
需要注意，Gemini 生成的图像在解剖结构上有不少错误，仓库中是经过审核的图像集，去除了多余的翅膀、分离的脚和训练图像水印。当前打包的图像集审核中，栖息姿态约有 3% 的解剖缺陷，飞行姿态约有 5%，飞行姿态更难处理。
每个物种附带二进制 alpha 遮罩，完整的遮罩注册表位于 [`avian/frontend/masks.json`]，用于编码鸟类的轮廓。前端用这些遮罩实现图块打包和悬停点击测试。
打包算法采用从中心向外的螺旋方式，图块按面积降序排序，成本函数在水平方向有偏向。图块大小设置较棘手，解决方法是根据视口面积预算进行归一化，确保在任何屏幕尺寸下生成合理布局。初始打包后，若图块超出屏幕范围，会缩小 7% 重新布局，最多循环 10 次。
~ 实时展示：前端功能与体验
前端每 30 秒轮询一次最近检测结果的端点，有新物种进入当前时间窗口时，会在下一次刷新时加入布局，前端进行完整的重新打包。时间窗口选择器会重新获取数据并原地重新渲染，过程流畅。
点击拼贴中的图块或图谱视图中的卡片会打开详细模态框，调用维基百科的摘要接口获取物种描述，提供栖息和飞行两种姿态的图片。录音列表拉取 BirdNET - Pi 存档的该物种最近的 mp3 文件，每个录音与对应的频谱图一起显示，底部有维基百科和 eBird 的链接供外部参考。
项目总结与订阅
这是一个简单的项目，能让用户轻松跟踪身边飞过的小鸟。用户可输入电子邮件地址，接收偶尔的更新。