Jinja Шаблоны

Эта страница описывает шаблонизатор из app/utils/template_helper.py и как использовать его в компонентах flow.

Где используется

Jinja-шаблоны применяются в параметрах компонентов, где есть поля вида:

  • content_template
  • context_template
  • messages_template
  • template
  • custom_key_template

Чаще всего это text_template, llm, end, run_flow, webhook/throttling.

Базовые переменные в шаблоне

В шаблоне доступны:

  • content - входной текст текущего шага.
  • context - словарь контекста выполнения.
  • variables - tenant/execution переменные (через VariablesProxy).
  • datetime - текущая дата/время строкой (YYYY-MM-DD HH:MM:SS).
  • timestamp - текущий unix timestamp.

Примеры:

{{ content }}
{{ context.get('Request-1', {}).get('status_code', 0) }}
{{ variables.CRM_API_KEY }}

Доступные функции

TemplateHelper добавляет безопасный набор функций:

  • Преобразования: str, int, float, bool, list, dict, set
  • Последовательности: len, min, max, sum, sorted, enumerate, zip
  • Логика: any, all
  • Математика: round, abs
  • Типы: isinstance, type
  • Регулярки: match, search, findall, sub, split (и модуль re)
  • Random: choice, randint, random, uniform, shuffle (и модуль random)
  • Дополнительно: extract_content_from_tag(text, tag)

Пример:

{{ search('order:\\s*(\\d+)', content).group(1) if search('order:\\s*(\\d+)', content) else '' }}

Фильтры

Кроме стандартных Jinja-фильтров, добавлены:

  • tojson / to_json
  • from_json
  • escapejs
  • jsonstr
  • tocsv
  • json_query (JMESPath)
  • dict_to_json
  • urlencode
  • urldecode
  • split

Примеры:

{{ context | tojson }}
{{ context.get('payload', '{}') | from_json | json_query('user.id') }}
{{ 'a,b,c' | split(',') }}

Важный паттерн доступа к контексту

Используйте безопасный доступ через .get(), особенно если в node_id есть дефис:

{{ context.get('Request-1', {}).get('status_code', 0) == 200 }}

Не рекомендуется:

{{ context['Request-1']['status_code'] }}

JSON-шаблоны

Для JSON-полей (messages_template, context_template) используйте tojson, чтобы избежать проблем с экранированием:

{
  "messages": [
    { "role": "system", "content": {{ system_prompt | tojson }} },
    { "role": "user", "content": {{ content | tojson }} }
  ]
}

Внутри TemplateHelper.render_jsonsafe() автоматически подставляются tojson/jsonstr для переменных, если шаблон должен вернуть корректный JSON.

Примеры для flow-компонентов

1) text_template

Здравствуйте! Ваш запрос: {{ content }}

2) end.context_template

{{ {"answer": content, "source": context.get("source", "unknown")} | tojson }}

3) run_flow.context_template

{{ {
  "customer_id": context.get("customer_id"),
  "order_id": context.get("order_id"),
  "variables": {
    "segment": variables.get("SEGMENT", "default")
  }
} | tojson }}

Отладка шаблонов

Для быстрой проверки можно использовать API:

  • POST /template/render

Передайте шаблон и входные данные, чтобы увидеть итоговый рендер до запуска полного flow.