模板转换节点

【模板转换】节点用于将上游节点输出的数据，按 Jinja 模板语法渲染为字符串。
它常被用来把结构化/半结构化数据（JSON、数组、对象、变量集合）拼装成 提示词、摘要、报告、SQL 片段、Markdown 文本等，便于下游节点继续处理。

适用场景

提示词拼装：将「开始」节点表单 + 知识检索结果统一格式化为 LLM 输入。
数据格式转换：把 JSON/对象转换为 Markdown、表格文本、CSV 行、自然语言描述等。
条件化输出：基于业务条件（如置信度、命中数、用户偏好）渲染不同的文案或指令。
多段合并：把多路检索结果/多 API 响应合并成单段上下文字符串。
结构化模板：生成约束格式（如 JSON、YAML、SQL）的字符串供下游使用。

基本用法

选择输入变量在节点面板的 输入变量 中勾选需要参与渲染的上游变量（如 sys.query、retrieval.result、profile 等）。这些变量在模板中可直接引用。
编写 Jinja 模板常用语法要点：

插值：{{ variable }}
逻辑：{% if ... %}...{% elif ... %}{% else %}...{% endif %}
循环：{% for item in list %}...{% endfor %}
过滤器：{{ text | trim | lower | replace('\n', ' ') }}
空值兜底：{{ maybe | default('N/A') }}
转义控制：{{ html | safe }}（仅在可控内容场景使用）

输出模板渲染后的字符串默认写入 输出变量（如 result），可被下游节点继续引用。

语法速查

能力	示例	说明
变量插值	`Hello, {{ user.name }}`	渲染对象属性
条件	`{% if score >= 0.8 %}高置信{% else %}低置信{% endif %}`	分支输出
循环	`{% for s in segments %}- {{ s.title }}{% endfor %}`	列表遍历
过滤器	`{{ text	strip
默认值	`{{ dep	default('未填写') }}`
连接	`{{ tags	join(', ') }}`
去重	`{% for x in items	unique %}...{% endfor %}`
选择	`{% for x in items if x.score > 0.7 %}...{% endfor %}`	条件筛选
控制空白	`{%- ... -%}`	去除模板周围空白

注意

提示：在 对话流智能体 中，模板输出若较长，请注意模型上下文窗口限制。

常见输入结构示例

知识检索结果（示例）

{
  "result": [
    { "content": "年假天数按工龄计算…", "title": "休假制度", "metadata": {"effective_date": "2024-01-01", "dept": "HR"} },
    { "content": "加班工资核算口径…", "title": "加班与调休", "metadata": {"effective_date": "2023-09-01", "dept": "HR"} }
  ]
}

会话/表单数据（示例）

{
  "name": "王同学",
  "range": "2025-10-01 ~ 2025-10-26",
  "tasks": ["调研制度库", "整理模板节点文档", "编写示例"]
}

场景

模板节点允许你借助 Jinja2 这一强大的 Python 模板语言，在工作流内实现轻量、灵活的数据转换，适用于文本处理、JSON 转换等情景。

例如，可以灵活地格式化并合并来自前面步骤的变量，创建出单一的文本输出。这非常适合于将多个数据源的信息汇总成一个特定格式，以满足后续步骤的需求。

示例 1

将多个输入（文章标题、介绍、内容）拼接为完整文本。

示例 2

将知识检索节点获取的信息及其相关的元数据，整理成一个结构化的 Markdown 格式。

{% for item in chunks %}
### Chunk {{ loop.index }} 
### Similarity: {{ item.metadata.score | default('N/A') }}

#### {{ item.title }}

##### Content
{{ item.content | replace('\n', '\n\n') }}

---
{% endfor %}

示例 3

支持渲染 HTML 的表单。

<form data-format="json"> // Default to text
  <label for="username">Username:</label>
  <input type="text" name="username" />
  <label for="password">Password:</label>
  <input type="password" name="password" />
  <label for="content">Content:</label>
  <textarea name="content"></textarea>
  <label for="date">Date:</label>
  <input type="date" name="date" />
  <label for="time">Time:</label>
  <input type="time" name="time" />
  <label for="datetime">Datetime:</label>
  <input type="datetime" name="datetime" />
  <label for="select">Select:</label>
  <input type="select" name="select" data-options='["hello","world"]'/>
  <input type="checkbox" name="check" data-tip="By checking this means you agreed"/>
  <button data-size="small" data-variant="primary">Login</button>
</form>

与其它节点的协作

开始节点：接收表单/上传信息，生成标准化提示或参数块。
知识检索节点：将 result 渲染为可读上下文，或生成二次检索查询（查询改写）。
LLM 节点：把模板输出作为 系统提示 / 用户提示 / 上下文变量 输入给模型。
HTTP 请求节点：渲染请求体（JSON/XML/表单）或 URL 查询串。
条件分支节点：模板先归一化字段，再让条件判断更稳定。

最佳实践

显式兜底：对可为空的字段使用 default，避免渲染出 None/空白导致下游异常。
控长与裁剪：对长文本使用 truncate/replace('\n',' ') 控制长度与换行。
少逻辑多数据：复杂筛选尽量在上游做（如代码节点/变量赋值节点），模板专注展示。
结构化优先：下游需要机器可读时，优先输出 JSON 字符串，并在下游进行解析。
注意安全：仅对可信内容使用 | safe；外部/用户输入须做转义或限制。
统一风格：将通用片段抽象为子模板（如签名、免责声明、引用格式），方便复用。
上下文预算：输出给 LLM 的文本越长，成本与延迟越高，注意控制模板体量。

输出

默认输出变量名：result（字符串）。
可在节点设置中自定义输出变量名，供下游节点引用。

小结

模板转换节点通过 Jinja 让你以“所见即所得”的方式，把上游的结构化/半结构化数据 转换成精确可控的字符串：既能做 高质量提示词拼装，也能做 可解析的结构化输出，是 对话流智能体 / 工作流 中承上启下的“文本粘合剂”与“格式转换器”。