Initial import
This commit is contained in:
182
docs/VARIABLES.md
Normal file
182
docs/VARIABLES.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# Переменные и макросы AgentUI
|
||||
|
||||
Этот файл — простая шпаргалка по переменным/макросам, которые можно использовать в шаблонах узла ProviderCall и в Prompt Blocks.
|
||||
|
||||
Правила ввода:
|
||||
- Квадратные макросы [[...]] — простая подстановка. Хорошо подходят для строк и для URL/заголовков.
|
||||
- Фигурные {{ ... }} — «джинджа‑лайт»: умеют фильтр |default(...), корректно вставляют объекты и массивы внутрь JSON без лишних кавычек.
|
||||
- Любые значения, вставляемые в JSON через макросы, приводятся к корректному JSON когда это возможно.
|
||||
|
||||
Служебные файлы/строки реализации:
|
||||
- Рендеринг и макросы: [render_template_simple()](agentui/pipeline/executor.py:125)
|
||||
- Провайдерный узел с формированием PROMPT: [ProviderCallNode.run()](agentui/pipeline/executor.py:565)
|
||||
|
||||
---
|
||||
|
||||
## Общие переменные контекста
|
||||
|
||||
- [[model]] — активная модель (строка)
|
||||
- [[vendor_format]] — openai | gemini | claude | unknown
|
||||
- [[system]] — системный текст, если был во входящем запросе
|
||||
- [[params.temperature]], [[params.max_tokens]], [[params.top_p]], [[params.stop]]
|
||||
- [[chat.last_user]] — последнее user‑сообщение
|
||||
- [[chat.messages]] — массив унифицированных сообщений
|
||||
- [[incoming.path]] — путь входящего HTTP‑запроса
|
||||
- [[incoming.query]] — строка query (?a=1&b=2)
|
||||
- [[incoming.query_params]] — объект query, например {"key":"..."}
|
||||
- [[incoming.headers]] — заголовки входящего запроса
|
||||
- [[incoming.json]] — JSON‑тело входящего запроса клиента
|
||||
- [[incoming.api_keys.authorization]] — значение Authorization (если есть)
|
||||
- [[incoming.api_keys.key]] — значение ?key=... в URL (удобно для Gemini)
|
||||
- [[incoming.api_keys.secret]] — запасной слот
|
||||
|
||||
Те же поля доступны через {{ ... }}: например {{ params.temperature|default(0.7) }}, {{ incoming.json }} и т.д.
|
||||
|
||||
---
|
||||
|
||||
## Макросы OUT (выходы нод)
|
||||
|
||||
Доступ к выходам нод возможен в двух формах:
|
||||
|
||||
### 1) Короткая форма (best‑effort текст)
|
||||
- [[OUT1]] — «текст» из ноды n1
|
||||
- [[OUT2]] — из ноды n2 и т.д.
|
||||
|
||||
Что делает «best‑effort текст»:
|
||||
- Если нода вернула response_text или text — берётся он
|
||||
- Если нода вернула объект провайдера:
|
||||
- OpenAI: choices[0].message.content
|
||||
- Gemini: candidates[0].content.parts[0].text
|
||||
- Claude: content[].text (склейка)
|
||||
- Если ничего из выше не подошло — выполняется глубокий поиск текстовых полей ("text"/"content")
|
||||
|
||||
Реализация: [_best_text_from_outputs()](agentui/pipeline/executor.py:45) и подстановка коротких OUT: [render_template_simple()](agentui/pipeline/executor.py:155)
|
||||
|
||||
### 2) Полная форма (точный путь)
|
||||
- [[OUT:n1.result]] — целиком результат ноды n1
|
||||
- [[OUT:n1.result.candidates.0.content.parts.0.text]] — конкретный путь
|
||||
- Эквивалент через фигурные скобки: {{ OUT.n1.result.candidates.0.content.parts.0.text }}
|
||||
|
||||
Совет: используйте короткий [[OUTx]] если нужно «просто текст». Используйте полную форму, если нужен конкретный фрагмент/массив.
|
||||
|
||||
---
|
||||
|
||||
## Единый фрагмент [[PROMPT]]
|
||||
|
||||
[[PROMPT]] — это уже собранный JSON‑фрагмент из ваших Prompt Blocks. Он зависит от выбранного провайдера ноды:
|
||||
- OpenAI → "messages": [...]
|
||||
- Gemini → "contents": [...], "systemInstruction": {...}
|
||||
- Claude → "system": "...", "messages": [...]
|
||||
|
||||
Как использовать внутри JSON‑шаблона:
|
||||
|
||||
{
|
||||
"model": "{{ model }}",
|
||||
[[PROMPT]],
|
||||
"temperature": {{ params.temperature|default(0.7) }}
|
||||
}
|
||||
|
||||
Вы также можете использовать сырьевые структуры:
|
||||
- {{ pm.messages }}
|
||||
- {{ pm.contents }}
|
||||
- {{ pm.systemInstruction }}
|
||||
- {{ pm.system_text }}
|
||||
|
||||
Но рекомендуемый путь — [[PROMPT]]: меньше шансов сломать JSON.
|
||||
|
||||
---
|
||||
|
||||
## Примеры по провайдерам
|
||||
|
||||
### OpenAI (/v1/chat/completions)
|
||||
|
||||
{
|
||||
"model": "{{ model }}",
|
||||
[[PROMPT]],
|
||||
"temperature": {{ incoming.json.temperature|default(params.temperature|default(0.7)) }},
|
||||
"top_p": {{ incoming.json.top_p|default(params.top_p|default(1)) }},
|
||||
"max_tokens": {{ incoming.json.max_tokens|default(params.max_tokens|default(256)) }},
|
||||
"stop": {{ incoming.json.stop|default(params.stop|default([])) }}
|
||||
}
|
||||
|
||||
### Gemini (/v1beta/models/{model}:generateContent?key=...)
|
||||
|
||||
{
|
||||
"model": "{{ model }}",
|
||||
[[PROMPT]],
|
||||
"safetySettings": {{ incoming.json.safetySettings|default([]) }},
|
||||
"generationConfig": {
|
||||
"temperature": {{ incoming.json.generationConfig.temperature|default(params.temperature|default(0.7)) }},
|
||||
"topP": {{ incoming.json.generationConfig.topP|default(params.top_p|default(1)) }},
|
||||
"maxOutputTokens": {{ incoming.json.generationConfig.maxOutputTokens|default(params.max_tokens|default(256)) }},
|
||||
"stopSequences": {{ incoming.json.generationConfig.stopSequences|default(params.stop|default([])) }}
|
||||
}
|
||||
}
|
||||
|
||||
### Claude (/v1/messages)
|
||||
|
||||
{
|
||||
"model": "{{ model }}",
|
||||
[[PROMPT]],
|
||||
"temperature": {{ incoming.json.temperature|default(params.temperature|default(0.7)) }},
|
||||
"top_p": {{ incoming.json.top_p|default(params.top_p|default(1)) }},
|
||||
"max_tokens": {{ incoming.json.max_tokens|default(params.max_tokens|default(256)) }}
|
||||
}
|
||||
|
||||
---
|
||||
|
||||
## Частые кейсы
|
||||
|
||||
1) Взять текст пользователя из входящего запроса и передать в Prompt Blocks
|
||||
- Gemini: [[VAR:incoming.json.contents.0.parts.0.text]]
|
||||
- OpenAI: [[VAR:incoming.json.messages.0.content]]
|
||||
- Claude: [[VAR:incoming.json.messages.0.content.0.text]]
|
||||
|
||||
2) Переписать ответ предыдущей ноды «как текст»
|
||||
- [[OUT1]] — если предыдущая нода имеет id n1
|
||||
|
||||
3) Добавить ключ Gemini из query в endpoint
|
||||
- /v1beta/models/{{ model }}:generateContent?key=[[VAR:incoming.api_keys.key]]
|
||||
|
||||
---
|
||||
|
||||
## Почему местами нужны {{ ... }}
|
||||
|
||||
Внутри JSON нам важно вставлять объекты/массивы без кавычек и иметь дефолты:
|
||||
- {{ pm.contents }} — вставит массив как массив
|
||||
- {{ params.temperature|default(0.7) }} — если нет значения, подставится 0.7
|
||||
|
||||
Квадратные [[...]] хорошо подходят для строк/простых значений и для URL/заголовков.
|
||||
|
||||
---
|
||||
|
||||
## Отладка
|
||||
|
||||
- Проверьте лог DEBUG в консоли: ProviderCallNode показывает провайдера, URL и первые 400 символов тела запроса.
|
||||
- Если «ничего не подставилось»:
|
||||
- убедитесь, что не подаёте входной payload в ProviderCall (иначе шаблон игнорируется);
|
||||
- проверьте валидность JSON после подстановок;
|
||||
- проверьте, что макрос написан корректно (OUT против OUTn).
|
||||
|
||||
---
|
||||
|
||||
## Мини‑FAQ
|
||||
|
||||
В: Почему [[OUT1]] пустой?
|
||||
О: Возможно, нода n1 не вернула текстового поля, и глубокий поиск не нашёл текста. Уточните путь через полную форму [[OUT:n1....]].
|
||||
|
||||
В: Можно ли получить весь «сырой» ответ?
|
||||
О: [[OUT:n1.result]] — вернёт весь JSON результата ноды n1.
|
||||
|
||||
В: Почему фигурные скобки иногда обязательны?
|
||||
О: Они умеют |default(...) и корректно вставляют объекты/массивы внутрь JSON.
|
||||
|
||||
---
|
||||
|
||||
## Ссылки на реализацию
|
||||
|
||||
- Макросы/рендер: [render_template_simple()](agentui/pipeline/executor.py:125)
|
||||
- Единый [[PROMPT]]: [ProviderCallNode.run()](agentui/pipeline/executor.py:604)
|
||||
- Короткий [[OUTx]] и извлечение текста: [render_template_simple()](agentui/pipeline/executor.py:155), [_best_text_from_outputs()](agentui/pipeline/executor.py:45)
|
||||
|
||||
Удачного редактирования!
|
||||
Reference in New Issue
Block a user