zylon-ai/private-gpt · error · ImportError

OpenAI embeddings dependencies are not installed. Install wi

Error message

OpenAI embeddings dependencies are not installed. Install with `uv sync --inexact --extra embedding-openai`.

What it means

ImportError raised inside OpenAIGPTEmbeddingFactory._create_embedding when llama_index.embeddings.openai (OpenAIEmbedding) cannot be imported. It is chained from the original ImportError and the message names the exact uv extra: embedding-openai. Because the import happens per model creation, the error surfaces at the first attempt to build an OpenAI embedding, not at application start.

Source

Thrown at private_gpt/components/embedding/factories/openai.py:21

from private_gpt.components.embedding.factories.base import EmbeddingFactory
from private_gpt.components.model_discovery.url_utils import is_openai_api_base
from private_gpt.settings.settings import EmbeddingModelConfig, Settings
from private_gpt.utils.dependencies import format_missing_dependency_message


class OpenAIGPTEmbeddingFactory(EmbeddingFactory):
    def __init__(self, settings: Settings) -> None:
        super().__init__(settings)

    def _create_embedding(
        self, model_config: EmbeddingModelConfig
    ) -> tuple[BaseEmbedding, str | None]:
        try:
            from llama_index.embeddings.openai import (  # ty:ignore[unresolved-import]
                OpenAIEmbedding,
            )
        except ImportError as e:
            raise ImportError(
                format_missing_dependency_message(
                    "OpenAI embeddings",
                    extras="embedding-openai",
                )
            ) from e

        api_base = (
            self.settings.openai.embedding_api_base or self.settings.openai.api_base
        )
        api_key = self.settings.openai.embedding_api_key or self.settings.openai.api_key
        model = model_config.name

        embedding_model = OpenAIEmbedding(
            api_base=api_base,
            api_key=api_key,
            model=model,
        )
        return embedding_model, model_config.name

View on GitHub (pinned to 4a030776a3)

Solutions

Run: uv sync --inexact --extra embedding-openai
Verify in the same environment: python -c "from llama_index.embeddings.openai import OpenAIEmbedding"
If install is present but failing, inspect the chained ImportError for version conflicts among llama-index packages
As a stopgap for tests, switch embedding mode to 'mock'

Example fix

# before: embedding mode 'openai' -> ImportError on first embed
# after
# uv sync --inexact --extra embedding-openai

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if importlib.util.find_spec('llama_index.embeddings.openai') is None:
    raise SystemExit('run: uv sync --inexact --extra embedding-openai')

Try / catch

try:
    embed = factory.create(model_config)
except ImportError as e:
    if 'embedding-openai' in str(e):
        raise SystemExit('OpenAI embeddings missing; run: uv sync --inexact --extra embedding-openai') from e
    raise

Prevention

Include the embedding-openai extra in production images by default
Check find_spec for the integration at deploy time
Keep llama-index packages on one coherent version set in the lockfile

When it happens

Trigger: Selecting embedding mode 'openai' (or a model routed to this factory) in an environment where the llama-index OpenAI embeddings integration is not installed.

Common situations: Base install without embedding extras; dependency pruning/lockfile regeneration that dropped the integration; running the app inside a different container/venv than the one that was synced; partial upgrade of llama-index packages.

Related errors

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/55b5cf8f363191b1. Report an issue: GitHub.