> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IBM watsonx

Generate text embeddings using IBM's watsonx.ai platform.

## Supported Models

You can find a list of supported models at [IBM watsonx.ai Documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models-embed.html?context=wx). The currently supported model names are:

| Model ID | Dimensions |
| - | - |
| `ibm/granite-embedding-278m-multilingual` | 768 |
| `ibm/slate-125m-english-rtrvr-v2` | 768 |
| `ibm/slate-30m-english-rtrvr-v2` | 384 |
| `intfloat/multilingual-e5-large` | 1024 |

> [!NOTE]
>
> For new tables, pass `name="ibm/granite-embedding-278m-multilingual"`. The default `name` is still the legacy `ibm/slate-125m-english-rtrvr`, so tables created with it reload with the same model. Legacy and deprecated IDs (such as `ibm/slate-125m-english-rtrvr`, `sentence-transformers/all-minilm-l6-v2` and `sentence-transformers/all-minilm-l12-v2`) still work for tables whose stored metadata references them, but they aren't listed above for new use.

## Parameters

The following parameters can be passed to the `create` method:

| Parameter | Type | Default Value | Description |
| - | - | - | - |
| name | str | `"ibm/slate-125m-english-rtrvr"` | The model ID of the watsonx.ai model to use. Pass one of the current supported IDs above (e.g. `"ibm/granite-embedding-278m-multilingual"`) when creating new tables. |
| api\_key | str | None | Optional IBM Cloud API key (or set `WATSONX_API_KEY`) |
| project\_id | str | None | Optional watsonx project ID (or set `WATSONX_PROJECT_ID`). Mutually exclusive with `space_id`. |
| space\_id | str | None | Optional watsonx deployment space ID (or set `WATSONX_SPACE_ID`). Mutually exclusive with `project_id`. |
| url | str | None | Optional custom URL for the watsonx.ai instance |
| params | dict | None | Optional additional parameters for the embedding model (e.g. `{"truncate_input_tokens": 512}`) |

> [!NOTE]
>
> You must supply exactly one of `project_id` or `space_id` (either as an argument or via its environment variable). Setting both, or neither, raises a `ValueError`.

## Usage Example

First, the watsonx.ai library is an optional dependency, so must be installed separately:

```
pip install ibm-watsonx-ai
```

Optionally set environment variables (if not passing credentials to `create` directly):

```bash Bash icon="terminal" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
export WATSONX_API_KEY="YOUR_WATSONX_API_KEY"
# Provide exactly one of the following:
export WATSONX_PROJECT_ID="YOUR_WATSONX_PROJECT_ID"
# export WATSONX_SPACE_ID="YOUR_WATSONX_SPACE_ID"
```

Replace the credential placeholders with your provider credentials. The registry
variable keeps the API key out of stored embedding configuration. In application
code, load its value from environment variables or a secrets manager.

```python Python icon="python" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
import tempfile
from pathlib import Path

import lancedb
from lancedb.embeddings import EmbeddingFunctionRegistry
from lancedb.pydantic import LanceModel, Vector

registry = EmbeddingFunctionRegistry.get_instance()
registry.set_var("watsonx-api-key", "your-api-key")
watsonx_embed = registry.get("watsonx").create(
    name="ibm/slate-125m-english-rtrvr",
    api_key="$var:watsonx-api-key",
    project_id="your-project-id",
)

class TextModel(LanceModel):
    text: str = watsonx_embed.SourceField()
    vector: Vector(watsonx_embed.ndims()) = watsonx_embed.VectorField()

data = [
    {"text": "hello world"},
    {"text": "goodbye world"},
]

db = lancedb.connect(str(Path(tempfile.mkdtemp()) / "watsonx-demo"))
tbl = db.create_table("watsonx_test", schema=TextModel, mode="overwrite")
tbl.add(data)

rs = tbl.search("hello").limit(1).to_pandas()
print(rs.head())
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.