From 6aed1b3fd66be0baa1bff1c930e1931f50808e60 Mon Sep 17 00:00:00 2001 From: Paul Cornell Date: Mon, 15 Sep 2025 15:12:29 -0700 Subject: [PATCH 1/3] IBM watsonx Orchestrate tool example --- examplecode/tools/ibm-orchestrate.mdx | 74 +++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 examplecode/tools/ibm-orchestrate.mdx diff --git a/examplecode/tools/ibm-orchestrate.mdx b/examplecode/tools/ibm-orchestrate.mdx new file mode 100644 index 00000000..b822c268 --- /dev/null +++ b/examplecode/tools/ibm-orchestrate.mdx @@ -0,0 +1,74 @@ + +## Requirements + +To use this example, you will need the following: + +- Within your IBM Cloud account, an IBM watsonx.data subscription that contains a Milvus service instance. + + - Create an [IBM Cloud account](https://cloud.ibm.com/registration). + - Create an [IBM watsonx.data subscription](https://cloud.ibm.com/watsonxdata) in your IBM Cloud account. + - Create a [Milvus service instance](/ui/destinations/milvus) within your IBM watsonx.data subscription plan. + +- Within your Unstructured account, a workflow that contains a Milvus destination connector. + + - Create an [Unstructured account](https://unstructured.io/signup). + - Create a [Milvus destination connector](/ui/destinations/milvus) in your Unstructured account. + - Create a [workflow]() that contains the Milvus destination connector in your Unstructured account. + + The workflow must generate [embeddings](/ui/embedding). The workflow's **Embedder** node's selected embedding model provider must be "IBM". The + node's selected embedding model must be one of the following models that are offered by IBM watsonx Orchestrate: + + - `all-minilm6-v2`, with 384 dimensions. Per IBM, this model is good for tasks such as information retrieval, clustering, and for detecting sentence similarity. + - `granite-embedding-107m-multilingual`, with 384 dimensions. Per IBM, this model is good for tasks such as text similarity, retrieval, and search. + - `granite-embedding-278m-multilingual`, with 768 dimensions. + - `multilingual-e5-large`, with 1024 dimensions. Per IBM, this model is good for generating text embeddings for text in a language other than English. + - `slate-125m-english-retrvr`, with 768 dimensions. Per IBM, the `slate-125m-*` models are good for generating embeddings for various inputs such as queries, passages, or documents. Per IBM, the `slate-125m-*` models are two to three times slower but perform slightly better than the `slate-30m-*` models. + - `slate-125m-english-retrvr-v2`, with 768 dimensions. + - `slate-30m-english-retrvr`, with 384 dimensions. Per IBM, the `slate-30m-*` models are trained to maximize the cosine similarity between two text inputs so that embeddings can be evaluated based on similarity later. Per IBM, the `slate-30m-*` models are two to three times faster and have slightly lower performance scores than the `slate-125m-*` models. + - `slate-30m-english-retrvr-v2`, with 384 dimensions. + + Be sure to [run the workflow](/ui/workflows#edit%2C-delete%2C-or-run-a-workflow) to have Unstructured generate the embeddings and store them—along with + Unstructured's processed data representing your organization's source documents and semi-structured data—in the database + that is accessed through the Milvus service instance within your IBM watsonx.data subscription. + +## Step 1: ... + +In this step, you add an IBM watsonx Orchestrate subscription to your IBM Cloud account. + +If you already have an IBM watsonx Orchestrate subscription, then skip ahead to **Step 2**. + +1. [Log in to your IBM Cloud account](https://cloud.ibm.com/login). +2. On the sidebar, click the **Resource list** icon. If the sidebar is not visible, click the **Navigation Menu** icon to the far left of the + top navigation bar. +3. Click **Create resource**. +4. With **IBM Cloud catalog** selected, search for and select **watsonx Orchestrate**. +5. Complete the on-screen instructions to finish creating the IBM watsonx Orchestrate subscription. + +## Step 2: ... + +In this step, ... + +1. Open your IBM watsonx Orchestrate subscription, if it is not already open. To do this: + + a. [Log in to your IBM Cloud account](https://cloud.ibm.com/login).
+ b. On the sidebar, click the **Resource list** icon. If the sidebar is not visible, click the **Navigation Menu** icon to the far left of the + top navigation bar.
+ c. In the list of resources, expand **AI / Machine Learning**, and then click the target watsonx Orchestrate subscription.
+ d. Click **Launch watsonx Orchestrate**.
+ +2. If the **Chat** page is not already open, click the **Open the main menu** icon to the far left of the + top navigation bar, and then click **Chat**. +3. Toward the bottom of the sidebar, click **Create new agent**. +4. On the **Create an agent** page, with **Create from scratch** already selected, enter some **Name** and **Description**for the agent, and then click **Create**. +5. Under **Knowledge source**, in the **Start by adding knowledge** tile, click **Choose knowledge**. +6. On the **Select source** page, click **Milvus**, and then click **Next**. +7. On the **Connect Milvus** page, specify the following settings: + + a. For **GRPC host**, enter the GRPC host value for the Milvus service instance within your IBM watsonx.data subscription.
+ b. For **GRPC port**, enter the GRPC port value for the Milvus service instance.
+ c. For **Choose an authentication type**, select **Basic authentication**.
+ d. For **Username**, enter `ibmlhapikey`.
+ e. For **Password**, enter the API key for your IBM Cloud account.
+ f. Click **Next**.
+ +8. ... \ No newline at end of file From a1163fd692123aedb63bab60ba9f159518b2159f Mon Sep 17 00:00:00 2001 From: Paul Cornell Date: Mon, 15 Sep 2025 16:03:18 -0700 Subject: [PATCH 2/3] Added more initial content --- examplecode/tools/ibm-orchestrate.mdx | 45 ++++++++++++++++++++++++--- 1 file changed, 41 insertions(+), 4 deletions(-) diff --git a/examplecode/tools/ibm-orchestrate.mdx b/examplecode/tools/ibm-orchestrate.mdx index b822c268..76d90ef6 100644 --- a/examplecode/tools/ibm-orchestrate.mdx +++ b/examplecode/tools/ibm-orchestrate.mdx @@ -6,16 +6,27 @@ To use this example, you will need the following: - Within your IBM Cloud account, an IBM watsonx.data subscription that contains a Milvus service instance. - Create an [IBM Cloud account](https://cloud.ibm.com/registration). + + To complete this example, you will to [create an API key](https://www.ibm.com/docs/en/masv-and-l/cd?topic=cli-creating-your-cloud-api-key) for your IBM Cloud account. + - Create an [IBM watsonx.data subscription](https://cloud.ibm.com/watsonxdata) in your IBM Cloud account. - Create a [Milvus service instance](/ui/destinations/milvus) within your IBM watsonx.data subscription plan. + To complete this example, you will need the following settings for the Milvus service instance: + + - The instance's GRPC host value. + - The instance's GRPC port value. + - The name of the target database on the instance. + - The name of the target collection in the database. + - The name of the target index in the collection. + - Within your Unstructured account, a workflow that contains a Milvus destination connector. - Create an [Unstructured account](https://unstructured.io/signup). - Create a [Milvus destination connector](/ui/destinations/milvus) in your Unstructured account. - - Create a [workflow]() that contains the Milvus destination connector in your Unstructured account. + - Create a [custom workflow](/ui/workflows#create-a-custom-workflow) that contains the Milvus destination connector in your Unstructured account. - The workflow must generate [embeddings](/ui/embedding). The workflow's **Embedder** node's selected embedding model provider must be "IBM". The + The workflow must generate [embeddings](/ui/embedding). The workflow's **Embedder** node's selected embedding model provider must be **IBM watson.ai**. The node's selected embedding model must be one of the following models that are offered by IBM watsonx Orchestrate: - `all-minilm6-v2`, with 384 dimensions. Per IBM, this model is good for tasks such as information retrieval, clustering, and for detecting sentence similarity. @@ -65,10 +76,36 @@ In this step, ... 7. On the **Connect Milvus** page, specify the following settings: a. For **GRPC host**, enter the GRPC host value for the Milvus service instance within your IBM watsonx.data subscription.
- b. For **GRPC port**, enter the GRPC port value for the Milvus service instance.
+ b. For **GRPC port**, enter the GRPC port value for the instance.
c. For **Choose an authentication type**, select **Basic authentication**.
d. For **Username**, enter `ibmlhapikey`.
e. For **Password**, enter the API key for your IBM Cloud account.
f. Click **Next**.
-8. ... \ No newline at end of file +8. On the **Select index** page, specify the following settings: + + a. For **Database**, select the name of the target database on the Milvus service instance within your IBM watsonx.data subscription.
+ b. For **Use Collection or Alias**, select **Collection**.
+ c. For **Collection**, select the name of the target collection in the database.
+ d. For **Index**, select the name of the target index in the collection.
+ e. For **Embedding model**, select the name of the embedding model that matches the one that you specified in your Unstructured workflow.
+ f. for **Title**, select **element_id**.
+ g. For **Body**, select **text**.
+ h. Click **Next**.
+ +9. On the **Description** page, enter some description for the agent, and then click **Save**. +10. In the list of pages, click **Behavior**. +11. Switch on **Chat with documents**. +10. Click **Deploy**. +11. On the **Pre-deployment summary** page, click **Deploy**. + +## Step 3: ... + +In this step, ... + +1. If the **Chat** page is not already open in IBM watsonxOrchestrate, click the **Open the main menu** icon to the far left of the + top navigation bar, and then click **Chat**. +2. In the sidebar, in the **Agents** list, select the name of the agent that you created in the previous step. +3. In the **Type something** box, enter a question, and then press `Enter`. +4. The agent will provide an answer. +5. Keep asking as many questions as you want to. \ No newline at end of file From 5ff7d682257d35dc38b62646b1424e14b9e089a1 Mon Sep 17 00:00:00 2001 From: Paul Cornell Date: Mon, 29 Sep 2025 08:41:05 -0700 Subject: [PATCH 3/3] Finished adding initial content --- docs.json | 1 + examplecode/tools/ibm-orchestrate.mdx | 55 ++++++++++++++------------- 2 files changed, 30 insertions(+), 26 deletions(-) diff --git a/docs.json b/docs.json index 9f5b6286..bfa6b27a 100644 --- a/docs.json +++ b/docs.json @@ -294,6 +294,7 @@ "examplecode/tools/vectorshift", "examplecode/tools/mcp", "examplecode/tools/mcp-partition", + "examplecode/tools/ibm-orchestrate", "examplecode/tools/snowflake-streamlit", "examplecode/tools/crewai", "examplecode/tools/neo4j-chatbot" diff --git a/examplecode/tools/ibm-orchestrate.mdx b/examplecode/tools/ibm-orchestrate.mdx index 76d90ef6..df65272c 100644 --- a/examplecode/tools/ibm-orchestrate.mdx +++ b/examplecode/tools/ibm-orchestrate.mdx @@ -1,3 +1,13 @@ +--- +title: IBM watsonx Orchestrate +--- + +[IBM watsonx Orchestrate](https://www.ibm.com/products/watsonx-orchestrate) helps you build, deploy and manage powerful +AI assistants and agents that automate workflows and processes with generative AI. + +This article provides a hands-on, step-by-step walkthrough that uses IBM watsonx Orchestrate to +build a simple AI chat app. This chat app relies on data that is stored in a Milvus vector database. This data +is generated by Unstructured and is based on your organization's source documents and semi-structured data. ## Requirements @@ -7,10 +17,11 @@ To use this example, you will need the following: - Create an [IBM Cloud account](https://cloud.ibm.com/registration). - To complete this example, you will to [create an API key](https://www.ibm.com/docs/en/masv-and-l/cd?topic=cli-creating-your-cloud-api-key) for your IBM Cloud account. + To complete this example, you must [create an API key](https://www.ibm.com/docs/en/masv-and-l/cd?topic=cli-creating-your-cloud-api-key) for your IBM Cloud account. - Create an [IBM watsonx.data subscription](https://cloud.ibm.com/watsonxdata) in your IBM Cloud account. - - Create a [Milvus service instance](/ui/destinations/milvus) within your IBM watsonx.data subscription plan. + - Create a [Milvus service instance](/ui/destinations/milvus) within your IBM watsonx.data subscription plan. This instance + must contain a database, a collection, and an index to store and manage the data that is generated by Unstructured. To complete this example, you will need the following settings for the Milvus service instance: @@ -20,6 +31,8 @@ To use this example, you will need the following: - The name of the target collection in the database. - The name of the target index in the collection. + To get these settings, see the [Milvus destination connector](/ui/destinations/milvus) documentation. + - Within your Unstructured account, a workflow that contains a Milvus destination connector. - Create an [Unstructured account](https://unstructured.io/signup). @@ -27,24 +40,11 @@ To use this example, you will need the following: - Create a [custom workflow](/ui/workflows#create-a-custom-workflow) that contains the Milvus destination connector in your Unstructured account. The workflow must generate [embeddings](/ui/embedding). The workflow's **Embedder** node's selected embedding model provider must be **IBM watson.ai**. The - node's selected embedding model must be one of the following models that are offered by IBM watsonx Orchestrate: - - - `all-minilm6-v2`, with 384 dimensions. Per IBM, this model is good for tasks such as information retrieval, clustering, and for detecting sentence similarity. - - `granite-embedding-107m-multilingual`, with 384 dimensions. Per IBM, this model is good for tasks such as text similarity, retrieval, and search. - - `granite-embedding-278m-multilingual`, with 768 dimensions. - - `multilingual-e5-large`, with 1024 dimensions. Per IBM, this model is good for generating text embeddings for text in a language other than English. - - `slate-125m-english-retrvr`, with 768 dimensions. Per IBM, the `slate-125m-*` models are good for generating embeddings for various inputs such as queries, passages, or documents. Per IBM, the `slate-125m-*` models are two to three times slower but perform slightly better than the `slate-30m-*` models. - - `slate-125m-english-retrvr-v2`, with 768 dimensions. - - `slate-30m-english-retrvr`, with 384 dimensions. Per IBM, the `slate-30m-*` models are trained to maximize the cosine similarity between two text inputs so that embeddings can be evaluated based on similarity later. Per IBM, the `slate-30m-*` models are two to three times faster and have slightly lower performance scores than the `slate-125m-*` models. - - `slate-30m-english-retrvr-v2`, with 384 dimensions. - - Be sure to [run the workflow](/ui/workflows#edit%2C-delete%2C-or-run-a-workflow) to have Unstructured generate the embeddings and store them—along with - Unstructured's processed data representing your organization's source documents and semi-structured data—in the database - that is accessed through the Milvus service instance within your IBM watsonx.data subscription. + node's selected embedding model must match the embedding model that you will specify later in **Step 2**. -## Step 1: ... + Be sure to [run the workflow](/ui/workflows#edit%2C-delete%2C-or-run-a-workflow) to have Unstructured generate the data and store it in your Milvus instance's database. -In this step, you add an IBM watsonx Orchestrate subscription to your IBM Cloud account. +## Step 1: Add an IBM watsonx Orchestrate subscription to your IBM Cloud account If you already have an IBM watsonx Orchestrate subscription, then skip ahead to **Step 2**. @@ -55,9 +55,11 @@ If you already have an IBM watsonx Orchestrate subscription, then skip ahead to 4. With **IBM Cloud catalog** selected, search for and select **watsonx Orchestrate**. 5. Complete the on-screen instructions to finish creating the IBM watsonx Orchestrate subscription. -## Step 2: ... +## Step 2: Create the chat app in IBM watsonx Orchestrate -In this step, ... +In this step, you use IBM watsonx Orchestrate to create a chat app. This chat app allows you to ask questions about +your organization's documents and semi-structured data. This data is stored in your Milvus instance's database and was +generated by Unstructured in a format that is well-suited for your chat app. 1. Open your IBM watsonx Orchestrate subscription, if it is not already open. To do this: @@ -70,7 +72,7 @@ In this step, ... 2. If the **Chat** page is not already open, click the **Open the main menu** icon to the far left of the top navigation bar, and then click **Chat**. 3. Toward the bottom of the sidebar, click **Create new agent**. -4. On the **Create an agent** page, with **Create from scratch** already selected, enter some **Name** and **Description**for the agent, and then click **Create**. +4. On the **Create an agent** page, with **Create from scratch** already selected, enter some **Name** and **Description** for the agent, and then click **Create**. 5. Under **Knowledge source**, in the **Start by adding knowledge** tile, click **Choose knowledge**. 6. On the **Select source** page, click **Milvus**, and then click **Next**. 7. On the **Connect Milvus** page, specify the following settings: @@ -88,8 +90,8 @@ In this step, ... b. For **Use Collection or Alias**, select **Collection**.
c. For **Collection**, select the name of the target collection in the database.
d. For **Index**, select the name of the target index in the collection.
- e. For **Embedding model**, select the name of the embedding model that matches the one that you specified in your Unstructured workflow.
- f. for **Title**, select **element_id**.
+ e. For **Embedding model**, select the name of the embedding model that matches the one that you specified earlier in your Unstructured workflow.
+ f. For **Title**, select **element_id**.
g. For **Body**, select **text**.
h. Click **Next**.
@@ -99,11 +101,12 @@ In this step, ... 10. Click **Deploy**. 11. On the **Pre-deployment summary** page, click **Deploy**. -## Step 3: ... +## Step 3: Run the chat app -In this step, ... +In this step, you ask questions about your organization's source documents and semi-structured data. The chat app then +attempts to answer your questions by searching the related data that Unstructured generated and stored in your Milvus instance's database. -1. If the **Chat** page is not already open in IBM watsonxOrchestrate, click the **Open the main menu** icon to the far left of the +1. If the **Chat** page is not already open in IBM watsonx Orchestrate, click the **Open the main menu** icon to the far left of the top navigation bar, and then click **Chat**. 2. In the sidebar, in the **Agents** list, select the name of the agent that you created in the previous step. 3. In the **Type something** box, enter a question, and then press `Enter`.