{"record":{"id":"3ed290a6f5e0ef16","repo":"apache/beam","slug":"vertexai-is-required-to-use-vertexaitextembeddings-please","errorCode":null,"errorMessage":"vertexai is required to use VertexAITextEmbeddings. Please install it with `pip install google-cloud-aiplatform`","messagePattern":"vertexai is required to use VertexAITextEmbeddings\\. 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":74,"sourceCode":"      project: Optional[str] = None,\n      location: Optional[str] = None,\n      credentials: Optional[Credentials] = None,\n      **kwargs):\n    \"\"\"Utilizes Vertex AI text embeddings for semantic search and RAG\n    pipelines.\n\n    Args:\n        model_name: Name of the Vertex AI text embedding model\n        title: Optional title for the text content\n        task_type: Task type for embeddings (default: RETRIEVAL_DOCUMENT)\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 VertexAITextEmbeddings. \"\n          \"Please install it with `pip install google-cloud-aiplatform`\")\n\n    super().__init__(type_adapter=create_text_adapter(), **kwargs)\n    self.model_name = model_name\n    self.title = title\n    self.task_type = task_type\n    self.project = project\n    self.location = location\n    self.credentials = credentials\n\n  def get_model_handler(self):\n    \"\"\"Returns model handler configured with RAG adapter.\"\"\"\n    return _VertexAITextEmbeddingHandler(\n        model_name=self.model_name,\n        title=self.title,\n        task_type=self.task_type,\n        project=self.project,","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/ml/rag/embeddings/vertex_ai.py#L56-L92","documentation":"VertexAITextEmbeddings.__init__ raises this ImportError when the vertexai module (from google-cloud-aiplatform) is not importable. The module imports vertexai in a guarded try/except (None on failure) and the constructor fails fast with a pip install hint. This class calls Vertex AI embedding models, which require the aiplatform SDK client.","triggerScenarios":"Constructing VertexAITextEmbeddings(model_name=..., project=..., location=...) without google-cloud-aiplatform installed; Beam worker environments missing the package because it wasn't in the requirements file (it is included in the apache_beam[gcp] extra only if that extra was actually installed).","commonSituations":"Local dev environment with plain apache_beam install; Dataflow workers launched without the gcp extra; dependency conflicts where google-cloud-aiplatform failed to install due to version pins.","solutions":["Install the dependency: pip install google-cloud-aiplatform.","Install Beam with the GCP extra: pip install apache_beam[gcp], and ship it via --requirements_file or setup_file to remote runners.","Resolve dependency conflicts if google-cloud-aiplatform fails to install (pip check)."],"exampleFix":"// before\nembedder = VertexAITextEmbeddings(model_name='textembedding-gecko@003', project='my-proj')\n\n// after\n# terminal: pip install google-cloud-aiplatform\nembedder = VertexAITextEmbeddings(model_name='textembedding-gecko@003', project='my-proj')","handlingStrategy":"try-catch","validationCode":"import importlib.util\n\ndef vertexai_available() -> bool:\n    return importlib.util.find_spec('google.cloud.aiplatform') is not None","typeGuard":null,"tryCatchPattern":"try:\n    embedder = VertexAITextEmbeddings(model_name='textembedding-gecko@003', project='my-proj')\nexcept ImportError:\n    logging.error('Install: pip install google-cloud-aiplatform (or apache_beam[gcp])')\n    raise","preventionTips":["Install apache_beam[gcp] so google-cloud-aiplatform comes with Beam.","Ship google-cloud-aiplatform via --requirements_file to Dataflow workers.","Run pip check in CI to catch version conflicts blocking the aiplatform install."],"tags":["python","apache-beam","importerror","vertexai","gcp","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"}