摘要：在工业场景中，YOLO26模型的核心消费方往往是各类系统而非人类，Streamlit等Web界面无法满足跨系统集成需求。本文基于FastAPI框架，实现YOLO26目标检测模型的RESTful API服务封装，涵盖从数据模型定义、模型缓存加载、核心API端点开发到生产级部署的完整流程。文中详细讲解FastAPI基础用法、异步处理、性能优化技巧，并通过智慧工厂视觉质检虚拟案例展示落地思路。读者可掌握单图检测、批量检测、文件上传、WebSocket实时交互等核心功能，实现YOLO26模型从本地运行到跨系统调用的转化，该方案可快速迁移至智慧安防、智能零售等多个领域，具备高并发、低延迟、易集成的特点。优质专栏欢迎订阅！【OpenClaw从入门到精通】【DeepSeek深度应用】【Python高阶开发：AI自动化与数据工程实战】【YOLOv11工业级实战】【机器视觉：C# + HALCON】【大模型微调实战：平民级微调技术全解】【人工智能之深度学习】【AI 赋能：Python 人工智能应用实战】【数字孪生与仿真技术实战指南】【AI工程化落地与YOLOv8/v9实战】【C#工业上位机高级应用：高并发通信+性能优化】【Java生产级避坑指南：高并发+性能调优终极实战】【Coze搞钱实战：零代码打造吸金AI助手】【YOLO26核心改进+场景落地实战宝典】【OpenClaw企业级智能体实战】文章目录【YOLO26实战全攻略】14——YOLO26 + FastAPI：构建RESTful API服务摘要关键词CSDN文章标签写在前面：关于本文的声明一、引言：为什么要给YOLO26穿上API的外衣？1.1 本章你能学到什么二、核心概念与原理2.1 RESTful API设计原则2.2 FastAPI核心工作原理2.3 YOLO26 API服务架构三、环境准备与项目结构3.1 软硬件环境要求3.2 依赖安装3.3 项目结构设计3.4 环境变量配置（.env文件）四、代码实现与详解4.1 配置管理模块（app/config.py）4.2 Pydantic数据模型（app/models.py）4.3 工具函数模块（app/utils.py）4.4 YOLO26推理封装（app/detector.py）4.5 FastAPI主应用（app/main.py）4.6 工业质检API扩展（app/industrial_api.py）五、实操演示与结果分析5.1 本地开发模式运行5.1.1 启动服务5.1.2 启动成功日志5.1.3 访问API文档5.2 核心接口测试演示5.2.1 单图检测接口（/detect）请求参数（JSON）响应结果结果分析5.2.2 文件上传检测接口（/detect/upload）请求方式响应结果（关键部分）结果分析5.2.3 批量检测接口（/detect/batch）请求参数响应结果结果分析5.2.4 工业质检接口（/industrial/api/v1/inspect）请求参数响应结果结果分析5.3 性能测试结果5.3.1 单接口性能（CPU vs GPU）5.3.2 并发性能测试（GPU环境）5.3.3 关键指标对比（与目标要求）六、部署方案：从开发到生产6.1 Docker容器化部署6.1.1 Dockerfile6.1.2 docker-compose.yml6.1.3 构建与启动命令6.1.4 生产环境优化配置6.2 多进程部署（Gunicorn + Uvicorn）6.2.1 启动命令（生产环境）6.2.2 关键参数说明6.2.3 日志轮转配置（避免日志过大）6.3 云平台部署方案6.3.1 阿里云ECS部署步骤6.3.2 华为云Atlas边缘部署6.4 生产环境安全配置6.4.1 API认证与授权6.4.2 请求限流6.4.3 HTTPS配置七、常见问题与解决方案7.1 模型加载相关问题问题1：模型加载慢，每次请求都重新加载问题2：GPU环境下模型加载失败7.2 接口调用相关问题问题1：Base64图片解码失败问题2：URL图片下载失败7.3 部署相关问题问题1：Docker容器中无法使用GPU问题2：高并发下内存溢出7.4 工业质检相关问题问题1：缺陷检测漏检或误检问题2：OSS上传失败八、总结与展望8.1 核心要点回顾8.2 可扩展方向8.3 学习建议【YOLO26实战全攻略】14——YOLO26 + FastAPI：构建RESTful API服务摘要在工业场景中，YOLO26模型的核心消费方往往是各类系统而非人类，Streamlit等Web界面无法满足跨系统集成需求。本文基于FastAPI框架，实现YOLO26目标检测模型的RESTful API服务封装，涵盖从数据模型定义、模型缓存加载、核心API端点开发到生产级部署的完整流程。文中详细讲解FastAPI基础用法、异步处理、性能优化技巧，并通过智慧工厂视觉质检虚拟案例展示落地思路。读者可掌握单图检测、批量检测、文件上传、WebSocket实时交互等核心功能，实现YOLO26模型从本地运行到跨系统调用的转化，该方案可快速迁移至智慧安防、智能零售等多个领域，具备高并发、低延迟、易集成的特点。关键词YOLO26、FastAPI、RESTful API、目标检测、API服务、Python、深度学习、工业质检、模型部署、Web服务CSDN文章标签机器学习、Python实战、YOLO26、FastAPI、API开发、模型部署、工业视觉写在前面：关于本文的声明内容真实性声明：本文所涉及的FastAPI框架使用方法、RESTful API设计原则、模型异步推理架构均基于Ultralytics官方文档及公开技术资源编写。文中引用的ultralytics、fastapi、uvicorn等Python包均为公开可访问的开源库，可通过pip正常安装。智慧工厂视觉质检API虚拟案例基于第12篇的工地监控思路和第5篇的训练流程构建，旨在帮助读者理解从本地模型到API服务的完整转化流程，案例中使用的工业缺陷检测模型基于公开数据集训练，但完整的API系统尚未在实际生产线中落地，特此声明为虚拟案例。工具与代码说明：本文所引用的所有工具链接均已核实可访问。文中的所有代码均可直接复制运行，代码及执行结果仅供参考。本文未提供任何GitHub代码仓库，请读者切勿搜索不存在的仓库。关于生产部署的说明：本文提供的API示例适用于本地测试和开发环境。如需在生产环境部署，建议结合Gunicorn、Nginx、Docker等工具进行容器化和负载均衡，同时配置适当的认证和限流机制。一、引言：为什么要给YOLO26穿上API的外衣？经过前面13篇的学习，你已经能够：训练自己的YOLO26检测模型（第5篇）评估模型并调优参数（第6-7篇）将模型部署到各类硬件平台（第8篇）处理实时视频流和RTSP摄像头（第12篇）用Streamlit构建Web演示界面（第13篇）但Streamlit Web界面有一个天然的局限：它面向的是“人”，而不是“系统”。在实际的工业场景中，YOLO26的消费方往往不是人类，而是其他系统：智能工厂：MES系统需要调用YOLO26 API，自动检测产线上的缺陷零件智慧安防：监控平台需要调用YOLO26 API，实时分析摄像头画面移动应用：手机App需要调用YOLO26 API，识别用户拍摄的物体微服务架构：多个服务需要共享同一个YOLO26模型，避免重复加载这时候，一个RESTful API服务就成了刚需。而FastAPI，正是把YOLO26包装成高性能API服务的最佳选择。1.1 本章你能学到什么本文将带你掌握YOLO26 + FastAPI的完整API开发流程：FastAPI基础：路由、请求/响应模型、依赖注入模型加载与缓存：使用全局变量和lru_cache避免重复加载核心API端点：健康检查、图片检测、批量检测异步处理：后台任务、WebSocket实时推送性能优化：模型量化、批处理、连接池部署方案：Docker容器化、Gunicorn多进程、云部署虚拟案例：智慧工厂视觉质检API服务二、核心概念与原理2.1 RESTful API设计原则RESTful API是一种软件架构风格，旨在规范HTTP请求的设计，使其具有可读性强、扩展性好、无状态的特点，核心原则包括：资源标识：使用URL表示资源（如/detect表示检测服务）动作语义：使用HTTP方法表达操作（GET查询、POST创建、PUT更新、DELETE删除）状态无关：每个请求包含完整信息，服务器不存储客户端状态响应一致：使用标准HTTP状态码（200成功、400参数错误、500服务器错误）2.2 FastAPI核心工作原理验证通过验证失败客户端发起请求FastAPI接收请求Pydantic数据验证依赖注入（模型实例等）返回400错误响应业务逻辑处理（模型推理）结果序列化（JSON）返回响应给客户端日志记录与监控FastAPI基于Starlette（异步Web框架）和Pydantic（数据验证）构建，其高性能源于：异步IO支持：非阻塞处理请求，提升高并发场景吞吐量类型提示优化：通过Python类型注解生成高效代码自动数据验证：Pydantic提前过滤无效请求，减少业务层开销2.3 YOLO26 API服务架构HTTP/WS请求请求路由数据处理模型缓存推理结果存储/转发响应构建JSON响应后台任务客户端FastAPI服务路由层：/detect/...服务层：模型调用YOLO26模型存储层：MySQL/OSS异步任务：视频处理等核心设计亮点：模型单例模式：启动时加载一次，所有请求共享，避免重复加载开销分层架构：路由层、服务层、存储层分离，便于维护和扩展多输入支持：Base64、URL、文件上传等多种图片输入方式三、环境准备与项目结构3.1 软硬件环境要求类别配置详情硬件环境CPU：Intel Core i5及以上（推荐i7）GPU：NVIDIA GTX 1650及以上（推荐RTX 3060）内存：16GB及以上软件环境操作系统：Windows 10/11、Ubuntu 20.04/22.04Python版本：3.8-3.11CUDA版本：11.8+（GPU加速需配置）3.2 依赖安装# 核心依赖安装pipinstallfastapi[all]==0.115.0 pipinstalluvicorn[standard]==0.30.0 pipinstallultralytics==8.3.0 pipinstallopencv-python==4.9.0.80 pipinstallpillow==10.4.0 pipinstallpython-multipart==0.0.6 pipinstallhttpx==0.27.0 pipinstallgunicorn==21.2.0 pipinstallmysql-connector-python==8.3.0 pipinstallpython-dotenv==1.0.1# 验证安装python-c"import fastapi; print(f'FastAPI {fastapi.__version__}')"python-c"from ultralytics import YOLO; print('YOLO26 OK')"python-c"import uvicorn; print('Uvicorn OK')"3.3 项目结构设计yolo26_api/ ├── app/ │ ├── __init__.py # 包初始化 │ ├── main.py # FastAPI应用入口（核心） │ ├── models.py # Pydantic数据模型（请求/响应） │ ├── detector.py # YOLO26推理封装（模型加载+推理） │ ├── config.py # 配置管理（环境变量、参数） │ ├── utils.py # 工具函数（图像处理、OSS上传等） │ └── industrial_api.py # 工业质检扩展API ├── models/ # 模型权重目录 │ ├── yolo26n.pt # 预训练模型 │ └── industrial_defect.pt # 工业缺陷检测模型 ├── .env # 环境变量配置（数据库、OSS等） ├── requirements.txt # 依赖列表 ├── Dockerfile # Docker部署配置 └── docker-compose.yml # 容器编排配置3.4 环境变量配置（.env文件）# 数据库配置 DB_HOST=localhost DB_NAME=quality_inspection DB_USER=admin DB_PASSWORD=123456 DB_PORT=3306 # OSS配置 OSS_BUCKET=defect-images OSS_ENDPOINT=https://oss-cn-beijing.aliyuncs.com OSS_ACCESS_KEY=your_access_key OSS_SECRET_KEY=your_secret_key # 服务配置 MODEL_PATH=models/yolo26n.pt LOG_LEVEL=INFO MAX_REQUEST_SIZE=10MB WORKERS=4四、代码实现与详解4.1 配置管理模块（app/config.py）frompydantic_settingsimportBaseSettingsfromtypingimportOptionalclassSettings(BaseSettings):"""应用配置类，自动从.env文件加载环境变量"""# 数据库配置db_host:str="localhost"db_name:str="quality_inspection"db_user:str="admin"db_password:str=""db_port:int=3306# OSS配置oss_bucket:Optional[str]=Noneoss_endpoint:Optional[str]=Noneoss_access_key:Optional[str]=Noneoss_secret_key:Optional[str]=None# 服务配置model_path:str="yolo26n.pt"log_level:str="INFO"max_request_size:int=10*1024*1024# 10MBworkers:int=4classConfig:env_file=".env"env_file_encoding="utf-8"# 创建配置实例（单例）settings=Settings()# 数据库连接配置DB_CONFIG={"host":settings.db_host,"database":settings.db_name,"user":settings.db_user,"password":settings.db_password,"port":settings.db_port,"charset":"utf8mb4"}4.2 Pydantic数据模型（app/models.py）frompydanticimportBaseModel,Field,ExtrafromtypingimportList,Optional,Dict,AnyfromdatetimeimportdatetimeclassDetectionRequest(BaseModel):"""单图检测请求模型"""image_base64:Optional[str]=Field(None,description="Base64编码的图片（可带data:image前缀）")image_url:Optional[str]=Field(None,description="图片URL（http/https协议）")confidence:float=Field(0.25,ge=0.0,le=1.0,description="置信度阈值")iou:float=Field(0.45,ge=0.0,le=1.0,description="IoU阈值（非极大值抑制）")classConfig:json_schema_extra={"example":{"image_url":"https://example.com/car.jpg","confidence":0.5,"iou":0.5}}extra=Extra.forbid# 禁止额外字段classDetectionResult(BaseModel):"""单个检测目标结果模型"""class_name:str=Field(...,description="目标类别名称")class_id:int=Field(...,description="目标类别ID")confidence:float=Field(...,ge=0.0,le=1.0,description="检测置信度")bbox:List[float]=Field(...,min_items=4,max_items=4,description="边界框坐标 [x1, y1, x2, y2]")bbox_normalized:Optional[List[float]]=Field(None,description="归一化边界框 [x1, y1, x2, y2]（0-1范围）")classDetectionResponse(BaseModel):"""单图检测响应模型"""success:bool=Field(...,description="请求是否成功")detections:List[DetectionResult]=Field(default_factory=list,description="检测结果列表")count:int=Field(0,description="检测到的目标数量")inference_time_ms:float=Field(0.0,description="推理耗时（毫秒）")error:Optional[str]=Field(None,description="错误信息（仅失败时存在）")extra:Optional[Dict[str,Any]]=Field(None,description="额外信息（如质检结果）")classBatchDetectionRequest(BaseModel):"""批量检测请求模型"""images:List[str]=Field(...,min_items=1,max_items=20,description="图片列表（Base64字符串或URL）")confidence:float=Field(0.25,ge=0.0,le=1.0,description="置信度阈值")iou:float=Field(0.45,ge=0.0,le=1.0,description="IoU阈值")classConfig:json_schema_extra={"example":{"images":["https://example.com/car1.jpg","https://example.com/car2.jpg"],"confidence":0.5}}classBatchDetectionResponse(BaseModel):"""批量检测响应模型"""success:bool=Field(...,description="请求是否成功")results:List[DetectionResponse]=Field(default_factory=list,description="每张图的检测结果")total_time_ms:float=Field(0.0,description="总处理耗时（毫秒）")error:Optional[str]=Field(None,description="错误信息（仅失败时存在）")classTaskStatusResponse(BaseModel):"""异步任务状态响应模型"""task_id:str=Field(...,description="任务ID")status:str=Field(...,description="任务状态（processing/completed/failed）")progress:int=Field(0,description="任务进度（0-100）")result:Optional[Any]=Field(None,description="任务结果（仅完成时存在）")error:Optional[str]
【YOLO26实战全攻略】14——YOLO26 + FastAPI：构建RESTful API服务
摘要：在工业场景中，YOLO26模型的核心消费方往往是各类系统而非人类，Streamlit等Web界面无法满足跨系统集成需求。本文基于FastAPI框架，实现YOLO26目标检测模型的RESTful API服务封装，涵盖从数据模型定义、模型缓存加载、核心API端点开发到生产级部署的完整流程。文中详细讲解FastAPI基础用法、异步处理、性能优化技巧，并通过智慧工厂视觉质检虚拟案例展示落地思路。读者可掌握单图检测、批量检测、文件上传、WebSocket实时交互等核心功能，实现YOLO26模型从本地运行到跨系统调用的转化，该方案可快速迁移至智慧安防、智能零售等多个领域，具备高并发、低延迟、易集成的特点。优质专栏欢迎订阅！【OpenClaw从入门到精通】【DeepSeek深度应用】【Python高阶开发：AI自动化与数据工程实战】【YOLOv11工业级实战】【机器视觉：C# + HALCON】【大模型微调实战：平民级微调技术全解】【人工智能之深度学习】【AI 赋能：Python 人工智能应用实战】【数字孪生与仿真技术实战指南】【AI工程化落地与YOLOv8/v9实战】【C#工业上位机高级应用：高并发通信+性能优化】【Java生产级避坑指南：高并发+性能调优终极实战】【Coze搞钱实战：零代码打造吸金AI助手】【YOLO26核心改进+场景落地实战宝典】【OpenClaw企业级智能体实战】文章目录【YOLO26实战全攻略】14——YOLO26 + FastAPI：构建RESTful API服务摘要关键词CSDN文章标签写在前面：关于本文的声明一、引言：为什么要给YOLO26穿上API的外衣？1.1 本章你能学到什么二、核心概念与原理2.1 RESTful API设计原则2.2 FastAPI核心工作原理2.3 YOLO26 API服务架构三、环境准备与项目结构3.1 软硬件环境要求3.2 依赖安装3.3 项目结构设计3.4 环境变量配置（.env文件）四、代码实现与详解4.1 配置管理模块（app/config.py）4.2 Pydantic数据模型（app/models.py）4.3 工具函数模块（app/utils.py）4.4 YOLO26推理封装（app/detector.py）4.5 FastAPI主应用（app/main.py）4.6 工业质检API扩展（app/industrial_api.py）五、实操演示与结果分析5.1 本地开发模式运行5.1.1 启动服务5.1.2 启动成功日志5.1.3 访问API文档5.2 核心接口测试演示5.2.1 单图检测接口（/detect）请求参数（JSON）响应结果结果分析5.2.2 文件上传检测接口（/detect/upload）请求方式响应结果（关键部分）结果分析5.2.3 批量检测接口（/detect/batch）请求参数响应结果结果分析5.2.4 工业质检接口（/industrial/api/v1/inspect）请求参数响应结果结果分析5.3 性能测试结果5.3.1 单接口性能（CPU vs GPU）5.3.2 并发性能测试（GPU环境）5.3.3 关键指标对比（与目标要求）六、部署方案：从开发到生产6.1 Docker容器化部署6.1.1 Dockerfile6.1.2 docker-compose.yml6.1.3 构建与启动命令6.1.4 生产环境优化配置6.2 多进程部署（Gunicorn + Uvicorn）6.2.1 启动命令（生产环境）6.2.2 关键参数说明6.2.3 日志轮转配置（避免日志过大）6.3 云平台部署方案6.3.1 阿里云ECS部署步骤6.3.2 华为云Atlas边缘部署6.4 生产环境安全配置6.4.1 API认证与授权6.4.2 请求限流6.4.3 HTTPS配置七、常见问题与解决方案7.1 模型加载相关问题问题1：模型加载慢，每次请求都重新加载问题2：GPU环境下模型加载失败7.2 接口调用相关问题问题1：Base64图片解码失败问题2：URL图片下载失败7.3 部署相关问题问题1：Docker容器中无法使用GPU问题2：高并发下内存溢出7.4 工业质检相关问题问题1：缺陷检测漏检或误检问题2：OSS上传失败八、总结与展望8.1 核心要点回顾8.2 可扩展方向8.3 学习建议【YOLO26实战全攻略】14——YOLO26 + FastAPI：构建RESTful API服务摘要在工业场景中，YOLO26模型的核心消费方往往是各类系统而非人类，Streamlit等Web界面无法满足跨系统集成需求。本文基于FastAPI框架，实现YOLO26目标检测模型的RESTful API服务封装，涵盖从数据模型定义、模型缓存加载、核心API端点开发到生产级部署的完整流程。文中详细讲解FastAPI基础用法、异步处理、性能优化技巧，并通过智慧工厂视觉质检虚拟案例展示落地思路。读者可掌握单图检测、批量检测、文件上传、WebSocket实时交互等核心功能，实现YOLO26模型从本地运行到跨系统调用的转化，该方案可快速迁移至智慧安防、智能零售等多个领域，具备高并发、低延迟、易集成的特点。关键词YOLO26、FastAPI、RESTful API、目标检测、API服务、Python、深度学习、工业质检、模型部署、Web服务CSDN文章标签机器学习、Python实战、YOLO26、FastAPI、API开发、模型部署、工业视觉写在前面：关于本文的声明内容真实性声明：本文所涉及的FastAPI框架使用方法、RESTful API设计原则、模型异步推理架构均基于Ultralytics官方文档及公开技术资源编写。文中引用的ultralytics、fastapi、uvicorn等Python包均为公开可访问的开源库，可通过pip正常安装。智慧工厂视觉质检API虚拟案例基于第12篇的工地监控思路和第5篇的训练流程构建，旨在帮助读者理解从本地模型到API服务的完整转化流程，案例中使用的工业缺陷检测模型基于公开数据集训练，但完整的API系统尚未在实际生产线中落地，特此声明为虚拟案例。工具与代码说明：本文所引用的所有工具链接均已核实可访问。文中的所有代码均可直接复制运行，代码及执行结果仅供参考。本文未提供任何GitHub代码仓库，请读者切勿搜索不存在的仓库。关于生产部署的说明：本文提供的API示例适用于本地测试和开发环境。如需在生产环境部署，建议结合Gunicorn、Nginx、Docker等工具进行容器化和负载均衡，同时配置适当的认证和限流机制。一、引言：为什么要给YOLO26穿上API的外衣？经过前面13篇的学习，你已经能够：训练自己的YOLO26检测模型（第5篇）评估模型并调优参数（第6-7篇）将模型部署到各类硬件平台（第8篇）处理实时视频流和RTSP摄像头（第12篇）用Streamlit构建Web演示界面（第13篇）但Streamlit Web界面有一个天然的局限：它面向的是“人”，而不是“系统”。在实际的工业场景中，YOLO26的消费方往往不是人类，而是其他系统：智能工厂：MES系统需要调用YOLO26 API，自动检测产线上的缺陷零件智慧安防：监控平台需要调用YOLO26 API，实时分析摄像头画面移动应用：手机App需要调用YOLO26 API，识别用户拍摄的物体微服务架构：多个服务需要共享同一个YOLO26模型，避免重复加载这时候，一个RESTful API服务就成了刚需。而FastAPI，正是把YOLO26包装成高性能API服务的最佳选择。1.1 本章你能学到什么本文将带你掌握YOLO26 + FastAPI的完整API开发流程：FastAPI基础：路由、请求/响应模型、依赖注入模型加载与缓存：使用全局变量和lru_cache避免重复加载核心API端点：健康检查、图片检测、批量检测异步处理：后台任务、WebSocket实时推送性能优化：模型量化、批处理、连接池部署方案：Docker容器化、Gunicorn多进程、云部署虚拟案例：智慧工厂视觉质检API服务二、核心概念与原理2.1 RESTful API设计原则RESTful API是一种软件架构风格，旨在规范HTTP请求的设计，使其具有可读性强、扩展性好、无状态的特点，核心原则包括：资源标识：使用URL表示资源（如/detect表示检测服务）动作语义：使用HTTP方法表达操作（GET查询、POST创建、PUT更新、DELETE删除）状态无关：每个请求包含完整信息，服务器不存储客户端状态响应一致：使用标准HTTP状态码（200成功、400参数错误、500服务器错误）2.2 FastAPI核心工作原理验证通过验证失败客户端发起请求FastAPI接收请求Pydantic数据验证依赖注入（模型实例等）返回400错误响应业务逻辑处理（模型推理）结果序列化（JSON）返回响应给客户端日志记录与监控FastAPI基于Starlette（异步Web框架）和Pydantic（数据验证）构建，其高性能源于：异步IO支持：非阻塞处理请求，提升高并发场景吞吐量类型提示优化：通过Python类型注解生成高效代码自动数据验证：Pydantic提前过滤无效请求，减少业务层开销2.3 YOLO26 API服务架构HTTP/WS请求请求路由数据处理模型缓存推理结果存储/转发响应构建JSON响应后台任务客户端FastAPI服务路由层：/detect/...服务层：模型调用YOLO26模型存储层：MySQL/OSS异步任务：视频处理等核心设计亮点：模型单例模式：启动时加载一次，所有请求共享，避免重复加载开销分层架构：路由层、服务层、存储层分离，便于维护和扩展多输入支持：Base64、URL、文件上传等多种图片输入方式三、环境准备与项目结构3.1 软硬件环境要求类别配置详情硬件环境CPU：Intel Core i5及以上（推荐i7）GPU：NVIDIA GTX 1650及以上（推荐RTX 3060）内存：16GB及以上软件环境操作系统：Windows 10/11、Ubuntu 20.04/22.04Python版本：3.8-3.11CUDA版本：11.8+（GPU加速需配置）3.2 依赖安装# 核心依赖安装pipinstallfastapi[all]==0.115.0 pipinstalluvicorn[standard]==0.30.0 pipinstallultralytics==8.3.0 pipinstallopencv-python==4.9.0.80 pipinstallpillow==10.4.0 pipinstallpython-multipart==0.0.6 pipinstallhttpx==0.27.0 pipinstallgunicorn==21.2.0 pipinstallmysql-connector-python==8.3.0 pipinstallpython-dotenv==1.0.1# 验证安装python-c"import fastapi; print(f'FastAPI {fastapi.__version__}')"python-c"from ultralytics import YOLO; print('YOLO26 OK')"python-c"import uvicorn; print('Uvicorn OK')"3.3 项目结构设计yolo26_api/ ├── app/ │ ├── __init__.py # 包初始化 │ ├── main.py # FastAPI应用入口（核心） │ ├── models.py # Pydantic数据模型（请求/响应） │ ├── detector.py # YOLO26推理封装（模型加载+推理） │ ├── config.py # 配置管理（环境变量、参数） │ ├── utils.py # 工具函数（图像处理、OSS上传等） │ └── industrial_api.py # 工业质检扩展API ├── models/ # 模型权重目录 │ ├── yolo26n.pt # 预训练模型 │ └── industrial_defect.pt # 工业缺陷检测模型 ├── .env # 环境变量配置（数据库、OSS等） ├── requirements.txt # 依赖列表 ├── Dockerfile # Docker部署配置 └── docker-compose.yml # 容器编排配置3.4 环境变量配置（.env文件）# 数据库配置 DB_HOST=localhost DB_NAME=quality_inspection DB_USER=admin DB_PASSWORD=123456 DB_PORT=3306 # OSS配置 OSS_BUCKET=defect-images OSS_ENDPOINT=https://oss-cn-beijing.aliyuncs.com OSS_ACCESS_KEY=your_access_key OSS_SECRET_KEY=your_secret_key # 服务配置 MODEL_PATH=models/yolo26n.pt LOG_LEVEL=INFO MAX_REQUEST_SIZE=10MB WORKERS=4四、代码实现与详解4.1 配置管理模块（app/config.py）frompydantic_settingsimportBaseSettingsfromtypingimportOptionalclassSettings(BaseSettings):"""应用配置类，自动从.env文件加载环境变量"""# 数据库配置db_host:str="localhost"db_name:str="quality_inspection"db_user:str="admin"db_password:str=""db_port:int=3306# OSS配置oss_bucket:Optional[str]=Noneoss_endpoint:Optional[str]=Noneoss_access_key:Optional[str]=Noneoss_secret_key:Optional[str]=None# 服务配置model_path:str="yolo26n.pt"log_level:str="INFO"max_request_size:int=10*1024*1024# 10MBworkers:int=4classConfig:env_file=".env"env_file_encoding="utf-8"# 创建配置实例（单例）settings=Settings()# 数据库连接配置DB_CONFIG={"host":settings.db_host,"database":settings.db_name,"user":settings.db_user,"password":settings.db_password,"port":settings.db_port,"charset":"utf8mb4"}4.2 Pydantic数据模型（app/models.py）frompydanticimportBaseModel,Field,ExtrafromtypingimportList,Optional,Dict,AnyfromdatetimeimportdatetimeclassDetectionRequest(BaseModel):"""单图检测请求模型"""image_base64:Optional[str]=Field(None,description="Base64编码的图片（可带data:image前缀）")image_url:Optional[str]=Field(None,description="图片URL（http/https协议）")confidence:float=Field(0.25,ge=0.0,le=1.0,description="置信度阈值")iou:float=Field(0.45,ge=0.0,le=1.0,description="IoU阈值（非极大值抑制）")classConfig:json_schema_extra={"example":{"image_url":"https://example.com/car.jpg","confidence":0.5,"iou":0.5}}extra=Extra.forbid# 禁止额外字段classDetectionResult(BaseModel):"""单个检测目标结果模型"""class_name:str=Field(...,description="目标类别名称")class_id:int=Field(...,description="目标类别ID")confidence:float=Field(...,ge=0.0,le=1.0,description="检测置信度")bbox:List[float]=Field(...,min_items=4,max_items=4,description="边界框坐标 [x1, y1, x2, y2]")bbox_normalized:Optional[List[float]]=Field(None,description="归一化边界框 [x1, y1, x2, y2]（0-1范围）")classDetectionResponse(BaseModel):"""单图检测响应模型"""success:bool=Field(...,description="请求是否成功")detections:List[DetectionResult]=Field(default_factory=list,description="检测结果列表")count:int=Field(0,description="检测到的目标数量")inference_time_ms:float=Field(0.0,description="推理耗时（毫秒）")error:Optional[str]=Field(None,description="错误信息（仅失败时存在）")extra:Optional[Dict[str,Any]]=Field(None,description="额外信息（如质检结果）")classBatchDetectionRequest(BaseModel):"""批量检测请求模型"""images:List[str]=Field(...,min_items=1,max_items=20,description="图片列表（Base64字符串或URL）")confidence:float=Field(0.25,ge=0.0,le=1.0,description="置信度阈值")iou:float=Field(0.45,ge=0.0,le=1.0,description="IoU阈值")classConfig:json_schema_extra={"example":{"images":["https://example.com/car1.jpg","https://example.com/car2.jpg"],"confidence":0.5}}classBatchDetectionResponse(BaseModel):"""批量检测响应模型"""success:bool=Field(...,description="请求是否成功")results:List[DetectionResponse]=Field(default_factory=list,description="每张图的检测结果")total_time_ms:float=Field(0.0,description="总处理耗时（毫秒）")error:Optional[str]=Field(None,description="错误信息（仅失败时存在）")classTaskStatusResponse(BaseModel):"""异步任务状态响应模型"""task_id:str=Field(...,description="任务ID")status:str=Field(...,description="任务状态（processing/completed/failed）")progress:int=Field(0,description="任务进度（0-100）")result:Optional[Any]=Field(None,description="任务结果（仅完成时存在）")error:Optional[str]
