“今天的进度”放在本地 AI 工具链里通常不是一句闲聊而是一组很具体的状态任务队列跑到哪一条了、显存还剩多少、有没有任务失败、今天一共产出了多少结果。如果你同时跑过批量图片生成、批量文档解析、多个 TTS 合成任务就知道“今天进度如何”这件事本身比“今天做了什么”更难回答。这次我们从本地 AI 批量任务的进度管理角度讲一套能落地的方法任务目录怎么规划、日志怎么记录、接口怎么查询进度、批量任务怎么断点续跑。这篇文章适合正在把本地 AI 工具接进日常生产的读者。无论你用的是图像生成、OCR 文档解析、语音合成还是视频抽帧类工具只要涉及批量任务、多文件输入、WebUI 或 API 服务都可以直接参考。不用把“进度”理解成一个复杂平台的功能它完全可以靠一套合理的目录结构、日志规范和接口约定实现。1. 核心能力速览这套方案本质上不是一个单独的开源项目而是一套围绕“本地 AI 服务 任务队列 进度查询”的通用做法。它的核心能力可以整理成下面这张表能力项说明任务类型图片生成、OCR 解析、TTS 合成、视频抽帧等本地 AI 推理任务启动方式命令行 / WebUI / API 服务按实际项目选择进度记录通过日志文件、任务状态文件、输出目录共同记录接口查询提供status或progress接口返回当前任务队列状态批量任务支持输入目录遍历、逐个任务执行、失败重试和断点续跑显存要求取决于模型类型建议先小参数测试再决定批量大小适合场景内容生产、数据清洗、文档转写、图像批量处理使用边界涉及人脸、声音、版权素材时需要先确认授权有一点需要明确不同工具的任务提交方式和输出格式差异很大。下面给出的命令和接口示例是通用模板具体路径、端口、参数需要替换成你实际使用的项目配置。2. 适用场景与使用边界2.1 适合谁内容生产者每天批量生成配图、缩略图需要知道今天完成了多少张、失败了多少张。文档处理用户用 OCR 模型解析大量 PDF需要记录每个文件的解析状态和输出 Markdown 路径。语音合成用户批量合成多段音频需要按文本文件逐条执行并记录每个片段的输出位置。本地工具链维护者把 WebUI 或 API 服务接到自己的脚本里需要一套稳定的任务状态查询方式。这类场景有一个共同特点任务量大、单条任务时长短、失败需要重试。如果只是偶尔跑一张图、转一段文字“进度”不是刚需一旦进入批量阶段进度管理就直接影响效率。2.2 不适合什么场景需要多人协作、实时看板、权限管理的团队任务调度应该用更完整的任务队列系统。任务之间有复杂依赖关系的流程例如 A 任务完成后才能触发 B 任务建议使用工作流引擎。单次任务就要跑数小时的大模型训练这类进度管理需要专门的训练日志和检查点机制。2.3 使用边界与合规提醒使用本地 AI 工具处理批量任务时有几个底线必须守住处理人脸图片时需要确认图片来源合法并且获得了人脸信息的使用授权。处理语音数据时需要确认声音素材的授权范围不能随意克隆或合成他人声线用于商用。处理版权素材时例如书籍扫描件、付费文档、影视截图需要确认你是否有权进行解析和转写。涉及用户隐私数据时建议先在完全隔离的测试环境中验证避免数据泄露。本地部署的优势是数据不出本机但这不等于可以随便处理他人数据。合规边界永远优先于技术效率。3. 前置条件与目录规划3.1 环境准备在开始跑批量任务之前先把基础环境核对一遍操作系统建议使用 Linux 或 WindowsMac 要看具体项目是否支持。Python 版本多数本地 AI 工具依赖 Python 3.10 或 3.11具体版本以项目文档为准。GPU 驱动与 CUDANVIDIA 显卡需要安装对应版本的驱动和 CUDA 工具包AMD 或 Apple Silicon 需要看项目是否支持。依赖管理建议每个项目使用独立虚拟环境避免依赖冲突。磁盘空间模型文件、输入素材、输出结果需要分开目录存放建议预留至少模型体积 2 倍的剩余空间。如果你不确定当前机器的显卡和显存情况在系统里执行下方命令查看# Windows nvidia-smi # Linux nvidia-smi # macOS system_profiler SPDisplaysDataTypenvidia-smi可以看到显卡型号、驱动版本、显存总量和当前占用。这是后面观察显存占用最直接的命令。3.2 目录结构设计“今天的进度”能不能一眼看懂很大程度上取决于目录设计。推荐按下面这种方式组织project/ ├── inputs/ # 输入素材按日期或批次分目录 │ └── 20250115/ ├── outputs/ # 输出结果 │ └── 20250115/ ├── logs/ # 运行日志 │ └── 20250115.log ├── status/ # 任务状态文件 │ └── 20250115.json └── scripts/ # 启动脚本和批量任务脚本按日期分目录的好处是每天的任务输入、输出、日志、状态都可以对应起来。想查“昨天的进度”直接看昨天的 logs 和 status 文件想复现当天结果直接找当天的 inputs 和 outputs。如果你的任务量不大也可以简化成 inputs、outputs、logs 三个目录但状态文件建议保留。它是批量任务断点续跑的基础。4. 任务启动与进度记录方式4.1 手动运行单条任务本地 AI 工具通常会有两种启动方式WebUI 页面和命令行 API。先用命令行跑通一条单任务确认模型能正常加载、输出目录能正常写入再进入批量阶段。以 API 服务为例启动命令通常是这样的形式# 示例命令具体参数需要按实际项目调整 python app.py --host 127.0.0.1 --port 7860启动后服务会监听本地的7860端口。浏览器打开http://127.0.0.1:7860可以进入 WebUI 页面命令行可以通过接口提交任务。启动时需要注意几点如果端口被占用更换端口号或者先杀掉占用进程。日志输出到控制台的同时建议同时写入日志文件。首次启动会加载模型文件耗时可能较长属于正常现象。4.2 给日志加上时间戳进度管理的第一个关键动作是让日志带上时间戳。很多默认日志只输出任务名称和结果摘要缺少时间信息导致后来很难判断一个任务到底跑了多久。Python 的logging模块配置时间戳并不复杂import logging logging.basicConfig( levellogging.INFO, format%(asctime)s [%(levelname)s] %(message)s, datefmt%Y-%m-%d %H:%M:%S, handlers[ logging.FileHandler(logs/20250115.log, encodingutf-8), logging.StreamHandler() ] )之后在任务脚本里调用logging.info(开始处理任务input_001.png) # 这里是调用模型的代码 logging.info(任务完成input_001.png - output_001.png)这样日志文件里就会出现类似下面的内容2025-01-15 09:00:12 [INFO] 开始处理任务input_001.png 2025-01-15 09:00:47 [INFO] 任务完成input_001.png - output_001.png 2025-01-15 09:00:47 [INFO] 开始处理任务input_002.png到这一步你已经拥有了一个最基础但可用的进度记录系统。接下来可以通过状态文件实现批量任务的进度追踪。5. 功能测试从单任务到批量任务5.1 功能验证维度不管底层是什么模型建议按以下维度做验证单任务能否成功执行输出文件是否完整。任务执行时间是否符合预期。显存占用是否稳定有没有溢出风险。连续执行多个任务时服务是否稳定。失败任务能否定位原因并重试。输出文件名是否与输入文件名有明确的对应关系。5.2 批量任务脚本批量任务的核心逻辑是遍历输入目录逐个提交任务记录每个任务的状态。下面是一个通用模板适用于大部分支持 API 调用的本地 AI 工具import json import logging import os import time from pathlib import Path import requests # 配置 INPUT_DIR Path(inputs/20250115) OUTPUT_DIR Path(outputs/20250115) STATUS_FILE Path(status/20250115.json) API_URL http://127.0.0.1:7860/api/generate OUTPUT_DIR.mkdir(parentsTrue, exist_okTrue) STATUS_FILE.parent.mkdir(parentsTrue, exist_okTrue) # 加载已有状态用于断点续跑 status {} if STATUS_FILE.exists(): with open(STATUS_FILE, r, encodingutf-8) as f: status json.load(f) input_files sorted(INPUT_DIR.glob(*)) for idx, file_path in enumerate(input_files, start1): if file_path.name in status and status[file_path.name] done: logging.info(跳过已完成任务%s, file_path.name) continue # 提交任务这里需要按实际项目调整请求参数 payload { filename: file_path.name, output_dir: str(OUTPUT_DIR), } try: logging.info(处理中%d/%d%s, idx, len(input_files), file_path.name) response requests.post(API_URL, jsonpayload, timeout600) response.raise_for_status() # 标记成功 status[file_path.name] done with open(STATUS_FILE, w, encodingutf-8) as f: json.dump(status, f, ensure_asciiFalse, indent2) except Exception as e: status[file_path.name] ferror: {e} with open(STATUS_FILE, w, encodingutf-8) as f: json.dump(status, f, ensure_asciiFalse, indent2) logging.error(任务失败%s错误%s, file_path.name, e) # 每个任务之间稍作间隔避免请求过密 time.sleep(1)这个脚本最关键的一点是每完成一个任务就把状态写入 JSON 文件。下次再运行脚本时已完成的任务会被跳过失败或者未执行的任务会继续处理这就是断点续跑的基础。5.3 状态文件示例运行一段时间后status/20250115.json的内容大概是这样的{ input_001.png: done, input_002.png: done, input_003.png: error: HTTP 500 Internal Server Error, input_004.png: done }查看这个文件就能知道哪些任务成功了哪些失败了失败原因是什么。这比看一张进度条要可靠得多因为批量任务往往不是顺序执行一次就完而是需要反复排查和重试的。5.4 判断成功的标准一个任务是否真正成功不能只看日志提示“完成”。建议做以下确认输出文件是否存在且大小不为 0。输出文件内容是否符合预期例如图片能正常打开、音频文件可以播放、OCR 结果包含目标文本。API 是否返回了成功状态码。日志中是否有隐性警告例如显存接近上限导致的自动降级。6. 接口 API 与页面化进度查询6.1 为什么需要接口日志文件能解决事后排查但在任务运行过程中你很可能想随时看一眼“现在跑到第几个了”。这时候需要 API 提供实时状态。很多本地 AI 工具本身带有进度查询接口例如 ComfyUI 的队列查询、TTS 服务的任务状态查询。如果你的工具没有现成接口可以自己写一个简单的状态服务读取 status JSON 文件并返回。6.2 一个轻量级进度接口示例下面这一段可以作为参考用 Flask 或 FastAPI 写一个极简的状态查询接口from flask import Flask, jsonify import json from pathlib import Path app Flask(__name__) STATUS_FILE Path(status/20250115.json) app.route(/api/progress, methods[GET]) def get_progress(): if not STATUS_FILE.exists(): return jsonify({total: 0, done: 0, failed: 0, tasks: {}}) with open(STATUS_FILE, r, encodingutf-8) as f: status json.load(f) total len(status) done sum(1 for v in status.values() if v done) failed sum(1 for v in status.values() if v.startswith(error)) return jsonify({ total: total, done: done, failed: failed, remaining: total - done - failed, tasks: status }) if __name__ __main__: # 只监听本机地址避免外部访问 app.run(host127.0.0.1, port8900)启动这个服务后浏览器打开http://127.0.0.1:8900/api/progress看到的内容类似{ total: 4, done: 2, failed: 1, remaining: 1, tasks: { input_001.png: done, input_002.png: done, input_003.png: error: HTTP 500 Internal Server Error, input_004.png: done } }这样可以通过 curl 直接查询curl http://127.0.0.1:8900/api/progress接口能力可以让进度管理从“手动看日志”升级为“脚本自动查询”。如果你愿意还可以写一个更简单的 Web 页面定时刷新这样在 WebUI 旁边开一个小窗口就能看到整体进度。6.3 批量任务队列设计建议当任务量很大时直接在一个循环里顺序跑会存在几个问题单个任务卡住会导致整个队列卡住。中途中断后虽然状态文件能帮助续跑但已经输出的结果不会自动清理。任务之间没有依赖关系时其实可以考虑并发但显存和内存需要评估。建议采用简单的“单进程顺序执行 状态文件记录 失败重试”模式。顺序执行虽然慢但稳定显存占用可控。如果你的显卡显存足够大可以尝试同时运行 2 到 4 个任务但需要预先观察显存占用避免 OOM。7. 资源占用与性能观察7.1 显存占用怎么看观察显存占用最简单的方式是执行nvidia-smi可以看到每个进程的显存使用量。批量任务运行时建议注意以下几点显存占用与模型大小、输入分辨率、批量大小直接相关不同工具差异很大。显存不足时任务通常会报错错误信息里可能包含out of memory、CUDA OOM等关键词。如果显存比较紧张可以选择降低分辨率、减少并发数、使用 CPU 推理速度会慢很多。7.2 性能影响要素影响批量任务整体耗时的因素主要包括模型大小模型参数越多单次推理越慢。输入大小图片分辨率、音频时长、文本长度都会影响推理时间。批量大小适当地提高批量大小可以提升 GPU 利用率但会提高显存占用。并发任务数并发任务越多资源竞争越明显单个任务速度反而可能下降。建议第一次跑批量任务时先用 5 到 10 个小样本测试记录单任务耗时和显存占用再放大到完整数据集。这样可以避免大规模任务跑到一半发现显存不够或者耗时长到无法接受。7.3 降低显存占用的常用做法如果你的显卡显存有限常规思路包括降低输入分辨率比如图片从 1024 降到 768。减少批量大小从 4 降到 2 或 1。使用模型 fp16 或 int8 量化版本前提是工具支持且质量可接受。清理显存缓存检查是否有残留进程占住显存。尽量避免多个 WebUI 服务同时运行互相挤占显存。8. 常见问题与排查方法问题现象可能原因排查方式解决方案启动后页面打不开端口被占用或服务未启动检查日志和端口监听状态更换端口或重启服务例如接口只监听 127.0.0.1 时外部访问会失败依赖安装失败Python 版本不匹配或网络原因导致包下载失败检查错误日志中的包名和版本要求使用镜像源、创建独立虚拟环境、按项目文档固定依赖版本模型文件缺失模型文件未下载完整或路径配置错误检查模型目录和启动日志重新下载模型文件确认路径配置正确CUDA 相关报错显卡驱动、CUDA 版本与框架版本不匹配运行nvidia-smi查看驱动版本检查 PyTorch 版本按框架要求安装对应 CUDA 版本或换用 CPU 推理验证显存不足CUDA OOM分辨率、批量大小或并发数设置过高观察任务失败时的显存占用降低批量大小、降低分辨率、减少并发数批量任务卡住单条任务请求没有超时或超时时间过短查看当前进程的 CPU / GPU 占用和网络状态增加请求超时时间或在脚本中加入单任务超时退出逻辑输出文件缺失任务实际未完成但被标记为成功打印输出文件路径并检查文件大小在脚本中增加“输出文件存在且大小大于 0”的成功判断状态文件越来越乱多个脚本同时写同一个 JSON 文件确认是否有多进程同时运行建议单进程顺序执行避免并发写同一状态文件API 查询返回慢状态文件过大查看文件大小和读取耗时按日期拆分状态文件或定期归档旧任务9. 最佳实践与使用建议9.1 第一次先小参数测试批量任务最容易踩的坑是一上来就用大批量、高分辨率测试。建议先跑 5 到 10 个样本确认单任务耗时、显存占用、输出质量符合预期再放大任务量。如果小样本测试就出现显存不足或者服务崩溃放大任务量只会更严重。9.2 保留一套最小可运行配置每次调试完把能跑通的最小配置单独保存下来。包括启动命令、Python 依赖清单、模型文件路径、输入素材样例。这样后续环境变化时可以快速恢复到可用状态。9.3 目录与状态文件规范化输入素材、输出结果、运行日志、状态文件分目录管理并且按日期命名。看似多花了几秒钟但后续排查问题、重跑任务、汇报进度都会非常省事。输出文件命名建议包含输入文件名和任务标识例如input_001__done.png。9.4 批量任务加入日志与失败重试不要让失败任务静默跳过。每个失败任务至少记录日志和状态文件。重试时不要无脑重跑全部任务而是通过状态文件找出失败或未完成的任务单独处理。9.5 接口服务限制访问范围如果启动 API 服务建议默认绑定127.0.0.1不要绑定0.0.0.0避免局域网其他设备直接访问。如果确实需要远程使用要加上简单的访问控制或至少使用防火墙限制端口。本地 AI 服务通常没有内置权限认证暴露在公网有风险。9.6 涉及人脸、声音、版权素材必须确认授权无论是图像生成、声音克隆还是文档解析只要素材涉及他人肖像、声音、版权内容都要先确认授权范围。本地部署不能作为免责理由合规要求仍然存在。发布或商用前需要做效果复核。9.7 发布或商用前复核输出AI 工具的批量输出可以节省大量时间但质量并不总是稳定。建议在正式发布或商用前抽查输出结果确认没有明显瑕疵或侵权内容。尤其是人脸、文字、标识等敏感信息需要人工复核。9.8 定期清理旧日志和旧输出日志文件和输出文件会快速累积。建议每个批次结束后归档每月清理一次早期日志避免磁盘空间被无限占用。10. 总结与下一步“今天的进度”在本地 AI 批量任务中并不难实现。核心是三个动作按日期规划输入输出目录用状态文件记录每个任务的成功与失败用日志时间戳记录执行耗时。这三个动作做完你已经可以从容回答任何一天的任务进度。如果想要更进一步可以再加一个轻量级进度查询接口把状态文件变成可以随时访问的 API。这套方法最适合的场景是每天固定跑一批 AI 任务的个人或小团队。它不依赖复杂平台不需要额外数据库只要会写简单的 Python 脚本就可以维护。需要最先验证的是你的服务能不能稳定处理批量任务状态文件在断点续跑时是否准确显存占用在连续运行后是否保持不变。最容易踩的坑则是没有给任务设置合理的超时时间导致一个失败任务卡住整个队列。建议先把你当前最常用的本地 AI 工具接进来跑一个 10 条任务的样本把状态文件生成出来。确认这套流程能流畅运转后再逐步扩展到日常生产。等积累一段时间这些日志和状态文件会成为你复盘效率、优化参数最有价值的数据。