一、项目整体概述

本项目围绕“牧场产犊事件智能监控”核心目标，整合萤石云摄像头定时截图与火山引擎多模态AI识别两大核心能力，构建了从“硬件视频流采集→AI智能识别→结果持久化存储→审计日志记录”的完整解决方案。项目采用Python开发，覆盖设备管理、定时任务、API对接、异常处理、数据存储等全环节，最终实现产犊事件的自动化识别、记录与追溯，有效降低人工监控成本，提升牧场管理数字化水平。

二、项目整体架构与核心流程

（一） 项目整体架构

1、项目目录结构

2.各文件功能详细说明

（1）配置文件目录 (config/) config/ init .py

（需要改变截图目录、提示词等，直接在config.py中更改后重新运行main.py即可）

• 功能 ：标记config为Python包

• 内容 ：空文件或包含包版本信息 config/config.py

• 功能 ：存储所有项目配置信息

• 核心配置项 ：

  • EZVIZ_CONFIG ：萤石云配置

    • ak ：AppKey

    • sk ：Secret

    • channel_no ：通道号

    • access_token ：访问令牌

    • devices ：设备列表（包含serial和name）

  • VOLCANO_CONFIG ：火山引擎配置

    • api_key ：API密钥

    • model ：模型名称

    • api_url ：API地址

  • PROJECT_CONFIG ：项目通用配置

    • save_dir ：截图保存目录

    • interval_minutes ：截图间隔

    • calving_prompt ：识别提示词

    • audit_log_file ：审计日志文件名 config/logging.py

• 功能 ：配置日志系统

• 核心功能 ：

  • 设置日志级别

  • 配置日志格式

  • 定义日志输出方式（控制台+文件）

  • 提供 get_logger 函数供其他模块使用

（2）源代码目录 (src/) src/ezviz/camera.py

• 功能 ：萤石云摄像头操作

• 核心功能 ：

  • 初始化摄像头连接

  • 使用API调用获取截图

  • 使用ezopen协议获取截图

  • 生成模拟截图（设备离线时）

  • 处理截图异常和错误 src/volcano/api.py

• 功能 ：火山引擎API对接

• 核心功能 ：

  • 初始化API客户端

  • 将图片编码为Base64

  • 构建API请求体

  • 调用豆包多模态API

  • 解析API响应

  • 处理识别结果 src/audit/logger.py

• 功能 ：审计日志记录

• 核心功能 ：

  • 初始化日志记录器

  • 记录产犊事件

  • 生成标准化审计日志

  • 持久化存储日志 src/utils/excel_writer.py

• 功能 ：Excel文件操作

• 核心功能 ：

  • 初始化Excel文件

  • 创建工作表

  • 写入识别结果

  • 保存Excel文件

  • 处理文件不存在的情况

（3）脚本文件 main.py

• 功能 ：主程序入口

• 核心功能 ：

  • 初始化监控系统

  • 管理多个设备

  • 调度定时任务

  • 处理截图和识别

  • 写入Excel和审计日志 test_volcano_ai.py

• 功能 ：AI识别测试

• 核心功能 ：

  • 测试指定目录下的图片

  • 调用火山引擎API

  • 显示识别结果

  • 生成测试报告 test_excel_write.py

• 功能 ：Excel写入测试

• 核心功能 ：

  • 测试识别结果写入Excel

  • 验证Excel文件更新

  • 显示测试结果 check_devices.py

• 功能 ：设备状态检测

• 核心功能 ：

  • 检测设备在线状态

  • 验证设备权限

  • 显示设备问题

  • 生成检测报告

3.项目结构搭建步骤

1. 初始化项目目录

• 创建项目根目录 Project_JieTu

• 在根目录中创建 config 和 src 目录

• 在 src 中创建各个功能模块目录

2. 创建配置文件

• 创建 config/config.py ，定义所有配置项

• 创建 config/logging.py ，配置日志系统

• 创建相应的 init.py 文件

3. 开发核心模块

• 摄像头模块 ：实现萤石云API调用和截图功能

• AI识别模块 ：实现火山引擎API对接和图片识别

• Excel模块 ：实现识别结果的Excel文件写入

• 审计模块 ：实现识别事件的标准化日志记录

4. 开发测试工具

• 创建AI识别测试脚本，验证识别功能

• 创建Excel写入测试脚本，验证数据存储

• 创建设备状态检测工具，检测设备问题

5. 开发主程序

• 实现多设备管理

• 实现定时任务调度

• 实现结果处理和存储

• 实现异常处理和错误恢复

（二） 核心业务流程（可视化）

三、核心模块开发经验（含API/工具类细节问题）

1. 萤石云摄像头模块（截图+设备管理）

核心能力	实现要点	踩坑与解决（含琐碎问题）
多API对接	支持最新API、LAPP API双路径调用，提高截图成功率	1. 问题：API路径返回404；解决：切换为/api/lapp/v2/live/address/get正确路径 2. 问题：curl命令格式错误（换行/引号）；解决：合并参数到单引号内，删除多余\n
定时任务	使用schedule库实现后台线程定时执行，避免主线程阻塞	问题：任务间隔不合理导致API限流；解决：按设备数动态调整间隔
异常降级	设备离线/无权限时生成模拟截图，保证流程不中断	1. 问题：设备不在线返回code:10012；解决：添加设备在线状态前置检测 2. 问题：模拟截图无业务信息；解决：增强模拟截图，添加设备/时间戳
设备状态检测 ✩✩✩	前置检测设备在线状态、accessToken有效性	1. 问题：accessToken无效（code:10002）；解决：重新生成token并核对绑定关系 2. 问题：deviceSerial拼写错误（seraial→serial）；解决：全局搜索修正键名
路径与命令执行	终端执行脚本时路径切换与命令调用	1. 问题：PowerShell找不到脚本；解决：用cd 绝对路径切换到项目目录 2. 问题：python命令未识别；解决：验证Python环境变量配置

2、萤石云调取视频流失败情况处理步骤：

-  1、系统如何处理失败情况

当添加多个设备时，系统会：

（1）逐一处理每个设备 ：

        ①系统会按顺序处理每个设备，一个设备失败不会影响其他设备

（2）详细的失败原因记录 ：     

        ① Access Token异常：提示"accessToken过期或参数异常"
        ② 设备序列号异常：提示"设备序列号错误"
        ③ 设备授权问题：提示"设备未授权给当前账号"
        ④ 设备连接状态：提示"设备已离线"
        ⑤ 通道号异常：提示"通道号错误"
        ⑥ 网络连接问题：显示具体网络错误信息

（3）日志记录 ：
        ① 所有失败原因都会详细记录到系统日志中
        ② 您可以通过查看控制台输出了解具体失败原因

（4）降级处理 ：
        ① 如果无法获取真实摄像头画面，系统会为该设备生成模拟截图
        ② 模拟截图会包含设备信息，方便您识别是哪个设备的问题

-  2、验证步骤

（1）添加设备后 ：

        ① 运行 python main.py
        ② 观察控制台输出，确认所有设备都被正确识别

（2）检查设备状态 ：
        ① 系统启动时会显示监控设备数量和每个设备的信息
        ② 处理每个设备时会显示详细的操作过程

（3）查看截图结果 ：

        ①成功的设备会生成 {serial}_{channel}_{timestamp}_api.jpg 格式的文件
        ②失败的设备会生成调试文件和模拟截图

-  3、注意事项

（1）确保设备在线 ：        

        ① 只有在线的设备才能获取真实截图

（2）设备授权 ：

        ② 确保所有设备都已授权给当前的Access Token；
        ③ 如果某些设备未授权，系统会明确显示错误信息

（3）通道号设置 ：

        ① 注意不同设备可能使用不同的通道号
        ② 如果默认通道号2不工作，可以尝试修改为1

        ③2026年1月22日补充：当多个摄像头同时抓视频流，但仅有一张真实摄像头画面被正确截图时，请检查序列号是否填写错误：

        请明确本python项目中配置到的序列号为 NVR设备在萤石云的注册序列号，序列号与通道的关系是一对多，也就是一个序列号可以有多个通道，从而展示多个角度或者位置的监控情况。

2. 火山引擎AI识别模块（多模态API对接）

核心能力	实现要点	踩坑与解决（含琐碎问题）
API鉴权与角色	实现HMAC-SHA256签名，包含X-Volc-Ak/Timestamp/Nonce等请求头	1. 问题：RoleAlreadyExists报错；解决：复用已存在的ServiceRoleForArk角色，无需重复创建 2. 问题：AK/SK填写错误；解决：从方舟控制台复制，避免手动输入漏字符
图片编码与请求格式	本地图片转Base64编码，适配API的image_url格式要求	1. 问题：图片类型传错（image→image_url）；解决：严格按文档调整请求体参数 2. 问题：Base64编码失败；解决：检查图片路径是否存在、文件是否损坏
模型选择与调用	动态适配模型ID，支持多版本切换	1. 问题：模型名称错误（Doubao-Seed-1.8→doubao-seed-1-8-251228）；解决：核对官方模型列表 2. 问题：混淆“火山方舟”与“豆包大模型”；解决：明确“火山方舟是平台，豆包是模型”，调用时指定正确模型ID 以下是API 接入方法（点击即可跳转网页）：
网络与连接问题	处理API调用时的网络异常	1. 问题：DNS解析失败（getaddrinfo failed）；解决：切换公共DNS（[223.5.5.5](223.5.5.5)）或手机热点 2. 问题：443端口被拦截；解决：找网管开放maas-api.ml-platform-cn-beijing.volcengine.com:443
识别结果异常	优化提示词与识别逻辑	1. 问题：识别结果非“是/否”；解决：提示词中强制要求仅返回“是”或“否” 2. 问题：误识别率高；解决：调整提示词（“白大褂人员+新生小牛”替代“母牛+小牛接触”）

3. 数据存储与审计模块（Excel+日志）

核心能力	实现要点	踩坑与解决（含细节问题）
Excel写入	追加式写入，按设备/时间维度组织数据	1. 问题：Excel文件不更新；解决：单独编写测试脚本验证写入逻辑，检查文件是否被占用 2. 问题：中文路径乱码；解决：使用UTF-8编码处理路径
审计日志	标准化JSONLines格式，追加写入日志文件	问题：日志文件权限不足；解决：检查保存目录是否有写入权限，使用绝对路径
数据持久化	截图文件按“设备-日期”分目录存储	1. 问题：文件覆盖；解决：文件名包含时间戳（如20260120_192000_GK1040085.jpg） 2. 问题：截图保存失败；解决：提前创建保存目录，避免路径不存在

四、通用开发与调试经验（含高频琐碎问题）

1. 配置管理类问题

• 问题1：配置项键名不一致（如config中是device_serial，代码中写device_seraial）；解决：统一配置键名，添加配置校验函数

• 问题2：绝对路径使用反斜杠（\）导致转义错误；解决：使用正斜杠（/）或原始字符串（r"路径"）

• 问题3：多设备配置时列表格式错误；解决：按[{"device_serial":"xxx","access_token":"xxx"},...]规范配置，启动时校验格式

2. 脚本运行类问题

• 问题1：PowerShell中执行脚本提示“找不到模块”；解决：先安装依赖（pip install requests schedule pillow）

• 问题2：终端切换路径时中文目录识别失败；解决：复制目录绝对路径，用cd "带空格的中文路径"格式

• 问题3：脚本运行时被杀毒软件拦截；解决：添加脚本到杀毒软件信任列表，关闭实时防护后测试

3. API调用通用问题

• 问题1：API返回“参数缺失”；解决：对照文档检查必填参数，确保无遗漏（如萤石云的channelNo=1）

• 问题2：请求频率过高导致限流；解决：添加请求间隔（如每设备每次调用间隔2秒），避免批量并发

• 问题3：响应结果解析失败；解决：先打印原始响应，按实际返回格式调整解析逻辑（如JSON字段大小写差异）

4. 工具使用类问题

• 问题1：PyCharm中Terminal不是PowerShell；解决：点击Terminal右上角下拉箭头，选择“PowerShell”

• 问题2：ffmpeg截图失败；解决：检查ffmpeg是否安装、环境变量是否配置，或改用API直接截图

• 问题3：测试脚本单独运行正常，整合后失败；解决：检查模块导入路径，使用相对导入（from src.volcano.api import xxx）

五、项目优化与未来展望

1. 已落地优化点

• 性能：多线程处理多设备截图，避免串行执行效率低；

• 稳定性：添加API调用重试机制（3次重试+指数退避）；

• 可维护性：模块化设计，各模块职责单一，便于单独修改/测试；

• 排错效率：新增“问题排查指南”文档，汇总高频琐碎问题及解决方案。

2. 未来扩展方向

• 功能扩展：

  • 设备监控：添加摄像头离线告警（短信/企业微信）；

  • 数据分析：产犊事件时间分布、设备识别准确率统计；

  • 可视化：开发Web界面，实时查看截图/识别结果/日志；

• 技术优化：

  • 异步化：使用aiohttp替代requests，实现异步API调用；

  • 容器化：Docker打包，简化环境配置与部署；

  • 智能化：基于历史数据优化识别提示词，提升准确率；

• 集成能力：

  • 与牧场现有管理系统对接，实现数据互通；

  • 支持更多摄像头品牌/AI模型扩展。

六、核心经验总结

1. 把一个困难问题拆解成多个简单问题：例如该需求可以拆解成 ①截图功能 ②AI识别功能 ③合并实现；

     这样可以确保错误独立分析，便于定位问题所在

2. API对接三原则：先看文档→再用curl测试→最后写代码，避免直接集成导致定位问题难；

3. 细节问题应对：建立“问题台账”，记录“错误现象→原因→解决方案”，重复问题直接复用；

4. 配置与代码一致性：核心配置（如设备序列号、模型ID）单独存放，避免硬编码，修改后全局搜索验证；

5. 环境与工具适配：提前确认Python版本、依赖包版本、终端类型，避免“本地运行正常，部署失败”；

6. 场景优先于技术：AI识别、功能逻辑需贴合牧场实际场景，而非仅依赖技术文档，多与现场人员沟通调整。

        本项目不仅实现了“截图+识别+记录”的功能闭环，更通过汇总高频细节问题，形成了可复用的“问题排查手册”，为后续类似项目开发提供了高效的避坑指南，同时沉淀了“多平台API整合”“异常降级”“模块化开发”等核心技术经验，为农业养殖场景的智能化改造提供了可落地的参考方案。