{"record":{"id":"886ebd4ca0297621","repo":"apache/beam","slug":"vertexai-is-required-to-use-vertexaiimageembeddings-please","errorCode":null,"errorMessage":"vertexai is required to use VertexAIImageEmbeddings. Please install it with `pip install google-cloud-aiplatform`","messagePattern":"vertexai is required to use VertexAIImageEmbeddings\\. Please install it with `pip install google-cloud-aiplatform`","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/ml/rag/embeddings/vertex_ai.py","lineNumber":165,"sourceCode":"      credentials: Optional[Credentials] = None,\n      **kwargs):\n    \"\"\"Vertex AI image embeddings for RAG pipelines.\n\n    Generates embeddings for images using Vertex AI\n    multimodal embedding models.\n\n    Args:\n        model_name: Name of the Vertex AI model.\n        dimension: Embedding dimension. Must be one of\n            128, 256, 512, or 1408.\n        project: GCP project ID.\n        location: GCP location.\n        credentials: Optional GCP credentials.\n        **kwargs: Additional arguments passed to\n            :class:`~apache_beam.ml.transforms.base.EmbeddingsManager`.\n    \"\"\"\n    if not vertexai:\n      raise ImportError(\n          \"vertexai is required to use \"\n          \"VertexAIImageEmbeddings. \"\n          \"Please install it with \"\n          \"`pip install google-cloud-aiplatform`\")\n\n    if dimension is not None and dimension not in (128, 256, 512, 1408):\n      raise ValueError(\"dimension must be one of \"\n                       \"128, 256, 512, or 1408\")\n\n    super().__init__(type_adapter=_create_image_adapter(), **kwargs)\n    self.model_name = model_name\n    self.dimension = dimension\n    self.project = project\n    self.location = location\n    self.credentials = credentials\n\n  def get_model_handler(self):\n    \"\"\"Returns model handler for image embedding.\"\"\"","sourceCodeStart":147,"sourceCodeEnd":183,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/ml/rag/embeddings/vertex_ai.py#L147-L183","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before\nfrom apache_beam.ml.rag.embeddings.vertex_ai import VertexAIImageEmbeddings\nembedder = VertexAIImageEmbeddings(model_name='multimodalembedding@001')  # ImportError\n// after\n# pip install google-cloud-aiplatform\nembedder = VertexAIImageEmbeddings(model_name='multimodalembedding@001', project='my-project')","handlingStrategy":"validation","validationCode":"try:\n    import vertexai  # noqa\nexcept ImportError:\n    raise SystemExit('Install: pip install google-cloud-aiplatform')","typeGuard":null,"tryCatchPattern":"try:\n    embedder = VertexAIImageEmbeddings(model_name='multimodalembedding@001')\nexcept ImportError as e:\n    logging.error('Missing aiplatform dependency: %s', e)\n    raise","preventionTips":["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."],"tags":["python","dependency","vertex-ai","import-error"],"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"}