Kosmos-2 环境搭建完全指南：基于 unilm 仓库的 conda 安装与依赖详解

Kosmos-2 环境搭建完全指南：基于 unilm 仓库的 conda 安装与依赖详解

【免费下载链接】unilmLarge-scale Self-supervised Pre-training Across Tasks, Languages, and Modalities项目地址: https://gitcode.com/GitHub_Trending/un/unilm

本文是 Kosmos-2（Grounding Multimodal Large Language Models to the World）在 unilm 仓库中的安装部署指南，以 kosmos-2/docs/install.md 为骨架，结合仓库内的 requirements.txt、vl_setup_xl.sh 等源码与脚本，完整讲解从克隆仓库、创建 conda 环境、编译 NVIDIA Apex 到一键安装全部依赖的完整流程。读完本文，你将能够独立搭建一套可运行的 Kosmos-2 开发环境，并能运行仓库自带的 Gradio 本地 Demo 与推理脚本验证环境。

Kosmos-2 环境概览：需要装什么，为什么这么装

Kosmos-2 是一个"接地"（grounding）的多模态大语言模型，它的代码仓库并不是一个单体 Python 包，而是构建在多个子项目之上的：

• fairseq：提供分布式训练、任务（task）、模型（arch）注册与 checkpoint 管理等基础设施，train.sh 中使用的python -m torch.distributed.launch与--task、--criterion、--arch等参数全部由它解析；
• infinibatch：提供跨进程的流式数据加载，用于大规模图像-文本对（如 GRIT/COYO）的读取；
• torchscale：提供 Transformer 底层模块（如subln、sope-rel-pos等架构选项的实现基础）；
• open_clip：提供视觉编码器，训练脚本中的--image-encoder clip --visual-model-name ViT-L-14即来自该库；
• DeepSpeed / xformers：优化训练与注意力计算（--flash-attention）；
• sentencepiece / spacy：分词与短语抽取（GRIT 数据的noun_chunks即由 spaCy 提取）。

因此安装环节分为三层：conda 基础环境 + pip 版本锁定依赖（requirements.txt）、Apex 编译安装（CUDA 扩展）、子项目与训练增强依赖（vl_setup_xl.sh）。

第一步：克隆仓库并进入项目目录

install.md 的第一步是从 GitHub 克隆 unilm 仓库并进入 kosmos-2 子目录：

git clone https://github.com/microsoft/unilm.git cd unilm/kosmos-2

如果你已经拥有本仓库的副本，直接进入kosmos-2/目录即可。仓库根目录下kosmos-2/的顶层结构如下（对应 kosmos-2 目录）：

kosmos-2/ ├── fairseq/ # 本地安装的 fairseq 子项目 ├── infinibatch/ # 本地安装的流式数据加载库 ├── torchscale/ # 本地安装的模型底层库 ├── open_clip/ # 本地安装的 OpenCLIP 实现 ├── unilm/ # Kosmos-2 特有的任务、模型、数据与损失实现 ├── data/ # 分词字典、sentencepiece 模型与数据预处理脚本 ├── demo/ # Gradio 演示应用（gradio_app.py 等） ├── evaluation/ # 评估代码 ├── docs/ # 文档（含本文依据的 install.md） ├── requirements.txt # 版本锁定的 pip 依赖 ├── vl_setup_xl.sh # 一键安装脚本 ├── train.sh # 训练脚本 ├── run_gradio.sh # 本地 Demo 启动脚本 ├── train.py / generate.py / interactive.py / preprocess.py / validate.py

注意：fairseq/、infinibatch/、torchscale/、open_clip/这四者既是目录也是可安装的 Python 包，这正是 vl_setup_xl.sh 用本地pip install安装它们的原因。

第二步：创建 conda 环境并安装版本锁定依赖

install.md 给出了明确的 Python 版本要求与依赖清单：

conda create -n kosmos-2 python=3.9 conda activate kosmos-2 pip3 install -r requirements.txt

其中requirements.txt的内容（kosmos-2/requirements.txt）完整如下：

numpy==1.23.0 scipy==1.8.0 sentencepiece==0.1.99 protobuf==3.20.3 torch==1.13.0 gradio==3.37.0 torchvision==0.14.0 opencv-python-headless==4.8.0.74 tensorboardX==1.8

这些依赖有几个值得注意的约束点：

实操提示：install.md 使用的是pip3 install -r requirements.txt。由于torch==1.13.0是 CPU/GPU 通用的版本约束，如果你的 CUDA 环境特殊，可以在安装 requirements 之前先按官方渠道安装匹配的 PyTorch 预编译包，再安装其余依赖；但请保持numpy、protobuf等关键版本与清单一致，避免后续 Apex 编译或 sentencepiece 运行时出现兼容问题。

第三步：编译安装 NVIDIA Apex（CUDA 扩展）

Apex 提供混合精度训练所需的--cpp_ext与--cuda_ext扩展。install.md 给出了两种安装方式，区别取决于你的 pip 版本：

git clone https://github.com/NVIDIA/apex cd apex # 如果 pip >= 23.1（该版本开始支持同一 key 的多个 --config-settings）： pip install -v --disable-pip-version-check --no-cache-dir --no-build-isolation --config-settings "--build-option=--cpp_ext" --config-settings "--build-option=--cuda_ext" ./ # 否则（旧版 pip，使用 --global-option）： pip install -v --disable-pip-version-check --no-cache-dir --no-build-isolation --global-option="--cpp_ext" --global-option="--cuda_ext" ./

两种方式的要点解析：

• --cpp_ext/--cuda_ext：编译 C++ 与 CUDA 扩展。Kosmos-2 训练脚本 train.sh 使用了--memory-efficient-fp16、--fp16-init-scale 4、--fp16-scale-window 256、--min-loss-scale 0.0001等混合精度参数，这些在底层会用到 Apex 提供的优化器与缩放器实现，因此不可跳过 Apex 安装；
• --no-build-isolation：禁止 pip 为构建过程创建隔离环境，直接使用当前 conda 环境中的 PyTorch 头文件与编译器，保证 Apex 链接到的是torch==1.13.0；
• --no-cache-dir/--disable-pip-version-check：避免缓存导致的编译产物不一致，并减少不必要的网络检查；
• pip 23.1 分水岭：pip 23.1 起--global-option被移除，同一--build-option需通过多个--config-settings重复传入，这正是 install.md 分别给出两条命令的原因。可以先执行pip --version确认自己的 pip 版本再选择对应命令。

Apex 编译需要本机具备 NVIDIA CUDA 工具链（nvcc）与兼容的 GCC，编译过程耗时较长属正常现象，看到Successfully built apex即表示成功。

第四步：一键安装子项目与训练增强依赖

环境安装的最后一步是执行仓库自带的一键脚本：

bash vl_setup_xl.sh

vl_setup_xl.sh 的全部内容如下，逐行拆解：

pip install fairseq/ pip install infinibatch/ pip install torchscale/ pip install open_clip/ pip install --user git+https://github.com/microsoft/DeepSpeed.git@jeffra/engine-xthru-v2 pip install -v -U git+https://github.com/facebookresearch/xformers.git@v0.0.22 pip install numpy==1.23.0 tiktoken ftfy sentencepiece httpcore==0.17.3 gradio==3.37.0 spacy==3.6.0 thinc==8.1.10 pydantic==1.10.11

从脚本内容可以看出，最后一行的numpy、gradio、sentencepiece与 requirements.txt 中的版本保持一致，属于"统一版本、防止冲突"的收尾动作。整个脚本是幂等友好的：即使某一步失败，修复环境后重新执行bash vl_setup_xl.sh即可继续。

备选方案：官方 Docker 镜像

在 kosmos-2/README.md 的 Setup 一节中，官方还提供了一条 Docker 路径，作为 conda 方案的替代：

alias=`whoami | cut -d'.' -f2`; docker run -it --rm --runtime=nvidia --ipc=host --privileged -v /home/${alias}:/home/${alias} nvcr.io/nvidia/pytorch:22.10-py3 bash

该命令基于 NVIDIA NGC 的pytorch:22.10-py3镜像（内含与torch==1.13.0时代匹配的 CUDA 环境），进入容器后直接执行bash vl_setup_xl.sh即可，省去 conda 与 Apex 的编译步骤。README 同时指出：详细包信息可参考仓库 issue 中的评论，conda 方案则正是本文依据的 kosmos-2/docs/install.md。两种方式二选一，推荐在无法访问 Docker 的机器上使用 conda 路径。

安装后验证：下载模型并启动本地 Demo

环境安装完成不代表万事大吉，建议按以下顺序做三层验证。

1. 验证 Python 导入

python -c "import torch, fairseq, torchscale, open_clip; print(torch.__version__)"

正常应输出1.13.0且无 ImportError；随后验证 Apex：

python -c "from apex import amp; print('apex ok')"

2. 下载 Kosmos-2 checkpoint

README 提供了模型权重的下载命令（checkpoint 由wget从转换中心获取）：

DLINK=$(echo -n "aHR0cHM6Ly9jb252ZXJzYXRpb25odWIuYmxvYi5jb3JlLndpbmRvd3MubmV0L2JlaXQtc2hhcmUtcHVibGljL2tvc21vcy0yL2tvc21vcy0yLnB0P3N2PTIwMjMtMDEtMDMmc3Q9MjAyNC0wNC0xMFQxMyUzQTExJTNBNDRaJnNlPTIwNTAtMDQtMTFUMTMlM0ExMSUzQTAwWiZzcj1jJnNwPXImc2lnPTRjWEpJalZSWkhJQldxSGpQZ0RuJTJGMDFvY3pwRFdYaXBtUENVazNaOHZiUSUzRA==" | base64 --decode) wget -O kosmos-2.pt $DLINK

模型权重即后续 Demo 与推理所需的kosmos-2.pt。

3. 启动 Gradio 本地 Demo

仓库提供 run_gradio.sh 一键启动本地交互式 Demo：

bash run_gradio.sh

脚本内部会将model_path=/path/to/kosmos2.pt替换为你的权重路径，然后通过torch.distributed.launch单卡启动 demo/gradio_app.py，并携带一系列推理关键参数：

• --task generation_obj：使用 Kosmos-2 的接地生成任务（对应 unilm 下的任务实现）；
• --model-overrides "{'visual_pretrained': '', 'dict_path':'data/dict.txt'}"与--dict-path 'data/dict.txt'：指定分词字典（data/dict.txt）；
• --image-feature-length 64：图像侧送入语言模型的 token 数，与训练脚本中的--latent-query-num 64一致；
• --locate-special-token 1：启用<grounding>特殊 token，让模型输出目标框；
• --location-bin-size 32：坐标离散化的分桶大小，对应训练侧的--quantized-size 32。

从 demo/gradio_app.py 的源码可以看到，输入图像会先经过Resize((224, 224))+ Inception 归一化（mean=[0.48145466, 0.4578275, 0.40821073]）的预处理管线，再送入视觉编码器，最终由draw_box模块把模型输出的坐标渲染成可视化框。若此 Demo 能正常出图与出框，说明从 PyTorch、Apex 到 sentencepiece、gradio 的整条依赖链均已就绪。

进阶：训练环境相关的参数速查

完成上述安装后，环境同样支持训练（数据准备后执行bash train.sh）。这里补充 train.sh 中与"环境能力"直接相关的参数说明，便于验证你的环境是否满足训练需求：

其中 DeepSpeed、xformers 均来自 vl_setup_xl.sh 的安装；data-weights 0,8,0表示交错数据、LAION 数据、纯文本数据三类数据源按 0:8:0 的概率采样。如果你的环境缺少 GPU 或未安装 CUDA 工具链，训练相关步骤（Apex 编译、DeepSpeed 安装）会失败，但纯推理 Demo 在满足 CUDA 的前提下仍可运行。

常见问题与排查建议

基于安装脚本与源码结构，可以推断以下常见问题及对策：

1. Apex 编译失败：多为torch与 nvcc 版本不匹配。确认nvcc --version与torch.version.cuda对应，并在编译前保证当前 conda 环境中torch==1.13.0已就位（--no-build-isolation直接复用该环境）；
2. protobuf报错：严格按 requirements.txt 锁定protobuf==3.20.3，避免被其他安装步骤升级到 4.x；
3. gradio / pydantic 冲突：保持gradio==3.37.0与pydantic==1.10.11，两者版本联动，不要单独升级其中任意一个；
4. sentencepiece 加载失败：检查--spm-model指向的data/sentencepiece.bpe.model文件是否存在（位于 kosmos-2/data 目录）；
5. 分布式启动报错：run_gradio.sh与train.sh都依赖torch.distributed.launch，若多卡环境异常，可先设置CUDA_VISIBLE_DEVICES=0单卡运行验证环境本身。

总结

Kosmos-2 的安装分为四个层次：conda 环境与版本锁定依赖（requirements.txt）→ Apex CUDA 扩展编译 → 子项目与训练增强依赖一键安装（vl_setup_xl.sh）→ 模型权重下载与本地 Demo 验证（run_gradio.sh）。其中最容易出错的是 Apex 编译（注意 pip 版本对应的两种安装语法）与 protobuf/pydantic 等精确版本锁定。按照本文顺序执行，即可获得一套同时支持本地交互 Demo 与大规模预训练实验的完整 Kosmos-2 环境；仓库的 Docker 方案（kosmos-2/README.md Setup 一节）可作为跳过编译步骤的替代选项。

【免费下载链接】unilmLarge-scale Self-supervised Pre-training Across Tasks, Languages, and Modalities项目地址: https://gitcode.com/GitHub_Trending/un/unilm