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.