ibm-research/WatsonxDocsQARetrieval huggingface dataset:
# Batch deployment input details for Python functions #

Follow these rules when you are specifying input details for batch deployments of Python functions\.

Data type summary table:

<!-- <table> -->

| Data         | Description |
| ------------ | ----------- |
| Type         | inline      |
| File formats | N/A         |

<!-- </table ""> -->

You can deploy Python functions in Watson Machine Learning the same way that you can deploy models\. Your tools and apps can use the Watson Machine Learning Python client or REST API to send data to your deployed functions in the same way that they send data to deployed models\. Deploying functions gives you the ability to:

<!-- <ul> -->

 *  Hide details (such as credentials)
 *  Preprocess data before you pass it to models
 *  Handle errors
 *  Include calls to multiple models All of these actions take place within the deployed function, instead of in your application\.

<!-- </ul> -->

## Data sources ##

If you are specifying input/output data references programmatically:

<!-- <ul> -->

 *  Data source reference `type` depends on the asset type\. Refer to the **Data source reference types** section in [Adding data assets to a deployment space](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/ml-space-add-assets.html)\.

<!-- </ul> -->

**Notes:**

<!-- <ul> -->

 *  For connections of type [Cloud Object Storage](https://dataplatform.cloud.ibm.com/docs/content/wsj/manage-data/conn-cos.html) or [Cloud Object Storage (infrastructure)](https://dataplatform.cloud.ibm.com/docs/content/wsj/manage-data/conn-cos-infra.html), you must configure **Access key** and **Secret key**, also known as [HMAC credentials](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-uhc-hmac-credentials-main)\.
 *  The environment variables parameter of deployment jobs is not applicable\.
 *  Make sure that the output is structured to match the output schema that is described in [Execute a synchronous deployment prediction](https://cloud.ibm.com/apidocs/machine-learning#deployments-compute-predictions)\.

<!-- </ul> -->

## Learn more ##

[Deploying Python functions](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/ml-deploy-py-function.html)\.

**Parent topic:**[Batch deployment input details by framework](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/deploy-batch-input-by-framework.html)

<!-- </article "role="article" "> -->
# Batch deployment input details for Pytorch models #

Follow these rules when you are specifying input details for batch deployments of Pytorch models\.

Data type summary table:

<!-- <table> -->

| Data         | Description                            |
| ------------ | -------------------------------------- |
| Type         | inline, data references                |
| File formats | \.zip archive that contains JSON files |

<!-- </table ""> -->

## Data sources ##

Input or output data references:

<!-- <ul> -->

 *  Local or managed assets from the space
 *  Connected (remote) assets: Cloud Object Storage

<!-- </ul> -->

If you are specifying input/output data references programmatically:

<!-- <ul> -->

 *  Data source reference `type` depends on the asset type\. Refer to the **Data source reference types** section in [Adding data assets to a deployment space](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/ml-space-add-assets.html)\.
 *  If you deploy Pytorch models with ONNX format, specify the `keep_initializers_as_inputs=True` flag and set `opset_version` to `9` (always set `opset_version` to the most recent version that is supported by the deployment runtime)\.
    
        torch.onnx.export(net, x, 'lin_reg1.onnx', verbose=True, keep_initializers_as_inputs=True, opset_version=9)

<!-- </ul> -->

Note: The environment variables parameter of deployment jobs is not applicable\.

**Parent topic:**[Batch deployment input details by framework](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/deploy-batch-input-by-framework.html)

<!-- </article "role="article" "> -->
# Batch deployment input details for Scikit\-learn and XGBoost models #

Follow these rules when you are specifying input details for batch deployments of Scikit\-learn and XGBoost models\.

Data type summary table:

<!-- <table> -->

| Data         | Description                                |
| ------------ | ------------------------------------------ |
| Type         | inline, data references                    |
| File formats | CSV, \.zip archive that contains CSV files |

<!-- </table ""> -->

## Data source ##

If you are specifying input/output data references programmatically:

<!-- <ul> -->

 *  Data source reference `type` depends on the asset type\. Refer to the **Data source reference types** section in [Adding data assets to a deployment space](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/ml-space-add-assets.html)\.

<!-- </ul> -->

**Notes:**

<!-- <ul> -->

 *  The environment variables parameter of deployment jobs is not applicable\.
 *  For connections of type [Cloud Object Storage](https://dataplatform.cloud.ibm.com/docs/content/wsj/manage-data/conn-cos.html) or [Cloud Object Storage (infrastructure)](https://dataplatform.cloud.ibm.com/docs/content/wsj/manage-data/conn-cos-infra.html), you must configure **Access key** and **Secret key**, also known as [HMAC credentials](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-uhc-hmac-credentials-main),

<!-- </ul> -->

**Parent topic:**[Batch deployment input details by framework](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/deploy-batch-input-by-framework.html)

<!-- </article "role="article" "> -->
# Batch deployment input details for Spark models #

Follow these rules when you are specifying input details for batch deployments of Spark models\.

Data type summary table:

<!-- <table> -->

| Data         | Description |
| ------------ | ----------- |
| Type         | Inline      |
| File formats | N/A         |

<!-- </table ""> -->

**Parent topic:**[Batch deployment input details by framework](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/deploy-batch-input-by-framework.html)

<!-- </article "role="article" "> -->
# Batch deployment input details for Tensorflow models #

Follow these rules when you are specifying input details for batch deployments of Tensorflow models\.

Data type summary table:

<!-- <table> -->

| Data         | Description                            |
| ------------ | -------------------------------------- |
| Type         | Inline or data references              |
| File formats | \.zip archive that contains JSON files |

<!-- </table ""> -->

## Data sources ##

Input or output data references:

<!-- <ul> -->

 *  Local or managed assets from the space
 *  Connected (remote) assets: Cloud Object Storage

<!-- </ul> -->

If you are specifying input/output data references programmatically:

<!-- <ul> -->

 *  Data source reference `type` depends on the asset type\. Refer to the **Data source reference types** section in [Adding data assets to a deployment space](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/ml-space-add-assets.html)\.

<!-- </ul> -->

**Notes:**

<!-- <ul> -->

 *  The environment variables parameter of deployment jobs is not applicable\.
 *  For connections of type [Cloud Object Storage](https://dataplatform.cloud.ibm.com/docs/content/wsj/manage-data/conn-cos.html) or [Cloud Object Storage (infrastructure)](https://dataplatform.cloud.ibm.com/docs/content/wsj/manage-data/conn-cos-infra.html), you must configure **Access key** and **Secret key**, also known as [HMAC credentials](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-uhc-hmac-credentials-main)\.

<!-- </ul> -->

**Parent topic:**[Batch deployment input details by framework](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/deploy-batch-input-by-framework.html)

<!-- </article "role="article" "> -->
# Deploying foundation model assets #

Deploy foundation model assets to test the assets, put them into production, and monitor them\.

After you save a prompt template as a project asset, you can promote it to a deployment space\. A deployment space is used to organize the assets for deployments and to manage access to deployed assets\. Use a *Pre\-production* space to test and validate assets, and use a *Production* space for deploying assets for productive use\.

For details, see [Deploying a prompt template](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/prompt-template-deploy.html)\.

## Learn more ##

<!-- <ul> -->

 *  [Tracking prompt templates ](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/xgov-track-prompt-temp.html)
 *  [Evaluating a prompt template in a deployment space](https://dataplatform.cloud.ibm.com/docs/content/wsj/model/wos-eval-prompt-spaces.html)

<!-- </ul> -->

**Parent topic:**[Deploying and managing assets](https://dataplatform.cloud.ibm.com/docs/content/wsj/wmls/wmls-deploy-overview.html)

<!-- </article "role="article" "> -->
# Deploying scripts in Watson Machine Learning #

When a script is copied to a deployment space, you can deploy it for use\. Supported script types are Python scripts\. [Batch deployment](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/deploy-batch-details.html) is the only supported deployment type for a script\.

<!-- <ul> -->

 *  When the script is promoted from a project, your software specification is included\.
 *  When you create a deployment job for a script, you must manually override the default environment with the correct environment for your script\. For more information, see [Creating a deployment job](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/create-jobs.html)

<!-- </ul> -->

## Learn more ##

<!-- <ul> -->

 *  To learn more about supported input and output types and setting environment variables, see [Batch deployment details](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/deploy-batch-details.html)\.
 *  To learn more about software specifications, see [Software specifications and hardware specifications for deployments](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/pm_service_supported_frameworks.html)\.

<!-- </ul> -->

**Parent topic:**[Managing predictive deployments](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/ml-deploy-general.html)

<!-- </article "role="article" "> -->
# Choosing compute resources for running tools in projects #

You use compute resources in projects when you run jobs and most tools\. Depending on the tool, you might have a choice of compute resources for the runtime for the tool\.

Compute resources are known as either environment templates or hardware and software specifications\. In general, compute resources with larger hardware configurations incur larger usage costs\.

These tools have multiple choices for configuring runtimes that you can choose from:

<!-- <ul> -->

 *  [Notebook editor](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/notebook-environments.html)
 *  [Data Refinery](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/spark-dr-envs.html)
 *  [SPSS Modeler](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/spss-envs.html)
 *  [AutoAI](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/run-autoai.html)
 *  [Decision Optimization experiment](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/run-decisionopt.html)
 *  [RStudio IDE](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/rstudio-envs.html)
 *  [Synthetic Data Generator](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/synthetic-envs.html)
 *  [Tuning Studio](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/run-fm-tuning.html)

<!-- </ul> -->

Prompt Lab does not consume compute resources\. Prompt Lab usage is measured by the number of processed tokens\.

## Learn more ##

<!-- <ul> -->

 *  [Monitoring account resource usage](https://dataplatform.cloud.ibm.com/docs/content/wsj/admin/monitor-resources.html)

<!-- </ul> -->

**Parent topic:**[Projects ](https://dataplatform.cloud.ibm.com/docs/content/wsj/manage-data/manage-projects.html)

<!-- </article "role="article" "> -->
# Federated Learning architecture #

IBM Federated Learning has two main components: the aggregator and the remote training parties\. 

## Aggregator ##

The aggregator is a model fusion processor\. The admin manages the aggregator\.

The aggregator runs the following tasks:

<!-- <ul> -->

 *  Runs as a platform service in regions Dallas, Frankfurt, London, or Tokyo\.
 *  Starts with a Federated Learning experiment\.

<!-- </ul> -->

## Party ##

A party is a user that provides model input to the Federated Learning experiment aggregator\. The party can be:

<!-- <ul> -->

 *  on any system that can run the Watson Machine Learning Python client and compatible with Watson Machine Learning frameworks\.
    
    Note:The system does not have to be specifically IBM watsonx. For a list of system requirements, see [Set up your system](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-setup.html).
 *  running on the system in any geographical location\. You are recommended to locate each party in the same region where the data is to avoid data extraction out of different regions\.

<!-- </ul> -->

This illustration shows the architecture of IBM Federated Learning\.

A Remote Training System is used to authenticate the party's identity to the aggregator during training\.

![Illustration of the Federated Learning architecture](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/images/fl-arch.svg)

## User workflow ##

<!-- <ol> -->

1.  The data scientist:
    
    <!-- <ol> -->
    
    1.  Identifies the data sources.
    2.  Creates an initial "untrained" model.
    3.  Creates a data handler file.  
        These tasks might overlap with a training party entity.
    
    <!-- </ol> -->
    
2.  A party connects to the aggregator on their system, which can be remote\.
3.  An admin controls the Federated Learning experiment by:
    
    <!-- <ol> -->
    
    1.  Configuring the experiment to accommodate remote parties.
    2.  Starting the aggregator.
    
    <!-- </ol> -->
    
<!-- </ol> -->

This illustration shows the actions that are associated with each role in the Federated Learning process\.

![Illustration of the Federated Learning group workflow process](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/images/fl-workflow.svg)

**Parent topic:**[Get started](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-get-started.html)

<!-- </article "role="article" "> -->
# Federated Learning tutorials and samples #

Select the tutorial that fits your needs\. To facilitate the learning process of Federated Learning, one tutorial with a UI\-based approach and one tutorial with an API calling approach for multiple frameworks and data sets is provided\. The results of either are the same\. All UI\-based tutorials demonstrate how to create the Federated Learning experiment in a low\-code environment\. All API\-based tutorials use two sample notebooks with Python scripts to demonstrate how to build and train the experiment\.

## Tensorflow ##

These hands\-on tutorials teach you how to create a Federated Learning experiment step by step\. These tutorials use the MNIST data set to demonstrate how different parties can contribute data to train a model to recognize handwriting\. You can choose between a UI\-based or API version of the tutorial\.

<!-- <ul> -->

 *  [Federated Learning Tensorflow tutorial for UI](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-tf2-tutorial.html)  
    
 *  [Federated Learning Tensorflow samples for API](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-tf2-samples.html)

<!-- </ul> -->

## XGBoost ##

This is a tutorial for Federated Learning that teaches you how to create an experiment step by step with an income in the XGBoost framework\. The tutorial demonstrates how different parties can contribute data to train a model about adult incomes\.

<!-- <ul> -->

 *  [Federated Learning XGBoost tutorial for UI](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-xg-tutorial.html)  
    
 *  [Federated Learning XGBoost sample for API](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-xg-samples.html)

<!-- </ul> -->

## Homomorphic encryption ##

This is a tutorial for Federated Learning that teaches you how to use the advanced method of homomorphic encryption step by step\.

<!-- <ul> -->

 *  [Federated Learning homomorphic encryption sample for API](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-fhe-sample.html)

<!-- </ul> -->

**Parent topic:**[IBM Federated learning](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fed-lea.html)

<!-- </article "role="article" "> -->
# Federated Learning homomorphic encryption sample for API #

Download and review sample files that show how to run a Federated Learning experiment with Fully Homomorphic Encryption (FHE)\.

## Homomorphic encryption ##

FHE is an advanced, optional method to provide additional security and privacy for your data by encrypting data sent between parties and the aggregator\. This method still creates a computational result that is the same as if the computations were done on unencrypted data\. For more details on applying homomorphic encryption in Federated Learning, see [Applying encryption](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-homo.html)\.

## Download the Federated Learning sample files ##

Download the following notebooks\.

[Federated Learning FHE Demo](https://dataplatform.cloud.ibm.com/exchange/public/entry/view/aa449d3939b73847c502bd7822d0949a)

**Parent topic:**[Federated Learning tutorial and samples](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-demo.html)

<!-- </article "role="article" "> -->
# Get started #

Federated Learning is appropriate for any situation where different entities from different geographical locations or Cloud providers want to train an analytical model without sharing their data\.

To get started with Federated Learning, choose from these options:

<!-- <ul> -->

 *  Familiarize yourself with the key concepts and [Terminology](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-term.html)\.
 *  Review the [architecture](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-arch.html) for creating a Federated Learning experiment\.
 *  Follow a tutorial for step\-by\-step instructions for creating a [Federated Learning experiment](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-demo.html) or review samples\.

<!-- </ul> -->

## Learn more ##

<!-- <ul> -->

 *  [Terminology](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-term.html)  
    
 *  [Federated Learning architecture](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-arch.html)  
    
<!-- </ul> -->

**Parent topic:**[IBM Federated Learning](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fed-lea.html)

<!-- </article "role="article" "> -->
# Monitoring the experiment and saving the model #

Any party or admin with collaborator access to the experiment can monitor the experiment and save a copy of the model\.

As the experiment runs, you can check the progress of the experiment\. After the training is complete, you can view your results, save and deploy the model, and then test the model with new data\.

## Monitoring the experiment ##

When all parties run the party connector script, the experiment starts training automatically\. As the training runs, you can view a dynamic diagram of the training progress\. For each round of training, you can view the four stages of a training round:

<!-- <ul> -->

 *  **Sending model**: Federated Learning sends the model metrics to each party\.
 *  **Training**: The process of training the data locally\. Each party trains to produce a local model that is fused\. No data is exchanged between parties\.
 *  **Receiving models**: After training is complete, each party sends its local model to the aggregator\. The data is not sent and remains private\.
 *  **Aggregating**: The aggregator combines the models that are sent by each of the remote parties to create an aggregated model\.

<!-- </ul> -->

## Saving your model ##

When the training is complete, a chart that displays the model accuracy over each round of training is drawn\. Hover over the points on the chart for more information on a single point's exact metrics\.

A **Training rounds** table shows details for each training round\. The table displays the participating parties' average accuracy of their model training for each round\.

![Screenshot of View Setup Information](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/images/fl-display.png)

When you are done with the viewing, click **Save model to project** to save the Federated Learning model to your project\.

### Rerun the experiment ###

You can rerun the experiment as many times as you need in your project\.

Note:If you encounter errors when rerunning an experiment, see [Troubleshoot](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-troubleshoot.html) for more details\.

### Deploying your model ###

After you save your Federated Learning model, you can deploy and score the model like other machine learning models in a Watson Studio platform\.

See [Deploying models](https://dataplatform.cloud.ibm.com/docs/content/wsj/wmls/wmls-deploy-overview.html) for more details\.

**Parent topic:**[Creating a Federated Learning experiment](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-start.html)

<!-- </article "role="article" "> -->
# Set up your system #

Before you can use IBM Federated Learning, ensure that you have the required hardware, software, and dependencies\.

## Core requirements by role ##

Each entity that participates in a Federated Learning experiment must meet the requirements for their role\.

### Admin software requirements ###

Designate an admin for the Federated Learning experiment\. The admin must have:

<!-- <ul> -->

 *  Access to the platform with Watson Studio and Watson Machine Learning enabled\.  
    You must [create a Watson Machine Learning service instance](https://cloud.ibm.com/catalog/services/machine-learning).
 *  A [project](https://dataplatform.cloud.ibm.com/docs/content/wsj/getting-started/projects.html) for assembling the global model\. You must [associate the Watson Machine Learning service instance with your project](https://dataplatform.cloud.ibm.com/docs/content/wsj/getting-started/assoc-services.html)\.

<!-- </ul> -->

### Party hardware and software requirements ###

Each party must have a system that meets these minimum requirements\.

Note: Remote parties participating in the same Federated Learning experiment can use different hardware specs and architectures, as long as they each meet the minimum requirement\.

#### Supported architectures ####

<!-- <ul> -->

 *  x86 64\-bit
 *  PPC
 *  Mac M\-series
 *  4 GB memory or greater

<!-- </ul> -->

#### Supported environments ####

<!-- <ul> -->

 *  Linux
 *  Mac OS/Unix
 *  Windows

<!-- </ul> -->

#### Software dependencies ####

<!-- <ul> -->

 *  A supported [Python version and a machine learning framework](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-frames.html)\.
 *  The Watson Machine Learning Python client\.
    
    <!-- <ol> -->
    
    1.  If you are using Linux, run `pip install 'ibm-watson-machine-learning[fl-rt22.2-py3.10]'`.
    2.  If you are using Mac OS with M-series CPU and Conda, download the installation script and then run `./install_fl_rt22.2_macos.sh <name for new conda environment>`.
    
    <!-- </ol> -->
    
<!-- </ul> -->

## Network requirements ##

An outbound connection from the remote party to aggregator is required\. Parties can use firewalls that restrict internal connections with each other\.

## Data sources requirements ##

Data must comply with these requirements\.

<!-- <ul> -->

 *  Data must be in a directory or storage repository that is accessible to the party that uses them\.
 *  Each data source for a federate model must have the same features\. IBM Federated Learning supports horizontal federated learning only\.
 *  Data must be in a readable format, but the formats can vary by data source\. Suggested formats include:
    
    <!-- <ul> -->
    
     *  Hive
     *  Excel
     *  CSV
     *  XML
     *  Database
    
    <!-- </ul> -->
    
<!-- </ul> -->

**Parent topic:**[Creating a Federated Learning experiment](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-start.html)

<!-- </article "role="article" "> -->
# Creating a Federated Learning experiment #

Learn how to create a Federated Learning experiment to train a machine learning model\.

Watch this short overview video of how to create a Federated Learning experiment\.

Video disclaimer: Some minor steps and graphical elements in this video might differ from your platform\.

This video provides a visual method to learn the concepts and tasks in this documentation\.

Follow these steps to create a Federated Learning experiment:

<!-- <ul> -->

 *  [Set up your system](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-setup.html)
 *  [Creating the initial model](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-models.html)
 *  [Create the data handler](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-handler.html)
 *  [Starting the aggregator (Admin)](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-agg.html)
 *  [Connecting to the aggregator (Party)](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-conn.html)
 *  [Monitoring and saving the model](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-mon.html)

<!-- </ul> -->

**Parent topic:**[IBM Federated Learning](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fed-lea.html)

<!-- </article "role="article" "> -->
# Federated Learning Tensorflow samples #

Download and review sample files that show how to run a Federated Learning experiment by using API calls with a Tensorflow Keras model framework\.

To see a step\-by\-step UI driven approach rather than sample files, see the [Federated Learning Tensorflow tutorial for UI](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-tf2-tutorial.html)\.

## Download the Federated Learning sample files ##

The Federated Learning sample has two parts, both in Jupyter Notebook format that can run in the latest Python environment\.

For single\-user demonstrative purposes, the Notebooks are placed in a project\. Access the [Federated Learning project](https://dataplatform.cloud.ibm.com/exchange/public/entry/view/cab78523832431e767c41527a42a6727), and click **Create project** to get all the sample files at once\.

You can also get the Notebook separately\. Since, for practical purposes of Federated Learning, one user would run the admin Notebook and multiple users would run the party Notebook\. For more details on the admin and party, see [Terminology](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-term.html)\.

<!-- <ol> -->

1.  [Federated Learning Tensorflow Demo Part 1 \- for Admin](https://github.com/IBMDataScience/sample-notebooks/blob/master/CloudPakForData/notebooks/4.7/Federated_Learning_TF_Demo_Part_1.ipynb)
2.  [Federated Learning Tensorflow Demo Part 2 \- for Party](https://github.com/IBMDataScience/sample-notebooks/blob/master/CloudPakForData/notebooks/4.7/Federated_Learning_TF_Demo_Part_2.ipynb)

<!-- </ol> -->

**Parent topic:**[Federated Learning tutorial and samples](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-demo.html)

<!-- </article "role="article" "> -->
# Troubleshooting Federated Learning experiments #

The following are some of the limitations and troubleshoot methods that apply to Federated learning experiments\.

## Limitations ##

<!-- <ul> -->

 *  If you choose to enable homomorphic encryption, intermediate models can no longer be saved\. However, the final model of the training experiment can be saved and used normally\. The aggregator will not be able to decrypt the model updates and the intermediate global models\. The aggregator can see only the final global model\.

<!-- </ul> -->

## Troubleshooting ##

<!-- <ul> -->

 *  If a quorum error occurs during homomorphic keys distribution, restart the experiment\.
 *  Changing the name of a Federated Learning experiment causes it to lose its current name, including earlier runs\. If this is not intended, create a new experiment with the new name\.
 *  The default software spec is used by every run\. If your model type becomes outdated and not compatible with future software specs, re\-running an older experiment might run into issues\.
 *  As Remote Training Systems are meant to run on different servers, you might encounter unexpected behavior when you run with multiple parties that are based in the same server\.

<!-- </ul> -->

## Federated Learning known issues ##

<!-- <ul> -->

 *  [Known issues for Federated Learning](https://dataplatform.cloud.ibm.com/docs/content/wsj/getting-started/known-issues.html#wml)

<!-- </ul> -->

**Parent topic:**[IBM Federated Learning](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fed-lea.html)

<!-- </article "role="article" "> -->
# Federated Learning XGBoost samples #

These are links to sample files to run Federated Learning by using API calls with an XGBoost framework\. To see a step\-by\-step UI driven approach, go to [Federated Learning XGBoost tutorial for UI](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-xg-tutorial.html)\.

## Download the Federated Learning sample files ##

The Federated Learning samples have two parts, both in Jupyter Notebook format that can run in the latest Python environment\.

For single\-user demonstrative purposes, the Notebooks are placed in a project\. Go to the following link and click **Create project** to get all the sample files\.

[Download the Federated Learning project](https://dataplatform.cloud.ibm.com/exchange/public/entry/view/45a71514d67d87bb7900880b4501732c?context=wx)

You can also get the Notebook separately\. For practical purposes of Federated Learning, one user would run the admin Notebook and multiple users would run the party Notebook\. For more details on the admin and party, see [Terminology](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-term.html)

<!-- <ol> -->

1.  [Federated Learning XGBoost Demo Part 1 \- for Admin](https://dataplatform.cloud.ibm.com/exchange/public/entry/view/c95a130a2efdddc0a4b38c319a011fed)
2.  [Federated Learning XGBoost Demo Part 2 \- for Party](https://dataplatform.cloud.ibm.com/exchange/public/entry/view/155a5e78ca72a013e45d54ae87012306)

<!-- </ol> -->

**Parent topic:**[Federated Learning tutorial and samples](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fl-demo.html)

<!-- </article "role="article" "> -->
# Credentials for prompting foundation models (IBM Cloud API key and IAM token) #

To prompt foundation models in IBM watsonx\.ai programmatically, you need an IBM Cloud API key and sometimes an IBM Cloud IAM token\.

## IBM Cloud API key ##

To use the [foundation models Python library](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-python-lib.html), you need an IBM Cloud API key\.

**Python pseudo\-code**  

    my_credentials = {
        "url"    : "https://us-south.ml.cloud.ibm.com",
        "apikey" : <my-IBM-Cloud-API-key>
    }
    ...
    model = Model( ... credentials=my_credentials ... )

You can create this API key by using multiple interfaces\. For full instructions, see [Creating an API key](https://cloud.ibm.com/docs/account?topic=account-userapikey&interface=ui#create_user_key)

## IBM Cloud IAM token ##

When you click the **View code** button in the Prompt Lab, a curl command is displayed that you can call outside the Prompt Lab to submit the current prompt and parameters to the selected model and get a generated response\. In the command, there is a placeholder for an IBM Cloud IAM token\.

For information about generating that access token, see: [Generating an IBM Cloud IAM token](https://cloud.ibm.com/docs/account?topic=account-iamtoken_from_apikey)

**Parent topic:**[Foundation models Python library](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-python-lib.html)

<!-- </article "role="article" "> -->
# Foundation model terms of use in watsonx\.ai #

Review these model terms of use to understand your responsibilities and risks with foundation models\.

By using any foundation model provided with this IBM offering, you acknowledge and understand that:

<!-- <ul> -->

 *  Some models that are included in this IBM offering are Non\-IBM Products\. Review the applicable model information for details on the third\-party provider and license terms that apply\. See [Supported foundation models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html)\.
 *  Third Party models have been trained with data that may contain biases and inaccuracies and could generate outputs containing misinformation, obscene or offensive language, or discriminatory content\. Users should review and validate the outputs that are generated\.
 *  The output that is generated by all models is provided to augment, not replace, human decision\-making by the Client\.

<!-- </ul> -->

**Parent topic:**[Foundation models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-overview.html)

<!-- </article "role="article" "> -->
# Tokens and tokenization #

A *token* is a collection of characters that has semantic meaning for a model\. Tokenization is the process of converting the words in your prompt into tokens\.

You can monitor foundation model token usage in a project on the **Environments** page on the **Resource usage** tab\.

## Converting words to tokens and back again ##

Prompt text is converted to tokens before being processed by foundation models\.

The correlation between words and tokens is complex:

<!-- <ul> -->

 *  Sometimes a single word is broken into multiple tokens
 *  The same word might be broken into a different number of tokens, depending on context (such as: where the word appears, or surrounding words)
 *  Spaces, newline characters, and punctuation are sometimes included in tokens and sometimes not
 *  The way words are broken into tokens varies from language to language
 *  The way words are broken into tokens varies from model to model

<!-- </ul> -->

For a rough idea, a sentence that has 10 words could be 15 to 20 tokens\.

The raw output from a model is also tokens\. In the Prompt Lab in IBM watsonx\.ai, the output tokens from the model are converted to words to be displayed in the prompt editor\.

### Example ###

The following image shows how this sample input might be tokenized:

> Tomatoes are one of the most popular plants for vegetable gardens\. Tip for success: If you select varieties that are resistant to disease and pests, growing tomatoes can be quite easy\. For experienced gardeners looking for a challenge, there are endless heirloom and specialty varieties to cultivate\. Tomato plants come in a range of sizes\.

![Visualization of tokenization](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/images/fm-tokenization.png)

Notice a few interesting points:

<!-- <ul> -->

 *  Some words are broken into multiple tokens and some are not
 *  The word "Tomatoes" is broken into multiple tokens at the beginning, but later "tomatoes" is all one token
 *  Spaces are sometimes included at the beginning of a word\-token and sometimes spaces are a token all by themselves
 *  Punctuation marks are tokens

<!-- </ul> -->

## Token limits ##

Every model has an upper limit to the number of tokens in the input prompt plus the number of tokens in the generated output from the model (sometimes called *context window length*, *context window*, *context length*, or *maximum sequence length*\.) In the Prompt Lab, an informational message shows how many tokens are used in a given prompt submission and the resulting generated output\.

In the Prompt Lab, you use the *Max tokens* parameter to specify an upper limit on the number of output tokens for the model to generate\. The maximum number of tokens that are allowed in the output differs by model\. For more information, see the *Maximum tokens* information in [Supported foundation models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models.html)\.

**Parent topic:**[Foundation models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-overview.html)

<!-- </article "role="article" "> -->
# When to tune a foundation model #

Find out when tuning a model can help you use a foundation model to achieve your goals\.

Tune a foundation model when you want to do the following things:

<!-- <ul> -->

 *  Reduce the cost of inferencing at scale
    
    Larger foundation models typically generate better results. However, they are also more expensive to use. By tuning a model, you can get similar, sometimes even better results from a smaller model that costs less to use.
 *  Get the model's output to use a certain style or format
 *  Improve the model's performance by teaching the model a specialized task
 *  Generate output in a reliable form in response to zero\-shot prompts

<!-- </ul> -->

## When not to tune a model ##

Tuning a model is not always the right approach for improving the output of a model\. For example, tuning a model cannot help you do the following things:

<!-- <ul> -->

 *  Improve the accuracy of answers in model output
    
    If you're using a foundation model for factual recall in a question-answering scenario, tuning will marginally improve answer accuracy. To get factual answers, you must provide factual information as part of your input to the model. Tuning can be used to help the generated factual answers conform to a format that can be more-easily used by a downstream process in a workflow. To learn about methods for returning factual answers, see [Retreival-augmented generation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-rag.html).
 *  Get the model to use a specific vocabulary in its output consistently
    
    Large language models that are trained on large amounts of data formulate a vocabulary based on that initial set of data. You can introduce significant terms to the model from training data that you use to tune the model. However, the model might not use these preferred terms reliably in its output.
 *  Teach a foundation model to perform an entirely new task
    
    Experimenting with prompt engineering is an important first step because it helps you understand the type of output that a foundation model is and is not capable of generating. You can use tuning to tweak, tailor, and shape the output that a foundation model is able to return.

<!-- </ul> -->

## Learn more ##

<!-- <ul> -->

 *  [Retreival\-augmented generation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-rag.html)
 *  [Tuning methods](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-tuning-methods.html)

<!-- </ul> -->

**Parent topic:**[Foundation models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-overview.html)

<!-- </article "role="article" "> -->
# Geospatial data analysis #

You can use the geospatio\-temporal library to expand your data science analysis in Python notebooks to include location analytics by gathering, manipulating and displaying imagery, GPS, satellite photography and historical data\.

The gespatio\-temporal library is available in all IBM Watson Studio Spark with Python runtime environments\.

## Key functions ##

The geospatio\-temporal library includes functions to read and write data, topological functions, geohashing, indexing, ellipsoidal and routing functions\.

Key aspects of the library include:

<!-- <ul> -->

 *  All calculated geometries are accurate without the need for projections\.
 *  The geospatial functions take advantage of the distributed processing capabilities provided by Spark\.
 *  The library includes native geohashing support for geometries used in simple aggregations and in indexing, thereby improving storage retrieval considerably\.
 *  The library supports extensions of Spark distributed joins\.
 *  The library supports the SQL/MM extensions to Spark SQL\.

<!-- </ul> -->

## Getting started with the library ##

Before you can start using the library in a notebook, you must register `STContext` in your notebook to access the `st` functions\.

To register `STContext`:

    from pyst import STContext
    stc = STContext(spark.sparkContext._gateway)

## Next steps ##

After you have registered `STContext` in your notebook, you can begin exploring the spatio\-temporal library for:

<!-- <ul> -->

 *  Functions to read and write data
 *  Topological functions
 *  Geohashing functions
 *  Geospatial indexing functions
 *  Ellipsoidal functions
 *  Routing functions

<!-- </ul> -->

Check out the following sample Python notebooks to learn how to use these different functions in Python notebooks:

<!-- <ul> -->

 *  [Use the spatio\-temporal library for location analytics](https://dataplatform.cloud.ibm.com/exchange/public/entry/view/92c6ab6ea922d1da6a2cc9496a277005)
 *  [Use spatial indexing to query spatial data](https://dataplatform.cloud.ibm.com/exchange/public/entry/view/a7432f0c29c5bda2fb42749f3628d981)
 *  [Spatial queries in PySpark](https://dataplatform.cloud.ibm.com/exchange/public/entry/view/27ecffa80bd3a386fffca1d8d1256ba7)

<!-- </ul> -->

**Parent topic:**[Notebooks and scripts](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/notebooks-and-scripts.html)

<!-- </article "role="article" "> -->
# Hiding sensitive code cells in a notebook #

If your notebook includes code cells with sensitive data, such as credentials for data sources, you can hide those code cells from anyone you share your notebook with\. Any collaborators in the same project can see the cells, but when you share a notebook with a link, those cells will be hidden from anyone who uses the link\.

To hide code cells:

<!-- <ol> -->

1.  Open the notebook and select the code cell to hide\.
2.  Insert a comment with the hide tag on the first line of the code cell\.
    
    For the Python and R languages, enter the following syntax: `# @hidden_cell`
    
    ![Syntax for hiding code cells](https://dataplatform.cloud.ibm.com/docs/content/wsj/getting-started/images/hide_tag.png)

<!-- </ol> -->

**Parent topic:**[Sharing notebooks](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/share-notebooks.html)

<!-- </article "role="article" "> -->
# Installing custom libraries through notebooks #

The prefered way of installing additional Python libraries to use in a notebook is to customize the software configuration of the environment runtime associated with the notebook\. You can add the conda or PyPi packages through a customization template when you customize the environment template\.

See [Customizing environment templates](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/customize-envs.html)\.

However, if you want to install packages from somewhere else or packages you created on your local machine, for example, you can install and import the packages through the notebook\.

To install packages other than conda or PyPi packages through your notebook:

<!-- <ol> -->

1.  Add the package to your project storage by clicking the **Upload asset to project** icon (![Shows the Upload asset to project icon](https://dataplatform.cloud.ibm.com/docs/content/wsj/console/images/find_data_icon.png)), and then browsing the package file or dragging it into your notebook sidebar\.
2.  Add a project token to the notebook by clicking **More > Insert project token** from the notebook action bar\. The code that is generated by this action initializes the variable `project`, which is required to access the library you uploaded to object storage\.
    
    Example of an inserted project token:
    
        # @hidden_cell
        # The project token is an authorization token that is used to access project resources like data sources, connections, and used by platform APIs.
        from project_lib import Project
        project = Project(project_id='7c7a9455-1916-4677-a2a9-a61a75942f58', project_access_token='p-9a4c487075063e610471d6816e286e8d0d222141')
        pc = project.project_context
    
    If you don't have a token, you need to create one. See [Adding a project token](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/token.html).
3.  Install the library:

<!-- </ol> -->

    ```python
    # Fetch the library file, for example the tar.gz or whatever installable distribution you created
    with open("xxx-0.1.tar.gz","wb") as f:
        f.write(project.get_file("xxx-0.1.tar.gz").read())
    
    # Install the library
    !pip install xxx-0.1.tar.gz
    ```

<!-- <ol> -->

1.  Now you can import the library:
    
        import xxx

<!-- </ol> -->

**Parent topic:**[Libraries and scripts](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/libraries.html)

<!-- </article "role="article" "> -->
# Jupyter kernels and notebook environments #

Jupyter notebooks run in kernels in Jupyter notebook environments or, if the notebooks use Spark APIs, those kernels run in a Spark environment\.

The number of notebook Juypter kernels started in an environment depends on the environment type:

<!-- <ul> -->

 *  CPU or GPU environments
    
    When you open a notebook in edit mode, exactly one interactive session connects to a Jupyter kernel for the notebook language and the environment runtime that you select. The runtime is started per user and not per notebook. This means that if you open a second notebook with the same environment template, a second kernel is started in that runtime. Resources are shared. If you want to avoid sharing runtime resources, you must associate each notebook with its own environment template.
    
    Important: Stopping a notebook kernel doesn't stop the environment runtime in which the kernel is started because other notebook kernels could still be active in that runtime. Only stop an environment runtime if you are sure that no kernels are active.
 *  Spark environments
    
    When you open a notebook in edit mode in a Spark environment, a dedicated Spark cluster is started, even if another notebook was opened in the same Spark environment template. Each notebook kernel has its own Spark driver and set of Spark executors. No resources are shared.

<!-- </ul> -->

If necessary, you can restart or reconnect to a kernel\. When you restart a kernel, the kernel is stopped and then started in the same session, but all execution results are lost\. When you reconnect to a kernel after losing a connection, the notebook is connected to the same kernel session, and all previous execution results which were saved are available\.

The kernel remains active even if you leave the notebook or close the web browser window\. When you reopen the same notebook, the notebook is connected to the same kernel\. Only the output cells that were saved (auto\-save happens every 2 minutes) before you left the notebook or closed the web browser window will be visible\. You will not see the output for any cells which ran in the background after you left the notebook or closed the window\. To see all of the output cells, you need to rerun the notebook\.

## Learn more ##

<!-- <ul> -->

 *  [Notebook environments](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/environments-parent.html)

<!-- </ul> -->

<!-- <ul> -->

 *  [Associated Spark services](https://dataplatform.cloud.ibm.com/docs/content/wsj/getting-started/assoc-services.html)

<!-- </ul> -->

<!-- <ul> -->

 *  [Runtime scope in notebook environments](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/notebook-environments.html#runtime-scope)

<!-- </ul> -->

**Parent topic:**[Creating notebooks](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/creating-notebooks.html)

<!-- </article "role="article" "> -->