Xing's blog

VPS DueGuard：把多家 VPS 续费和流量监控收进 Telegram

Wed, 03 Jun 2026 00:00:00 +0000

如果你和我一样，会在不同商家手里放着几台低价 VPS，那大概率也遇到过这类小麻烦：每家后台都要单独登录，续费日期散落在不同页面，流量用量也要点进去看；等到想起来检查时，可能已经快到期了。

VPS DueGuard 就是为这个场景写的一个轻量工具。它不是完整的监控系统，而是更聚焦在「VPS 服务清单、续费日期、流量使用、Telegram 提醒」这几件高频但容易遗忘的小事上。

它解决的是什么问题

很多低价 VPS 商家使用 WHMCS / Lagom 风格相近的用户面板。服务列表、续费时间、流量信息通常都能在后台找到，但问题是：

账号分散在多个商家；
每次查看都要登录不同面板；
有些服务只在临近续费时才会想起来；
流量用量需要点进详情页才能确认；
想要一个每日汇总，还得自己手动整理。

VPS DueGuard 的思路比较直接：把多个提供商配置到一个 config.yaml 里，然后通过脚本统一查询。能拿到的服务信息会被整理成统一输出，并可通过 Telegram Bot 随时查看。

主要功能

这个项目目前比较适合下面几类需求：

功能	说明
多商家服务汇总	统一列出多个 WHMCS / Lagom 风格面板中的活跃 VPS 服务
续费日期提醒	在配置的提醒窗口内，通过 Telegram 发送续费提醒
流量概览	读取面板中暴露的已用流量、总流量和剩余流量
Telegram Bot 查询	通过 `/summary`、`/traffic`、`/renewals` 等命令查看最新状态
Cookie 会话缓存	尽量复用登录 Cookie，减少重复登录，也让后续查询更快
Linux 菜单部署	通过 `vpsm.sh` 提供安装、配置、测试、日志、卸载等菜单入口
systemd 定时任务	支持日报、续费检查、Bot 服务等 systemd 管理方式

它的定位不是替代 Prometheus、Uptime Kuma 这类监控工具。它更像是一个「VPS 到期和流量管家」：不关注 CPU、内存、端口存活，而是关注账单和面板里已经存在的信息。

快速安装

项目为 Debian / Ubuntu 准备了菜单式部署脚本。最简单的使用方式是：

1
2
3


git clone https://github.com/xing-xing-coder/vps-dueguard.git
cd vps-dueguard
sudo bash vpsm.sh

执行后会进入一个双语菜单，可以在里面完成安装、添加服务商、测试查询、配置 Telegram、启用 systemd 服务等操作。详细步骤参考VPS DueGuard。

安装完成后，后续可以直接通过下面的命令重新打开菜单：

1

vpsm

配置提供商

菜单会把配置写入：

1

/opt/vps-dueguard/config.yaml

配置结构大致如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


providers:
 - name: provider-a
 base_url: https://example-provider-a.com/
 username: your@email.com
 password: your-password

 - name: provider-b
 base_url: https://example-provider-b.com/
 username: your@email.com
 password: your-password

这里的 name 建议写得短一些，因为后续 Telegram Bot 可以用类似下面的命令单独查询某一家：

1

/provider provider-a

需要注意的是，VPS DueGuard 主要面向 WHMCS / Lagom 风格的客户区页面。不同商家的页面结构、登录流程、风控策略、语言设置都可能不同，所以兼容性不能保证百分百一致。如果遇到某家无法读取，通常需要先从菜单里跑一次单商家测试，再结合日志判断是登录失败、页面结构变化，还是被验证码 / 2FA 等机制挡住了。

Telegram Bot：最方便的入口

我比较喜欢这个项目的一点，是它没有要求你一直 SSH 到服务器上看输出。配置好 Telegram Bot Token 和 Chat ID 之后，就可以直接在 Telegram 里查询 VPS 状态。

常用命令包括：

1
2
3
4
5
6


/summary
/traffic
/renewals
/provider provider-a
/refresh
/help

其中：

/summary：查看所有活跃 VPS、续费日期和流量概览；
/traffic：只看流量使用情况；
/renewals：只看续费日期和剩余天数；
/provider provider-a：查询某一个服务商；
/refresh：强制刷新 5 分钟缓存；
/help：查看帮助。

为了安全，项目只允许配置中的 chat_id 查询 VPS 信息。也就是说，即使别人知道了你的 Bot，也不能直接拿它查你的服务状态。

续费提醒和日报

默认续费提醒窗口是：

1

21,14,7,3

也就是服务进入 21 天、14 天、7 天、3 天这些窗口时，可以触发提醒。项目会用本地状态文件做去重，避免同一个服务在同一个提醒阈值下反复发送通知。

除了续费提醒，它也可以通过 systemd timer 发送每日汇总。对 VPS 数量比较多的人来说，这种日报很实用：不用每天主动想起来检查，到点就能看到一份当前服务状态。

systemd 管理

安装器会创建几个 systemd 单元，用来运行 Bot、日报和续费检查：

1
2
3


vps-dueguard-bot.service
vps-dueguard-daily.timer
vps-dueguard-renewals.timer

常见管理命令如下：

1
2
3


sudo systemctl restart vps-dueguard-bot.service
sudo systemctl status vps-dueguard-bot.service
sudo systemctl list-timers 'vps-dueguard-*'

查看日志可以用：

1
2
3


sudo journalctl -u vps-dueguard-bot.service -n 100 --no-pager
sudo journalctl -u vps-dueguard-daily.service -n 100 --no-pager
sudo journalctl -u vps-dueguard-renewals.service -n 100 --no-pager

隐私和安全提醒

这类工具最需要注意的是配置文件安全。config.yaml 里会保存服务商账号密码、Telegram Bot Token 等敏感信息。项目安装时会把配置文件权限设为 600，但日常使用时仍然建议注意：

不要把 config.yaml 上传到公开仓库；
不要在 issue、截图、日志里泄露账号、Token、服务地址、续费日期或流量信息；
不要把 Cookie 会话目录打包分享；
只监控自己拥有或明确被授权管理的 VPS 账号；
不要用它绕过验证码、2FA、访问控制、限速或商家的反自动化机制。

项目本身也明确说明，它不会绕过 CAPTCHA、2FA、访问控制、限速或反机器人机制。因此更合适的使用方式，是把它当作一个面向自有账号的自动化整理工具，而不是任何形式的绕过工具。

适合谁使用

我觉得 VPS DueGuard 特别适合这几类用户：

手里有多台 VPS，且分散在不同商家；
经常忘记某台机器什么时候续费；
想定期看看流量是否快用完；
不想部署一整套重型监控系统；
喜欢用 Telegram 接收服务器相关通知；
希望通过一个菜单完成安装、测试、启停和卸载。

如果你只有一台 VPS，或者只需要监控机器是否在线，那它可能不是必需品。但如果你长期维护多个低价 VPS，尤其是不同商家之间来回切换，它能省掉不少重复登录后台的时间。

小结

VPS DueGuard 是一个很典型的「小而准」工具：它没有试图做成通用监控平台，而是盯住 VPS 用户经常遇到的续费、流量、服务列表和 Telegram 通知问题。

它最吸引我的地方有三个：

部署入口简单，vpsm 菜单对日常维护比较友好；
Telegram Bot 查询自然，适合随手看状态；
功能边界清晰，不绕过验证码和安全机制，只做授权账号下的信息整理。

如果你也有多家 VPS 需要管理，可以看看这个项目：VPS DueGuard

Windows PowerShell 中文乱码的解决方法：永久启用 UTF-8

Tue, 02 Jun 2026 00:00:00 +0000

问题现象

在 Windows 的终端或 PowerShell 中，有时会遇到中文显示异常的问题，例如：

中文显示为乱码；
中文显示为问号；
某些命令输出中文时无法正常显示；
Python、Git、npm 等工具在终端里输出中文异常。

这类问题通常和终端编码、PowerShell 输出编码或字体设置有关。

本文记录一种常用解决方法：让 PowerShell 默认使用 UTF-8 编码。

解决思路

PowerShell 中影响中文显示的关键点主要有三个：

当前终端代码页是否为 UTF-8；
PowerShell 的输出编码是否为 UTF-8；
终端字体是否支持中文。

其中，UTF-8 对应的代码页是：

1

65001

如果 PowerShell 每次打开后都自动切换到 65001，并且输出编码也是 UTF-8，那么大多数中文乱码问题都可以解决。

永久设置 PowerShell 使用 UTF-8

打开 PowerShell，执行：

1

notepad $PROFILE

如果提示文件不存在，就选择新建。

然后在打开的配置文件中加入下面内容：

1
2
3


chcp 65001 > $null
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

保存文件后，关闭当前 PowerShell 窗口，并重新打开一个新的 PowerShell。

配置说明

这三行配置分别表示：

1

chcp 65001 > $null

将当前终端代码页切换为 UTF-8。
> $null 的作用是隐藏 Active code page: 65001 这类提示信息，让每次打开 PowerShell 时界面更干净。

1

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

设置控制台输出编码为 UTF-8。

1

$OutputEncoding = [System.Text.Encoding]::UTF8

设置 PowerShell 向外部程序传递文本时使用 UTF-8 编码。

如何测试是否成功

重新打开一个新的 PowerShell 窗口后，依次执行下面命令：

1

chcp

如果输出类似下面这样：

1

Active code page: 65001

说明当前终端代码页已经是 UTF-8。

继续测试中文输出：

1

echo 中文测试

如果能够正常显示：

1

中文测试

说明终端已经可以正常显示中文。

再检查 PowerShell 的输出编码：

1
2


[Console]::OutputEncoding.CodePage
$OutputEncoding.CodePage

如果两个结果都是：

说明 PowerShell 的输出编码也已经设置为 UTF-8。

也可以使用下面这组命令一次性检查：

1
2
3
4


chcp
echo 中文测试
[Console]::OutputEncoding.CodePage
$OutputEncoding.CodePage

理想结果类似：

1
2
3
4


Active code page: 65001
中文测试
65001
65001

出现这个结果，就说明 UTF-8 配置已经生效。

实际测试结果示例

下面是一次成功配置后的测试结果：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


PS C:\Users\xx> chcp
Active code page: 65001

PS C:\Users\xx> echo 中文测试
中文测试

PS C:\Users\xx> [Console]::OutputEncoding.CodePage
65001

PS C:\Users\xx> $OutputEncoding.CodePage
65001

这说明：

当前代码页是 UTF-8；
中文可以正常输出；
PowerShell 控制台输出编码是 UTF-8；
PowerShell 的 $OutputEncoding 也是 UTF-8。

因此可以判断：配置成功。

如果仍然乱码怎么办

如果上面的测试都通过了，但某些地方仍然显示乱码，可以继续检查下面几项。

1. 检查 Windows Terminal 字体

如果字体不支持中文，中文可能会显示成方块、问号或异常字符。

可以在 Windows Terminal 中打开：

1

设置 → 配置文件 → PowerShell → 外观 → 字体

推荐使用支持中文的字体，例如：

Microsoft YaHei UI
Microsoft YaHei
SimSun
Sarasa Mono SC
Noto Sans Mono CJK SC

2. 检查具体程序的编码

如果只有某些程序乱码，例如 Python、Git、npm、旧版 exe 程序，那么问题可能不在 PowerShell，而在这些程序本身的编码设置。

例如 Git 中文文件名乱码，可以尝试：

1

git config --global core.quotepath false

Python 可以尝试启用 UTF-8 模式：

1

$env:PYTHONUTF8=1

或者运行脚本时使用：

1

python -X utf8 your_script.py

3. 优先使用新版 PowerShell

Windows 自带的 Windows PowerShell 5.1 对 UTF-8 的支持不如新版 PowerShell 7。

可以通过下面命令查看版本：

1

$PSVersionTable.PSVersion

如果是 Windows PowerShell 5.1，建议安装 PowerShell 7 后再使用。

总结

Windows PowerShell 中文乱码通常可以通过设置 UTF-8 编码解决。

推荐在 $PROFILE 中加入：

1
2
3


chcp 65001 > $null
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8

然后重新打开 PowerShell，并使用下面命令确认：

1
2
3
4


chcp
echo 中文测试
[Console]::OutputEncoding.CodePage
$OutputEncoding.CodePage

只要代码页和编码都显示为 65001，并且中文可以正常输出，就说明配置已经成功。

N2830 小主机安装 Linux 卡死的处理记录

Mon, 01 Jun 2026 00:00:00 +0000

最近折腾一台 Intel Celeron N2830 小主机安装 Linux，遇到了安装过程卡死、Live USB 启动后假死、装完系统后随机冻结的问题。最后发现问题大概率不是硬盘、内存或者安装镜像损坏，而是 Bay Trail 平台常见的 C-State 省电状态兼容问题。其他N28XX系列主机若遇到相同问题可以参考此方法尝试解决。

问题现象

这台机器的表现大概是这样：

启动 Linux 安装 U 盘后，进入安装器没多久就卡死；
有时可以进 Live 系统，但操作一会儿整机冻结；
鼠标、键盘都没有反应；
SSH 也连不上；
屏幕停在最后一帧，没有明显报错；
只能长按电源强制关机。

这种卡死很容易被误判成 U 盘、硬盘、内存、显卡驱动或者发行版本身的问题。但如果机器是 Intel Bay Trail 一类低功耗平台，例如 Celeron N2830、N2840、J1900 等，优先应该怀疑 CPU 深度省电状态导致的冻结问题。

原因

N2830 属于 Intel Bay Trail 时代的低功耗处理器。这类机器在 Linux 下可能会因为 CPU 进入过深的 C-State 省电状态而无法正常唤醒，表现为整机无响应。

简单说，就是 Linux 的电源管理为了省电，会让 CPU 进入更深的 idle 状态。但某些 Bay Trail 设备进入这些状态后稳定性不好，结果就是系统直接冻结。

所以解决思路不是换桌面环境，也不是一直重装系统，而是限制 CPU 不要进入太深的 C-State。

安装时的临时解决方式

如果还没有装好系统，可以在安装 U 盘的 GRUB 菜单里临时加启动参数。

在 Ubuntu、Debian、Linux Mint、Xubuntu、Lubuntu 等安装菜单中：

选中 Try or Install、Install 或类似启动项；
按 e 编辑启动项；
找到包含 quiet splash 的那一行；
在后面加上这些参数：

1

intel_idle.max_cstate=1 processor.max_cstate=1 idle=nomwait pcie_aspm=off

如果原来是：

1

quiet splash

可以改成类似：

1

quiet splash intel_idle.max_cstate=1 processor.max_cstate=1 idle=nomwait pcie_aspm=off

然后按 F10 或 Ctrl + X 启动。

其中最关键的是前面三个：

1

intel_idle.max_cstate=1 processor.max_cstate=1 idle=nomwait

pcie_aspm=off 是额外关闭 PCIe 省电，有些小主机的网卡、存储控制器或者桥接设备也可能因为省电策略导致不稳定，所以也可以一起加上。

安装完成后的永久修复

需要注意的是，安装阶段修改的是 U 盘启动菜单里的 GRUB 参数，这个修改只对安装环境临时生效。系统安装完成后，硬盘里的新系统仍然可能因为缺少这些启动参数而无法正常进入。

因此，第一次启动已安装好的系统时，还需要在硬盘系统的 GRUB 菜单中再次临时加入相同的启动参数，方法与前面修改 U 盘 GRUB 菜单一致。确认可以成功进入系统后，再编辑系统自己的 GRUB 默认配置，让修复永久生效：

1

sudo nano /etc/default/grub

找到这两行：

1
2


GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"
GRUB_CMDLINE_LINUX=""

改成：

1
2


GRUB_CMDLINE_LINUX_DEFAULT="quiet splash intel_idle.max_cstate=1 processor.max_cstate=1 idle=nomwait"
GRUB_CMDLINE_LINUX="modprobe.blacklist=pcspkr pcie_aspm=off"

然后更新 GRUB：

1
2


sudo update-grub
sudo reboot

重启后，这些参数才会真正生效。

参数说明

参数	作用
`intel_idle.max_cstate=1`	限制 Intel idle 驱动，只允许进入较浅的 C-State，避免 Bay Trail 深度休眠卡死。
`processor.max_cstate=1`	限制通用 processor idle 驱动的最大 C-State，作为补充限制。
`idle=nomwait`	禁用基于 `MWAIT` 的 idle 路径，Bay Trail 机器上常用于避免冻结。
`pcie_aspm=off`	关闭 PCIe Active State Power Management，减少部分网卡、存储、桥接设备的省电兼容问题。
`modprobe.blacklist=pcspkr`	禁用主板蜂鸣器模块，和卡死关系不大，主要是避免蜂鸣器干扰。

这套参数的核心是：

1

intel_idle.max_cstate=1 processor.max_cstate=1 idle=nomwait

如果只是普通 Bay Trail 冻结问题，通常这三个就够了。

如何确认当前参数已经生效

进系统后，查看当前 Linux 内核实际启动参数：

1

cat /proc/cmdline

也可以只筛选相关项：

1

cat /proc/cmdline | tr ' ' '\n' | grep -E 'cstate|intel_idle|processor|idle|aspm|pcspkr|quiet|splash'

如果看到类似下面的内容，说明参数已经生效：

1
2
3
4
5
6
7


quiet
splash
intel_idle.max_cstate=1
processor.max_cstate=1
idle=nomwait
modprobe.blacklist=pcspkr
pcie_aspm=off

注意，/etc/default/grub 只是配置文件，真正当前运行的内核参数要看：

1

cat /proc/cmdline

如果 /etc/default/grub 里已经改了，但 /proc/cmdline 里没有看到对应参数，通常说明忘了执行：

1
2


sudo update-grub
sudo reboot

如何查看自己改过的 GRUB

查看 GRUB 默认配置：

1

grep -n 'GRUB_CMDLINE_LINUX' /etc/default/grub

我的配置类似这样：

1
2


GRUB_CMDLINE_LINUX_DEFAULT="quiet splash intel_idle.max_cstate=1 processor.max_cstate=1 idle=nomwait"
GRUB_CMDLINE_LINUX="modprobe.blacklist=pcspkr pcie_aspm=off"

也可以查看生成后的 GRUB 菜单配置里有没有写进去：

1

grep -n "intel_idle.max_cstate\|processor.max_cstate\|idle=nomwait\|pcie_aspm" /boot/grub/grub.cfg

不过 /boot/grub/grub.cfg 不建议手动编辑，它是由 update-grub 自动生成的。

如果还是不稳定

如果加了这些参数以后仍然会卡死，可以继续检查下面几项：

进入 BIOS / UEFI，关闭 C-State、C1E、Package C State、Deep Sleep 一类选项；
如果是黑屏或显示器无信号，而不是整机冻结，可以临时测试 nomodeset；
换一个较新的轻量发行版，例如 Debian 12、Ubuntu 24.04、Linux Mint XFCE、Xubuntu、Lubuntu；
检查内存和硬盘健康状态，避免把硬件故障误认为 Bay Trail 问题。

nomodeset 主要解决显卡初始化问题，不是 Bay Trail C-State 冻结的核心修复。如果系统只是黑屏，可以试；如果是整机假死，优先还是处理 C-State。

总结

N2830 小主机安装 Linux 卡死，优先按 Bay Trail C-State 问题处理。

推荐最终 GRUB 配置：

1
2


GRUB_CMDLINE_LINUX_DEFAULT="quiet splash intel_idle.max_cstate=1 processor.max_cstate=1 idle=nomwait"
GRUB_CMDLINE_LINUX="modprobe.blacklist=pcspkr pcie_aspm=off"

修改后执行：

1
2


sudo update-grub
sudo reboot

重启后用下面命令确认：

1

cat /proc/cmdline

只要 /proc/cmdline 里能看到 intel_idle.max_cstate=1、processor.max_cstate=1、idle=nomwait，基本就说明核心修复已经生效了。

参考

Ask Ubuntu: System freezes completely with Intel Bay Trail

使用 Quick, Draw! 数据集训练 YOLO11 模型

Sat, 23 May 2026 00:00:00 +0000

这篇文章记录我如何使用 Google Quick, Draw! 数据集训练一个 YOLO11 模型。目标是先用公开的手绘数据训练一个基础模型，让模型具备识别手绘线条、简笔画、图形轮廓的能力，后续再用真实纸面拍摄数据进行微调。

一、目标

我想做的是：识别人在纸上绘制的不同线条或图形。

例如：

直线
曲线
折线
波浪线
箭头
圆形
方形
三角形
简笔画图案
不规则手绘线条

一开始我考虑直接找现成的数据集，但发现完全匹配“纸上手绘线条识别”的数据集并不多。Quick, Draw! 虽然不是专门的线条检测数据集，但它有大量人类随手画出来的矢量笔画，非常适合用来训练一个手绘风格的基础模型。

这次的方案是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Quick, Draw! NDJSON 数据
 ↓
解析矢量笔画
 ↓
渲染成图片
 ↓
根据笔画坐标自动生成 YOLO 检测框
 ↓
训练 YOLO11 检测模型
 ↓
后续用真实纸面照片微调

二、重要说明

Quick, Draw! 原始数据并不是 YOLO 检测数据集。

它的数据形式更接近这样：

1

类别名 + 笔画坐标 + 是否被识别

例如每个样本里会有一组 drawing，里面保存了手绘笔画的 x/y 坐标。

所以这次我们需要自己做一步转换：

1
2


笔画坐标 → 图片
笔画坐标范围 → 目标检测框

也就是说，这次生成的 YOLO 标签框不是人工标注的，而是通过笔画的最小外接矩形自动生成的。

这个方法适合先训练 baseline，但最终如果要用于真实纸面照片，还是需要收集真实图片并人工标注一部分数据来微调。

三、项目目录结构

我把整个项目整理成下面的结构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


quickdraw-yolo11/
 scripts/
 01_download_quickdraw_all.py
 02_verify_and_fix_quickdraw.py
 03_convert_quickdraw_to_yolo.py
 04_check_yolo_dataset.py
 05_preview_yolo_labels.py
 06_train_yolo11.py
 07_predict.py

 data/
 categories.txt
 quickdraw_ndjson/
 airplane.ndjson
 alarm clock.ndjson
 ...
 quickdraw_failed.txt

 datasets/
 quickdraw_all/
 images/
 train/
 val/
 labels/
 train/
 val/
 quickdraw_all.yaml
 preview/

 test_images/
 your_test.jpg

 runs/

新建项目：

1
2


mkdir quickdraw-yolo11
cd quickdraw-yolo11

新建目录：

1
2
3
4


mkdir scripts
mkdir data
mkdir datasets
mkdir test_images

四、安装环境

建议使用 Python 3.10 或 Python 3.11。

创建虚拟环境：

1

python -m venv .venv

Windows 激活：

1

.venv\Scripts\activate

Linux / macOS 激活：

1

source .venv/bin/activate

安装依赖：

1

pip install ultralytics pillow tqdm pyyaml requests opencv-python

检查 YOLO 环境：

1

yolo checks

如果有 NVIDIA GPU，可以检查 PyTorch 是否识别到 GPU：

1

python -c "import torch; print(torch.cuda.is_available())"

如果输出：

1

True

说明可以使用 GPU 训练。

五、下载 Quick, Draw! 全部类别

第一个脚本用于下载 Quick, Draw! 的全部类别。

保存为：

1

scripts/01_download_quickdraw_all.py

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117


import os
import time
import urllib.parse
from pathlib import Path

import requests
from tqdm import tqdm


CATEGORY_URL = "https://raw.githubusercontent.com/googlecreativelab/quickdraw-dataset/master/categories.txt"
BASE_URL = "https://storage.googleapis.com/quickdraw_dataset/full/simplified"

DATA_DIR = Path("data")
OUT_DIR = DATA_DIR / "quickdraw_ndjson"
CATEGORY_FILE = DATA_DIR / "categories.txt"

MAX_RETRIES = 3
TIMEOUT = 60


def fetch_categories():
 DATA_DIR.mkdir(parents=True, exist_ok=True)

 print("Fetching categories.txt...")
 r = requests.get(CATEGORY_URL, timeout=TIMEOUT)
 r.raise_for_status()

 CATEGORY_FILE.write_text(r.text, encoding="utf-8")

 categories = [line.strip() for line in r.text.splitlines() if line.strip()]
 return categories


def download_file(category_name: str):
 filename = f"{category_name}.ndjson"
 encoded_filename = urllib.parse.quote(filename)
 url = f"{BASE_URL}/{encoded_filename}"

 out_path = OUT_DIR / filename
 tmp_path = OUT_DIR / f"{filename}.part"

 if out_path.exists() and out_path.stat().st_size > 0:
 print(f"Skip existing: {out_path}")
 return True

 for attempt in range(1, MAX_RETRIES + 1):
 print(f"\nDownloading [{attempt}/{MAX_RETRIES}]: {category_name}")
 print(url)

 try:
 if tmp_path.exists():
 tmp_path.unlink()

 with requests.get(url, stream=True, timeout=TIMEOUT) as r:
 if r.status_code != 200:
 print(f"HTTP {r.status_code}: {category_name}")
 time.sleep(2)
 continue

 total = int(r.headers.get("content-length", 0))

 with tmp_path.open("wb") as f, tqdm(
 total=total,
 unit="B",
 unit_scale=True,
 desc=filename,
 ) as pbar:
 for chunk in r.iter_content(chunk_size=1024 * 1024):
 if chunk:
 f.write(chunk)
 pbar.update(len(chunk))

 os.replace(tmp_path, out_path)
 return True

 except Exception as e:
 print(f"Error downloading {category_name}: {e}")
 if tmp_path.exists():
 try:
 tmp_path.unlink()
 except Exception:
 pass
 time.sleep(2)

 return False


def main():
 OUT_DIR.mkdir(parents=True, exist_ok=True)

 categories = fetch_categories()
 print(f"Total categories: {len(categories)}")

 failed = []

 for category_name in categories:
 ok = download_file(category_name)
 if not ok:
 failed.append(category_name)

 print("\nDownload summary:")
 print(f"Success: {len(categories) - len(failed)}")
 print(f"Failed: {len(failed)}")

 if failed:
 failed_file = DATA_DIR / "quickdraw_failed.txt"
 failed_file.write_text("\n".join(failed), encoding="utf-8")

 print(f"\nFailed list saved to: {failed_file}")
 for name in failed:
 print(f"- {name}")
 else:
 print("\nAll categories downloaded.")


if __name__ == "__main__":
 main()

运行：

1

python scripts/01_download_quickdraw_all.py

下载完成后，数据会放在：

1

data/quickdraw_ndjson/

六、检查 Quick, Draw! 原始下载完整度并补下载

下载 Quick, Draw! 全部类别时，可能会因为网络波动导致某些类别没有下载成功，或者留下 .part 临时文件。

因此在转换 YOLO 数据集之前，我需要先检查原始 NDJSON 文件是否完整。

这一步检查的是：

1

data/quickdraw_ndjson/*.ndjson

它和后面的 YOLO 数据集检查不一样：

1
2


原始下载完整度检查：检查 NDJSON 是否缺失或异常
YOLO 数据集完整性检查：检查图片、label、bbox、类别 ID 是否正常

保存脚本为：

1

scripts/02_verify_and_fix_quickdraw.py

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228


import os
import time
import urllib.parse
from pathlib import Path

import requests
from tqdm import tqdm


CATEGORY_URL = "https://raw.githubusercontent.com/googlecreativelab/quickdraw-dataset/master/categories.txt"
BASE_URL = "https://storage.googleapis.com/quickdraw_dataset/full/simplified"

OUT_DIR = Path("data/quickdraw_ndjson")
CATEGORY_FILE = Path("data/categories.txt")

MIN_VALID_SIZE_BYTES = 1024 * 1024 # 小于 1MB 基本可以认为异常
MAX_RETRIES = 3
TIMEOUT = 60


def fetch_categories():
 """
 优先使用本地 data/categories.txt。
 如果没有，则从官方仓库下载。
 """
 CATEGORY_FILE.parent.mkdir(parents=True, exist_ok=True)

 if CATEGORY_FILE.exists() and CATEGORY_FILE.stat().st_size > 0:
 text = CATEGORY_FILE.read_text(encoding="utf-8")
 else:
 print("Fetching categories.txt from official repo...")
 r = requests.get(CATEGORY_URL, timeout=TIMEOUT)
 r.raise_for_status()
 text = r.text
 CATEGORY_FILE.write_text(text, encoding="utf-8")

 categories = [line.strip() for line in text.splitlines() if line.strip()]
 return categories


def is_valid_ndjson(path: Path):
 """
 基础核验：
 - 文件存在
 - 文件大小不是 0
 - 文件不是过小
 - 第一行看起来像 JSON 行
 - 最后一行不是明显截断的空文件
 """
 if not path.exists():
 return False, "missing"

 size = path.stat().st_size
 if size == 0:
 return False, "empty"

 if size < MIN_VALID_SIZE_BYTES:
 return False, f"too small: {size} bytes"

 try:
 with path.open("rb") as f:
 first_line = f.readline().strip()

 if not first_line.startswith(b"{") or not first_line.endswith(b"}"):
 return False, "first line does not look like ndjson"

 except Exception as e:
 return False, f"read error: {e}"

 return True, "ok"


def cleanup_part_files():
 """
 清理上次中断残留的 .part 文件。
 """
 if not OUT_DIR.exists():
 return

 part_files = list(OUT_DIR.glob("*.part"))
 if not part_files:
 return

 print(f"Found {len(part_files)} .part files, removing...")
 for path in part_files:
 try:
 path.unlink()
 print(f"Removed: {path}")
 except Exception as e:
 print(f"Failed to remove {path}: {e}")


def download_file(category_name: str):
 """
 下载单个类别。
 """
 filename = f"{category_name}.ndjson"
 encoded_filename = urllib.parse.quote(filename)
 url = f"{BASE_URL}/{encoded_filename}"

 out_path = OUT_DIR / filename
 tmp_path = OUT_DIR / f"{filename}.part"

 for attempt in range(1, MAX_RETRIES + 1):
 print(f"\nDownloading [{attempt}/{MAX_RETRIES}]: {category_name}")
 print(url)

 try:
 if tmp_path.exists():
 tmp_path.unlink()

 with requests.get(url, stream=True, timeout=TIMEOUT) as r:
 if r.status_code != 200:
 print(f"HTTP {r.status_code}: {category_name}")
 time.sleep(2)
 continue

 total = int(r.headers.get("content-length", 0))

 with tmp_path.open("wb") as f, tqdm(
 total=total,
 unit="B",
 unit_scale=True,
 desc=filename,
 ) as pbar:
 for chunk in r.iter_content(chunk_size=1024 * 1024):
 if chunk:
 f.write(chunk)
 pbar.update(len(chunk))

 ok, reason = is_valid_ndjson(tmp_path)
 if not ok:
 print(f"Downloaded file invalid: {category_name}, reason: {reason}")
 if tmp_path.exists():
 tmp_path.unlink()
 time.sleep(2)
 continue

 os.replace(tmp_path, out_path)
 print(f"Fixed: {out_path}")
 return True

 except Exception as e:
 print(f"Error downloading {category_name}: {e}")
 if tmp_path.exists():
 try:
 tmp_path.unlink()
 except Exception:
 pass
 time.sleep(2)

 return False


def main():
 OUT_DIR.mkdir(parents=True, exist_ok=True)

 categories = fetch_categories()
 print(f"Expected categories: {len(categories)}")

 cleanup_part_files()

 invalid = []
 valid_count = 0

 print("\nChecking local files...")

 for category_name in categories:
 path = OUT_DIR / f"{category_name}.ndjson"
 ok, reason = is_valid_ndjson(path)

 if ok:
 valid_count += 1
 else:
 invalid.append((category_name, reason))

 print("\nCheck summary:")
 print(f"Valid files: {valid_count}")
 print(f"Invalid/miss: {len(invalid)}")

 if invalid:
 print("\nNeed to fix:")
 for name, reason in invalid:
 print(f"- {name}: {reason}")

 if not invalid:
 print("\nAll files look good.")
 return

 failed = []

 print("\nStart fixing missing/invalid files...")

 for category_name, reason in invalid:
 path = OUT_DIR / f"{category_name}.ndjson"

 # 避免保留坏文件影响重下
 if path.exists():
 try:
 path.unlink()
 except Exception as e:
 print(f"Could not remove invalid file {path}: {e}")
 failed.append(category_name)
 continue

 ok = download_file(category_name)
 if not ok:
 failed.append(category_name)

 print("\nFinal summary:")
 print(f"Fixed: {len(invalid) - len(failed)}")
 print(f"Failed: {len(failed)}")

 if failed:
 failed_file = Path("data/quickdraw_failed.txt")
 failed_file.write_text("\n".join(failed), encoding="utf-8")

 print("\nStill failed:")
 for name in failed:
 print(f"- {name}")

 print(f"\nFailed list saved to: {failed_file}")
 else:
 print("\nAll missing/invalid files have been fixed.")


if __name__ == "__main__":
 main()

运行：

1

python scripts/02_verify_and_fix_quickdraw.py

如果全部正常，会看到：

1

All files look good.

如果有缺失或异常文件，脚本会列出类似：

1
2
3


Need to fix:
- cat: missing
- alarm clock: too small: 12345 bytes

然后它会自动重新下载这些类别。

如果仍然失败，会写入：

1

data/quickdraw_failed.txt

之后可以再次运行同一个脚本继续补下载。

这个脚本主要检查以下问题：

检查项	说明
missing	类别文件不存在
empty	文件大小为 0
too small	文件小于设定阈值，默认小于 1MB
first line does not look like ndjson	文件首行不像 JSON 行
read error	文件无法读取
.part 文件	上次下载中断留下的临时文件

需要注意的是，这个检查是基础完整度检查。它不会逐行解析整个 NDJSON 文件，否则全部类别检查会比较慢。一般情况下，配合文件大小、首行格式和 .part 清理，已经足够发现大多数下载失败问题。

七、转换成 YOLO 数据集

第三个脚本负责把 Quick, Draw! 的 NDJSON 数据转换成 YOLO 检测数据集。

保存为：

1

scripts/03_convert_quickdraw_to_yolo.py

主要逻辑：

1
2
3
4
5
6
7


读取 categories.txt
读取每个类别的 ndjson
解析 drawing 笔画坐标
渲染为 640x640 图片
计算笔画最小外接框
保存 YOLO 标签
生成 quickdraw_all.yaml

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292


import json
import random
from pathlib import Path

import yaml
from PIL import Image, ImageDraw, ImageFilter, ImageEnhance
from tqdm import tqdm


DATA_DIR = Path("data")
CATEGORY_FILE = DATA_DIR / "categories.txt"
SRC_DIR = DATA_DIR / "quickdraw_ndjson"

OUT_DIR = Path("datasets") / "quickdraw_all"

IMG_SIZE = 640

# 全部类别时建议先从 200 或 500 开始测试流程。
# 200 张/类：约 6.9 万张图
# 500 张/类：约 17 万张图
# 1000 张/类：约 34.5 万张图
# 3000 张/类：约 103.5 万张图
SAMPLES_PER_CLASS = 1000

VAL_RATIO = 0.15
SEED = 42

ONLY_RECOGNIZED = True
ENABLE_AUGMENT = True

random.seed(SEED)


def load_classes():
 if not CATEGORY_FILE.exists():
 raise FileNotFoundError(
 f"Missing {CATEGORY_FILE}. Please run download script first."
 )

 text = CATEGORY_FILE.read_text(encoding="utf-8")
 classes = [line.strip() for line in text.splitlines() if line.strip()]

 if not classes:
 raise RuntimeError("categories.txt is empty.")

 return classes


def ensure_dirs():
 for split in ["train", "val"]:
 (OUT_DIR / "images" / split).mkdir(parents=True, exist_ok=True)
 (OUT_DIR / "labels" / split).mkdir(parents=True, exist_ok=True)


def get_bbox_from_drawing(drawing):
 xs = []
 ys = []

 for stroke in drawing:
 if len(stroke) < 2:
 continue

 stroke_xs = stroke[0]
 stroke_ys = stroke[1]

 xs.extend(stroke_xs)
 ys.extend(stroke_ys)

 if not xs or not ys:
 return None

 x1 = max(0, min(xs))
 y1 = max(0, min(ys))
 x2 = min(255, max(xs))
 y2 = min(255, max(ys))

 if x2 <= x1 or y2 <= y1:
 return None

 pad = 8
 x1 = max(0, x1 - pad)
 y1 = max(0, y1 - pad)
 x2 = min(255, x2 + pad)
 y2 = min(255, y2 + pad)

 if x2 <= x1 or y2 <= y1:
 return None

 return x1, y1, x2, y2


def render_drawing(drawing, img_size=640):
 if ENABLE_AUGMENT:
 bg = random.choice([
 (255, 255, 255),
 (250, 250, 250),
 (245, 245, 240),
 (248, 246, 238),
 ])
 else:
 bg = (255, 255, 255)

 img = Image.new("RGB", (img_size, img_size), bg)
 draw = ImageDraw.Draw(img)

 scale = img_size / 256.0

 if ENABLE_AUGMENT:
 width = random.choice([3, 4, 5, 6, 7, 8])
 else:
 width = 5

 ink = random.choice([
 (0, 0, 0),
 (20, 20, 20),
 (40, 40, 40),
 ]) if ENABLE_AUGMENT else (0, 0, 0)

 for stroke in drawing:
 if len(stroke) < 2:
 continue

 xs = stroke[0]
 ys = stroke[1]

 points = [
 (int(x * scale), int(y * scale))
 for x, y in zip(xs, ys)
 ]

 if len(points) >= 2:
 draw.line(points, fill=ink, width=width, joint="curve")
 elif len(points) == 1:
 x, y = points[0]
 r = width
 draw.ellipse((x - r, y - r, x + r, y + r), fill=ink)

 if ENABLE_AUGMENT:
 # 这里使用不会改变几何位置的增强，因此 bbox 不需要重新计算。
 if random.random() < 0.25:
 img = img.filter(ImageFilter.GaussianBlur(radius=random.uniform(0.2, 0.8)))

 if random.random() < 0.35:
 enhancer = ImageEnhance.Brightness(img)
 img = enhancer.enhance(random.uniform(0.85, 1.15))

 if random.random() < 0.35:
 enhancer = ImageEnhance.Contrast(img)
 img = enhancer.enhance(random.uniform(0.85, 1.25))

 return img


def bbox_to_yolo(bbox, img_size=640):
 x1, y1, x2, y2 = bbox

 scale = img_size / 256.0

 x1 *= scale
 y1 *= scale
 x2 *= scale
 y2 *= scale

 xc = ((x1 + x2) / 2) / img_size
 yc = ((y1 + y2) / 2) / img_size
 w = (x2 - x1) / img_size
 h = (y2 - y1) / img_size

 xc = min(max(xc, 0.0), 1.0)
 yc = min(max(yc, 0.0), 1.0)
 w = min(max(w, 0.0), 1.0)
 h = min(max(h, 0.0), 1.0)

 if w <= 0 or h <= 0:
 return None

 return xc, yc, w, h


def read_samples(src_path: Path, max_samples: int):
 samples = []

 with src_path.open("r", encoding="utf-8") as f:
 for line in f:
 if len(samples) >= max_samples:
 break

 try:
 item = json.loads(line)
 except Exception:
 continue

 if ONLY_RECOGNIZED and not item.get("recognized", False):
 continue

 drawing = item.get("drawing")
 if not drawing:
 continue

 samples.append(item)

 return samples


def convert_one_class(class_id: int, class_name: str):
 src_path = SRC_DIR / f"{class_name}.ndjson"

 if not src_path.exists():
 print(f"Missing file, skip: {src_path}")
 return 0

 samples = read_samples(src_path, SAMPLES_PER_CLASS)

 if not samples:
 print(f"No usable samples, skip: {class_name}")
 return 0

 converted = 0

 for idx, item in enumerate(tqdm(samples, desc=class_name)):
 drawing = item["drawing"]

 bbox = get_bbox_from_drawing(drawing)
 if bbox is None:
 continue

 yolo_box = bbox_to_yolo(bbox, IMG_SIZE)
 if yolo_box is None:
 continue

 split = "val" if random.random() < VAL_RATIO else "train"

 safe_name = class_name.replace(" ", "_").replace("/", "_")
 image_name = f"{safe_name}_{idx:07d}.jpg"
 label_name = f"{safe_name}_{idx:07d}.txt"

 image_path = OUT_DIR / "images" / split / image_name
 label_path = OUT_DIR / "labels" / split / label_name

 img = render_drawing(drawing, IMG_SIZE)
 img.save(image_path, quality=95)

 xc, yc, w, h = yolo_box

 with label_path.open("w", encoding="utf-8") as f:
 f.write(f"{class_id} {xc:.6f} {yc:.6f} {w:.6f} {h:.6f}\n")

 converted += 1

 return converted


def write_yaml(classes):
 yaml_path = OUT_DIR / "quickdraw_all.yaml"

 data = {
 "path": str(OUT_DIR.resolve()),
 "train": "images/train",
 "val": "images/val",
 "names": {i: name for i, name in enumerate(classes)},
 }

 with yaml_path.open("w", encoding="utf-8") as f:
 yaml.safe_dump(data, f, sort_keys=False, allow_unicode=True)

 print(f"YAML saved to: {yaml_path}")


def main():
 classes = load_classes()
 print(f"Classes: {len(classes)}")
 print(f"Samples per class: {SAMPLES_PER_CLASS}")
 print(f"Output: {OUT_DIR}")

 ensure_dirs()

 total = 0

 for class_id, class_name in enumerate(classes):
 count = convert_one_class(class_id, class_name)
 total += count

 write_yaml(classes)

 print("\nConvert summary:")
 print(f"Total images: {total}")
 print(f"Dataset dir: {OUT_DIR}")
 print(f"YAML: {OUT_DIR / 'quickdraw_all.yaml'}")


if __name__ == "__main__":
 main()

运行：

1

python scripts/03_convert_quickdraw_to_yolo.py

生成的数据集结构：

1
2
3
4
5
6
7
8


datasets/quickdraw_all/
 images/
 train/
 val/
 labels/
 train/
 val/
 quickdraw_all.yaml

八、检查转换后的 YOLO 数据集完整性

在正式训练 YOLO11 之前，除了要检查 Quick, Draw! 原始 NDJSON 是否下载完整，还需要检查转换后的 YOLO 数据集是否正常。

这一步非常重要，因为 YOLO 训练时如果 label 有问题，可能会出现：

1
2
3
4
5
6
7
8
9


图片和标签数量不一致
label 文件找不到对应图片
图片文件打不开
类别 ID 超出范围
坐标不是 0~1
bbox 宽高为 0
bbox 极小
bbox 超出图像边界
类别分布严重不均衡

所以我额外准备了一个完整性检查脚本，用来扫描转换后的数据集。

保存为：

1

scripts/04_check_yolo_dataset.py

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396


from pathlib import Path
from collections import Counter, defaultdict
import math
import yaml
from PIL import Image


DATASET_DIR = Path("datasets") / "quickdraw_all"
YAML_PATH = DATASET_DIR / "quickdraw_all.yaml"

IMAGE_EXTS = [".jpg", ".jpeg", ".png", ".bmp", ".webp"]

# 极端框阈值，可按需要调整
MIN_WH = 0.002 # 小于 0.002 约等于 640 图上的 1.28 像素
WARN_WH = 0.01 # 小于 0.01 约等于 640 图上的 6.4 像素
WARN_RATIO = 20.0 # 宽高比超过 20 认为是极细长框
WARN_AREA_SMALL = 0.0001
WARN_AREA_LARGE = 0.95


def load_yaml():
 if not YAML_PATH.exists():
 print(f"[ERROR] 找不到 YAML: {YAML_PATH}")
 return None

 with YAML_PATH.open("r", encoding="utf-8") as f:
 data = yaml.safe_load(f)

 names = data.get("names", {})
 if isinstance(names, list):
 names = {i: name for i, name in enumerate(names)}

 nc = data.get("nc", len(names))

 print(f"[INFO] YAML: {YAML_PATH}")
 print(f"[INFO] nc: {nc}")
 print(f"[INFO] names: {len(names)} classes")

 return {
 "data": data,
 "names": names,
 "nc": nc,
 }


def find_image_for_label(label_path: Path, split: str):
 image_stem = label_path.stem
 image_dir = DATASET_DIR / "images" / split

 for ext in IMAGE_EXTS:
 p = image_dir / f"{image_stem}{ext}"
 if p.exists():
 return p

 return None


def check_one_label_file(label_path: Path, split: str, nc: int):
 errors = []
 warnings = []
 stats = []

 image_path = find_image_for_label(label_path, split)
 if image_path is None:
 errors.append(("missing_image", "找不到对应图片"))
 img_w = img_h = None
 else:
 try:
 with Image.open(image_path) as img:
 img_w, img_h = img.size
 except Exception as e:
 errors.append(("bad_image", f"图片无法打开: {e}"))
 img_w = img_h = None

 try:
 text = label_path.read_text(encoding="utf-8").strip()
 except Exception as e:
 errors.append(("read_label_failed", f"label 无法读取: {e}"))
 return errors, warnings, stats

 if not text:
 warnings.append(("empty_label", "label 文件为空"))
 return errors, warnings, stats

 lines = text.splitlines()

 for line_no, line in enumerate(lines, 1):
 raw_line = line
 parts = line.strip().split()

 if len(parts) != 5:
 errors.append(("bad_columns", f"第 {line_no} 行列数不是 5: {raw_line}"))
 continue

 try:
 cls_raw, x_raw, y_raw, w_raw, h_raw = parts
 cls_float = float(cls_raw)
 x = float(x_raw)
 y = float(y_raw)
 w = float(w_raw)
 h = float(h_raw)
 except Exception:
 errors.append(("not_number", f"第 {line_no} 行存在非数字: {raw_line}"))
 continue

 vals = [x, y, w, h]

 if not math.isfinite(cls_float):
 errors.append(("class_nan_inf", f"第 {line_no} 行 class 是 NaN/Inf: {raw_line}"))
 continue

 if int(cls_float) != cls_float:
 errors.append(("class_not_int", f"第 {line_no} 行 class 不是整数: {raw_line}"))
 continue

 cls = int(cls_float)

 if cls < 0 or cls >= nc:
 errors.append(("class_out_of_range", f"第 {line_no} 行 class 超出范围 0~{nc - 1}: {raw_line}"))
 continue

 if not all(math.isfinite(v) for v in vals):
 errors.append(("coord_nan_inf", f"第 {line_no} 行坐标存在 NaN/Inf: {raw_line}"))
 continue

 if not all(0.0 <= v <= 1.0 for v in vals):
 errors.append(("coord_out_of_0_1", f"第 {line_no} 行坐标不在 0~1: {raw_line}"))
 continue

 if w <= 0 or h <= 0:
 errors.append(("zero_or_negative_wh", f"第 {line_no} 行 w/h <= 0: {raw_line}"))
 continue

 x1 = x - w / 2
 y1 = y - h / 2
 x2 = x + w / 2
 y2 = y + h / 2

 if x1 < 0 or y1 < 0 or x2 > 1 or y2 > 1:
 warnings.append(("box_cross_border", f"第 {line_no} 行 bbox 超出图像边界: {raw_line}"))

 area = w * h
 ratio = max(w / h, h / w)

 if w < MIN_WH or h < MIN_WH:
 errors.append(("too_tiny_wh", f"第 {line_no} 行 w/h 极小: w={w:.8f}, h={h:.8f}, {raw_line}"))

 if w < WARN_WH or h < WARN_WH:
 warnings.append(("small_wh", f"第 {line_no} 行 w/h 较小: w={w:.8f}, h={h:.8f}, {raw_line}"))

 if ratio > WARN_RATIO:
 warnings.append(("extreme_ratio", f"第 {line_no} 行宽高比极端: ratio={ratio:.2f}, {raw_line}"))

 if area < WARN_AREA_SMALL:
 warnings.append(("small_area", f"第 {line_no} 行面积过小: area={area:.8f}, {raw_line}"))

 if area > WARN_AREA_LARGE:
 warnings.append(("large_area", f"第 {line_no} 行面积过大: area={area:.8f}, {raw_line}"))

 if img_w is not None and img_h is not None:
 pixel_w = w * img_w
 pixel_h = h * img_h
 else:
 pixel_w = None
 pixel_h = None

 stats.append({
 "cls": cls,
 "x": x,
 "y": y,
 "w": w,
 "h": h,
 "area": area,
 "ratio": ratio,
 "pixel_w": pixel_w,
 "pixel_h": pixel_h,
 "label_path": label_path,
 "image_path": image_path,
 "line_no": line_no,
 "line": raw_line,
 })

 return errors, warnings, stats


def scan_split(split: str, nc: int):
 label_dir = DATASET_DIR / "labels" / split
 image_dir = DATASET_DIR / "images" / split

 print(f"\n========== Checking split: {split} ==========")
 print(f"[INFO] labels: {label_dir}")
 print(f"[INFO] images: {image_dir}")

 if not label_dir.exists():
 print(f"[ERROR] label 目录不存在: {label_dir}")
 return None

 if not image_dir.exists():
 print(f"[ERROR] image 目录不存在: {image_dir}")
 return None

 label_files = sorted(label_dir.rglob("*.txt"))
 image_files = []
 for ext in IMAGE_EXTS:
 image_files.extend(image_dir.rglob(f"*{ext}"))

 print(f"[INFO] label files: {len(label_files)}")
 print(f"[INFO] image files: {len(image_files)}")

 error_counter = Counter()
 warning_counter = Counter()
 class_counter = Counter()

 bad_examples = defaultdict(list)
 warn_examples = defaultdict(list)

 all_stats = []

 for label_path in label_files:
 errors, warnings, stats = check_one_label_file(label_path, split, nc)

 for code, msg in errors:
 error_counter[code] += 1
 if len(bad_examples[code]) < 20:
 bad_examples[code].append((label_path, msg))

 for code, msg in warnings:
 warning_counter[code] += 1
 if len(warn_examples[code]) < 20:
 warn_examples[code].append((label_path, msg))

 for item in stats:
 class_counter[item["cls"]] += 1
 all_stats.append(item)

 # 检查是否存在图片没有 label
 label_stems = {p.stem for p in label_files}
 image_stems = {p.stem for p in image_files}

 images_without_labels = sorted(image_stems - label_stems)
 labels_without_images = sorted(label_stems - image_stems)

 if images_without_labels:
 warning_counter["image_without_label"] += len(images_without_labels)
 warn_examples["image_without_label"] = images_without_labels[:20]

 if labels_without_images:
 error_counter["label_without_image"] += len(labels_without_images)
 bad_examples["label_without_image"] = labels_without_images[:20]

 print("\n[SUMMARY]")
 print(f"valid boxes parsed: {len(all_stats)}")
 print(f"errors: {sum(error_counter.values())}")
 print(f"warnings: {sum(warning_counter.values())}")

 print("\n[ERROR COUNTS]")
 if error_counter:
 for k, v in error_counter.most_common():
 print(f"{k}: {v}")
 else:
 print("No hard errors found.")

 print("\n[WARNING COUNTS]")
 if warning_counter:
 for k, v in warning_counter.most_common():
 print(f"{k}: {v}")
 else:
 print("No warnings found.")

 if all_stats:
 widths = [x["w"] for x in all_stats]
 heights = [x["h"] for x in all_stats]
 areas = [x["area"] for x in all_stats]
 ratios = [x["ratio"] for x in all_stats]

 print("\n[BOX DISTRIBUTION]")
 print(f"w min/avg/max: {min(widths):.8f} / {sum(widths) / len(widths):.8f} / {max(widths):.8f}")
 print(f"h min/avg/max: {min(heights):.8f} / {sum(heights) / len(heights):.8f} / {max(heights):.8f}")
 print(f"area min/avg/max: {min(areas):.8f} / {sum(areas) / len(areas):.8f} / {max(areas):.8f}")
 print(f"ratio min/avg/max: {min(ratios):.2f} / {sum(ratios) / len(ratios):.2f} / {max(ratios):.2f}")

 print("\n[SMALLEST BOXES]")
 for item in sorted(all_stats, key=lambda x: x["area"])[:20]:
 print(
 f"area={item['area']:.8f}, "
 f"w={item['w']:.8f}, h={item['h']:.8f}, "
 f"ratio={item['ratio']:.2f}, "
 f"cls={item['cls']}, "
 f"file={item['label_path']}"
 )

 print("\n[MOST EXTREME RATIOS]")
 for item in sorted(all_stats, key=lambda x: x["ratio"], reverse=True)[:20]:
 print(
 f"ratio={item['ratio']:.2f}, "
 f"w={item['w']:.8f}, h={item['h']:.8f}, "
 f"area={item['area']:.8f}, "
 f"cls={item['cls']}, "
 f"file={item['label_path']}"
 )

 print("\n[CLASS DISTRIBUTION]")
 print(f"classes with labels: {len(class_counter)}")
 if class_counter:
 counts = list(class_counter.values())
 print(f"per-class min/avg/max: {min(counts)} / {sum(counts) / len(counts):.2f} / {max(counts)}")

 print("\nLeast common classes:")
 for cls, n in class_counter.most_common()[-20:]:
 print(f"class {cls}: {n}")

 print("\nMost common classes:")
 for cls, n in class_counter.most_common(20):
 print(f"class {cls}: {n}")

 print("\n[ERROR EXAMPLES]")
 if bad_examples:
 for code, examples in bad_examples.items():
 print(f"\n--- {code} ---")
 for ex in examples[:20]:
 print(ex)
 else:
 print("No error examples.")

 print("\n[WARNING EXAMPLES]")
 if warn_examples:
 for code, examples in warn_examples.items():
 print(f"\n--- {code} ---")
 for ex in examples[:20]:
 print(ex)
 else:
 print("No warning examples.")

 return {
 "split": split,
 "errors": error_counter,
 "warnings": warning_counter,
 "class_counter": class_counter,
 "stats": all_stats,
 }


def main():
 if not DATASET_DIR.exists():
 print(f"[ERROR] 数据集目录不存在: {DATASET_DIR}")
 return

 yaml_info = load_yaml()
 if yaml_info is None:
 return

 nc = int(yaml_info["nc"])

 results = []
 for split in ["train", "val"]:
 result = scan_split(split, nc)
 if result is not None:
 results.append(result)

 print("\n========== FINAL SUMMARY ==========")

 total_errors = Counter()
 total_warnings = Counter()
 total_classes = Counter()
 total_boxes = 0

 for r in results:
 total_errors.update(r["errors"])
 total_warnings.update(r["warnings"])
 total_classes.update(r["class_counter"])
 total_boxes += len(r["stats"])

 print(f"total boxes: {total_boxes}")
 print(f"total classes with labels: {len(total_classes)}")
 print(f"total errors: {sum(total_errors.values())}")
 print(f"total warnings: {sum(total_warnings.values())}")

 if total_errors:
 print("\nFinal error counts:")
 for k, v in total_errors.most_common():
 print(f"{k}: {v}")
 else:
 print("\nNo hard label errors found.")

 if total_warnings:
 print("\nFinal warning counts:")
 for k, v in total_warnings.most_common():
 print(f"{k}: {v}")
 else:
 print("\nNo label warnings found.")

 print("\n[DONE]")


if __name__ == "__main__":
 main()

运行：

1

python scripts/04_check_yolo_dataset.py

如果一切正常，最后应该能看到类似：

1
2


No hard label errors found.
[DONE]

如果出现 warning，不一定代表数据不能用。例如 Quick, Draw! 有些图形本身就是细长的线条，所以可能出现：

1
2
3


extreme_ratio
small_wh
small_area

这些需要结合样本查看，不一定要全部删除。

但如果出现下面这些 hard error，就需要优先处理：

1
2
3
4
5
6
7
8


missing_image
bad_image
bad_columns
not_number
class_out_of_range
coord_out_of_0_1
zero_or_negative_wh
label_without_image

我的训练流程里，这一步放在可视化预览之前：

1
2
3


python scripts/03_convert_quickdraw_to_yolo.py
python scripts/04_check_yolo_dataset.py
python scripts/05_preview_yolo_labels.py

九、抽样可视化检查 YOLO 标签框

脚本检查完之后，还要人工看一批图片，确认框的位置是否符合预期。

保存为：

1

scripts/05_preview_yolo_labels.py

这个脚本会从训练集或验证集随机抽样，把 YOLO 框画出来，保存到：

1

datasets/quickdraw_all/preview/

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104


import random
from pathlib import Path

import cv2
import yaml


DATASET_DIR = Path("datasets") / "quickdraw_all"
YAML_PATH = DATASET_DIR / "quickdraw_all.yaml"

SPLIT = "val"
NUM_PREVIEW = 50

OUT_DIR = DATASET_DIR / "preview"


def load_names():
 with YAML_PATH.open("r", encoding="utf-8") as f:
 data = yaml.safe_load(f)

 names = data["names"]

 if isinstance(names, dict):
 names = {int(k): v for k, v in names.items()}
 else:
 names = {i: name for i, name in enumerate(names)}

 return names


def draw_one(image_path: Path, label_path: Path, names):
 img = cv2.imread(str(image_path))
 if img is None:
 return None

 h, w = img.shape[:2]

 if label_path.exists():
 lines = label_path.read_text(encoding="utf-8").splitlines()

 for line in lines:
 parts = line.strip().split()
 if len(parts) != 5:
 continue

 cls_id = int(float(parts[0]))
 xc, yc, bw, bh = map(float, parts[1:])

 x1 = int((xc - bw / 2) * w)
 y1 = int((yc - bh / 2) * h)
 x2 = int((xc + bw / 2) * w)
 y2 = int((yc + bh / 2) * h)

 x1 = max(0, min(w - 1, x1))
 y1 = max(0, min(h - 1, y1))
 x2 = max(0, min(w - 1, x2))
 y2 = max(0, min(h - 1, y2))

 label = names.get(cls_id, str(cls_id))

 cv2.rectangle(img, (x1, y1), (x2, y2), (0, 0, 255), 2)
 cv2.putText(
 img,
 label,
 (x1, max(20, y1 - 8)),
 cv2.FONT_HERSHEY_SIMPLEX,
 0.7,
 (0, 0, 255),
 2,
 cv2.LINE_AA,
 )

 return img


def main():
 names = load_names()

 image_dir = DATASET_DIR / "images" / SPLIT
 label_dir = DATASET_DIR / "labels" / SPLIT

 OUT_DIR.mkdir(parents=True, exist_ok=True)

 images = list(image_dir.glob("*.jpg")) + list(image_dir.glob("*.png"))
 if not images:
 raise RuntimeError(f"No images found in {image_dir}")

 sample_images = random.sample(images, min(NUM_PREVIEW, len(images)))

 for i, image_path in enumerate(sample_images):
 label_path = label_dir / f"{image_path.stem}.txt"

 img = draw_one(image_path, label_path, names)
 if img is None:
 continue

 out_path = OUT_DIR / f"preview_{i:03d}_{image_path.name}"
 cv2.imwrite(str(out_path), img)

 print(f"Preview images saved to: {OUT_DIR}")


if __name__ == "__main__":
 main()

运行：

1

python scripts/05_preview_yolo_labels.py

检查输出目录：

1

datasets/quickdraw_all/preview/

确认框没有明显偏移、类别没有错乱，再进入训练。

十、训练 YOLO11

保存为：

1

scripts/06_train_yolo11.py

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


from ultralytics import YOLO


MODEL = "yolo11n.pt"
DATA = "datasets/quickdraw_all/quickdraw_all.yaml"

EPOCHS = 50
IMGSZ = 640
BATCH = 16
DEVICE = 0 # 没有 GPU 改成 "cpu"

PROJECT = "runs/detect"
NAME = "quickdraw_yolo11n"


def main():
 model = YOLO(MODEL)

 model.train(
 data=DATA,
 epochs=EPOCHS,
 imgsz=IMGSZ,
 batch=BATCH,
 device=DEVICE,
 project=PROJECT,
 name=NAME,
 workers=4,
 patience=10,
 cache=False,
 )


if __name__ == "__main__":
 main()

运行：

1

python scripts/06_train_yolo11.py

也可以直接用命令行训练：

1
2
3
4
5
6
7
8
9


yolo detect train \
 model=yolo11n.pt \
 data=datasets/quickdraw_all/quickdraw_all.yaml \
 epochs=50 \
 imgsz=640 \
 batch=16 \
 device=0 \
 project=runs/detect \
 name=quickdraw_yolo11n

训练完成后，最佳模型会保存在：

1

runs/detect/quickdraw_yolo11n/weights/best.pt

最后一轮模型一般在：

1

runs/detect/quickdraw_yolo11n/weights/last.pt

十一、预测测试

保存为：

1

scripts/07_predict.py

代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


from ultralytics import YOLO


MODEL_PATH = "runs/detect/quickdraw_yolo11n/weights/best.pt"
SOURCE = "test_images"

IMGSZ = 640
CONF = 0.25


def main():
 model = YOLO(MODEL_PATH)

 model.predict(
 source=SOURCE,
 imgsz=IMGSZ,
 conf=CONF,
 save=True,
 project="runs/detect",
 name="quickdraw_predict",
 )


if __name__ == "__main__":
 main()

把测试图片放到：

1

test_images/

运行：

1

python scripts/07_predict.py

预测结果会输出到：

1

runs/detect/quickdraw_predict/

十二、完整执行顺序

整理一下，完整流程是：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# 1. 下载全部类别
python scripts/01_download_quickdraw_all.py

# 2. 核验并补下载缺失或损坏的 NDJSON 原始文件
python scripts/02_verify_and_fix_quickdraw.py

# 3. 转换成 YOLO 数据集
python scripts/03_convert_quickdraw_to_yolo.py

# 4. 检查转换后的 YOLO 数据集完整性
python scripts/04_check_yolo_dataset.py

# 5. 抽样可视化检查标签框
python scripts/05_preview_yolo_labels.py

# 6. 训练 YOLO11
python scripts/06_train_yolo11.py

# 7. 预测测试
python scripts/07_predict.py

对应脚本功能：

脚本	作用
`01_download_quickdraw_all.py`	下载全部 Quick, Draw! 类别
`02_verify_and_fix_quickdraw.py`	检查 NDJSON 下载完整度并补下载
`03_convert_quickdraw_to_yolo.py`	转换为 YOLO 数据集
`04_check_yolo_dataset.py`	检查 YOLO 数据集完整性
`05_preview_yolo_labels.py`	抽样可视化标签框
`06_train_yolo11.py`	训练 YOLO11
`07_predict.py`	预测测试

十三、第一次训练建议参数

第一次不要直接上超大数据量，先跑通流程。

我建议先这样设置：

1
2
3
4


SAMPLES_PER_CLASS = 200
MODEL = "yolo11n.pt"
EPOCHS = 30
BATCH = 8

这样可以快速验证：

1
2
3
4
5
6


下载是否完整
转换脚本是否正常
YOLO 数据集检查是否通过
标签框是否正确
YOLO11 是否能正常训练
预测输出是否正常

确认流程没问题后，再扩大到：

1
2
3
4


SAMPLES_PER_CLASS = 1000
MODEL = "yolo11n.pt"
EPOCHS = 50
BATCH = 16

如果显卡性能足够，再考虑：

1
2
3
4


SAMPLES_PER_CLASS = 3000
MODEL = "yolo11s.pt"
EPOCHS = 80
BATCH = 16

十四、后续调参方向

1. 调整每类样本数量

最重要的参数之一是：

1

SAMPLES_PER_CLASS = 1000

不同设置大概对应：

每类样本数	总图片数量	适合阶段
200	约 6.9 万	流程验证
500	约 17 万	小规模训练
1000	约 34.5 万	正式 baseline
3000	约 103.5 万	更充分训练
10000	约 345 万	大规模训练

我的建议：

1
2
3


先用 200 跑通流程
再用 1000 训练 baseline
最后根据效果决定是否扩大到 3000

2. 调整模型大小

YOLO11 有不同规模的模型。

一般可以按这个顺序尝试：

1

yolo11n.pt → yolo11s.pt → yolo11m.pt

建议：

模型	特点	适合场景
yolo11n.pt	最快，最轻	测试流程、低显存
yolo11s.pt	精度和速度平衡	推荐正式 baseline
yolo11m.pt	更强，但更慢	数据量更大、有较好 GPU

如果只是先验证 Quick, Draw! 方案，使用：

1

MODEL = "yolo11n.pt"

如果效果稳定，可以换成：

1

MODEL = "yolo11s.pt"

3. 调整训练轮数

训练轮数在脚本里是：

1

EPOCHS = 50

建议：

训练轮数	适合阶段
10	快速测试
30	初步训练
50	baseline
80	更充分训练
100+	大数据长期训练

如果训练过程中验证集指标已经不再提升，可以减少 epochs。

如果模型还在持续提升，可以增加 epochs。

4. 调整 batch size

batch 参数：

1

BATCH = 16

如果显存不够，训练时报 CUDA out of memory，可以降低：

1

BATCH = 8

甚至：

1

BATCH = 4

如果显存充足，可以提高：

1

BATCH = 32

经验上：

1
2
3


显存小：batch=4 或 8
8GB 显存：batch=8 或 16
16GB 显存：batch=16 或 32

5. 调整图片尺寸

当前图片尺寸是：

1

IMG_SIZE = 640

训练时也是：

1

IMGSZ = 640

如果想训练更快，可以改成：

1

IMGSZ = 416

如果想保留更多细节，可以改成：

1

IMGSZ = 768

但是图片越大，显存占用越高，训练越慢。

我的建议：

1
2
3


baseline 使用 640
显存不足使用 416 或 512
后期追求精度再尝试 768

6. 调整是否只使用 recognized 样本

转换脚本里有：

1

ONLY_RECOGNIZED = True

如果为 True，只使用 Quick, Draw! 中被系统识别成功的样本。

优点：

1
2
3


数据更干净
标签和图形更稳定
训练更容易收敛

缺点：

1

少了一些更难、更潦草、更真实的手绘样本

如果想让模型更鲁棒，可以后期尝试：

1

ONLY_RECOGNIZED = False

但建议 baseline 先保持：

1

ONLY_RECOGNIZED = True

7. 调整数据增强

当前转换脚本里的增强比较保守：

1

ENABLE_AUGMENT = True

增强内容包括：

1
2
3
4
5
6


不同背景颜色
不同笔迹深浅
不同笔迹粗细
轻微模糊
亮度变化
对比度变化

这些增强不会改变几何位置，所以 YOLO 框不用重新计算。

后续如果想更贴近真实纸面照片，可以加入：

1
2
3
4
5
6


纸张纹理
阴影
轻微噪声
拍照模糊
JPEG 压缩
局部光照变化

但要注意：

1

旋转、透视变换、裁剪这类增强会改变 bbox

如果加入这些增强，就必须同步变换标注框，否则标签会错。

8. 调整检查脚本阈值

YOLO 数据集检查脚本里有几个阈值：

1
2
3
4
5


MIN_WH = 0.002
WARN_WH = 0.01
WARN_RATIO = 20.0
WARN_AREA_SMALL = 0.0001
WARN_AREA_LARGE = 0.95

如果训练的是线条类目标，很多框天然会比较细长，所以 extreme_ratio 和 small_wh 的 warning 可能会比较多。

如果确认这些是正常样本，可以适当放宽：

1
2


WARN_RATIO = 40.0
WARN_WH = 0.005

但是 hard error 不建议轻易忽略，例如：

1
2
3
4


coord_out_of_0_1
class_out_of_range
label_without_image
bad_image

这些问题应该先修复再训练。

9. 调整置信度阈值

预测脚本中有：

1

CONF = 0.25

如果误检很多，可以提高：

1

CONF = 0.4

如果漏检很多，可以降低：

1

CONF = 0.15

一般可以测试：

观察哪个阈值最适合自己的场景。

10. 训练结果怎么看

训练结束后重点看：

1
2
3
4


Precision
Recall
mAP50
mAP50-95

简单理解：

指标	含义
Precision	检出的东西有多少是真的
Recall	真实目标有多少被检出来
mAP50	IoU=0.5 下的平均检测性能
mAP50-95	更严格的平均检测性能

如果：

1

Precision 高，Recall 低

说明模型比较保守，漏检可能比较多。

如果：

1

Recall 高，Precision 低

说明模型检得比较多，但误检可能比较多。

十五、后续微调真实纸面数据

Quick, Draw! 数据是干净白底手绘图，而真实纸面照片会有很多额外问题：

1
2
3
4
5
6
7


纸张阴影
拍摄角度
纸张纹理
笔迹粗细变化
背景杂乱
多条线同时出现
手写文字干扰

所以 Quick, Draw! 训练出来的模型更适合作为基础模型。

真正落地时，建议继续做：

1
2
3
4


1. 收集真实纸面照片
2. 使用 CVAT 或 Roboflow 标注 YOLO 框
3. 用 Quick, Draw! 训练出的 best.pt 继续微调
4. 用真实测试集评估

微调命令示例：

1
2
3
4
5
6
7
8


yolo detect train \
 model=runs/detect/quickdraw_yolo11n/weights/best.pt \
 data=datasets/paper_lines/paper_lines.yaml \
 epochs=80 \
 imgsz=640 \
 batch=8 \
 device=0 \
 name=paper_lines_finetune

真实纸面数据建议至少准备：

数据量	适合阶段
300 张	快速验证
1000 张	初步可用
3000 张	比较稳定
10000 张以上	更接近生产使用

十六、我的当前结论

这套方案的意义不是直接得到一个最终可商用的纸面线条识别模型，而是先训练出一个手绘风格基础模型。

当前流程可以总结为：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


Quick, Draw! 全量类别
 ↓
检查 NDJSON 下载完整度
 ↓
自动转 YOLO 检测数据
 ↓
检查 YOLO 数据集完整性
 ↓
抽样可视化标签框
 ↓
训练 YOLO11 baseline
 ↓
用真实纸面数据继续微调

我后续主要会继续优化三件事：

1
2
3


1. 扩大每类样本数量
2. 尝试 yolo11s.pt 或 yolo11m.pt
3. 加入真实纸面照片进行微调

最终目标是让模型不仅能识别干净白底手绘图，也能识别真实纸张上拍摄出来的线条和图形。

OpenPCDet 常用训练、测试与可视化命令

Mon, 18 May 2026 00:00:00 +0000

这篇文章整理 OpenPCDet 中比较常用的训练、测试、demo 可视化和显卡监控命令，方便后续实验时快速复制。

1. 启动 TensorBoard

在日志目录下运行：

1

tensorboard --logdir=./

如果训练输出目录类似：

1

output/kitti_models/pointpillar/default

也可以进入对应目录后再启动 TensorBoard。

2. PointPillar demo 测试

1
2
3
4
5


python demo.py \
 --cfg_file cfgs/kitti_models/pointpillar.yaml \
 --ckpt /home/cx/OpenPCDet/output/kitti_models/pointpillar/default/ckpt/checkpoint_epoch_80.pth \
 --data_path /home/cx/OpenPCDet/data/kitti/testing/velodyne \
 --ext .bin

参数说明：

参数	说明
`--cfg_file`	模型配置文件
`--ckpt`	加载的 checkpoint
`--data_path`	点云数据路径
`--ext`	点云文件后缀，KITTI 通常是 `.bin`

3. PointPillar 测试

1
2
3
4


python test.py \
 --cfg_file ../tools/cfgs/kitti_models/pointpillar.yaml \
 --batch_size 4 \
 --ckpt ../output/kitti_models/pointpillar/default/ckpt/checkpoint_epoch_80.pth

如果测试时需要保存提交结果，需要加上：

1

--save_to_file

例如：

1
2
3
4
5


python test.py \
 --cfg_file ../tools/cfgs/kitti_models/pointpillar.yaml \
 --batch_size 4 \
 --ckpt ../output/kitti_models/pointpillar/default/ckpt/checkpoint_epoch_80.pth \
 --save_to_file

4. 训练 PillarNet

1

python train.py --cfg_file cfgs/kitti_models/pillarnet.yaml

如果后续需要指定 batch size、epoch 或多卡训练，可以在此基础上继续扩展参数。

5. 评估模型

示例命令：

1
2
3
4


python test.py \
 --cfg_file cfgs/kitti_models/voxt_gnn.yaml \
 --batch_size 4 \
 --ckpt ../output/kitti_models/voxt_gnn/default/ckpt/checkpoint_epoch_120.pth

建议每次评估时记录：

配置文件；
checkpoint 路径；
batch size；
是否开启 --save_to_file；
评估结果；
当前代码 commit 或修改说明。

6. demo 可视化颜色对应关系

OpenPCDet demo 中可以通过 box_colormap 设置不同类别框的颜色：

1
2
3
4
5
6


box_colormap = [
 [1, 1, 1], # index 0 -> 白色，未使用
 [0, 1, 0], # index 1 -> 绿色
 [0, 1, 1], # index 2 -> 青色，蓝绿色
 [1, 1, 0], # index 3 -> 黄色
]

对应关系如下：

颜色	index	类别
绿色	1	Car
蓝绿色	2	Pedestrian
黄色	3	Cyclist

7. 显卡监控工具 nvitop

安装：

1

pip install nvitop

运行：

1

nvitop -m full

相比 nvidia-smi，nvitop 的交互体验更好，适合训练时观察显存、功耗和进程占用。

8. 建议的实验记录格式

每次训练或测试建议记录成下面这种格式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


## 实验名称

- 日期：
- 数据集：
- 配置文件：
- 修改代码：
- checkpoint：
- batch size：
- GPU：
- 训练轮数：
- 评估结果：
- 备注：

这样后续对比不同模型结构和参数时会更清楚。

总结

这篇主要是命令速查。OpenPCDet 实验比较多时，最重要的是保证配置文件、checkpoint 和代码改动能够对应起来，否则后期很容易忘记某个结果是怎么跑出来的。

OpenPCDet 实验资料、调试提示词与工具索引

Mon, 18 May 2026 00:00:00 +0000

这篇文章整理 OpenPCDet 实验中零散但常用的资料链接、工具脚本和代码分析提示词，方便后续查找。

1. KITTI road plane 资料

关于 KITTI road plane 的生成和下载，可以参考：

1
2


https://github.com/sshaoshuai/PointRCNN/issues/12#issuecomment-484769943
https://github.com/kujason/avod?tab=readme-ov-file

road plane 在一些基于 KITTI 的 3D 检测方法中会用到，配置数据集时需要注意相关文件是否完整。

2. nuScenes 数据集子集划分

如果想把 nuScenes 数据集拆分为 20% 子集，可以使用：

1

create_subset.py

建议在使用子集实验时记录清楚：

子集比例；
随机种子；
train / val 划分方式；
使用的 sample token；
是否保持类别分布一致。

否则不同实验之间可能无法公平比较。

3. 模型参数量统计

需要注意：

1

.pth 文件大小不等于模型参数量

模型参数量可以使用：

1

tools/count_params.py

建议同时记录：

参数量；
checkpoint 大小；
FLOPs；
推理速度；
显存占用。

这样比单独记录 .pth 文件大小更有意义。

4. 显卡监控工具

安装：

1

pip install nvitop

运行：

1

nvitop -m full

训练模型时可以用它观察：

显存占用；
GPU 利用率；
温度；
功耗；
当前占用 GPU 的进程。

5. 代码分析提示词

如果需要让 AI 辅助分析 OpenPCDet 代码，可以使用下面的提示词。

5.1 分析 VFE 过程

1

以下是这篇论文的 VFE 过程。我是一名 3D 目标检测学习的新手，请根据代码和输入点云举例，用类似 debug 的形式，通俗易懂地一步一步分析 VFE 的过程。

5.2 分析 OpenPCDet 数据流

1

请用点云举例，一步一步分析 OpenPCDet 中 VFE、backbone、dense head 等模块的数据流变化。请结合代码，用类似 debug 的形式解释每一步输入输出的 shape 和含义。

5.3 分析某个模块

1

我是 3D 目标检测新手。请结合 OpenPCDet 源码，以一帧 KITTI 点云为例，用 debug 的方式逐行解释这个模块的输入、输出、shape 变化和每一步的作用。

5.4 分析论文改进点

1

请根据这篇论文的模型结构和 OpenPCDet 中的实现代码，帮我分析它相对于 PointPillar / SECOND / DSVT 的主要改进点，并说明这些改进可能影响哪些类别和哪些指标。

6. 实验记录模板

建议每次实验都单独记录：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


## 实验名称

### 基本信息

- 日期：
- 数据集：
- 模型：
- 配置文件：
- 代码文件：
- checkpoint：
- GPU：
- batch size：
- epoch：

### 修改内容

- 修改点 1：
- 修改点 2：
- 修改点 3：

### 训练命令

```bash
python train.py --cfg_file ...

测试命令

1

python test.py --cfg_file ... --ckpt ...

结果

类别	Easy	Moderate	Hard
Car
Pedestrian
Cyclist

备注

是否出现报错：
是否保存提交文件：
是否需要复跑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17



## 7. 推荐的实验目录管理方式

可以按下面方式组织：

```text
experiments/
├── 2026-05-18-dsvt-baseline/
│ ├── config.yaml
│ ├── notes.md
│ ├── train.log
│ └── eval.log
├── 2026-05-19-dsvt-cross-xy/
│ ├── config.yaml
│ ├── notes.md
│ ├── train.log
│ └── eval.log

这样做的好处是：

每个实验独立；
配置和结果能一一对应；
后续写论文或报告时容易追溯；
出现问题时方便回滚。

总结

这篇文章主要作为资料索引使用。OpenPCDet 实验中很多问题不是一次性解决的，建议把链接、脚本、提示词和实验记录模板长期维护起来，后续会非常省时间。

OpenPCDet 与 nuScenes 的 NumPy 兼容问题

Mon, 18 May 2026 00:00:00 +0000

这篇文章整理 OpenPCDet 和 nuScenes 测试过程中遇到的 NumPy 兼容问题，主要是 np.int、np.float 等旧别名在新版本 NumPy 中被移除导致的报错。

1. 当前 NumPy 版本

当前记录中，NumPy 的原始正常版本是：

1
2


Name: numpy
Version: 1.26.4

在 NumPy 1.24 之后，np.int、np.float、np.bool 等旧别名已经被移除。如果旧代码中仍然使用这些写法，就会报错。

2. OpenPCDet 中 np.int 报错

2.1 报错现象

如果报错类似：

1

AttributeError: module 'numpy' has no attribute 'int'

通常说明代码里还有旧写法：

1

np.int

2.2 修改位置

根据报错信息，需要修改的文件是：

1

/home/cx/OpenPCDet/pcdet/models/backbones_2d/base_bev_backbone.py

找到第 299 行或附近代码：

1

stride = np.round(1 / stride).astype(np.int)

修改为：

1

stride = np.round(1 / stride).astype(int)

或者指定具体精度：

1

stride = np.round(1 / stride).astype(np.int64)

2.3 修改建议

如果只是为了兼容原代码，通常直接改成 int 即可。

如果后续涉及严格的 tensor shape、索引或跨平台一致性，也可以考虑明确使用 np.int64 或 np.int32。

3. nuScenes 测试时 np.float 报错

3.1 修改位置

直接修改当前 Conda 环境中的文件：

1

/home/cx/anaconda3/envs/Openpcdet-cu117/lib/python3.10/site-packages/nuscenes/eval/detection/algo.py

找到类似代码：

1

tp = np.cumsum(tp).astype(np.float)

修改为：

1

tp = np.cumsum(tp).astype(float)

或者：

1

tp = np.cumsum(tp).astype(np.float64)

4. 同类旧别名统一替换

如果同一个文件里还有下面这些写法：

1
2
3


np.int
np.float
np.bool

可以分别改成：

1
2
3


int
float
bool

或者改成明确的 NumPy 类型：

1
2
3


np.int64
np.float64
np.bool_

5. 临时兼容垫片

如果只是临时跑通，也可以在文件开头加入兼容垫片：

1
2
3
4
5
6


import numpy as np

if not hasattr(np, "float"):
 np.float = float
 np.int = int
 np.bool = bool

不过这种方法不够优雅，容易掩盖旧代码问题。长期来看，更推荐直接修改旧别名。

6. 训练 nuScenes 数据集时的注意事项

笔记中记录：训练 nuScenes 数据集时如果因为 NumPy 版本报错，需要先修改相关代码，训练完成后根据实际情况决定是否改回。

我的建议是：

如果你维护的是自己的实验代码，可以直接替换旧别名；
如果你只是临时运行别人的代码，可以用补丁方式记录修改；
修改第三方库文件时，最好单独记录修改点，避免后续换环境后忘记。

7. PillarNet 测试报错记录

PillarNet 测试时可能遇到：

1

KeyError: 'final_box_dicts'

可以参考：

1

https://github.com/open-mmlab/OpenPCDet/issues/1524

建议排查方向：

当前 model.forward() 返回值是否符合测试脚本预期；
配置文件是否与模型代码版本匹配；
是否混用了不同分支或不同版本的 OpenPCDet 代码；
post_processing 是否正常返回预测框结果。

8. 常用测试命令

示例：

1
2
3
4


python test.py \
 --cfg_file ../tools/cfgs/kitti_models/pointpillar.yaml \
 --batch_size 4 \
 --ckpt ../output/kitti_models/pointpillar/default/ckpt/checkpoint_epoch_80.pth

如果需要保存测试提交文件：

1
2
3
4
5


python test.py \
 --cfg_file ../tools/cfgs/kitti_models/pointpillar.yaml \
 --batch_size 4 \
 --ckpt ../output/kitti_models/pointpillar/default/ckpt/checkpoint_epoch_80.pth \
 --save_to_file

总结

OpenPCDet 和 nuScenes 中这类报错本质上多半不是算法问题，而是旧代码和新依赖之间的兼容问题。遇到 np.int、np.float、np.bool 报错时，优先搜索对应文件并替换旧别名即可。

ROS2 与 OpenPCDet 跨环境调用配置

Mon, 18 May 2026 00:00:00 +0000

在 ROS2 节点中调用 OpenPCDet 时，比较容易遇到 Conda 环境和 ROS2 系统环境冲突的问题。这篇文章记录我在配置过程中的处理方式。

1. 问题背景

OpenPCDet 通常运行在 Conda 环境中，例如：

1

conda activate Openpcdet-cu117

而 ROS2 通常安装在系统目录，例如：

1

/opt/ros/humble

因此运行 ROS2 + OpenPCDet 节点时，需要同时处理：

Conda Python 环境；
ROS2 Python 接口；
ROS2 系统环境变量；
C++ 动态库链接问题。

2. 基本原则

不要直接在普通系统终端里运行 Conda 环境中的 OpenPCDet 代码。

推荐流程是：

先激活 OpenPCDet Conda 环境；
在该环境中安装需要的 ROS2 Python 依赖；
source ROS2 的系统环境变量；
必要时设置 LD_PRELOAD；
回到 OpenPCDet 根目录运行节点。

3. 激活 OpenPCDet Conda 环境

1

conda activate Openpcdet-cu117

后续命令都建议在这个环境下执行。

4. 安装 ROS2 Python 基础库

假设使用的是 ROS2 Humble：

1

pip install rclpy

注意：这里安装的是 Python 接口，不等于安装完整 ROS2。

如果你的 ROS2 版本不是 Humble，需要根据实际版本调整后续路径。

5. 加载 ROS2 系统环境变量

1

source /opt/ros/humble/setup.bash

这一步很重要，否则 Python 代码中可能无法正确找到 ROS2 相关包和环境配置。

6. 处理 C++ 动态库 ImportError

如果运行时遇到 C++ 动态库相关的 ImportError，可以尝试强制预加载系统的 libstdc++.so.6：

1

export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6

完整运行流程如下：

1
2
3
4
5
6


conda activate Openpcdet-cu117
source /opt/ros/humble/setup.bash
export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6

cd ~/OpenPCDet
python3 ros2/pcdet_ros2_node.py

7. 推荐启动脚本

为了避免每次手动输入，可以写一个简单脚本，例如：

1
2
3
4
5
6
7
8


#!/usr/bin/env bash

conda activate Openpcdet-cu117
source /opt/ros/humble/setup.bash
export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6

cd ~/OpenPCDet
python3 ros2/pcdet_ros2_node.py

保存为：

1

run_pcdet_ros2.sh

赋予执行权限：

1

chmod +x run_pcdet_ros2.sh

运行：

1

./run_pcdet_ros2.sh

8. 排查思路

如果仍然报错，可以按下面顺序排查：

8.1 检查当前 Python 是否来自 Conda 环境

1
2


which python
python -V

预期路径应类似：

1

/home/cx/anaconda3/envs/Openpcdet-cu117/bin/python

8.2 检查 rclpy 是否能导入

1

python -c "import rclpy; print('rclpy ok')"

8.3 检查 ROS2 环境变量

1

echo $ROS_DISTRO

如果使用 Humble，预期输出：

1

humble

8.4 检查 libstdc++ 路径

1

echo $LD_PRELOAD

如果已经设置，应该看到：

1

/usr/lib/x86_64-linux-gnu/libstdc++.so.6

总结

ROS2 与 OpenPCDet 一起使用时，核心问题不是模型本身，而是 Python 环境和系统 ROS2 环境之间的衔接。我的建议是把启动流程写成脚本，固定执行顺序，避免每次手动配置导致环境不一致。

Ubuntu 新 SSD 挂载到 /home/cx/data

Mon, 18 May 2026 00:00:00 +0000

在配置 OpenPCDet 数据集之前，我先把新 SSD 挂载到了 /home/cx/data，用于存放 KITTI、nuScenes 等点云数据集。

⚠️ 注意：本文中的分区、wipefs、mkfs 都是破坏性操作，会清空目标硬盘数据。执行前一定要确认目标盘是新盘，例如 /dev/sdb，不要误操作系统盘 /dev/sda 或 Windows 盘 nvme0n1。

1. 确认新盘设备名

先查看磁盘列表、型号、文件系统、挂载点等信息：

1
2


sudo lsblk -o NAME,SIZE,FSTYPE,LABEL,MOUNTPOINTS,MODEL,SERIAL,TRAN
sudo fdisk -l /dev/sdb

需要确认：

/dev/sdb 是新 SSD；
/dev/sda 是系统盘时不要动；
nvme0n1 如果是 Windows 盘，也不要动；
后续所有 /dev/sdb 都要根据自己机器实际情况替换。

预期能看到类似：

1

/dev/sdb MODEL 显示你的新 SSD，例如 Fanxiang S100Pro

2. 创建 GPT 分区表和全盘分区

1
2
3


sudo parted -s /dev/sdb mklabel gpt
sudo parted -s /dev/sdb mkpart primary ext4 0% 100%
lsblk /dev/sdb

正常情况下会出现：

1

/dev/sdb1

3. 擦除旧文件系统签名

如果硬盘之前被格式化过，可能残留 NTFS 或其他文件系统签名，导致 mkfs 时出现提示。建议先查看，再擦除：

1
2
3


sudo umount /dev/sdb1 2>/dev/null || true
sudo wipefs -n /dev/sdb1
sudo wipefs -a /dev/sdb1

说明：

wipefs -n：只查看，不修改；
wipefs -a：擦除文件系统签名。

4. 格式化为 ext4

1

sudo mkfs.ext4 -L data /dev/sdb1

这里使用 -L data 给分区设置标签，方便后续识别。

5. 挂载到 /home/cx/data

1
2
3


mkdir -p /home/cx/data
sudo mount /dev/sdb1 /home/cx/data
df -hT | grep /home/cx/data

如果希望用户 cx 可以直接读写这个目录，可以修改目录所有者：

1

sudo chown -R cx:cx /home/cx/data

6. 设置开机自动挂载

先获取分区 UUID：

1

sudo blkid /dev/sdb1

编辑 /etc/fstab：

1

sudo nano /etc/fstab

追加一行：

1

UUID=你的UUID /home/cx/data ext4 defaults,nofail 0 2

注意把 UUID=你的UUID 替换成真实 UUID。

保存后测试：

1
2


sudo mount -a
df -hT | grep -E "/home/cx/data|/data|/mnt/data"

sudo mount -a 很重要。如果这里不报错，说明开机自动挂载配置基本没问题。

7. 处理 mount point does not exist

如果执行：

1

sudo mount -a

时报错：

1

mount: /mnt/data: mount point does not exist.

说明 /etc/fstab 中还有一条指向 /mnt/data 的挂载项，但该目录不存在。

方案 A：注释或删除 /mnt/data 挂载项

推荐这种方式：

1

sudo nano /etc/fstab

找到包含 /mnt/data 的那一行，删除或在行首加 # 注释掉。

然后重新测试：

1

sudo mount -a

方案 B：创建 /mnt/data 目录

如果你确实需要使用 /mnt/data，可以创建目录：

1
2


sudo mkdir -p /mnt/data
sudo mount -a

8. 开启 SSD 定期 TRIM

1
2


sudo systemctl enable --now fstrim.timer
systemctl status fstrim.timer

9. 快速验证清单

1
2
3
4
5
6
7
8


# 1. 挂载是否生效
df -hT | grep /home/cx/data

# 2. 是否是 ext4
lsblk -f | grep -A2 sdb

# 3. fstab 配置是否无误
sudo mount -a

总结

新 SSD 挂载时最容易出问题的地方有两个：

设备名确认错误，导致误格式化其他硬盘；
/etc/fstab 写错，导致开机挂载失败。

所以每次修改 /etc/fstab 后，都建议立即执行：

1

sudo mount -a

这样可以在重启前提前发现问题。

Git 日常使用入门：从提交到协作

Sun, 17 May 2026 00:00:00 +0000

Git 是一个版本管理工具。你可以把它理解成项目的“时间机器”：每次完成一小段工作，就保存一个快照；以后如果改坏了，可以回头看、对比、撤销，也可以和 GitHub 这类远程仓库同步。

这篇文章不讲太多底层原理，只整理日常最常用的一套 Git 操作。

先理解三个区域

Git 日常操作主要围绕三个区域：

1
2
3
4
5
6
7
8


工作区 Working Directory
 你正在编辑的文件

暂存区 Staging Area
 准备放进下一次提交的文件

本地仓库 Repository
 已经提交保存的历史记录

对应到命令就是：

1
2


git add .
git commit -m "提交说明"

git add 是把改动放进暂存区，git commit 是把暂存区里的内容真正保存成一次历史记录。

第一次配置 Git

新电脑上使用 Git 前，建议先设置用户名和邮箱：

1
2


git config --global user.name "Your Name"
git config --global user.email "you@example.com"

查看当前配置：

1

git config --global --list

这些信息会记录在每次提交里，方便以后知道是谁提交了这次改动。

初始化一个仓库

如果一个文件夹还不是 Git 仓库，可以进入这个项目目录后执行：

1

git init

然后查看当前状态：

1

git status

git status 是最常用的命令之一。只要不知道现在发生了什么，就先看它。

完成一次提交

日常最标准的保存流程是：

1
2
3


git status
git add .
git commit -m "说明这次改了什么"

例如你写完一篇博客文章：

1
2


git add content/post/git-daily-guide/index.md
git commit -m "Add Git daily guide"

如果这次修改了多个文件，也可以直接：

1
2


git add .
git commit -m "Update blog content"

提交说明建议写清楚“做了什么”，不用太长，但要能看懂。

查看历史记录

查看提交历史：

1

git log

更简洁的写法：

1

git log --oneline

查看某一次提交改了什么：

1

git show 提交ID

提交 ID 不需要写完整，通常复制前 7 位左右就够了。

查看文件改动

查看工作区里还没暂存的改动：

1

git diff

查看已经 git add 进暂存区、但还没提交的改动：

1

git diff --cached

这是提交前很有用的一步，可以避免把不该提交的内容带进去。

连接远程仓库

如果你已经在 GitHub 上创建了仓库，可以把本地仓库和远程仓库关联起来：

1

git remote add origin git@github.com:用户名/仓库名.git

查看远程仓库地址：

1

git remote -v

第一次推送：

1

git push -u origin main

以后再推送就可以直接：

1

git push

如果你的默认分支叫 master，就把上面的 main 改成 master。

从远程拉取更新

如果远程仓库有别人提交的内容，或者你在另一台电脑上改过代码，回到当前电脑后可以拉取：

1

git pull

它大致等于“先下载远程更新，再合并到当前分支”。

日常建议是：

1
2
3
4
5


git pull
# 修改文件
git add .
git commit -m "Update something"
git push

先拉再改，可以减少冲突。

分支的基本用法

分支适合用来做一段独立修改，比如写新功能、改页面、尝试新样式。

查看当前分支：

1

git branch

创建并切换到新分支：

1

git switch -c feature/about-page

切回主分支：

1

git switch main

把分支合并回主分支：

1
2


git switch main
git merge feature/about-page

合并完成后，如果不再需要这个分支，可以删除：

1

git branch -d feature/about-page

撤销还没提交的修改

如果某个文件改坏了，还没有 git add，可以丢弃这个文件的改动：

1

git restore 文件路径

例如：

1

git restore assets/scss/custom.scss

如果已经 git add 了，但还没有提交，可以先取消暂存：

1

git restore --staged 文件路径

然后再决定是否丢弃工作区修改。

修改上一次提交

如果刚提交完，发现提交说明写错了，可以改最后一次提交说明：

1

git commit --amend -m "新的提交说明"

如果刚提交完，发现漏了一个文件：

1
2


git add 漏掉的文件
git commit --amend --no-edit

--no-edit 表示沿用上一次提交说明。

注意：如果这次提交已经推送给别人使用了，修改历史前要谨慎。

回退一次提交

如果想撤销某一次已经提交的改动，比较稳妥的方式是 revert：

1

git revert 提交ID

它不会删除历史，而是新建一个“反向提交”。这种方式适合已经推送到远程仓库的提交。

不建议新手随便使用：

1

git reset --hard

它会直接丢弃改动，比较危险。

处理冲突

冲突通常发生在两个人改了同一个文件的同一段内容，或者你在两台电脑上分别改了同一处。

冲突文件里一般会出现类似内容：

1
2
3
4
5


<<<<<<< HEAD
当前分支的内容
=======
别人或远程分支的内容
>>>>>>> main

处理步骤：

打开冲突文件。
保留你真正想要的内容。
删除 <<<<<<<、=======、>>>>>>> 这些标记。
保存文件。
重新提交。

命令大概是：

1
2
3
4


git status
# 手动编辑冲突文件
git add 冲突文件
git commit

如果是 git pull 时产生的冲突，解决后继续提交即可。

忽略不需要提交的文件

有些文件不应该提交，比如缓存、构建产物、临时文件、密钥文件。可以写进 .gitignore：

1
2
3
4
5
6


.DS_Store
Thumbs.db
node_modules/
.env
.hugo_build.lock
resources/_gen/

对 Hugo 博客来说，是否提交 public/ 取决于你的部署方式：

1

public/

如果你使用 Cloudflare Pages、GitHub Actions 等自动构建，一般可以不提交 public/。如果你的部署方式要求上传静态产物，就不要忽略它。

日常推荐流程

个人维护博客时，可以按这个流程来：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


git pull

# 编辑文章或配置
hugo

git status
git diff
git add .
git commit -m "Update blog"
git push

如果只是写新文章：

1
2
3
4


git pull
git add content/post/文章目录/index.md
git commit -m "Add new post"
git push

如果是改主题样式：

1
2
3
4
5
6
7
8


git switch -c style/update-about-page

# 修改 CSS 或模板
hugo

git add .
git commit -m "Update about page style"
git push -u origin style/update-about-page

常用命令速查

目的	命令
查看状态	`git status`
查看改动	`git diff`
暂存全部改动	`git add .`
提交	`git commit -m "message"`
查看历史	`git log --oneline`
拉取远程更新	`git pull`
推送到远程	`git push`
查看分支	`git branch`
新建并切换分支	`git switch -c 分支名`
切换分支	`git switch 分支名`
合并分支	`git merge 分支名`
丢弃某个文件修改	`git restore 文件路径`
取消暂存	`git restore --staged 文件路径`
撤销某次提交	`git revert 提交ID`
查看远程仓库	`git remote -v`

一个简单心法

日常使用 Git 时，记住这几件事就够了：

不确定状态时，先 git status。
提交前先 git diff 看一眼。
每次提交只做一件相对完整的事。
提交说明写清楚，不要全都叫 update。
已经推送到远程的历史，不要轻易乱改。

Git 一开始会显得命令很多，但日常真正高频使用的其实不多。熟悉 status、add、commit、pull、push、diff 之后，就已经可以完成大多数个人项目和博客维护工作了。

Hugo + Stack 博客部署记录

Fri, 15 May 2026 00:00:00 +0000

这篇文章记录本次 Hugo + Stack 博客的部署和写作经验，方便后续忘记时快速找回。

部署方案

当前方案：

1
2
3
4
5
6
7


本地 Hugo 博客
 ↓ git push
GitHub 私有仓库
 ↓ Cloudflare Pages 自动构建
Cloudflare Pages 部署
 ↓
自定义域名 example.com

因为 GitHub 私有仓库启用 GitHub Pages 可能需要升级账户，所以改用 Cloudflare Pages。

GitHub Pages Workflow

如果不用 GitHub Pages，可以删除或禁用 .github/workflows/ 下的 Pages 部署文件。

常见相关配置：

1
2


uses: actions/configure-pages@v6
uses: actions/deploy-pages@v4

禁用自动运行可以改成：

1
2


on:
 workflow_dispatch:

Cloudflare Pages 配置

Cloudflare Pages 构建配置：

1
2
3
4


框架预设：Hugo
构建命令：hugo --gc --minify
构建输出目录：public
根目录：留空

如果 Hugo 项目在子目录，例如 blog/，根目录就填 blog。

Hugo 版本

Stack v4 主题需要较新的 Hugo 版本。Cloudflare Pages 中建议添加环境变量：

1

HUGO_VERSION = 0.158.0

如果日志里出现 Hugo 版本过低或主题不兼容，就优先检查这个变量。

config.toml 关键配置

文件位置：

1

config/_default/config.toml

参考配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


baseurl = "https://example.com/"
title = "My Blog"

defaultContentLanguage = "zh"
hasCJKLanguage = true

[pagination]
 pagerSize = 5

[languages]
 [languages.zh]
 locale = "zh-CN"
 label = "简体中文"
 title = "My Blog"
 weight = 1

注意：Stack 主题中文 i18n 使用 zh，所以 defaultContentLanguage 保持为 zh。不要随便改成 zh-cn，否则可能导致中文不显示。

新文章放在哪里

普通文章建议放在：

1
2


content/post/my-first-post/index.md
content/post/my-first-post/cover.jpg

每篇文章一个独立文件夹，正文、封面、图片都放一起，后续更好管理。

新文章模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


---
title: "文章标题"
description: "一句话摘要"
slug: "my-first-post"
date: 2026-05-15
image: cover.jpg
categories:
 - 技术
tags:
 - Hugo
 - Blog
---

这里开始写正文。

常用字段：

title：文章标题。
description：文章摘要。
slug：文章 URL 的最后一段。
date：发布时间。
image：封面图。
categories：分类。
tags：标签。
comments: false：关闭评论。
math: false：关闭当前文章数学公式渲染。

Markdown 常用写法

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


## 二级标题

这是一段正文。

> 这是一段引用。

| 名称 | 说明 |
| ---- | ---- |
| Hugo | 静态站点生成器 |

```python
print("Hello, Hugo")
```

首页摘要分隔：

1

<!--more-->

数学公式

如果 params.toml 中开启：

1
2


[article]
 math = true

文章里可以写：

1
2
3
4
5
6
7


行内公式：$E = mc^2$

块级公式：

$$
f(x) = x^2
$$

图片

图片建议放在文章目录下：

1
2
3


content/post/my-trip/index.md
content/post/my-trip/cover.jpg
content/post/my-trip/1.jpg

正文插入图片：

1

![图片说明](1.jpg)

连续写多张图片时，Stack 主题会渲染为图片画廊：

1

![图片 1](1.jpg) ![图片 2](2.jpg)

页面和菜单

独立页面放在：

1
2
3


content/page/about/index.md
content/page/archives/index.md
content/page/search/index.md

页面加入左侧菜单：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


---
title: 关于
slug: about
menu:
 main:
 weight: 5
 params:
 icon: user
comments: false
---

weight 控制排序，icon 使用 Tabler Icons 图标名。

Git 回退记录

撤销已经 push 的最近一次提交：

1
2


git revert HEAD
git push

取消还没 push 的最近一次提交：

1

git reset --hard HEAD~1

查看最近提交：

1

git log --oneline -5

取消正在进行中的 revert：

1

git revert --abort

写作建议

分类用大类，例如 技术、生活、阅读。
标签用更细的关键词，例如 Hugo、GitHub、Cloudflare Pages。
文章标题可以用中文，slug 建议用英文或拼音。
封面图和正文图片尽量放在文章同目录。
构建失败时，优先检查 Hugo 版本、主题版本和第一条 ERROR。