Sentence Transformers 安装指南：pip/uv/Conda 全流程与各功能扩展包（extras）详解

人工智能NLPEmbedding微调【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址https://gitcode.com/gh_mirrors/se/sentence-transformers点击查看免费下载本文是 Sentence Transformers当前仓库版本6.2.0.dev0的完整安装实战指南覆盖uv、pip、Conda三种主流包管理方式逐一讲解 Default、Image、Audio、Video、Training、ONNX、OpenVINO、Development 等全部扩展包extras的适用场景与依赖组成并介绍从源码安装、可编辑安装开发模式以及 PyTorch CUDA 环境的配置方法。读完本文你可以根据只做推理、要训练微调、要处理多模态输入、要用 ONNX/OpenVINO 后端加速等不同需求准确选择并完成最小化、可复现的安装。安装前置要求官方推荐的运行环境基线为Python 3.10PyTorch 2.2需按是否使用 GPU 选择对应版本详见下文 安装 PyTorch 并启用 CUDA 一节transformers v5.0这一基线在仓库的 pyproject.toml 中得到了印证项目声明requires-python 3.10核心依赖包含transformers5.0.0,6.0.0、tokenizers0.19、huggingface-hub1.3.0,3.0.0、torch2.2、numpy1.24.0、scikit-learn1.1.0、scipy1.0.0、typing_extensions4.10.0、tqdm4.0.0。也就是说即使是最小安装默认包pip也会自动解析并装入上述依赖无需手动逐个安装。安装选项extras总览Sentence Transformers 的安装包按功能拆分为若干可选扩展extras其依赖定义见 pyproject.toml 的[project.optional-dependencies]段。你可以根据用途按需取用并且各 extras 之间可以自由组合例如pip install -U sentence-transformers[train,image,video,onnx-gpu]。选项一句话说明实际引入的依赖来自 pyproject.tomlDefault默认文本模型的加载、保存与推理获取 embedding仅核心依赖无额外项Image支持处理图像的模型如 CLIP、基于 VLM 的模型transformers[vision]Audio支持处理音频输入的模型transformers[audio]Video支持处理视频输入的模型transformers[video]Training训练与微调模型所需依赖datasets2.16.0、accelerate1.3.0ONNX使用 ONNX 后端加载/保存/推理/优化/量化模型optimum-onnx[onnxruntime]CPU 版ONNX-GPUONNX 后端的 GPU 加速版本optimum-onnx[onnxruntime-gpu]GPU 版OpenVINO使用 OpenVINO 后端加载/保存/推理模型optimum-intel[openvino]2.0.0Development以上全部能力外加开发 Sentence Transformers 本身所需的依赖见下文 Development 开发环境 一节两个值得注意的细节ONNX 分为 CPU 与 GPU 两种安装方式onnx对应optimum-onnx[onnxruntime]仅含 CPU 版 ONNX Runtimeonnx-gpu对应optimum-onnx[onnxruntime-gpu]额外包含 CUDA 版运行库。两者不要混装。torchcodec 需要单独安装若要以torchcodec.AudioDecoder/torchcodec.VideoDecoder实例作为模型输入必须先单独执行pip install torchcodec。在源码中AudioDecoder与VideoDecoder都是可选导入的见 sentence_transformers/base/modality.py 与 sentence_transformers/base/modality_types.pysentence_transformers/util/environment.py 还专门提示缺少 torchcodec 时 transformers 会回退到 torchvision 已移除的read_video接口因此处理视频输入时务必安装 torchcodec。使用 uv 安装uv 是高性能的 Python 包管理器安装命令以uv pip install -U开头-U表示升级到最新版场景命令默认uv pip install -U sentence-transformers图像uv pip install -U sentence-transformers[image]音频uv pip install -U sentence-transformers[audio]视频uv pip install -U sentence-transformers[video]训练uv pip install -U sentence-transformers[train]ONNXGPU 与 CPUuv pip install -U sentence-transformers[onnx-gpu]ONNX仅 CPUuv pip install -U sentence-transformers[onnx]OpenVINOuv pip install -U sentence-transformers[openvino]开发uv pip install -U sentence-transformers[dev]训练日志与碳排放追踪可选推荐使用train扩展进行训练时官方还推荐安装两个辅助库# 用 Weights Biases 或 Trackio 追踪训练日志推荐二选一 uv pip install trackio # 追踪训练过程的碳排放并自动写入模型卡片 uv pip install codecarbon注意安装之后训练时还必须在 Training Arguments 的report_to参数中加入对应模块名例如wandb、trackio、codecarbon否则这些工具不会被真正启用。使用 pip 安装pip是最通用的安装方式命令与 uv 一一对应场景命令默认pip install -U sentence-transformers图像pip install -U sentence-transformers[image]音频pip install -U sentence-transformers[audio]视频pip install -U sentence-transformers[video]训练pip install -U sentence-transformers[train]ONNXGPU 与 CPUpip install -U sentence-transformers[onnx-gpu]ONNX仅 CPUpip install -U sentence-transformers[onnx]OpenVINOpip install -U sentence-transformers[openvino]开发pip install -U sentence-transformers[dev]训练场景下同样建议追加安装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 补齐。场景命令默认conda install -c conda-forge sentence-transformers图像pip install -U sentence-transformers[image]音频pip install -U sentence-transformers[audio]视频pip install -U sentence-transformers[video]训练conda install -c conda-forge sentence-transformers accelerate datasetsONNXGPU 与 CPUpip install -U sentence-transformers[onnx-gpu]ONNX仅 CPUpip install -U sentence-transformers[onnx]OpenVINOpip install -U sentence-transformers[openvino]开发conda install -c conda-forge sentence-transformers accelerate datasets pre-commit pytest ruff训练场景下同样建议pip install trackio或wandb与pip install codecarbon并在 Training Arguments 的report_to中声明对应模块名。可以看出Conda 路线下train与dev两个场景会直接通过 conda-forge 装好accelerate、datasets等训练/测试相关库而其余多模态与后端相关扩展一律走 pip。从源码安装Source Install如果你想尝鲜main分支上的最新特性而不是等待 PyPI 上的稳定版发布可以直接从源码安装场景命令默认pip install githttps://github.com/huggingface/sentence-transformers.git图像pip install -U sentence-transformers[image] githttps://github.com/huggingface/sentence-transformers.git音频pip install -U sentence-transformers[audio] githttps://github.com/huggingface/sentence-transformers.git视频pip install -U sentence-transformers[video] githttps://github.com/huggingface/sentence-transformers.git训练pip install -U sentence-transformers[train] githttps://github.com/huggingface/sentence-transformers.gitONNXGPU 与 CPUpip install -U sentence-transformers[onnx-gpu] githttps://github.com/huggingface/sentence-transformers.gitONNX仅 CPUpip install -U sentence-transformers[onnx] githttps://github.com/huggingface/sentence-transformers.gitOpenVINOpip install -U sentence-transformers[openvino] githttps://github.com/huggingface/sentence-transformers.git开发pip install -U sentence-transformers[dev] githttps://github.com/huggingface/sentence-transformers.git训练场景下的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 可以看到它实际聚合了训练相关datasets2.16.0、accelerate1.3.0测试相关pytest、pytest-cov、pytest-env、pytest-subtests、pytest-xdist代码质量pre-commit额外能力fastcluster1.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 并启用 CUDApip install sentence-transformers默认拉取的是 CPU 版 PyTorch。如果要用 GPU/CUDA 加速必须单独安装带 CUDA 支持的 PyTorch前往 PyTorch 官方 Get Started 页面根据你的 CUDA 版本选择对应的安装命令例如pip3 install torch --index-url https://download.pytorch.org/whl/cu121在安装 PyTorch 之后、安装或升级sentence-transformers或确保pip不会用 CPU 版覆盖掉已装的 CUDA 版 PyTorch安装完成后运行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。安装决策速查你的需求推荐安装命令仅做文本 embedding 推理pip install -U sentence-transformers推理 图像/音频/视频多模态模型pip install -U sentence-transformers[image,audio,video]按需取舍训练 / 微调pip install -U sentence-transformers[train]并视需要追加pip install trackio codecarbon推理 ONNX 加速CPUpip install -U sentence-transformers[onnx]推理 ONNX 加速GPUpip install -U sentence-transformers[onnx-gpu]推理 OpenVINO 加速pip install -U sentence-transformers[openvino]参与开源贡献 / 修改源码git clone后执行pip install -e .[train,dev]GPU 训练或推理先按官方指引安装 CUDA 版 PyTorch再选择上述命令安装完成并验证版本号输出正常后即可进入下一步参考 docs/quickstart.rst 快速上手文本 embedding或阅读 examples/sentence_transformer 下的各类应用示例开始你的 embedding、检索与重排之旅。赞分享人工智能NLPEmbedding微调【免费下载链接】sentence-transformersState-of-the-Art Embeddings, Retrieval, and Reranking项目地址https://gitcode.com/gh_mirrors/se/sentence-transformers点击查看免费下载相关推荐smolagents 安装完全指南pip/uv 安装、可选扩展extras与安装验证smolagents 安装完全指南pip/uv 安装、可选扩展extras与安装验证 本指南基于当前仓库smolagentsHugging Face人工智能AI AgentAgent 框架工具调用代码智能体MCP ClientsAgent 沙箱marimo 安装指南pip、uv、conda 三方式安装与推荐依赖配置详解marimo 安装指南pip、uv、conda 三方式安装与推荐依赖配置详解 marimo 是一个用纯 Python 存储的响应式笔记本reactive n数据科学前端后端AI 应用AutoGluon 安装完全指南pip、uv、Conda、源码四种方式与 CPU/GPU 配置详解AutoGluon 安装完全指南pip、uv、Conda、源码四种方式与 CPU/GPU 配置详解 本文是 AutoGluon 开源自动机器学习框架的官方安装人工智能机器学习AutoML深度学习数据科学创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考