ibm-watsonx-ai Embedding

Available in Zilla Plus

Defines an embedding provider backed by IBM watsonx.ai's hosted text-embeddings models, either the public IBM Cloud SaaS service or a Cloud Pak for Data (CP4D) deployment. An embedding turns a string of text into a fixed-size numeric vector, for use by consumers that need semantic similarity (e.g. cosine-similarity ranking) rather than exact-match lookup -- for example, binding-mcp-ext's semantic tool-search index.

embeddings:
  mcp_tools:
    type: ibm-watsonx-ai
    options:
      endpoint: https://us-south.ml.cloud.ibm.com
      project: ${{env.WATSONX_PROJECT_ID}}
      model: ibm/slate-125m-english-rtrvr
      credentials:
        api-key: ${{env.WATSONX_API_KEY}}

Authentication

Which credential exchange is used follows from where the model is hosted -- the IBM Cloud SaaS service or a CP4D cluster -- and, for CP4D, which credentials are supplied:

• IBM Cloud SaaS (options.region, or an options.endpoint on the *.ml.cloud.ibm.com host) + credentials.api-key -- exchanges the API key for a short-lived bearer token via https://iam.cloud.ibm.com/identity/token. The token is cached and proactively refreshed before it expires, so ordinary requests never wait on the token exchange once a token has been established.
• CP4D (options.endpoint set to the cluster URL) + credentials.username + credentials.password -- CP4D's own internal IAM token exchange: a POST to the cluster's /idprovider/v1/auth/identitytoken, followed by a GET to /v1/preauth/validateAuth to obtain the final access token. Cached and refreshed the same way as the SaaS token.
• CP4D + credentials.username + credentials.api-key -- CP4D's Zen API key mode. No token exchange at all: the Authorization header is computed once, locally, as ZenApiKey base64(username:api-key).

A 401 response from the embeddings endpoint invalidates any cached token so the next request re-authenticates (not applicable to Zen API key mode, which holds no token to invalidate).

Configuration (* required)

options*

object

The ibm-watsonx-ai specific options.

options:
  region: us-south
  project: 11111111-2222-3333-4444-555555555555
  model: ibm/slate-125m-english-rtrvr
  credentials:
    api-key: ${{env.WATSONX_API_KEY}}

options.region

string

IBM Cloud region hosting the model, e.g. us-south. Resolves to https://<region>.ml.cloud.ibm.com. Exactly one of options.region or options.endpoint is required.

options.endpoint

string

The watsonx.ai service endpoint URL, either an IBM Cloud SaaS region host (e.g. https://us-south.ml.cloud.ibm.com) or a CP4D cluster URL (e.g. https://cpd-namespace.apps.mycluster.example.com). Exactly one of options.region or options.endpoint is required.

options.project

string

The watsonx.ai project id hosting the deployed model, e.g. 11111111-2222-3333-4444-555555555555. Must be a UUID. Exactly one of options.project or options.space is required.

options.space

string

The watsonx.ai deployment space id hosting the deployed model. Must be a UUID. Exactly one of options.project or options.space is required.

options.model*

string

The watsonx.ai embedding model, e.g. ibm/slate-125m-english-rtrvr or ibm/granite-embedding-107m-multilingual.

options.credentials*

object

Authentication material. Its shape selects the credential exchange, per Authentication above: api-key alone, username + password, or username + api-key. When options.region is set, or options.endpoint resolves to an IBM Cloud SaaS host, only the api-key-alone shape is accepted.

options:
  credentials:
    api-key: ${{env.WATSONX_API_KEY}}

credentials.username

string

CP4D username. Required together with either credentials.password or credentials.api-key; not valid for the IBM Cloud SaaS service.

credentials.password

string

CP4D password, exchanged via CP4D's internal IAM token endpoint. Mutually exclusive with credentials.api-key; requires credentials.username.

credentials.api-key

string

Either an IBM Cloud IAM API key (when used alone, against the SaaS service or a region), or a CP4D Zen API key (when paired with credentials.username, against a CP4D cluster). Typically supplied via an environment variable, e.g. ${{env.WATSONX_API_KEY}}, rather than inlined directly.

Engine Properties

Two engine-level properties, set with zilla start -P, affect every ibm-watsonx-ai embedding:

Property	Default	Purpose
zilla.embedding.ibm.watsonx.ai.iam.endpoint	https://iam.cloud.ibm.com/identity/token	IBM Cloud IAM token endpoint used for the SaaS api-key exchange.
zilla.embedding.ibm.watsonx.ai.mode	(auto)	Overrides automatic SaaS-vs-CP4D detection. Accepts cloud or cp4d. By default, an options.endpoint on the *.ml.cloud.ibm.com host (or any options.region) resolves to cloud; anything else resolves to cp4d. Useful when a non-standard hostname (e.g. a local mock endpoint in a test) needs to be forced to one mode or the other.