[v5.4] Introduce cross-modality and multi-modality support; modularize CrossEncoder class

.git-blame-ignore-revs

@@ -0,0 +1,8 @@
+# Reorder Transformer class methods into logical groups
+89278b37fa5fb5d63541a7b584116665b0f1c29f
+# Extensive TitleCase -> snake_case file renaming + backwards compat.
+a4318ac5b39e043eda56e40cbef637882f8e4030
+# Rename example/test files to snake_case and replace dashes with underscores
+0db9a35d3d4b017aa79dfb7e5c6db78592d4ae23
+# Move test files to mirror source directory structure
+86e0a21228683fd7feac002cad5d7ff5536d3f2e

.github/workflows/min-versions.yml

@@ -0,0 +1,71 @@
+name: Minimum version tests
+
+on:
+  push:
+    branches:
+      - main
+      - "*-release"
+  pull_request:
+    branches:
+      - main
+      - "*-release"
+    paths:
+      - "pyproject.toml"
+      - "sentence_transformers/**"
+      - ".github/workflows/min-versions.yml"
+  workflow_dispatch:
+
+env:
+  TRANSFORMERS_IS_CI: 1
+  HF_HUB_DISABLE_PROGRESS_BARS: 1
+
+jobs:
+  test_min_versions:
+    name: Test minimum dependency versions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Remove unnecessary files
+        run: |
+          sudo rm -rf \
+            "$AGENT_TOOLSDIRECTORY" \
+            /opt/google/chrome \
+            /opt/microsoft/msedge \
+            /opt/microsoft/powershell \
+            /opt/pipx \
+            /usr/lib/mono \
+            /usr/local/julia* \
+            /usr/local/lib/android \
+            /usr/local/lib/node_modules \
+            /usr/local/share/chromium \
+            /usr/local/share/powershell \
+            /usr/share/dotnet \
+            /usr/share/swift
+
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - name: Setup Python environment
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6
+        with:
+          python-version: "3.10"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d0d8abe699bfb85fec6de9f7adb5ae17292296ff  # v6
+
+      - name: Install FFmpeg libraries (needed to build av)
+        run: sudo apt-get update && sudo apt-get install -y libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libavfilter-dev libswscale-dev libswresample-dev
+
+      - name: Install with minimum versions
+        # Runtime deps at lowest resolution & dev tools at normal resolution
+        # av>=12 because av==9.2.0 (from transformers[video]) fails to compile with modern Cython
+        # scipy>=1.7.2 because older scipy has no wheels for Python 3.10+ and fails to build from source
+        # datasets>=2.14.7 because older datasets uses pyarrow's removed PyExtensionType
+        run: |
+          uv pip install '.[train]' 'transformers[vision,audio,video]' 'av>=12.0.0' 'scipy>=1.7.2' 'datasets>=2.14.7' --resolution lowest-direct --system
+          uv pip install pytest pytest-cov pytest-env pytest-subtests pytest-xdist peft --system
+
+      - name: Show installed versions
+        run: uv pip list --system | grep -iE 'transformers|huggingface|torch|numpy|scikit|scipy|typing.ext|tqdm|accelerate'
+
+      - name: Run unit tests
+        run: python -m pytest --durations 20 -sv tests/

.github/workflows/tests.yml

@@ -58,13 +58,24 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@d0d8abe699bfb85fec6de9f7adb5ae17292296ff  # v6
 
+      # kenlm doesn't compile on Python 3.13, and pyctcdecode pins numpy<2.0.0
+      # which conflicts with the rest of the stack. Exclude both on Python 3.13.
+      - name: Create excludes file for packages without Python 3.13 support
+        shell: bash
+        run: |
+          if [ "${{ matrix.python-version }}" = "3.13" ]; then
+            echo -e "kenlm\npyctcdecode" > excludes.txt
+          else
+            touch excludes.txt
+          fi
+
       - name: Install dependencies (transformers < 5.0.0)
         if: ${{ matrix.transformers-version == '<5.0.0' }}
-        run: uv pip install '.[train, onnx, openvino, dev]' 'transformers<5.0.0' 'datasets>=3.3.0' --system
+        run: uv pip install '.[train, onnx, openvino, dev]' 'transformers<5.0.0' 'accelerate>=1.13.0' 'datasets>=3.3.0' --excludes excludes.txt --system
 
       - name: Install dependencies (transformers >= 5.0.0)
         if: ${{ matrix.transformers-version == '>=5.0.0' }}
-        run: uv pip install '.[train, dev]' 'transformers>=5.0.0' --system
+        run: uv pip install '.[train, dev]' 'transformers>=5.0.0' 'accelerate>=1.13.0' --excludes excludes.txt --system
 
       - name: Install model2vec
         run: uv pip install model2vec[distill] --system

.gitignore

@@ -17,6 +17,7 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+__pycache__
 
 # Docs
 /docs/_build/

.pre-commit-config.yaml

@@ -1,7 +1,16 @@
 repos:
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.5
-    hooks:
-      - id: ruff
-        args: [--exit-non-zero-on-fix]
-      - id: ruff-format
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.15.6
+  hooks:
+    # Run the linter.
+    - id: ruff-check
+      args: [ --fix, --show-fixes ]
+    # Run the formatter.
+    - id: ruff-format
+
+- repo: https://github.com/crate-ci/typos
+  rev: v1.45.0
+  hooks:
+    - id: typos
+      args: ["--diff", "--force-exclude"]

README.md

@@ -58,7 +58,7 @@ First download a pretrained embedding a.k.a. Sentence Transformer model.
 ```python
 from sentence_transformers import SentenceTransformer
 
-model = SentenceTransformer("all-MiniLM-L6-v2")
+model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
 ```
 
 Then provide some texts to the model.
@@ -112,7 +112,7 @@ print(scores)
 # => [8.607139 5.506266 6.352977]
 ```
 
-And we're good to go. You can also use [`model.rank`](https://sbert.net/docs/package_reference/cross_encoder/cross_encoder.html#sentence_transformers.cross_encoder.CrossEncoder.rank) to avoid having to perform the reranking manually:
+And we're good to go. You can also use [`model.rank`](https://sbert.net/docs/package_reference/cross_encoder/cross_encoder.html#sentence_transformers.cross_encoder.model.CrossEncoder.rank) to avoid having to perform the reranking manually:
 
 ```python
 # 2b. Rank a list of passages for a query

docs/.htaccess

@@ -18,7 +18,7 @@ Redirect 301 /docs/package_reference/cross_encoder.html /docs/package_reference/
 Redirect 301 /docs/package_reference/datasets.html /docs/package_reference/sentence_transformer/datasets.html
 Redirect 301 /docs/package_reference/evaluation.html /docs/package_reference/sentence_transformer/evaluation.html
 Redirect 301 /docs/package_reference/losses.html /docs/package_reference/sentence_transformer/losses.html
-Redirect 301 /docs/package_reference/models.html /docs/package_reference/sentence_transformer/models.html
+Redirect 301 /docs/package_reference/models.html /docs/package_reference/sentence_transformer/modules.html
 Redirect 301 /docs/package_reference/quantization.html /docs/package_reference/sentence_transformer/quantization.html
 Redirect 301 /docs/package_reference/SentenceTransformer.html /docs/package_reference/sentence_transformer/SentenceTransformer.html
 
@@ -71,6 +71,18 @@ Redirect 301 /examples/unsupervised_learning/README.html /examples/sentence_tran
 Redirect 301 /examples/unsupervised_learning/SimCSE/README.html /examples/sentence_transformer/unsupervised_learning/SimCSE/README.html
 Redirect 301 /examples/unsupervised_learning/TSDAE/README.html /examples/sentence_transformer/unsupervised_learning/TSDAE/README.html
 
+# Moved API Reference pages for v5.3.0
+Redirect 301 /docs/package_reference/sentence_transformer/quantization.html /docs/package_reference/util/quantization.html
+Redirect 301 /docs/package_reference/util.html /docs/package_reference/util/index.html
+
+# Moved API Reference pages for v5.4.0, the multimodality refactor
+Redirect 301 /docs/package_reference/sentence_transformer/models.html /docs/package_reference/sentence_transformer/modules.html
+Redirect 301 /docs/package_reference/cross_encoder/models.html /docs/package_reference/cross_encoder/modules.html
+Redirect 301 /docs/package_reference/sparse_encoder/models.html /docs/package_reference/sparse_encoder/modules.html
+Redirect 301 /docs/package_reference/sentence_transformer/SentenceTransformer.html /docs/package_reference/sentence_transformer/model.html
+Redirect 301 /docs/package_reference/sparse_encoder/SparseEncoder.html /docs/package_reference/sparse_encoder/model.html
+Redirect 301 /docs/package_reference/cross_encoder/cross_encoder.html /docs/package_reference/cross_encoder/model.html
+
 # Redirect to index.html when request file does not exist
 # RewriteCond %{REQUEST_FILENAME} !-f
 # RewriteCond %{REQUEST_FILENAME} !-d