EagleEye快速上手：使用curl命令行调用EagleEye API完成首次图像检测-开发者社区

EagleEye快速上手：使用curl命令行调用EagleEye API完成首次图像检测

1. 为什么你需要一个“不用点鼠标”的检测方式？

你刚部署好EagleEye，浏览器里看着Streamlit界面流畅运行，框也画得准，置信度也标得清——但心里可能有个小疑问：如果我想批量处理100张监控截图、集成进自动化脚本、或者嵌入到CI/CD流程里，难道每次都要手动上传图片再截图保存结果？

答案是否定的。

EagleEye从设计之初就不是只给“点一点”用的玩具。它是一个真正面向工程落地的视觉API服务。而最直接、最轻量、最可控的调用方式，就是用curl发一个HTTP请求——不需要安装SDK，不依赖Python环境，甚至在Linux服务器、Mac终端、Windows PowerShell里都能一键执行。

这篇文章不讲模型原理，不跑训练代码，也不配前端界面。我们就做一件事：用一条curl命令，把一张本地图片发给EagleEye，拿到结构化检测结果，全程不超过60秒。
你不需要会写API文档，不需要查HTTP状态码含义，更不需要调试token——所有步骤都已验证通过，复制粘贴就能跑通。

2. 准备工作：3个确认，5秒搞定

在敲下第一个curl之前，请花10秒确认以下三点。这比反复重试失败要快得多：

2.1 确认服务正在运行

EagleEye默认启动后监听http://localhost:8501（Streamlit前端）和http://localhost:8000（API服务端口）。
请先打开浏览器访问http://localhost:8000/health—— 如果看到{"status":"healthy"}，说明API服务已就绪。
如果返回连接被拒绝（Connection refused），请检查启动日志，确认是否指定了--api-port 8000参数（默认即为8000）。

2.2 确认图片已就位

准备一张本地图片，比如test_car.jpg，放在当前目录下。支持格式：.jpg、.jpeg、.png（注意：不支持WebP、BMP等）。
建议选一张含1–3个清晰目标的图（如一辆车、一只猫、一个背包），便于快速验证结果是否合理。

2.3 确认curl可用

在终端输入：

curl --version

只要显示版本号（如curl 8.5.0），就说明环境就绪。Windows用户若未安装curl，可直接用Invoke-WebRequest（PowerShell）替代，文末会提供对应写法。

小提醒：EagleEye API默认无需认证，不强制Token，不走OAuth。这是为本地化部署场景专门设计的——你的内网服务，不该被登录墙挡住。

3. 第一次curl：发送图片并获取JSON结果

现在，执行这条命令（请将test_car.jpg替换为你自己的文件名）：

curl -X POST "http://localhost:8000/detect" \ -H "Content-Type: multipart/form-data" \ -F "image=@test_car.jpg" \ -o result.json

成功时，终端不会报错，同时当前目录下会生成一个result.json文件。
❌ 失败时常见原因及修复：

No such file or directory→ 检查文件名拼写、路径是否正确（@符号前不能有空格）
Failed to connect→ 服务没起来，或端口被占用（改用http://127.0.0.1:8000/detect试试）
415 Unsupported Media Type→-H "Content-Type"不要手动设为multipart/form-data，curl会自动添加，删掉该行即可

为什么不用-H "Content-Type"？
因为curl用-F发送表单数据时，会自动生成带boundary的正确header。手动指定反而会破坏协议，导致服务端无法解析——这是新手最常踩的坑。

4. 看懂返回的JSON：不只是“检测到了”，而是“检测得有多准”

打开result.json，你会看到类似这样的内容（已简化排版）：

{ "success": true, "detections": [ { "label": "car", "confidence": 0.924, "bbox": [128.3, 215.7, 482.1, 398.4] }, { "label": "person", "confidence": 0.871, "bbox": [312.5, 189.2, 367.8, 321.6] } ], "inference_time_ms": 18.3 }

我们逐字段解释，全是大白话：

"success": true→ 表示这次请求成功处理，不是网络错误也不是内部异常
"detections"数组 → 每一项代表一个被识别出来的目标
"label"→ 模型认出的类别名，比如"car"、"dog"、"bottle"（EagleEye预置80类COCO标签）
"confidence"→ 置信度，0.0–1.0之间。0.924 = 模型有92.4%把握认为这个框里是车
"bbox"→ 检测框坐标，格式是[x_min, y_min, x_max, y_max]（单位：像素），左上角为原点
"inference_time_ms"→ 真实推理耗时，单位毫秒。看到18.3，你就知道它确实做到了“毫秒级”

小技巧：用jq工具可以快速提取关键信息。例如只看所有标签和置信度：
jq '.detections[] | "\(.label) \(.confidence)"' result.json # 输出： # "car 0.924" # "person 0.871"

5. 进阶用法：用参数控制检测行为，不靠滑块也能调灵敏度

你在Streamlit界面上拖动“Sensitivity”滑块，其实就是在调整一个叫confidence_threshold的参数。这个参数同样可以通过API传入——完全不用打开浏览器。

试试这条命令，把阈值设为0.5（只返回置信度≥50%的结果）：

curl -X POST "http://localhost:8000/detect?confidence_threshold=0.5" \ -F "image=@test_car.jpg" \ -o result_high_recall.json

再试试设为0.85（只保留高置信度结果，大幅减少误报）：

curl -X POST "http://localhost:8000/detect?confidence_threshold=0.85" \ -F "image=@test_car.jpg" \ -o result_high_precision.json

你会发现：

confidence_threshold=0.5时，detections数量可能变多（比如多检出一个模糊的自行车轮）
confidence_threshold=0.85时，detections可能只剩1个（只留最确定的那个车）

这正是EagleEye“动态阈值过滤”能力的命令行体现——你可以把它写进Shell脚本，根据业务场景自动切换策略。

6. 批量处理实战：用for循环检测10张图

假设你有一个images/文件夹，里面放了10张.jpg图片。想一次性全检测，并把每张的结果存成独立JSON，只需一段Shell：

mkdir -p results for img in images/*.jpg; do basename=$(basename "$img" .jpg) curl -s -X POST "http://localhost:8000/detect" \ -F "image=@$img" \ -o "results/${basename}.json" echo " Done: $basename" done

运行后，results/目录下会出现001.json、002.json……每个都包含对应图片的检测结果。
你还可以加一行jq -r '.detections[].label' "results/${basename}.json"把所有检测到的类别打印出来，做成简易统计报表。

注意：EagleEye默认支持并发请求，但RTX 4090显存有限。如需高并发（>5路），建议在启动时加--max-concurrent 3参数限制并发数，避免OOM。

7. Windows用户友好方案：PowerShell一行等效命令

如果你在Windows上工作，没有安装curl，也没关系。PowerShell原生命令Invoke-WebRequest完全胜任：

$filePath = ".\test_car.jpg" $body = @{ image = Get-Item $filePath } $response = Invoke-WebRequest -Uri "http://localhost:8000/detect" -Method Post -Form $body $response.Content | Out-File -FilePath "result.json" -Encoding UTF8

保存为detect.ps1，右键以PowerShell运行即可。效果与curl完全一致。

8. 常见问题速查：5个高频问题，30秒定位原因

问题现象	最可能原因	一句话解决
`curl: (7) Failed to connect`	EagleEye API服务未启动，或端口不对	运行`lsof -i :8000`（Mac/Linux）或`netstat -ano \| findstr :8000`（Win）确认进程是否存在
返回空JSON或`{"detail":"Not Found"}`	访问了前端地址`:8501`，而非API地址`:8000`	把URL中的`8501`改成`8000`
`400 Bad Request`+`"image": ["Field required"]`	`-F "image=@xxx"`写成了`-F "image=xxx"`（漏了`@`）	`@`是关键，表示读取文件内容，不是传文件名字符串
结果中`detections`为空数组	图片中目标太小、太模糊，或类别不在支持列表内	换一张清晰图；或用`curl "http://localhost:8000/labels"`查看当前支持的所有标签
推理时间超过50ms	GPU未被正确调用，回落到CPU推理	检查启动日志是否有`Using CUDA`字样；确认NVIDIA驱动和CUDA版本匹配