Dinja 是一個 Flutter/Dart 套件,實作 Jinja 模板引擎,適用於 Hugging Face 與 GGUF 大型語言模型(LLM)對話範本,支援訊息、工具與產生提示。確保與 llama.cpp 及 Jinja2 的一致性,實現跨平台一致的範本呈現。專為跨平台使用設計,可於 Android、iOS、Linux、macOS、Web 與 Windows 上順暢運行,包含 WebAssembly。適合開發需要精確提示格式化的 AI 應用程式。
適用情境
LLM 聊天介面開發
AI 助手提示範本
跨平台大語言模型整合
Web 與行動 AI 應用
LLM 工作流程中的工具呼叫
主要特色
Jinja2 兼容性
與 llama.cpp 的相容性
支援 GGUF 與 Hugging Face 模型
Web 與 Wasm 支援
平台無關的渲染
適合對象
Flutter 開發人員建構 AI 應用
需要一致提示處理的團隊
使用 LLM 工具呼叫的應用程式
基於網路的AI助理
多平台AI客戶端
使用建議
需要熟悉 Jinja 語法
最適合用於大語言模型專用的樣板化
僅限提示產生使用情境
不是通用的範本引擎
依賴於底層的大語言模型框架
原始 README
以下為關聯原始碼儲存庫的 README 原文快照,最新內容請造訪原始碼儲存庫。
dinja
dinja renders LLM chat templates in Dart: give it a model's Jinja chat template and a conversation, and it returns the prompt string. It is a port of llama.cpp's common/jinja engine.
Output, identical to what llama.cpp and Python Jinja2 render:
<|im_start|>system
You are a helpful assistant.
# Tools
<tools>
{"type": "function", "function": {"name": "get_weather", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}}}
</tools><|im_end|>
<|im_start|>user
What is the weather in Paris?<|im_end|>
<|im_start|>assistant
Real templates come from the chat_template field of a model's tokenizer_config.json on huggingface.co, or from the tokenizer.chat_template key in GGUF metadata. Pass that string to Template unchanged.
Why dinja
llama.cpp parity. dinja follows common/jinja, the engine llama-server renders chat templates with. llama.cpp's Jinja test suite, 290 cases whose expected output also matches Python Jinja2 3.1.6, is ported case for case: dinja matches all 279 cases that llama.cpp runs byte for byte. The other 11 are cases llama.cpp skips as not implemented.
Real templates. The tests parse and render 45 distinct chat templates from real models, including Llama 3.x, Qwen2.5, Qwen3, Mistral, Gemma, DeepSeek R1, Phi, gpt-oss, Kimi K2 and GLM. With these and the templates in llama.cpp's models/templates, 86 distinct in all, dinja gives the same output as llama.cpp 7fe450e1 byte for byte, or raises the same template error, in four conversations: system prompt with tools, user only, multi-turn, and a tool call with its result.
Input marking. Values wrapped in JinjaString.user are escaped on output, and renderJinjaResult reports which parts of the output came from input.
Web and Wasm. Pure Dart, depending only on meta. The parser, runtime and llama.cpp tests also pass in Chrome, compiled to JavaScript and to Wasm.
Used by llamadart, a llama.cpp runtime for Dart and Flutter, to render chat templates.
Input marking
Wrap untrusted values in JinjaString.user. They are escaped when rendered; a plain String is treated as template text and is not.
Input text keeps its marking through filters, ~, loops, macros and {% set %} and {% filter %} blocks, and is escaped once, when the template outputs it. So a filter sees it as it was passed in: {% filter length %}{{ name }}{% endfilter %} counts the characters of name, not of its escaped form. tojson and join escape only the input text in their output, not the JSON's quotes or the template's separator. | safe and markSafe() turn escaping off for a value passed to render, or returned by a function passed to it. The output of a block set, macro, caller() or {% filter %} block is final, as in Jinja2 with autoescape, so | safe on it escapes the input in it.
A function passed to render is trusted: | safe on a string it builds outputs it unescaped, even when it built it from captured output. With x = JinjaString.user('<b>') and up returning its argument upper-cased, {% set c %}<i>{{ x }}{% endset %}{{ up(c)|safe }} gives <I><B>.
import'package:dinja/dinja.dart';
voidmain() {
final template = Template('Hello {{ name }}');
const html = '<script>alert(1)</script>';
print(template.render({'name': JinjaString.user(html)}));
print(template.render({'name': html}));
final result = template.renderJinjaResult({'name': JinjaString.user('Bob')});
print(result.parts.where((part) => part.isInput).map((part) => part.val));
}
package:dinja/ast.dart parses a template into an AST without rendering it, for tools that inspect templates, for example to detect which features a chat template uses.
import'package:dinja/ast.dart';
voidmain() {
final program = parseTemplate(
'{% if tools %}{{ tools | length }}{% endif %}',
);
for (final statement in program.body) {
print(statement.type);
}
}
If
dinja and package:jinja
jinja ports Jinja as a general-purpose, server-side template engine with template inheritance. dinja targets LLM chat templates: it tracks llama.cpp's engine and output, adds input marking, and leaves out inheritance and template loading.
Scope
dinja implements the Jinja that chat templates use, not all of Jinja2:
A template is a single string: extends, block, include, import, raw and with throw a ParserException.
Plain strings are never escaped; only JinjaString.user values are.
Some Jinja2 features llama.cpp lacks are missing here too; for example, '%s'|format(x) returns %s.
String literals support \xHH with exactly two hexadecimal digits, as in {{ '\x41\xE9' }} rendering Aé. Values above 0x7f are Unicode characters, as in llama.cpp; \\x41 keeps the literal text \x41.
strftime_now formats the system clock's current time in the local time zone, as C strftime does in llama.cpp. %Z is Dart's DateTime.timeZoneName, whose format depends on the platform: on the web it is the browser's name for the zone, such as Eastern Daylight Time where llama.cpp gives EDT.
To supply a deterministic clock for one render, pass
{'strftime_now': strftimeNow(DateTime.utc(2026, 1, 2))} to render.
The callable keeps the built-in argument/output checks and input escaping;
other renders retain their own clock.