openai: Update API Reference docs for AzureOpenAI Embeddings (#25312)

Update AzureOpenAI Embeddings docs

Author: eyurtsev

libs/partners/openai/langchain_openai/embeddings/azure.py

@@ -13,19 +13,92 @@
 
 
 class AzureOpenAIEmbeddings(OpenAIEmbeddings):
-    """`Azure OpenAI` Embeddings API.
+    """AzureOpenAI embedding model integration.
 
-    To use, you should have the
-    environment variable ``AZURE_OPENAI_API_KEY`` set with your API key or pass it
-    as a named parameter to the constructor.
+    Setup:
+        To access AzureOpenAI embedding models you'll need to create an Azure account,
+        get an API key, and install the `langchain-openai` integration package.
 
-    Example:
+        You’ll need to have an Azure OpenAI instance deployed.
+        You can deploy a version on Azure Portal following this
+        [guide](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/create-resource?pivots=web-portal).
+
+        Once you have your instance running, make sure you have the name of your
+        instance and key. You can find the key in the Azure Portal,
+        under the “Keys and Endpoint” section of your instance.
+
+        .. code-block:: bash
+
+            pip install -U langchain_openai
+
+            # Set up your environment variables (or pass them directly to the model)
+            export AZURE_OPENAI_API_KEY="your-api-key"
+            export AZURE_OPENAI_ENDPOINT="https://<your-endpoint>.openai.azure.com/"
+            export AZURE_OPENAI_API_VERSION="2024-02-01"
+
+    Key init args — completion params:
+        model: str
+            Name of AzureOpenAI model to use.
+        dimensions: Optional[int]
+            Number of dimensions for the embeddings. Can be specified only
+            if the underlying model supports it.
+
+    Key init args — client params:
+      api_key: Optional[SecretStr]
+
+    See full list of supported init args and their descriptions in the params section.
+
+    Instantiate:
         .. code-block:: python
 
             from langchain_openai import AzureOpenAIEmbeddings
 
-            openai = AzureOpenAIEmbeddings(model="text-embedding-3-large")
-    """
+            embeddings = AzureOpenAIEmbeddings(
+                model="text-embedding-3-large"
+                # dimensions: Optional[int] = None, # Can specify dimensions with new text-embedding-3 models
+                # azure_endpoint="https://<your-endpoint>.openai.azure.com/", If not provided, will read env variable AZURE_OPENAI_ENDPOINT
+                # api_key=... # Can provide an API key directly. If missing read env variable AZURE_OPENAI_API_KEY
+                # openai_api_version=..., # If not provided, will read env variable AZURE_OPENAI_API_VERSION
+            )
+
+    Embed single text:
+        .. code-block:: python
+
+            input_text = "The meaning of life is 42"
+            vector = embed.embed_query(input_text)
+            print(vector[:3])
+
+        .. code-block:: python
+
+            [-0.024603435769677162, -0.007543657906353474, 0.0039630369283258915]
+
+    Embed multiple texts:
+        .. code-block:: python
+
+             input_texts = ["Document 1...", "Document 2..."]
+            vectors = embed.embed_documents(input_texts)
+            print(len(vectors))
+            # The first 3 coordinates for the first vector
+            print(vectors[0][:3])
+
+        .. code-block:: python
+
+            2
+            [-0.024603435769677162, -0.007543657906353474, 0.0039630369283258915]
+
+    Async:
+        .. code-block:: python
+
+            vector = await embed.aembed_query(input_text)
+           print(vector[:3])
+
+            # multiple:
+            # await embed.aembed_documents(input_texts)
+
+        .. code-block:: python
+
+            [-0.009100092574954033, 0.005071679595857859, -0.0029193938244134188]
+    """  # noqa: E501
 
     azure_endpoint: Union[str, None] = None
     """Your Azure endpoint, including the resource.