一、项目概述本项目是一个基于FastAPI OpenCV的图片相似度自动检测系统实现上传 → 预处理 → 多算法综合比对 → 邮件报表推送的全自动无人值守流水线。适用于版权图片监测、商品图片查重、标准图库匹配等场景。核心功能功能说明Web 拖拽上传支持 JPG/PNG/BMP/GIF/WebP/TIFF最大 20MB自动预处理等比缩放至 800×800 高斯去噪5 种算法综合评分加权融合结果更准确历史记录管理SQLite 持久化存储可回溯查询自动邮件推送每次上传后自动发送 HTML 报表二、核心技术点详解2.1 技术架构┌──────────────────────────────────────────────────┐ │ 前端 (HTML/CSS/JS) │ │ 拖拽上传 · 结果展示 · 历史查询 │ └─────────────────────┬────────────────────────────┘ │ HTTP/REST ┌─────────────────────▼────────────────────────────┐ │ FastAPI 后端 (Python) │ │ │ │ app.py ── 主应用编排流水线 │ │ ├── image_processor.py ── 图片预处理 │ │ ├── similarity.py ── 5种算法比对引擎 │ │ ├── database.py ── SQLite 增删改查 │ │ ├── report_generator.py ── HTML报表生成 │ │ └── email_service.py ── SMTP邮件发送 │ └────────────────────────────────────────────────────┘2.2 五种相似度算法系统采用加权融合策略综合评判兼顾结构、颜色、纹理、局部特征等多个维度。(1) pHash — 感知哈希权重 0.30原理对图片进行 DCT离散余弦变换提取低频系数生成 256 位二进制指纹。不受缩放、亮度微调、JPEG 压缩等影响。# similarity.py 核心实现 hash1 imagehash.phash(pil1, hash_size16) # 16x16 → 256位 distance abs(hash1 - hash2) # 汉明距离 score 1.0 - (distance / 256) # 距离 → 相似度适用场景需要忽略压缩/缩放差异的整体结构比对。(2) dHash — 差异哈希权重 0.15原理逐行比较相邻像素的大小关系对渐变和亮度变化敏感。hash1 imagehash.dhash(pil1, hash_size16) distance abs(hash1 - hash2) score 1.0 - (distance / 256)与 pHash 互补dHash 对渐变敏感能区分 pHash 无法区分的色调差异。(3) SSIM — 结构相似性权重 0.30原理从亮度、对比度、结构三个维度建模最接近人眼视觉感知。来自scikit-image库。from skimage.metrics import structural_similarity as ssim score, _ ssim(gray1, gray2, fullTrue, data_range255)为什么权重高SSIM 是公认最接近人类判定的客观指标对两图是否为同一内容的判断最为准确。(4) 直方图比较权重 0.15原理统计 R/G/B 三通道像素分布用相关性系数衡量颜色分布相似度。for channel in range(3): hist1 cv2.calcHist([img1_bgr], [channel], None, [256], [0, 256]) hist2 cv2.calcHist([img2_bgr], [channel], None, [256], [0, 256]) score cv2.compareHist(hist1, hist2, cv2.HISTCMP_CORREL)适用场景同内容不同色调如加了滤镜的图片判定。(5) ORB 特征匹配权重 0.10原理提取 500 个 FAST 角点 BRIEF 描述子使用 FLANN 匹配器 Lowes ratio test (0.75) 筛选优质匹配点。orb cv2.ORB_create(nfeatures500) kp1, des1 orb.detectAndCompute(gray1, None) # ... FLANN 匹配 Lowes ratio test score len(good_matches) / max(min(len(kp1), len(kp2)), 1)适用场景图片存在旋转、裁剪、局部遮挡等情况。权重设计逻辑算法权重设计理由pHash30%核心结构判断抗压缩SSIM30%最接近人眼感知准确率最高dHash15%作为 pHash 的补充直方图15%颜色维度不可或缺ORB10%辅助抗旋转/裁剪但噪声较大2.3 图片预处理管道# image_processor.py def preprocess_image(path): img cv2.imread(path) # 保持宽高比缩放至 800x800 h, w img.shape[:2] scale min(800/h, 800/w) new_w, new_h int(w*scale), int(h*scale) img cv2.resize(img, (new_w, new_h)) # 高斯去噪 img cv2.GaussianBlur(img, (3, 3), 0) return img预处理目的统一输入尺寸、去除拍摄噪点确保后续 5 种算法在公平条件下比对。2.4 数据库设计 (SQLite)三张表协作完成数据持久化-- 1. 上传记录表 CREATE TABLE upload_records ( id INTEGER PRIMARY KEY AUTOINCREMENT, filename TEXT, saved_path TEXT, file_size INTEGER, width INTEGER, height INTEGER, upload_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); ​ -- 2. 比对结果表一对多 CREATE TABLE comparison_results ( id INTEGER PRIMARY KEY AUTOINCREMENT, upload_id INTEGER, standard_image TEXT, phash_score REAL, dhash_score REAL, ssim_score REAL, histogram_score REAL, orb_score REAL, final_score REAL, -- 加权综合分 best_match INTEGER DEFAULT 0, -- 1最佳匹配 FOREIGN KEY (upload_id) REFERENCES upload_records(id) ); ​ -- 3. 标准图库表 CREATE TABLE standard_library ( id INTEGER PRIMARY KEY AUTOINCREMENT, filename TEXT, filepath TEXT, file_size INTEGER, width INTEGER, height INTEGER );2.5 邮件推送机制支持SSL (端口 465)和STARTTLS (端口 587)两种加密方式邮件内容包含本次评分明细带进度条颜色编码 历史汇总统计完善的异常处理认证失败、收件人拒绝、网络超时等分数颜色编码分数区间颜色含义≥ 85% 绿色高度相似65% - 85% 橙色中度相似 65% 红色差异较大三、如何运行3.1 环境要求Python 3.9pipWindows / macOS / Linux 均可3.2 方式一一键启动Windows双击项目根目录下的start.bat脚本会自动检查 Python 是否安装安装所有依赖包启动 FastAPI 服务监听0.0.0.0:80803.3 方式二手动启动# 1. 进入后端目录 cd backend ​ # 2. 安装依赖 pip install -r requirements.txt ​ # 3. 启动服务 python app.py3.4 访问系统启动成功后在浏览器中打开地址说明http://localhost:8080前端主界面上传/结果/历史http://localhost:8080/docsSwagger API 交互文档3.5 添加标准图库将你的标准/参考图片放入standard_library/目录系统启动时会自动扫描。支持格式.jpg.jpeg.png.bmp.gif.webp。注意只有放入standard_library/的图片才会参与比对。3.6 使用流程① 打开网页 → ② 拖拽/点击上传图片 → ③ 系统自动完成全流程 │ ┌─────────────────────────────────────┘ ▼ 预处理缩放 去噪 ▼ 与标准图库逐一比对5种算法 ▼ 加权计算综合分 排序 ▼ 结果存入数据库 ▼ 自动发送邮件报告 ──→ 邮箱收到 HTML 报表 ▼ 前端展示统计卡片 排序表格 进度条四、邮箱配置重要邮件配置位于backend/config.py第 32-39 行是系统首次使用必须修改的地方。4.1 配置项说明EMAIL_CONFIG { smtp_host: smtp.qq.com, # SMTP 服务器地址 smtp_port: 465, # 端口SSL465, STARTTLS587 use_ssl: True, # TrueSSL连接, FalseSTARTTLS sender_email: 你的邮箱qq.com, # 发件邮箱地址 sender_password: 你的授权码, # ⚠️ 授权码不是邮箱密码 recipient_email: 收件人qq.com, # 接收报告的邮箱 }4.2 不同邮箱配置对照表邮箱服务商smtp_hostsmtp_portuse_sslQQ邮箱smtp.qq.com465TrueQQ邮箱smtp.qq.com587False163邮箱smtp.163.com465TrueGmailsmtp.gmail.com587FalseOutlooksmtp.office365.com587False4.3 QQ邮箱授权码获取步骤最常用⚠️关键sender_password必须填授权码而不是 QQ 登录密码第1步: 登录 QQ邮箱网页版mail.qq.com 第2步: 点击顶部「设置」→「账户」 第3步: 往下滚动找到「POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务」 第4步: 点击「开启」IMAP/SMTP服务 或 POP3/SMTP服务 第5步: 按提示发送短信验证发送到 1069070069 第6步: 验证成功后页面上会显示一串 16 位授权码如 ekbtiezxyzmjieih 第7步: 将这串授权码填入 config.py 的 sender_password 字段4.4 163邮箱授权码获取示例登录 163邮箱 → 设置 → POP3/SMTP/IMAP → 开启服务 → 设置授权码 → 填入 config.py4.5 Gmail 配置需开启两步验证 应用专用密码EMAIL_CONFIG { smtp_host: smtp.gmail.com, smtp_port: 587, use_ssl: False, # Gmail 使用 STARTTLS sender_email: yourgmail.com, sender_password: 应用专用密码, # 不是Google密码 recipient_email: receiverexample.com, }步骤Google 账号 → 安全性 → 两步验证 → 应用专用密码 → 生成 → 填入4.6 邮件测试如果邮件发送失败可以使用项目自带的诊断脚本cd backend python test_email.py该脚本会逐步测试SSL 连接 → STARTTLS 连接 → 登录 → 发送帮助定位问题。常见报错及解决错误提示原因解决方法535 Authentication failed授权码错误重新获取授权码SMTP service not enabledSMTP 服务未开启去邮箱设置中开启Connect timeout网络/防火墙拦截检查网络或关闭代理Recipient refused收件地址不存在确认收件邮箱正确Data error触发反垃圾机制调整邮件内容或频率4.7 不想使用邮件功能如果暂时不需要邮件推送有两种方式方式一留空配置但保留键名邮件发送会静默失败不影响上传和比对功能方式二注释掉app.py第 123-138 行的邮件发送代码块五、其他可配置项5.1 算法权重调整在backend/config.py中修改SCORE_WEIGHTS四项之和应为 1.0SCORE_WEIGHTS { phash: 0.30, # 调高 → 更看重整体结构 dhash: 0.15, # 调高 → 更看重渐变细节 ssim: 0.30, # 调高 → 更接近人眼判断 histogram: 0.15, # 调高 → 更看重颜色分布 orb: 0.10, # 调高 → 更看重局部特征 }5.2 预处理尺寸MAX_IMAGE_SIZE (800, 800) # 调大 → 精度更高但速度更慢5.3 上传限制MAX_UPLOAD_SIZE 20 * 1024 * 1024 # 默认 20MB ALLOWED_EXTENSIONS {.jpg, .jpeg, .png, .bmp, .gif, .webp, .tiff}5.4 服务端口HOST 0.0.0.0 # 监听所有网卡局域网可访问 PORT 8080 # 修改端口号避免冲突六、项目目录结构image-similarity-recognition/ ├── start.bat # Windows 一键启动脚本 ├── backend/ │ ├── app.py # FastAPI 主应用API路由 流水线编排 │ ├── config.py # ⚙ 配置文件邮箱、权重、路径等 │ ├── database.py # SQLite 数据库操作三张表 │ ├── image_processor.py # 图片预处理缩放 高斯去噪 │ ├── similarity.py # 5种算法相似度比对引擎 │ ├── email_service.py # SMTP 邮件发送服务 │ ├── report_generator.py # HTML 报表生成评分表 汇总表 │ ├── test_email.py # 邮箱 SMTP 诊断工具 │ ├── requirements.txt # Python 依赖清单 │ └── image_compare.db # SQLite 数据库文件 ├── frontend/ │ ├── index.html # 前端页面上传 结果 历史 │ ├── style.css # 响应式样式 评分颜色编码 │ └── app.js # 前端逻辑上传 展示 Toast ├── standard_library/ # ⚠ 标准图库存放目录 └── uploads/ # 上传图片自动保存目录七、API 接口一览接口方法说明/api/uploadPOST上传图片触发完整比对流水线/api/recordsGET获取所有历史记录摘要/api/records/{id}GET获取指定记录详情含各项评分/api/libraryGET标准图库图片列表/api/library/preview/{filename}GET预览标准图库某张图片/api/uploads/preview/{filename}GET预览上传的某张图片/api/healthGET健康检查状态 图库数量/docs-Swagger 交互式 API 文档八、技术栈总结层级技术用途Web 框架FastAPI UvicornREST API 异步文件上传图像处理OpenCV scikit-image预处理、特征提取、SSIM哈希算法imagehash (phash/dhash)感知哈希 差异哈希数据库SQLite3本地轻量级数据存储邮件smtplib MIMEHTML 格式报表推送前端原生 HTML/CSS/JS拖拽上传 结果可视化