# 图片物体智能标注系统 - 实施文档 ## 📋 项目概述 ### 功能描述 用户在对话框中上传图片后，可以通过点击图片预览中的"定位标注"按钮，点击图片中的任意物体，系统自动识别该物体的名称（包括颜色、材质等详细信息），并将识别结果以特殊格式自动填入对话框。 ### 使用场景示例 1. 用户上传两张图片 2. 点击第一张图中的"绿色手提包" → 输入框自动添加：`📍图1: 绿色手提包` 3. 点击第二张图中的"红色背包" → 输入框继续添加：`📍图2: 红色背包` 4. 用户手动输入"替换" → 最终输入框内容：`将📍图1: 绿色手提包 替换成 📍图2: 红色背包` --- ## 🏗️ 技术架构 ### 方案选择：Florence-2 **选择理由**： - ✅ **零配置**：不需要预定义物体类别 - ✅ **速度快**：推理时间 0.5-1秒 - ✅ **识别准确**：自动识别颜色、材质、细节 - ✅ **轻量级**：模型仅 230MB - ✅ **多任务支持**：物体检测、区域描述、OCR 等 ### 系统架构图 ``` ┌─────────────────────────────────────────────────────────┐ │ 前端 (React) │ ├─────────────────────────────────────────────────────────┤ │ 1. MultimodalInput (上传图片) │ │ 2. ImagePreview (图片预览 + 标注按钮) │ │ 3. ObjectAnnotation (点击检测 + 标注UI) │ └─────────────────┬───────────────────────────────────────┘ │ HTTP POST ▼ ┌─────────────────────────────────────────────────────────┐ │ 后端 API (FastAPI) │ ├─────────────────────────────────────────────────────────┤ │ POST /api/detect-object │ │ - 接收图片 URL 和点击坐标 │ │ - 裁剪点击区域 │ │ - 调用 Florence-2 模型 │ │ - 返回物体描述 │ └─────────────────┬───────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Florence-2 模型服务 │ ├─────────────────────────────────────────────────────────┤ │ - 加载预训练模型 (microsoft/Florence-2-base) │ │ - 图像预处理 │ │ - 推理生成物体描述 │ │ - 中英文翻译（可选） │ └─────────────────────────────────────────────────────────┘ ``` --- ## 🔧 实施步骤 ### 阶段一：后端 API 开发（第1-2天） #### 1.1 环境准备 **服务器要求**： - CPU: 8核或以上（如果使用 GPU，CPU 要求可降低） - 内存: 16GB 或以上 - GPU: NVIDIA GPU（推荐，支持 CUDA 11.8+） - 显存: 4GB 或以上（推荐 8GB） - 驱动: 最新版 NVIDIA 驱动 - 存储: 10GB 可用空间 - Python: 3.9+ **安装依赖**： **步骤 1：检查 GPU 是否可用** ```bash # 检查 NVIDIA 驱动 nvidia-smi # 查看 CUDA 版本 nvcc --version ``` **步骤 2：安装 Python 依赖** ```bash # 创建 Python 虚拟环境 cd /var/www/ai-chatbot-backend python3 -m venv venv source venv/bin/activate # 安装核心依赖 pip install fastapi uvicorn python-multipart # 🚀 GPU 加速版本（推荐，如果有 NVIDIA GPU） pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # 或者使用国内镜像（更快） pip install torch torchvision -i https://pypi.tuna.tsinghua.edu.cn/simple # CPU 版本（如果没有 GPU） # pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu # 其他依赖 pip install transformers pillow requests pip install openai # 用于调用翻译 API（可选） ``` **步骤 3：验证 GPU 可用性** ```bash python -c "import torch; print(f'CUDA 可用: {torch.cuda.is_available()}'); print(f'GPU 数量: {torch.cuda.device_count()}'); print(f'GPU 名称: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else \"N/A\"}')" ``` 预期输出（如果 GPU 可用）： ``` CUDA 可用: True GPU 数量: 1 GPU 名称: NVIDIA GeForce RTX 3090 ``` #### 1.2 下载 Florence-2 模型 **方式一：自动下载（推荐）** ```python from transformers import AutoProcessor, AutoModelForCausalLM # 首次运行会自动下载模型（约 230MB） model = AutoModelForCausalLM.from_pretrained( "microsoft/Florence-2-base", trust_remote_code=True ) processor = AutoProcessor.from_pretrained( "microsoft/Florence-2-base", trust_remote_code=True ) ``` **方式二：手动下载（网络受限时）** ```bash # 使用魔搭社区镜像（国内访问更快） pip install modelscope modelscope download --model=AI-ModelScope/Florence-2-base --local_dir ./models/florence-2 ``` #### 1.3 创建 API 服务 **文件结构**： ``` /var/www/ai-chatbot-backend/ ├── app/ │ ├── api/ │ │ └── detect_object.py # 物体检测 API │ ├── services/ │ │ └── florence_service.py # Florence-2 服务封装 │ ├── utils/ │ │ ├── image_utils.py # 图片处理工具 │ │ └── translation.py # 中英文翻译 │ └── main.py # FastAPI 主入口 ├── models/ # 模型文件目录 ├── requirements.txt └── start.sh # 启动脚本 ``` **核心代码实现**（详见下文"代码实现"章节） #### 1.4 API 端点设计 **POST /api/detect-object** **请求参数**： ```typescript { "imageUrl": string, // 图片 URL（S3 地址） "clickX": number, // 点击 X 坐标（像素） "clickY": number, // 点击 Y 坐标（像素） "imageIndex": number, // 图片序号（从 1 开始） "imageWidth": number, // 图片原始宽度 "imageHeight": number // 图片原始高度 } ``` **响应格式**： ```typescript { "success": boolean, "data": { "description": string, // 物体描述（中文）："绿色皮革手提包" "descriptionEn": string, // 物体描述（英文）："green leather handbag" "confidence": number, // 置信度（0-1） "imageIndex": number, // 图片序号 "formattedText": string // 格式化文本："📍图1: 绿色皮革手提包" }, "error": string | null } ``` **错误响应**： ```typescript { "success": false, "data": null, "error": "无法识别该区域的物体，请点击更明显的物体位置" } ``` --- ### 阶段二：前端组件开发（第3-4天） #### 2.1 修改 ImagePreview 组件 **文件**：`components/image-preview.tsx` **新增功能**： 1. 添加"定位标注"模式切换按钮 2. 在标注模式下，鼠标悬停显示准星光标 3. 点击时发送请求到后端 API 4. 显示加载状态和识别结果 5. 将结果传递给父组件 **UI 设计**： ``` ┌──────────────────────────────────────────┐ │ ← 返回 📍 定位标注 ⬇️ 下载 │ ← 顶部工具栏 ├──────────────────────────────────────────┤ │ │ │ │ │ [图片显示区域] │ │ （标注模式下显示准星） │ │ │ │ │ ├──────────────────────────────────────────┤ │ 识别中... 🔍 │ ← 底部状态栏（可选） └──────────────────────────────────────────┘ ``` #### 2.2 修改 MultimodalInput 组件 **文件**：`components/multimodal-input.tsx` **新增功能**： 1. 接收来自 `ImagePreview` 的标注结果 2. 将标注文本插入到输入框中 3. 使用特殊样式显示标注文本（蓝色、带图标） 4. 支持多次标注，文本自动追加 **输入框样式**： ``` ┌──────────────────────────────────────────────────────────┐ │ 将 [📍图1: 绿色手提包] 替换成 [📍图2: 红色背包] │ │ ↑ 蓝色、可点击 ↑ 蓝色、可点击 │ └──────────────────────────────────────────────────────────┘ ``` #### 2.3 创建标注文本组件 **新建文件**：`components/annotation-tag.tsx` **功能**： - 显示标注标签（如 `📍图1: 绿色手提包`） - 支持点击删除 - 特殊样式（蓝色背景、圆角、图标） **样式示例**： ```tsx 📍图1: 绿色手提包 ``` --- ### 阶段三：集成与测试（第5天） #### 3.1 本地开发测试 **启动后端**： ```bash cd /var/www/ai-chatbot-backend source venv/bin/activate python app/main.py # 访问 http://localhost:8001/docs 查看 API 文档 ``` **启动前端**： ```bash cd /var/www/ai-chatbot npm run dev # 访问 http://localhost:3000 ``` **测试流程**： 1. 上传测试图片（包含明显物体） 2. 点击"定位标注"按钮 3. 点击图片中的物体 4. 验证识别结果是否准确 5. 验证文本是否正确插入输入框 #### 3.2 性能测试 **测试指标**： - 单次识别耗时：< 1秒 - 并发请求数：10 QPS - 内存占用：< 2GB **测试命令**： ```bash # 使用 Apache Bench 测试 ab -n 100 -c 10 -p test_data.json -T application/json \ http://localhost:8001/api/detect-object ``` #### 3.3 边缘情况测试 **测试场景**： 1. 点击图片空白区域（无物体） 2. 点击模糊不清的区域 3. 上传黑白图片 4. 上传极小/极大图片 5. 快速连续点击多次 **预期处理**： - 返回友好的错误提示 - 不崩溃、不卡死 - 有重试机制 --- ### 阶段四：生产部署（第6天） #### 4.1 后端部署 **使用 PM2 管理进程**： ```bash # 安装 PM2 npm install -g pm2 # 创建 PM2 配置文件 cat > ecosystem.config.js << EOF module.exports = { apps: [{ name: 'florence-api', script: '/var/www/ai-chatbot-backend/venv/bin/python', args: '/var/www/ai-chatbot-backend/app/main.py', instances: 1, exec_mode: 'fork', max_memory_restart: '2G', env: { PORT: 8001, MODEL_PATH: '/var/www/ai-chatbot-backend/models/florence-2' } }] } EOF # 启动服务 pm2 start ecosystem.config.js pm2 save ``` **Nginx 反向代理**： ```nginx # /etc/nginx/sites-available/ai-chatbot # 新增后端 API 代理 location /api/detect-object { proxy_pass http://127.0.0.1:8001; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection 'upgrade'; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; # 增加超时时间（因为 AI 推理需要时间） proxy_connect_timeout 10s; proxy_send_timeout 10s; proxy_read_timeout 10s; } ``` #### 4.2 前端部署 **构建生产版本**： ```bash cd /var/www/ai-chatbot npm run build pm2 restart ai-chatbot ``` #### 4.3 监控与日志 **设置日志轮转**： ```bash # 查看 Florence API 日志 pm2 logs florence-api # 设置日志文件大小限制 pm2 install pm2-logrotate pm2 set pm2-logrotate:max_size 100M pm2 set pm2-logrotate:retain 7 ``` **监控指标**： - API 响应时间 - 错误率 - 内存/CPU 使用率 - 请求 QPS --- ## 💻 代码实现 ### 1. 后端 API 实现 #### `app/main.py` - FastAPI 主入口 ```python from fastapi import FastAPI, HTTPException from fastapi.middleware.cors import CORSMiddleware from pydantic import BaseModel import uvicorn from app.services.florence_service import FlorenceService app = FastAPI(title="Florence-2 物体检测 API") # CORS 配置 app.add_middleware( CORSMiddleware, allow_origins=["https://ai.yydd.ai", "http://localhost:3000"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) # 初始化 Florence 服务（全局单例） florence_service = FlorenceService() class DetectRequest(BaseModel): imageUrl: str clickX: int clickY: int imageIndex: int imageWidth: int imageHeight: int class DetectResponse(BaseModel): success: bool data: dict | None error: str | None @app.on_event("startup") async def startup_event(): """启动时加载模型""" print("🚀 正在加载 Florence-2 模型...") await florence_service.load_model() print("✅ 模型加载完成！") @app.post("/api/detect-object", response_model=DetectResponse) async def detect_object(request: DetectRequest): """检测图片中点击位置的物体""" try: result = await florence_service.detect_object_at_point( image_url=request.imageUrl, click_x=request.clickX, click_y=request.clickY, image_index=request.imageIndex, image_width=request.imageWidth, image_height=request.imageHeight ) return DetectResponse( success=True, data=result, error=None ) except Exception as e: print(f"❌ 检测失败: {str(e)}") return DetectResponse( success=False, data=None, error=f"物体识别失败: {str(e)}" ) @app.get("/health") async def health_check(): """健康检查""" return {"status": "ok", "model_loaded": florence_service.is_loaded} if __name__ == "__main__": uvicorn.run(app, host="0.0.0.0", port=8001) ``` #### `app/services/florence_service.py` - Florence-2 服务 ```python import torch from transformers import AutoProcessor, AutoModelForCausalLM from PIL import Image import requests from io import BytesIO import asyncio class FlorenceService: def __init__(self): self.model = None self.processor = None self.is_loaded = False # 🚀 自动检测并使用 GPU（如果可用） self.device = "cuda" if torch.cuda.is_available() else "cpu" print(f"🎯 使用设备: {self.device}") if self.device == "cuda": print(f"🚀 GPU 加速已启用: {torch.cuda.get_device_name(0)}") print(f"💾 GPU 显存: {torch.cuda.get_device_properties(0).total_memory / 1024**3:.1f} GB") async def load_model(self): """异步加载模型""" if self.is_loaded: return loop = asyncio.get_event_loop() await loop.run_in_executor(None, self._load_model_sync) def _load_model_sync(self): """同步加载模型（在线程池中执行）""" print("📦 下载 Florence-2 模型...") self.model = AutoModelForCausalLM.from_pretrained( "microsoft/Florence-2-base", trust_remote_code=True ).to(self.device) self.processor = AutoProcessor.from_pretrained( "microsoft/Florence-2-base", trust_remote_code=True ) self.is_loaded = True print("✅ Florence-2 模型加载完成") async def detect_object_at_point( self, image_url: str, click_x: int, click_y: int, image_index: int, image_width: int, image_height: int ) -> dict: """检测点击位置的物体""" # 1. 下载图片 print(f"📥 下载图片: {image_url}") response = requests.get(image_url, timeout=10) image = Image.open(BytesIO(response.content)).convert("RGB") # 2. 计算裁剪区域（以点击点为中心，200x200 像素） crop_size = 200 left = max(0, click_x - crop_size // 2) top = max(0, click_y - crop_size // 2) right = min(image_width, click_x + crop_size // 2) bottom = min(image_height, click_y + crop_size // 2) print(f"✂️ 裁剪区域: ({left}, {top}, {right}, {bottom})") cropped_image = image.crop((left, top, right, bottom)) # 3. 使用 Florence-2 识别物体 print("🔍 正在识别物体...") loop = asyncio.get_event_loop() description = await loop.run_in_executor( None, self._detect_sync, cropped_image ) # 4. 翻译成中文（如果是英文） description_cn = await self._translate_to_chinese(description) # 5. 格式化返回结果 formatted_text = f"📍图{image_index}: {description_cn}" return { "description": description_cn, "descriptionEn": description, "confidence": 0.95, # Florence-2 不返回置信度，固定值 "imageIndex": image_index, "formattedText": formatted_text } def _detect_sync(self, image: Image.Image) -> str: """同步推理（在线程池中执行）""" # 使用 任务生成简短描述 prompt = "" inputs = self.processor( text=prompt, images=image, return_tensors="pt" ).to(self.device) # 生成描述 with torch.no_grad(): generated_ids = self.model.generate( input_ids=inputs["input_ids"], pixel_values=inputs["pixel_values"], max_new_tokens=50, num_beams=3, do_sample=False ) # 解码结果 generated_text = self.processor.batch_decode( generated_ids, skip_special_tokens=False )[0] # 提取描述（去除提示词） description = generated_text.replace(prompt, "").strip() print(f"✅ 识别结果: {description}") return description async def _translate_to_chinese(self, text: str) -> str: """翻译成中文（简单的关键词映射）""" # 方案1: 简单的关键词映射（快速、离线） keyword_map = { "red": "红色", "green": "绿色", "blue": "蓝色", "yellow": "黄色", "black": "黑色", "white": "白色", "brown": "棕色", "pink": "粉色", "purple": "紫色", "orange": "橙色", "gray": "灰色", "handbag": "手提包", "backpack": "背包", "bag": "包", "shoe": "鞋子", "hat": "帽子", "glasses": "眼镜", "chair": "椅子", "table": "桌子", "sofa": "沙发", "bed": "床", "person": "人", "car": "汽车", "cat": "猫", "dog": "狗", "leather": "皮革", "cloth": "布料", "plastic": "塑料", "metal": "金属", "wooden": "木制", } # 简单替换 result = text.lower() for en, cn in keyword_map.items(): result = result.replace(en, cn) # 如果没有翻译成功，返回原文 if result == text.lower(): return text return result # 方案2: 调用翻译 API（可选，需要额外配置） # from app.utils.translation import translate # return await translate(text, target_lang="zh") ``` #### `requirements.txt` - Python 依赖 ```txt fastapi==0.109.0 uvicorn[standard]==0.27.0 python-multipart==0.0.6 pydantic==2.5.3 torch==2.1.2 torchvision==0.16.2 transformers==4.37.0 pillow==10.2.0 requests==2.31.0 ``` --- ### 2. 前端组件实现 #### `components/image-preview.tsx` - 修改 ```typescript "use client"; import { Dialog, DialogContent } from "@/components/ui/dialog"; import { Button } from "@/components/ui/button"; import { X, Download, Target } from "lucide-react"; import Image from "next/image"; import { useState } from "react"; import { toast } from "sonner"; interface ImagePreviewProps { isOpen: boolean; imageUrl: string; imageIndex: number; onClose: () => void; onAnnotate?: (annotation: { imageIndex: number; description: string; formattedText: string; }) => void; } export function ImagePreview({ isOpen, imageUrl, imageIndex, onClose, onAnnotate, }: ImagePreviewProps) { const [isAnnotationMode, setIsAnnotationMode] = useState(false); const [isDetecting, setIsDetecting] = useState(false); const handleImageClick = async (e: React.MouseEvent) => { if (!isAnnotationMode || isDetecting) return; const rect = e.currentTarget.getBoundingClientRect(); const clickX = Math.round(e.clientX - rect.left); const clickY = Math.round(e.clientY - rect.top); setIsDetecting(true); toast.info("正在识别物体..."); try { const response = await fetch("/api/detect-object", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ imageUrl, clickX, clickY, imageIndex, imageWidth: rect.width, imageHeight: rect.height, }), }); const result = await response.json(); if (result.success && result.data) { toast.success(`识别成功：${result.data.description}`); onAnnotate?.({ imageIndex: result.data.imageIndex, description: result.data.description, formattedText: result.data.formattedText, }); onClose(); } else { toast.error(result.error || "识别失败，请重试"); } } catch (error) { console.error("物体检测失败:", error); toast.error("识别失败，请检查网络连接"); } finally { setIsDetecting(false); } }; const handleDownload = () => { const link = document.createElement("a"); link.href = imageUrl; link.download = `image-${imageIndex}.png`; document.body.appendChild(link); link.click(); document.body.removeChild(link); }; return ( {/* 顶部工具栏 */}
{/* 图片显示区域 */}
{`图片 {isAnnotationMode && (
点击图片中的物体进行标注
)} {isDetecting && (
正在识别...
)}
); } ``` #### `components/multimodal-input.tsx` - 修改（部分） 在现有的 `MultimodalInput` 组件中添加： ```typescript // 在组件顶部添加状态 const [annotations, setAnnotations] = useState>([]); // 添加标注处理函数 const handleAnnotate = (annotation: { imageIndex: number; description: string; formattedText: string; }) => { setAnnotations((prev) => [...prev, annotation]); // 自动插入到输入框 setInput((prev) => { if (prev) { return `${prev} ${annotation.formattedText}`; } return annotation.formattedText; }); }; // 在 PreviewAttachment 组件调用时传递 onAnnotate handleRemoveAttachment(attachment.url)} onAnnotate={handleAnnotate} // 新增 imageIndex={index + 1} // 新增 /> ``` #### `components/preview-attachment.tsx` - 修改 ```typescript // 添加新的 props interface PreviewAttachmentProps { attachment: Attachment; onRemove: () => void; onAnnotate?: (annotation: any) => void; // 新增 imageIndex?: number; // 新增 // ... 其他 props } // 在图片点击处理中打开预览 const handleImageClick = () => { setShowPreview(true); }; // 渲染 ImagePreview {showPreview && ( setShowPreview(false)} onAnnotate={onAnnotate} /> )} ``` --- ## 🚀 部署脚本 ### `deploy.sh` - 一键部署脚本 ```bash #!/bin/bash echo "🚀 开始部署 Florence-2 物体检测系统..." # 1. 部署后端 echo "📦 部署后端 API..." cd /var/www/ai-chatbot-backend # 激活虚拟环境 source venv/bin/activate # 安装/更新依赖 pip install -r requirements.txt # 下载模型（如果未下载） python -c "from app.services.florence_service import FlorenceService; s = FlorenceService(); s._load_model_sync()" # 重启服务 pm2 restart florence-api || pm2 start ecosystem.config.js echo "✅ 后端部署完成" # 2. 部署前端 echo "📦 部署前端..." cd /var/www/ai-chatbot # 构建 npm run build # 重启服务 pm2 restart ai-chatbot echo "✅ 前端部署完成" # 3. 重启 Nginx echo "🔄 重启 Nginx..." sudo nginx -t && sudo systemctl reload nginx echo "" echo "🎉 部署完成！" echo "" echo "📝 检查服务状态:" echo " pm2 status" echo "" echo "📊 查看日志:" echo " pm2 logs florence-api" echo " pm2 logs ai-chatbot" echo "" echo "🌐 访问地址:" echo " https://ai.yydd.ai" echo "" ``` --- ## 🧪 测试计划 ### 功能测试 | 测试项 | 测试步骤 | 预期结果 | |--------|---------|---------| | 基础识别 | 上传包含明显物体的图片，点击物体 | 正确识别物体名称和颜色 | | 多图标注 | 上传多张图片，分别点击标注 | 每张图片的标注独立，序号正确 | | 颜色识别 | 点击不同颜色的同类物体 | 能区分颜色（如红色包、绿色包） | | 空白区域 | 点击图片空白处 | 提示"无法识别物体" | | 模糊图片 | 上传模糊图片并点击 | 尽可能识别，或提示图片质量问题 | | 快速点击 | 连续快速点击多次 | 不重复识别，有防抖机制 | ### 性能测试 | 指标 | 目标值 | 测试方法 | |------|--------|----------| | 单次推理时间 | < 1秒 | 使用计时器测量 | | 并发处理能力 | 10 QPS | Apache Bench 压测 | | 内存占用 | < 2GB | `top` 命令监控 | | 错误率 | < 1% | 压测统计 | --- ## 🚀 GPU 加速配置（推荐） 如果您的服务器有 NVIDIA GPU，强烈建议启用 GPU 加速，可以将推理速度从 0.5-1 秒降低到 **0.1-0.3 秒**！ ### 1. 检查 GPU 状态 ```bash # 检查 GPU 信息 nvidia-smi # 输出示例： # +-----------------------------------------------------------------------------+ # | NVIDIA-SMI 525.125.06 Driver Version: 525.125.06 CUDA Version: 12.0 | # |-------------------------------+----------------------+----------------------+ # | GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC | # | 0 NVIDIA RTX 3090 Off | 00000000:01:00.0 Off | N/A | # +-----------------------------------------------------------------------------+ ``` ### 2. 安装 CUDA 版本的 PyTorch ```bash # 进入虚拟环境 cd /var/www/ai-chatbot-backend source venv/bin/activate # 安装 CUDA 版本（根据您的 CUDA 版本选择） # CUDA 11.8 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 # CUDA 12.1 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 # 或使用国内镜像（更快） pip install torch torchvision -i https://pypi.tuna.tsinghua.edu.cn/simple ``` ### 3. 验证 GPU 可用性 ```bash python << EOF import torch print(f"PyTorch 版本: {torch.__version__}") print(f"CUDA 可用: {torch.cuda.is_available()}") print(f"CUDA 版本: {torch.version.cuda}") print(f"GPU 数量: {torch.cuda.device_count()}") if torch.cuda.is_available(): print(f"GPU 名称: {torch.cuda.get_device_name(0)}") print(f"GPU 显存: {torch.cuda.get_device_properties(0).total_memory / 1024**3:.1f} GB") EOF ``` ### 4. 性能对比 | 设备 | 推理时间 | 吞吐量 | 内存占用 | |------|---------|--------|---------| | CPU（8核） | 0.5-1秒 | 1-2 QPS | 1.5GB | | GPU（RTX 3090） | 0.1-0.2秒 | 5-10 QPS | 2GB（显存） | | GPU（T4） | 0.2-0.3秒 | 3-5 QPS | 2GB（显存） | | GPU（V100） | 0.15-0.25秒 | 4-7 QPS | 2GB（显存） | > 💡 **推荐配置**：RTX 3060 或以上，显存 ≥ 6GB ### 5. GPU 监控 ```bash # 实时监控 GPU 使用率 watch -n 1 nvidia-smi # 查看 GPU 进程 nvidia-smi pmon # 记录 GPU 使用日志 nvidia-smi dmon -s pucvmet -f gpu_usage.log ``` ### 6. 故障排查 #### 问题 1：`torch.cuda.is_available()` 返回 False **解决方案**： ```bash # 1. 检查 NVIDIA 驱动 nvidia-smi # 如果报错，需要重新安装驱动 # 2. 检查 CUDA 工具包 nvcc --version # 如果找不到命令，需要安装 CUDA Toolkit # 3. 重新安装 PyTorch（确保版本匹配） pip uninstall torch torchvision pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 ``` #### 问题 2：显存不足（CUDA out of memory） **解决方案**： ```python # 方法1: 减小批处理大小（在代码中已经是单张推理，无需调整） # 方法2: 清空 GPU 缓存 import torch torch.cuda.empty_cache() # 方法3: 使用半精度推理（FP16） model = model.half() # 转换为 FP16 ``` #### 问题 3：推理速度慢（GPU 利用率低） **原因**：首次推理会有模型编译开销 **解决方案**： ```python # 在启动时预热模型 @app.on_event("startup") async def warmup(): print("🔥 正在预热模型...") dummy_image = Image.new("RGB", (224, 224), color="red") await florence_service.detect_object_at_point( image_url="dummy", click_x=112, click_y=112, image_index=1, image_width=224, image_height=224 ) print("✅ 模型预热完成") ``` --- ## ⚠️ 注意事项 ### 1. 模型准确度限制 Florence-2 是通用视觉模型，可能存在以下情况： - 小物体或远景物体识别不准确 - 罕见物体可能无法识别 - 颜色描述可能不够精确（如"深蓝"和"浅蓝"） **解决方案**： - 引导用户点击明显、清晰的物体 - 提供"重新识别"按钮 - 允许用户手动编辑识别结果 ### 2. 性能优化 **模型缓存**： - 模型加载到内存后常驻，避免重复加载 - 使用全局单例模式 **图片缓存**： - 对于同一张图片的多次点击，缓存下载的图片 - 使用 LRU 缓存策略，限制内存占用 **并发控制**： - 使用队列限制并发推理数量 - 避免 OOM（内存溢出） ### 3. 用户体验优化 **加载状态**： - 首次使用时提示"模型加载中" - 识别过程中显示加载动画 - 预估等待时间（约 0.5-1秒） **错误处理**： - 网络错误：提示"网络连接失败，请重试" - 识别失败：提示"无法识别该区域，请点击更明显的位置" - 服务异常：提示"服务暂时不可用，请稍后再试" --- ## 📊 项目进度表 | 阶段 | 任务 | 预计时间 | 负责人 | |------|------|---------|--------| | 阶段一 | 后端 API 开发 | 2天 | 后端开发 | | 阶段二 | 前端组件开发 | 2天 | 前端开发 | | 阶段三 | 集成与测试 | 1天 | 全栈 | | 阶段四 | 生产部署 | 1天 | 运维 | | **总计** | - | **6天** | - | --- ## 🔮 未来扩展 ### 1. 支持更多识别任务 - **OCR 文字识别**：识别图片中的文字 - **区域分割**：精确标注物体边界 - **多物体标注**：一次点击识别多个物体 ### 2. 用户反馈机制 - 允许用户纠正错误的识别结果 - 收集用户反馈，优化模型 ### 3. 自定义类别 - 允许用户上传自己的物体类别 - 支持小样本学习（Few-shot Learning） --- ## 📚 参考资料 1. [Florence-2 官方论文](https://arxiv.org/abs/2311.06242) 2. [Hugging Face - Florence-2 文档](https://huggingface.co/microsoft/Florence-2-base) 3. [FastAPI 官方文档](https://fastapi.tiangolo.com/) 4. [Next.js 官方文档](https://nextjs.org/docs) --- ## 📞 技术支持 如有问题，请联系开发团队。 **文档版本**: v1.0 **更新日期**: 2025-12-15 **作者**: AI Chatbot 开发团队