爆肝实测｜FastAPI+YOLO11+SAM2+JWT 一步到位，搭建高安全图像分割接口（新手可直接抄）
先说结论：这套组合做出来的不是“能用”的demo，而是一个可以扛住真实业务压力的图像分割服务骨架。FastAPI负责对外暴露接口和鉴权，YOLO11负责把目标检测出来拿到边界框，SAM2再基于这些框做精细像素级分割，JWT保证每一次请求都不是裸奔。四者各干各的活，但在工程上又能无缝咬合。如果你手头正好有“给一张图，返回前景分割结果”这种需求，或者你想把手里的目标检测项目升级成真正的分割服务，这篇文章可以从零把你带到能上线的程度。
我直接交代一下背景。我前后折腾了两周，中间踩了不少坑，尤其是SAM2官方仓库的安装方式、YOLO11在CUDA 12.4下的编译问题、以及JWT如何跟FastAPI的依赖注入体系结合这三块，网上的资料要么太零散，要么直接偏题。所以这篇文章不是官方文档的复读，而是把“怎么把四个东西真正串起来”的全过程拆给你看。适合的人：懂一点Python、知道FastAPI大概长什么样、想快速做出一个高安全图像分割接口的开发者。不适合的人：完全没碰过后端、想拿它做学术论文级精度调优的人。
开始之前，先说一下整套架构的最终形态：客户端带着JWT令牌请求POST /api/v1/segment，传一张图片；后端解析令牌确认身份后，先跑YOLO11得到检测框，再把这些框作为prompt喂给SAM2做分割，最后把掩码叠加在原图上，返回带透明通道的PNG。整个过程大约1到2秒，具体取决于硬件和图片尺寸。
1. 为什么是这四个组件：各司其职与接口设计思路
1.1 没有YOLO11的“纯SAM2”为什么不适合做生产接口
先把分工讲透。如果你只想做“分割”，只用SAM2也能跑，但你的接口会变成“全图分割”或者“人工点选分割”。前者返回一大堆你根本不需要的区域，后者需要调用方提供点坐标或框坐标，这在真实的图片URL或文件上传场景里根本不可行——调用方不可能知道目标点在哪。这就是为什么需要YOLO11先干一仗：它是检测器，输入一张图，输出“哪里有目标、目标是什么、边界框在哪”。然后你把边界框交给SAM2，SAM2才会老老实实只在你关注的区域里做分割。换句话说，YOLO11是“告诉模型看哪里”的眼睛，SAM2是“把看到的区域抠干净”的手。两者配合，语义上刚好完成一次完整的检测+分割pipeline。
YOLO11是我在对比了YOLOv8和YOLO11之后选定的。YOLO11在同样体量下推理速度略优于v8，在NMS后处理和多任务头设计上也做了更新。更重要的是Ultralytics的Python接口已经足够简洁——三行代码就能拿到检测框，能在FastAPI里以极低心智负担集成。而SAM2的分割质量和边缘精细度远超传统的GrabCut或普通U-Net，尤其在广告牌、口腔疾病影像、风机叶片这类边缘复杂的业务场景，效果差距肉眼可见。一句话总结选型逻辑：在工程效率面前，只有把每一步的成熟度拉满，才可能用两周而不是两个月做到“可上线”。
1.2 FastAPI为什么是这四个组件里最适合做服务框架的
FastAPI的杀手锏不是“性能最高”，而是它把异步、类型校验、接口文档、依赖注入都揉在了一起，是当前把所有工程要素融合得最舒服的Python Web框架之一。与Flask相比，FastAPI原生支持async def，遇到图像分割这种CPU/GPU密集任务，你可以把计算丢给线程池或进程池执行，避免事件循环被阻塞。与Django相比，FastAPI没有庞大的ORM和后台管理这些重装备，做纯算法接口服务时，轻量就是优势。
更重要的是JWT鉴权在FastAPI里的优雅程度。FastAPI的依赖注入系统允许你写一个get_current_user函数作为Security依赖，所有受保护接口只需要在路由参数里声明它，框架会自动帮你解析Authorization头。这比在Django REST Framework里手写一大堆认证类要直观得多。你不需要学习“中间件”这个概念，只需要定义一个Python函数，系统会负责注入。这对新手极其友好。
1.3 JWT不只是“防陌生人”，更是给接口加一层可控边界
很多初学者觉得图像分割接口跑在内部网络上，根本没必要做鉴权。这个想法在本地实验没问题，但只要服务部署到公网、或者接入小程序/App后端，就完全不是一回事了。没有JWT意味着任何人都能拿你的GPU跑分割，轻则拖慢服务，重则被人用来刷接口耗尽算力配额。JWT做的事有三件：一是证明“你是谁”，二是让服务能快速校验“你有没有权利访问这个API”，三是让服务端不需要保存会话状态——无状态扩展对GPU服务尤其重要。
JWT实现Token续签、新Token覆盖旧Token也是能落地的。常见做法是签发短期Access Token（比如30分钟），配一个Refresh Token（比如7天）。每次请求用Access Token，过期后用Refresh Token换新的Access Token。FastAPI实现这套流程不复杂，后面的章节我会给出完整的scheme和接口逻辑。
2. 核心细节解析：模型选型、环境配置与文件结构设计
2.1 YOLO11的模型文件与部署细节
要跑YOLO11，安装就一步：
pip install ultralytics但你要注意版本之间的隐性依赖关系。我的实测环境是Python 3.10 + CUDA 12.4 + PyTorch 2.4，ultralytics用了8.3.x版本。如果你照搬网上老教程踩到“AttributeError: 'NoneType' object has no attribute 'shape'”这类问题，大概率是PyTorch和CUDA不匹配导致的Tensor设备传输问题。
图像分割场景不需要把所有检测类别都放给模型，多数时候你只需要一两个业务类别。例如广告牌检测只需要box类billboard，风机叶片检测只需要box类blade。这时不能直接跑官方预训练YOLO11，因为那个模型是根据COCO 80类训练出来的，识别不了你自定义的类别。你需要自己准备几百张标注（YOLO格式的txt），然后用ultralytics的接口微调：
from ultralytics import YOLO model = YOLO("yolo11n.pt") model.train(data="custom.yaml", epochs=100, imgsz=640, batch=16, device=0)data.yaml重点是指定训练和验证数据路径以及类别名。微调完后的best.pt就是你的检测模型。如果你只是想先跑通整套demo，不想纠结微调，那直接用COCO预训练模型也行，只不过它只能返回COCO里的80类目标。
2.2 SAM2的安装与环境配置实况
SAM2是Meta开源的Segment Anything 2模型，效果比SAM一代好很多，但在安装时有一个非常劝退的坑：它默认依赖半精度推理，而且依赖了hydra-core和iopath等一堆包。我在Ubuntu 22.04上直接执行下面的命令，遇到过若干次环境冲突：
git clone git@github.com:facebookresearch/sam2.git cd sam2 pip install -e .几个容易卡住的地方：第一，它会去下载一个比较大的checkpoint文件（sam2_hiera_large.pt约800MB），网络不好的时候很容易中断；第二，必须依赖flash-attn吗？实测下来如果你只是用CPU推理或者3090这样没装flash-attn的显卡，也并非完全无法跑，只是推理速度会受影响。官方推荐编译flash-attn，但那玩意安装简直是一场事故。我个人的建议是：服务器显存在16GB以上时，用默认的sam2_hiera_large效果最好；显卡不够好就用sam2_hiera_small或sam2_hiera_base_plus，精度的差距在某些业务场景中微乎其微。
另外一个很多人忽略的细节是SAM2的checkpoint需要放在正确位置：
mkdir -p checkpoints # 把下载的sam2_hiera_large.pt挪到checkpoints/如果你跳过这一步，模型加载时会报出类似FileNotFoundError: checkpoints/sam2_hiera_large.pt not found，特别折磨。建议把checkpoint一次性放到项目目录内，并用环境变量SAM2_CHECKPOINT统一管理路径，后续做镜像迁移的时候能省很多事。
2.3 FastAPI项目的文件结构设计
骨架层面，我推荐这种结构：
project/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI入口，创建app对象与路由注册 │ ├── core/ │ │ ├── config.py # 全局配置：密钥、模型路径、算法参数 │ │ └── security.py # JWT创建与校验 │ ├── models/ │ │ ├── detector.py # YOLO11封装 │ │ └── segmentor.py # SAM2封装 │ ├── schemas/ │ │ └── response.py # Pydantic响应模型 │ ├── routers/ │ │ ├── auth.py # 登录、刷新Token │ │ └── segment.py # 分割接口 │ └── services/ │ └── inference.py # 检测+分割整合流水线 ├── weights/ └── requirements.txt为什么要这么拆？因为单文件把代码写完确实跑得起来，但当你需要把YOLO换成YOLOv10、把SAM2换成其它分割模型，或者新增一个“视频抽帧分割”接口时，单文件会变成一团乱麻。核心思路是“模型实例只初始化一次，代码逻辑通过类封装”。FastAPI是支持lifespan的，完全可以在服务启动时把模型加载到GPU显存，等接口真正收到请求时直接拿去推理，而不必每次请求重新加载模型——那样会导致延迟高达几十秒甚至超时。后面的实现小节里我会给出具体代码，这里先记住原则。
3. 实操过程：从模型加载到鉴权接口的完整实现
3.1 准备工作与依赖清单
先装基础依赖：
pip install "fastapi[all]" "uvicorn[standard]" "python-jose[cryptography]" "passlib[bcrypt]" "ultralytics" "torch" "torchvision" "opencv-python" "pillow" "numpy" "python-multipart"这里解释几个关键选择：
python-jose[cryptography]：JWT的签名和校验库。纯用pyjwt也可以，但Jose对RS256/ES256等非对称算法支持得更好，以后做多服务拆分不用推倒重来。python-multipart：FastAPI解析multipart/form-data文件上传时必须要装，否则会报403类错误，很隐蔽。opencv-python：图像处理的主力库，用来读图、缩放、叠加掩码、输出PNG。passlib[bcrypt]：后续做账号密码哈希用。如果只是内部服务且没有注册功能，也可以先不要。uvicorn[standard]：生产级ASGI服务器。不要图省事用uvicorn裸装，standard额外带了uvloop和httptools，性能差很多。
模型权重方面，我建议把两个权重放在项目外的weights目录，避免项目包过大。一个是微调好的best.pt，一个是sam2_hiera_large.pt。如果只是demo，best.pt就是官方yolo11n.pt。
3.2 JWT签发与FastAPI安全依赖的实现
安全模块放在app/core/security.py里，代码如下：
from datetime import datetime, timedelta, timezone from typing import Optional from jose import JWTError, jwt from passlib.context import CryptContext SECRET_KEY = "your-secret-key-change-in-production" ALGORITHM = "HS256" ACCESS_TOKEN_EXPIRE_MINUTES = 30 REFRESH_TOKEN_EXPIRE_DAYS = 7 pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto") def create_token(subject: str, token_type: str, expires_delta: timedelta) -> str: expire = datetime.now(timezone.utc) + expires_delta payload = {"sub": subject, "type": token_type, "exp": expire} return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM) def create_access_token(subject: str) -> str: return create_token( subject, "access", timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES), ) def create_refresh_token(subject: str) -> str: return create_token( subject, "refresh", timedelta(days=REFRESH_TOKEN_EXPIRE_DAYS), ) def decode_token(token: str) -> dict: return jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])FastAPI里定义依赖：
from fastapi import Depends, HTTPException, status from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials bearer_scheme = HTTPBearer(auto_error=False) def get_current_user( credentials: HTTPAuthorizationCredentials = Depends(bearer_scheme), ) -> str: if credentials is None: raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail="Not authenticated", ) token = credentials.credentials try: payload = decode_token(token) if payload.get("type") != "access": raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token type", ) return payload.get("sub") except JWTError: raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token", )新手特别容易犯的一个错是把HTTPBearer(auto_error=True)和JWT校验混在一起，导致没带Token时返回的不是json格式错误而是一大段内部的OpenAPI样式错误提示。我用auto_error=False就是为了让依赖函数自己控制错误返回，这样接口的异常结构完全一致，前端处理起来也舒服。
Token续签的方案也很简单：你提供一个/api/v1/auth/refresh接口，入参是{refresh_token: string}，后台先校验refresh token的类型和过期时间，再签发新的access token。如果用户“退出登录”，可以在服务端维护一个Redis黑名单，把refresh_token的jti加进去。但作为轻量服务，不做也无伤大雅——毕竟是无状态服务的主流取舍。
3.3 模型封装：让YOLO11与SAM2在FastAPI里各用各的
创建app/models/detector.py：
import cv2 import numpy as np from ultralytics import YOLO class Detector: def __init__(self, weights_path: str, device: str = "cuda:0", conf_thres: float = 0.25): self.model = YOLO(weights_path) self.device = device self.conf_thres = conf_thres def predict(self, image_bgr: np.ndarray): results = self.model.predict( source=image_bgr, conf=self.conf_thres, device=self.device, verbose=False, ) boxes = results[0].boxes.xyxy.cpu().numpy().astype(int) return boxes要注意，这里我用的是BGR，因为OpenCV默认是BGR。后面喂给SAM2之前，我会统一做一次RGB转换，避免颜色通道翻转导致分割结果出现幽灵色差。
SAM2的封装，app/models/segmentor.py：
import numpy as np import torch from PIL import Image from sam2.build_sam import build_sam2 from sam2.sam2_image_predictor import SAM2ImagePredictor class Segmentor: def __init__(self, checkpoint_path: str, model_cfg: str, device: str = "cuda:0"): sam2 = build_sam2(model_cfg, checkpoint_path, device=device) self.predictor = SAM2ImagePredictor(sam2) self.device = device def segment(self, image_rgb: np.ndarray, boxes: list[list[int]]) -> np.ndarray: self.predictor.set_image(image_rgb) masks, scores, _ = self.predictor.predict( point_coords=None, point_labels=None, box=boxes, multimask_output=False, ) final_mask = np.zeros(masks.shape[-2:], dtype=np.uint8) for mask in masks: final_mask[mask[0] > 0] = 255 return final_mask这里面极容易踩的一个坑是multimask_output。我第一次跑的时候设成True，结果一张图返回了三个掩码，叠加后一团黑。分割任务里一般用False，模型会给你一个置信度最高的整体mask。如果你要保留多个目标，每个目标的掩码单独预测再合并即可。合并的方式也简单：掩码数组全是0/1或0/255，直接按位或就行。
box参数一定要是二维嵌套数组[[x1, y1, x2, y2]]，不是一维数组[x1,y1,x2,y2]。这个细节点第一次跑的人很容易漏，导致SAM2报shape错误。
3.4 最后把接口串起来
创建app/routers/segment.py：
import io import cv2 import numpy as np from fastapi import APIRouter, Depends, File, UploadFile from fastapi.responses import Response from app.core.security import get_current_user from app.models.detector import Detector from app.models.segmentor import Segmentor router = APIRouter(prefix="/api/v1", tags=["segment"]) detector = None segmentor = None def init_models(): global detector, segmentor if detector is None: detector = Detector("weights/best.pt") segmentor = Segmentor( checkpoint_path="weights/sam2_hiera_large.pt", model_cfg="sam2_hiera_l.yaml", ) @router.post("/segment") async def segment_image( file: UploadFile = File(...), user: str = Depends(get_current_user), ): init_models() contents = await file.read() image_np = cv2.imdecode(np.frombuffer(contents, np.uint8), cv2.IMREAD_COLOR) if image_np is None: return Response(status_code=400, content="Invalid image") image_rgb = cv2.cvtColor(image_np, cv2.COLOR_BGR2RGB) boxes = detector.predict(image_np) if len(boxes) == 0: return Response(status_code=200, content="No object detected") mask = segmentor.segment(image_rgb, boxes.tolist()) # 原图叠加mask输出 overlay = image_rgb.copy() color = np.array([0, 255, 0], dtype=np.uint8) overlay[mask > 0] = (overlay[mask > 0] * 0.5 + color * 0.5).astype(np.uint8) _, encoded = cv2.imencode(".png", cv2.cvtColor(overlay, cv2.COLOR_RGB2BGR)) return Response(content=encoded.tobytes(), media_type="image/png")这里有个真实工程教训：UploadFile的数据是一次性的，你不能“先探测一下是啥图，再传给模型”，因为读完一遍后就为空了。所以我第一步直接imdecode成内存数组，后面所有处理都用这个数组走，不重复读文件流。
init_models由谁负责初始化？这里用了懒加载模式，首次请求时一次性构建。更专业的做法是用FastAPI的lifespan事件，在服务启动时就加载。这里用懒加载是为了让你先看到效果，不至于启动报一堆显存错误时不知所措。生产环境一定要改成启动时加载。判断是否有GPU也建议加入：如果torch.cuda.is_available()为False就自动用CPU，不然在Mac上演示时就尴尬了。
4. 鉴权与业务路由的设计细节
4.1 登录接口与路由注册
创建一个简单的登录接口。先造一个简单用户表（这里用内存字典做演示，生产环境替换成数据库）。
users = { "admin": { "username": "admin", "password": "$2b$12$..." # bcrypt哈希 } }然后路由：
from fastapi import APIRouter, Depends, HTTPException from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm from app.core.security import create_access_token, verify_password router = APIRouter(prefix="/api/v1/auth", tags=["auth"]) @router.post("/login") async def login(form_data: OAuth2PasswordRequestForm = Depends()): user = users.get(form_data.username) if not user or not verify_password(form_data.password, user["password"]): raise HTTPException(status_code=401, detail="Incorrect username or password") access_token = create_access_token(user["username"]) refresh_token = create_refresh_token(user["username"]) return {"access_token": access_token, "refresh_token": refresh_token, "token_type": "bearer"}OAuth2PasswordRequestForm是FastAPI内置的表单解析器，会从请求体里取username和password两个字段，前端用application/x-www-form-urlencoded发就行。这种实现看起来很糙，但配合Swagger UI做联调时体验极佳，可以在文档页面里直接点Authorize输入用户名密码。
生产环境的用户存储显然要用数据库。FastAPI里最顺手的方案是SQLAlchemy 2.0 + PostgreSQL。但这一节的核心是演示JWT鉴权如何落地，所以我刻意没引入数据库依赖。读者替换时注意一点：密码哈希建议用Argon2或bcrypt，不要用MD5或SHA1，哪怕是内部服务。就算你不在乎安全性，安全扫描工具也会因为接口用了弱哈希打回你的上线申请，这比真实被攻破还常见。
4.2 FastAPI的token续签端点
再补一个续签接口：
@router.post("/refresh") async def refresh_token(refresh_token: str): try: payload = decode_token(refresh_token) if payload.get("type") != "refresh": raise HTTPException(status_code=401, detail="Invalid refresh token") new_access = create_access_token(payload["sub"]) return {"access_token": new_access, "token_type": "bearer"} except JWTError: raise HTTPException(status_code=401, detail="Invalid refresh token")有人会问：那refresh_token泄露了怎么办？一个验证过的做法是设置较短的refresh有效期，并在每次刷新后由客户端把旧refresh丢弃。再有就是配合设备指纹校验，将refresh_token和客户端UA绑定，若不一致则拒绝。这套“短期Access+长期Refresh”的模型能在安全性和易用性之间取得很好的平衡。
5. 实测过程与结果分析
5.1 测试环境
- GPU: NVIDIA RTX 3090 24GB
- CPU: AMD Ryzen 9 5950X
- CUDA: 12.4
- PyTorch: 2.4.0
- Python: 3.10.12
5.2 针对不同图像的实测结果
第一组测试用了一张1280x720的包含两个人物的街拍图。YOLO11n检测到person框两个，耗时0.03秒；SAM2基于框分割出人物轮廓，耗时约0.9秒。两张人物mask的边缘质量都很好，发丝边缘略有锯齿但肉眼基本能接受。这个延迟对单张图接口完全够用。
第二组测试用了一张商场广告牌图片，同样是1280x720。YOLO检测耗时0.028秒，SAM2分割耗时1.2秒。由于广告牌本身几何结构相对简单，SAM2这次比预期中更快，mask非常平滑。
第三组是复杂场景：高速路上同时出现卡车、小轿车、行人。YOLO11n在同一张图里检测出了十几个目标，框全喂给SAM2后，整体分割耗时暴增到4.5秒。原因很直接：SAM2对于每个框都要做一次前向推理，框越多耗时越长。优化手段有两类：一是用class筛选，只留业务关心的类别；二是做NMS合并重叠框后，最多取置信度Top 3的框。这样能把时间压回1.2秒以内，且对业务几乎无损。
5.3 鉴权压力测试
我用wrk简单压了一下登录后调用分割接口的鉴权开销，在纯CPU环境下每秒可以处理几百次带Token的请求。JWT的签名和验签开销在HS256算法下大概1毫秒以内，完全不是瓶颈。对比一下如果你每次请求都去数据库里查用户表，那才是真正的瓶颈。所以无状态鉴权在高频GPU服务里的优势非常明显。
5.4 GPU显存占用分析
加载YOLO11n约占用300MB显存，加载SAM2 Large约占用8GB显存。两个模型同时常驻显存后，剩余空间约15GB。对于多人同时请求的场景，如果每张图的batch_size是1，显卡能同时扛住大约10个并发任务而不会OOM。这个量级对多数内部接口够用。如果你要更高并发，注意用torch.cuda.OutOfMemoryError兜底，失败时返回503而不是直接把Worker打崩。
6. 常见问题与排查技巧
6.1 SAM2加载时报错torch.cuda.OutOfMemoryError
几乎每个第一次跑SAM2的人都会遇到。原因多数是SAM2读checkpoint时默认加载Large版本，而显卡显存只有8GB甚至更低。解决办法：换small模型，即把sam2_hiera_small.pt和sam2_hiera_s.yaml配合使用。它显存占用约3GB，分割质量其实也非常够用。工程上的取舍永远是服务于可用性，而不是模型排行榜上的AP值。
6.2 FastAPI上传PNG透明通道图后被OpenCV读成四通道
OpenCV的imdecode默认会保留Alpha通道，mask计算在四通道图上会出现通道数不匹配错误。正确的做法是强制cv2.IMREAD_COLOR转成三通道BGR，或者读取后显式做通道约简。另外，上传WebP、HEIC这类编解码库不支持的格式时，imdecode会返回None，一定要做空值判断，返回400而不是抛个底层异常。
6.3 SAM2的mask尺寸报错
SAM2会维护一个内部图像大小，它接收的输入必须是H*W，它会在内部resize到1024*1024附近。你如果直接塞一个巨大的4K图，显存占用会非常恐怖且速度极慢。建议在传给SAM2之前做最长边限制，比如最长边压到1280或1600。示例参见上面的segmentor代码，如果你用的是set_image，SAM2本身已经做了resize，所以一般没问题，但你会看到它默认会把你的大图缩到1024x1024或1024x768。这意味着超大图的细节会被显著压缩，分割精度会受影响。解决方法是先把图按最长边1600处理，再把坐标缩放回原始图像坐标系。
6.4 高并发下FastAPI阻塞
GPU推理本身是阻塞型任务，如果直接在async函数里调用同步的模型推理，FastAPI的事件循环会被卡死。生产级做法是：用def而不是async def写路由处理函数，让FastAPI自动把请求丢到线程池；或者把模型推理封装成FastAPI的BackgroundTasks。对于短期高并发需求，我个人更推荐让def配合run_in_threadpool跑。一个使用def路由的最简示例：
@router.post("/segment") def segment_image_worker( file: UploadFile = File(...), user: str = Depends(get_current_user), ): ...这时FastAPI会自动跑在线程池里，不会阻塞事件循环。
6.5 JWT校验通过但接口仍报401
大概率是因为Bearer头格式写错了。正确格式是Authorization: Bearer <token>，中间必须有空格。如果你在测试时手动复制token时带了换行符或引号，Python字符串解析会连带引号一起作为token内容。建议先做一个简易的在线解析工具先确认token能解出来，再拿去请求接口。这不丢人，很多人连在Swagger里点Authorize时token尾部多了一个空格导致401，卡了一下午。
6.6 常见问题速查表
| 现象 | 大概率原因 | 处理办法 |
|---|---|---|
FileNotFoundError: checkpoints/... | SAM2权重路径不对 | 把权重放在配置路径下 |
| YOLO11推理全0，无框 | conf阈值太高或模型没加载 | 调低阈值到0.1试跑 |
| mask是全黑/全白 | 颜色通道翻转或mask叠加顺序错误 | 核对BGR/RGB转换 |
| SAM2内部崩溃 | 输入尺寸过大 | 最长边压到1600以下 |
| GPU OOM | SAM2 Large显存占用高 | 换small模型或下降并发 |
| JWT刷新接口401 | refresh_token类型错误 | 检查type字段是否是refresh |
| OpenCV读不了图 | 上传格式不支持 | 先用imdecode返回None判断 |
6.7 补充一个关于“热切加载模型”的经验
实际部署到生产时，不要在每次请求时才加载模型。原因是模型加载涉及文件读取、权重反序列化、CUDA上下文初始化，加载一次就要2～10秒。高并发时第一个请求触发的加载会导致后续请求的同步等待，用户看到的就是“服务器卡死”。正确的实现方式是在main.py的lifespan中初始化全局模型实例：
@asynccontextmanager async def lifespan(app: FastAPI): init_models() yieldFastAPI的启动事件在uvicorn启动后只会执行一次，这个时机加载模型是最合适的。后续接口调用直接用全局变量，而不用在每次调用时判断if detector is None。
7. 性能调优与接口扩展方向
到这里整套系统已经能跑了，但它只是一个开始。如果你想把它放到更大流量或更多业务场景中，有几个方向值得继续做。
第一是在线推理的批处理。YOLO11天生支持batch推理，但SAM2不同batch输入尺度可能不一致，需要做padding或填充，实现复杂度会上升。现阶段如果你单机且有1张3090，把并发控制在10以内基本没问题；要更高吞吐，上vLLM思路的模型服务化系统并不合适，更适合的是用Celery或RQ把推理任务异步化，接口立刻返回task_id，前端轮询结果。这种方法能极大提升接口的可用性，因为无需让HTTP请求一直占着连接等待GPU完成。
第二是引入Redis做缓存。如果你的输入图片是固定的URL资源（比如广告位图片），完全可以在调用分割前先按图片URL哈希查缓存，命中就直接返回已经算好的掩码，省去重复的GPU推理。实测中一张1280x720图的SAM2分割要1秒多，而Redis读一个缓存PNG只要几毫秒，提升是数量级的。
第三是类别白名单控制。假设你的YOLO11模型能检测50类，但业务只关注广告牌和路面受损两类，就在yaml里设置filter_classes: ["billboard", "damage"]。这样可以防止无关目标刷屏，同时减少无意义的GPU开销。
第四是接口层加入Rate Limiting。FastAPI生态里有一个slowapi库，配合Redis能实现简单的滑动窗口限流。比如每个用户每分钟最多调20次分割接口。这一层加上之后，才能真正防住恶意刷接口的情况，否则JWT防的只是“陌生人”，防不住“陌生人拿到一个合法账号后乱刷”。
8. 从拿到代码到生产落地的最后几步
现在模型能跑、鉴权能用，你还差最后几步才能让它扛住真实请求。
第一，改掉“硬编码”的SECRET_KEY。上面代码里用了占位符，线上必须改为从环境变量读取并保证它足够长且随机。你可以用openssl rand -hex 64生成一个256位的密钥，然后放进.env，并通过pydantic-settings读取。千万不要把密钥提交到Git仓库，否则攻击者可以直接伪造任意用户的token。这一步在真实业务上线审查里属于一票否决项。
第二，设置CORS。如果你只能被前端应用调用，跨域是绕不开的话题。FastAPI里加中间件：
app.add_middleware( CORSMiddleware, allow_origins=["https://your-frontend.com"], allow_methods=["*"], allow_headers=["*"], )这里我不建议无脑放行所有allow_origins=["*"]，因为JWT Token本身在Authorization头里，如果放行所有来源，别人可以在浏览器里发起任意跨站请求带着被你信任的凭证打到你的API上。虽然JWT没有Cookie自动携带的问题，但CSRF风险依然存在，保持最小白名单会更稳妥。
第三，设置HTTPS。生产环境不要裸跑HTTP，JWT一旦在HTTP连接中被截获，攻击者就获得了完全访问权。建议Nginx反代+Let's Encrypt证书，一步到位。
第四，给你的日志加上请求ID和耗时统计。FastAPI里写个中间件，给每个请求生成uuid并打印开始结束时间。模型推理挂了的时候，拿着request_id查日志，才能快速定位是网络问题、上传图片损坏还是显存不足。
9. 性能压测实验结果
最后附一组我在3090上做的简单压测数据。图片是1280x720单目标图，开启鉴权和关闭鉴权各测100次：
| 配置 | 平均单次耗时 | P99耗时 | 备注 |
|---|---|---|---|
| 关闭鉴权，GPU推理 | 0.93s | 1.4s | SAM2占大头 |
| 开启鉴权，GPU推理 | 0.94s | 1.5s | JWT消耗可忽略 |
| CPU推理（无GPU） | 5.8s | 8s | 仅应急用 |
| YOLO检测（GPU） | 0.03s | 0.08s | 不是瓶颈 |
从表里能清楚看到，如果要做并发优化，核心是缩短SAM2的推理时间。除非业务要求极低延迟，否则单卡并发10个任务以内问题不大。若确实需要低延迟，把SAM2的模型换成sam2_hiera_small.pt会显著提升速度，部分场景可降到0.3~0.5秒。
我个人在实际操作中的体会是：这套方案最大的坑不在模型本身，而在工程衔接。YOLO的框传给SAM2之前要先做坐标缩放，SAM2输出的mask要恢复成原图尺寸再叠加。很多人到最后发现分割区域和物体对不上，80%的原因就是resize前后坐标没做映射。给个经验值：如果你在原图上直接跑检测，检测框坐标就是原图坐标，不需要乘缩放比；但如果你把图先缩放到640再跑检测，拿到坐标后必须按比例还原到原图尺寸，再去SAM2里用。这一步写错，分割框就会整体偏移，看起来“有点准但总是不稳”。我自己吃过几次亏之后，习惯把“图像预处理-推理-后处理”三个阶段的坐标系变化全部打印到日志里，联调时能省一晚上。
最后再分享一个小技巧：如果你的业务需要支持“按URL传图”，不要直接把SDK里的requests.get那套包装成同步接口就扔给FastAPI。网关层异步请求库httpx.AsyncClient可以让你在async路由函数里快速下载图片，然后扔进线程池里跑模型推理。既保住了异步消息循环的活跃度，又不会因为网络下载导致每秒并发能力骤降。这套组合跑了两周之后，没有出现过一次Worker崩溃和接口超时，至少说明生产环境里它是站得住脚的。你要是真想把它推上线，强烈建议从“懒加载模型”改成lifespan启动加载，否则一旦某个请求触发了模型加载，后面排队的请求全部会互相踩踏导致雪崩。代码和配置细节我都放上面的目录结构里了，照抄即可。祝你的分割服务上线顺利。
