Connecting to a watsonx.ai instance

To enable users to connect to a local or a remote watsonx.ai model from IBM watsonx.data intelligence for using generative AI capabilities, you must set up a connection to that watsonx.ai instance for communication with your foundation models. In addition, you can manage which foundation models are used with the enabled gen AI capabilities.

Prerequisites

The following prerequisites must be met:

Generative AI capabilities must be enabled in your IBM watsonx.data intelligence deployment. This setup can be done during installation, upgrade, or at any time later. For more information about the deployment modes, see Preparing to install IBM watsonx.data intelligence in the IBM Software Hub documentation.
The use of foundation models that require local or remote GPU must be enabled in your IBM watsonx.data intelligence deployment. This setup can also be done during installation, upgrade, or at any time later. If set up your system with models running on CPU and want to switch to using remote models, but do not want to change any other configuration settings, you can follow the instructions in Can't work with a remote watsonx.ai instance if the system is configured to run models on CPU in the IBM Software Hub documentation.
A watsonx.ai instance with appropriate foundation models must exist.
You must have your user API key available for authenticating to the system that hosts the watsonx.ai instance.

Required permissions

A user with the IBM Software Hub Administrator role who has access to the watsonx.ai instance can set up the connection.

IBM watsonx.data intelligence users with any user role who need access to generative AI features must be collaborators in the deployment space that is selected in the setup. Users need to authenticate to the remote watsonx.ai instance with their user API key when they want to use any generative AI features in IBM watsonx.data intelligence.

Administrator tasks:

Setting up the connection to the watsonx.ai instance
Selecting the models to be used for the gen AI capabilities
Deleting the configuration

User tasks:

Authenticating with the watsonx.ai instance

Setting up the connection to the watsonx.ai instance

To enable users to connect to a watsonx.ai model:

Go to Administration > Configurations and settings and click Generative AI setup.
To configure the connection, click Add connection.
Provide the connection details. Select one of these options:
Cloud service provider

Select a cloud service provider. Before you can proceed, you must acknowledge that use of remote inferencing foundation models will incur additional costs and that data samples are sent to the remote model as additional context for the prompts.

On premises (IP/URL)

Provide the URL or IP address of the local or remote watsonx.ai instance and specify a port. For enhanced security when you connect to a remote cluster, use an SSL-enabled port. To ensure that the origin cluster can trust the certificate of the remote cluster, provide the certificate chain of the remote cluster.
To obtain this information, complete the steps that apply to the operating system that you are working on:
- Linux
  
  Run the openssl command with the showcerts flag. Do not include the protocol in the <route> value.
```
true | openssl s_client -showcerts -connect <route>:443 </dev/null 2>/dev/null | awk '/BEGIN/,/END/'
```
- Windows
  1. If OpenSSL is not yet available on your workstation, install the package:
    
    winget install --id ShiningLight.OpenSSL.Light -e
  2. Add the openssl bin directory path to the PATH variable:
    
    Press Win + R, then type SystemPropertiesAdvanced and press Enter.
    
    Click Environment variables.
    
    In the System variables section, select Path.
    
    Click Edit.
    
    Click New and paste the correct path here, for example, C:\Program Files\OpenSSL-Win64\bin.
  3. Open a command shell and run the following command. Do not include the protocol in the <route> value.
    
    echo QUIT | openssl s_client -showcerts -connect <route>:443
The output of the openssl command should have this format:
```
-----BEGIN CERTIFICATE-----
<first certificate>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<second certificate>
-----END CERTIFICATE-----
```
Copy the complete certificate into the SSL certificate field.
Provide the credentials for authenticating to the system to which you want to connect. Enter your personal user API key for use with the watsonx.ai instance. The API key is stored as a secret in the internal vault for future authentication. For authentication to a IBM watsonx.data intelligence cluster, also specify the username that is associated with the provided user API key.
Select a deployment space from your watsonx.ai instance that you have access to.
Select a default model to use with this connection. Initially, the default model that is predefined by the service is used. You can change the default model for the connection to your preferred model.

At any time later, you can change the models for the use cases.
Click Add connection.

Your connection setup is complete.

Selecting the gen AI models

Configure which foundation models are used for the generative AI capabilities. You can work with the default models, select from the foundation models that are supported in watsonx.ai, or work with your own custom models.

The selections that you make in the generative AI setup UI take precedence over any the model configuration that was applied by using installation options. Model configuration at install time is deprecated starting with IBM Software Hub 5.4. The selected models must be available in the deployment space that is configured in the connection to the watsonx.ai instance.

Important: Changing a model can impact the accuracy of the results and can incur additional cost for inferencing.

In general, you can set the models for enrichment and Text2SQL:

Enrichment: The selected model is used for generating descriptions and display names for tables and table columns, and for creating new business terms based on the content of tables and table columns.
Text2SQL: The selected model is used for transforming user-provided natural language queries into SQL queries that can be consumed by the service.

Depending on your deployment configuration for the generative AI capabilities, not all options might be available. For more information about the deployment modes, see Preparing to install IBM watsonx.data intelligence in the IBM Software Hub documentation.

For a list of certified foundation models, see Certified foundation models.

Deleting the configuration

If you want to delete the configuration and start over, click Remove connection. However, remember that this connection is used by any service that connects to this watsonx.ai instance to provide generative AI capabilities. If you remove the connection, all jobs that currently use the connection will fail. The model configuration is reset to using the default models.

Authenticating with the watsonx.ai instance

To authenticate to the system that hosts the watsonx.ai instance as a user of generative AI capabilities such as metadata expansion in metadata enrichment, complete these steps:

Go to Administration > Configurations and settings and click Generative AI setup.
Check the connection details for information about the system, the deployment space in which the models run, and your authentication status.
Click Authenticate.
Provide the credentials for authenticating to the system. Enter your personal user API key for use with the watsonx.ai instance. The API key is stored as a secret in the internal vault for future authentication. For authentication to a remote IBM Software Hub cluster, also specify the username that is associated with the provided user API key.

To update your credentials, for example, because your API key expired, click the Edit icon edit icon in the Authentication section of the connection details.

Learn more

Generating API keys for authentication in the IBM Software Hub documentation
Managing the user API key in the IBM watsonx.ai as a Service documentation