1. 从命令行到浏览器为什么要把 YOLO 训练搬上网页做过视觉项目的人都有个共同体会模型训练本身不难难的是让不写代码的人也能用起来。早些年我们团队做目标检测每次有新数据要训练流程都是这样的——标注同事把数据集打包发过来我这边改配置文件、调参数、跑脚本训练完了再把权重文件和指标截图发回去。来回沟通成本极高而且一旦我出差或者忙别的项目整条链路就卡住了。后来我下定决心把这套流程做成一个网页工具让标注同事自己上传数据集、自己选参数、自己点开始训练、自己看结果。技术栈选的是FastAPI SQLite单机部署不依赖任何外部服务。这套方案跑了大半年支撑了十几个内部小项目稳定性完全够用。这篇文章就把当时的需求设计思路和技术选型逻辑完整拆一遍包括我踩过的坑和后来总结出来的经验。先说清楚这套东西适合谁如果你手头有一台带 GPU 的机器哪怕是单张消费级显卡团队规模在几个人到十几个人之间需要一个轻量的、能管理训练任务和数据集的小工具那这套方案非常合适。它不适合高并发、多租户、需要弹性扩缩容的场景那种情况你得上分布式任务队列和对象存储复杂度是另一个量级。核心关键词就几个YOLO 训练、FastAPI、SQLite、单机部署、任务管理、数据集管理。整篇文章围绕这几个点展开把需求怎么拆、技术怎么选、坑怎么避讲透。2. 需求拆解一个训练平台到底要管哪几件事2.1 把训练这件事拆成可管理的对象很多人一上来就想做一键训练结果发现根本没法做因为训练不是一个原子操作它是一连串有状态的过程。我当时的做法是先做领域建模把整个流程拆成几个核心实体每个实体对应数据库里的一张表。拆下来大概是这么几类数据集Dataset一次上传的原始数据包含图片和标注文件有版本概念。训练任务Training Job一次具体的训练执行绑定一个数据集、一组参数、一个状态。模型产物Model Artifact训练产出的权重文件、日志、指标曲线。配置模板Config Template常用的参数组合避免每次手填。这个拆法的好处是每个实体都有明确的生命周期状态流转清晰。比如训练任务的状态就是pending - running - succeeded / failed / canceled前端只要根据状态渲染不同按钮就行逻辑非常简单。提示不要试图把数据集和训练任务合并成一张表。我见过有人这么干结果同一个数据集训练两次就出现数据冗余后面想复用数据集做对比实验时非常痛苦。2.2 用户真正在意的三个动作做完建模之后我找几个实际会用这个工具的同事聊了一圈发现他们真正关心的动作只有三个上传数据、发起训练、看结果。其他都是锦上添花。这个结论很重要它直接决定了前端页面的复杂度。我最后只做了三个主页面加一个任务列表页没有做复杂的权限系统、没有做花哨的仪表盘。事实证明这个取舍是对的工具上线后几乎没人问这个按钮在哪学习成本接近于零。具体到每个动作的细节需求动作关键需求容易忽略的点上传数据支持 zip 批量上传、自动解压、校验标注格式大文件上传要能断点续传或至少显示进度发起训练选数据集、选模型规格、填超参、启动参数要有默认值不能让人从零填看结果实时日志、指标曲线、下载权重训练中途刷新页面不能丢状态2.3 单机场景下的隐性约束单机部署听起来简单但它带来几个必须提前想清楚的约束否则做到一半会推翻重来。第一个约束是GPU 资源独占。一张卡同一时间只能跑一个训练任务所以任务队列必须是串行的不能并发。这一点必须在需求阶段就定死不然后面做并发调度会非常麻烦。第二个约束是磁盘空间。数据集和权重文件都很占地方一个中等规模的数据集加上几轮训练的权重几十 GB 很正常。所以要有清理机制不能只进不出。第三个约束是进程隔离。训练脚本跑崩了不能把 Web 服务带崩所以训练必须跑在独立进程里Web 层只负责调度和状态查询。这三个约束看起来是技术问题其实都是需求问题。想清楚它们后面的技术选型就顺理成章了。3. 技术选型FastAPI 和 SQLite 到底图什么3.1 为什么是 FastAPI 而不是 Flask 或 Django选 FastAPI 有三个实打实的理由不是为了追新。第一是原生异步支持。训练任务的日志推送、状态轮询这些接口用异步写起来很自然不会因为一个慢请求把整个服务堵住。Flask 要上异步得额外折腾Django 的异步生态相对重。第二是Pydantic 带来的参数校验。训练参数很多类型五花八门用 Pydantic 定义一遍模型请求进来自动校验省掉大量手写 if-else 的校验代码。这一点在参数多的场景下价值极高。第三是自动生成的交互式文档。FastAPI 自带 Swagger UI接口写完直接能在浏览器里点着测联调阶段省了很多事。对于内部工具来说这份文档本身就是给同事看的说明书。Django 我也考虑过它自带 Admin 和 ORM做后台管理确实快。但这套工具的前端交互比较定制化Django 的模板体系反而束手束脚而且它整体偏重单机小工具用不上那么多功能。3.2 SQLite 在单机训练平台里的真实定位一提到 SQLite很多人第一反应是玩具数据库不能用于生产。这个印象在单机场景下是错的。SQLite 的定位是嵌入式数据库它没有独立的服务进程数据就是一个文件。对于单机部署的训练平台这个特性反而是优势部署时不用额外装数据库服务备份时直接拷贝文件迁移时把文件带走就行。它真正扛不住的场景是高并发写入。但我们的场景是串行训练同一时间只有一个任务在写状态写入压力极小。读多写少SQLite 完全够用。不过有几个坑必须提前避开开启 WAL 模式。默认的日志模式在读写并发时容易锁库开启 WAL 后读写可以并行体验好很多。执行PRAGMA journal_modeWAL;即可。设置合理的 busy_timeout。避免偶发的锁冲突直接报错设置成几秒的等待时间更稳。不要把大文件存进数据库。权重文件、数据集这些放文件系统数据库里只存路径。这一点很多人会犯把二进制塞进 BLOB 字段结果数据库膨胀到几个 GB查询慢得离谱。3.3 训练进程与 Web 进程的边界怎么划这是整个架构里最关键的一个决策点。我的做法是Web 进程只做调度和查询训练进程独立运行两者通过数据库和文件系统通信。具体来说Web 层收到训练请求后往数据库写一条pending状态的任务记录然后由一个后台调度器可以是单独的线程或进程轮询数据库发现有 pending 任务就拉起训练子进程。训练子进程把日志写到文件把状态更新回数据库。Web 层查询时读数据库和日志文件即可。这样划分的好处是解耦彻底。训练崩了不影响 WebWeb 重启了训练照常跑。代价是状态同步有轻微延迟但对于训练这种分钟级、小时级的任务几秒的延迟完全可以接受。注意不要用 Web 进程直接subprocess.Popen拉起训练然后同步等待。我早期这么干过结果一个长训练把 worker 占满整个服务假死。一定要异步化。4. 数据库表结构设计几张表撑起整个平台4.1 核心表结构与字段取舍表结构不用多四张表就能撑起来。我把当时的设计整理如下字段做了简化但保留了关键部分。-- 数据集表 CREATE TABLE dataset ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, status TEXT DEFAULT ready, -- uploading / ready / invalid image_count INTEGER DEFAULT 0, class_count INTEGER DEFAULT 0, storage_path TEXT NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); -- 训练任务表 CREATE TABLE training_job ( id INTEGER PRIMARY KEY AUTOINCREMENT, dataset_id INTEGER NOT NULL, status TEXT DEFAULT pending, -- pending/running/succeeded/failed/canceled model_spec TEXT NOT NULL, -- 如 yolov8n epochs INTEGER DEFAULT 100, batch_size INTEGER DEFAULT 16, img_size INTEGER DEFAULT 640, learning_rate REAL DEFAULT 0.01, log_path TEXT, weight_path TEXT, started_at TIMESTAMP, finished_at TIMESTAMP, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (dataset_id) REFERENCES dataset(id) ); -- 指标表用于画曲线 CREATE TABLE metric ( id INTEGER PRIMARY KEY AUTOINCREMENT, job_id INTEGER NOT NULL, epoch INTEGER NOT NULL, loss REAL, precision REAL, recall REAL, map50 REAL, FOREIGN KEY (job_id) REFERENCES training_job(id) );字段设计上有几个取舍值得说。status用字符串而不是数字枚举虽然占空间但可读性好排查问题时直接看数据库一目了然。storage_path存相对路径而不是绝对路径方便整体迁移。指标单独建表而不是塞进任务表因为一个任务有几百个 epoch塞进去会变成一行超宽的表查询和更新都难受。4.2 状态流转与并发控制状态字段是整个系统的灵魂它的流转必须严格受控。我定义的状态机是这样的pending - running - succeeded - failed - canceled任何其他跳转都是非法的。比如不能从succeeded回到running也不能从pending直接到succeeded。实现上每次更新状态前先检查当前状态是否允许这次跳转不允许就拒绝。并发控制方面因为训练是串行的理论上不会有两个任务同时 running。但为了保险我在调度器里加了一个简单的锁调度前先查有没有 running 的任务有就跳过。这个检查用数据库事务包起来避免竞态。def try_acquire_job(): with db.transaction(): running db.query(SELECT id FROM training_job WHERE statusrunning LIMIT 1) if running: return None job db.query(SELECT id FROM training_job WHERE statuspending ORDER BY id LIMIT 1) if not job: return None db.execute(UPDATE training_job SET statusrunning, started_at? WHERE id?, (now(), job[id])) return job[id]这段逻辑虽然简单但把同一时间只有一个任务在跑这个约束落到了实处。4.3 数据集校验该放在哪一层数据集上传后必须校验否则训练跑到一半才发现标注格式不对浪费时间。校验放在哪一层有讲究。我的做法是分两步上传时做轻量校验训练前做完整校验。上传时只检查文件结构是否完整有没有 images 目录、有没有 labels 目录、数量是否对得上这个很快。训练前再跑一次完整校验检查每个标注文件的格式、类别 id 是否越界、图片是否能正常解码。为什么分两步因为完整校验很慢一个上万张图的数据集可能要跑几分钟。如果放在上传时同步做用户上传完要干等体验很差。放到训练前做用户点完开始训练后可以先去忙别的校验结果通过日志反馈。校验结果要落库dataset.status字段就是干这个的。校验不通过的数据集不允许被选来训练前端直接置灰。5. 训练调度与日志推送的落地细节5.1 调度器用轮询还是事件驱动调度器的实现方式有两种轮询和事件驱动。轮询就是每隔几秒查一次数据库事件驱动就是任务创建时发个信号。我最终选了轮询间隔 3 秒。原因很实际事件驱动需要引入消息队列或者进程间通信机制复杂度上去了而单机场景下轮询的开销可以忽略不计。3 秒的延迟对训练任务来说完全无感。轮询调度器的代码结构大概是这样import threading, time def scheduler_loop(): while True: try: job_id try_acquire_job() if job_id: launch_training(job_id) except Exception as e: log.error(scheduler error: %s, e) time.sleep(3) threading.Thread(targetscheduler_loop, daemonTrue).start()注意这里用 daemon 线程Web 服务退出时调度线程自动结束。launch_training内部再起独立进程跑训练不阻塞调度循环。5.2 训练日志怎么实时传到前端日志实时性是体验的关键。用户点了开始训练最想看到的就是日志在滚动。实现方式我试过两种最后选了 SSEServer-Sent Events。第一种是前端定时轮询日志接口每隔一两秒拉一次增量日志。实现简单但延迟高、请求多。第二种是 SSE服务端主动推延迟低、连接少。FastAPI 对 SSE 支持很好用StreamingResponse就能实现。核心逻辑是训练进程把日志写到文件SSE 接口持续读文件的新增内容并推给前端。这里有个细节读文件要记录上次读到的位置offset每次只读新增部分避免重复推送。app.get(/jobs/{job_id}/logs/stream) async def stream_logs(job_id: int): async def event_generator(): offset 0 while True: content, offset read_new_content(job_id, offset) if content: yield fdata: {content}\n\n if is_job_finished(job_id): yield data: [DONE]\n\n break await asyncio.sleep(1) return StreamingResponse(event_generator(), media_typetext/event-stream)提示SSE 连接要注意超时和断线重连。前端用EventSource会自动重连但服务端要能处理重复连接别让一个任务积累一堆僵尸连接。5.3 训练进程的启动与资源限制训练进程用subprocess拉起但有几个细节必须处理。第一是环境隔离。训练脚本依赖的 Python 环境和 Web 服务可能不一样最好用独立的虚拟环境或者容器。我图省事一开始用同一个环境结果 Web 依赖升级把训练依赖搞崩了后来老老实实分开。第二是资源限制。单机场景下要防止训练把内存吃光导致系统卡死。可以用resource模块限制子进程的内存或者用 cgroup。简单点的话在训练脚本里控制 dataloader 的 worker 数量别开太多。第三是优雅退出。用户点取消训练时要能真正杀掉训练进程而不是只改数据库状态。我的做法是记录子进程的 pid取消时发信号杀掉。注意要杀整个进程组因为训练脚本可能 fork 出子进程。import os, signal, subprocess proc subprocess.Popen(cmd, preexec_fnos.setsid) # 取消时 os.killpg(os.getpgid(proc.pid), signal.SIGTERM)preexec_fnos.setsid让子进程成为新进程组的组长这样killpg能一次杀掉整组。6. 踩过的坑与实测经验6.1 数据库锁冲突的真实排查过程上线第一周就遇到一个诡异问题偶尔训练任务卡在 pending 不动日志里报database is locked。一开始以为是并发太高但明明只有一个任务在跑。排查过程是这样的。先看错误堆栈定位到是调度器更新状态时锁库。然后查 SQLite 的锁机制发现默认的 rollback journal 模式下读操作会阻塞写操作。调度器在轮询查询时持有读锁训练进程更新状态时想拿写锁两者撞上就报错。解决方案就是前面提到的 WAL 模式。开启后读写可以并行问题消失。另外把busy_timeout设成 5000 毫秒给锁冲突一个等待窗口进一步降低报错概率。db.execute(PRAGMA journal_modeWAL;) db.execute(PRAGMA busy_timeout5000;)这个坑的教训是SQLite 的默认配置是给单连接场景优化的多进程访问必须调参。6.2 大文件上传把内存吃爆数据集上传是个大坑。一开始我用 FastAPI 的UploadFile直接接收然后一次性读进内存再写文件。小数据集没事一个 2GB 的 zip 传上来服务直接 OOM。后来改成流式写入分块读分块写内存占用稳定在几 MB。FastAPI 的UploadFile本身就是流式的关键是别用await file.read()一次性读而是用shutil.copyfileobj或者手动分块。app.post(/datasets/upload) async def upload(file: UploadFile): dest os.path.join(UPLOAD_DIR, file.filename) with open(dest, wb) as f: while chunk : await file.read(1024 * 1024): # 每次 1MB f.write(chunk) return {path: dest}分块大小 1MB 是个经验值太小了系统调用频繁太大了内存占用高。实测 1MB 到 4MB 之间都行。6.3 训练中断后状态不一致怎么修有次机器断电重启后发现一个任务状态是 running但实际训练进程早就没了。这种僵尸任务会阻塞整个队列因为调度器看到有 running 就不启动新任务。修复方案是加一个心跳机制。训练进程每隔一段时间更新任务的heartbeat_at字段调度器发现某个 running 任务的心跳超过阈值比如 5 分钟没更新就判定它已经死了把状态改成 failed。def check_zombie_jobs(): threshold now() - timedelta(minutes5) db.execute( UPDATE training_job SET statusfailed, finished_at? WHERE statusrunning AND heartbeat_at ? , (now(), threshold))这个检查放在调度循环里每次轮询时顺带跑一遍。加了之后断电、进程崩溃这些情况都能自动恢复不用人工干预。6.4 几个提升体验的小细节除了上面这些大坑还有几个小细节对体验提升很明显一并分享。参数默认值要合理。别让用户从零填给一套经过验证的默认值。比如 YOLO 的img_size默认 640batch_size根据显存自动推荐用户不改也能跑出个像样的结果。训练进度要有百分比。光有日志不够用户想知道还要多久。根据当前 epoch 和总 epoch 算个百分比前端画个进度条心理预期就稳了。失败原因要写清楚。训练失败时别只写个 failed把 stderr 的最后几十行存下来前端能展开看。很多失败是显存不够、数据格式错这类明确原因写清楚用户自己能解决。权重文件提供直接下载。训练完最想要的就是权重给个下载按钮别让人去服务器上找路径。7. 这套方案能走多远以及什么时候该换这套 FastAPI SQLite 的单机方案我用了大半年支撑了十几个内部项目最大的一个数据集两万多张图训练任务累计跑了几百次没出过系统性故障。对于小团队内部工具来说它的性价比非常高开发快、部署简单、维护成本低。但它有明确的天花板。当出现下面这些信号时就该考虑升级架构了需要多人同时训练单卡串行满足不了得上多卡调度SQLite 的写入压力也会上来。数据集规模到几十万张文件系统管理和校验都会变慢需要考虑对象存储。需要跨机器访问单机部署的服务只能本机访问要对外提供服务得考虑反向代理和认证。任务量到每天几十上百个轮询调度和文件日志的方式会显得笨重需要真正的任务队列。升级路径也很清晰SQLite 换 PostgreSQL轮询调度换 Celery 或类似的任务队列文件存储换对象存储训练进程换容器化调度。每一步都是平滑替换因为前面的领域建模和接口设计是通用的。我个人在实际操作中的体会是不要过早优化。很多团队一上来就上分布式、上消息队列结果业务量根本撑不起这套复杂度维护成本反而拖垮了项目。先用最简单的方案把流程跑通等真正遇到瓶颈了再升级这个顺序不能反。单机方案不是低配版它是特定规模下的最优解想清楚自己的规模选对工具比盲目追新技术重要得多。
