简介visdom-master.zip 是面向深度学习研究者与 PyTorch 开发者的可视化工具源代码包可用于训练过程监控、实验对比与数据展示适合希望了解 Visdom 内部实现或进行二次开发的中高级用户。压缩包共 45 个文件、约 715KB以 12 个 JavaScript 前端交互文件、7 个 Python 后端模块和 7 个 Markdown 说明文档为主并含 CSS、HTML 及项目配置示例便于从界面、服务端和文档三条线索理解整体结构。已有 2200 人学习下载说明其在实验可视化场景中具有较高参考价值。读者可借此梳理环境与窗口管理、图表/图像/文本等多类型数据展示、事件回调、布局组织及远程部署等机制并结合示例脚本体会与 PyTorch 训练曲线的联动方式为自定义面板、API 集成和功能扩展提供可复用的源码依据。1. 训练曲线看不清的时候visdom 是我愿意临时起一个进程的理由模型跑到第 30 个 epoch终端里 loss 一行行往上滚你想看的是它从哪一步开始抖而不是再翻 3000 行日志。visdom pytorch 这套组合的价值就在这种时刻一条python -m visdom.server浏览器打开 8097 端口训练循环里几行viz.line曲线当场长出来。visdom-master.zip 是这套可视化服务的完整源码包包含服务端、前端静态资源和 Python 客户端三部分。它适合两类人在没有端口映射的实验机上想快速看指标的以及需要把 loss、学习率、样本图、直方图放在同一屏里对照的。它不追求大屏看板追求的是进程起来就能看。2. 把 visdom 服务拉起来端口、宿主与 env 目录的三个开关拿到源码包的第一件事不是急着pip install而是先判断这台机器上有没有装过、装的是哪一版、能不能起来。visdom 的坑高度集中在依赖版本和监听地址这两处先把服务跑通后面写客户端才有意义。2.1 装之前先看清版本关系visdom 与 tornado 的绑定visdom 的服务端是一个基于 tornado 的 Web 应用前端是打包好的静态页面客户端是纯 Python 的 requests 封装。它对外部依赖不算多真正容易出问题的只有 tornado 这一条线tornado 跨大版本时会删改一些老 API而 visdom 的代码更新节奏慢装到不匹配的组合python -m visdom.server直接起不来报错往往出现在 import 阶段一眼看不出是谁的问题。我的习惯是先用 pip 装正式版起不来再去源码包里装。源码包的好处是可以直接翻setup.py和requirements.txt看清这个包声明的依赖区间而不是被 pip 解析出来的最新版牵着走# 方式一直接装发布版最省事 pip install visdom # 方式二从源码包装适合要改前端或排查依赖的情况 unzip visdom-master.zip -d /opt/ cd /opt/visdom-master pip install -e . # -e 是可编辑安装改完代码不用重装 # 装完先确认两件事visdom 自己的版本、tornado 的版本 python -c import visdom, tornado; print(visdom, visdom.__version__); print(tornado, tornado.version)pip install -e .的作用是把源码目录挂进环境后面如果你改了py/visdom/__init__.py里的默认参数不需要重新安装。python -c那一行打出来的两个版本号要记下来出问题时这是排查的起点。注意如果启动时报的是ImportError或AttributeError错误栈里出现tornado字样八成是版本区间不对。这时候不要盲降先看错误栈指向 tornado 的哪个模块再决定往下钉到哪个版本# 列出可选的 tornado 版本挑一个比当前低一个小版本的试 pip index versions tornado # 钉版本示例钉到一个较老的稳定线然后重新启动验证 pip install tornado6.1 python -m visdom.server提示钉版本这一步建议在虚拟环境里做别动系统 Python。visdom 的依赖树浅单独开一个 conda 或 venv 成本很低回滚的时候直接删环境。2.2 启动命令-port、-host、-env_path 怎么填服务端脚本的参数不多但每一个都对应一个真实场景。下面这张表是我自己常用的对照默认值按常见安装行为写具体以你那份源码里visdom/server.py的 argparse 定义为准参数常用取值什么时候必须改-port8097端口被占或多个人共用一台机器时各开一个-host0.0.0.0需要从别的机器访问只在本机看就留默认-env_path~/.visdom/不想把实验数据写在 home 下或 home 分区小-logging_levelWARNING长期挂着跑减少日志噪音-readonly无只想让别人看图不允许他们改面板-f/--force_new_start无上次异常退出留下状态文件起不来时强制重开对应的启动命令# 最常用的一条指定端口、对外监听、把 env 数据放到数据盘 python -m visdom.server \ -port 8097 \ -host 0.0.0.0 \ -env_path /data/visdom_env \ -logging_level WARNING-port决定了客户端Visdom(port...)要填什么两边必须一致-host 0.0.0.0是让服务监听所有网卡只在本机浏览器看的话可以不写安全性更好-env_path指向的目录是面板数据的落盘位置训练跑很久的话一定要放到容量够的盘上默认的 home 目录经常在几个月后被一堆 env 文件塞满。起来之后别急着开浏览器先用命令行确认服务真的在响应# 看端口有没有在监听 ss -lntp | grep 8097 # 看 HTTP 层能不能拿到页面返回 200 和一坨 HTML 就对了 curl -s -o /dev/null -w %{http_code}\n http://127.0.0.1:8097/ss那条能看到监听地址是0.0.0.0:8097还是127.0.0.1:8097这是后面远程连不连得上的关键curl返回200说明 HTTP 服务正常返回空或超时说明进程压根没起来回去看启动日志。2.3 远程机器上的三种连法改 host、端口转发、base_url最常见的场景是训练在实验室的机器上人在自己电脑前浏览器打开http://那台机器:8097一片白。原因几乎都是服务只绑了回环地址外面进不来。第一种做法是启动时加-host 0.0.0.0让服务监听所有网卡然后直接用机器地址访问。这种做法最省事但等于把这个端口暴露在网段里visdom 本身没有认证机制任何人连上都能看、能改、能关面板。内网临时用可以长期挂着不建议。第二种做法是保持默认监听用一条本地端口映射把远端端口搬到本机来# 在本地机器上执行把远端的 8097 映射到本地的 18097 ssh -N -L 18097:127.0.0.1:8097 userremote-host之后浏览器打开http://127.0.0.1:18097即可。-N表示只做转发不执行命令-L的格式是本地端口:目标地址:目标端口目标地址写127.0.0.1是站在远端机器的视角看自己。这种方式下服务端完全不用改配置安全性也好唯一的代价是多一条常驻连接。第三种是前面挂了反向代理、路径带了前缀的情况。此时服务端要加-base_url把前缀告诉它否则前端静态资源和 WebSocket 的地址都会拼错表现是页面能打开但一直转圈、面板刷不出来# 假设外部访问路径是 http://host/visdom/ python -m visdom.server -port 8097 -base_url /visdom/-base_url的值要和代理配置里的路径严格对齐多一个斜杠少一个斜杠都会出问题。这一条踩过一次就记住了页面白屏但curl能拿到 HTML先怀疑 base_url而不是怀疑服务没起来。3. 从一条 line 到一屏面板客户端 API 的调用顺序服务通了接下来是客户端。visdom 的 Python 客户端用起来很像画图工具但它的状态是存在服务端的本地只有一个连接对象。理解这一点很多为什么我的曲线不更新的问题就自动有答案了。3.1 Visdom() 对象与 env连接期的四个参数客户端对象建议在训练脚本入口处创建一次然后一路传下去。不要在每个 batch 里新建Visdom()那样每次都会重新握手、重新拉一遍窗口状态训练慢了不说还容易把服务端连接数打满。import visdom viz visdom.Visdom( serverhttp://127.0.0.1, # 只写协议和主机不要带端口 port8097, # 端口单独给和 server 参数分开 envexp-lr1e-3, # 一个实验一个 env面板互不干扰 use_incoming_socketFalse, # 不订阅服务端推送网络抖动时更稳 raise_exceptionsTrue, # 连不上直接抛异常不要静默失败 )四个参数逐个说。server只填协议加主机端口必须写在port里这是新手最容易翻车的地方——写成serverhttp://127.0.0.1:8097再加port8097拼出来的地址会变成两段端口请求直接打空。env是面板分组本质上是服务端的一组窗口集合每个 env 对应-env_path目录下的一个数据文件。做对照实验时一组超参一个 env浏览器右上角切一下就能对比比在同一个面板里塞二十条线清楚得多。use_incoming_socketFalse关掉的是客户端对服务端推送的订阅。关掉之后面板不会自动刷新别人的改动但你自己的line调用照样生效。训练机网络不稳的时候这个开关能省掉一类莫名其妙的卡顿。raise_exceptionsTrue是我强烈建议开的。默认情况下客户端连不上服务端只会往 stdout 打一句 Visdom is down然后所有绘图调用静默返回你的训练照跑曲线一条没有——这个坑能让人浪费半小时。3.2 line 的 append 与 replaceX/Y 形状决定成败line是使用频率最高的接口也是形状要求最严的一个。它的核心规则只有一条Y是二维数组形状(N, M)N是本次写入的点数M是曲线条数X是一维或(N, 1)长度必须等于N。import numpy as np # 第一次调用创建面板并写入第一个点 viz.line( Ynp.array([[0.92, 0.88]]), # (1, 2)1 个 steptrain 和 val 两条线 Xnp.array([0]), # (1,)横坐标 winloss, # 面板 id后续靠它找回同一个面板 optsdict( titletrain / val loss, legend[train, val], xlabelepoch, ylabelloss, ), ) # 后续每个 epoch同名 win updateappend viz.line( Ynp.array([[0.71, 0.74]]), Xnp.array([1]), winloss, updateappend, )win是面板的唯一标识第一次调用时它同时承担创建和命名两个职责之后所有更新都要带同一个win。opts里的legend长度必须和M对齐两条线配三个图例前端只会显示前两个第三个位置一直是空的。update的取值决定这次写入的语义用错了表现完全不同update取值语义典型场景不传用这批数据覆盖整个面板初始化或想清空重画append在末尾追加 N 个点训练曲线逐步累积replace保留面板配置替换全部数据定长滑动窗口防止点数无限增长insert从头部插入 N 个点时间倒序的滚动窗口还有一个隐性规则update只能用在已经存在的win上。如果进程重启后直接调append而服务端没有这个面板visdom 会新建一个此时第一个点的横坐标可能落在奇怪的位置看起来像曲线少了一截。稳妥做法是启动时先判断面板在不在# 进程重启后先探测面板是否还在决定是初始化还是续写 if not viz.win_exists(loss, envexp-lr1e-3): viz.line(Ynp.array([[0.0, 0.0]]), Xnp.array([0]), winloss, optsdict(titletrain / val loss, legend[train, val]))win_exists会真的发一次请求到服务端返回布尔值。多这一次请求换来的是重启训练时曲线不会断成两段。3.3 image、text、histogram数据形状与取值范围除了曲线最常用的三类面板是图像、文本和直方图。它们的接口都很短坑全在数据形状和值域上。# 图像期望 (C, H, W) 的 float取值范围 0~1 img tensor.detach().float().clamp(0, 1).cpu().numpy() # (3, 224, 224) viz.image(img, winsample, optsdict(titleinput, captionstep 1200)) # 一批图像期望 (B, C, H, W)前端会拼成网格 viz.images(batch.detach().float().clamp(0, 1).cpu().numpy()[:8], nrow4, winbatch, optsdict(title8 samples)) # 文本直接给字符串用来贴当前超参配置 viz.text(lr1e-3 bs64 warmup500, wincfg, optsdict(titleconfig)) # 直方图一维数组用来观察权重分布有没有塌 viz.histogram(w.detach().float().cpu().numpy().ravel(), winw_hist, optsdict(numbins50, titleconv1 weight))图像这块有两个必踩的坑。一是值域visdom 的 image 期望0~1的浮点如果你把0~255的 uint8 数组直接丢进去结果是一片惨白反过来把0~1的浮点当0~255处理就是一片全黑。二是通道顺序(H, W, C)的数组要先transpose(2, 0, 1)否则颜色会整个错乱红蓝互换是最典型的症状。viz.text很适合放超参快照训练开始写一次浏览器里就有个固定角落告诉你这次跑的是什么配置比翻命令行历史省事。viz.histogram我一般每几百步看一次权重分布numbins给 50 左右足够看出形状给太大会让前端渲染变慢。4. 把可视化埋进训练循环一个 60 行的 VisdomLogger直接在每个 batch 里写viz.line(...)的脚本跑到第二个项目就没人愿意维护了。把可视化和训练逻辑拆开是我做完第三个项目后固定下来的习惯。4.1 埋点节奏每个 step 记什么、每个 epoch 记什么先说频率。loss 这类标量如果按 step 记一个 epoch 5000 步、跑 200 个 epoch 就是一千万个点前端渲染会先崩你的浏览器会先卡死。我的经验是step 级别只做累加和滑动平均写入服务端的频率压到每 2050 步一次epoch 级别的验证指标一步不落。学习率这种变化缓慢的量每个 step 记一次纯属浪费跟着 loss 的节奏一起写就行。样本图像更奢侈每 5001000 步放一张足够看出训练有没有崩每个 step 都传网络带宽和 CPU 都会先扛不住。这套节奏下来一个跑 8 小时的训练任务写入服务端的点数大概在几万个量级浏览器的 line 面板撑得住同时曲线又足够看出抖动。4.2 封装VisdomLogger 的构造与 update_loss下面这个类是我在多个项目里改出来的版本核心是把面板初始化和数据写入分开初始化只做一次写入走统一入口。import numpy as np import visdom class VisdomLogger: 把 visdom 的连接、面板初始化和写入节奏收在一处。 def __init__(self, env, serverhttp://127.0.0.1, port8097, scalar_every20, image_every500): self.viz visdom.Visdom( serverserver, portport, envenv, use_incoming_socketFalse, raise_exceptionsTrue, ) self.env env self.scalar_every scalar_every # 标量写入降频间隔 self.image_every image_every # 图像写入降频间隔 self.step 0 self._inited set() # 已初始化的面板名避免重复建 def _ensure_line(self, win, title, legendNone): # 首次遇到这个 win 时建面板之后只 append if win in self._inited: return self.viz.line( Ynp.zeros((1, len(legend) if legend else 1)), Xnp.zeros(1), winwin, optsdict(titletitle, legendlegend), ) self._inited.add(win) def log_scalar(self, name, value, titleNone, legendNone): # 非关键 step 直接丢弃控制服务端压力 if self.step % self.scalar_every ! 0: return self._ensure_line(name, title or name, legend) y np.array([[value]]) if np.isscalar(value) else np.array([value]) self.viz.line(Yy, Xnp.array([self.step]), winname, updateappend) def log_image(self, tensor, winsample, titlesample): if self.step % self.image_every ! 0: return # detach cpu clamp 三件套缺一个都可能出问题 img tensor.detach().float().clamp(0, 1).cpu().numpy() self.viz.image(img, winwin, optsdict(titletitle, captionfstep {self.step})) def tick(self): self.step 1构造里的scalar_every和image_every是两个节奏旋钮前者控制曲线密度后者控制图像流量。_inited这个集合看起来多余实际很关键不做判重的话同名win反复走初始化分支会把已经累积的曲线整个覆盖掉表现就是曲线每隔一会儿重置一次。log_scalar里的np.isscalar(value)分支处理的是单值和多值两种情况。传单个 float 时包成(1, 1)传[train_loss, val_loss]这样的列表时包成(1, 2)两者都能被line正确接收。注意Y必须显式转成二维一维数组会被当成单点的多条线横坐标对不上。log_image里的.detach().float().clamp(0, 1).cpu().numpy()这一串每一个都有必要detach断开计算图不然显存会一直被这批图占着float统一类型clamp把归一化后的越界值压回0~1cpu是因为 visdom 不接受 GPU 上的张量。4.3 接进训练循环三行改动封装好之后训练脚本里的改动很小logger VisdomLogger(envexp-lr1e-3, scalar_every20, image_every500) for epoch in range(num_epochs): for batch in loader: loss train_step(batch) logger.log_scalar(loss, loss.item(), titletrain loss) logger.log_image(batch[img][0], winsample, titleinput sample) logger.tick() val_loss, val_acc evaluate(model, val_loader) logger.log_scalar(val, [val_loss, val_acc], titleval metrics, legend[loss, acc]) logger.tick()这里有个细节log_scalar内部会检查step % scalar_every所以调用方不用再判断直接每次丢进去即可降频逻辑集中在 logger 里。验证阶段用的log_scalar传的是列表配合legend就能在一个面板里画两条线前提是这两条线的量纲接近——loss 和 accuracy 放在一起会很难看实际项目里我一般拆成两个面板。tick()单独抽出来而不是放在log_scalar里自增是因为有些 step 你只想记图像不想记标量共用计数器会让节奏错乱。这个设计不算优雅但足够直观接手的人看一眼就懂。5. 五条踩坑复盘连不上、曲线堆点、面板越开越多这一节按现象 → 原因 → 解决的顺序把我在实际项目里重复遇到过的五次翻车记下来。这些问题有一个共同点报错信息都极少甚至不报错全靠观察。5.1 连接类连不上和连上了没反应现象一浏览器打开一片白curl也返回空。原因通常是服务压根没起来或者起在了别的端口上。启动日志里如果出现Address already in use说明 8097 被上一次没退干净的进程占着。解决办法是先查占用再决定是杀掉还是换端口ss -lntp | grep 8097 # 看清是谁占着 kill -9 pid # 确认是残留的 visdom 进程后再杀 python -m visdom.server -port 8098 # 或者干脆换一个端口现象二客户端不报错浏览器里一个面板都没有。原因是raise_exceptions默认是False连接失败的信息只打印一句 Visdom is down后面的绘图调用全部空转训练照常结束。解决办法是在构造时显式打开异常让它在第一次调用就炸出来viz visdom.Visdom(serverhttp://127.0.0.1, port8097, envdebug, raise_exceptionsTrue)打开之后常见的报错就两种ConnectionError说明服务没起或端口不通URL 拼错说明server参数里带了端口。后者改一下参数即可。5.2 数据类形状不对导致的曲线异常现象三append 之后曲线上所有点挤在 x0或者只剩一条竖线。这是 X 的形状问题。X必须是长度为 N 的数组如果你传了一个标量0而不是np.array([0])visdom 会把它当成单点处理后续 append 的横坐标全部落在同一个位置。# 错误标量服务端收到的是单点 viz.line(Ynp.array([[0.5]]), X0, winloss, updateappend) # 正确显式包成数组 viz.line(Ynp.array([[0.5]]), Xnp.array([1]), winloss, updateappend)还有一种情况是第一次调用就带了updateappend此时面板还不存在服务端新建后横坐标基准是空数据历史点自然对不齐。解决办法就是 3.2 节那段判断先用不带update的调用把面板建出来。现象四图像面板全黑或全白。值域问题。viz.image期望0~1的浮点传0~255的 uint8 会全都超过 1被裁成白色反过来把0~1的浮点用*255转成整数再传会全部贴近 0看起来是全黑。解决方式是统一在写入前做一次归一化和钳制img tensor.detach().float() if img.max() 1.5: # 判断是 0~255 还是 0~1 img img / 255.0 img img.clamp(0, 1).cpu().numpy() viz.image(img, winsample)5.3 运行类面板复用与长时间运行现象五重启训练进程后面板数量翻倍旧面板还挂着上一次的曲线。原因是每次启动用了新的win名比如把时间戳拼进了win或者换了env导致同名win落在不同分组里前端看起来就是两套。解决办法是win名保持稳定用loss、val、sample这种固定名启动时先探测再决定续写还是重建WIN loss if viz.win_exists(WIN, envexp-lr1e-3): # 面板还在接着写如果数据太旧可以先 close 再建 pass else: viz.line(Ynp.zeros((1, 1)), Xnp.zeros(1), winWIN, optsdict(titletrain loss))现象六跑了两三个小时后浏览器卡得动不了。原因是 line 面板的点数没有上限加上图像面板每个 step 都在传。解决办法是两条标量写入降频第 4 章那个scalar_every曲线点数超过阈值就用replace截断成定长窗口MAX_POINTS 2000 def log_line_windowed(viz, win, x, y, xs, ys): 超过上限就整体重写只保留最近 MAX_POINTS 个点。 xs.append(x); ys.append(y) if len(xs) MAX_POINTS: xs, ys xs[-MAX_POINTS:], ys[-MAX_POINTS:] viz.line(Ynp.array(ys).reshape(-1, 1), Xnp.array(xs), winwin, updatereplace) else: viz.line(Ynp.array([y]).reshape(1, -1), Xnp.array([x]), winwin, updateappend)这里用 Python 列表在客户端维护窗口服务端只负责渲染。代价是重启后历史丢失换来的是浏览器不会卡死——长时间训练的场景下这个交换是值得的。注意env_path下的数据文件是追加的删面板不会释放磁盘。跑了几十次实验之后记得定期清理不再需要的 env 文件否则某天会发现 home 分区满了而训练任务因为这个原因挂掉。6. 进阶用 env 做实验分组用日志文件做离线复现到这一步服务能跑、曲线能画、坑也踩过了剩下的是怎么让它长期可用。我自己的做法是三条纪律。第一条是一个实验一个 envenv 名带超参信息比如exp-lr1e-3-bs64。visdom 的前端右上角可以切 env做对照实验时同一个模型的两组超参并排看比在同一个面板里画十条线清楚得多。env 的数据落在-env_path指定的目录下每个 env 一个文件格式是 JSON出问题时可以直接打开看里面存了哪些窗口、每个窗口多少数据点。env 命名用途保留策略exp-lr1e-3-bs64正式对照实验保留到论文/报告定稿debug-tmp调代码时的临时面板每次启动前清空paper-fig3出图用的复现实验长期保留单独备份第二条是给客户端加日志落盘。Visdom的构造参数里有一个可以指定日志文件路径的选项打开之后每次绘图调用都会被记录成一行包括接口名、窗口名和数据。这个文件的价值在于训练跑完、服务关掉、env 文件删了你还能拿它重放出当时的面板。做法是给第 4 章那个 logger 加一个参数# 把每次绘图调用记到文件之后可以脱离服务和 GPU 重放 viz visdom.Visdom( serverhttp://127.0.0.1, port8097, envexp-lr1e-3, raise_exceptionsTrue, log_to_filename/data/visdom_logs/exp-lr1e-3.log, )日志文件是纯文本一行一次调用体积很小。重放的时候起一个新的服务、把日志喂回去就能在没有训练环境、没有原始数据的机器上把当时的曲线完整还原出来。写报告、做复盘、给同事演示的时候这个能力省下的沟通成本很高。第三条是关键指标双写。visdom 挂了不要紧但如果 loss 只存在 visdom 里服务一崩你就只剩终端日志。所以我的 logger 里总会多一个 CSV 写入的分支把step, train_loss, val_loss, lr这些字段同步写一份。CSV 的好处是任何工具都能读画图、算统计、贴到别的地方都不挑环境。这份 CSV 就是后悔药平时用不上出问题那天能救命。最后说一个验证方法每接一个新项目先跑 20 步的假数据烟测。用一个只产生随机数的循环把 logger 的每个接口都调一遍确认面板能建、曲线能 append、图像不是全黑再上真模型。这个习惯是踩过一次坑之后强制加上的——那次是训练跑完 8 小时才发现env名多打了一个空格所有面板都建在一个看不见的分组里白跑。从那以后我每次接新项目都强制先用假数据把可视化链路走通一遍五分钟换八小时很值。希望帮到你。本文还有配套的精品资源点击获取