apache/beam · error · ImportError

vertexai is required to use VertexAIImageEmbeddings. Please…

Error message

vertexai is required to use VertexAIImageEmbeddings. Please install it with `pip install google-cloud-aiplatform`

What it means

VertexAIImageEmbeddings depends on the google-cloud-aiplatform package (imported as vertexai). The module does an optional import with try/except; if the package is not installed, __init__ raises ImportError instructing the user to install it. This is a standard optional-dependency guard in Beam ML.

Solutions

Run `pip install google-cloud-aiplatform`.
Install with extras: `pip install apache-beam[gcp]`.
Pin the package in requirements.txt / setup.py and pass it via --requirements_file on Dataflow.
Verify `python -c "import vertexai"` works in the target runtime environment.

Example fix

// before
from apache_beam.ml.rag.embeddings.vertex_ai import VertexAIImageEmbeddings
embedder = VertexAIImageEmbeddings(model_name='multimodalembedding@001')  # ImportError
// after
# pip install google-cloud-aiplatform
embedder = VertexAIImageEmbeddings(model_name='multimodalembedding@001', project='my-project')

Defensive patterns

Strategy: validation

Validate before calling

try:
    import vertexai  # noqa
except ImportError:
    raise SystemExit('Install: pip install google-cloud-aiplatform')

Try / catch

try:
    embedder = VertexAIImageEmbeddings(model_name='multimodalembedding@001')
except ImportError as e:
    logging.error('Missing aiplatform dependency: %s', e)
    raise

Prevention

Pin google-cloud-aiplatform in requirements.txt and pass --requirements_file to Dataflow.
Install apache-beam[gcp] in dev and CI environments.
Smoke-test `import vertexai` in the target runner image.

When it happens

Trigger: Instantiating VertexAIImageEmbeddings(model_name=..., project=...) in an environment where google-cloud-aiplatform was never pip-installed (or the import inside vertex_ai.py failed due to a broken installation).

Common situations: Deploying a Beam pipeline to Dataflow/Spark/Flink runners where extra deps weren't included; fresh venv missing extras; running `pip install apache-beam` without the gcp extra.

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

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

Appendix: source

Thrown at sdks/python/apache_beam/ml/rag/embeddings/vertex_ai.py:165

      credentials: Optional[Credentials] = None,
      **kwargs):
    """Vertex AI image embeddings for RAG pipelines.

    Generates embeddings for images using Vertex AI
    multimodal embedding models.

    Args:
        model_name: Name of the Vertex AI model.
        dimension: Embedding dimension. Must be one of
            128, 256, 512, or 1408.
        project: GCP project ID.
        location: GCP location.
        credentials: Optional GCP credentials.
        **kwargs: Additional arguments passed to
            :class:`~apache_beam.ml.transforms.base.EmbeddingsManager`.
    """
    if not vertexai:
      raise ImportError(
          "vertexai is required to use "
          "VertexAIImageEmbeddings. "
          "Please install it with "
          "`pip install google-cloud-aiplatform`")

    if dimension is not None and dimension not in (128, 256, 512, 1408):
      raise ValueError("dimension must be one of "
                       "128, 256, 512, or 1408")

    super().__init__(type_adapter=_create_image_adapter(), **kwargs)
    self.model_name = model_name
    self.dimension = dimension
    self.project = project
    self.location = location
    self.credentials = credentials

  def get_model_handler(self):
    """Returns model handler for image embedding."""

View on GitHub (pinned to 12126d8942)