From f6b9d760a92fa579080cb359bb403dcd2bbf324d Mon Sep 17 00:00:00 2001 From: davidsbatista <7937824+davidsbatista@users.noreply.github.com> Date: Thu, 24 Sep 2026 15:06:03 +0000 Subject: [PATCH] Sync Core Integrations API reference (ollama) on Docusaurus --- .../integrations-api/ollama.md | 475 ++++++++++++++++++ 1 file changed, 475 insertions(+) create mode 100644 docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/ollama.md diff --git a/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/ollama.md b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/ollama.md new file mode 100644 index 00000000000..f6654a31ec5 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-3.2-unstable/integrations-api/ollama.md @@ -0,0 +1,475 @@ +--- +title: "Ollama" +id: integrations-ollama +description: "Ollama integration for Haystack" +slug: "/integrations-ollama" +--- + + +## haystack_integrations.components.embedders.ollama.document_embedder + +### OllamaDocumentEmbedder + +Computes the embeddings of a list of Documents and stores the obtained vectors in each Document's embedding field. + +It uses embedding models compatible with the Ollama Library. + +Usage example: + +```python +from haystack import Document +from haystack_integrations.components.embedders.ollama import OllamaDocumentEmbedder + +doc = Document(content="What do llamas say once you have thanked them? No probllama!") +document_embedder = OllamaDocumentEmbedder() + +result = document_embedder.run([doc]) +print(result['documents'][0].embedding) +``` + +#### __init__ + +```python +__init__( + model: str = "nomic-embed-text", + url: str = "http://localhost:11434", + generation_kwargs: dict[str, Any] | None = None, + timeout: int = 120, + keep_alive: float | str | None = None, + prefix: str = "", + suffix: str = "", + progress_bar: bool = True, + meta_fields_to_embed: list[str] | None = None, + embedding_separator: str = "\n", + batch_size: int = 32, + dimensions: int | None = None, +) -> None +``` + +Create a new OllamaDocumentEmbedder instance. + +**Parameters:** + +- **model** (str) – The name of the model to use. The model should be available in the running Ollama instance. +- **url** (str) – The URL of a running Ollama instance. +- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature, top_p, and others. + See the available arguments in + [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). +- **timeout** (int) – The number of seconds before throwing a timeout error from the Ollama API. +- **keep_alive** (float | str | None) – The option that controls how long the model will stay loaded into memory following the request. + If not set, it will use the default value from the Ollama (5 minutes). + The value can be set to: +- a duration string (such as "10m" or "24h") +- a number in seconds (such as 3600) +- any negative number which will keep the model loaded in memory (e.g. -1 or "-1m") +- '0' which will unload the model immediately after generating a response. +- **prefix** (str) – A string to add at the beginning of each text. +- **suffix** (str) – A string to add at the end of each text. +- **progress_bar** (bool) – If `True`, shows a progress bar when running. +- **meta_fields_to_embed** (list\[str\] | None) – List of metadata fields to embed along with the document text. +- **embedding_separator** (str) – Separator used to concatenate the metadata fields to the document text. +- **batch_size** (int) – Number of documents to process at once. +- **dimensions** (int | None) – The desired number of dimensions in the embedding output. Only supported by models + that implement Matryoshka Representation Learning (MRL), such as nomic-embed-text-v1.5, + mxbai-embed-large, and qwen3-embedding. If None (default), the full vector is returned. + Requires ollama-python >= 0.6.2. + +#### warm_up + +```python +warm_up() -> None +``` + +Create the synchronous Ollama client. + +#### warm_up_async + +```python +warm_up_async() -> None +``` + +Create the asynchronous Ollama client. + +#### close + +```python +close() -> None +``` + +Close the synchronous Ollama client. + +#### close_async + +```python +close_async() -> None +``` + +Close the asynchronous Ollama client. + +#### run + +```python +run( + documents: list[Document], generation_kwargs: dict[str, Any] | None = None +) -> dict[str, list[Document] | dict[str, Any]] +``` + +Runs an Ollama Model to compute embeddings of the provided documents. + +**Parameters:** + +- **documents** (list\[Document\]) – Documents to be converted to an embedding. +- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature, + top_p, etc. See the + [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). + +**Returns:** + +- dict\[str, list\[Document\] | dict\[str, Any\]\] – A dictionary with the following keys: +- `documents`: Documents with embedding information attached +- `meta`: The metadata collected during the embedding process + +#### run_async + +```python +run_async( + documents: list[Document], generation_kwargs: dict[str, Any] | None = None +) -> dict[str, list[Document] | dict[str, Any]] +``` + +Asynchronously run an Ollama Model to compute embeddings of the provided documents. + +**Parameters:** + +- **documents** (list\[Document\]) – Documents to be converted to an embedding. +- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature, + top_p, etc. See the + [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). + +**Returns:** + +- dict\[str, list\[Document\] | dict\[str, Any\]\] – A dictionary with the following keys: +- `documents`: Documents with embedding information attached +- `meta`: The metadata collected during the embedding process + +## haystack_integrations.components.embedders.ollama.text_embedder + +### OllamaTextEmbedder + +Computes the embeddings of a string using embedding models compatible with the Ollama Library. + +Usage example: + +```python +from haystack_integrations.components.embedders.ollama import OllamaTextEmbedder + +embedder = OllamaTextEmbedder() +result = embedder.run(text="What do llamas say once you have thanked them? No probllama!") +print(result['embedding']) +``` + +#### __init__ + +```python +__init__( + model: str = "nomic-embed-text", + url: str = "http://localhost:11434", + generation_kwargs: dict[str, Any] | None = None, + timeout: int = 120, + keep_alive: float | str | None = None, + dimensions: int | None = None, +) -> None +``` + +Create a new OllamaTextEmbedder instance. + +**Parameters:** + +- **model** (str) – The name of the model to use. The model should be available in the running Ollama instance. +- **url** (str) – The URL of a running Ollama instance. +- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature, + top_p, and others. See the available arguments in + [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). +- **timeout** (int) – The number of seconds before throwing a timeout error from the Ollama API. +- **keep_alive** (float | str | None) – The option that controls how long the model will stay loaded into memory following the request. + If not set, it will use the default value from the Ollama (5 minutes). + The value can be set to: +- a duration string (such as "10m" or "24h") +- a number in seconds (such as 3600) +- any negative number which will keep the model loaded in memory (e.g. -1 or "-1m") +- '0' which will unload the model immediately after generating a response. +- **dimensions** (int | None) – The desired number of dimensions in the embedding output. Only supported by models + that implement Matryoshka Representation Learning (MRL), such as nomic-embed-text-v1.5, + mxbai-embed-large, and qwen3-embedding. If None (default), the full vector is returned. + +#### warm_up + +```python +warm_up() -> None +``` + +Create the synchronous Ollama client. + +#### warm_up_async + +```python +warm_up_async() -> None +``` + +Create the asynchronous Ollama client. + +#### close + +```python +close() -> None +``` + +Close the synchronous Ollama client. + +#### close_async + +```python +close_async() -> None +``` + +Close the asynchronous Ollama client. + +#### run + +```python +run( + text: str, generation_kwargs: dict[str, Any] | None = None +) -> dict[str, list[float] | dict[str, Any]] +``` + +Runs an Ollama Model to compute embeddings of the provided text. + +**Parameters:** + +- **text** (str) – Text to be converted to an embedding. +- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature, + top_p, etc. See the + [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). + +**Returns:** + +- dict\[str, list\[float\] | dict\[str, Any\]\] – A dictionary with the following keys: +- `embedding`: The computed embeddings +- `meta`: The metadata collected during the embedding process + +#### run_async + +```python +run_async( + text: str, generation_kwargs: dict[str, Any] | None = None +) -> dict[str, list[float] | dict[str, Any]] +``` + +Asynchronously run an Ollama Model to compute embeddings of the provided text. + +**Parameters:** + +- **text** (str) – Text to be converted to an embedding. +- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature, + top_p, etc. See the + [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). + +**Returns:** + +- dict\[str, list\[float\] | dict\[str, Any\]\] – A dictionary with the following keys: +- `embedding`: The computed embeddings +- `meta`: The metadata collected during the embedding process + +## haystack_integrations.components.generators.ollama.chat.chat_generator + +### OllamaChatGenerator + +Haystack Chat Generator for models served with Ollama (https://ollama.ai). + +Supports streaming, tool calls, reasoning, and structured outputs. + +Usage example: + +```python +from haystack_integrations.components.generators.ollama.chat import OllamaChatGenerator +from haystack.dataclasses import ChatMessage + +llm = OllamaChatGenerator(model="qwen3:0.6b") +result = llm.run(messages=[ChatMessage.from_user("What is the capital of France?")]) +print(result) +``` + +#### __init__ + +```python +__init__( + model: str = "qwen3:0.6b", + url: str = "http://localhost:11434", + generation_kwargs: dict[str, Any] | None = None, + timeout: int = 120, + max_retries: int = 0, + keep_alive: float | str | None = None, + streaming_callback: Callable[[StreamingChunk], None] | None = None, + tools: ToolsType | None = None, + response_format: None | Literal["json"] | JsonSchemaValue | None = None, + think: bool | Literal["low", "medium", "high"] = False, +) -> None +``` + +Create a new OllamaChatGenerator instance. + +**Parameters:** + +- **model** (str) – The name of the model to use. The model must already be present (pulled) in the running Ollama instance. +- **url** (str) – The base URL of the Ollama server (default "http://localhost:11434"). +- **generation_kwargs** (dict\[str, Any\] | None) – Optional arguments to pass to the Ollama generation endpoint, such as temperature, + top_p, and others. See the available arguments in + [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). +- **timeout** (int) – The number of seconds before throwing a timeout error from the Ollama API. +- **max_retries** (int) – Maximum number of retries to attempt for failed requests (HTTP 429, 5xx, connection/timeout errors). + Uses exponential backoff between attempts. Set to 0 (default) to disable retries. +- **think** (bool | Literal['low', 'medium', 'high']) – If True, the model will "think" before producing a response. + Only [thinking models](https://ollama.com/search?c=thinking) support this feature. + Some models like gpt-oss support different levels of thinking: "low", "medium", "high". + The intermediate "thinking" output can be found by inspecting the `reasoning` property of the returned + `ChatMessage`. +- **keep_alive** (float | str | None) – The option that controls how long the model will stay loaded into memory following the request. + If not set, it will use the default value from the Ollama (5 minutes). + The value can be set to: +- a duration string (such as "10m" or "24h") +- a number in seconds (such as 3600) +- any negative number which will keep the model loaded in memory (e.g. -1 or "-1m") +- '0' which will unload the model immediately after generating a response. +- **streaming_callback** (Callable\\[[StreamingChunk\], None\] | None) – A callback function that is called when a new token is received from the stream. + The callback function accepts StreamingChunk as an argument. +- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. + Each tool should have a unique name. Not all models support tools. For a list of models compatible + with tools, see the [models page](https://ollama.com/search?c=tools). +- **response_format** (None | Literal['json'] | JsonSchemaValue | None) – The format for structured model outputs. The value can be: +- None: No specific structure or format is applied to the response. The response is returned as-is. +- "json": The response is formatted as a JSON object. +- JSON Schema: The response is formatted as a JSON object + that adheres to the specified JSON Schema. (needs Ollama ≥ 0.1.34) + +#### warm_up + +```python +warm_up() -> None +``` + +Create the synchronous Ollama client. + +#### warm_up_async + +```python +warm_up_async() -> None +``` + +Create the asynchronous Ollama client. + +#### close + +```python +close() -> None +``` + +Close the synchronous Ollama client. + +#### close_async + +```python +close_async() -> None +``` + +Close the asynchronous Ollama client. + +#### to_dict + +```python +to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns:** + +- dict\[str, Any\] – Dictionary with serialized data. + +#### from_dict + +```python +from_dict(data: dict[str, Any]) -> OllamaChatGenerator +``` + +Deserializes the component from a dictionary. + +**Parameters:** + +- **data** (dict\[str, Any\]) – Dictionary to deserialize from. + +**Returns:** + +- OllamaChatGenerator – Deserialized component. + +#### run + +```python +run( + messages: list[ChatMessage] | str, + generation_kwargs: dict[str, Any] | None = None, + tools: ToolsType | None = None, + *, + streaming_callback: StreamingCallbackT | None = None +) -> dict[str, list[ChatMessage]] +``` + +Runs an Ollama Model on a given chat history. + +**Parameters:** + +- **messages** (list\[ChatMessage\] | str) – A list of ChatMessage instances representing the input messages. If a string is provided, it is converted + to a list containing a ChatMessage with user role. +- **generation_kwargs** (dict\[str, Any\] | None) – Per-call overrides for Ollama inference options. + These are merged on top of the instance-level `generation_kwargs`. + Optional arguments to pass to the Ollama generation endpoint, such as temperature, top_p, etc. See the + [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). +- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. + If set, it will override the `tools` parameter set during component initialization. +- **streaming_callback** (StreamingCallbackT | None) – A callable to receive `StreamingChunk` objects as they + arrive. Supplying a callback (here or in the constructor) switches + the component into streaming mode. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys: +- `replies`: A list of ChatMessages containing the model's response + +#### run_async + +```python +run_async( + messages: list[ChatMessage] | str, + generation_kwargs: dict[str, Any] | None = None, + tools: ToolsType | None = None, + *, + streaming_callback: StreamingCallbackT | None = None +) -> dict[str, list[ChatMessage]] +``` + +Async version of run. Runs an Ollama Model on a given chat history. + +**Parameters:** + +- **messages** (list\[ChatMessage\] | str) – A list of ChatMessage instances representing the input messages. If a string is provided, it is converted + to a list containing a ChatMessage with user role. +- **generation_kwargs** (dict\[str, Any\] | None) – Per-call overrides for Ollama inference options. + These are merged on top of the instance-level `generation_kwargs`. +- **tools** (ToolsType | None) – A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. + If set, it will override the `tools` parameter set during component initialization. +- **streaming_callback** (StreamingCallbackT | None) – A callable to receive `StreamingChunk` objects as they arrive. + Supplying a callback switches the component into streaming mode. + +**Returns:** + +- dict\[str, list\[ChatMessage\]\] – A dictionary with the following keys: +- `replies`: A list of ChatMessages containing the model's response