WatsonxEmbeddings integration

WatsonxEmbeddings is a wrapper for IBM watsonx.ai foundation models.

This example shows how to communicate with watsonx.ai models using LangChain.

Overview

Integration details

Setup

To access IBM watsonx.ai models you’ll need to create an IBM watsonx.ai account, get an API key, and install the langchain-ibm integration package.

Credentials

This cell defines the WML credentials required to work with watsonx Embeddings. Action: Provide the IBM Cloud user API key. For details, see documentation.

import os
from getpass import getpass

watsonx_api_key = getpass()
os.environ["WATSONX_APIKEY"] = watsonx_api_key

Additionally you are able to pass additional secrets as an environment variable.

import os

os.environ["WATSONX_URL"] = "your service instance url"
os.environ["WATSONX_TOKEN"] = "your token for accessing the CLOUD or CPD cluster"
os.environ["WATSONX_PASSWORD"] = "your password for accessing the CPD cluster"
os.environ["WATSONX_USERNAME"] = "your username for accessing the CPD cluster"
os.environ["WATSONX_INSTANCE_ID"] = "your instance_id for accessing the CPD cluster"

Installation

The LangChain IBM integration lives in the langchain-ibm package:

!pip install -qU langchain-ibm

Instantiation

You might need to adjust model parameters for different models.

from ibm_watsonx_ai.metanames import EmbedTextParamsMetaNames

embed_params = {
    EmbedTextParamsMetaNames.TRUNCATE_INPUT_TOKENS: 3,
    EmbedTextParamsMetaNames.RETURN_OPTIONS: {"input_text": True},
}

Initialize the WatsonxEmbeddings class with previously set parameters. Note:

To provide context for the API call, you must add project_id or space_id. For more information see documentation.
Depending on the region of your provisioned service instance, use one of the region-specific authentication URLs.

In this example, we’ll use the project_id and Dallas url. You need to specify model_id that will be used for inferencing.

from langchain_ibm import WatsonxEmbeddings

watsonx_embedding = WatsonxEmbeddings(
    model_id="ibm/granite-embedding-107m-multilingual",
    url="https://us-south.ml.cloud.ibm.com",
    project_id="PASTE YOUR PROJECT_ID HERE",
    params=embed_params,
)

Alternatively you can use Cloud Pak for Data credentials. For details, see documentation.

watsonx_embedding = WatsonxEmbeddings(
    model_id="ibm/granite-embedding-107m-multilingual",
    url="PASTE YOUR URL HERE",
    username="PASTE YOUR USERNAME HERE",
    password="PASTE YOUR PASSWORD HERE",
    instance_id="openshift",
    version="4.8",
    project_id="PASTE YOUR PROJECT_ID HERE",
    params=embed_params,
)

For certain requirements, there is an option to pass the IBM’s APIClient object into the WatsonxEmbeddings class.

from ibm_watsonx_ai import APIClient

api_client = APIClient(...)

watsonx_embedding = WatsonxEmbeddings(
    model_id="ibm/granite-embedding-107m-multilingual",
    watsonx_client=api_client,
)

Indexing and retrieval

Embedding models are often used in retrieval-augmented generation (RAG) flows, both as part of indexing data as well as later retrieving it. For more detailed instructions, please see our RAG tutorials. Below, see how to index and retrieve data using the embeddings object we initialized above. In this example, we will index and retrieve a sample document in the InMemoryVectorStore.

# Create a vector store with a sample text
from langchain_core.vectorstores import InMemoryVectorStore

text = "LangChain is the framework for building context-aware reasoning applications"

vectorstore = InMemoryVectorStore.from_texts(
    [text],
    embedding=watsonx_embedding,
)

# Use the vectorstore as a retriever
retriever = vectorstore.as_retriever()

# Retrieve the most similar text
retrieved_documents = retriever.invoke("What is LangChain?")

# show the retrieved document's content
retrieved_documents[0].page_content

'LangChain is the framework for building context-aware reasoning applications'

Direct usage

Under the hood, the vectorstore and retriever implementations are calling embeddings.embed_documents(...) and embeddings.embed_query(...) to create embeddings for the text(s) used in from_texts and retrieval invoke operations, respectively. You can directly call these methods to get embeddings for your own use cases.

Embed single texts

You can embed single texts or documents with embed_query:

text = "This is a test document."

query_result = watsonx_embedding.embed_query(text)
query_result[:5]

[0.009447193, -0.024981951, -0.026013248, -0.040483937, -0.05780445]

Embed multiple texts

You can embed multiple texts with embed_documents:

texts = ["This is a content of the document", "This is another document"]

doc_result = watsonx_embedding.embed_documents(texts)
doc_result[0][:5]

[0.009447167, -0.024981938, -0.02601326, -0.04048393, -0.05780444]

API reference

For detailed documentation of all WatsonxEmbeddings features and configurations head to the API reference.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Popular Providers

Integrations by component

Overview

Integration details

Setup

Credentials

Installation

Instantiation

Indexing and retrieval

Direct usage

Embed single texts

Embed multiple texts

API reference

​Overview

​Integration details

​Setup

​Credentials

​Installation

​Instantiation

​Indexing and retrieval

​Direct usage

​Embed single texts

​Embed multiple texts

​API reference

Overview

Integration details

Setup

Credentials

Installation

Instantiation

Indexing and retrieval

Direct usage

Embed single texts

Embed multiple texts

API reference