鸟类访客项目从个人小项目到公开报告一开始项目发起者打算把“鸟类访客”项目当作个人项目觉得这只是花一下午完成的小项目发条推文记录就行。然而Twitter上的反响让他改变想法为想监测自家附近鸟类访客的人整理了这份简短报告。目前报告简洁明了是为尽快分享且这项工作是一系列与鸟类相关项目的一部分后续还会有相关内容。公寓鸟类“鸟类访客”分支及物料清单“鸟类访客”Avian Visitors是 [BirdNET - Pi] 的一个分支添加了花鸟绘风格的拼贴覆盖层。BirdNET - Pi 负责音频采集和物种识别用康奈尔大学的 [BirdNET] 声学分类器分析树莓派上 USB 麦克风采集的声音。可在 [bird.onethreenine.net] 查看运行效果。搭建鸟类追踪站所需材料如下1 个树莓派4B / 5 / Zero 2W价格约 $35 - 801 个微型 SD 卡≥32 GB价格约 $101 个 USB 领夹式麦克风价格 $16.951 个树莓派电源价格约 $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 的链接供外部参考。项目总结与订阅这是一个简单的项目能让用户轻松跟踪身边飞过的小鸟。用户可输入电子邮件地址接收偶尔的更新。