企业官网建设流程全解析

• NLP

本指南是微软开源项目nlp-recipes（Natural Language Processing Best Practices & Examples）的官方环境搭建手册 SETUP.md 的中文深度解读。文章围绕"如何跑通仓库内全部 Jupyter notebook"这一核心目标，完整覆盖 Python CPU / Python GPU 两种 conda 环境的生成与安装、Apex 混合精度训练、Jupyter kernel 注册、utils_nlp工具包安装以及 NVIDIA Docker 镜像构建，并逐层结合仓库源码说明底层实现原理。读完本文，你将能够在一台裸机、云端数据科学虚拟机或 Docker 容器中，从零搭建出可运行 nlp-recipes 全部示例的深度学习环境。

一、SETUP.md 在仓库中的定位

nlp-recipes 是一个以"自然语言处理最佳实践与示例"为目标的仓库，其主体内容是 examples 目录下覆盖文本分类、命名实体识别、文本摘要、蕴含推理、问答、句间相似度、词向量、情感分析等场景的 Jupyter notebook，以及支撑这些示例的 utils_nlp 工具库。绝大多数算法依赖深度神经网络与预训练 Transformer 模型（BERT、XLNet、RoBERTa、ALBERT、UniLM 等），因此环境依赖较重。

仓库根目录的 README.md 在Getting Started一节中明确引导用户先阅读 SETUP.md 完成环境配置，再进入示例。SETUP.md 是仓库唯一的官方环境搭建入口文档，其内容可以概括为三条主线：

1. 本地/虚拟机环境：用 conda 管理依赖，环境文件由仓库脚本自动生成；
2. 云端环境：Azure DSVM 与 Azure ML Notebook VM 两种托管工作站；
3. 容器环境：通过 NVIDIA Docker 构建自带全部依赖的镜像。

文档在开头给出了两条重要的环境选型建议：

• 推荐运行环境是 Azure 数据科学虚拟机（DSVM）：由于相当数量的算法依赖深度学习，建议选用GPU 型 DSVM；
• 当需要大规模训练、模型运营化（operationalization）或超参数调优时，推荐使用 Azure ML（Azure 机器学习服务），这一建议与仓库内大量*_azureml.ipynb示例相对应。

二、计算环境选择：Python CPU 与 Python GPU

根据待运行的 NLP 系统和具体 notebook 的不同，计算需求差异很大。SETUP.md 明确指出，当前仓库支持两类环境：

• Python CPU 环境：适用于轻量任务、推理演示与资源受限机器；
• Python GPU 环境：适用于训练 Transformer 等大规模深度模型。

两种环境的 conda YAML 文件都可以通过下文介绍的generate_conda_file.py脚本一键生成，CPU 与 GPU 环境的核心差异在于 PyTorch 的安装方式与 cudatoolkit 的引入。仓库的持续集成也遵循这一划分：例如 tests/ci/cpu_unit_tests_linux.yml 中即通过source activate nlp_cpu激活 CPU 环境后运行pytest tests/unit。

三、可选的云端工作站：Azure ML Notebook VM

如果希望完全跳过本地安装，SETUP.md 推荐了Azure Machine Learning service 的 Notebook VM——一个专为数据科学家打造的云端工作站。其特点包括：

• 直接集成在 Azure Machine Learning 服务中，为 Python 开发者提供"代码优先"（code-first）的体验，可以在工作区内便捷地构建和部署模型；
• 数据科学家可在熟悉的 Jupyter notebook 界面中完成 Azure ML Python SDK 支持的全部操作，运行于安全、企业级的环境中；
• 预配置了机器学习所需环境，安全且易于使用，支持完全自定义。

创建好 Notebook VM 后，直接在其终端中按下一节"本地或虚拟机环境搭建"的步骤操作即可，无需任何额外改动。

四、本地或虚拟机环境搭建（核心章节）

4.1 环境要求

SETUP.md 给出的硬性前提如下：

⚠️ 注意：SETUP.md 明确提示Windows 机器不被完全支持（NOT FULLY SUPPORTED），使用风险自负。

4.2 依赖设置原理：generate_conda_file.py 源码解析

仓库提供了一个一键脚本 tools/generate_conda_file.py，用于生成包含全部正确依赖的 conda 环境 YAML 文件。该脚本本身是一个值得细读的源码，其核心设计如下：

命令行参数（tools/generate_conda_file.py）：

channels 与依赖包组织：脚本固定使用defaults、conda-forge、pytorch三个 channel（L33）。依赖被组织为"conda 基础包"（CONDA_BASE）、"conda GPU 包"（CONDA_GPU）、"pip 包"（PIP_BASE）以及按平台区分的DARWIN/LINUX/WIN32系列字典。关键版本约束如下：

• CONDA_BASE 核心依赖：python==3.6.8、pip>=19.1.1、ipykernel>=4.6.1、jupyter>=1.0.0、matplotlib>=2.2.2、numpy>=1.13.3、pandas>=0.24.2、pytest>=3.6.4、pytorch-cpu>=1.0.0、scipy>=1.0.0、h5py>=2.8.0、tensorflow==1.15.0、tensorflow-hub==0.7.0、dask[dataframe]==1.2.2、papermill==1.2.1；
• CONDA_GPU 追加依赖：pytorch==1.4.0、cudatoolkit=10.1（可被--cuda_version覆盖）、numba>=0.38.1；
• PIP_BASE 关键包：transformers==2.9.0（Hugging Face）、spacy==2.1.8、gensim>=3.7.0、nltk>=3.4、seqeval>=0.0.12、allennlp==0.8.4、azureml-sdk[automl,notebooks,contrib]==1.0.85、pytorch-pretrained-bert>=0.6、torchtext>=0.4.0、pyrouge、indic-nlp-library以及用于摘要场景的s2s-ft（以-e git+...形式从源码安装）。

平台分支逻辑（L162-L181）：脚本通过sys.platform判断darwin/linux/win32，为不同平台追加对应依赖；Windows GPU 环境会额外指定pytorch==1.0.0与cuda90。若平台不支持，脚本会抛出Unsupported platform异常。

YAML 输出结构：脚本生成的 YAML 文件包含name、三个channels、dependencies（conda 包 + 嵌套pip:段），并在文件头注释中写入conda env create/conda env update/ Jupyter kernel 注册三条提示命令。

仓库还提供了姊妹脚本 tools/generate_requirements_txt.py，它复用generate_conda_file.py中定义的各依赖字典，将全部依赖去重后输出为requirements.txt，供非 conda 场景使用。

4.3 安装默认（Python CPU）环境

假设仓库已克隆到本机并命名为nlp-recipes，安装 CPU 环境的完整流程为：

cd nlp-recipes python tools/generate_conda_file.py conda env create -f nlp_cpu.yaml

执行后会在仓库根目录生成nlp_cpu.yaml，并创建名为nlp_cpu的 conda 环境。若想自定义环境名，可使用-n标志：

python tools/generate_conda_file.py -n my_env_name

注意：环境名会同时作为输出 YAML 的文件名（源码 L143-L149 中，--gpu默认环境名为nlp_gpu，CPU 默认环境名为nlp_cpu，--name可覆盖两者）。

4.4 安装 Python GPU 环境

GPU 环境的安装关键在于分清 CUDA 驱动（driver）版本与 CUDA 运行时（runtime）版本，两者是不同的概念：

• driver 版本：由显卡驱动提供，是整个 CUDA 体系的"天花板"；
• runtime 版本：指 conda 环境中安装的cudatoolkit版本，必须 ≤ driver 版本。

步骤 1：查看 CUDA driver 版本

nvidia-smi

输出顶部即显示 driver 版本。例如：

+-----------------------------------------------------------------------------+ | NVIDIA-SMI 410.79 Driver Version: 410.79 CUDA Version: 10.0 | +-----------------------------------------------------------------------------+

步骤 2：确定应安装的 CUDA runtime 版本

runtime 版本（即下一步安装的 cudatoolkit 版本）应 ≤ 步骤 1 查到的 driver 版本。当前仓库使用的PyTorch 1.4.0兼容 cuda 9.2 与 cuda 10.1；脚本生成的 GPU 环境默认安装cudatoolkit 10.1。若 driver 版本 < 10.1，则调用脚本时需追加--cuda_version 9.2。

步骤 3：安装 GPU 环境

• 当 CUDA driver 版本 ≥ 10.1 时：

cd nlp-recipes python tools/generate_conda_file.py --gpu conda env create -n nlp_gpu -f nlp_gpu.yaml

• 当 CUDA driver 版本 < 10.1 时：

cd nlp-recipes python tools/generate_conda_file.py --gpu --cuda_version 9.2 conda env create -n nlp_gpu -f nlp_gpu.yaml

--cuda_version参数在源码中直接改写CONDA_GPU["cudatoolkit"]（L156），从而精确控制 YAML 中的 cudatoolkit 版本。

步骤 4（可选）：启用混合精度训练（mixed precision training）

混合精度训练对训练时间较长的模型尤其有价值，通常可将训练时间缩短约 50%，同时保持模型质量不变（此结论来自原文档说明，实践中结果会随模型与数据有所不同）。启用方式为在nlp_gpu环境中安装 NVIDIA 的 Apex 库：

conda activate nlp_gpu git clone https://github.com/NVIDIA/apex.git cd apex pip install -v --no-cache-dir --global-option="--cpp_ext" --global-option="--cuda_ext" ./

故障排查：若出现RuntimeError: Cuda extensions are being compiled with a version of Cuda that does not match the version used to compile Pytorch binaries.，说明nvcc（CUDA 编译器驱动）版本与 cudatoolkit runtime 版本不一致。用nvcc -V检查 nvcc 版本：

nvcc -V

若 nvcc 版本为 10.0，建议升级到 10.1，并以cudatoolkit=10.1重新创建 conda 环境。

升级 CUDA driver 与 nvcc 的参考步骤（原文档中经过验证的流程）：

a. 更新 apt 并重启机器：

sudo apt-get update sudo apt-get upgrade --fix-missing sudo reboot

b. 从 NVIDIA 官网下载目标平台的 CUDA toolkit.run文件。例如 Ubuntu 16.04 的 Linux 机器可使用：

wget https://developer.nvidia.com/compute/cuda/10.1/Prod/local_installers/cuda_10.1.105_418.39_linux.run

c. 执行安装（先接受用户协议；若已安装 418.39 驱动与 CUDA 10.1 但 nvcc 为 10.0，可取消勾选 "DRIVER" 仅重装 CUDA toolkit 以升级 nvcc；若选择安装全部组件，则先按屏幕提示卸载现有 NVIDIA 驱动与 CUDA toolkit 后再重跑安装命令，并在提示时选择 "Yes" 更新 CUDA symlink）：

sudo sh cuda_10.1.105_418.39_linux.run

d. 重新运行nvidia-smi与nvcc -V，确认 NVIDIA driver 418.39、CUDA driver 10.1 与 nvcc 10.1 三者就绪；

e. 重复上述"步骤 3 & 4"，以 cudatoolkit runtime 10.1 重建 conda 环境并安装 Apex，即可启用混合精度训练。

五、将 conda 环境注册为 Jupyter kernel

创建好的 conda 环境需要注册为 Jupyter kernel 才能在 notebook 中选用。SETUP.md 给出的通用命令为：

conda activate my_env_name python -m ipykernel install --user --name my_env_name --display-name "Python (my_env_name)"

在 DSVM 上，可通过浏览器访问https://your-vm-ip:8000连接 JupyterHub（若提示输入用户名密码，使用登录虚拟机的账号密码即可）。Jupyter 相关依赖（jupyter、ipykernel）已包含在generate_conda_file.py生成的依赖清单中，无需额外安装。

六、安装 utils_nlp 工具包

6.1 开发模式安装（pip install -e .）

仓库根目录提供了 setup.py，用于将utils_nlp工具包安装为 Python 包，供 examples 下的示例 notebook 直接导入使用。从仓库根目录执行：

pip install -e .

-e（editable，开发模式）的含义是：以源码形式安装，对utils_nlp源码目录的任何修改都会立即反映到已安装的包中，无需重新安装——对持续更新的工具库非常实用。

从 setup.py 源码可以看到，该包名为utils_nlp，版本号取自 utils_nlp/init.py 中的VERSION = "2.0.0"，并声明python_requires=">=3.6"。值得注意的是，setup.py中install_requires=[]为空——这印证了 SETUP.md 的明确说明：pip 安装不会安装任何依赖包，环境中的依赖一律通过上文 conda 方式建立，两者分工明确。

6.2 在外部项目中安装

如果要在外部项目中使用utils_nlp，推荐直接从 Git 仓库以可编辑模式安装：

pip install -e git+git@github.com:microsoft/nlp-recipes.git@master#egg=utils_nlp

该方式同样以-e可编辑模式安装，因此对源码的更新同样会即时生效。执行上述任一命令后，utils_nlp即进入当前 conda 虚拟环境，可用以下命令验证安装是否成功：

pip list

6.3 版本信息

仓库的版本策略遵循语义化版本，详见 VERSIONING.md：版本号由setuptools_scm依据 git 提交历史自动计算，无需手工维护，可通过python setup.py --version查看当前推导出的版本。

七、Docker 方式搭建环境

对于希望完全容器化的用户，SETUP.md 提供了基于 NVIDIA Docker 的完整方案。

7.1 预置条件

• 已安装Docker；
• 已安装NVIDIA Docker 驱动（用于在容器内访问 GPU）。

7.2 构建 Docker 镜像

仓库 docker 目录下提供了现成的 Dockerfile，构建命令为：

cd docker docker build -f . -t nlp-recipes

构建完成后会得到一个包含全部依赖、名为nlp-recipes（latest tag）的镜像。从 docker/Dockerfile 源码可以还原镜像的构建逻辑：

1. 基础镜像为nvidia/cuda（自带 CUDA 的官方镜像）；
2. 安装 Miniconda 到/opt/conda并初始化conda activate；
3. 下载 nlp-recipes 仓库源码压缩包并解压；
4. 复用仓库的依赖生成脚本：执行python /root/nlp-recipes-staging/tools/generate_conda_file.py --gpu生成 GPU 环境文件，再conda env create -n nlp_gpu -f nlp_gpu.yaml创建nlp_gpu环境——这再次印证了"一条脚本，本地 / 云端 / 容器三处通用"的设计；
5. 在nlp_gpu环境中执行pip install -e .安装utils_nlp，并用python -m ipykernel install注册 Jupyter kernel；
6. 暴露8888/tcp端口，容器启动命令（CMD）为以--allow-root --ip 0.0.0.0 --port 8888 --no-browser方式启动 Jupyter notebook。

7.3 运行容器

docker run --gpus all -p 8888:8888 nlp-recipes

-p 8888:8888将本机 8888 端口映射到容器的 8888 端口，--gpus all使容器可访问宿主机全部 GPU。启动后即可在浏览器中打开http://localhost:8888使用 notebook。

7.4 Docker 故障排查

• 权限问题：docker build或docker run若提示权限不足，可用sudo前缀执行；
• 端口占用：若提示port already in use，可换用本机其他端口映射到容器 8888 端口，例如：

docker run --gpus all -p 9000:8888 nlp-recipes

八、环境就绪后的验证路径

完成上述任一路径（本地 conda、云端工作站或 Docker）的环境搭建后，即可按以下方式验证并进入实战：

1. 运行单元测试：激活对应 conda 环境后，可仿照 CI 配置（如 tests/ci/cpu_unit_tests_linux.yml 中的pytest --durations=0 tests/unit）运行 tests/unit 下的测试，快速验证环境完整性；
2. 打开示例 notebook：进入 examples 目录，选择感兴趣的场景（如 examples/text_classification、examples/question_answering、examples/text_summarization），并确保 notebook 的 kernel 指向已注册的 conda 环境（如Python (nlp_cpu)或Python (nlp_gpu)）；
3. 下载数据集与预训练模型：多数 notebook 会按需下载数据集（数据集清单见 DatasetReferences.md）与 Hugging Face 预训练模型，首次运行耗时较长属正常现象。

至此，从零开始搭建 nlp-recipes 运行环境的全部官方路径——CPU/GPU conda 环境、云端工作站、Docker 容器——均已打通。后续学习建议以 examples/README.md 为索引，按场景逐个运行 notebook，并结合 utils_nlp 源码理解每个模型的具体实现。

• NLP