WatsonxEmbeddings

Reference docs

This page contains reference documentation for WatsonxEmbeddings. See the docs for conceptual guides, tutorials, and examples on using WatsonxEmbeddings.

langchain_ibm.embeddings.WatsonxEmbeddings

Bases: BaseModel, Embeddings

IBM watsonx.ai embedding model integration.

Setup

To use, you should have langchain_ibm python package installed, and the environment variable WATSONX_API_KEY set with your API key, or pass it as a named parameter api_key to the constructor.

pip install -U langchain-ibm

# or using uv
uv add langchain-ibm

export WATSONX_API_KEY="your-api-key"

Deprecated

apikey and WATSONX_APIKEY are deprecated and will be removed in version 2.0.0. Use api_key and WATSONX_API_KEY instead.

Instantiate

from langchain_ibm import WatsonxEmbeddings

embeddings = WatsonxEmbeddings(
    model_id="ibm/granite-embedding-278m-multilingual",
    url="https://us-south.ml.cloud.ibm.com",
    project_id="*****",
    # api_key="*****"
)

Embed single text

input_text = "The meaning of life is 42"
vector = embeddings.embed_query("hello")
print(vector[:3])

[-0.0020519258, 0.0147288125, -0.0090887165]

Embed multiple texts

vectors = embeddings.embed_documents(["hello", "goodbye"])
# Showing only the first 3 coordinates
print(len(vectors))
print(vectors[0][:3])

2
[-0.0020519265, 0.01472881, -0.009088721]

Async

await embeddings.aembed_query(input_text)
print(vector[:3])

# multiple:
# await embeddings.aembed_documents(input_texts)

[-0.0020519258, 0.0147288125, -0.0090887165]

METHOD	DESCRIPTION
validate_environment	Validate that credentials and python package exists in environment.
embed_documents	Embed search docs.
aembed_documents	Asynchronous Embed search docs.
embed_query	Embed query text.
aembed_query	Asynchronous Embed query text.

model_id class-attribute instance-attribute

model_id: str | None = None

Type of model to use.

model class-attribute instance-attribute

model: str | None = None

Name or alias of the foundation model to use. When using IBM's watsonx.ai Model Gateway (public preview), you can specify any supported third-party model—OpenAI, Anthropic, NVIDIA, Cerebras, or IBM's own Granite series—via a single, OpenAI-compatible interface. Models must be explicitly provisioned (opt-in) through the Gateway to ensure secure, vendor-agnostic access and easy switch-over without reconfiguration.

For more details on configuration and usage, see IBM watsonx Model Gateway docs

project_id class-attribute instance-attribute

project_id: str | None = None

ID of the Watson Studio project.

space_id class-attribute instance-attribute

space_id: str | None = None

ID of the Watson Studio space.

url class-attribute instance-attribute

url: SecretStr = Field(
    alias="url", default_factory=secret_from_env("WATSONX_URL", default=None)
)

URL to the Watson Machine Learning or CPD instance.

api_key class-attribute instance-attribute

api_key: SecretStr | None = Field(
    default_factory=secret_from_env_multi(
        names_priority=["WATSONX_API_KEY", "WATSONX_APIKEY"],
        deprecated={"WATSONX_APIKEY"},
    ),
    serialization_alias="api_key",
    validation_alias=AliasChoices("api_key", "apikey"),
    description="API key to the Watson Machine Learning or CPD instance.",
)

API key to the Watson Machine Learning or CPD instance.

token class-attribute instance-attribute

token: SecretStr | None = Field(
    alias="token", default_factory=secret_from_env("WATSONX_TOKEN", default=None)
)

Token to the CPD instance.

password class-attribute instance-attribute

password: SecretStr | None = Field(
    alias="password", default_factory=secret_from_env("WATSONX_PASSWORD", default=None)
)

Password to the CPD instance.

username class-attribute instance-attribute

username: SecretStr | None = Field(
    alias="username", default_factory=secret_from_env("WATSONX_USERNAME", default=None)
)

Username to the CPD instance.

instance_id class-attribute instance-attribute

instance_id: SecretStr | None = Field(
    alias="instance_id",
    default_factory=secret_from_env("WATSONX_INSTANCE_ID", default=None),
)

Instance_id of the CPD instance.

version class-attribute instance-attribute

version: SecretStr | None = None

Version of the CPD instance.

params class-attribute instance-attribute

params: dict | None = None

Model parameters to use during request generation.

verify class-attribute instance-attribute

verify: str | bool | None = None

You can pass one of following as verify: * the path to a CA_BUNDLE file * the path of directory with certificates of trusted CAs * True - default path to truststore will be taken * False - no verification will be made

validate_environment

validate_environment() -> Self

Validate that credentials and python package exists in environment.

embed_documents

embed_documents(texts: list[str], **kwargs: Any) -> list[list[float]]

Embed search docs.

aembed_documents async

aembed_documents(texts: list[str], **kwargs: Any) -> list[list[float]]

Asynchronous Embed search docs.

embed_query

embed_query(text: str, **kwargs: Any) -> list[float]

Embed query text.

aembed_query async

aembed_query(text: str, **kwargs: Any) -> list[float]

Asynchronous Embed query text.