FastAPI+SQLite单机部署YOLO训练平台：任务管理与数据集管理实战

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 用户真正在意的三个动作

做完建模之后，我找几个实际会用这个工具的同事聊了一圈，发现他们真正关心的动作只有三个：上传数据、发起训练、看结果。其他都是锦上添花。

这个结论很重要，它直接决定了前端页面的复杂度。我最后只做了三个主页面加一个任务列表页，没有做复杂的权限系统、没有做花哨的仪表盘。事实证明这个取舍是对的，工具上线后几乎没人问"这个按钮在哪"，学习成本接近于零。

具体到每个动作的细节需求：

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_mode=WAL;即可。
• 设置合理的 busy_timeout。避免偶发的锁冲突直接报错，设置成几秒的等待时间更稳。
• 不要把大文件存进数据库。权重文件、数据集这些放文件系统，数据库里只存路径。这一点很多人会犯，把二进制塞进 BLOB 字段，结果数据库膨胀到几个 GB，查询慢得离谱。

3.3 训练进程与 Web 进程的边界怎么划

这是整个架构里最关键的一个决策点。我的做法是：Web 进程只做调度和查询，训练进程独立运行，两者通过数据库和文件系统通信。

具体来说，Web 层收到训练请求后，往数据库写一条pending状态的任务记录，然后由一个后台调度器（可以是单独的线程或进程）轮询数据库，发现有 pending 任务就拉起训练子进程。训练子进程把日志写到文件，把状态更新回数据库。Web 层查询时读数据库和日志文件即可。

这样划分的好处是解耦彻底。训练崩了不影响 Web，Web 重启了训练照常跑。代价是状态同步有轻微延迟，但对于训练这种分钟级、小时级的任务，几秒的延迟完全可以接受。

注意：不要用 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 status='running' LIMIT 1") if running: return None job = db.query("SELECT id FROM training_job WHERE status='pending' ORDER BY id LIMIT 1") if not job: return None db.execute("UPDATE training_job SET status='running', 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(target=scheduler_loop, daemon=True).start()

注意这里用 daemon 线程，Web 服务退出时调度线程自动结束。launch_training内部再起独立进程跑训练，不阻塞调度循环。

5.2 训练日志怎么实时传到前端

日志实时性是体验的关键。用户点了开始训练，最想看到的就是日志在滚动。实现方式我试过两种，最后选了 SSE（Server-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 f"data: {content}\n\n" if is_job_finished(job_id): yield "data: [DONE]\n\n" break await asyncio.sleep(1) return StreamingResponse(event_generator(), media_type="text/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_fn=os.setsid) # 取消时 os.killpg(os.getpgid(proc.pid), signal.SIGTERM)

preexec_fn=os.setsid让子进程成为新进程组的组长，这样killpg能一次杀掉整组。

6. 踩过的坑与实测经验

6.1 数据库锁冲突的真实排查过程

上线第一周就遇到一个诡异问题：偶尔训练任务卡在 pending 不动，日志里报database is locked。一开始以为是并发太高，但明明只有一个任务在跑。

排查过程是这样的。先看错误堆栈，定位到是调度器更新状态时锁库。然后查 SQLite 的锁机制，发现默认的 rollback journal 模式下，读操作会阻塞写操作。调度器在轮询查询时持有读锁，训练进程更新状态时想拿写锁，两者撞上就报错。

解决方案就是前面提到的 WAL 模式。开启后读写可以并行，问题消失。另外把busy_timeout设成 5000 毫秒，给锁冲突一个等待窗口，进一步降低报错概率。

db.execute("PRAGMA journal_mode=WAL;") db.execute("PRAGMA busy_timeout=5000;")

这个坑的教训是：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(minutes=5) db.execute(""" UPDATE training_job SET status='failed', finished_at=? WHERE status='running' AND heartbeat_at < ? """, (now(), threshold))

这个检查放在调度循环里，每次轮询时顺带跑一遍。加了之后，断电、进程崩溃这些情况都能自动恢复，不用人工干预。

6.4 几个提升体验的小细节

除了上面这些大坑，还有几个小细节对体验提升很明显，一并分享。

参数默认值要合理。别让用户从零填，给一套经过验证的默认值。比如 YOLO 的img_size默认 640，batch_size根据显存自动推荐，用户不改也能跑出个像样的结果。

训练进度要有百分比。光有日志不够，用户想知道"还要多久"。根据当前 epoch 和总 epoch 算个百分比，前端画个进度条，心理预期就稳了。

失败原因要写清楚。训练失败时别只写个 "failed"，把 stderr 的最后几十行存下来，前端能展开看。很多失败是显存不够、数据格式错这类明确原因，写清楚用户自己能解决。

权重文件提供直接下载。训练完最想要的就是权重，给个下载按钮，别让人去服务器上找路径。

7. 这套方案能走多远，以及什么时候该换

这套 FastAPI + SQLite 的单机方案，我用了大半年，支撑了十几个内部项目，最大的一个数据集两万多张图，训练任务累计跑了几百次，没出过系统性故障。对于小团队内部工具来说，它的性价比非常高：开发快、部署简单、维护成本低。

但它有明确的天花板。当出现下面这些信号时，就该考虑升级架构了：

• 需要多人同时训练：单卡串行满足不了，得上多卡调度，SQLite 的写入压力也会上来。
• 数据集规模到几十万张：文件系统管理和校验都会变慢，需要考虑对象存储。
• 需要跨机器访问：单机部署的服务只能本机访问，要对外提供服务得考虑反向代理和认证。
• 任务量到每天几十上百个：轮询调度和文件日志的方式会显得笨重，需要真正的任务队列。

升级路径也很清晰：SQLite 换 PostgreSQL，轮询调度换 Celery 或类似的任务队列，文件存储换对象存储，训练进程换容器化调度。每一步都是平滑替换，因为前面的领域建模和接口设计是通用的。

我个人在实际操作中的体会是，不要过早优化。很多团队一上来就上分布式、上消息队列，结果业务量根本撑不起这套复杂度，维护成本反而拖垮了项目。先用最简单的方案把流程跑通，等真正遇到瓶颈了再升级，这个顺序不能反。单机方案不是"低配版"，它是特定规模下的最优解，想清楚自己的规模，选对工具，比盲目追新技术重要得多。