Skip to main content

变量

变量是SenseFlow的"信息桥梁"，用于串联工作流中各节点的输入与输出，实现动态数据的流转和复杂逻辑的处理。通过变量，用户可以轻松在流程中实现数据共享和逻辑控制，打造更加智能和高效的应用。

变量分类​

具体的变量类型可以分为如下三类：

系统变量​

  • 定义：应用内部预设的系统级参数，可以被各节点全局读取
  • 特点：系统级变量均以sys开头，无需手动配置，开箱即用
  • 用途：适用于需要快速获取全局信息的场景，如记录时间戳或跟踪会话状态
  • 常见内容：当前时间、设备信息、用户会话ID等

环境变量​

  • 定义：用户自定义的全局变量，用于设置应用的固定参数
  • 特点：值可长期保存，适用于跨流程或多节点共享的数据
  • 用途：例如一些需要反复调用的配置项
  • 常见内容：API 密钥、默认语言设置、数据库连接参数等

会话变量​

  • 定义：特定用户或会话中的动态数据容器，随交互过程实时更新
  • 特点：仅在当前会话有效，仅在Chatflow中使用
  • 用途：适用于需要个性化响应或实时动态处理的场景
  • 常见内容：用户输入内容、模型生成的中间结果、实时计算的参数等

系统变量​

系统变量是在工作流内预设的系统级参数，可以被工作流内的其他节点全局读取，系统级变量均以sys开头。

Workflow类型​

Workflow类型应用具有如下系统变量：

变量名类型描述示例值
sys.querystring用户输入的查询内容"今天天气怎么样？"
sys.filesarray[file]用户上传的文件列表[file1.pdf, image.jpg]
sys.user_idstring用户唯一标识符"user_12345"
sys.app_idstring应用唯一标识符"app_67890"
sys.workflow_idstring工作流唯一标识符"workflow_abc123"
sys.workflow_run_idstring工作流运行实例ID"run_def456"

Chatflow类型​

Chatflow类型应用具有如下系统变量：

变量名类型描述示例值
sys.querystring用户当前输入的查询内容"请帮我分析这份报告"
sys.filesarray[file]用户上传的文件列表[report.docx, data.xlsx]
sys.conversation_idstring对话会话唯一标识符"conv_xyz789"
sys.user_idstring用户唯一标识符"user_12345"
sys.app_idstring应用唯一标识符"app_67890"
sys.workflow_idstring工作流唯一标识符"workflow_abc123"
sys.workflow_run_idstring工作流运行实例ID"run_def456"
sys.dialogue_countnumber当前对话轮次计数5

环境变量​

环境变量专门用于保护工作流中的敏感信息，例如 API 密钥、数据库密码等。它们被存储在工作流配置中，而非直接写入代码，从而确保数据安全，并便于在工作流中共享和复用。

环境变量配置界面示意图

支持的数据类型​

环境变量支持以下三种数据类型：

  • String 字符串：存储文本信息
  • Number 数字：存储数值信息
  • Secret 密钥：存储敏感信息，如API密钥、密码等

使用注意事项​

  • 环境变量可在大部分节点内全局引用
  • 环境变量命名不可重复
  • 环境变量为只读变量，不可写入
  • Secret类型的变量在界面上会被隐藏显示

环境变量配置示例​

# 环境变量配置示例
API_BASE_URL: "https://api.example.com"  # String类型
MAX_RETRY_COUNT: 3                       # Number类型
API_SECRET_KEY: "sk-xxxxxxxxxx"          # Secret类型

会话变量​

会话变量专为多轮对话场景设计，适用于需要多次交互、信息上下文保持的情况。而 Workflow 类型的应用通常是线性、独立的单次任务流程，不涉及多轮交互。因此，会话变量仅在 Chatflow 类型（如聊天助手 → 工作流编排）应用中使用。

功能特点​

会话变量让应用开发者能够在同一个 Chatflow 会话中存储特定信息，并确保在整个工作流的多轮对话中都能使用这些信息，比如上下文、或用户在对话中的偏好设置等。它就像为大型语言模型（LLM）提供一个"备忘录"，确保信息不会因为记忆错误而失真。

使用示例​

例如，你可以在对话的第一轮中将用户选择的语言偏好存储到会话变量中，之后，LLM 在回答问题时会参考这些信息，并在接下来的对话中继续使用用户指定的语言回复。

会话变量使用流程示意图

支持的数据类型​

会话变量支持以下六种数据类型：

  • String 字符串：存储文本信息
  • Number 数值：存储数字信息
  • Object 对象：存储复杂的数据结构
  • Array[string] 字符串数组：存储字符串列表
  • Array[number] 数值数组：存储数字列表
  • Array[object] 对象数组：存储对象列表

使用注意事项​

  • 会话变量可在大部分节点内全局引用
  • 会话变量的写入需要使用变量赋值节点
  • 会话变量为可读写变量
  • 会话变量仅在当前会话生命周期内有效

变量使用最佳实践​

变量命名规范​

  1. 使用描述性名称：变量名应清楚表达其用途

    好的例子：user_preference, api_response_data
    不好的例子：temp, data, x

  2. 采用一致的命名风格：建议使用下划线分隔的小写字母

    推荐：user_login_status, order_total_amount
    不推荐：userLoginStatus, OrderTotalAmount

  3. 避免系统保留字：不要使用以sys开头的变量名

变量作用域管理​

  1. 系统变量：用于获取系统级信息，只读使用
  2. 环境变量：用于存储配置信息和敏感数据
  3. 会话变量：用于维护对话状态和用户个性化信息

数据类型选择指南​

  1. String类型：适用于文本、标识符、状态值
  2. Number类型：适用于计数、金额、评分等数值
  3. Object类型：适用于复杂的结构化数据
  4. Array类型：适用于列表、集合类数据
  5. Secret类型：仅用于敏感信息，如密钥、密码

变量生命周期管理​

系统变量​

  • 生命周期：与应用实例绑定
  • 访问权限：全局只读
  • 使用场景：获取系统状态和请求信息

环境变量​

  • 生命周期：与应用配置绑定
  • 访问权限：全局只读
  • 使用场景：配置参数和敏感信息存储

会话变量​

  • 生命周期：与用户会话绑定
  • 访问权限：会话内读写
  • 使用场景：用户状态维护和个性化数据

变量安全注意事项​

敏感信息处理​

  1. 使用Secret类型：对于API密钥、数据库密码等敏感信息，必须使用Secret类型的环境变量
  2. 避免日志泄露：确保敏感变量不会在日志中明文输出
  3. 权限控制：限制对敏感变量的访问权限

数据验证​

  1. 输入验证：对用户输入的变量值进行格式和范围验证
  2. 类型检查：确保变量值符合预期的数据类型
  3. 边界检查：验证数值变量是否在合理范围内

错误处理​

  1. 默认值设置：为重要变量设置合理的默认值
  2. 异常捕获：处理变量访问可能出现的异常情况
  3. 回退机制：在变量不可用时提供备选方案

变量调试技巧​

调试工具使用​

  1. 变量监控：实时查看变量值的变化
  2. 日志输出：在关键节点输出变量状态
  3. 断点调试：在特定节点暂停执行检查变量

常见问题排查​

  1. 变量未定义：检查变量名拼写和作用域
  2. 类型不匹配：确认变量类型与使用场景匹配
  3. 权限问题：验证变量的读写权限设置

性能优化​

  1. 减少变量数量：只保留必要的变量
  2. 优化数据结构：使用合适的数据类型和结构
  3. 及时清理：释放不再需要的会话变量

通过合理使用变量功能，您可以构建出更加灵活、智能和高效的应用，实现复杂的业务逻辑和用户交互体验。

下一步：了解知识库功能