# YOLO12 API调用实战：curl+Python批量图像检测代码实例 ## 1. 引言：为什么选择YOLO12进行目标检测 目标检测是计算机视觉领域的核心任务之一，而YOLO系列一直是这个领域的标杆。YOLO12作为Ultralytics在2025年推出的最新版本，在保持实时推理速度的同时，显著提升了检测精度。 相比前代版本，YOLO12引入了注意力机制优化特征提取网络，提供n/s/m/l/x五种规格，参数量从370万到数千万不等，能够适配从边缘设备到高性能服务器的多样化硬件环境。其中nano版本在RTX 4090上能达到131 FPS的推理速度，延迟仅7.6毫秒每帧，完全满足实时处理需求。 本文将重点介绍如何通过API方式调用YOLO12模型，包括基础的curl命令测试和完整的Python批量处理代码，帮助开发者快速集成到自己的项目中。 ## 2. 环境准备与API服务启动 ### 2.1 部署YOLO12镜像 首先需要在云平台部署YOLO12镜像。选择`ins-yolo12-independent-v1`镜像，使用`insbase-cuda124-pt250-dual-v7`底座进行部署。部署完成后，实例状态变为"已启动"即可使用。 ### 2.2 验证服务状态 服务启动后提供两个访问端口： - **8000端口**：FastAPI接口，用于程序调用 - **7860端口**：Gradio可视化界面，用于手动测试 可以通过浏览器访问`http://<实例IP>:7860`来确认Web界面正常工作，或者使用以下命令测试API服务： ```bash curl -X GET "http://localhost:8000/health" ``` 正常情况应该返回`{"status":"healthy"}`。 ## 3. 基础API调用：curl命令实战 ### 3.1 单张图片检测 最基本的API调用方式是使用curl命令发送POST请求： ```bash curl -X POST "http://localhost:8000/predict" \ -H "accept: application/json" \ -F "file=@test_image.jpg" ``` 这个命令会返回JSON格式的检测结果，包含边界框坐标、置信度和类别信息。 ### 3.2 调整检测参数 可以通过附加参数调整检测行为： ```bash curl -X POST "http://localhost:8000/predict?confidence=0.5" \ -H "accept: application/json" \ -F "file=@test_image.jpg" ``` 其中`confidence`参数用于设置置信度阈值（范围0.1-1.0），值越高检测越严格。 ### 3.3 处理API响应 成功的API调用会返回类似这样的JSON响应： ```json { "predictions": [ { "class": "person", "confidence": 0.89, "bbox": [123, 45, 234, 167] }, { "class": "car", "confidence": 0.78, "bbox": [345, 89, 456, 123] } ], "image_size": [640, 480], "inference_time": 0.0076 } ``` 响应中包含每个检测到的目标类别、置信度、边界框坐标（x1,y1,x2,y2格式），以及推理时间等信息。 ## 4. Python批量处理代码实现 ### 4.1 安装必要依赖 首先确保安装了必要的Python库： ```bash pip install requests opencv-python pillow tqdm ``` ### 4.2 单张图片处理函数 ```python import requests import json import cv2 import os from PIL import Image import time def detect_single_image(image_path, api_url="http://localhost:8000/predict", confidence=0.25): """ 单张图片检测函数 Args: image_path: 图片文件路径 api_url: API地址 confidence: 置信度阈值 Returns: dict: 检测结果 """ try: with open(image_path, 'rb') as f: files = {'file': f} data = {'confidence': str(confidence)} response = requests.post(api_url, files=files, data=data) response.raise_for_status() return response.json() except Exception as e: print(f"处理图片 {image_path} 时出错: {str(e)}") return None ``` ### 4.3 批量图片处理类 ```python class YOLO12BatchProcessor: def __init__(self, api_url="http://localhost:8000/predict", output_dir="results"): self.api_url = api_url self.output_dir = output_dir os.makedirs(output_dir, exist_ok=True) def process_batch(self, image_folder, confidence=0.25, batch_size=10): """ 批量处理文件夹中的所有图片 Args: image_folder: 图片文件夹路径 confidence: 置信度阈值 batch_size: 批处理大小（控制并发请求数） """ # 获取所有图片文件 image_extensions = ['.jpg', '.jpeg', '.png', '.bmp'] image_files = [f for f in os.listdir(image_folder) if os.path.splitext(f)[1].lower() in image_extensions] print(f"找到 {len(image_files)} 张待处理图片") results = [] processed_count = 0 for i, image_file in enumerate(image_files): image_path = os.path.join(image_folder, image_file) # 调用检测API result = detect_single_image(image_path, self.api_url, confidence) if result: # 保存结果 result_filename = f"result_{os.path.splitext(image_file)[0]}.json" result_path = os.path.join(self.output_dir, result_filename) with open(result_path, 'w') as f: json.dump(result, f, indent=2) # 可视化结果（可选） self.visualize_result(image_path, result, image_file) results.append(result) processed_count += 1 print(f"已处理 {processed_count}/{len(image_files)}: {image_file}") # 添加短暂延迟，避免服务器过载 time.sleep(0.1) return results def visualize_result(self, image_path, result, output_filename): """ 可视化检测结果，绘制边界框并保存 Args: image_path: 原始图片路径 result: 检测结果 output_filename: 输出文件名 """ # 读取图片 image = cv2.imread(image_path) if image is None: return # 绘制检测框 for detection in result.get('predictions', []): bbox = detection['bbox'] class_name = detection['class'] confidence = detection['confidence'] # 绘制矩形框 cv2.rectangle(image, (bbox[0], bbox[1]), (bbox[2], bbox[3]), (0, 255, 0), 2) # 添加标签文本 label = f"{class_name}: {confidence:.2f}" cv2.putText(image, label, (bbox[0], bbox[1]-10), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0, 255, 0), 2) # 保存结果图片 output_path = os.path.join(self.output_dir, f"vis_{output_filename}") cv2.imwrite(output_path, image) ``` ### 4.4 使用示例 ```python # 创建处理器实例 processor = YOLO12BatchProcessor( api_url="http://localhost:8000/predict", output_dir="./detection_results" ) # 处理整个文件夹的图片 results = processor.process_batch( image_folder="./input_images", confidence=0.3, # 置信度阈值 batch_size=8 # 同时处理8张图片 ) print(f"批量处理完成，共处理 {len(results)} 张图片") ``` ## 5. 高级功能与性能优化 ### 5.1 多线程批量处理 对于大量图片，可以使用多线程提高处理速度： ```python import concurrent.futures from tqdm import tqdm def process_batch_parallel(image_folder, confidence=0.25, max_workers=4): """ 多线程批量处理 Args: image_folder: 图片文件夹路径 confidence: 置信度阈值 max_workers: 最大线程数 """ image_extensions = ['.jpg', '.jpeg', '.png', '.bmp'] image_files = [f for f in os.listdir(image_folder) if os.path.splitext(f)[1].lower() in image_extensions] results = [] with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor: # 创建任务列表 future_to_image = { executor.submit(detect_single_image, os.path.join(image_folder, img_file), confidence=confidence): img_file for img_file in image_files } # 使用tqdm显示进度条 for future in tqdm(concurrent.futures.as_completed(future_to_image), total=len(image_files), desc="处理进度"): image_file = future_to_image[future] try: result = future.result() if result: results.append((image_file, result)) except Exception as e: print(f"处理 {image_file} 时出错: {str(e)}") return results ``` ### 5.2 结果分析与统计 ```python def analyze_results(results): """ 分析检测结果统计信息 Args: results: 检测结果列表 """ class_counts = {} total_objects = 0 total_time = 0 for image_file, result in results: total_time += result.get('inference_time', 0) for detection in result.get('predictions', []): class_name = detection['class'] class_counts[class_name] = class_counts.get(class_name, 0) + 1 total_objects += 1 print("\n=== 检测结果统计 ===") print(f"总处理图片数: {len(results)}") print(f"总检测目标数: {total_objects}") print(f"平均推理时间: {total_time/len(results)*1000:.2f}ms/张") print(f"平均FPS: {1000/(total_time/len(results)*1000):.1f}") print("\n目标类别分布:") for class_name, count in sorted(class_counts.items(), key=lambda x: x[1], reverse=True): print(f" {class_name}: {count}个") ``` ## 6. 常见问题与解决方案 ### 6.1 连接超时问题 如果遇到连接超时，可以增加超时时间： ```python # 在detect_single_image函数中修改请求代码 response = requests.post(api_url, files=files, data=data, timeout=30) ``` ### 6.2 内存优化处理大图 对于大尺寸图片，可以先进行缩放处理： ```python def resize_image(image_path, max_size=1024): """ 调整图片尺寸以减少内存占用 Args: image_path: 图片路径 max_size: 最大边长 Returns: str: 调整后的临时文件路径 """ from PIL import Image import tempfile with Image.open(image_path) as img: # 计算缩放比例 width, height = img.size if max(width, height) > max_size: scale = max_size / max(width, height) new_width = int(width * scale) new_height = int(height * scale) img = img.resize((new_width, new_height), Image.Resampling.LANCZOS) # 保存到临时文件 temp_file = tempfile.NamedTemporaryFile(suffix='.jpg', delete=False) img.save(temp_file.name, 'JPEG') return temp_file.name ``` ### 6.3 错误处理与重试机制 添加重试逻辑提高稳定性： ```python import time from requests.exceptions import RequestException def detect_with_retry(image_path, api_url, confidence=0.25, max_retries=3): """ 带重试机制的检测函数 """ for attempt in range(max_retries): try: return detect_single_image(image_path, api_url, confidence) except RequestException as e: if attempt == max_retries - 1: raise e print(f"请求失败，第{attempt+1}次重试...") time.sleep(2 ** attempt) # 指数退避 ``` ## 7. 总结 通过本文介绍的curl命令和Python代码，你可以轻松实现YOLO12模型的API调用和批量图像处理。关键要点包括： 1. **基础API调用**：使用简单的curl命令或Python requests库即可调用检测服务 2. **批量处理**：通过多线程和适当的错误处理机制，可以高效处理大量图片 3. **结果可视化**：不仅获取检测数据，还可以生成带标注框的结果图片 4. **性能优化**：通过调整参数和实现技巧，平衡检测精度和处理速度 YOLO12提供的API接口标准化程度高，易于集成到各种应用场景中。无论是安防监控、智能相册还是工业质检，都可以通过本文介绍的方法快速实现目标检测功能。 实际使用时，建议根据具体需求调整置信度阈值和处理参数，并在正式部署前进行充分的测试验证。 --- > **获取更多AI镜像** > > 想探索更多AI镜像和应用场景？访问 [CSDN星图镜像广场](https://ai.csdn.net/?utm_source=mirror_blog_end)，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。