创建自定义Python组件

自定义组件是在 Blaflow 内部创建的，通过可重用的 Python 代码扩展平台功能。

由于 Blaflow 在后台使用 Python 运行，您可以在自定义组件中实现任何 Python 函数。这意味着您可以利用 Pandas、Scikit-learn、Numpy 等库的强大功能，以及数千个其他包来创建以无限方式处理数据的组件。只要类型在输出方法中正确注释(例如> list[int])，您可以使用任何类型。

自定义组件创建可重用和可配置的组件，增强 Blaflow 的能力，使其成为开发用户和 AI 消息之间复杂处理的强大工具。

目录结构要求

默认情况下，Blaflow 在blaflow/components目录中查找自定义组件。

如果您使用 BLAFLOW_COMPONENTS_PATH 环境变量在不同的位置创建自定义组件，组件必须组织在特定的目录结构中才能正确加载并显示在 UI 中：


_10/your/custom/components/path/    # 基础目录(由BLAFLOW_COMPONENTS_PATH设置)
_10    └── category_name/          # 必需的类别子文件夹(决定菜单名称)
_10        └── custom_component.py # 组件文件

组件必须放在类别文件夹内，而不是直接放在基础目录中。类别文件夹名称决定组件在 UI 菜单中的显示位置。

例如，要将组件添加到Helpers菜单，将其放在helpers子文件夹中：


_10/app/custom_components/          # BLAFLOW_COMPONENTS_PATH
_10    └── helpers/                 # 显示为"Helpers"菜单
_10        └── custom_component.py  # 您的组件

您可以有多个类别文件夹将组件组织到不同的菜单中：


_10/app/custom_components/
_10    ├── helpers/
_10    │   └── helper_component.py
_10    └── tools/
_10        └── tool_component.py

此文件夹结构是 Blaflow 正确发现和加载自定义组件所必需的。直接放在基础目录中的组件将不会被加载。


_10/app/custom_components/          # BLAFLOW_COMPONENTS_PATH
_10    └── custom_component.py      # 不会被加载 - 缺少类别文件夹!

在 Blaflow 中创建自定义组件

在 Blaflow 中创建自定义组件涉及创建一个 Python 类，该类定义组件的功能、输入和输出。默认代码为您的自定义组件提供了一个工作结构。


_25# from blaflow.field_typing import Data
_25from blaflow.custom import Component
_25from blaflow.io import MessageTextInput, Output
_25from blaflow.schema import Data
_25
_25
_25class CustomComponent(Component):
_25    display_name = "Custom Component"
_25    description = "Use as a template to create your own component."
_25    documentation: str = "https://docs.blaflow.com/components-custom-components"
_25    icon = "custom_components"
_25    name = "CustomComponent"
_25
_25    inputs = [
_25        MessageTextInput(name="input_value", display_name="Input Value", value="Hello, World!"),
_25    ]
_25
_25    outputs = [
_25        Output(display_name="Output", name="output", method="build_output"),
_25    ]
_25
_25    def build_output(self) -> Data:
_25        data = Data(value=self.input_value)
_25        self.status = data
_25        return data

您可以在 Blaflow 之外的您喜欢的文本编辑器中创建您的类，稍后粘贴进来，或者直接在代码窗格中跟随操作。

在 Blaflow 中，点击新增自定义组件将自定义组件添加到工作区。
打开组件的代码窗格。
导入依赖项。您的自定义组件继承自 blaflow 的Component类，因此需要包含它。


_10from blaflow.custom import Component
_10from blaflow.io import MessageTextInput, Output
_10from blaflow.schema import Data

定义类：首先定义一个继承自Component的 Python 类。这个类将封装自定义组件的功能。


_10class CustomComponent(Component):
_10    display_name = "Custom Component"
_10    description = "Use as a template to create your own component."
_10    documentation: str = "https://docs.blaflow.com/components-custom-components"
_10    icon = "custom_components"
_10    name = "CustomComponent"

指定输入和输出：使用 Blaflow 的输入和输出类来定义组件的输入和输出。它们应声明为类属性。


_10    inputs = [
_10        MessageTextInput(name="input_value", display_name="Input Value", value="Hello, World!"),
_10    ]
_10
_10    outputs = [
_10        Output(display_name="Output", name="output", method="build_output"),
_10    ]

实现输出方法：为每个输出实现方法，其中包含组件的逻辑。这些方法可以使用self.<input_name>访问输入值，返回处理后的值，并使用self.status属性定义组件中显示的内容。


_10    def build_output(self) -> Data:
_10        data = Data(value=self.input_value)
_10        self.status = data
_10        return data

使用适当的注释：确保输出方法正确注释其类型。Blaflow 使用这些注释来正确验证和处理数据。例如，此方法注释为输出Data。


_10    def build_output(self) -> Data:

点击Check & Save确认您的组件工作正常。您现在有了一个可操作的自定义组件。

添加输入和修改输出方法

此代码定义了一个接受 5 个输入并输出消息的自定义组件。

复制并粘贴到自定义组件代码窗格中，然后点击检查并保存


_55from blaflow.custom import Component
_55from blaflow.inputs import StrInput, MultilineInput, SecretStrInput, IntInput, DropdownInput
_55from blaflow.template import Output, Input
_55from blaflow.schema.message import Message
_55
_55class MyCustomComponent(Component):
_55    display_name = "My Custom Component"
_55    description = "An example of a custom component with various input types."
_55
_55    inputs = [
_55        StrInput(
_55            name="username",
_55            display_name="Username",
_55            info="Enter your username."
_55        ),
_55        SecretStrInput(
_55            name="password",
_55            display_name="Password",
_55            info="Enter your password."
_55        ),
_55        MessageTextInput(
_55            name="special_message",
_55            display_name="special_message",
_55            info="Enter a special message.",
_55        ),
_55        IntInput(
_55            name="age",
_55            display_name="Age",
_55            info="Enter your age."
_55        ),
_55        DropdownInput(
_55            name="gender",
_55            display_name="Gender",
_55            options=["Male", "Female", "Other"],
_55            info="Select your gender."
_55        )
_55    ]
_55
_55    outputs = [
_55        Output(display_name="Result", name="result", method="process_inputs"),
_55    ]
_55
_55    def process_inputs(self) -> Message:
_55        """
_55        Process the user inputs and return a Message object.
_55
_55        Returns:
_55            Message: A Message object containing the processed information.
_55        """
_55        try:
_55            processed_text = f"User {self.username} (Age: {self.age}, Gender: {self.gender}) " \
_55                             f"sent the following special message: {self.special_message}"
_55            return Message(text=processed_text)
_55        except AttributeError as e:
_55            return Message(text=f"Error processing inputs: {str(e)}")

由于组件输出Message，您可以将其连接到聊天中并将消息传递给自己。

您的自定义组件通过MessageTextInput接收聊天输入消息，用process_inputs方法填充变量，最后将消息User Username (Age: 49, Gender: Male) sent the following special message: Hello!传递给聊天输出。

通过这种方式定义输入，Blaflow 可以自动处理这些字段在用户界面中的验证和显示，从而更容易创建健壮且用户友好的自定义组件。

上面详细说明的所有类型都派生自一个通用类，也可以通过通用的Input类访问。

tip

使用MessageInput获取整个 Message 对象，而不仅仅是文本。

输入类型

Blaflow 提供了几种高级输入类型，以简化自定义组件的创建。这些输入类型标准化了输入的定义、验证和使用方式。以下是关于如何使用这些输入及其主要用途的指南：

HandleInput

表示具有特定类型(例如BaseLanguage模式l、BaseRetriever等)句柄的输入。

用途：用于连接到流程中的特定组件类型。

DataInput

表示接收Data对象的输入。

用途：适用于处理或操作数据对象的组件。
输入类型：["Data"]

StrInput

表示标准字符串输入字段。

用途：用于需要用户提供字符串的任何文本输入。
输入类型：["Text"]

MessageInput

表示专门用于Message对象的输入字段。

用途：用于处理或处理消息的组件。
输入类型：["Message"]

MessageTextInput

表示消息的文本输入。

用途：适用于需要从消息对象中提取文本的组件。
输入类型：["Message"]

MultilineInput

表示支持多行的文本字段。

用途：适用于用户可能需要编写较长文本的较长文本输入。
输入类型：["Text"]
属性：multiline=True

SecretStrInput

表示密码输入字段。

用途：用于应隐藏的敏感文本输入(例如密码、API 密钥)。
属性：password=True
输入类型：不接受输入类型，意味着它没有输入句柄供前一个节点/组件连接到它。

IntInput

表示整数输入字段。

用途：用于值应为整数的数字输入。
输入类型：["Integer"]

FloatInput

表示浮点数输入字段。

用途：用于值应为浮点数的数字输入。
输入类型：["Float"]

BoolInput

表示布尔输入字段。

用途：用于真/假或是/否类型的输入。
输入类型：["Boolean"]

NestedDictInput

表示嵌套字典的输入字段。

用途：用于需要字典形式的更复杂数据结构。
输入类型：["NestedDict"]

DictInput

表示字典的输入字段。

用途：适用于需要字典格式的输入。
输入类型：["Dict"]

DropdownInput

表示下拉输入字段。

用途：用于用户需要从预定义选项列表中选择的情况。
属性：options定义可选选项列表。
输入类型：["Text"]

文件 Input

表示文件输入字段。

用途：用于上传文件。
属性：file_types指定可以上传的文件类型。
输入类型：["文件"]

通用输入

Blaflow 提供原生输入类型，但只要在输出方法中正确注释(例如-> list[int])，您可以使用任何类型。

Input类高度可定制，允许您为每个输入字段指定广泛的属性。它有几个可以定制的属性：

field_type：指定字段类型(例如str、int)。默认为str。
required：布尔值，指示字段是否为必填。默认为False。
placeholder：输入字段的占位符文本。默认为空字符串。
is_list：布尔值，指示字段是否应接受值列表。默认为False。
show：布尔值，指示是否应显示字段。默认为True。
multiline：布尔值，指示字段是否允许多行输入。默认为False。
value：输入字段的默认值。默认为None。
file_types：接受的文件类型列表(用于文件输入)。默认为空列表。
file_path：如果字段是文件输入，则为文件路径。默认为None。
password：布尔值，指示字段是否为密码。默认为False。
options：字段的选项列表(用于下拉菜单)。默认为None。
name：输入字段的名称。默认为None。
display_name：输入字段的显示名称。默认为None。
advanced：布尔值，指示字段是否为高级参数。默认为False。
input_types：接受的输入类型列表。默认为None。
dynamic：布尔值，指示字段是否为动态。默认为False。
info：输入字段的附加信息或工具提示。默认为空字符串。
real_time_refresh：布尔值，指示字段是否应实时刷新。默认为None。
refresh_button：布尔值，指示字段是否应具有刷新按钮。默认为None。
refresh_button_text：刷新按钮的文本。默认为None。
range_spec：数字字段的范围规范。默认为None。
load_from_db：布尔值，指示字段是否应从数据库加载。默认为False。
title_case：布尔值，指示显示名称是否应为标题大小写。默认为True。

使用通用输入创建自定义组件

以下是使用Input类为组件定义输入的示例。

复制并粘贴到自定义组件代码窗格中，然后点击检查并保存


_76from blaflow.template import Input, Output
_76from blaflow.custom import Component
_76from blaflow.field_typing import Text
_76from blaflow.schema.message import Message
_76from typing import Dict, Any
_76
_76class TextAnalyzerComponent(Component):
_76    display_name = "Text Analyzer"
_76    description = "Analyzes input text and provides basic statistics."
_76
_76    inputs = [
_76        Input(
_76            name="input_text",
_76            display_name="Input Text",
_76            field_type="Message",
_76            required=True,
_76            placeholder="Enter text to analyze",
_76            multiline=True,
_76            info="The text you want to analyze.",
_76            input_types=["Text"]
_76        ),
_76        Input(
_76            name="include_word_count",
_76            display_name="Include Word Count",
_76            field_type="bool",
_76            required=False,
_76            info="Whether to include word count in the analysis.",
_76        ),
_76        Input(
_76            name="perform_sentiment_analysis",
_76            display_name="Perform Sentiment Analysis",
_76            field_type="bool",
_76            required=False,
_76            info="Whether to perform basic sentiment analysis.",
_76        ),
_76    ]
_76
_76    outputs = [
_76        Output(display_name="Analysis Results", name="results", method="analyze_text"),
_76    ]
_76
_76    def analyze_text(self) -> Message:
_76        # Extract text from the Message object
_76        if isinstance(self.input_text, Message):
_76            text = self.input_text.text
_76        else:
_76            text = str(self.input_text)
_76
_76        results = {
_76            "character_count": len(text),
_76            "sentence_count": text.count('.') + text.count('!') + text.count('?')
_76        }
_76
_76        if self.include_word_count:
_76            results["word_count"] = len(text.split())
_76
_76        if self.perform_sentiment_analysis:
_76            # Basic sentiment analysis
_76            text_lower = text.lower()
_76            if "happy" in text_lower or "good" in text_lower:
_76                sentiment = "positive"
_76            elif "sad" in text_lower or "bad" in text_lower:
_76                sentiment = "negative"
_76            else:
_76                sentiment = "neutral"
_76
_76            results["sentiment"] = sentiment
_76
_76        # Convert the results dictionary to a formatted string
_76        formatted_results = "\n".join([f"{key}: {value}" for key, value in results.items()])
_76
_76        # Return a Message object
_76        return Message(text=formatted_results)
_76
_76# Define how to use the inputs and outputs
_76component = TextAnalyzerComponent()

在此自定义组件中：

input_text输入是一个必需的多行文本字段，接受 Message 对象或字符串。用于提供要分析的文本。
include_word_count输入是一个可选的布尔字段。当设置为 True 时，它将单词计数添加到分析结果中。
perform_sentiment_analysis输入是一个可选的布尔字段。当设置为 True 时，它触发对输入文本的基本情感分析。

组件执行基本的文本分析，包括字符计数和句子计数(基于标点符号)。如果启用了单词计数，它会拆分文本并计算单词数。如果启用了情感分析，它会执行基于关键字的简单情感分类(正面、负面或中性)。

由于组件输入和输出Message，您可以将组件连接到聊天中，看看基本自定义组件逻辑如何与您的输入交互。

创建具有多个输出的自定义组件

在 Blaflow 中，自定义组件可以有多个输出。每个输出可以与组件中的特定方法相关联，允许您为每个输出路径定义不同的行为。当您想根据某些条件路由数据或以多种方式处理数据时，此功能特别有用。

输出定义：每个输出在组件的outputs列表中定义。每个输出与一个显示名称、一个内部名称和一个被调用来生成输出的方法相关联。
输出方法：与输出相关联的方法负责为该特定输出生成

目录结构要求​

在 Blaflow 中创建自定义组件​

添加输入和修改输出方法​

输入类型​

HandleInput​

DataInput​

StrInput​

MessageInput​

MessageTextInput​

MultilineInput​

SecretStrInput​

IntInput​

FloatInput​

BoolInput​

NestedDictInput​

DictInput​

DropdownInput​

文件 Input​

通用输入​

使用通用输入创建自定义组件​

创建具有多个输出的自定义组件​