适用场景与准备思路

Weights & Biases 常用于AI实验跟踪、模型训练日志记录、参数对比、结果可视化和团队协作。

免费方案适合个人研究、小型项目验证、课程实验和开源模型复现实验等场景。

如果训练环境无法直接连接外部网络，或项目要求在封闭机房、内网服务器上运行，就需要提前准备离线安装包，并配置本地记录模式。待允许同步时，再上传项目数据。

离线安装的核心思路并不复杂：

• 先在一台可联网且系统架构一致的机器上下载Python依赖包。
• 再把安装包复制到目标环境，通过pip的本地安装参数完成部署。
• 随后在训练脚本中接入wandb，并设置离线模式。
• 最后导入AI工作流模板，统一实验命名、参数结构、指标记录和产物管理规则。

环境要求与安装包准备

环境要求

建议使用Python 3.8及以上版本。请提前确认目标机器的操作系统、CPU架构、Python版本与联网下载机器保持一致。

若目标环境使用Conda，建议新建独立环境，避免与已有深度学习框架依赖冲突。常见组合包括Python 3.10、PyTorch或TensorFlow、wandb最新版稳定包。

安装包准备

在联网机器上新建目录，例如 wandb_offline_pkgs，用于保存离线安装包。执行下载命令时，可指定完整依赖：pip download wandb -d wandb_offline_pkgs。

如果项目还需要PyTorch、Transformers、Datasets、Accelerate等组件，也应一并下载对应版本。例如：pip download transformers datasets accelerate -d wandb_offline_pkgs。

为了提高可复现性，建议生成 requirements.txt，将版本固定为 wandb==0.x.x 这类形式，避免不同时间下载到不一致的依赖。

完成下载后，检查目录内是否包含 .whl 或 .tar.gz 文件。将整个目录复制到目标服务器，可以使用U盘、内网文件传输工具或运维允许的文件分发方式。复制完成后，建议计算文件校验值，确认安装包没有损坏或被替换。

目标环境离线安装步骤

进入目标机器后，先创建干净环境。Conda用户可执行 conda create -n ai_wandb python=3.10，随后激活环境。若使用venv，可通过 python -m venv venv 创建，再进入对应环境。

安装前先升级本地pip并非必须。如果无法联网，可跳过该步骤。但要确保pip版本不低到无法识别新格式安装包。

进入离线包目录后，执行本地安装：pip install --no-index --find-links=./wandb_offline_pkgs wandb。参数 --no-index 表示不访问远程软件源，--find-links 用于指定本地包目录。

如果有 requirements.txt，可执行 pip install --no-index --find-links=./wandb_offline_pkgs -r requirements.txt。

安装完成后，用 python -c "import wandb; print(wandb.__version__)" 验证是否可正常导入。

若出现依赖缺失，通常说明联网下载阶段没有把所有依赖带齐。处理方式是在联网机器上重新使用 pip download -r requirements.txt -d wandb_offline_pkgs 补齐，再复制到目标环境。不要在生产训练环境临时混装未知来源文件，尤其是非官方渠道的安装包，这可能带来依赖污染与安全风险。

账号、项目与离线模式配置

账号与令牌准备

免费方案一般需要在可联网设备上创建个人账号，并获取访问令牌。目标环境完全离线时，不必立即登录，可以先使用离线模式记录实验。

离线模式配置

常用方式是在命令行设置环境变量 WANDB_MODE=offline，或在Python脚本中设置 os.environ["WANDB_MODE"]="offline"。这样训练记录会保存在本地 wandb 目录下，不会尝试连接远程服务。

基础接入示例

在训练脚本开头 import wandb，随后执行 wandb.init(project="demo-ai-workflow", name="baseline-run", config={"lr":0.0001,"batch_size":16,"epoch":10})。训练过程中使用 wandb.log({"loss":loss_value,"acc":acc_value,"step":global_step}) 记录指标。训练结束后调用 wandb.finish()，保证本地记录完整写入。

离线记录目录通常位于当前项目下的 wandb 文件夹，里面包含run信息、配置、日志和媒体文件。后续如果环境获得合规网络访问条件，可在安装好wandb并完成登录的机器上执行 wandb sync wandb/offline-run-xxxx，将离线结果同步到项目空间。

注意：同步前应先检查记录内容，删除不应上传的样本、路径、密钥或内部备注。

AI工作流模板导入方法

模板分类与结构

为了让实验更规范，建议把AI工作流拆成四类模板：训练配置模板、指标记录模板、产物归档模板和复现实验模板。

训练配置模板

训练配置模板通常是YAML或JSON文件，记录模型名称、数据路径、学习率、批次大小、随机种子、训练轮次等。导入方式是在脚本启动时读取配置文件，再将其传入wandb.init的config参数。

例如团队可以准备 workflow_train.yaml，字段包括project、run_name、model、dataset_version、hyperparameters、metrics、artifacts。脚本读取后自动创建项目记录，并按模板中的metrics列表统一记录train_loss、valid_loss、accuracy、f1等指标。这样不同成员提交的实验结果结构一致，便于后续比较。

产物归档模板

产物归档模板可用于管理模型权重、评估报告、配置快照等文件。使用 wandb.Artifact 创建产物对象，将模型文件、日志摘要、配置文件加入其中，再通过 run.log_artifact 提交。离线模式下同样会先写入本地，待同步时进入云端项目。

注意：免费方案通常存在资源额度和功能范围限制，不建议上传过大的中间文件；可只上传最佳权重、指标表和必要配置。

复现实验模板

复现实验模板建议固定随机种子、依赖版本、数据版本标识和启动命令。每次训练时，将这些信息写入config或summary，后续排查效果波动会更容易。对于课程或轻量团队项目，可建立templates目录，放置base_train.yaml、sweep_config.yaml、artifact_policy.yaml等文件，复制后按项目修改即可。

推荐工作流示例

一个较稳妥的离线工作流可以按以下顺序执行：

• 第一步：准备requirements.txt，并在联网机器下载完整离线包。
• 第二步：在目标环境创建独立Python环境，并本地安装。
• 第三步：将WANDB_MODE设为offline。
• 第四步：导入workflow_train.yaml，并启动训练。
• 第五步：在训练中记录关键指标和少量可视化结果。
• 第六步：训练结束后检查wandb目录。
• 第七步：在允许的环境中执行同步。
• 第八步：在项目页面查看不同run的参数、曲线和产物。

命名规则也很重要。建议run名称包含模型、数据版本和日期，例如 bert_cls_v2_202506。项目名称保持稳定，不要每次训练都新建项目。标签可用于区分baseline、debug、full-train、ablation等实验类型。这样即使免费方案下项目规模不大，也能保持清晰的实验台账。

常见问题与排查

• 问题一：安装时报No matching distribution found。通常是Python版本、系统架构或包版本不匹配，需要在相同平台重新下载安装包。
• 问题二：提示缺少依赖。说明pip download时没有覆盖requirements中的全部包，应补齐后再安装。
• 问题三：脚本运行时仍尝试联网。检查是否设置了WANDB_MODE=offline，也可在命令行执行 wandb offline 切换模式。
• 问题四：同步失败。先确认本地run目录完整，再确认已在同步机器上执行 wandb login。若项目名或实体空间不正确，可在sync命令中指定目标项目。
• 问题五：日志文件过大。可减少图片、音频、表格等大体积内容记录频率，或只记录验证集关键样本。
• 问题六：多人结果混乱。应统一项目名、run命名、config字段和标签，避免每个人自定义一套字段。

安全边界与实用建议

数据安全审查

离线部署不代表可以忽视数据安全。训练日志中可能包含样本路径、数据片段、模型输出、内部目录结构和运行参数。

同步前务必审查wandb目录，确认没有敏感数据、密钥、内部地址或不应公开的样本内容。

访问令牌应通过环境变量或安全配置注入，不要写死在脚本、模板或版本库中。

免费方案建议

对于免费方案，建议将其定位为实验管理和结果对比工具，而不是大文件长期存储空间。模型权重可以只保留关键版本，完整数据集应放在项目批准的存储位置，W&B中记录数据版本编号即可。

团队协作建议

团队协作时要设置最小必要权限，离职或项目结束后及时移除无关成员访问。

离线包维护

离线安装包要定期维护。每次升级wandb或深度学习框架前，先在测试环境验证训练脚本、模板导入、离线记录和同步流程，再更新正式环境。保留旧版安装包和requirements文件，出现兼容性问题时可快速回退。

只要把依赖、模板、命名和安全审查四件事做好，Weights & Biases在受限网络环境下依然能稳定支撑AI实验管理。