尧图网页设计 
1. 项目缘起与整体架构思路海草床这东西做过海洋生态监测的人都知道它是近岸生态里最容易被忽略又最要命的一环。传统调查靠潜水员下水样方拍照、人工数种类一个潮次下来累得半死数据还带主观偏差。我手上这个项目目标很直接把已经训练好的 CNN 海草识别模型塞进一个现有的 PHP 业务系统里让一线人员上传水下照片后台自动返回海草种类和覆盖度不用再单独开一套 Python 服务给业务方用。为什么非得是 PHP 接 CNN因为现实里很多海洋监测站、保护区管理平台的历史系统就是 PHP 写的运维只会 PHP服务器上跑着 Apache 加 MySQL你让他为了一个识别功能再学 Python 部署、再维护一套 GPU 环境成本高得离谱。所以核心思路是Python 只负责模型推理这一件事PHP 负责所有业务逻辑、权限、存储和前端交互两者之间用 HTTP API 做桥接。这个拆分的好处是模型可以独立升级、独立扩容PHP 那边完全不用动坏处是多了一次网络往返得把超时、并发、错误处理做扎实。整体架构我画成三层。第一层是 PHP 应用层处理用户登录、图片上传、任务入库、结果展示第二层是推理服务层用 Python 的 Flask 或 FastAPI 起一个轻量 HTTP 服务加载 CNN 模型接收图片返回 JSON第三层是模型层CNN 权重文件加预处理逻辑。三层之间用内网通信PHP 通过 cURL 调用推理服务推理服务不碰数据库纯无状态这样扩容就是多起几个进程的事。选 HTTP API 而不是其他方式理由很实在。gRPC 性能好但 PHP 端支持麻烦要装扩展消息队列异步虽然解耦彻底但一线人员上传完想立刻看结果同步返回体验更好。HTTP 加 JSON 是最土但最稳的方案任何 PHP 环境都能跑调试用浏览器就能测出问题抓包一目了然。实测下来单张 224x224 的图片CPU 推理在 200 毫秒左右加上网络往返整体响应控制在 500 毫秒内完全够用。这里有个关键决策点模型到底放 PHP 服务器还是单独服务器。如果放同一台省网络开销但 PHP 服务器通常没 GPUCPU 推理并发一高就卡死如果单独放多一台机器但可以专门配 GPU 或者多核 CPU。我最终选了单独部署因为海草识别模型虽然不大但批量上传时并发推理会吃满 CPU跟 Web 服务抢资源是灾难。单独部署后PHP 服务器负载几乎没变化推理服务器可以按需加核。提示如果你的场景是低频使用比如一天就几十张图其实可以把 Python 推理脚本用 PHP 的 exec 直接调用省掉 HTTP 服务。但一旦并发上来exec 会阻塞 PHP 进程而且错误处理很痛苦不推荐生产环境用。2. 核心细节解析与实操要点2.1 CNN 模型选型与预处理的关键参数海草识别这个任务跟通用图像分类不太一样。水下照片普遍偏蓝绿、对比度低、有悬浮物遮挡而且不同海草种类之间形态差异小比如喜盐草和针叶草在模糊照片里几乎一个样。所以模型选型上我没用 ResNet50 这种大模型而是选了MobileNetV3-Small做 backbone原因有三一是参数量小推理快适合 CPU 部署二是它本身对纹理特征敏感海草识别主要靠叶片形状和纹理三是可以方便地做迁移学习用几百张标注图就能微调出不错的效果。输入尺寸定在 224x224这是 ImageNet 预训练的标准尺寸改动小。但预处理不能直接照搬我加了两个针对性操作。第一是白平衡校正水下照片色偏严重用灰度世界算法先做一次颜色校正让模型不被色偏带偏。第二是CLAHE 对比度受限自适应直方图均衡这个在 OpenCV 里一行代码的事但对水下低对比度图像提升明显实测准确率能涨 5 到 8 个百分点。归一化参数用的是 ImageNet 的均值和标准差即 mean[0.485, 0.456, 0.406]std[0.229, 0.224, 0.225]。这里有个坑很多人预处理时忘了把 BGR 转 RGBOpenCV 读图默认是 BGR直接送进模型会导致颜色通道错位准确率暴跌。我踩过这个坑排查了半天才发现是通道顺序问题。模型输出层改成全连接输出维度等于海草类别数。我这边是 6 类喜盐草、针叶草、卵叶喜盐草、海菖蒲、泰来草、其他。最后一层用 Softmax返回每类的概率。阈值设 0.6低于这个值就返回“不确定”避免硬分类误导用户。这个阈值不是拍脑袋定的是在验证集上画了 P-R 曲线找的平衡点。2.2 PHP 端 HTTP 调用的封装与超时设计PHP 调 Python 服务核心就是 cURL。但直接写 cURL 很容易踩坑我封装了一个CnnClient类把超时、重试、错误码处理都包进去。超时设置很讲究连接超时设 2 秒总超时设 10 秒。为什么总超时是 10 秒因为推理服务冷启动加载模型可能要 3 到 5 秒如果设太短第一次请求必失败。但也不能太长否则 PHP 进程被占住并发一高就雪崩。重试策略是失败后重试一次间隔 500 毫秒。注意只对网络错误和 5xx 重试4xx 不重试因为那是请求本身有问题重试也没用。这个逻辑写在CnnClient里业务代码只管调identify($imagePath)返回统一格式的数组。图片传输方式我选了multipart/form-data而不是 base64。base64 会让数据体积膨胀 33%而且 PHP 端编码、Python 端解码都耗 CPU。multipart 直接传二进制效率高。但要注意 PHP 的CURLFile类用它构造文件字段别手动拼 multipart 边界容易出错。$ch curl_init(); curl_setopt_array($ch, [ CURLOPT_URL http://127.0.0.1:5000/predict, CURLOPT_POST true, CURLOPT_POSTFIELDS [image new CURLFile($imagePath)], CURLOPT_RETURNTRANSFER true, CURLOPT_CONNECTTIMEOUT 2, CURLOPT_TIMEOUT 10, ]); $response curl_exec($ch); $httpCode curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch);这段代码看着简单但有几个细节。CURLOPT_RETURNTRANSFER必须开否则结果直接输出到页面。CURLFile的路径必须是绝对路径相对路径在某些 PHP 版本下会失败。还有如果图片是用户上传的临时文件记得先move_uploaded_file到安全目录再传别直接传临时文件因为推理服务可能读不到。2.3 推理服务的接口设计与并发处理Python 端我用 FastAPI不是 Flask。原因很简单FastAPI 原生支持异步而且自带请求校验和文档。接口就一个POST /predict接收图片文件返回 JSON。返回结构我定成{ success: true, class: 喜盐草, confidence: 0.87, all_probs: {喜盐草: 0.87, 针叶草: 0.08, ...}, inference_time_ms: 187 }all_probs返回所有类别概率方便前端做可视化。inference_time_ms是推理耗时用于监控。并发处理上FastAPI 默认是单进程CPU 推理会阻塞事件循环。所以启动时用uvicorn加--workers参数worker 数设成 CPU 核数。但注意每个 worker 都会加载一份模型内存占用会翻倍。如果模型是 50MB4 个 worker 就是 200MB一般服务器扛得住。如果模型很大就得考虑用共享内存或者模型服务化框架但那是另一个话题了。注意--workers不是越多越好。我试过设成 8结果内存爆了而且进程切换开销反而让吞吐下降。实测 4 核 CPU 设 4 个 worker 最稳吞吐量比单 worker 高 3 倍多。还有一个坑是模型加载时机。如果在每个请求里加载模型那慢得没法用。必须在服务启动时加载一次全局变量持有。FastAPI 用lifespan事件做启动加载比app.on_event(startup)更规范。3. 实操过程与核心环节实现3.1 从零搭建 Python 推理服务先装依赖。Python 版本建议 3.9 以上太老的版本有些库不支持。核心库就四个torch、torchvision、fastapi、uvicorn。如果要用 OpenCV 做预处理再加opencv-python-headless注意是 headless 版本服务器不需要 GUI。pip install torch torchvision fastapi uvicorn opencv-python-headless pillow模型文件我存成seagrass_mobilenetv3.pth加载时用torch.load注意map_location设成cpu否则在有 GPU 的机器上训练、在 CPU 机器上部署会报错。加载后调model.eval()这步不能省否则 BatchNorm 和 Dropout 层行为不对结果会飘。预处理函数单独写输入是 PIL Image输出是 tensor。步骤是转 RGB、白平衡、CLAHE、Resize 到 224、转 tensor、归一化。白平衡和 CLAHE 用 OpenCV 做注意 OpenCV 读进来是 numpy 数组要转回 PIL 再送 torchvision 的 transform。def preprocess(image: Image.Image) - torch.Tensor: img np.array(image.convert(RGB)) img gray_world_white_balance(img) img apply_clahe(img) image Image.fromarray(img) transform transforms.Compose([ transforms.Resize((224, 224)), transforms.ToTensor(), transforms.Normalize(mean[0.485, 0.456, 0.406], std[0.229, 0.224, 0.225]), ]) return transform(image).unsqueeze(0)unsqueeze(0)是加 batch 维度因为模型期望输入是[N, C, H, W]。这步忘了会报维度错误新手常犯。推理就是with torch.no_grad(): output model(tensor)然后softmax拿概率。注意torch.no_grad()一定要加否则会建计算图内存暴涨。FastAPI 的接口函数用async def但推理是同步的所以实际会阻塞。如果要用真异步得用run_in_executor把推理丢到线程池。我图省事直接用多 worker 解决每个 worker 同步处理简单可靠。3.2 PHP 端上传与调用全流程PHP 这边前端页面就是一个表单enctypemultipart/form-data一个 file input一个提交按钮。后端接收后先校验文件类型和大小。类型用finfo读 MIME别信$_FILES[type]那个是客户端传的可以伪造。大小限制我设 10MB水下照片一般 2 到 5MB10MB 足够。校验通过后把临时文件移到uploads/目录文件名用uniqid加时间戳避免冲突。然后调CnnClient的identify方法。返回结果存数据库同时返回给前端展示。数据库表设计很简单id、image_path、class、confidence、all_probsJSON 字段、created_at。all_probs用 MySQL 的 JSON 类型存方便后续分析。注意 MySQL 5.7 以上才支持 JSON 类型老版本用 TEXT 存 JSON 字符串也行。$result $client-identify($absolutePath); if ($result[success]) { $stmt $pdo-prepare(INSERT INTO seagrass_records (image_path, class, confidence, all_probs, created_at) VALUES (?, ?, ?, ?, NOW())); $stmt-execute([ $relativePath, $result[class], $result[confidence], json_encode($result[all_probs], JSON_UNESCAPED_UNICODE), ]); }JSON_UNESCAPED_UNICODE这个参数很重要不加的话中文会被转成\uXXXX存进数据库虽然能还原但直接看很痛苦。前端展示用 AJAX上传后显示 loading返回后渲染结果。结果里把all_probs画成横向条形图用纯 CSS 就行不用引图表库。置信度低于 0.6 的标红提示“建议人工复核”。3.3 部署与性能调优实录部署我用了 Docker Compose两个服务php-app和cnn-service。php-app用php:8.2-apache镜像cnn-service用python:3.10-slim自己构建。两个服务在同一网络PHP 通过服务名cnn-service访问不用暴露端口到外网。cnn-service的 Dockerfile 关键点是先装依赖再拷代码利用 Docker 层缓存。torch的 CPU 版本安装包很大用--index-url指定 CPU 源能省几百 MB。FROM python:3.10-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt \ --index-url https://download.pytorch.org/whl/cpu COPY . . CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 5000, --workers, 4]性能调优上我做了三件事。第一是图片压缩PHP 端上传前用 GD 库把图片长边压到 1024体积能降 70%推理精度几乎没影响因为模型输入本来就是 224。第二是结果缓存同一张图片的 MD5 做 key存 Redis重复上传直接返回缓存省推理。第三是批量接口如果一次传多张Python 端支持 batch 推理比逐张快 2 到 3 倍。实测数据单张 CPU 推理 187ms加网络和 PHP 处理端到端 420ms。4 worker 并发下QPS 能到 18 左右。对于监测站这种场景完全够用。4. 常见问题与排查技巧实录4.1 推理服务报错与排查速查表实际跑起来问题不少。我整理了一个速查表都是真实踩过的坑。现象可能原因排查方法解决PHP 返回 500cURL 超时或连接拒绝看 PHP error log用curl -v手动测检查推理服务是否启动端口是否对推理结果全是同一类预处理通道错位或归一化错打印 tensor 的 min/max/mean确认 BGR 转 RGB归一化参数正确首次请求特别慢模型冷启动加载看日志时间戳预热启动后发一张测试图并发高时超时worker 不够或 CPU 满top看 CPU看 uvicorn 日志加 worker或加机器中文类别名乱码JSON 编码问题看返回原始字符串PHP 端json_encode加JSON_UNESCAPED_UNICODE图片上传失败PHP 上传大小限制看php.ini的upload_max_filesize调大到 10M重启 Apache内存持续增长推理没加no_grad看进程内存曲线加torch.no_grad()这个表我贴在工位上出问题先查表80% 的情况能直接定位。4.2 那些文档不会告诉你的实操心得第一个心得模型版本管理要提前做。我一开始模型文件就叫model.pth后来微调了一版覆盖上去结果线上结果变了排查半天才发现是模型换了。后来改成model_v1.2.pth接口返回里带上版本号PHP 端存数据库这样任何一次结果都能追溯到具体模型版本。第二个心得日志要打全。Python 端每次推理打一行日志时间、图片 MD5、预测类别、置信度、耗时。PHP 端每次调用打一行用户 ID、图片路径、调用结果、耗时。两边日志用同一个请求 ID 关联出问题能串起来看。这个请求 ID 由 PHP 生成通过 HTTP header 传给 Python。第三个心得别忽视图片方向。手机拍的照片带 EXIF 方向信息PHP 的 GD 库不自动旋转导致图片是横的模型识别率下降。解决方法是读 EXIF 的Orientation字段用imagerotate校正。这个坑很隐蔽因为人眼看图是正的但程序读出来是歪的。第四个心得置信度阈值要按场景调。我一开始设 0.6后来发现有些模糊照片模型给 0.55 但其实是正确的。如果业务能接受人工复核阈值可以降到 0.5召回率更高。如果要求高精度就升到 0.7。这个没有标准答案得跟业务方一起定。提示推理服务的健康检查接口别忘了加。GET /health返回{status: ok}PHP 端可以定时探活服务挂了能及时告警而不是等用户上传失败才发现。4.3 扩展方向与后续优化思路这套架构跑通后扩展空间很大。最直接的是加目标检测现在只能识别整张图的主要海草如果一张图里有多种海草就得用 YOLO 之类的检测模型先框出来再分类。这个改动主要在 Python 端PHP 端接口不用变返回结构加个boxes字段就行。另一个方向是边缘部署。有些监测站网络不好可以把模型转成 ONNX用 ONNX Runtime 在本地跑PHP 直接调本地推理不走网络。ONNX Runtime 有 PHP 绑定但不太成熟更稳的方案是 Python 起本地服务PHP 调127.0.0.1效果一样。还有主动学习。把置信度低的样本自动存下来定期人工标注再微调模型。这个闭环建起来模型会越用越准。PHP 端加个字段标记“待复核”Python 端加个脚本定期导出低置信度样本就搞定了。最后说个数据层面的优化。海草识别受季节和光照影响大夏天和冬天的照片分布不一样。可以在模型输入里加个时间特征或者按季节分模型。我目前是单模型打天下后续打算按季度微调每个季度一个权重PHP 端根据上传时间选模型。这个改动不大但效果应该明显。整套东西从零到跑通我花了大概两周其中一周在调预处理和排查通道问题。现在回头看最难的不是模型而是 PHP 和 Python 之间的那层胶水。把超时、重试、日志、版本管理做扎实后面就顺了。如果你也在做类似的事建议先把接口协议定死两边并行开发别等模型调好了再想怎么接那样返工成本太高。 PHP集成CNN海草识别：HTTP API桥接与性能调优实战
1. 项目缘起与整体架构思路海草床这东西做过海洋生态监测的人都知道它是近岸生态里最容易被忽略又最要命的一环。传统调查靠潜水员下水样方拍照、人工数种类一个潮次下来累得半死数据还带主观偏差。我手上这个项目目标很直接把已经训练好的 CNN 海草识别模型塞进一个现有的 PHP 业务系统里让一线人员上传水下照片后台自动返回海草种类和覆盖度不用再单独开一套 Python 服务给业务方用。为什么非得是 PHP 接 CNN因为现实里很多海洋监测站、保护区管理平台的历史系统就是 PHP 写的运维只会 PHP服务器上跑着 Apache 加 MySQL你让他为了一个识别功能再学 Python 部署、再维护一套 GPU 环境成本高得离谱。所以核心思路是Python 只负责模型推理这一件事PHP 负责所有业务逻辑、权限、存储和前端交互两者之间用 HTTP API 做桥接。这个拆分的好处是模型可以独立升级、独立扩容PHP 那边完全不用动坏处是多了一次网络往返得把超时、并发、错误处理做扎实。整体架构我画成三层。第一层是 PHP 应用层处理用户登录、图片上传、任务入库、结果展示第二层是推理服务层用 Python 的 Flask 或 FastAPI 起一个轻量 HTTP 服务加载 CNN 模型接收图片返回 JSON第三层是模型层CNN 权重文件加预处理逻辑。三层之间用内网通信PHP 通过 cURL 调用推理服务推理服务不碰数据库纯无状态这样扩容就是多起几个进程的事。选 HTTP API 而不是其他方式理由很实在。gRPC 性能好但 PHP 端支持麻烦要装扩展消息队列异步虽然解耦彻底但一线人员上传完想立刻看结果同步返回体验更好。HTTP 加 JSON 是最土但最稳的方案任何 PHP 环境都能跑调试用浏览器就能测出问题抓包一目了然。实测下来单张 224x224 的图片CPU 推理在 200 毫秒左右加上网络往返整体响应控制在 500 毫秒内完全够用。这里有个关键决策点模型到底放 PHP 服务器还是单独服务器。如果放同一台省网络开销但 PHP 服务器通常没 GPUCPU 推理并发一高就卡死如果单独放多一台机器但可以专门配 GPU 或者多核 CPU。我最终选了单独部署因为海草识别模型虽然不大但批量上传时并发推理会吃满 CPU跟 Web 服务抢资源是灾难。单独部署后PHP 服务器负载几乎没变化推理服务器可以按需加核。提示如果你的场景是低频使用比如一天就几十张图其实可以把 Python 推理脚本用 PHP 的 exec 直接调用省掉 HTTP 服务。但一旦并发上来exec 会阻塞 PHP 进程而且错误处理很痛苦不推荐生产环境用。2. 核心细节解析与实操要点2.1 CNN 模型选型与预处理的关键参数海草识别这个任务跟通用图像分类不太一样。水下照片普遍偏蓝绿、对比度低、有悬浮物遮挡而且不同海草种类之间形态差异小比如喜盐草和针叶草在模糊照片里几乎一个样。所以模型选型上我没用 ResNet50 这种大模型而是选了MobileNetV3-Small做 backbone原因有三一是参数量小推理快适合 CPU 部署二是它本身对纹理特征敏感海草识别主要靠叶片形状和纹理三是可以方便地做迁移学习用几百张标注图就能微调出不错的效果。输入尺寸定在 224x224这是 ImageNet 预训练的标准尺寸改动小。但预处理不能直接照搬我加了两个针对性操作。第一是白平衡校正水下照片色偏严重用灰度世界算法先做一次颜色校正让模型不被色偏带偏。第二是CLAHE 对比度受限自适应直方图均衡这个在 OpenCV 里一行代码的事但对水下低对比度图像提升明显实测准确率能涨 5 到 8 个百分点。归一化参数用的是 ImageNet 的均值和标准差即 mean[0.485, 0.456, 0.406]std[0.229, 0.224, 0.225]。这里有个坑很多人预处理时忘了把 BGR 转 RGBOpenCV 读图默认是 BGR直接送进模型会导致颜色通道错位准确率暴跌。我踩过这个坑排查了半天才发现是通道顺序问题。模型输出层改成全连接输出维度等于海草类别数。我这边是 6 类喜盐草、针叶草、卵叶喜盐草、海菖蒲、泰来草、其他。最后一层用 Softmax返回每类的概率。阈值设 0.6低于这个值就返回“不确定”避免硬分类误导用户。这个阈值不是拍脑袋定的是在验证集上画了 P-R 曲线找的平衡点。2.2 PHP 端 HTTP 调用的封装与超时设计PHP 调 Python 服务核心就是 cURL。但直接写 cURL 很容易踩坑我封装了一个CnnClient类把超时、重试、错误码处理都包进去。超时设置很讲究连接超时设 2 秒总超时设 10 秒。为什么总超时是 10 秒因为推理服务冷启动加载模型可能要 3 到 5 秒如果设太短第一次请求必失败。但也不能太长否则 PHP 进程被占住并发一高就雪崩。重试策略是失败后重试一次间隔 500 毫秒。注意只对网络错误和 5xx 重试4xx 不重试因为那是请求本身有问题重试也没用。这个逻辑写在CnnClient里业务代码只管调identify($imagePath)返回统一格式的数组。图片传输方式我选了multipart/form-data而不是 base64。base64 会让数据体积膨胀 33%而且 PHP 端编码、Python 端解码都耗 CPU。multipart 直接传二进制效率高。但要注意 PHP 的CURLFile类用它构造文件字段别手动拼 multipart 边界容易出错。$ch curl_init(); curl_setopt_array($ch, [ CURLOPT_URL http://127.0.0.1:5000/predict, CURLOPT_POST true, CURLOPT_POSTFIELDS [image new CURLFile($imagePath)], CURLOPT_RETURNTRANSFER true, CURLOPT_CONNECTTIMEOUT 2, CURLOPT_TIMEOUT 10, ]); $response curl_exec($ch); $httpCode curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch);这段代码看着简单但有几个细节。CURLOPT_RETURNTRANSFER必须开否则结果直接输出到页面。CURLFile的路径必须是绝对路径相对路径在某些 PHP 版本下会失败。还有如果图片是用户上传的临时文件记得先move_uploaded_file到安全目录再传别直接传临时文件因为推理服务可能读不到。2.3 推理服务的接口设计与并发处理Python 端我用 FastAPI不是 Flask。原因很简单FastAPI 原生支持异步而且自带请求校验和文档。接口就一个POST /predict接收图片文件返回 JSON。返回结构我定成{ success: true, class: 喜盐草, confidence: 0.87, all_probs: {喜盐草: 0.87, 针叶草: 0.08, ...}, inference_time_ms: 187 }all_probs返回所有类别概率方便前端做可视化。inference_time_ms是推理耗时用于监控。并发处理上FastAPI 默认是单进程CPU 推理会阻塞事件循环。所以启动时用uvicorn加--workers参数worker 数设成 CPU 核数。但注意每个 worker 都会加载一份模型内存占用会翻倍。如果模型是 50MB4 个 worker 就是 200MB一般服务器扛得住。如果模型很大就得考虑用共享内存或者模型服务化框架但那是另一个话题了。注意--workers不是越多越好。我试过设成 8结果内存爆了而且进程切换开销反而让吞吐下降。实测 4 核 CPU 设 4 个 worker 最稳吞吐量比单 worker 高 3 倍多。还有一个坑是模型加载时机。如果在每个请求里加载模型那慢得没法用。必须在服务启动时加载一次全局变量持有。FastAPI 用lifespan事件做启动加载比app.on_event(startup)更规范。3. 实操过程与核心环节实现3.1 从零搭建 Python 推理服务先装依赖。Python 版本建议 3.9 以上太老的版本有些库不支持。核心库就四个torch、torchvision、fastapi、uvicorn。如果要用 OpenCV 做预处理再加opencv-python-headless注意是 headless 版本服务器不需要 GUI。pip install torch torchvision fastapi uvicorn opencv-python-headless pillow模型文件我存成seagrass_mobilenetv3.pth加载时用torch.load注意map_location设成cpu否则在有 GPU 的机器上训练、在 CPU 机器上部署会报错。加载后调model.eval()这步不能省否则 BatchNorm 和 Dropout 层行为不对结果会飘。预处理函数单独写输入是 PIL Image输出是 tensor。步骤是转 RGB、白平衡、CLAHE、Resize 到 224、转 tensor、归一化。白平衡和 CLAHE 用 OpenCV 做注意 OpenCV 读进来是 numpy 数组要转回 PIL 再送 torchvision 的 transform。def preprocess(image: Image.Image) - torch.Tensor: img np.array(image.convert(RGB)) img gray_world_white_balance(img) img apply_clahe(img) image Image.fromarray(img) transform transforms.Compose([ transforms.Resize((224, 224)), transforms.ToTensor(), transforms.Normalize(mean[0.485, 0.456, 0.406], std[0.229, 0.224, 0.225]), ]) return transform(image).unsqueeze(0)unsqueeze(0)是加 batch 维度因为模型期望输入是[N, C, H, W]。这步忘了会报维度错误新手常犯。推理就是with torch.no_grad(): output model(tensor)然后softmax拿概率。注意torch.no_grad()一定要加否则会建计算图内存暴涨。FastAPI 的接口函数用async def但推理是同步的所以实际会阻塞。如果要用真异步得用run_in_executor把推理丢到线程池。我图省事直接用多 worker 解决每个 worker 同步处理简单可靠。3.2 PHP 端上传与调用全流程PHP 这边前端页面就是一个表单enctypemultipart/form-data一个 file input一个提交按钮。后端接收后先校验文件类型和大小。类型用finfo读 MIME别信$_FILES[type]那个是客户端传的可以伪造。大小限制我设 10MB水下照片一般 2 到 5MB10MB 足够。校验通过后把临时文件移到uploads/目录文件名用uniqid加时间戳避免冲突。然后调CnnClient的identify方法。返回结果存数据库同时返回给前端展示。数据库表设计很简单id、image_path、class、confidence、all_probsJSON 字段、created_at。all_probs用 MySQL 的 JSON 类型存方便后续分析。注意 MySQL 5.7 以上才支持 JSON 类型老版本用 TEXT 存 JSON 字符串也行。$result $client-identify($absolutePath); if ($result[success]) { $stmt $pdo-prepare(INSERT INTO seagrass_records (image_path, class, confidence, all_probs, created_at) VALUES (?, ?, ?, ?, NOW())); $stmt-execute([ $relativePath, $result[class], $result[confidence], json_encode($result[all_probs], JSON_UNESCAPED_UNICODE), ]); }JSON_UNESCAPED_UNICODE这个参数很重要不加的话中文会被转成\uXXXX存进数据库虽然能还原但直接看很痛苦。前端展示用 AJAX上传后显示 loading返回后渲染结果。结果里把all_probs画成横向条形图用纯 CSS 就行不用引图表库。置信度低于 0.6 的标红提示“建议人工复核”。3.3 部署与性能调优实录部署我用了 Docker Compose两个服务php-app和cnn-service。php-app用php:8.2-apache镜像cnn-service用python:3.10-slim自己构建。两个服务在同一网络PHP 通过服务名cnn-service访问不用暴露端口到外网。cnn-service的 Dockerfile 关键点是先装依赖再拷代码利用 Docker 层缓存。torch的 CPU 版本安装包很大用--index-url指定 CPU 源能省几百 MB。FROM python:3.10-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt \ --index-url https://download.pytorch.org/whl/cpu COPY . . CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 5000, --workers, 4]性能调优上我做了三件事。第一是图片压缩PHP 端上传前用 GD 库把图片长边压到 1024体积能降 70%推理精度几乎没影响因为模型输入本来就是 224。第二是结果缓存同一张图片的 MD5 做 key存 Redis重复上传直接返回缓存省推理。第三是批量接口如果一次传多张Python 端支持 batch 推理比逐张快 2 到 3 倍。实测数据单张 CPU 推理 187ms加网络和 PHP 处理端到端 420ms。4 worker 并发下QPS 能到 18 左右。对于监测站这种场景完全够用。4. 常见问题与排查技巧实录4.1 推理服务报错与排查速查表实际跑起来问题不少。我整理了一个速查表都是真实踩过的坑。现象可能原因排查方法解决PHP 返回 500cURL 超时或连接拒绝看 PHP error log用curl -v手动测检查推理服务是否启动端口是否对推理结果全是同一类预处理通道错位或归一化错打印 tensor 的 min/max/mean确认 BGR 转 RGB归一化参数正确首次请求特别慢模型冷启动加载看日志时间戳预热启动后发一张测试图并发高时超时worker 不够或 CPU 满top看 CPU看 uvicorn 日志加 worker或加机器中文类别名乱码JSON 编码问题看返回原始字符串PHP 端json_encode加JSON_UNESCAPED_UNICODE图片上传失败PHP 上传大小限制看php.ini的upload_max_filesize调大到 10M重启 Apache内存持续增长推理没加no_grad看进程内存曲线加torch.no_grad()这个表我贴在工位上出问题先查表80% 的情况能直接定位。4.2 那些文档不会告诉你的实操心得第一个心得模型版本管理要提前做。我一开始模型文件就叫model.pth后来微调了一版覆盖上去结果线上结果变了排查半天才发现是模型换了。后来改成model_v1.2.pth接口返回里带上版本号PHP 端存数据库这样任何一次结果都能追溯到具体模型版本。第二个心得日志要打全。Python 端每次推理打一行日志时间、图片 MD5、预测类别、置信度、耗时。PHP 端每次调用打一行用户 ID、图片路径、调用结果、耗时。两边日志用同一个请求 ID 关联出问题能串起来看。这个请求 ID 由 PHP 生成通过 HTTP header 传给 Python。第三个心得别忽视图片方向。手机拍的照片带 EXIF 方向信息PHP 的 GD 库不自动旋转导致图片是横的模型识别率下降。解决方法是读 EXIF 的Orientation字段用imagerotate校正。这个坑很隐蔽因为人眼看图是正的但程序读出来是歪的。第四个心得置信度阈值要按场景调。我一开始设 0.6后来发现有些模糊照片模型给 0.55 但其实是正确的。如果业务能接受人工复核阈值可以降到 0.5召回率更高。如果要求高精度就升到 0.7。这个没有标准答案得跟业务方一起定。提示推理服务的健康检查接口别忘了加。GET /health返回{status: ok}PHP 端可以定时探活服务挂了能及时告警而不是等用户上传失败才发现。4.3 扩展方向与后续优化思路这套架构跑通后扩展空间很大。最直接的是加目标检测现在只能识别整张图的主要海草如果一张图里有多种海草就得用 YOLO 之类的检测模型先框出来再分类。这个改动主要在 Python 端PHP 端接口不用变返回结构加个boxes字段就行。另一个方向是边缘部署。有些监测站网络不好可以把模型转成 ONNX用 ONNX Runtime 在本地跑PHP 直接调本地推理不走网络。ONNX Runtime 有 PHP 绑定但不太成熟更稳的方案是 Python 起本地服务PHP 调127.0.0.1效果一样。还有主动学习。把置信度低的样本自动存下来定期人工标注再微调模型。这个闭环建起来模型会越用越准。PHP 端加个字段标记“待复核”Python 端加个脚本定期导出低置信度样本就搞定了。最后说个数据层面的优化。海草识别受季节和光照影响大夏天和冬天的照片分布不一样。可以在模型输入里加个时间特征或者按季节分模型。我目前是单模型打天下后续打算按季度微调每个季度一个权重PHP 端根据上传时间选模型。这个改动不大但效果应该明显。整套东西从零到跑通我花了大概两周其中一周在调预处理和排查通道问题。现在回头看最难的不是模型而是 PHP 和 Python 之间的那层胶水。把超时、重试、日志、版本管理做扎实后面就顺了。如果你也在做类似的事建议先把接口协议定死两边并行开发别等模型调好了再想怎么接那样返工成本太高。