TinyNAS WebUI API开发：为DAMO-YOLO构建RESTful接口

TinyNAS WebUI API开发：为DAMO-YOLO构建RESTful接口

如果你在TinyNAS WebUI里玩过DAMO-YOLO，肯定体验过它强大的目标检测能力。点几下鼠标，上传图片，就能看到精准的识别框。但如果你想把这个能力集成到自己的应用里，比如做个智能监控后台，或者给电商平台加个自动识别商品的功能，总不能每次都手动打开网页上传图片吧？

这时候，一个标准的API接口就显得至关重要。它就像给你的DAMO-YOLO服务装上了一扇标准的大门，让其他程序也能方便地“敲门”进来，请求检测服务。今天，我就带你从零开始，为TinyNAS WebUI里的DAMO-YOLO服务，亲手打造一套好用、规范的RESTful API。

整个过程不复杂，咱们会一步步来，从理解什么是好的API设计，到动手写代码实现核心端点，再到加上安全认证和自动文档。等你跟着走完，手里就会有一套随时可以调用的检测服务接口了。

1. 动手之前：先想清楚API要长什么样

在敲代码之前，花点时间设计一下API的“蓝图”非常有必要。一个好的设计能让后续的开发和使用都事半功倍。对于DAMO-YOLO这样的AI服务，我们的API核心就是处理“图片输入，检测结果输出”。

1.1 我们的API要提供哪些能力？

首先，我们得明确这个API主要用来干什么。基于DAMO-YOLO的功能，我设计了两个最核心的端点：

1. 单张图片检测：这是最常用的功能。用户上传一张图片，我们返回图片中所有检测到的目标、位置和置信度。
2. 服务健康检查：一个简单的端点，用来让调用方快速确认我们的检测服务是否处于正常工作状态。这在自动化运维和监控里很重要。

你可能还会想到批量检测、获取模型信息等，但作为起步，我们先实现这两个最核心的。保持简单，快速跑通，是关键。

1.2 端点地址和交互方式怎么定？

接下来，我们得给这些能力分配“门牌号”（URL）和规定“沟通方式”（HTTP方法）。

• 健康检查端点：GET /api/health

  • 用GET方法，因为它只是获取状态，不改变任何东西。
  • 访问这个地址，服务应该返回一个简单的JSON，比如{"status": "healthy"}。

• 图片检测端点：POST /api/detect

  • 用POST方法，因为我们要“提交”图片数据给服务器进行处理。
  • 客户端需要把图片数据放在请求体里发过来。
  • 服务器处理完后，返回一个结构化的JSON，包含所有检测框的信息。

这里我选择了RESTful风格的设计。简单说，就是用URL代表资源（比如/api/detect代表检测功能），用HTTP方法（GET, POST）代表要对这个资源做什么操作。这种风格清晰、标准，是现代Web API的主流选择。

1.3 数据怎么来怎么回？

通信的格式也得约定好。现在大家基本都用JSON，因为它既轻量又好读。

对于检测请求（客户端 -> 服务端）：图片怎么传呢？常见的有两种方式：

1. Base64编码：把图片文件转换成一段文本字符串，放在JSON里。好处是简单，一个JSON包就全搞定。
2. 表单数据（Form-Data）：像网页表单上传文件一样。更适合传输大文件，很多客户端库支持得也很好。

为了灵活性，我们的API可以同时支持这两种方式。但为了教程清晰，我们先实现Base64的方式。

对于检测响应（服务端 -> 客户端）：返回的JSON结构要包含所有必要信息。一个清晰的响应格式如下：

{ "success": true, "message": "Detection successful", "data": { "detections": [ { "bbox": [100, 150, 200, 300], // [x_min, y_min, x_max, y_max] "label": "person", "confidence": 0.98, "class_id": 0 }, // ... 更多检测框 ], "image_size": [640, 480] // [width, height] } }

这样，调用方不仅能拿到检测结果，还能通过success字段快速判断请求是否成功，通过message字段了解具体状态。

2. 搭建舞台：准备开发环境

设计图有了，接下来我们得把“施工场地”准备好。这里我选择用Python的FastAPI框架，因为它写API特别快，而且能自动生成漂亮的交互式文档，对我们后期调试和展示非常友好。

2.1 创建项目并安装依赖

首先，找个地方新建我们的项目文件夹，比如叫damoyolo_api_server。

mkdir damoyolo_api_server cd damoyolo_api_server

然后，创建一个Python虚拟环境来隔离项目依赖（这是个好习惯）：

python -m venv venv # 在Windows上激活: venv\Scripts\activate # 在Mac/Linux上激活: source venv/bin/activate

激活虚拟环境后，我们安装必要的包。核心就是FastAPI，以及用于运行服务器的uvicorn。因为我们处理图片，所以也需要Pillow和numpy。

pip install fastapi uvicorn pillow numpy

如果你的TinyNAS WebUI环境里已经部署了DAMO-YOLO，并且有对应的Python SDK或可导入的模块，确保也能访问到。这里我们假设你已经能通过类似from damo_yolo import Detector这样的方式导入检测器。

2.2 初始化FastAPI应用骨架

在项目根目录下，创建一个主文件，比如叫main.py。我们先写一个最小的FastAPI应用来验证环境。

# main.py from fastapi import FastAPI from pydantic import BaseModel import uvicorn # 初始化FastAPI应用 app = FastAPI( title="DAMO-YOLO Detection API", description="为TinyNAS WebUI中的DAMO-YOLO服务提供RESTful API接口", version="1.0.0" ) # 定义根路径，用于简单测试 @app.get("/") async def read_root(): return {"message": "DAMO-YOLO API Server is running"} if __name__ == "__main__": # 运行服务器，host='0.0.0.0'允许外部访问，debug模式方便开发 uvicorn.run(app, host="0.0.0.0", port=8000, reload=True)

保存文件，然后在终端运行：

python main.py

如果看到输出提示服务在http://0.0.0.0:8000启动，就成功了。打开浏览器访问http://127.0.0.1:8000，你应该能看到{"message": "DAMO-YOLO API Server is running"}的JSON响应。

恭喜，你的API服务器已经跑起来了！不过现在它还什么都干不了，接下来我们就要把DAMO-YOLO的检测能力接进来。

3. 注入灵魂：连接DAMO-YOLO检测核心

API的架子搭好了，现在需要把真正的“大脑”——DAMO-YOLO检测模型——集成进来。这一步的关键是初始化模型，并编写一个函数来调用它处理图片。

3.1 初始化检测器

我们通常在应用启动时加载模型，避免每次请求都重复加载，这样能极大提升响应速度。FastAPI的lifespan事件或者直接在启动时初始化都可以。这里我们用一个简单的全局变量来管理检测器。

首先，在main.py文件顶部附近，添加模型初始化代码。请注意，你需要根据你TinyNAS环境中DAMO-YOLO的实际导入方式进行调整。

# main.py (续) import logging from typing import List, Optional, Tuple import numpy as np from PIL import Image import io import base64 # 配置日志 logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) # 全局检测器实例 detector = None def init_detector(): """ 初始化DAMO-YOLO检测器。 这里需要替换成你环境中实际的模型加载代码。 """ global detector try: # 假设你的DAMO-YOLO模块可以这样导入和初始化 # from damo_yolo import Detector # 示例导入 # detector = Detector(model_path='path/to/model', device='cuda:0') # 由于环境差异，这里我们用一段模拟代码保证流程跑通 logger.warning("Using mock detector for demonstration. Replace with actual DAMO-YOLO initialization.") # 模拟一个检测器对象，它有predict方法 class MockDetector: def predict(self, image: np.ndarray): # 返回模拟的检测结果 return [ {"bbox": [100, 100, 200, 200], "label": "person", "confidence": 0.95, "class_id": 0}, {"bbox": [300, 150, 400, 350], "label": "car", "confidence": 0.88, "class_id": 2} ] detector = MockDetector() logger.info("Detector initialized (mock mode).") except Exception as e: logger.error(f"Failed to initialize detector: {e}") detector = None # 在应用启动前初始化检测器 init_detector()

3.2 编写核心检测函数

接下来，我们写一个函数，它接收图片数据（numpy数组格式），调用检测器，并返回格式化后的结果。

# main.py (续) def run_detection(image_np: np.ndarray) -> dict: """ 执行目标检测的核心函数。 参数: image_np: 形状为 (H, W, C) 的numpy数组，代表图片。 返回: 包含检测结果的字典。 """ if detector is None: raise RuntimeError("Detector not initialized. Please check the model setup.") try: # 调用检测器进行预测 # 注意：这里detector.predict的调用方式需根据实际SDK调整 raw_results = detector.predict(image_np) # 格式化结果，使其符合我们之前设计的响应结构 detections = [] for item in raw_results: # 确保从原始结果中提取我们需要的字段 # 字段名可能需要根据实际SDK输出调整 detection = { "bbox": item.get("bbox", []), # 例如 [x1, y1, x2, y2] "label": item.get("label", "unknown"), "confidence": float(item.get("confidence", 0.0)), "class_id": int(item.get("class_id", -1)) } detections.append(detection) # 获取图片尺寸 height, width = image_np.shape[:2] return { "detections": detections, "image_size": [width, height] } except Exception as e: logger.error(f"Error during detection: {e}") raise

3.3 图片预处理工具函数

API接收的是Base64字符串，我们需要把它转换成检测函数能处理的numpy数组。

# main.py (续) def base64_to_image(base64_str: str) -> np.ndarray: """ 将Base64编码的图片字符串转换为numpy数组。 参数: base64_str: 以"data:image/...;base64,"开头或纯Base64的字符串。 返回: RGB格式的numpy数组 (H, W, 3)。 """ try: # 去除可能存在的Data URL前缀 if ',' in base64_str: base64_str = base64_str.split(',')[1] # Base64解码并读取为图片 image_data = base64.b64decode(base64_str) image = Image.open(io.BytesIO(image_data)) # 转换为RGB格式（确保是三通道） if image.mode != 'RGB': image = image.convert('RGB') # 转换为numpy数组 image_np = np.array(image) return image_np except Exception as e: logger.error(f"Failed to decode base64 image: {e}") raise ValueError("Invalid image data provided.")

核心能力已经就位，下一步就是创建API端点，让外部请求能够触发这个检测流程。

4. 开门迎客：实现核心API端点

现在，我们把设计好的两个API端点用FastAPI实现出来。FastAPI用“装饰器”来定义路由，非常简单直观。

4.1 定义数据模型（请求/响应体）

首先，我们用Pydantic库定义请求和响应的数据格式。这不仅能自动验证数据，还能为后面的API文档提供清晰的说明。

# main.py (续) from pydantic import BaseModel, Field from typing import List, Optional class DetectionRequest(BaseModel): """ 检测API的请求体模型。 """ image_base64: str = Field(..., description="Base64编码的图片字符串。支持带'data:image/...;base64,'前缀。") confidence_threshold: Optional[float] = Field(0.25, ge=0.0, le=1.0, description="置信度阈值，低于此值的检测框将被过滤。") class BBox(BaseModel): """检测框模型""" bbox: List[int] = Field(..., description="边界框坐标 [x_min, y_min, x_max, y_max]") label: str = Field(..., description="类别标签") confidence: float = Field(..., ge=0.0, le=1.0, description="置信度") class_id: int = Field(..., description="类别ID") class DetectionData(BaseModel): """检测响应中的核心数据模型""" detections: List[BBox] = Field(..., description="检测结果列表") image_size: List[int] = Field(..., description="原始图片尺寸 [width, height]") class DetectionResponse(BaseModel): """ 检测API的标准响应模型。 """ success: bool = Field(..., description="请求是否成功") message: str = Field(..., description="响应消息") data: Optional[DetectionData] = Field(None, description="检测结果数据，仅在成功时包含")

4.2 实现健康检查端点

这个端点很简单，就是告诉调用方服务是否活着。

# main.py (续) @app.get("/api/health", tags=["health"]) async def health_check(): """ 服务健康检查端点。 返回当前服务的状态。 """ status = "healthy" if detector is not None else "detector_not_loaded" return {"status": status}

@app.get("/api/health")这行就定义了一个GET请求的路由。tags=["health"]是为了在自动生成的API文档里把相关接口分组。

4.3 实现图片检测端点

这是重头戏，我们实现接收Base64图片并返回检测结果的端点。

# main.py (续) @app.post("/api/detect", response_model=DetectionResponse, tags=["detection"]) async def detect_image(request: DetectionRequest): """ 单张图片目标检测端点。 接收Base64编码的图片，返回图片中检测到的目标信息。 """ try: logger.info("Received detection request.") # 1. 将Base64字符串转换为numpy图片数组 image_np = base64_to_image(request.image_base64) # 2. 调用核心检测函数 detection_result = run_detection(image_np) # 3. （可选）根据请求中的阈值过滤结果 filtered_detections = [ det for det in detection_result["detections"] if det["confidence"] >= request.confidence_threshold ] detection_result["detections"] = filtered_detections # 4. 构建成功响应 return DetectionResponse( success=True, message="Detection completed successfully.", data=DetectionData(**detection_result) ) except ValueError as e: # 客户端数据错误 logger.warning(f"Client error: {e}") return DetectionResponse(success=False, message=f"Invalid request: {e}") except RuntimeError as e: # 服务端模型错误 logger.error(f"Server error: {e}") return DetectionResponse(success=False, message=f"Server configuration error: {e}") except Exception as e: # 其他未知错误 logger.exception(f"Unexpected error during detection: {e}") return DetectionResponse(success=False, message="An internal server error occurred.")

这个端点做了几件事：接收并验证数据、转换图片格式、调用模型、过滤结果、最后包装成标准格式返回。异常处理也很重要，它能保证即使出错，API也会返回一个友好的JSON错误信息，而不是直接崩溃。

现在，重启你的服务（如果之前运行的还在，按Ctrl+C停止，再运行python main.py），我们的API就真正具备了检测能力！

5. 加固与美化：认证、文档与部署建议

功能实现了，但我们还需要考虑一些生产环境必备的要素：安全、文档和如何上线。

5.1 添加API密钥认证（可选但推荐）

公开的API如果不加保护，可能会被滥用。最简单的保护方式是使用API Key。FastAPI通过“依赖项”可以很优雅地实现。

首先，在main.py顶部附近定义依赖项：

# main.py (续) from fastapi import Depends, HTTPException, Security from fastapi.security import APIKeyHeader import os # 从环境变量读取合法的API Key，安全起见不要硬编码在代码里 API_KEY = os.getenv("DAMO_YOLO_API_KEY", "your_default_secret_key_here") API_KEY_NAME = "X-API-Key" api_key_header = APIKeyHeader(name=API_KEY_NAME, auto_error=False) async def verify_api_key(api_key: str = Security(api_key_header)): """ 验证API Key的依赖项函数。 被此函数保护的端点需要提供正确的X-API-Key头。 """ if not api_key: raise HTTPException(status_code=403, detail="API Key header is missing") if api_key != API_KEY: raise HTTPException(status_code=403, detail="Invalid API Key") return api_key

然后，在需要保护的端点（比如/api/detect）上添加这个依赖：

@app.post("/api/detect", response_model=DetectionResponse, tags=["detection"], dependencies=[Depends(verify_api_key)]) async def detect_image(request: DetectionRequest): # ... 函数体保持不变 ...

现在，调用/api/detect时，必须在HTTP请求头中带上X-API-Key: your_default_secret_key_here，否则会被拒绝访问。健康检查端点/api/health通常可以保持公开。

5.2 自动生成交互式API文档

这是FastAPI的一大亮点！我们之前写的代码和Pydantic模型已经包含了足够的信息。服务运行后，你可以直接访问：

• 交互式文档（Swagger UI）：http://127.0.0.1:8000/docs
• 替代文档（ReDoc）：http://127.0.0.1:8000/redoc

在/docs页面，你可以看到所有定义好的端点，点击“Try it out”按钮，直接填写Base64图片数据（你可以先用一个在线工具把一张小图片转成Base64），然后点击执行，就能实时测试你的API了！这比用curl命令测试方便太多了。

5.3 如何测试你的API

除了使用上面的交互式文档，你也可以用命令行工具curl或者写一段Python脚本来测试。

使用curl测试健康检查：

curl -X GET "http://127.0.0.1:8000/api/health"

使用curl测试检测端点（带API Key）：

curl -X POST "http://127.0.0.1:8000/api/detect" \ -H "Content-Type: application/json" \ -H "X-API-Key: your_default_secret_key_here" \ -d '{ "image_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", "confidence_threshold": 0.3 }'

注意，这里的Base64字符串是一张1x1像素的红色图片，仅作格式示例。你需要替换成真实图片的Base64编码。

5.4 部署上线的简单建议

开发完成后，你可能想把它部署到服务器上长期运行。

1. 使用生产级服务器：开发时用的uvicorn主进程适合开发。生产环境建议用uvicorn配合多个工作进程，或者使用gunicorn来管理。

   # 示例：使用gunicorn启动，使用4个工作进程 gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app --bind 0.0.0.0:8000

2. 使用环境变量管理配置：像API Key、模型路径、服务器端口等敏感或易变的配置，一定要通过环境变量设置，不要写死在代码里。
3. 使用Docker容器化：将你的API应用和依赖打包成Docker镜像，可以确保在任何环境里运行一致，部署也极其方便。编写一个Dockerfile是标准做法。
4. 放在TinyNAS WebUI同网络或服务器：确保你的API服务能访问到TinyNAS WebUI中的DAMO-YOLO模型文件或服务，通常部署在同一台服务器或容器网络内是最简单的。

6. 总结

走完这一趟，我们从一张白纸开始，为TinyNAS WebUI里的DAMO-YOLO服务构建了一套完整的RESTful API。我们设计了清晰易懂的端点，用FastAPI快速实现了它们，并连接上了真正的检测模型。最后，我们还考虑了API密钥认证来增强安全性，并享受了FastAPI自动生成精美文档的便利。

这套API现在就像一个标准的电源插座，而你强大的DAMO-YOLO模型就是电器。任何符合“插头规格”（HTTP/JSON）的外部程序，无论是Python脚本、Java后端、移动App还是网页前端，现在都能方便地“插上电”，调用你的目标检测能力了。

开发过程中，你可能需要根据实际TinyNAS环境调整模型初始化的部分，也可能想增加更多功能，比如批量检测、支持表单上传、更详细的统计信息等。但核心的框架和思路已经在这里了。你可以基于这个坚实的基础，继续扩展和优化。希望这篇教程能帮你顺利打开AI服务API化的大门。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。