{"record":{"id":"81a524d32917ff16","repo":"apache/beam","slug":"sentence-transformers-is-required-to-use-huggingface","errorCode":null,"errorMessage":"sentence-transformers is required to use HuggingfaceImageEmbeddings. Please install it with `pip install sentence-transformers`.","messagePattern":"sentence-transformers is required to use HuggingfaceImageEmbeddings\\. Please install it with `pip install sentence-transformers`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/ml/rag/embeddings/huggingface.py","lineNumber":169,"sourceCode":"            if applicable.\n        **kwargs: Additional arguments passed to\n            :class:`~apache_beam.ml.transforms.base.EmbeddingsManager`,\n            including:\n\n            - ``load_model_args``: dict passed to\n              ``SentenceTransformer()`` constructor\n              (e.g. ``device``, ``cache_folder``,\n              ``trust_remote_code``).\n            - ``min_batch_size`` / ``max_batch_size``:\n              Control batching for inference.\n            - ``large_model``: If True, share the model\n              across processes to reduce memory usage.\n            - ``inference_args``: dict passed to\n              ``model.encode()``\n              (e.g. ``normalize_embeddings``).\n    \"\"\"\n    if not SentenceTransformer:\n      raise ImportError(\n          \"sentence-transformers is required to use \"\n          \"HuggingfaceImageEmbeddings. \"\n          \"Please install it with `pip install sentence-transformers`.\")\n    if not PILImage:\n      raise ImportError(\n          \"Pillow is required to use HuggingfaceImageEmbeddings. \"\n          \"Please install it with `pip install pillow`.\")\n    super().__init__(type_adapter=_create_hf_image_adapter(), **kwargs)\n    self.model_name = model_name\n    self.max_seq_length = max_seq_length\n    self.model_class = SentenceTransformer\n\n  def get_model_handler(self):\n    \"\"\"Returns model handler configured with RAG adapter.\"\"\"\n    return _SentenceTransformerModelHandler(\n        model_class=self.model_class,\n        max_seq_length=self.max_seq_length,\n        model_name=self.model_name,","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/ml/rag/embeddings/huggingface.py#L151-L187","documentation":"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.","triggerScenarios":"Constructing HuggingfaceImageEmbeddings(model_name=...) without sentence-transformers installed; remote Beam workers missing the package because requirements weren't shipped.","commonSituations":"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.","solutions":["Install the dependency: pip install sentence-transformers.","Include sentence-transformers in the requirements file delivered to your Beam runner.","Choose an embeddings manager whose dependencies you already have."],"exampleFix":"// before\nembedder = HuggingfaceImageEmbeddings(model_name='clip-ViT-B-32')\n\n// after\n# terminal: pip install sentence-transformers\nembedder = HuggingfaceImageEmbeddings(model_name='clip-ViT-B-32')","handlingStrategy":"try-catch","validationCode":"import importlib.util\n\ndef image_embedding_deps_available() -> bool:\n    return (importlib.util.find_spec('sentence_transformers') is not None\n            and importlib.util.find_spec('PIL') is not None)","typeGuard":null,"tryCatchPattern":"try:\n    embedder = HuggingfaceImageEmbeddings(model_name='clip-ViT-B-32')\nexcept ImportError:\n    logging.error('Install: pip install sentence-transformers pillow')\n    raise","preventionTips":["Install both sentence-transformers and pillow for image embedding pipelines.","Add both packages to the requirements file delivered to remote runners.","Run a constructor smoke test in CI before submitting pipelines."],"tags":["python","apache-beam","importerror","huggingface","optional-dependency"],"backgroundTag":"missing-optional-dependency","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}