跳到主要内容

SkillFlaw 数据类型

SkillFlaw 组件会接收并产出特定类型的输入与输出。 理解这些数据类型，有助于你正确连接组件、预判运行结果，并在调试时快速定位“为什么这个端口接不上”或“为什么输出格式不对”。

组件端口体现了组件能够发送与接收的数据类型。 一些字段本身也直接暗示了类型，例如 System Message 字段就接收 Message 数据。 端口颜色同样表示端口的数据类型。 例如， Data 端口表示结构化对象数据。

构建流程时，应尽量把同类型（同颜色）的输出端口连接到对应输入端口。

提示
  • 在工作区中，把鼠标悬停到端口上可以查看该端口的连接说明。
  • 点击端口后，可以使用 Search 搜索兼容组件。
  • 如果两个组件的数据类型不兼容，可以使用例如 Type Convert 这样的处理组件做类型转换。

Data​

Data 端口接收或产出 Data 类型。 它表示一种结构化对象，类似你会发给 API 的 JSON 负载，适合在组件之间传递用户资料、配置项、抽取结果等键值数据。

Data 对象包含一个主文本字段（由 text_key 指定）以及其他元数据。

结构与属性​

Data 类型定义了组件之间传递结构化键值对象时使用的 schema。

常见属性包括：

  • data：真正承载键值对的对象主体
  • text_key：data 中被视为主文本的字段名
  • default_value：当 text_key 缺失时使用的回退值；默认 text_key 是 "text"

_10
data_obj = Data(
_10
text_key="text",
_10
data={
_10
"text": "Hello world",
_10
"name": "Charlie",
_10
"age": 28
_10
},
_10
default_value=""
_10
)

序列化为 JSON 后，大致如下：


_10
{
_10
"text_key": "text",
_10
"data": {
_10
"text": "Hello world",
_10
"name": "Charlie",
_10
"age": 28
_10
},
_10
"default_value": ""
_10
}

DataFrame​

DataFrame 端口接收或产出 pandas DataFrame。 它适合处理多行、多记录的表格型数据，类似 CSV 或结果集。

结构与属性​

DataFrame 类型定义了组件之间传递多行表格记录时使用的 schema。

它具备以下特点：

  • 完整 pandas 兼容性：可以使用 pandas 的 DataFrame 能力
  • SkillFlaw 集成：支持从 Data 列表、字典或已有 DataFrame 构建
  • 常用便捷方法：
    • to_data_list()
    • add_row()
    • add_rows()
    • to_lc_documents()
    • to_data()
    • to_message()
  • 文本字段兼容：保留 text_key 与 default_value，方便与 Data 类型互转

DataFrame 示例​


_12
[
_12
{
_12
"name": "Charlie Lastname",
_12
"age": 28,
_12
"email": "charlie.lastname@example.com"
_12
},
_12
{
_12
"name": "Alexandra Example",
_12
"age": 34,
_12
"email": "alexandra@example.com"
_12
}
_12
]

表格化后可理解为：


_10
| name | age | email |
_10
|------|-----|-------|
_10
| Charlie Lastname | 28 | charlie.lastname@example.com |
_10
| Alexandra Example | 34 | alexandra@example.com |

Embeddings​

Embeddings 端口用于接收或输出向量嵌入，常见于相似度搜索、向量检索与知识库场景。

例如，嵌入模型组件会输出 Embeddings，再连接到向量存储组件的嵌入输入端口。

更多底层说明可参阅 LangChain Embedding 模型文档。

LanguageModel​

LanguageModel 是由语言模型组件产出的特定数据类型，供依赖 LLM 的其他组件使用。

当某个模型组件把输出类型从 Model Response 改为 Language Model 后，它的输出端口会从 Message 端口变成 Language Model 端口。 随后，你可以把它连接到兼容组件的 Language Model 输入端口，例如 Smart Transform。

关于如何在流程中使用这类输出，请参阅模型组件。

LanguageModel 本质上是什么？

由于 SkillFlaw 构建在 LangChain 之上，LanguageModel 本质上通常是一个 LangChain ChatModel 实例，并带有来源组件中配置好的参数。

例如，它可能是某个具体服务商对应的聊天模型实例，如 ChatOpenAI 或 ChatAnthropic。

如果你需要确认组件实际产出了什么模型对象，可以查看对应组件代码。

Memory​

Memory 端口通常用于把 Message History 组件与外部聊天记忆存储连接起来。

更多说明请参阅Message History 组件。

Message​

Message 端口接收或产出 Message 数据。 它在 Data 的基础上补充了聊天场景常见的字段与方法，因此是聊天型流程中最常见的数据类型之一。

提示

接收或输出 Message 的组件，不一定会使用 Message 对象的全部属性。 只要与 Message schema 兼容，它就可以是有效输入或输出。

实际搭流程时，优先关注组件面板上真正暴露出来的字段；只有在调试流程或调试组件输出不符合预期时，才需要深究完整的 Message 结构。

结构与属性​

Message 类型定义了聊天场景下使用的消息 schema，包含文本、发送方、附件与内容块等字段。

一个 Message JSON 例子如下：


_10
{
_10
"text": "Name: Charlie Lastname, Age: 28, Email: charlie.lastname@example.com",
_10
"sender": "User",
_10
"sender_name": "Charlie Lastname",
_10
"session_id": "some-session-id",
_10
"timestamp": "2024-06-01T12:00:00Z",
_10
"files": [],
_10
"content_blocks": [],
_10
"category": "message"
_10
}

常见属性包括：

  • text：主消息内容
  • sender：消息发送方，通常是 User 或 Language Model
  • sender_name：显示名称
  • session_id：聊天会话标识
  • flow_id：消息所属流程 ID
  • timestamp：UTC 时间戳
  • files：附带文件或图片列表
  • content_blocks：富文本 / 多模态内容块，也可能包含错误信息
  • category：例如 message、error、warning、info

在输入 / 输出组件中的 Message​

在使用 Chat Input and Output 组件 的流程中，Message 提供了稳定的一致结构，适合聊天机器人、对话分析与 agent 场景。

在 Playground 中，默认只会展示与对话相关的 Message 字段，例如 text、files 和错误信息。 如果要查看完整属性，可在 Playground 中查看消息日志。

在仅使用 Text Input and Output 组件 的流程中，Message 更多被当作普通文本传递，而不是持续对话的一部分。 因此，这类流程通常不适合直接作为 Playground 聊天流程使用。

通过 SkillFlaw API 调用流程时，响应中通常也会包含 Message 对象。 实际接入你的应用时，通常需要自行提取你真正关心的字段。

Tool​

Tool 端口用于把工具连接到 Agent 组件。

这些工具可以是：

  • 开启了 Tool Mode 的其他组件
  • 专门的 MCP Tools 组件
  • 只支持 Tool Mode 的特定组件

多个工具可以连接到同一个 Agent 组件的同一工具输入端口。

从底层语义看，Tool 数据通常对应 LangChain 的 StructuredTool 对象。

更多说明请参阅为智能体配置工具与将 SkillFlaw 用作 MCP 客户端。

未知或多种类型​

如果某个端口可以接收或输出多种数据类型，界面会使用灰色端口图标 表示。

把鼠标悬停到端口上，可以查看该端口支持的具体类型。

在流程中查看数据类型​

在 SkillFlaw 中，你可以使用 Inspect output 查看单个组件的输出。 这对于学习数据结构、排查输入格式错误或输出结构不符合预期非常有帮助。

以下示例展示如何查看 Type Convert 组件 的输出：

  1. 创建一个流程，把 Chat Input 连接到 Type Convert。
  2. 在 Chat Input 中输入一些文本。
  3. 在 Type Convert 上点击 Run component，然后点击 Inspect output。

默认输出是 Message 数据，也就是从 Chat Input 传过来的消息结构。 如果你把 Type Convert 的 Output Type 切换成 Data 或 DataFrame，再重新运行，就能看到不同类型下的结果。


_10
Input text

另请参阅​