apache/beam · error · ImportError

sentence-transformers is required to use HuggingfaceImageEmb

Error message

sentence-transformers is required to use HuggingfaceImageEmbeddings. Please install it with `pip install sentence-transformers`.

What it means

HuggingfaceImageEmbeddings.__init__ raises this ImportError when the sentence-transformers package is not installed. SentenceTransformer is imported in a guarded try/except (None on failure) and the constructor fails fast with an install hint. Image embedding via CLIP-style SentenceTransformer models requires this library at model-load time.

Source

Thrown at sdks/python/apache_beam/ml/rag/embeddings/huggingface.py:169

            if applicable.
        **kwargs: Additional arguments passed to
            :class:`~apache_beam.ml.transforms.base.EmbeddingsManager`,
            including:

            - ``load_model_args``: dict passed to
              ``SentenceTransformer()`` constructor
              (e.g. ``device``, ``cache_folder``,
              ``trust_remote_code``).
            - ``min_batch_size`` / ``max_batch_size``:
              Control batching for inference.
            - ``large_model``: If True, share the model
              across processes to reduce memory usage.
            - ``inference_args``: dict passed to
              ``model.encode()``
              (e.g. ``normalize_embeddings``).
    """
    if not SentenceTransformer:
      raise ImportError(
          "sentence-transformers is required to use "
          "HuggingfaceImageEmbeddings. "
          "Please install it with `pip install sentence-transformers`.")
    if not PILImage:
      raise ImportError(
          "Pillow is required to use HuggingfaceImageEmbeddings. "
          "Please install it with `pip install pillow`.")
    super().__init__(type_adapter=_create_hf_image_adapter(), **kwargs)
    self.model_name = model_name
    self.max_seq_length = max_seq_length
    self.model_class = SentenceTransformer

  def get_model_handler(self):
    """Returns model handler configured with RAG adapter."""
    return _SentenceTransformerModelHandler(
        model_class=self.model_class,
        max_seq_length=self.max_seq_length,
        model_name=self.model_name,

View on GitHub (pinned to 12126d8942)

Solutions

1. Install the dependency: pip install sentence-transformers.
2. Include sentence-transformers in the requirements file delivered to your Beam runner.
3. Choose an embeddings manager whose dependencies you already have.

Example fix

// before
embedder = HuggingfaceImageEmbeddings(model_name='clip-ViT-B-32')

// after
# terminal: pip install sentence-transformers
embedder = HuggingfaceImageEmbeddings(model_name='clip-ViT-B-32')

import importlib.util

def image_embedding_deps_available() -> bool:
    return (importlib.util.find_spec('sentence_transformers') is not None
            and importlib.util.find_spec('PIL') is not None)

try:
    embedder = HuggingfaceImageEmbeddings(model_name='clip-ViT-B-32')
except ImportError:
    logging.error('Install: pip install sentence-transformers pillow')
    raise

When it happens

Trigger: Constructing HuggingfaceImageEmbeddings(model_name=...) without sentence-transformers installed; remote Beam workers missing the package because requirements weren't shipped.

Common situations: Deployment image built without the extra dependency; forgetting that image embeddings need sentence-transformers in addition to Pillow; fresh environment repro of an existing pipeline.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• sentence-transformers is required to use HuggingfaceTextEmbe
• langchain is required to use LangChainChunkerPlease install
• Pillow is required to use HuggingfaceImageEmbeddings. Please
• vertexai is required to use VertexAITextEmbeddings. Please i
• Please provide both model class and model uri to load the mo

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/81a524d32917ff16. Report an issue: GitHub.