{"record":{"id":"931e14d9b0b39004","repo":"apache/beam","slug":"sentence-transformers-is-required-to-use-931e14","errorCode":null,"errorMessage":"sentence-transformers is required to use SentenceTransformerEmbeddings.Please install it with using `pip install sentence-transformers`.","messagePattern":"sentence-transformers is required to use SentenceTransformerEmbeddings\\.Please install it with using `pip install sentence-transformers`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/ml/transforms/embeddings/huggingface.py","lineNumber":72,"sourceCode":"      model_name: str,\n      model_class: Callable,\n      load_model_args: Optional[dict] = None,\n      min_batch_size: Optional[int] = None,\n      max_batch_size: Optional[int] = None,\n      max_seq_length: Optional[int] = None,\n      large_model: bool = False,\n      **kwargs):\n    self._max_seq_length = max_seq_length\n    self.model_name = model_name\n    self._model_class = model_class\n    self._load_model_args = load_model_args\n    self._min_batch_size = min_batch_size\n    self._max_batch_size = max_batch_size\n    self._large_model = large_model\n    self._kwargs = kwargs\n\n    if not SentenceTransformer:\n      raise ImportError(\n          \"sentence-transformers is required to use \"\n          \"SentenceTransformerEmbeddings.\"\n          \"Please install it with using `pip install sentence-transformers`.\")\n\n  def run_inference(\n      self,\n      batch: Sequence[str],\n      model: SentenceTransformer,\n      inference_args: Optional[dict[str, Any]] = None,\n  ):\n    inference_args = inference_args or {}\n    return model.encode(batch, **inference_args)\n\n  def load_model(self):\n    model = self._model_class(self.model_name, **self._load_model_args)\n    if self._max_seq_length:\n      model.max_seq_length = self._max_seq_length\n    return model","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/ml/transforms/embeddings/huggingface.py#L54-L90","documentation":"SentenceTransformerEmbeddings depends on the optional sentence-transformers package. The module captures the import result into SentenceTransformer; if the package is not installed, __init__ raises ImportError instructing the user to install it with pip install sentence-transformers.","triggerScenarios":"Instantiating SentenceTransformerEmbeddings(...) in an environment where sentence-transformers is not installed, so SentenceTransformer is None; deploying a pipeline to runners/workers without the extra dependency.","commonSituations":"Fresh virtualenv or CI job missing the optional dependency; Dataflow/Flink workers launched without the dependency in requirements; a requirements file that includes apache-beam but not sentence-transformers.","solutions":["Install the dependency: pip install sentence-transformers.","Add sentence-transformers to your requirements.txt / setup.py extra so workers get it too.","Use the apache-beam[ml] extra if it covers the dependency, and pin compatible versions of transformers/torch alongside it."],"exampleFix":"// before\nembeddings = SentenceTransformerEmbeddings(model_name='all-MiniLM-L6-v2')\n// after\n# terminal: pip install sentence-transformers\nembeddings = SentenceTransformerEmbeddings(model_name='all-MiniLM-L6-v2')","handlingStrategy":"validation","validationCode":"try:\n    import sentence_transformers\nexcept ImportError:\n    raise SystemExit('Install with: pip install sentence-transformers')","typeGuard":"def sentence_transformers_available() -> bool:\n    try:\n        import sentence_transformers\n        return True\n    except ImportError:\n        return False","tryCatchPattern":"try:\n    embeddings = SentenceTransformerEmbeddings(model_name='all-MiniLM-L6-v2')\nexcept ImportError:\n    pip_install(['sentence-transformers'])\n    embeddings = SentenceTransformerEmbeddings(model_name='all-MiniLM-L6-v2')","preventionTips":["pip install sentence-transformers in every environment (dev, CI, workers).","Add it to requirements.txt or the apache-beam[ml] extra used at deploy time.","Verify worker containers include the dependency.","Lazy-import inside functions to fail fast with a clear message."],"tags":["python","missing-dependency","sentence-transformers"],"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-20T03:17:13.778Z"}