企业官网建设流程全解析

• 人工智能
• NLP
• Embedding
• 微调

本文是 Sentence Transformers（当前仓库版本6.2.0.dev0）的完整安装实战指南，覆盖uv、pip、Conda三种主流包管理方式，逐一讲解 Default、Image、Audio、Video、Training、ONNX、OpenVINO、Development 等全部扩展包（extras）的适用场景与依赖组成，并介绍从源码安装、可编辑安装（开发模式）以及 PyTorch CUDA 环境的配置方法。读完本文，你可以根据"只做推理"、"要训练微调"、"要处理多模态输入"、"要用 ONNX/OpenVINO 后端加速"等不同需求，准确选择并完成最小化、可复现的安装。

安装前置要求

官方推荐的运行环境基线为：

• Python 3.10+
• PyTorch 2.2+（需按是否使用 GPU 选择对应版本，详见下文 "安装 PyTorch 并启用 CUDA" 一节）
• transformers v5.0+

这一基线在仓库的 pyproject.toml 中得到了印证：项目声明requires-python = ">=3.10"，核心依赖包含transformers>=5.0.0,<6.0.0、tokenizers>=0.19、huggingface-hub>=1.3.0,<3.0.0、torch>=2.2、numpy>=1.24.0、scikit-learn>=1.1.0、scipy>=1.0.0、typing_extensions>=4.10.0、tqdm>=4.0.0。也就是说，即使是最小安装（默认包），pip也会自动解析并装入上述依赖，无需手动逐个安装。

安装选项（extras）总览

Sentence Transformers 的安装包按功能拆分为若干可选扩展（extras），其依赖定义见 pyproject.toml 的[project.optional-dependencies]段。你可以根据用途"按需取用"，并且各 extras 之间可以自由组合，例如pip install -U "sentence-transformers[train,image,video,onnx-gpu]"。

两个值得注意的细节：

1. ONNX 分为 CPU 与 GPU 两种安装方式：onnx对应optimum-onnx[onnxruntime]，仅含 CPU 版 ONNX Runtime；onnx-gpu对应optimum-onnx[onnxruntime-gpu]，额外包含 CUDA 版运行库。两者不要混装。
2. torchcodec 需要单独安装：若要以torchcodec.AudioDecoder/torchcodec.VideoDecoder实例作为模型输入，必须先单独执行pip install torchcodec。在源码中，AudioDecoder与VideoDecoder都是可选导入的：见 sentence_transformers/base/modality.py 与 sentence_transformers/base/modality_types.py；sentence_transformers/util/environment.py 还专门提示：缺少 torchcodec 时 transformers 会回退到 torchvision 已移除的read_video接口，因此处理视频输入时务必安装 torchcodec。

使用 uv 安装

uv 是高性能的 Python 包管理器，安装命令以uv pip install -U开头（-U表示升级到最新版）：

训练日志与碳排放追踪（可选，推荐）

使用train扩展进行训练时，官方还推荐安装两个辅助库：

# 用 Weights & Biases 或 Trackio 追踪训练日志（推荐二选一） uv pip install trackio # 追踪训练过程的碳排放，并自动写入模型卡片 uv pip install codecarbon

注意：安装之后，训练时还必须在 Training Arguments 的report_to参数中加入对应模块名（例如"wandb"、"trackio"、"codecarbon"），否则这些工具不会被真正启用。

使用 pip 安装

pip是最通用的安装方式，命令与 uv 一一对应：

训练场景下，同样建议追加安装pip install trackio（或wandb）与pip install codecarbon，并记得在 Training Arguments 的report_to中声明相应模块名。

扩展包组合示例

因为 extras 是可叠加的，一份安装即可覆盖多种需求。例如同时需要训练、图像、视频与 ONNX GPU 推理：

pip install -U "sentence-transformers[train,image,video,onnx-gpu]"

使用 Conda 安装

基础包已发布在conda-forge频道上。需要说明的是：extras（如[image]、[train]）是 pip 的概念，Conda 并不支持，因此使用 Conda 安装基础包后，扩展能力仍需通过 pip 补齐。

训练场景下，同样建议pip install trackio（或wandb）与pip install codecarbon，并在 Training Arguments 的report_to中声明对应模块名。

可以看出，Conda 路线下train与dev两个场景会直接通过 conda-forge 装好accelerate、datasets等训练/测试相关库，而其余多模态与后端相关扩展一律走 pip。

从源码安装（Source Install）

如果你想尝鲜main分支上的最新特性（而不是等待 PyPI 上的稳定版发布），可以直接从源码安装：

训练场景下的trackio（或wandb）与codecarbon附加安装、以及report_to配置要求，与前面 pip 章节完全一致。

可编辑安装（Editable Install，开发模式）

如果你计划修改 Sentence Transformers 的源码并即时验证效果，就需要使用可编辑安装。先克隆仓库，再以开发依赖安装：

git clone https://github.com/huggingface/sentence-transformers cd sentence-transformers pip install -e ".[train,dev]"

执行后，sentence-transformers目录会与你的 Python 库路径建立链接：当你import sentence_transformers时，使用的就是本地克隆出来的这份代码，你对源码所做的改动无需重装即可生效。这是贡献代码、调试底层逻辑（例如 sentence_transformers/backend/load.py 中的后端加载逻辑）时的推荐姿势。

关于开发依赖（devextra），从 pyproject.toml 可以看到它实际聚合了：

• 训练相关：datasets>=2.16.0、accelerate>=1.3.0
• 测试相关：pytest、pytest-cov、pytest-env、pytest-subtests、pytest-xdist
• 代码质量：pre-commit
• 额外能力：fastcluster>=1.2.0、peft、transformers[vision,audio,video]、faiss-cpu、usearch

因此[train,dev]的组合足以覆盖"训练 + 测试 + 多模态 + 向量检索"的完整开发闭环。

验证安装是否成功

安装完成后，可执行如下命令快速验证：

python -c "import sentence_transformers; print(sentence_transformers.__version__)"

若输出类似6.2.0.dev0的版本号（或对应发行版本号），说明安装成功。

安装 PyTorch 并启用 CUDA

pip install sentence-transformers默认拉取的是 CPU 版 PyTorch。如果要用 GPU/CUDA 加速，必须单独安装带 CUDA 支持的 PyTorch：

1. 前往 PyTorch 官方 Get Started 页面，根据你的 CUDA 版本选择对应的安装命令（例如pip3 install torch --index-url https://download.pytorch.org/whl/cu121）；
2. 在安装 PyTorch 之后、安装（或升级）sentence-transformers，或确保pip不会用 CPU 版覆盖掉已装的 CUDA 版 PyTorch；
3. 安装完成后，运行python -c "import torch; print(torch.cuda.is_available())"检查，输出True即代表 CUDA 可用。

另外，若使用 ONNX GPU 后端，请选用sentence-transformers[onnx-gpu]（optimum-onnx[onnxruntime-gpu]），而不是onnxCPU 版。

后端（ONNX / OpenVINO）与安装包的对应关系

如果你打算使用 ONNX 或 OpenVINO 后端加载模型，理解源码中的依赖检查逻辑可以帮你避免踩坑：

• ONNX 后端：sentence_transformers/backend/load.py 中的load_onnx_model在运行时导入onnxruntime与optimum.onnxruntime，若未安装会抛出异常，并明确提示安装sentence-transformers[onnx]或sentence-transformers[onnx-gpu]。此外，该函数默认按优先级自动选择可用的 provider（如 TensorRT > CUDA > CPU），也可通过provider参数手动指定。
• OpenVINO 后端：sentence_transformers/backend/load.py 中的load_openvino_model需要optimum.intel.openvino，未安装时同样会提示pip install sentence-transformers[openvino]；其加载目标是openvino*.xml权重文件。
• OpenVINO 静态量化：sentence_transformers/backend/quantize.py 中的export_static_quantized_openvino_model额外要求datasets、optimum-intel与openvino，缺失时会提示pip install datasets sentence-transformers[openvino]。

因此，计划使用某一后端前，请先按上文表格安装对应的 extras，避免运行到一半才报ModuleNotFoundError。

安装决策速查

安装完成并验证版本号输出正常后，即可进入下一步：参考 docs/quickstart.rst 快速上手文本 embedding，或阅读 examples/sentence_transformer 下的各类应用示例，开始你的 embedding、检索与重排之旅。

• 人工智能
• NLP
• Embedding
• 微调