tqdm包裹可迭代对象可自动显示实时进度，需知总次数；未知长度时须手动update()并调用close()或用with；set_description()/set_postfix()动态更新状态；嵌套循环需用leave=false或position控制显示位置。
用 tqdm 包裹可迭代对象是最直接的实时进度方案
只要你知道总次数（比如 range(100)、len(data)），tqdm 就能自动算出百分比、剩余时间、速率，且每轮迭代后立即刷新显示。它不是“定时轮询”，而是靠迭代触发更新，天然实时。
- 必须确保被包裹对象是可迭代的，不能是纯函数调用或无长度生成器（否则会报
TypeError: object of type 'generator' has no len()） - 在 Jupyter 中默认走
IPython.utils.io.capture_output通道，若发现进度条不动或重复打印，先检查是否启用了ipywidgets（pip install ipywidgets && jupyter nbextension enable --py widgetsnbextension） - 终端里如果看到进度条闪烁或换行错乱，大概率是输出被其他
print()或日志干扰，建议关闭非必要输出，或用leave=False避免残留
处理未知长度任务时必须手动控制 tqdm.update()
比如从网络流读 chunk、递归遍历目录、或 while 循环中分批拉取数据——这些场景下你无法提前知道 total，但又需要进度反馈。这时不能直接用 for x in tqdm(iterator)，得显式创建实例并调用 update()。
Article To Html
下载
文章转信息图。将文章/笔记转化为手机可读的 HTML 信息图，自动匹配视觉风格。触发场景：文章转图、笔记转图、信息图、转小红书图、做张图、可视化这篇文章、文生图。
- 初始化时传入
total（即使只是预估），否则tqdm会以 “?/?” 形式显示，且不计算 ETA - 每次处理完一批数据后，调用
pbar.update(n)，其中n是本次实际完成数；别用pbar.n += n，它不会触发刷新 - 务必在结束时调用
pbar.close()，否则可能卡在最后一行；若用with语句则自动处理（推荐）
set_description() 和 set_postfix() 是动态展示 PROGRESS 标签的核心
静态进度条只能告诉你“做了多少”，而真实任务常需同步反馈当前状态（如“正在处理第 42 张图”）、中间指标（如 loss=0.023, acc=0.987）。这两个方法就是为此设计的，且不打断进度条结构。
-
set_description("Processing")改的是进度条前缀文字，适合表达阶段切换（如 "Loading → Validating → Saving"） -
set_postfix(loss=0.023, acc=f"{acc:.3f}")加在进度条右侧，支持任意键值对，值会自动格式化为字符串 - 两者都可在循环体内高频调用，但避免在每次迭代都重设完全相同的描述——有性能开销，且视觉上无意义
嵌套循环或异步任务中，leave=False 和 position 决定是否“叠在一起”
两层 for 循环同时跑进度条，默认会抢占同一行，导致上层条被下层覆盖。这不是 bug，而是 tqdm 的默认行为：所有条共享标准输出流。要并排显示，必须干预位置管理。
- 外层加
leave=False，内层保持默认（leave=True），这样外层完成后自动清空，只留内层结果 - 显式指定
position：外层position=0，内层position=1，就能固定上下两行，互不干扰 - 注意：Jupyter 中
position有时失效，此时改用tqdm.notebook.tqdm替代基础版，它专为 notebook 的 cell 输出模型优化
