{"record":{"id":"02ad24daab73dfc7","repo":"chroma-core/chroma","slug":"deployment-id-must-be-specified-for-azure-openai","errorCode":null,"errorMessage":"deployment_id must be specified for Azure OpenAI","messagePattern":"deployment_id must be specified for Azure OpenAI","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/openai_embedding_function.py","lineNumber":97,"sourceCode":"\n        # Initialize the OpenAI client\n        client_params: Dict[str, Any] = {\"api_key\": self.api_key}\n\n        if self.organization_id is not None:\n            client_params[\"organization\"] = self.organization_id\n        if self.api_base is not None:\n            client_params[\"base_url\"] = self.api_base\n        if self.default_headers is not None:\n            client_params[\"default_headers\"] = self.default_headers\n\n        self.client = openai.OpenAI(**client_params)\n\n        # For Azure OpenAI\n        if self.api_type == \"azure\":\n            if self.api_version is None:\n                raise ValueError(\"api_version must be specified for Azure OpenAI\")\n            if self.deployment_id is None:\n                raise ValueError(\"deployment_id must be specified for Azure OpenAI\")\n            if self.api_base is None:\n                raise ValueError(\"api_base must be specified for Azure OpenAI\")\n\n            from openai import AzureOpenAI\n\n            self.client = AzureOpenAI(\n                api_key=self.api_key,\n                api_version=self.api_version,\n                azure_endpoint=self.api_base,\n                azure_deployment=self.deployment_id,\n                default_headers=self.default_headers,\n            )\n\n    def __call__(self, input: Documents) -> Embeddings:\n        \"\"\"\n        Generate embeddings for the given documents.\n        Args:\n            input: Documents to generate embeddings for.","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/openai_embedding_function.py#L79-L115","documentation":"Azure validation in OpenAIEmbeddingFunction.__init__: with api_type=\"azure\", deployment_id must be set. Azure OpenAI does not address models by plain model name; embeddings are served from a named deployment you created in the portal/CLI, and it maps to AzureOpenAI(azure_deployment=...). A None deployment_id therefore means the client cannot know which deployment to call, so the constructor raises immediately.","triggerScenarios":"OpenAIEmbeddingFunction(api_type=\"azure\", api_version=..., api_base=...) with deployment_id omitted. A frequent variant: passing model_name=\"text-embedding-ada-002\" believing it selects the Azure target — it does not; only deployment_id does, so the error still fires.","commonSituations":"New Azure OpenAI resource where the developer has the model name but no deployment yet (deployments must be created explicitly); multiple deployments and the wrong variable copied; confusion between deployment name and model name — the deployment can be named anything and is what must be passed.","solutions":["Create (or locate) a deployment in Azure Portal -> your Azure OpenAI resource -> Model deployments, then pass its exact name: OpenAIEmbeddingFunction(api_type=\"azure\", deployment_id=\"<deployment-name>\", api_version=..., api_base=...).","Use Azure CLI to create one if missing: az cognitiveservices account deployment create --resource-group <rg> --name <account> --deployment-name embed-dep --model-name text-embedding-3-small --model-version latest --model-format OpenAI.","Load it from configuration/env (AZURE_OPENAI_DEPLOYMENT) so local and cloud values don't get mixed up.","Remember model_name stays as the underlying model (e.g. text-embedding-3-small) while deployment_id is the deployment you named — both are needed."],"exampleFix":"// before\nazure_ef = OpenAIEmbeddingFunction(\n    api_type=\"azure\", api_version=\"2024-02-01\",\n    api_base=\"https://myresource.openai.azure.com\",\n    model_name=\"text-embedding-3-small\",\n)  # ValueError: deployment_id must be specified for Azure OpenAI\n\n# after\nazure_ef = OpenAIEmbeddingFunction(\n    api_type=\"azure\", api_version=\"2024-02-01\",\n    api_base=\"https://myresource.openai.azure.com\",\n    model_name=\"text-embedding-3-small\",\n    deployment_id=\"my-embed-deployment\",  # deployment name from Azure Portal\n)","handlingStrategy":"validation","validationCode":"AZURE_REQUIRED = (\"api_base\", \"api_version\", \"deployment_id\")\nmissing = [k for k in AZURE_REQUIRED if not os.getenv(f\"AZURE_OPENAI_{k.upper()}\")]\nif missing:\n    raise RuntimeError(f\"Set these before startup: {', '.join('AZURE_OPENAI_' + m.upper() for m in missing)}\")","typeGuard":"def azure_config_complete(cfg: dict) -> bool:\n    return all(cfg.get(k) for k in (\"api_version\", \"deployment_id\", \"api_base\"))","tryCatchPattern":"try:\n    azure_ef = OpenAIEmbeddingFunction(api_type=\"azure\", **azure_params)\nexcept ValueError as e:\n    # e.g. \"deployment_id must be specified for Azure OpenAI\"\n    raise RuntimeError(f\"Fix Azure OpenAI settings: {e}\") from e","preventionTips":["Create the model deployment before wiring code, and store its exact name in AZURE_OPENAI_DEPLOYMENT.","Never assume model_name selects the Azure target — deployment_id is the addressing key.","Validate the whole Azure trio at config load time, not at first embed.","Use a pydantic/settings model so missing required fields fail fast with field-level messages."],"tags":["azure","openai","embedding","deployment","configuration","chroma"],"backgroundTag":"azure-openai-missing-config","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}