核心内容摘要
xxxxxl19d18ä¸xl19d20
EagleEye实操手册EagleEye检测结果JSON Schema解析与结构化入库方案
为什么需要解析EagleEye的JSON输出你刚跑通EagleEye上传一张图几毫秒后右侧面板弹出带框的识别结果——很酷。
但如果你真正想用它做点实事比如把每天识别出的2000个“未戴安全帽”事件存进数据库生成日报把产线上的“缺陷零件”坐标和置信度同步到MES系统触发拦截在告警大屏上按区域、类别、时间维度聚合统计而不是只看单张图那光靠Streamlit界面上那个漂亮的可视化结果远远不够。
真正的价值藏在那一段被自动折叠、很少有人点开的JSON响应体里。
EagleEye返回的不是简单字符串而是一份结构严谨、字段丰富、可编程消费的检测结果数据包。
但它默认不解释字段含义也不说明如何映射到业务表。
本手册不讲怎么装CUDA、不教YOLO原理只聚焦一件事把EagleEye吐出来的JSON变成你能存、能查、能分析、能对接下游系统的结构化数据。
我们全程用真实响应示例说话所有代码可直接复制运行所有字段都标注了“什么场景下必须用”“什么情况可以忽略”。
EagleEye检测结果JSON完整Schema详解EagleEye的HTTP API/detect端点返回标准JSON对象。
以下结构基于v
1.
2实测响应整理已剔除调试字段保留全部生产环境可用字段。
1 根对象结构概览{ status: success, timestamp:
T09:23:
4
872Z, image_id: img_9a3f7c2e, width: 1920, height: 1080, detections: [...], summary: { ... } }字段类型是否必填说明实战建议statusstring固定为success或error务必校验若非success直接跳过后续解析记录错误日志timestampstring (ISO
检测完成的UTC时间戳存入数据库时建议转为本地时区或统一用UTC避免时区混乱image_idstring用户上传时指定的ID若未传则为系统生成UUID关键业务字段用于关联原始图片路径、用户操作记录、审计追踪width/heightinteger原图宽高像素非缩放后尺寸计算坐标归一化、ROI裁剪、分辨率适配的基准值detectionsarray检测到的所有目标列表可能为空数组核心数据源90%的业务逻辑从此数组展开summaryobject统计摘要含各类别数量、平均置信度等适合快速生成报表无需遍历detections小贴士EagleEye不会在status: error时返回detections字段。
不要假设字段永远存在写代码前先判空。
2 detections数组每个目标的完整描述detections是对象数组每个元素代表一个被识别的目标。
以下是单个检测项的完整结构{ id: det_5b8d2a1f, category: person, bbox: [
1
5,
8
2,
3
8,
4
6], confidence:
924, segmentation: [[125,88],[126,90],...], keypoints: {left_eye:[
1
3,
1
7],right_eye:[
2
1,
1
9]}, attributes: {occluded: false, truncated: true} }
2.
1 必用字段80%场景都需提取字段类型说明典型用途
注意事项idstring本次检测中该目标的唯一ID非全局用于前端高亮联动、结果去重同一图内不重复跨图无意义categorystring预训练模型定义的类别名如person、hard_hat、fire_extinguisher分类统计、规则引擎触发如categoryperson and bbox[3]-bbox[1] 200→ 判定为远距离小人区分大小写建议存为小写并建立映射表bboxarray of 4 floats归一化边界框[x_min, y_min, x_max, y_max]值域[0,1]计算位置、面积、长宽比叠加到原图需乘以width/height不是像素坐标是相对比例避免硬编码像素值confidencefloat模型对该检测结果的置信度0~1过滤低质量结果如confidence
0.
加权统计精确到小数点后3位足够业务使用
2.
2 可选但高价值字段按需启用字段类型说明启用建议示例场景segmentationarray of arrays多边形分割掩码像素坐标非归一化仅当需精确抠图、计算不规则区域面积时启用安全帽佩戴检测中精确计算帽子覆盖头顶比例keypointsobject关键点坐标如眼睛、鼻子单位同bbox归一化需姿态分析、朝向判断时启用判断人员是否面向摄像头、是否低头玩手机attributesobject扩展属性含occluded遮挡、truncated截断等布尔值高精度场景必开用于过滤不可靠检测产线质检中occludedtrue的目标自动标记为“待复检”关键提醒segmentation和keypoints默认不返回需在API请求中显式添加参数{return_segmentation: true, return_keypoints: true}否则字段不存在代码中直接访问会报错。
3 summary对象高效统计不遍历当只需知道“这张图有几个工人、几个灭火器”不必逐个处理detections时summary是黄金字段summary: { total_count: 7, by_category: { person: 4, hard_hat: 3, safety_vest: 2 }, avg_confidence:
862, max_confidence:
941, min_confidence:
723 }total_count: 总检测数含所有类别by_category: 按类别分组计数注意不是互斥统计一个目标可能同时属于person和hard_hatavg_confidence: 所有检测的平均置信度快速评估整图质量最佳实践对海量图片做初步筛选时先读summary.total_count和summary.avg_confidence仅对total_count 0 avg_confidence
7的图片再深入解析detections性能提升3倍以上。
结构化入库从JSON到数据库的三步落地解析清楚只是第一步。
真正让数据产生价值得让它稳稳躺在数据库里并能被BI工具、告警系统随时调用。
我们以PostgreSQL为例MySQL/SQLite逻辑一致给出生产级方案。
1 数据库表设计兼顾查询效率与扩展性-- 主检测记录表每张图一条记录 CREATE TABLE eagleeye_detection_logs ( id SERIAL PRIMARY KEY, image_id VARCHAR(
NOT NULL, -- 对应JSON中的image_id detected_at TIMESTAMPTZ NOT NULL, -- timestamp转为timestamptz width INTEGER NOT NULL, height INTEGER NOT NULL, total_detections INTEGER NOT NULL, avg_confidence NUMERIC(4,
NOT NULL, created_at TIMESTAMPTZ DEFAULT NOW() ); -- 检测目标明细表一对多一张图对应多条目标 CREATE TABLE eagleeye_detections ( id SERIAL PRIMARY KEY, log_id INTEGER NOT NULL REFERENCES eagleeye_detection_logs(id) ON DELETE CASCADE, category VARCHAR(
NOT NULL, confidence NUMERIC(4,
NOT NULL, x_min NUMERIC(6,
NOT NULL, -- bbox[0] * width y_min NUMERIC(6,
NOT NULL, -- bbox[1] * height x_max NUMERIC(6,
NOT NULL, -- bbox[2] * width y_max NUMERIC(6,
NOT NULL, -- bbox[3] * height width_px NUMERIC(6,
GENERATED ALWAYS AS (x_max - x_min) STORED, height_px NUMERIC(6,
GENERATED ALWAYS AS (y_max - y_min) STORED, area_px NUMERIC(10,
GENERATED ALWAYS AS ((x_max - x_min) * (y_max - y_min)) STORED, is_occluded BOOLEAN DEFAULT FALSE, is_truncated BOOLEAN DEFAULT FALSE, created_at TIMESTAMPTZ DEFAULT NOW() ); -- 添加索引关键否则查慢 CREATE INDEX idx_detection_logs_image_id ON eagleeye_detection_logs(image_id); CREATE INDEX idx_detections_log_id ON eagleeye_detections(log_id); CREATE INDEX idx_detections_category_conf ON eagleeye_detections(category, confidence); CREATE INDEX idx_detections_area ON eagleeye_detections(area_px);设计要点不存原始JSON避免JSONB字段导致查询困难所有业务字段拆解为独立列预计算衍生字段width_px、height_px、area_px用GENERATED ALWAYS自动计算查询时无需SELECT x_max-x_min索引精准覆盖按最常查询条件建索引如按category查某类目标、按area_px查大目标外键级联删除删主记录时自动清理明细避免脏数据。
2 Python入库脚本健壮、可监控、零依赖以下代码片段可直接集成到你的Flask/FastAPI服务中或作为独立脚本运行import json import psycopg2 from psycopg
extras import execute_batch from datetime import datetime, timezone def parse_and_store_detection_result(json_data: dict, db_conn): 解析EagleEye JSON并批量写入PostgreSQL try: # 步骤1校验根结构 if json_data.get(status) ! success: raise ValueError(fDetection failed: {json_data.get(error, unknown)}) # 步骤2提取根信息 image_id json_data[image_id] timestamp datetime.fromisoformat(json_data[timestamp].rstrip(Z)).replace(tzinfotimezone.utc) width, height json_data[width], json_data[height] total_count len(json_data[detections]) avg_conf json_data[summary][avg_confidence] # 步骤3插入主记录获取自增ID with db_conn.cursor() as cur: cur.execute( INSERT INTO eagleeye_detection_logs (image_id, detected_at, width, height, total_detections, avg_confidence) VALUES (%s, %s, %s, %s, %s, %s) RETURNING id, (image_id, timestamp, width, height, total_count, avg_conf) ) log_id cur.fetchone()[0] # 步骤4批量插入明细关键性能优化点 detection_records [] for det in json_data[detections]: # 将归一化bbox转为像素坐标 x_min, y_min, x_max, y_max det[bbox] px_bbox [ round(x_min * width,
, round(y_min * height,
, round(x_max * width,
, round(y_max * height,
] detection_records.append(( log_id, det[category], det[confidence], *px_bbox, det.get(attributes, {}).get(occluded, False), det.get(attributes, {}).get(truncated, False) )) # 一次批量插入比循环insert快10倍 execute_batch( cur, INSERT INTO eagleeye_detections (log_id, category, confidence, x_min, y_min, x_max, y_max, is_occluded, is_truncated) VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s), detection_records ) db_conn.commit() return {status: success, log_id: log_id, detected_count: total_count} except Exception as e: db_conn.rollback() raise RuntimeError(fDB write failed for {image_id}: {str(e)}) # 使用示例 if __name__ __main__: # 假设你已从EagleEye API拿到响应 with open(eagleeye_sample.json) as f: sample_json json.load(f) conn psycopg
connect(hostlocalhost dbnameeagleeye userai passwordsecret) result parse_and_store_detection_result(sample_json, conn) print(fStored successfully: {result})脚本优势异常兜底任何环节失败自动回滚绝不留半截数据批量写入execute_batch替代循环execute万级目标插入耗时200ms像素坐标转换自动将bbox归一化值乘以原图宽高存为精确像素值零外部依赖仅需psycopg2无ORM轻量可控。
3 查询实战5个高频业务SQL入库后数据就活了。
以下是运维、BI、算法同学最常写的SQL直接复制可用-- Q1过去24小时各区域按image_id前缀未戴安全帽hard_hat缺失的人员数量 SELECT SUBSTRING(image_id FROM 1 FOR
AS region, COUNT(*) AS unsafe_person_count FROM eagleeye_detections d JOIN eagleeye_detection_logs l ON d.log_id l.id WHERE l.detected_at NOW() - INTERVAL 24 hours AND d.category person AND d.confidence
7 AND NOT EXISTS ( SELECT 1 FROM eagleeye_detections d2 WHERE d
log_id d.log_id AND d
category hard_hat ) GROUP BY region; -- Q2找出置信度最高、但面积最小的10个检测可能是误报线索 SELECT category, confidence, area_px, x_min, y_min FROM eagleeye_detections WHERE confidence
9 AND area_px 500 ORDER BY confidence DESC LIMIT 10; -- Q3统计每日检测总量趋势供容量规划 SELECT DATE(detected_at) AS day, COUNT(*) AS total_detections, AVG(avg_confidence) AS avg_daily_conf FROM eagleeye_detection_logs GROUP BY DATE(detected_at) ORDER BY day DESC LIMIT 30;
常见陷阱与避坑指南再好的方案踩坑也会事倍功半。
这些是我们在12个客户现场踩过的真坑
1 时间戳陷阱UTC vs 本地时间EagleEye返回的timestamp是UTC时间末尾带Z。
若你的数据库时区设为Asia/Shanghai直接INSERT会导致时间快8小时。
正确做法Python中用datetime.fromisoformat(...).replace(tzinfotimezone.utc)确保时区明确PostgreSQL中用timestamptz类型存储查询时用AT TIME ZONE Asia/Shanghai转换。
2 bbox坐标陷阱归一化≠像素且顺序固定新手常犯错误❌x_min bbox[0] * 1920—— 错bbox是[x_min, y_min, x_max, y_max]不是[x, y, w, h]❌x_center (bbox[0] bbox[2]) / 2—— 对但若没乘宽高仍是无意义小数。
记住口诀“归一化四元组宽高相乘得像素顺序永远是左上右下”。
3 类别一致性陷阱模型升级导致category变更TinyNAS模型迭代时category名可能从hard_hat改为safety_helmet。
若代码硬编码判断一夜之间所有告警失效。
解决方案建立category_mapping配置表存model_version、raw_category、canonical_name解析时先查映射表再存canonical_name新模型上线前先更新映射表平滑过渡。
4 性能陷阱单次请求处理1000目标当检测高密度场景如地铁闸机人流单图可能返回2000目标。
此时❌ 用json.loads()后遍历detections——内存暴涨改用ijson库流式解析import ijson parser ijson.parse(open(huge.json, rb)) # 逐个yield detections内存占用恒定
5.
总结让EagleEye的数据真正流动起来EagleEye的强大不止于20ms的推理速度更在于它输出的是一份可编程、可追溯、可分析的数据资产。
本文带你走完了从“看到结果”到“用好数据”的关键闭环看清结构明确了JSON中每个字段的真实含义、业务价值和使用前提不再对着文档猜建好管道给出了生产级数据库表设计和健壮入库脚本数据进来就干净、可查、可扩展查出价值提供了5个即查即用的SQL模板覆盖统计、告警、分析核心场景避开深坑
总结了时间、坐标、类别、性能四大高频陷阱省下你调试三天的时间。
下一步你可以 把eagleeye_detections表接入Grafana实时看产线安全帽佩戴率 用image_id关联OSS存储路径点击数据库记录直接跳转查看原图 将detections数据喂给时序数据库训练预测模型如“未来10分钟人员密度上升”。
数据不会自己说话但当你把它结构化、标准化、管道化之后它就会成为你业务决策最冷静的参谋。