feat(embedders): default to text-embedding-3-small (5x cheaper than ada-002)

Switches default model for OpenAITextEmbedder, OpenAIDocumentEmbedder,
AzureOpenAITextEmbedder, and AzureOpenAIDocumentEmbedder from
text-embedding-ada-002 to text-embedding-3-small.

text-embedding-3-small is the previous-generation ada-002's successor:
~5x cheaper per token and higher MTEB scores per OpenAI's announcement
(https://openai.com/index/new-embedding-models-and-api-updates/).

Users can pin the old model explicitly via model= or azure_deployment=.

Author: camgrimsec

haystack/components/embedders/azure_document_embedder.py

@@ -40,7 +40,7 @@ def __init__(  # noqa: PLR0913 (too-many-arguments)
         self,
         azure_endpoint: str | None = None,
         api_version: str | None = "2023-05-15",
-        azure_deployment: str = "text-embedding-ada-002",
+        azure_deployment: str = "text-embedding-3-small",
         dimensions: int | None = None,
         api_key: Secret | None = Secret.from_env_var("AZURE_OPENAI_API_KEY", strict=False),
         azure_ad_token: Secret | None = Secret.from_env_var("AZURE_OPENAI_AD_TOKEN", strict=False),
@@ -67,7 +67,7 @@ def __init__(  # noqa: PLR0913 (too-many-arguments)
         :param api_version:
             The version of the API to use.
         :param azure_deployment:
-            The name of the model deployed on Azure. The default model is text-embedding-ada-002.
+            The name of the model deployed on Azure. The default is `text-embedding-3-small`.
         :param dimensions:
             The number of dimensions of the resulting embeddings. Only supported in text-embedding-3
             and later models.

haystack/components/embedders/azure_text_embedder.py

@@ -38,7 +38,7 @@ def __init__(  # noqa: PLR0913
         self,
         azure_endpoint: str | None = None,
         api_version: str | None = "2023-05-15",
-        azure_deployment: str = "text-embedding-ada-002",
+        azure_deployment: str = "text-embedding-3-small",
         dimensions: int | None = None,
         api_key: Secret | None = Secret.from_env_var("AZURE_OPENAI_API_KEY", strict=False),
         azure_ad_token: Secret | None = Secret.from_env_var("AZURE_OPENAI_AD_TOKEN", strict=False),
@@ -60,7 +60,7 @@ def __init__(  # noqa: PLR0913
         :param api_version:
             The version of the API to use.
         :param azure_deployment:
-            The name of the model deployed on Azure. The default model is text-embedding-ada-002.
+            The name of the model deployed on Azure. The default is `text-embedding-3-small`.
         :param dimensions:
             The number of dimensions the resulting output embeddings should have. Only supported in text-embedding-3
             and later models.

haystack/components/embedders/openai_document_embedder.py

@@ -42,7 +42,7 @@ class OpenAIDocumentEmbedder:
     def __init__(  # noqa: PLR0913 (too-many-arguments)
         self,
         api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"),
-        model: str = "text-embedding-ada-002",
+        model: str = "text-embedding-3-small",
         dimensions: int | None = None,
         api_base_url: str | None = None,
         organization: str | None = None,
@@ -71,7 +71,7 @@ def __init__(  # noqa: PLR0913 (too-many-arguments)
             during initialization.
         :param model:
             The name of the model to use for calculating embeddings.
-            The default model is `text-embedding-ada-002`.
+            The default model is `text-embedding-3-small`.
         :param dimensions:
             The number of dimensions of the resulting embeddings. Only `text-embedding-3` and
             later models support this parameter.

haystack/components/embedders/openai_text_embedder.py

@@ -39,7 +39,7 @@ class OpenAITextEmbedder:
     def __init__(
         self,
         api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"),
-        model: str = "text-embedding-ada-002",
+        model: str = "text-embedding-3-small",
         dimensions: int | None = None,
         api_base_url: str | None = None,
         organization: str | None = None,
@@ -62,7 +62,7 @@ def __init__(
             during initialization.
         :param model:
             The name of the model to use for calculating embeddings.
-            The default model is `text-embedding-ada-002`.
+            The default model is `text-embedding-3-small`.
         :param dimensions:
             The number of dimensions of the resulting embeddings. Only `text-embedding-3` and
             later models support this parameter.

releasenotes/notes/openai-embedder-default-text-embedding-3-small-4e7672049be8c6bd.yaml

@@ -0,0 +1,24 @@
+---
+upgrade:
+  - |
+    The default model for ``OpenAITextEmbedder``, ``OpenAIDocumentEmbedder``,
+    ``AzureOpenAITextEmbedder``, and ``AzureOpenAIDocumentEmbedder`` has been changed
+    from ``text-embedding-ada-002`` to ``text-embedding-3-small``.
+
+    ``text-embedding-3-small`` is roughly 5x cheaper per token than the previous
+    generation ``text-embedding-ada-002`` and scores higher on the MTEB benchmark
+    (see OpenAI's `announcement <https://openai.com/index/new-embedding-models-and-api-updates/>`_).
+
+    To preserve previous behavior, pass ``model="text-embedding-ada-002"``
+    explicitly (or, for the Azure variants,
+    ``azure_deployment="text-embedding-ada-002"``).
+
+    Note for Azure users: ``azure_deployment`` refers to the deployment name in
+    your Azure OpenAI resource, not a model identifier. If you do not already
+    have a ``text-embedding-3-small`` deployment in Azure, you will need to
+    create one or pass the name of an existing deployment explicitly.
+
+    Embeddings generated with the new default model are not compatible with
+    embeddings produced by ``text-embedding-ada-002``. If you have a document
+    store populated with previously-generated embeddings, either keep using
+    the old model explicitly or re-embed your corpus.

test/components/embedders/test_azure_document_embedder.py

@@ -18,8 +18,8 @@ class TestAzureOpenAIDocumentEmbedder:
     def test_init_default(self, monkeypatch):
         monkeypatch.setenv("AZURE_OPENAI_API_KEY", "fake-api-key")
         embedder = AzureOpenAIDocumentEmbedder(azure_endpoint="https://example-resource.azure.openai.com/")
-        assert embedder.azure_deployment == "text-embedding-ada-002"
-        assert embedder.model == "text-embedding-ada-002"
+        assert embedder.azure_deployment == "text-embedding-3-small"
+        assert embedder.model == "text-embedding-3-small"
         assert embedder.dimensions is None
         assert embedder.organization is None
         assert embedder.prefix == ""
@@ -38,8 +38,8 @@ def test_init_with_0_max_retries(self, monkeypatch):
         embedder = AzureOpenAIDocumentEmbedder(
             azure_endpoint="https://example-resource.azure.openai.com/", max_retries=0
         )
-        assert embedder.azure_deployment == "text-embedding-ada-002"
-        assert embedder.model == "text-embedding-ada-002"
+        assert embedder.azure_deployment == "text-embedding-3-small"
+        assert embedder.model == "text-embedding-3-small"
         assert embedder.dimensions is None
         assert embedder.organization is None
         assert embedder.prefix == ""
@@ -62,7 +62,7 @@ def test_to_dict(self, monkeypatch):
                 "api_key": {"env_vars": ["AZURE_OPENAI_API_KEY"], "strict": False, "type": "env_var"},
                 "azure_ad_token": {"env_vars": ["AZURE_OPENAI_AD_TOKEN"], "strict": False, "type": "env_var"},
                 "api_version": "2023-05-15",
-                "azure_deployment": "text-embedding-ada-002",
+                "azure_deployment": "text-embedding-3-small",
                 "dimensions": None,
                 "azure_endpoint": "https://example-resource.azure.openai.com/",
                 "organization": None,

test/components/embedders/test_azure_text_embedder.py

@@ -16,8 +16,8 @@ def test_init_default(self, monkeypatch):
         embedder = AzureOpenAITextEmbedder(azure_endpoint="https://example-resource.azure.openai.com/")
 
         assert embedder.client.api_key == "fake-api-key"
-        assert embedder.azure_deployment == "text-embedding-ada-002"
-        assert embedder.model == "text-embedding-ada-002"
+        assert embedder.azure_deployment == "text-embedding-3-small"
+        assert embedder.model == "text-embedding-3-small"
         assert embedder.dimensions is None
         assert embedder.organization is None
         assert embedder.prefix == ""
@@ -32,8 +32,8 @@ def test_init_with_zero_max_retries(self, monkeypatch):
         embedder = AzureOpenAITextEmbedder(azure_endpoint="https://example-resource.azure.openai.com/", max_retries=0)
 
         assert embedder.client.api_key == "fake-api-key"
-        assert embedder.azure_deployment == "text-embedding-ada-002"
-        assert embedder.model == "text-embedding-ada-002"
+        assert embedder.azure_deployment == "text-embedding-3-small"
+        assert embedder.model == "text-embedding-3-small"
         assert embedder.dimensions is None
         assert embedder.organization is None
         assert embedder.prefix == ""
@@ -51,7 +51,7 @@ def test_to_dict_default(self, monkeypatch):
             "init_parameters": {
                 "api_key": {"env_vars": ["AZURE_OPENAI_API_KEY"], "strict": False, "type": "env_var"},
                 "azure_ad_token": {"env_vars": ["AZURE_OPENAI_AD_TOKEN"], "strict": False, "type": "env_var"},
-                "azure_deployment": "text-embedding-ada-002",
+                "azure_deployment": "text-embedding-3-small",
                 "dimensions": None,
                 "organization": None,
                 "azure_endpoint": "https://example-resource.azure.openai.com/",

test/components/embedders/test_openai_document_embedder.py

@@ -19,7 +19,7 @@ def test_init_default(self, monkeypatch):
         monkeypatch.setenv("OPENAI_API_KEY", "fake-api-key")
         embedder = OpenAIDocumentEmbedder()
         assert embedder.api_key.resolve_value() == "fake-api-key"
-        assert embedder.model == "text-embedding-ada-002"
+        assert embedder.model == "text-embedding-3-small"
         assert embedder.organization is None
         assert embedder.prefix == ""
         assert embedder.suffix == ""
@@ -98,7 +98,7 @@ def test_to_dict(self, monkeypatch):
             "init_parameters": {
                 "api_key": {"env_vars": ["OPENAI_API_KEY"], "strict": True, "type": "env_var"},
                 "api_base_url": None,
-                "model": "text-embedding-ada-002",
+                "model": "text-embedding-3-small",
                 "dimensions": None,
                 "organization": None,
                 "http_client_kwargs": None,

test/components/embedders/test_openai_text_embedder.py

@@ -18,7 +18,7 @@ def test_init_default(self, monkeypatch):
         embedder = OpenAITextEmbedder()
 
         assert embedder.client.api_key == "fake-api-key"
-        assert embedder.model == "text-embedding-ada-002"
+        assert embedder.model == "text-embedding-3-small"
         assert embedder.api_base_url is None
         assert embedder.organization is None
         assert embedder.prefix == ""
@@ -83,7 +83,7 @@ def test_to_dict(self, monkeypatch):
                 "api_key": {"env_vars": ["OPENAI_API_KEY"], "strict": True, "type": "env_var"},
                 "api_base_url": None,
                 "dimensions": None,
-                "model": "text-embedding-ada-002",
+                "model": "text-embedding-3-small",
                 "organization": None,
                 "http_client_kwargs": None,
                 "prefix": "",
@@ -153,7 +153,7 @@ def test_prepare_input(self, monkeypatch):
         inp = "The food was delicious"
         prepared_input = embedder._prepare_input(inp)
         assert prepared_input == {
-            "model": "text-embedding-ada-002",
+            "model": "text-embedding-3-small",
             "input": "The food was delicious",
             "encoding_format": "float",
             "dimensions": 1536,