Kiln Input Transform 架构解析：用 Jinja2 模板引擎在运行期变换任务输入

人工智能AI 应用AI 评测RAG微调提示工程开发工具桌面应用【免费下载链接】KilnBuild, Evaluate, and Optimize AI Systems. Includes evals, RAG, agents, fine-tuning, synthetic data generation, dataset management, MCP, and more.项目地址https://gitcode.com/gh_mirrors/ki/Kiln点击查看免费下载本文以 Kiln 仓库中 Input Transform 架构文档 为核心结合 功能规格书、实施计划 以及libs/core/kiln_ai下的实际实现与测试完整讲解这一通用基础设施功能的模块划分、数据模型、Jinja2 引擎设计、适配器集成点、错误处理与测试策略。读完本文你将掌握input_transform字段如何从 RunConfig 一路流到模型调用链路理解StrictUndefined与Undefined双环境设计、命名空间构造规则、TaskRun.input与 trace 的持久化约定并能独立为任意任务纯文本 / 对象 schema / 数组 schema配置与排查输入变换。1. 功能定位一次通用能力而非评估专属input_transform是挂在KilnAgentRunConfigProperties上的一个可选字段类型为InputTransform | None默认None。当它被设置时会在任务调用时运行所配置的变换把渲染结果作为发送给模型的第一个用户消息first user message。V1 只提供一种变换变体——JinjaInputTransform即用 Jinja2 模板对任务输入做投影渲染功能规格书 §1。值得强调的是它的边界只产出第一个用户消息不修改系统提示词系统提示词来自prompt_id也不影响多轮流程中的后续用户轮次如工具调用跟进、COT 草稿轮。通用 Kiln 能力纯文本任务、对象 schema 任务、数组 schema 任务都可以使用eval v2 是第一个下游消费者但本项目本身不写任何 eval 侧代码。不是新输入模式任务的输入契约不变纯文本或匹配 schema 的 JSON在任务创建时锁定模板只是对结构化输入做投影不是第三种输入类型项目概述 中引用的 Steve 提案原话。对应的数据模型约束也很清晰字段放在KilnAgentRunConfigProperties上不放在TaskRunConfig持久化包装类、不放在Task同一个任务可以有多个携带不同变换的 RunConfig、不放在McpRunConfigPropertiesMCP 工具接收原始输入。2. 模块布局datamodel 与 utils 的职责切分整个功能只新增两个模块测试文件与源码并置架构文档 §1路径职责libs/core/kiln_ai/datamodel/input_transform.pyPydantic 类型JinjaInputTransform、InputTransform判别联合、_get_input_transform_type判别函数libs/core/kiln_ai/utils/jinja_engine.py两个SandboxedEnvironment实例与全部公开引擎函数测试文件libs/core/kiln_ai/utils/test_jinja_engine.py —— 引擎单元测试libs/core/kiln_ai/datamodel/test_input_transform.py —— 数据模型测试libs/core/kiln_ai/datamodel/test_run_config.py —— 扩展input_transform字段的默认值 / 往返 / 判别分发 / 向后兼容测试libs/core/kiln_ai/adapters/model_adapters/test_base_adapter.py —— 适配器集成测试同步 流式两条路径见TestInputTransformIntegration为什么这样拆分遵循仓库既有先例。prompt_id.py/tool_id.py放在datamodel/因为它们是被数据模型类使用的字段类型而 Jinja2 引擎是纯逻辑、不承担任何数据模型角色因此放在utils/与formatting.py、config.py、open_ai_types.py等并列。3. 数据模型判别联合与保存期校验3.1JinjaInputTransform与InputTransform联合libs/core/kiln_ai/datamodel/input_transform.py 的实际实现from typing import Annotated, Any, Literal, Union from pydantic import BaseModel, Discriminator, Field, Tag, field_validator class JinjaInputTransform(BaseModel): Render the task input via a Jinja2 template, producing the first user message sent to the model. See specs/projects/templates/functional_spec.md for the full contract. type: Literal[jinja] jinja template: str Field( descriptionJinja2 template source. Validated at save time., ) field_validator(template) classmethod def validate_template_compiles(cls, v: str) - str: from kiln_ai.utils.jinja_engine import compile_template_or_raise compile_template_or_raise(v) return v def _get_input_transform_type(data: Any) - str | None: if isinstance(data, dict): return data.get(type) return getattr(data, type, None) InputTransform Annotated[ Union[Annotated[JinjaInputTransform, Tag(jinja)],], Discriminator(_get_input_transform_type), ]三个关键设计点架构文档 §2.1 的 Notes与实现一致懒导入打破循环依赖validate_template_compiles在函数体内from kiln_ai.utils.jinja_engine import compile_template_or_raise。因为jinja_engine在类型层面需要引用InputTransformrender_input_transform的形参注解而input_transform需要compile_template_or_raise模块顶层互相导入会形成环函数级懒导入是标准解法。jinja_engine.py侧同样只在TYPE_CHECKING下导入InputTransformjinja_engine.py 第 27-28 行。判别联合只有 V1 一个成员新增第二种变换变体例如未来的 JSON 输出变体只需扩展Union加一个BaseModel类几乎是一行代码的改动。判别函数与_get_run_config_type模式保持一致type缺失时既不是 dict 也没有type属性返回None——注意实际实现返回None而非架构草稿中的字符串jinja缺失 type 会被 Pydantic 判定为无法分发并报ValidationError这一点由 test_input_transform.py 的test_dispatch_missing_type_raises_validation_error钉死。3.2 字段落点KilnAgentRunConfigPropertieslibs/core/kiln_ai/datamodel/run_config.py 第 82-89 行 中input_transform作为tools_config的平级字段加入input_transform: InputTransform | None Field( defaultNone, description( Optional transform applied to the task input at run time, producing the first user message sent to the model. Default None preserves the identity path. ), )run_config.py其余部分判别器、validators、类型收窄辅助函数as_kiln_agent_run_config/as_mcp_run_config完全不受影响。3.3 字段级向后兼容已有的、磁盘上不含input_transform键的 RunConfig 会以input_transformNone正常解析——这是 Pydantic 字段默认值的自动行为无需任何迁移代码也没有upgrade_old_entries风格的回填钩子。TaskRunConfig上的model_validator(modebefore) upgrade_old_entrieslibs/core/kiln_ai/datamodel/task.py 第 102-109 行只回填structured_output_mode不触碰input_transform因此互不影响。回归测试由 test_run_config.py 的TestInputTransformField覆盖默认None、接受模型实例、接受 dict 判别分发、无键旧 JSON 加载为None、McpRunConfigProperties没有该字段负向测试。4. 引擎模块两个沙箱环境四条公开 API4.1 双SandboxedEnvironment实例libs/core/kiln_ai/utils/jinja_engine.py 第 98-112 行_template_env SandboxedEnvironment( undefinedStrictUndefined, trim_blocksTrue, lstrip_blocksTrue, ) _template_env.filters[fromjson] _fromjson _template_env.filters[format_trace] _format_trace _expression_env SandboxedEnvironment( undefinedUndefined, trim_blocksTrue, lstrip_blocksTrue, ) _expression_env.filters[fromjson] _fromjson _expression_env.filters[format_trace] _format_traceundefined是环境级设置因此必须两个实例架构文档 §3.2环境undefined服务对象缺失变量时的行为模板环境_template_envStrictUndefinedrender_input_transform、compile_template_or_raise抛UndefinedError硬失败表达式环境_expression_env默认Undefinedextract、compile_expression_or_raise返回Undefinedfalsy且与None可区分两者共享trim_blocksTrue去掉块标签后的换行让 prompt 输出更干净与lstrip_blocksTrue去掉块标签前的空白并且使用同一个SandboxedEnvironment类——即共享同一套安全边界、语法面和过滤器集。无FileSystemLoader或任何 I/O loader模板只从内联字符串渲染。为什么模板要StrictUndefined模板引用了缺失变量意味着作者拼错了字段名必须立刻可见为什么表达式要默认Undefined调用方需要能区分键缺失Undefined与显式 nullNone而不用靠 try/except。eval v2 消费方的required_var预检查正是靠这个信号做 skip-with-reason。4.2 四条公开 API四个公开函数全部从 libs/core/kiln_ai/utils/jinja_engine.py 导出def compile_template_or_raise(template: str) - None: ... def compile_expression_or_raise(expression: str) - None: ... def render_input_transform(transform: InputTransform, task_input: Any) - str: ... def extract(expression: str, data: dict) - Any: ...compile_template_or_raise/compile_expression_or_raise校验语法捕获TemplateSyntaxError后重抛为带行号的ValueErrorInvalid Jinja2 template: {e.message} (line {e.lineno})。render_input_transform按JinjaInputTransform分发调用私有的_build_namespace后渲染返回字符串。extract对 dict 求值一个 Jinja2 表达式返回 Python 值缺失键返回Undefined显式 null 返回None生成器自动物化为列表。编译成本取舍架构文档 §3.4两个compile_*_or_raise返回None而不返回编译对象因此render_input_transform与extract每次调用都会重新编译模板/表达式。Jinja2 对 prompt 量级的模板编译只需微秒级V1 可以接受未来若剖析显示需要可在引擎模块内加一个以源码字符串为键的模块级 LRU 缓存且不改变公开 API。4.3 命名空间构造统一暴露单一变量input_build_namespacejinja_engine.py 第 199-212 行把功能规格书 §5 的输入处理规则实现为模板永远只看到一个名为input的变量任务输入预处理input的值对象 schemadict无dict 本身{{ input.field_name }}、{{ input.items() }}数组 schemalist无list 本身{{ input[0] }}、{{ input \| length }}纯文本str先尝试json.loads()成功则用解析值失败则退回原始字符串解析后的 dict / list / 标量或原始字符串def _build_namespace(task_input: Any) - dict: if isinstance(task_input, str): try: parsed json.loads(task_input) except (ValueError, TypeError): parsed task_input return {input: parsed} return {input: task_input}这条统一变量 纯文本自动解析规则的收益模板在不同输入形态的任务间可原样移植无顶层解包、无别名、无命名冲突规则用户提供 JSON 形状的纯文本即可直接获得结构化模板能力而非常规纯文本仍可通过{{ input }}使用。42解析为 int 42、true解析为 bool True 这类魔法是被接受的因为 Jinja2 在模板中能很好处理这些类型功能规格书 §5 的 rationale。为什么_build_namespace是私有的架构文档 §3.3eval v2 会自己构造四字段合成 dictfinal_message、trace、reference_data、task_input直接传给render_input_transform并不需要纯文本自动解析逻辑V1 也没有其他消费者。现在暴露它属于投机性的 API 表面积未来有需要再提升为公开。4.4 引擎的落地演进实现相对文档的增量对照架构文档的 V1 设计当前实现有几处值得注意的演进均可在 jinja_engine.py 源码中确认新增JinjaExtractionErrorValueError子类覆盖过滤器拒绝输入如fromjson作用于非 JSON 字符串与表达式操作了不存在的值嵌套字段缺失、list 越界索引两类场景调用方统一把它当作这份输入没有表达式所要求的东西而非意外崩溃。新增两个内建式过滤器fromjson把 JSON 字符串解析为 Python 对象与format_trace把会话 trace 渲染成EvalTraceFormatter规范的角色标注转录文本让 LLM 无论在哪里看到 trace 都得到同一份可读文本。两个环境都注册了这两个过滤器。新增expression_variables(expression) - set[str]解析表达式涉及的命名空间变量对 eval 消费方做依赖检查有用。它把表达式包进{{ ... }}输出块后再做 AST 遍历因为裸表达式按模板解析只是字面文本。extract的错误语义细化用undefined_to_noneFalse编译单个缺失查找得到Undefined但任何后续操作属性访问、索引、过滤器会抛UndefinedError此时extract将其转换为JinjaExtractionError保留 Jinja 原始消息其中带有缺失字段名而不是让调用方处理裸异常。生成器的物化list(result)放在try块内是刻意的map/selectattr/groupby返回懒生成器逐项查找要等list()才执行缺失字段的错误因此必然在try内抛出test_jinja_engine.py 的TestExtractOperationsOnMissingData专门钉住这条边界。提示以上增量说明jinja_engine.py作为通用引擎其公开面已经超出纯输入变换的最初设计如extract、expression_variables、fromjson/format_trace这正是为 eval v2 等下游消费者预留的通用求值原语。如果你只关心 V1 输入变换可忽略这些增量。5. 适配器集成同步与流式两条路径5.1 单一辅助方法_apply_input_transform变换逻辑集中为 base_adapter.py 第 530-544 行 的一个辅助方法同步与流式两条路径共用避免逻辑漂移未来新增变换变体也只需改一处def _apply_input_transform(self, input: InputType) - InputType: If the run config has an input_transform, render it and return the resulting string. Otherwise return input unchanged. MCP run configs (no input_transform field) are a no-op. if not isinstance(self.run_config, KilnAgentRunConfigProperties): return input transform self.run_config.input_transform if transform is None: return input try: return render_input_transform(transform, input) except Exception as e: raise ValueError(fInput transform failed: {e}) from e注意实现相对架构草稿的一个演进架构文档 §4.1 建议不捕获、原样上抛而实际实现用try/except把渲染期异常包装为带Input transform failed:前缀的ValueError并保留__cause__链集成测试test_input_transform_undefined_error_pre_inference断言exc_info.value.__cause__是UndefinedError。这让调用方更容易把变换失败与模型调用失败区分开。5.2 调用点保持原始input引入model_input同步路径_run_returning_run_outputbase_adapter.py 第 235-254 行与流式路径_prepare_streambase_adapter.py 第 428-444 行采用完全相同的模式if self.input_schema is not None: validate_schema_with_value_error(...) # 1. schema 校验原有行为 model_input self._apply_input_transform(input) # 2. NEW变换只作用于模型面输入 formatted_input model_input # 3. 格式化器看到的是字符串 formatter_id self.model_provider().formatter if formatter_id is not None: formatter request_formatter_from_id(formatter_id) formatted_input formatter.format_input(model_input)为什么必须用model_input而不是覆盖input架构文档 §4.3generate_run(input, ...)在 base_adapter.py 第 328-335 行 用局部变量input持久化TaskRun.input。如果直接把input覆盖为渲染后的字符串TaskRun.input就会保存变换后的文本违反功能规格书 §10/§12 的约定。因此变换结果单独命名为model_input原始input原样流入generate_run。这与文件内既有的注释一致we save the original input in the task without formatting。5.3 执行顺序与持久化约定变换的执行顺序是架构文档 §4.5在输入 schema 校验之后——变换收到的是有 schema 时已通过校验的结构化输入schema 校验不会被绕过在 provider 专用格式化器之前——格式化器在所有变换场景下都收到字符串与既有的纯文本任务路径完全一致在 trace 组装 / 推理之前。持久化层面功能规格书 §12TaskRun.input永远保存原始、未变换的输入。这是刻意的选择而非疏漏渲染字符串是可推导的派生数据原始输入 变换即可重算、变换不可逆只存渲染串将无法还原原始输入、且渲染串对对象/数组 schema 任务几乎必然不满足input_json_schema持久化它会破坏 run 的 schema 不变量。模型实际看到的内容通过既有 trace 机制落入TaskRun.trace[0]第一个用户消息无需新增TaskRun字段。5.4 MCP 路径无需改动McpRunConfigProperties没有input_transform字段_apply_input_transform的isinstance(self.run_config, KilnAgentRunConfigProperties)守卫对 MCP 直接原样返回输入。集成测试test_input_transform_mcp_unchanged验证了字符串与 dict 输入都原样通过。6. 错误处理fail loud, fail fast, fail attributable所有变换错误都发生在推理之前不引入任何新异常类架构文档 §5 的错误矩阵结合实现后的行为失败场景发生阶段呈现方式模板语法错误保存时PydanticValidationError保存被拒绝field_validatorUndefinedError缺失变量运行时render_input_transform被_apply_input_transform包装为ValueError(Input transform failed: ...)__cause__为UndefinedError沙箱SecurityError运行时同上包装为ValueError过滤器异常如fromjson解析失败运行时JinjaExtractionError或包装后的ValueError模板语法错误纵深防御正常不会发生运行时同上两条调用路径中变换发生在 schema 校验与格式化之间、位于 base_adapter.py 第 261 行 的tryKilnRunError包装区之外——因此变换错误不会被包装成KilnRunError而是以普通异常直接呈现给调用方。这是有意为之变换错误是配置 / 编写错误不是运行执行错误不应与模型失败混为一谈与既有 schema 校验错误的处理一致。测试test_input_transform_undefined_error_pre_inference用 mock 的推理层验证了_run从未被调用。7. 依赖与实施顺序7.1 依赖在 libs/core/pyproject.toml 的dependencies中加入jinja23.1.0当前已存在版本下限 3.1.0并在依赖变更后运行uv lock验证uv.lock干净更新。7.2 两阶段实施implementation_plan.md 与 phase_1.md、phase_2.mdPhase 1引擎 数据模型地基。加依赖并uv lock创建utils/jinja_engine.py两个环境实例 四个公开函数 私有_build_namespace创建datamodel/input_transform.pyJinjaInputTransform带模板field_validator、判别函数、InputTransform联合在run_config.py的KilnAgentRunConfigProperties上加字段写test_jinja_engine.py、test_input_transform.py并扩展test_run_config.py。每阶段结束运行uv run ./checks.sh --agent-mode。Phase 2适配器集成。在BaseAdapter上加_apply_input_transform辅助方法在_run_returning_run_output同步与_prepare_stream流式两个调用点接入遵循保留原始input、用model_input供格式化器的约定按架构 §7.4 写适配器集成测试对象 schema、纯文本JSON 非 JSON、数组 schema、identitytransformNone字节级一致、流式路径对齐、UndefinedError在推理前浮出mock provider 断言从不调用、MCP run config 行为不变。8. 测试清单权威依据是功能规格书 §16架构文档 §7 与功能规格书 §16 的清单是实现的权威依据当前仓库中均已落地为真实测试引擎层utils/test_jinja_engine.pycompile_*_or_raise语法错误带行号抛ValueErrorrender_input_transform覆盖 dict 属性访问、list 索引/length过滤、纯文本 JSON 自动解析dict/list/标量、非 JSON 退回原始串、缺失属性抛UndefinedError、dunder 访问__class__、__bases__、__mro__游走、__subclasses__遍历抛SecurityError、空模板返回空串、未知变体抛ValueErrorextract返回值/字符串/list/dict、缺失键返回Undefined、显式 null 返回None、生成器物化为 list、嵌套属性访问、trim_blocks/lstrip_blocks的空白行为另有fromjson/format_trace/expression_variables的专门测试组。数据模型层datamodel/test_input_transform.py合法模板可构造、畸形模板{% if抛ValidationError、model_dump/JSON 往返、判别联合把{type: jinja, ...}分发到JinjaInputTransform、缺失/未知type抛干净的 Pydantic 错误。RunConfig 层datamodel/test_run_config.py 的TestInputTransformField默认None、接受合法变换、dict 判别分发、无input_transform键的旧 JSON 加载为None向后兼容回归、McpRunConfigProperties无该字段负向测试、带变换的往返。适配器集成层adapters/model_adapters/test_base_adapter.py 的TestInputTransformIntegration对象 schema 任务渲染串进入TaskRun.trace首个用户消息且TaskRun.input保留原始 dict纯文本 JSON 被解析非 JSON 纯文本以{{ input }}暴露数组 schema 以{{ input[0] }}暴露input_transformNone行为与无变换字节级一致流式路径与同步路径对齐对_prepare_stream断言捕获到的输入缺失键在推理前以ValueError(Input transform failed:)浮出且__cause__为UndefinedErrorMCP run config 原样通过。覆盖目标上没有量化指标——上面的清单就是权威检查表实施代理不得在未在 phase plan 中说明的情况下增删测试架构文档 §7.5。9. V1 明确不做的事Out of Scope / 未来钩子架构文档 §8 与功能规格书 §3 明确列出 V1 边界渲染无 CPU/内存上限病态模板可以挂住渲染调用作为已记录的 V1 风险见功能规格书 §13V1 不做编译结果缓存引擎 API 已设计为将来可加而不破坏调用方不做自定义 Jinja2 过滤器实现层面已注册的fromjson/format_trace属于后续消费者驱动的演进见 §4.4无 eval 侧代码由未来 eval v2 项目消费无变换编辑 UI未来项目不公开_build_namespace未来需要时再提升。安全模型上模板是 Jinja2 语法而非 Python 代码无任意 Python 执行无{% python %}、无eval()、无文件 I/O无FileSystemLoader、无open()、无网络 I/O、无 shell 访问、无import且SandboxedEnvironment阻断已知 SSTI 链dunder 遍历。模板可以使用{{ ... }}替换、{% if %}/{% for %}/{% set %}块、内建过滤器与测试default、length、join、upper、tojson、is defined、is none等、对传入数据的属性访问与索引、以及作用域内值的算术与字符串拼接。结语从 架构文档 到 功能规格书再到libs/core/kiln_ai中真实落地的 input_transform.py、jinja_engine.py、run_config.py 与 base_adapter.py这条链路展示了 Kiln 处理运行时输入投影的完整设计数据模型侧用判别联合 保存期校验保证模板合法、向前可扩展引擎侧用双沙箱环境在硬失败渲染与软求值提取之间取得平衡适配器侧用单一辅助方法与model_input命名约定保证同步/流式行为一致、原始输入与渲染结果各得其所。理解这条链路后你可以轻松地为任何任务挂载一个JinjaInputTransformRunConfig并预判每一步的校验、渲染与错误行为——这正是 eval v2 以及未来更多消费者所依赖的通用基础设施。赞分享人工智能AI 应用AI 评测RAG微调提示工程开发工具桌面应用【免费下载链接】KilnBuild, Evaluate, and Optimize AI Systems. Includes evals, RAG, agents, fine-tuning, synthetic data generation, dataset management, MCP, and more.项目地址https://gitcode.com/gh_mirrors/ki/Kiln点击查看免费下载相关推荐Kiln Input Transform 创建 UI 完整指南在 /run 页面编写与管理 Jinja2 输入转换模板Kiln Input Transform 创建 UI 完整指南在 /run 页面编写与管理 Jinja2 输入转换模板 导读 本文档深入解析 Kiln 项目中人工智能AI 应用AI 评测RAG微调提示工程开发工具桌面应用MLOpsKiln input_transform 深度解析基于 Jinja2 的任务输入模板化引擎设计与实现Kiln input_transform 深度解析基于 Jinja2 的任务输入模板化引擎设计与实现 导读 input_transform 是 Kiln 核心人工智能AI 应用AI 评测RAG微调提示工程开发工具桌面应用MLOpsKiln Input Transform 创建 UI 功能规范在 /run 页面编排 Jinja2 输入转换器Kiln Input Transform 创建 UI 功能规范在 /run 页面编排 Jinja2 输入转换器 导读 本文讲解 Kiln 开源仓库中 Inpu人工智能AI 应用AI 评测RAG微调提示工程开发工具桌面应用MLOps上一篇如何高效管理您的音乐歌词库163MusicLyrics完整使用指南下一篇从音乐爱好者到歌词专家163MusicLyrics如何重塑你的音乐体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考