vania-janet/multiturn-rag-retrieval-data huggingface dataset:
Upgrading custom models 

To improve the quality of speech recognition, the IBM Watson® Speech to Text service occasionally updates base previous- and next-generation models. Because base models for different languages are independent of each other, as are different models for the same language, updates to individual base models do not affect other models.

When a base model is updated, you might need to upgrade any custom models that are built on that base model to take advantage of the improvements. An update to a base model that requires an upgrade produces a new version of the base model (for example, en-US_BroadbandModel.v2020-01-16). An update that does not require an upgrade does not produce a new version.



* For previous-generation models, all updates to a base model produce a new version of the model. When a new version of a base model is released, you must upgrade any custom language and custom acoustic models that are built on the updated base model to take advantage of the improvements.
* For next-generation models, most updates do not produce a new version of the model. These updates do not require that you upgrade your custom models. Some updates, however, do generate a new version of a base model. You must upgrade any custom language models that are built on the updated base model to take advantage of the improvements.

The service released new language model customization technology on 27 February 2023. How you upgrade to the new technology is different from traditional custom model upgrades. For more information about the new technology and about upgrading, see



* [Improved language model customization for next-generation models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-customizationcustomLanguage-intro-ng)
* [Upgrading a custom language model based on an improved next-generation model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-upgradecustom-upgrade-language-ng)





If an upgrade is required, your custom models continue to use the older version of the base model until you complete the upgrade. Upgrade to the latest version of an updated base model as soon as possible.
To add a Machine Learning model, complete the following steps:



1. Create the model and export it from the tool you use to create it.

For more information, see the following documentation:



* Knowledge Studio for IBM Cloud Pak® for Data



* [Creating a rule-based model](https://cloud.ibm.com/docs/watson-knowledge-studio-data?topic=watson-knowledge-studio-data-rule-annotator)
* [Creating a machine learning model](https://cloud.ibm.com/docs/watson-knowledge-studio-data?topic=watson-knowledge-studio-data-ml_annotator)



* Knowledge Studio for IBM Cloud



* [Creating a rule-based model](https://cloud.ibm.com/docs/watson-knowledge-studio?topic=watson-knowledge-studio-rule-annotator)
* [Creating a machine learning model](https://cloud.ibm.com/docs/watson-knowledge-studio?topic=watson-knowledge-studio-ml_annotator)



* [Watson Explorer Content Analytics Studio](https://www.ibm.com/docs/en/watson-explorer/12.0.x?topic=analytics-content-studio-advanced-text)

You must export the model from Watson Explorer Content Analytics Studio as a UIMA PEAR file. For more information, see: [Creating Custom PEAR Files for use with Lexical Analysis Streams](https://www.ibm.com/docs/en/watson-explorer/12.0.x?topic=las-creating-custom-pear-files-use-lexical-analysis-streams).
* [Discovery entity extractor](https://cloud.ibm.com/docs/discovery-data?topic=discovery-data-entity-extractorentity-extractor-export)



2. From the Teach domain concepts section of the Improvement tools panel, and then click Import machine learning models.
3. Specify a name for the model, and then choose the language that was used to define the model.
4. Click Upload to browse for the file that you exported earlier.
5.
Some updates, however, do generate a new version of a base model. You must upgrade any custom language models that are built on the updated base model to take advantage of the improvements.



All updates to base models and whether they require upgrades are announced in the release notes:



* [Release notes for Speech to Text for IBM Cloud](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-release-notes)
* [Release notes for Speech to Text for IBM Cloud Pak for Data](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-release-notes-data)



Once you upgrade a custom model, the service uses the latest version of the custom model by default when you specify that model with a speech recognition request. But you can still direct the service to use the older version of the model. For more information about upgrading custom models and about using an older version of a model, see



* [Upgrading custom models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-upgrade)
* [Using upgraded custom models for speech recognition](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-upgrade-use)
Also, the version strings that represent different versions of base models have been updated. And the base_model_version parameter can also be used with upgraded next-generation models.

For more information about custom model upgrade, when upgrade is necessary, and how to use older versions of custom models, see



* [Upgrading custom models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-upgrade)
* [Using upgraded custom models for speech recognition](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-upgrade-use)



Defect fix: Update capitalization documentation
: Defect fix: The documentation that describes the service's automatic capitalization of transcripts has been updated. The service capitalizes appropriate nouns only for the following languages and models:



* All previous-generation US English models
* The next-generation German model



For more information, see [Capitalization](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-basic-responseresponse-capitalization).





 31 January 2022 (Version 4.0.5) 

Version 4.0.5 has been updated
: Speech to Text for IBM Cloud Pak for Data version 4.0.5 has been updated to address installation issues. The case package version is now 4.0.6. Use this package instead of the version 4.0.5 package. For more information about installing and managing the service, see [Installing Watson Speech to Text](https://www.ibm.com/docs/en/cloud-paks/cp-data/4.0?topic=text-installing-watson-speech).

Important: Extra steps for mirrored installation are no longer necessary
: Important: The [26 January 2022 release notes](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-release-notes-dataspeech-to-text-data-26january2022) included important notes for the following steps:



* Additional step for performing a mirrored installation of Minio datastore
For more information, see [Monitoring the train model request](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-languageCreatemonitorTraining-language).

The service cannot accept requests to modify the model in any way until the upgrade request completes. However, you can continue to issue recognition requests with the existing version of the model during the upgrade.



 Upgrading a custom language model based on an improved next-generation model 

For custom language models that are based on improved next-generation models, upgrade is performed automatically when you retrain the custom model. And once a custom model is based on an improved next-generation model, the service continues to perform any necessary upgrades when the custom model is retrained.

You cannot use the POST /v1/customizations/{customization_id}/upgrade_model method to upgrade a custom model to an improved next-generation base model.

To upgrade a custom model that is based on an improved next-generation model, perform one of the following procedures:



* Change the custom model and then train it.



1. Change your custom model by adding or modifying a custom word, corpus, or grammar that the model contains. Any change that you make moves the model to the ready state.
2. Use the POST /v1/customizations/{customization_id}/train method to retrain the model. Retraining upgrades the custom model and moves it to the available state.



IBM Cloud

Train the custom model by using the force query parameter.

If you include the parameter force=true with the POST /v1/customizations/{customization_id}/train request, you do not need to change the model's custom words, corpora, or grammars to enable upgrading. The parameter forces the training, and thus the upgrade, of the custom model regardless of whether it is in the ready or available state. The following example shows the use of the force parameter:

IBM Cloud

curl -X POST -u "apikey:{apikey}" "{url}/v1/customizations/{customization_id}/train?force=true"
When a new version of a base model is first released, existing custom models are still based on the older version of the base model. Until a custom model is upgraded, all operations on that custom model, such as adding data to or training the model, affect the existing version of the custom model. Similarly, all recognition requests that specify the custom model use the existing version of the custom model.

Upgrading results in two versions of a custom model, one based on the older version of the base model and one based on the latest version of the base model. Once a custom model is upgraded, all operations on that custom model affect the newer, upgraded version of the custom model. It is no longer possible to add data to or to train the older version of the model. You cannot undo an upgrade operation.

When you upgrade a custom model, you do not need to upgrade its individual resources. For a custom language model, the service automatically upgrades any corpora, grammars, and words that are defined for the model. Likewise, when you upgrade a custom acoustic model, the service automatically upgrades its audio resources. You do not need to upgrade a custom language or custom acoustic model that contains no resources.

By default, the service uses the latest version of a custom model for speech recognition requests. However, you can continue to use the older version of a custom model for speech recognition. For more information, see [Using upgraded custom models for speech recognition](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-upgrade-use).





 Upgrading a custom language model 

Follow these steps to upgrade a custom language model:



1. Ensure that the custom language model is in either the ready or the available state. You can check a model's status by using the GET /v1/customizations/{customization_id} method. If the model's state is ready, upgrade the model before training it on its latest data.
2. Upgrade the custom language model by using the POST /v1/customizations/{customization_id}/upgrade_model method:

IBM Cloud
* [Upgrading a custom language model based on an improved next-generation model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-custom-upgradecustom-upgrade-language-ng)





If an upgrade is required, your custom models continue to use the older version of the base model until you complete the upgrade. Upgrade to the latest version of an updated base model as soon as possible. The sooner you upgrade a custom model, the sooner you can experience the improved speech recognition of the new model.

Once you upgrade a custom model, the service uses the latest version of the custom model by default when you specify that model with a speech recognition request. But you can still direct the service to use the older version of the model. Note that older versions of base models can be removed at a future time. To encourage upgrading, the service returns a warning message with the results for recognition requests that use custom models that are based on older base models.

All updates to base models and whether they require upgrades are announced in the release notes:



* [Release notes for Speech to Text for IBM Cloud](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-release-notes)
* [Release notes for Speech to Text for IBM Cloud Pak for Data](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-release-notes-data)



As with all customization operations, you must use credentials for the instance of the service that owns a custom model to upgrade it.



 How upgrading works 

When a new version of a base model is first released, existing custom models are still based on the older version of the base model. Until a custom model is upgraded, all operations on that custom model, such as adding data to or training the model, affect the existing version of the custom model. Similarly, all recognition requests that specify the custom model use the existing version of the custom model.

Upgrading results in two versions of a custom model, one based on the older version of the base model and one based on the latest version of the base model.
* The default character_insertion_bias for custom models that are based on the new versions of these models remains 0.0, but the models have changed in a manner that makes use of the parameter for speech recognition less necessary.



Upgrading to the new models: To take advantage of the improved technology, you must upgrade any custom language models that are based on the new models. To upgrade to the new version of one of these base models, do the following:



1. Change your custom model by adding or modifying a custom word, corpus, or grammar that the model contains. Any change that you make moves the model to the ready state.
2. Use the POST /v1/customizations/{customization_id}/train method to retrain the model. Retraining upgrades the custom model to the new technology and moves the model to the available state.

Known issue: At this time, you cannot use the POST /v1/customizations/{customization_id}/upgrade_model method to upgrade a custom model to one of the new base models. This issue will be addressed in a future release.



Using the new models: Following the upgrade to the new base model, you are advised to evaluate the performance of the upgraded custom model by paying special attention to the customization_weight and character_insertion_bias parameters for speech recognition. When you retrain your custom model:



* The custom model uses the new default customization_weight of 0.1 for your custom model. A non-default customization_weight that you had associated with your custom model is removed.
* The custom model might no longer require use of the character_insertion_bias parameter for optimal speech recognition.



Improvements to language model customization render these parameters less important for high-quality speech recognition:



* If you use the default values for these parameters, continue to do so after the upgrade. The default values will likely continue to offer the best results for speech recognition.
* If you specify non-default values for these parameters, experiment with the default values following upgrade. Your custom model might work well for speech recognition with the default values.



If you feel that using different values for these parameters might improve speech recognition with your custom model, experiment with incremental changes to determine whether the parameters are needed to improve speech recognition.
Training the machine learning model 

In IBM Watson™ Knowledge Studio for IBM Cloud Pak for Data, the creation of the machine learning model involves training the machine learning model and evaluating how well the model performed when annotating test data and blind data.



 Creating a machine learning model 

When you create a machine learning model, you select the document sets that you want to use to train the model and specify the percentage of documents that are to be used as training data, test data, and blind data.



 About this task 

By exploring the performance metrics, you can identify ways to improve the model's accuracy.

Only three machine learning models can be trained at a time per Knowledge Studio instance. If your instance contains multiple workspaces and the number of machine learning models that are being trained in other workspaces totals 3 already, then your request to train the machine learning model in your workspace will be queued until the other training processes are done.





 Procedure 

To create a machine learning model:



1. Log in as a Knowledge Studio administrator and select your workspace.
2. Select Machine Learning Model > Performance.
3. Verify that all of the document sets have been approved and that all annotation conflicts have been resolved through adjudication. Only documents that have become ground truth through adjudication or approval can be used to train the model.
4. Click Train and evaluate.
5. Optional: To specify how you want to allocate documents from your document sets to be used by the system-level training, test, or blind sets, click Edit settings.

For more information about which ratios to apply, see [Document set management](https://cloud.ibm.com/docs/watson-knowledge-studio-data?topic=watson-knowledge-studio-data-improve-mlwks_mamanagedata).
6. Click Train to train the model, or click Train & Evaluate to train the model, evaluate annotations added by the machine learning model, and analyze the performance statistics.

Training a machine learning model can take several minutes or several hours, depending on the number of human annotations that exist and the total number of words across all documents.
7. Select the document sets that you want to use for training the model.
New features and changes 

Deployed Models page updated
: The Deployed Models page was updated to include models from Knowledge Studio instances that are managed by [IAM resource groups](https://cloud.ibm.com/docs/iam?topic=iam-userroles), in addition to models that are managed by [Cloud Foundry organizations](https://cloud.ibm.com/docs/iam?topic=iam-cfaccess).

What you see on the Deployed Models page depends on the [region](https://cloud.ibm.com/docs/resources?topic=resources-services_region) that hosts your Knowledge Studio instance. If the region supports instances managed by both access management methods, you see a tab for each method. Models from instances that are managed by IAM are listed on the Resource Groups tab. Models from instances that are managed by Cloud Foundry are listed on the Organizations tab.

If the region supports instances managed by only one of the access management methods, you see only one list of models, because only one access management method is applicable.

To view the Deployed Models page, from the Settings menu in the top right menu bar, click Manage deployed models. For more information about undeploying models on the Deployed Models page, see [Undeploying machine learning models](https://cloud.ibm.com/docs/watson-knowledge-studio?topic=watson-knowledge-studio-publish-mlpm-um) and [Undeploying rule-based models](https://docs/watson-knowledge-studio?topic=watson-knowledge-studio-wks_rule_publish).

Navigation changed to better align with the Knowledge Studio workflow.
: In addition, the following functionality was reorganized:



* In the previous version, management of dictionaries was included as part of the Pre-annotators page. Now, management of dictionaries is located on the Dictionaries page in the Assets section of the navigation.
* In the previous version, human annotation functionality was distributed across the Mentions, Relations, and Coreferences tabs in the Document Annotation section of the navigation.
Using upgraded custom models for speech recognition 

Once you upgrade a custom model, the service uses the latest version of the custom model by default when you specify that model with a speech recognition request. However, you can still direct the service to use the older version of the model. You need to list information about the custom model to determine the available versions.



 Listing version information for a custom model 

Listing information about a custom model is the only way to see the available versions of a base model. To see the versions of the base model for which a custom model is available, use the following methods:



* To list information about a custom language model, use the GET /v1/customizations/{customization_id} method. For more information, see [Listing custom language models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageLanguageModelslistModels-language).
* To list information about a custom acoustic model, use the GET /v1/acoustic_customizations/{customization_id} method. For more information, see [Listing custom acoustic models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-manageAcousticModelslistModels-acoustic).



In both cases, the output includes a versions field that shows information about the base models that are available for the custom model. If the custom model has not been upgraded or only a single version of its base model exists, the versions field shows a single version.



 Example of listing version information 

The following example request shows information for an upgraded custom language model:

IBM Cloud

curl -X GET -u "apikey:{apikey}" "{url}/v1/customizations?language=en-US"

IBM Cloud Pak for Data

curl -X GET --header "Authorization: Bearer {token}" "{url}/v1/customizations?language=en-US"
You do not need to upgrade custom models that are based on these models. For more information about all available next-generation models, see [Next-generation languages and models](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-models-ng).

Defect fix: Improve custom model naming documentation
: Defect fix: The documentation now provides detailed rules for naming custom language models and custom acoustic models. For more information, see



* [Create a custom language model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-languageCreatecreateModel-language)
* [Create a custom acoustic model](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-acousticcreateModel-acoustic)
* [API & SDK reference](https://cloud.ibm.com/apidocs/speech-to-text)



Security vulnerabilities addressed
: The following security vulnerabilities have been fixed:



* [Security Bulletin: IBM Watson Speech Services Cartridge for IBM Cloud Pak for Data is vulnerable to a cross-configuration attack against OpenPGP (CVE-2021-40528)](https://www.ibm.com/support/pages/node/6843867)
* [Security Bulletin: IBM Watson Speech Services Cartridge for IBM Cloud Pak for Data is vulnerable to arbitrary code execution in PCRE2 (CVE-2022-1586)](https://www.ibm.com/support/pages/node/6843869)
* [Security Bulletin: IBM Watson Speech Services Cartridge for IBM Cloud Pak for Data is vulnerable to a heap-based buffer overflow in Vim (CVE-2022-1621)](https://www.ibm.com/support/pages/node/6843871)
* [Security Bulletin: IBM Watson Speech Services Cartridge for IBM Cloud Pak for Data is vulnerable to a buffer overflow in Vim (CVE-2022-1629)](https://www.ibm.com/support/pages/node/6843873)