From 215fd8eca926bc7b2e68d76e5037e7ba9d2c5699 Mon Sep 17 00:00:00 2001 From: writinwaters Date: Fri, 17 Jan 2025 11:45:52 +0800 Subject: [PATCH 1/7] Added descriptions of Rewrite and Switch components. TBC --- docs/guides/agent/agent_introduction.md | 3 +- .../agent_component_reference/rewrite.mdx | 80 +++++++++++++++++++ .../agent_component_reference/switch.mdx | 69 ++++++++++++++++ web/src/locales/en.ts | 4 +- 4 files changed, 152 insertions(+), 4 deletions(-) create mode 100644 docs/references/agent_component_reference/rewrite.mdx create mode 100644 docs/references/agent_component_reference/switch.mdx diff --git a/docs/guides/agent/agent_introduction.md b/docs/guides/agent/agent_introduction.md index ec2b043902d..17bbba29851 100644 --- a/docs/guides/agent/agent_introduction.md +++ b/docs/guides/agent/agent_introduction.md @@ -62,8 +62,7 @@ Please review the flowing description of the RAG-specific components before you | **Interact** | A component that serves as the interface between human and the bot, receiving user inputs and displaying the agent's responses. | | **Categorize** | A component that uses the LLM to classify user inputs into predefined categories. Ensure you specify the name, description, and examples for each category, along with the corresponding next component. | | **Message** | A component that sends out a static message. If multiple messages are supplied, it randomly selects one to send. Ensure its downstream is **Interact**, the interface component. | -| **Relevant** | A component that uses the LLM to assess whether the upstream output is relevant to the user's latest query. Ensure you specify the next component for each judge result. | -| **Rewrite** | A component that refines a user query if it fails to retrieve relevant information from the knowledge base. It repeats this process until the predefined looping upper limit is reached. Ensure its upstream is **Relevant** and downstream is **Retrieval**. | +| **Rewrite** | A component that edits, corrects, expands, or rewrites a user query from user-agent interaction, based on the context of previous dialogues. | | **Keyword** | A component that extracts keywords from a user query, with TopN specifying the number of keywords to extract. | :::caution NOTE diff --git a/docs/references/agent_component_reference/rewrite.mdx b/docs/references/agent_component_reference/rewrite.mdx new file mode 100644 index 00000000000..21234182697 --- /dev/null +++ b/docs/references/agent_component_reference/rewrite.mdx @@ -0,0 +1,80 @@ +--- +sidebar_position: 8 +slug: /rewrite_component +--- + +# Rewrite component + +A component that edits, corrects, expands, or rewrites a user query. + +--- + +A **Rewrite** component edits, corrects, expands, or rewrites a user query from user-agent interaction, based on the context of previous dialogues. + +## Scenarios + +A **Rewrite** component is essential when you need to optimize a user query based on the context of previous conversations. It is usually used in conjunction with a **Retrieval** component. + +See also the [Keyword](https://ragflow.io/docs/dev/keyword_component) component, a similar component used for multi-turn optimization. + +## Configurations + +:::tip NOTE +The **Rewrite** component uses the user-agent interaction from the **Interact** component as its data input. Therefore, there is no need to specify its data inputs in the Configurations. +::: + +### Model + +Click the dropdown menu of **Model** to show the model configuration window. + +- **Model**: The chat model to use. + - Ensure you set the chat model correctly on the **Model providers** page. + - You can use different models for different components to increase flexibility or improve overall performance. +- **Freedom**: A shortcut to **Temperature**, **Top P**, **Presence penalty**, and **Frequency penalty** settings, indicating the freedom level of the model. + This parameter has three options: + - **Improvise**: Produces more creative responses. + - **Precise**: (Default) Produces more conservative responses. + - **Balance**: A middle ground between **Improvise** and **Precise**. +- **Temperature**: The randomness level of the model's output. + Defaults to 0.1. + - Lower values lead to more deterministic and predictable outputs. + - Higher values lead to more creative and varied outputs. + - A temperature of zero results in the same output for the same prompt. +- **Top P**: Nucleus sampling. + - Reduces the likelihood of generating repetitive or unnatural text by setting a threshold *P* and restricting the sampling to tokens with a cumulative probability exceeding *P*. + - Defaults to 0.3. +- **Presence penalty**: Encourages the model to include a more diverse range of tokens in the response. + - A higher **presence penalty** value results in the model being more likely to generate tokens not yet been included in the generated text. + - Defaults to 0.4. +- **Frequency penalty**: Discourages the model from repeating the same words or phrases too frequently in the generated text. + - A higher **frequency penalty** value results in the model being more conservative in its use of repeated tokens. + - Defaults to 0.7. +- **Max tokens**: Sets the maximum length of the model's output, measured in the number of tokens. + - Defaults to 512. + - If disabled, you lift the maximum token limit, allowing the model to determine the number of tokens in its responses. + +:::tip NOTE +- It is not necessary to stick with the same model for all components. If a specific model is not performing well for a particular task, consider using a different one. +- If you are uncertain about the mechanism behind **Temperature**, **Top P**, **Presence penalty**, and **Frequency penalty**, you can simply choose one of the three options of **Freedom**. +::: + + +### Message window size + +An integer specifying the number of previous dialogue rounds to input into the LLM. For example, if it is set to 12, the tokens from the last 12 dialogue rounds will be fed to the LLM. This feature consumes additional tokens. + +Defaults to 1. + +:::tip IMPORTANT +This feature is used for multi-turn dialogue *only*. If your **Categorize** component is not part of a multi-turn dialogue (i.e., it is not in a loop), leave this field as-is. +::: + +## Examples + +Explore our customer service agent template, where the **Rewrite** component (component ID: **Refine Question**) is used to optimize a product-specific user query based on context of previous dialogues before passing it on to the **Retrieval** component. + +1. Click the **Agent** tab at the top center of the page to access the **Agent** page. +2. Click **+ Create agent** on the top right of the page to open the **agent template** page. +3. On the **agent template** page, hover over the **Customer service** card and click **Use this template**. +4. Name your new agent and click **OK** to enter the workflow editor. +5. Click on the **Rewrite** component to display its **Configuration** window. \ No newline at end of file diff --git a/docs/references/agent_component_reference/switch.mdx b/docs/references/agent_component_reference/switch.mdx new file mode 100644 index 00000000000..e67947f44eb --- /dev/null +++ b/docs/references/agent_component_reference/switch.mdx @@ -0,0 +1,69 @@ +--- +sidebar_position: 9 +slug: /switch_component +--- + +# Switch component + +The component that evaluates whether specified conditions are met and applies strategies accordingly. + +--- + +A **Switch** component evaluates conditions based on the output of specific components and directs the flow of execution accordingly. It allows for complex branching logic by defining cases and specifying actions for each case or default action if no conditions are met. + +## Scenarios + +A **Switch** component is essential for condition-based flow of execution. It is somewhat similar to the [Categorize](https://ragflow.io/docs/dev/categorize_component) component, which is also used for multi-pronged strategies. The difference is that it does not involve an LLM and that there is a *clearer* line between the conditions it defines. + +## Configurations + +TO BE CONTINUED. + +### Input + +The **Switch** component relies on input variables to specify its data inputs (queries). Click **+ Add variable** in the **Input** section to add the desired input variables. There are two types of input variables: **Reference** and **Text**. + +- **Reference**: Uses a component's output or a user input as the data source. You are required to select from the dropdown menu: + - A component ID under **Component Output**, or + - A global variable under **Begin input**, which is defined in the **Begin** component. +- **Text**: Uses fixed text as the query. You are required to enter static text. + +### Case n + +A **Switch** component must have at least one case. This field sets the conditions and the corresponding downstream component. + +#### Condition + +- **Component ID** +- **Operator** + - Equals + - Not equal + - Greater than + - Greater equal + - Less than + - Less equal + - Contains + - Not contains + - Starts with + - Ends with + - Is empty + - Not empty +- **Value** + +#### Next step + +Specifies the downstream component of this case. + +- Once you specify the ID of the downstream component, a link is established between this case and the corresponding component. +- If you manually link this category to a downstream component on the canvas, the ID of that component is auto-populated. + + +### ELSE + +Optional + +## Frequently asked questions + +### Where to specify the data inputs for this component? + +The **Switch** component evaluates only whether specific conditions are met and directs the flow of execution accordingly. It does not accept data input, so there is no need to specify data inputs. \ No newline at end of file diff --git a/web/src/locales/en.ts b/web/src/locales/en.ts index 130f37ad0b5..dc194520464 100644 --- a/web/src/locales/en.ts +++ b/web/src/locales/en.ts @@ -751,7 +751,7 @@ This procedure will improve precision of retrieval by adding more information to generateDescription: `A component that prompts the LLM to generate responses. Ensure the prompt is set correctly.`, categorizeDescription: `A component that uses the LLM to classify user inputs into predefined categories. Ensure you specify the name, description, and examples for each category, along with the corresponding next component.`, relevantDescription: `A component that uses the LLM to assess whether the upstream output is relevant to the user's latest query. Ensure you specify the next component for each judge result.`, - rewriteQuestionDescription: `A component that refines a user query if it fails to retrieve relevant information from the knowledge base. It repeats this process until the predefined looping upper limit is reached.`, + rewriteQuestionDescription: `A component that edits, corrects, expands, or rewrites a user query from user-agent interaction, based on the context of previous dialogues.`, messageDescription: "A component that sends out a static message. If multiple messages are supplied, it randomly selects one to send. Ensure its downstream is 'Interact', the interface component.", keywordDescription: `A component that retrieves top N search results from user's input. Ensure the TopN value is set properly before use.`, @@ -1103,7 +1103,7 @@ This procedure will improve precision of retrieval by adding more information to testRun: 'Test Run', template: 'Template', templateDescription: - 'A component that formats the output of another component.', + 'A component that formats the output of other components.', emailComponent: 'Email', emailDescription: 'Send an email to a specified address.', smtpServer: 'SMTP Server', From e345b3c8751db139ec28f5460e1beacc24db19e3 Mon Sep 17 00:00:00 2001 From: writinwaters Date: Fri, 17 Jan 2025 11:53:37 +0800 Subject: [PATCH 2/7] minor --- docs/references/agent_component_reference/switch.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/agent_component_reference/switch.mdx b/docs/references/agent_component_reference/switch.mdx index e67947f44eb..c8c47895f43 100644 --- a/docs/references/agent_component_reference/switch.mdx +++ b/docs/references/agent_component_reference/switch.mdx @@ -60,7 +60,7 @@ Specifies the downstream component of this case. ### ELSE -Optional +Required. ## Frequently asked questions From 683460e0e93fa2e28f3ef0492fa630609804a53a Mon Sep 17 00:00:00 2001 From: writinwaters Date: Fri, 17 Jan 2025 12:21:36 +0800 Subject: [PATCH 3/7] minor --- docs/references/agent_component_reference/switch.mdx | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/references/agent_component_reference/switch.mdx b/docs/references/agent_component_reference/switch.mdx index c8c47895f43..b16b6899bb4 100644 --- a/docs/references/agent_component_reference/switch.mdx +++ b/docs/references/agent_component_reference/switch.mdx @@ -19,15 +19,6 @@ A **Switch** component is essential for condition-based flow of execution. It is TO BE CONTINUED. -### Input - -The **Switch** component relies on input variables to specify its data inputs (queries). Click **+ Add variable** in the **Input** section to add the desired input variables. There are two types of input variables: **Reference** and **Text**. - -- **Reference**: Uses a component's output or a user input as the data source. You are required to select from the dropdown menu: - - A component ID under **Component Output**, or - - A global variable under **Begin input**, which is defined in the **Begin** component. -- **Text**: Uses fixed text as the query. You are required to enter static text. - ### Case n A **Switch** component must have at least one case. This field sets the conditions and the corresponding downstream component. From 3faf044c1d66422cd78edca753e5dbed637db343 Mon Sep 17 00:00:00 2001 From: writinwaters Date: Mon, 20 Jan 2025 03:33:06 +0800 Subject: [PATCH 4/7] Updates based on feedback --- docs/references/agent_component_reference/rewrite.mdx | 8 +++++--- docs/references/agent_component_reference/switch.mdx | 6 +++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/references/agent_component_reference/rewrite.mdx b/docs/references/agent_component_reference/rewrite.mdx index 21234182697..cef3eaa4569 100644 --- a/docs/references/agent_component_reference/rewrite.mdx +++ b/docs/references/agent_component_reference/rewrite.mdx @@ -5,17 +5,19 @@ slug: /rewrite_component # Rewrite component -A component that edits, corrects, expands, or rewrites a user query. +A component that rewrites a user query. --- -A **Rewrite** component edits, corrects, expands, or rewrites a user query from user-agent interaction, based on the context of previous dialogues. +A **Rewrite** component uses a specified LLM to rewrite a user query from the **Interact** component, based on the context of previous dialogues. ## Scenarios -A **Rewrite** component is essential when you need to optimize a user query based on the context of previous conversations. It is usually used in conjunction with a **Retrieval** component. +A **Rewrite** component is essential when you need to optimize a user query based on the context of previous conversations. It is usually the upstream component of a **Retrieval** component. +:::tip NOTE See also the [Keyword](https://ragflow.io/docs/dev/keyword_component) component, a similar component used for multi-turn optimization. +::: ## Configurations diff --git a/docs/references/agent_component_reference/switch.mdx b/docs/references/agent_component_reference/switch.mdx index b16b6899bb4..f5033a203a6 100644 --- a/docs/references/agent_component_reference/switch.mdx +++ b/docs/references/agent_component_reference/switch.mdx @@ -5,15 +5,15 @@ slug: /switch_component # Switch component -The component that evaluates whether specified conditions are met and applies strategies accordingly. +A component that evaluates whether specified conditions are met and directs the follow of execution accordingly. --- -A **Switch** component evaluates conditions based on the output of specific components and directs the flow of execution accordingly. It allows for complex branching logic by defining cases and specifying actions for each case or default action if no conditions are met. +A **Switch** component evaluates conditions based on the output of specific components, directing the flow of execution to enable complex branching logic. ## Scenarios -A **Switch** component is essential for condition-based flow of execution. It is somewhat similar to the [Categorize](https://ragflow.io/docs/dev/categorize_component) component, which is also used for multi-pronged strategies. The difference is that it does not involve an LLM and that there is a *clearer* line between the conditions it defines. +A **Switch** component is essential for condition-based direction of execution flow. While it shares similarities with the [Categorize](https://ragflow.io/docs/dev/categorize_component) component, which is also used in multi-pronged strategies, the key distinction lies in their approach: the evaluation of the **Switch** component is rule-based, whereas the **Categorize** component involves AI and uses an LLM for decision-making. ## Configurations From 3802d8856a69c60e34872a497363d150ad04bd21 Mon Sep 17 00:00:00 2001 From: writinwaters Date: Mon, 20 Jan 2025 06:51:42 +0800 Subject: [PATCH 5/7] minor --- .../agent_component_reference/switch.mdx | 43 ++++++++++--------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/docs/references/agent_component_reference/switch.mdx b/docs/references/agent_component_reference/switch.mdx index f5033a203a6..7e71955e192 100644 --- a/docs/references/agent_component_reference/switch.mdx +++ b/docs/references/agent_component_reference/switch.mdx @@ -9,7 +9,7 @@ A component that evaluates whether specified conditions are met and directs the --- -A **Switch** component evaluates conditions based on the output of specific components, directing the flow of execution to enable complex branching logic. +A **Switch** component evaluates conditions based on the output of specific components, directing the flow of execution accordingly to enable complex branching logic. ## Scenarios @@ -17,16 +17,27 @@ A **Switch** component is essential for condition-based direction of execution f ## Configurations -TO BE CONTINUED. - ### Case n -A **Switch** component must have at least one case. This field sets the conditions and the corresponding downstream component. +A **Switch** component must have at least one case, each with multiple specified conditions and corresponding downstream components. When multiple conditions are specified for a case, you must set the logical relationship between them to either AND or OR. + +#### Next step + +Specifies the downstream component of this case. + +- *Once you specify the ID of the downstream component, a link is established between this case and the corresponding component.* +- *If you manually link this category to a downstream component on the canvas, the ID of that component is auto-populated.* #### Condition -- **Component ID** -- **Operator** +Evaluates whether the output of specific components meets certain conditions, with **Component ID**, **Operator**, and **Value** together forming a conditional expression. + +:::danger IMPORTANT +When you have added multiple conditions for a specific case, a **Logical operator** field appears, requiring you to set the logical relationship between these conditions as either AND or OR. +::: + +- **Component ID**: The ID of the corresponding component. +- **Operator**: The operator required to form a conditional expression. - Equals - Not equal - Greater than @@ -39,22 +50,12 @@ A **Switch** component must have at least one case. This field sets the conditio - Ends with - Is empty - Not empty -- **Value** - -#### Next step - -Specifies the downstream component of this case. - -- Once you specify the ID of the downstream component, a link is established between this case and the corresponding component. -- If you manually link this category to a downstream component on the canvas, the ID of that component is auto-populated. - +- **Value**: A single value, which can be an integer, float, or string. + - Delimiters, multiple values, or expressions are *not* supported. + - Strings need not be wrapped in `""` or `''`. ### ELSE -Required. - -## Frequently asked questions - -### Where to specify the data inputs for this component? +**Required**. Specifies the downstream component if none of the conditions defined above are met. -The **Switch** component evaluates only whether specific conditions are met and directs the flow of execution accordingly. It does not accept data input, so there is no need to specify data inputs. \ No newline at end of file +*Once you specify the ID of the downstream component, a link is established between ELSE and the corresponding component.* From 2ed6a2853d8776e7013de925254d51c02cb1208e Mon Sep 17 00:00:00 2001 From: writinwaters Date: Mon, 20 Jan 2025 07:00:35 +0800 Subject: [PATCH 6/7] minor --- docs/references/agent_component_reference/switch.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/agent_component_reference/switch.mdx b/docs/references/agent_component_reference/switch.mdx index 7e71955e192..f2f709e37e0 100644 --- a/docs/references/agent_component_reference/switch.mdx +++ b/docs/references/agent_component_reference/switch.mdx @@ -26,7 +26,7 @@ A **Switch** component must have at least one case, each with multiple specified Specifies the downstream component of this case. - *Once you specify the ID of the downstream component, a link is established between this case and the corresponding component.* -- *If you manually link this category to a downstream component on the canvas, the ID of that component is auto-populated.* +- *If you manually link this case to a downstream component on the canvas, the ID of that component is auto-populated.* #### Condition From 3eb007bb3750a918722ac2b4e8e2c7b388d6fe58 Mon Sep 17 00:00:00 2001 From: writinwaters Date: Mon, 20 Jan 2025 07:55:51 +0800 Subject: [PATCH 7/7] minor --- docs/guides/agent/agent_introduction.md | 2 +- docs/references/agent_component_reference/concentrator.mdx | 0 web/src/locales/en.ts | 2 +- 3 files changed, 2 insertions(+), 2 deletions(-) create mode 100644 docs/references/agent_component_reference/concentrator.mdx diff --git a/docs/guides/agent/agent_introduction.md b/docs/guides/agent/agent_introduction.md index 17bbba29851..2c871ccb876 100644 --- a/docs/guides/agent/agent_introduction.md +++ b/docs/guides/agent/agent_introduction.md @@ -62,7 +62,7 @@ Please review the flowing description of the RAG-specific components before you | **Interact** | A component that serves as the interface between human and the bot, receiving user inputs and displaying the agent's responses. | | **Categorize** | A component that uses the LLM to classify user inputs into predefined categories. Ensure you specify the name, description, and examples for each category, along with the corresponding next component. | | **Message** | A component that sends out a static message. If multiple messages are supplied, it randomly selects one to send. Ensure its downstream is **Interact**, the interface component. | -| **Rewrite** | A component that edits, corrects, expands, or rewrites a user query from user-agent interaction, based on the context of previous dialogues. | +| **Rewrite** | A component that rewrites a user query from the **Interact** component, based on the context of previous dialogues. | | **Keyword** | A component that extracts keywords from a user query, with TopN specifying the number of keywords to extract. | :::caution NOTE diff --git a/docs/references/agent_component_reference/concentrator.mdx b/docs/references/agent_component_reference/concentrator.mdx new file mode 100644 index 00000000000..e69de29bb2d diff --git a/web/src/locales/en.ts b/web/src/locales/en.ts index 42b86131f55..19c901c1909 100644 --- a/web/src/locales/en.ts +++ b/web/src/locales/en.ts @@ -751,7 +751,7 @@ This procedure will improve precision of retrieval by adding more information to generateDescription: `A component that prompts the LLM to generate responses. Ensure the prompt is set correctly.`, categorizeDescription: `A component that uses the LLM to classify user inputs into predefined categories. Ensure you specify the name, description, and examples for each category, along with the corresponding next component.`, relevantDescription: `A component that uses the LLM to assess whether the upstream output is relevant to the user's latest query. Ensure you specify the next component for each judge result.`, - rewriteQuestionDescription: `A component that edits, corrects, expands, or rewrites a user query from user-agent interaction, based on the context of previous dialogues.`, + rewriteQuestionDescription: `A component that rewrites a user query from the Interact component, based on the context of previous dialogues.`, messageDescription: "A component that sends out a static message. If multiple messages are supplied, it randomly selects one to send. Ensure its downstream is 'Interact', the interface component.", keywordDescription: `A component that retrieves top N search results from user's input. Ensure the TopN value is set properly before use.`,