工具定位与安装前准备
Weights & Biases，常简称 W&B，是机器学习实验管理、指标可视化、模型版本记录和团队协作工具。它并不是传统意义上必须部署在本机的“单体软件”，常见用法是在 Ubuntu 服务器上安装 Python SDK 与命令行工具，将训练日志、超参数、模型文件等同步到可视化控制台。对做深度学习训练、微调大模型、对比多组实验结果的团队来说，它能显著减少手工记录表格和截图的工作量。
安装前建议确认三件事：第一，服务器系统建议为 Ubuntu 20.04、22.04 或更新的长期维护版本；第二，Python 版本建议为 3.8 及以上，项目依赖最好放在虚拟环境中，避免污染系统环境；第三，服务器需要能访问 W&B 服务端地址，否则日志无法正常同步。如果企业有内网部署需求，应先确认是否具备相应授权和部署包，不要把云端 SDK 安装误解为完整后台系统安装。
更新系统并安装基础依赖
使用具有管理权限的账号登录 Ubuntu 服务器后，先更新软件索引并安装常用工具。可执行：sudo apt update && sudo apt upgrade -y，随后安装 Python、pip 和虚拟环境模块：sudo apt install -y python3 python3-pip python3-venv git curl。如果服务器上同时存在多个 Python 版本，建议通过 python3 --version 和 pip3 --version 确认当前调用的是预期版本。
生产训练环境不建议直接使用系统级 pip 安装所有包。更稳妥的做法是在项目目录创建虚拟环境，例如：mkdir -p ~/ai-projects/wandb-demo && cd ~/ai-projects/wandb-demo，再执行 python3 -m venv .venv，启用环境：source .venv/bin/activate。命令行前出现 (.venv) 后，再安装项目依赖，后续卸载或迁移会更清晰。
安装 Weights & Biases SDK
在虚拟环境中执行：pip install --upgrade pip，然后安装 W&B：pip install wandb。安装完成后可运行 wandb --version 检查命令是否可用。如果命令不存在，通常是虚拟环境未启用，或 pip 安装到了另一个 Python 环境。可用 which python、which pip、which wandb 对照路径。
部分训练项目还会用到 PyTorch、Transformers、Datasets 等依赖，这些并不是 W&B 的必需组件，应按具体项目安装。对于多人共用的服务器，建议每个项目使用独立虚拟环境，避免某个项目升级依赖后影响其他训练任务。
登录账号与配置 API Key
W&B SDK 需要通过 API Key 识别用户或团队空间。命令行登录方式为：wandb login，随后粘贴在控制台生成的 API Key。登录成功后，认证信息通常会保存到当前用户目录下的配置文件中。服务器多人共用时，不建议把个人密钥写入公共脚本或共享镜像，更不要提交到代码仓库。
如果是自动化训练任务，可使用环境变量传入：export WANDB_API_KEY=你的密钥。在任务调度系统中，也应使用密钥管理能力或受限权限的环境变量配置。对于不希望立即同步到线上控制台的调试场景，可以设置离线模式：export WANDB_MODE=offline，训练结束后再根据需要同步。若只想临时禁用记录，可设置：export WANDB_DISABLED=true。
运行一个最小测试任务
安装完成后，建议先用最小脚本验证链路。创建 test_wandb.py，内容思路是初始化一个项目，记录几轮指标，然后结束运行。核心代码可写为：import wandb; run=wandb.init(project="ubuntu-wandb-demo"); [wandb.log({"loss": 1/(i+1), "step": i}) for i in range(10)]; run.finish()。保存后执行：python test_wandb.py。
如果终端输出中间出现 run 地址，说明本机 SDK、认证信息和网络连通基本正常。打开该地址即可查看曲线、运行参数、系统信息和日志。对于正式训练脚本，只需在训练开始处调用 wandb.init()，在每个训练周期或固定步数调用 wandb.log()，即可把损失值、准确率、学习率等指标记录下来。
后台管理入口说明
很多用户搜索“后台管理入口”时，容易把 W&B SDK 和服务端后台混在一起。若使用官方云端服务，Ubuntu 服务器只负责运行训练代码和上传日志，管理入口在浏览器控制台中，通常从 W&B 官网登录后进入工作区、项目和运行详情页。项目地址一般呈现为 https://wandb.ai/团队或用户名/项目名 的形式，具体以控制台实际显示为准。
云端控制台可完成项目查看、运行对比、图表面板、报告整理、成员协作、权限设置等操作。普通训练服务器上安装 wandb 包后，本地不会自动生成一个可访问的管理后台，也不会默认开放 Web 端口。因此，如果在服务器 IP 后尝试访问某个端口却没有页面，这是正常现象，并不代表 SDK 安装失败。
如果企业采用自托管版本，后台入口取决于部署方式、域名和反向袋里配置。常见方式是通过管理员提供的实例地址访问，例如 https://wandb.example.com，再由具备权限的账号进入管理区域。部分版本可能提供系统管理路径或页面内管理员入口，具体应以部署文档和安装完成后的提示为准。自托管环境还需要额外关注对象存储、数据库、队列、证书、备份和版本升级策略，不能只安装 Python SDK 就视为服务端部署完成。
常见问题与排查方法
第一，执行 wandb login 后仍提示未认证。可检查当前运行训练的系统用户是否与登录用户一致，尤其是使用 sudo、定时任务或任务调度平台时，配置文件目录可能不同。建议尽量不要用 sudo python train.py 启动训练，而是在普通用户环境中配置好依赖和密钥。
第二，训练能运行但控制台没有数据。先查看终端是否显示离线模式、禁用模式或同步失败提示；再确认脚本中是否调用了 wandb.log()，以及项目名、团队空间是否写对。离线模式下会在本地生成记录目录，需后续执行同步命令才会出现在控制台。
第三，安装时报编译错误。通常与 pip 版本过旧、Python 版本不匹配或底层依赖缺失有关。可先升级 pip，并确认使用受支持的 Python 版本。若项目依赖较多，建议用 requirements 文件固定版本，避免每次部署解析出不同依赖。
第四，页面能打开但图表延迟。大型训练可能高频记录指标、图片或模型文件，导致同步压力较大。建议降低日志频率，例如每几十步记录一次核心指标，大文件按阶段保存，避免把无关中间文件全部上传。
安全边界与实用建议
W&B 适合记录实验指标、配置、模型产物和可公开协作的信息，但不应上传包含敏感数据的原始样本、内部密钥、访问凭据或未脱敏日志。训练脚本中如果会打印环境变量、配置文件内容，应先检查是否含有不该外传的信息。团队项目还要合理设置成员权限，区分只读、编辑和管理角色。
在服务器运维层面，建议为训练任务创建专用 Linux 用户，虚拟环境、缓存目录和输出目录都放在该用户空间内；API Key 定期轮换，人员离开项目后及时移除权限；重要项目开启统一命名规范，例如 模型名-数据版本-实验目标，方便后续检索。对于长期训练任务，可结合 tmux、systemd 或作业调度工具保持进程稳定，但要注意日志目录和磁盘空间，避免训练未结束时本地缓存占满分区。
总体来看，在 Ubuntu 服务器上使用 Weights & Biases 的核心流程并不复杂：准备 Python 环境，安装 SDK，完成登录，运行测试脚本，再进入控制台查看结果。真正影响使用效果的，往往是项目命名、日志频率、权限配置和数据边界。把这些规则在团队内提前约定好，才能让实验管理从“能跑起来”进一步变成“可追踪、可复现、可协作”。
