improve docstrings (#6170)

Co-authored-by: Daria Fokina <[email protected]>

haystack/preview/components/embedders/openai_document_embedder.py

@@ -13,6 +13,21 @@ class OpenAIDocumentEmbedder:
     """
     A component for computing Document embeddings using OpenAI models.
     The embedding of each Document is stored in the `embedding` field of the Document.
+
+    Usage example:
+    ```python
+    from haystack.preview import Document
+    from haystack.preview.components.embedders import OpenAIDocumentEmbedder
+
+    doc = Document(text="I love pizza!")
+
+    document_embedder = OpenAIDocumentEmbedder()
+
+    result = document_embedder.run([doc])
+    print(result['documents'][0].embedding)
+
+    # [0.017020374536514282, -0.023255806416273117, ...]
+    ```
     """
 
     def __init__(

haystack/preview/components/embedders/openai_text_embedder.py

@@ -10,6 +10,21 @@
 class OpenAITextEmbedder:
     """
     A component for embedding strings using OpenAI models.
+
+    Usage example:
+    ```python
+    from haystack.preview.components.embedders import OpenAITextEmbedder
+
+    text_to_embed = "I love pizza!"
+
+    text_embedder = OpenAITextEmbedder()
+
+    print(text_embedder.run(text_to_embed))
+
+    # {'embedding': [0.017020374536514282, -0.023255806416273117, ...],
+    # 'metadata': {'model': 'text-embedding-ada-002-v2',
+    #              'usage': {'prompt_tokens': 4, 'total_tokens': 4}}}
+    ```
     """
 
     def __init__(
@@ -24,10 +39,11 @@ def __init__(
         Create an OpenAITextEmbedder component.
 
         :param api_key: The OpenAI API key. It can be explicitly provided or automatically read from the
-                        environment variable OPENAI_API_KEY (recommended).
-        :param model_name: The name of the model to use.
-        :param organization: The OpenAI-Organization ID, defaults to `None`. For more details, see OpenAI
-        [documentation](https://platform.openai.com/docs/api-reference/requesting-organization).
+            environment variable OPENAI_API_KEY (recommended).
+        :param model_name: The name of the OpenAI model to use. For more details on the available models,
+            see [OpenAI documentation](https://platform.openai.com/docs/guides/embeddings/embedding-models).
+        :param organization: The OpenAI-Organization ID, defaults to `None`. For more details,
+            see [OpenAI documentation](https://platform.openai.com/docs/api-reference/requesting-organization).
         :param prefix: A string to add to the beginning of each text.
         :param suffix: A string to add to the end of each text.
         """

haystack/preview/components/embedders/sentence_transformers_document_embedder.py

@@ -11,6 +11,20 @@ class SentenceTransformersDocumentEmbedder:
     """
     A component for computing Document embeddings using Sentence Transformers models.
     The embedding of each Document is stored in the `embedding` field of the Document.
+
+    Usage example:
+    ```python
+    from haystack.preview import Document
+    from haystack.preview.components.embedders import SentenceTransformersDocumentEmbedder
+    doc = Document(text="I love pizza!")
+    doc_embedder = SentenceTransformersDocumentEmbedder()
+    doc_embedder.warm_up()
+
+    result = doc_embedder.run([doc])
+    print(result['documents'][0].embedding)
+
+    # [-0.07804739475250244, 0.1498992145061493, ...]
+    ```
     """
 
     def __init__(
@@ -37,6 +51,8 @@ def __init__(
             If this parameter is set to `True`, then the token generated when running
             `transformers-cli login` (stored in ~/.huggingface) will be used.
         :param prefix: A string to add to the beginning of each Document text before embedding.
+            Can be used to prepend the text with an instruction, as required by some embedding models,
+            such as E5 and bge.
         :param suffix: A string to add to the end of each Document text before embedding.
         :param batch_size: Number of strings to encode at once.
         :param progress_bar: If true, displays progress bar during embedding.

haystack/preview/components/embedders/sentence_transformers_text_embedder.py

@@ -10,6 +10,20 @@
 class SentenceTransformersTextEmbedder:
     """
     A component for embedding strings using Sentence Transformers models.
+
+    Usage example:
+    ```python
+    from haystack.preview.components.embedders import SentenceTransformersTextEmbedder
+
+    text_to_embed = "I love pizza!"
+
+    text_embedder = SentenceTransformersTextEmbedder()
+    text_embedder.warm_up()
+
+    print(text_embedder.run(text_to_embed))
+
+    # {'embedding': [-0.07804739475250244, 0.1498992145061493,, ...]}
+    ```
     """
 
     def __init__(
@@ -33,7 +47,9 @@ def __init__(
         :param token: The API token used to download private models from Hugging Face.
             If this parameter is set to `True`, then the token generated when running
             `transformers-cli login` (stored in ~/.huggingface) will be used.
-        :param prefix: A string to add to the beginning of each text.
+        :param prefix: A string to add to the beginning of each Document text before embedding.
+            Can be used to prepend the text with an instruction, as required by some embedding models,
+            such as E5 and bge.
         :param suffix: A string to add to the end of each text.
         :param batch_size: Number of strings to encode at once.
         :param progress_bar: If true, displays progress bar during embedding.