1  ---
  2  title: "OpenAIDocumentEmbedder"
  3  id: openaidocumentembedder
  4  slug: "/openaidocumentembedder"
  5  description: "OpenAIDocumentEmbedder computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses OpenAI embedding models."
  6  ---
  7  
  8  # OpenAIDocumentEmbedder
  9  
 10  OpenAIDocumentEmbedder computes the embeddings of a list of documents and stores the obtained vectors in the embedding field of each document. It uses OpenAI embedding models.
 11  
 12  The vectors computed by this component are necessary to perform embedding retrieval on a collection of documents. At retrieval time, the vector representing the query is compared with those of the documents to find the most similar or relevant documents.
 13  
 14  <div className="key-value-table">
 15  
 16  |  |  |
 17  | --- | --- |
 18  | **Most common position in a pipeline** | Before a [`DocumentWriter`](../writers/documentwriter.mdx)  in an indexing pipeline |
 19  | **Mandatory init variables** | `api_key`: An OpenAI API key. Can be set with `OPENAI_API_KEY` env var. |
 20  | **Mandatory run variables** | `documents`: A list of documents |
 21  | **Output variables** | `documents`: A list of documents (enriched with embeddings)  <br /> <br />`meta`: A dictionary of metadata |
 22  | **API reference** | [Embedders](/reference/embedders-api) |
 23  | **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/embedders/openai_document_embedder.py |
 24  
 25  </div>
 26  
 27  ## Overview
 28  
 29  To see the list of compatible OpenAI embedding models, head over to OpenAI [documentation](https://platform.openai.com/docs/guides/embeddings/embedding-models). The default model for `OpenAIDocumentEmbedder` is `text-embedding-ada-002`. You can specify another model with the `model` parameter when initializing this component.
 30  
 31  This component should be used to embed a list of documents. To embed a string, use the [OpenAITextEmbedder](openaitextembedder.mdx).
 32  
 33  The component uses an `OPENAI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
 34  
 35  ```
 36  embedder = OpenAIDocumentEmbedder(api_key=Secret.from_token("<your-api-key>"))
 37  ```
 38  
 39  ### Embedding Metadata
 40  
 41  Text documents often come with a set of metadata. If they are distinctive and semantically meaningful, you can embed them along with the text of the document to improve retrieval.
 42  
 43  You can do this easily by using the Document Embedder:
 44  
 45  ```python
 46  from haystack import Document
 47  from haystack.components.embedders import OpenAIDocumentEmbedder
 48  
 49  doc = Document(content="some text", meta={"title": "relevant title", "page number": 18})
 50  
 51  embedder = OpenAIDocumentEmbedder(meta_fields_to_embed=["title"])
 52  
 53  docs_w_embeddings = embedder.run(documents=[doc])["documents"]
 54  ```
 55  
 56  ## Usage
 57  
 58  ### On its own
 59  
 60  Here is how you can use the component on its own:
 61  
 62  ```python
 63  from haystack.components.embedders import OpenAIDocumentEmbedder
 64  
 65  doc = Document(content="I love pizza!")
 66  
 67  document_embedder = OpenAIDocumentEmbedder(api_key=Secret.from_token("<your-api-key>"))
 68  
 69  result = document_embedder.run([doc])
 70  print(result["documents"][0].embedding)
 71  
 72  ## [0.017020374536514282, -0.023255806416273117, ...]
 73  ```
 74  
 75  :::info
 76  We recommend setting OPENAI_API_KEY as an environment variable instead of setting it as a parameter.
 77  :::
 78  
 79  ### In a pipeline
 80  
 81  ```python
 82  from haystack import Pipeline
 83  from haystack.document_stores.in_memory import InMemoryDocumentStore
 84  from haystack.components.embedders import OpenAITextEmbedder, OpenAIDocumentEmbedder
 85  from haystack.components.writers import DocumentWriter
 86  from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
 87  
 88  document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")
 89  
 90  documents = [
 91      Document(content="My name is Wolfgang and I live in Berlin"),
 92      Document(content="I saw a black horse running"),
 93      Document(content="Germany has many big cities"),
 94  ]
 95  
 96  indexing_pipeline = Pipeline()
 97  indexing_pipeline.add_component("embedder", OpenAIDocumentEmbedder())
 98  indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store))
 99  indexing_pipeline.connect("embedder", "writer")
100  
101  indexing_pipeline.run({"embedder": {"documents": documents}})
102  
103  query_pipeline = Pipeline()
104  query_pipeline.add_component("text_embedder", OpenAITextEmbedder())
105  query_pipeline.add_component(
106      "retriever",
107      InMemoryEmbeddingRetriever(document_store=document_store),
108  )
109  query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
110  
111  query = "Who lives in Berlin?"
112  
113  result = query_pipeline.run({"text_embedder": {"text": query}})
114  
115  print(result["retriever"]["documents"][0])
116  
117  ## Document(id=..., mimetype: 'text/plain',
118  ## text: 'My name is Wolfgang and I live in Berlin')
119  ```