IBM watsonx.ai Python SDK

1.5.6 · active · verified Sat Apr 11

The `ibm-watsonx-ai` library is the official Python SDK for IBM watsonx.ai, an enterprise-grade AI and data platform for building, training, tuning, deploying, and operating AI models at scale. It provides a unified interface to watsonx.ai capabilities, including Foundation Models (LLMs), AutoAI experiments, Retrieval-Augmented Generation (RAG), model tuning, deployment, and data integration. The library is actively maintained with regular updates and new feature releases.

Warnings

breaking The `client.<resource>.list()` methods no longer directly print a table of assets. Instead, they now return a `pandas.DataFrame` object. The `return_as_df` optional parameter has been removed as it is now the default and only behavior.
Fix: Update your code to expect a `pandas.DataFrame` from `.list()` methods. Process the returned DataFrame directly instead of relying on printed output.
breaking Prompt tuning as a method to tune foundation models is no longer supported and all existing prompt tuning deployments will be removed upon upgrading the `watsonx.ai` service. Parameter-efficient fine-tuning (PEFT) techniques like LoRA and QLoRA are now the recommended alternatives.
Fix: Migrate existing prompt tuning deployments to alternative tuning methods, such as LoRA or QLoRA, which are available programmatically. Refer to the official `watsonx.ai` documentation for guidance on new tuning approaches.
deprecated Several foundation models are regularly deprecated and eventually withdrawn. For example, `pixtral-12b` was deprecated in a recent release, and models like `codestral-22b`, `llama-2-13b-chat`, `mistral-small-instruct`, `mistral-large`, and `mixtral-8x7b-instruct-v01` were deprecated in the August 2025 release (IBM Software Hub 5.2.1). Older versions of IBM foundation models remain available for at least 90 days after an update.
Fix: Review your application's use of foundation models. If you are using a deprecated model, migrate to a recommended alternative listed in the `watsonx.ai` documentation. IBM regularly updates its list of supported models.
gotcha For most operations, setting a default `project_id` or `space_id` using `client.set.default_project()` or `client.set.default_space()` is mandatory after initializing `APIClient`. Failure to do so will result in errors.
Fix: Always call `client.set.default_project(your_project_id)` or `client.set.default_space(your_space_id)` after creating the `APIClient` instance, unless you are specifically using a lightweight engine which does not require it.
gotcha When importing PyTorch models into `watsonx.ai`, they must first be exported to the `.onnx` format. Direct import of other PyTorch model formats is not supported.
Fix: Before attempting to import a PyTorch model, ensure it has been converted and exported to the `.onnx` format using `torch.onnx.export()`.

Install

pip install ibm-watsonx-ai Install latest version

Imports

APIClient
```
from ibm_watsonx_ai import APIClient
```
Credentials
```
from ibm_watsonx_ai import Credentials
```

Model

from ibm_watsonx_ai.foundation_models import Model

ModelTypes

from ibm_watsonx_ai.foundation_models.utils.enums import ModelTypes

DecodingMethods

from ibm_watsonx_ai.foundation_models.utils.enums import DecodingMethods

Quickstart

This quickstart demonstrates how to authenticate with the `ibm-watsonx-ai` SDK using environment variables and perform a basic text generation task with a foundation model. Ensure your `IBM_CLOUD_API_KEY`, `WATSONX_AI_URL`, and `WATSONX_PROJECT_ID` environment variables are set.

import os
from ibm_watsonx_ai import APIClient, Credentials
from ibm_watsonx_ai.foundation_models import Model
from ibm_watsonx_ai.foundation_models.utils.enums import ModelTypes, DecodingMethods

# --- Authentication ---
# Set these environment variables: IBM_CLOUD_API_KEY, WATSONX_AI_URL, WATSONX_PROJECT_ID
api_key = os.environ.get("IBM_CLOUD_API_KEY", "")
watsonx_url = os.environ.get("WATSONX_AI_URL", "https://us-south.ml.cloud.ibm.com")
project_id = os.environ.get("WATSONX_PROJECT_ID", "")

if not all([api_key, watsonx_url, project_id]):
    raise ValueError("Please set IBM_CLOUD_API_KEY, WATSONX_AI_URL, and WATSONX_PROJECT_ID environment variables.")

credentials = Credentials(
    api_key=api_key,
    url=watsonx_url
)

client = APIClient(credentials)
client.set.default_project(project_id)
print(f"Authenticated successfully for project_id: {project_id}")

# --- Foundation Model Inference (Text Generation) ---
model_id = ModelTypes.GRANITE_13B_INSTRUCT.value # Or other supported model like MISTRAL_7B_INSTRUCT

# Model parameters for text generation
parameters = {
    "decoding_method": DecodingMethods.GREEDY,
    "max_new_tokens": 50,
    "min_new_tokens": 1,
    "stop_sequences": []
}

# Initialize the model object
model = Model(
    model_id=model_id,
    credentials=credentials,
    project_id=project_id,
    parameters=parameters
)

# Define the prompt
prompt = "Write a short poem about artificial intelligence:"

# Generate text
try:
    print(f"\nPrompt: {prompt}")
    generated_text = model.generate_text(prompt=prompt)
    print(f"Generated Text:\n{generated_text}")
except Exception as e:
    print(f"An error occurred during text generation: {e}")

view raw JSON →