企业官网建设流程全解析

TensorZero 提示词模板（Prompt Template）与 Schema 完整实战指南：从创建、配置到推理调用

【免费下载链接】tensorzeroTensorZero is an open-source LLMOps platform that unifies an LLM gateway, observability, evaluation, optimization, and experimentation.项目地址: https://gitcode.com/GitHub_Trending/te/tensorzero

导读

本文以 TensorZero 开源 LLMOps 平台的提示词模板功能为核心，基于仓库内完整可运行示例 examples/docs/guides/gateway/create-a-prompt-template 与官方指南 docs/gateway/create-a-prompt-template.mdx，系统讲解为什么需要提示词模板、如何用 MiniJinja 编写模板、如何在tensorzero.toml中声明模板与 JSON Schema、以及如何在推理请求中通过tensorzero::template内容块动态使用模板。读完本文，你将掌握一套"提示词与代码解耦、按模型独立变体、结构化收集推理数据"的完整工程化方案，并能直接运行示例验证效果。

为什么要创建提示词模板？

在 TensorZero 中，function（函数）是推理请求的抽象入口，而variant（变体）是具体实现——每个变体绑定一个模型（如openai::gpt-5-mini）和一套提示词。将提示词抽离为模板（template），而不是把字符串硬编码在应用代码里，主要带来三个核心收益：

1. 提示词与应用代码解耦：随着时间推移迭代提示词（或进行 A/B 测试 时），无需改动应用代码即可在集中式配置中统一管理，团队成员协作更简单。
2. 收集结构化推理数据集：如果只把提示词存成字符串，日后做 监督微调（SFT） 时只能用当时实际用过的旧提示词。而模板保存的是输入变量（如topic），你可以反事实地把新提示词换入历史训练数据，这对实验新模型尤其重要——因为提示词在不同模型之间往往不能直接迁移。
3. 实现模型专属提示词：某个模型的最佳提示词往往不适用于另一个模型。在 TensorZero 中，提示词与模型是两个独立维度，可以自由组合尝试（例如为gpt-5-mini和另一个模型各配一套模板），这在应用代码层面很难优雅实现。

完整示例项目结构

仓库中给出了一个可直接运行的示例，目录结构如下（见 examples/docs/guides/gateway/create-a-prompt-template）：

create-a-prompt-template/ ├── README.md # 运行说明 ├── docker-compose.yml # 启动 Gateway + Postgres + UI ├── openai_sdk.py # 使用 OpenAI SDK 调用模板的示例 ├── pyproject.toml # Python 依赖（openai） ├── uv.lock └── config/ ├── tensorzero.toml # 函数、变体、模板与 Schema 的声明 └── functions/ └── fun_fact/ ├── fun_fact_topic_schema.json # 模板变量契约 └── gpt_5_mini/ └── fun_fact_topic_template.minijinja # MiniJinja 模板

示例围绕一个fun_fact（冷知识）聊天函数展开：用户传入一个topic主题，由模型返回一条与该主题相关的冷知识。下面按步骤逐步搭建。

第一步：编写 MiniJinja 提示词模板

TensorZero 使用 MiniJinja 作为模板语言。MiniJinja 与 Flask、Django 等广泛使用的 Jinja2大部分兼容，熟悉 Jinja2 的开发者几乎零成本上手。

新建模板文件 fun_fact_topic_template.minijinja，内容只有一行：

Share a fun fact about: {{ topic }}

{{ topic }}是变量插值语法，topic将在推理时由调用方通过参数注入。除了插值，MiniJinja 还支持控制流（{% if %}、{% for %}）、过滤器、宏等 Jija2 常见特性；在仓库源码中，模板渲染由 crates/tensorzero-core/src/minijinja_util.rs 负责，配置解析时template_filesystem_access等相关字段在 crates/tensorzero-core/src/config/gateway.rs 中定义。MiniJinja 官方提供浏览器 Playground，方便你先行调试模板语法。

第二步：在变体配置中声明模板

模板文件本身只是一段文本，还必须告诉 TensorZero "这个模板属于哪个变体"。修改 config/tensorzero.toml：

[functions.fun_fact] type = "chat" [functions.fun_fact.variants.gpt_5_mini] type = "chat_completion" model = "openai::gpt-5-mini" templates.fun_fact_topic.path = "functions/fun_fact/gpt_5_mini/fun_fact_topic_template.minijinja" # relative to this file

关键点说明：

• templates.<模板名>.path声明该变体拥有的模板，路径相对于tensorzero.toml所在目录（config/）；
• 一个变体可以配置多个模板（例如templates.system、templates.user、templates.fun_fact_topic等），彼此用不同名字区分；
• type = "chat_completion"指定变体走 OpenAI 兼容的 chat completion 推理路径，model = "openai::gpt-5-mini"通过provider::model格式引用模型；
• 该模板属于gpt_5_mini变体，因此文件放在gpt_5_mini/子目录下，便于为不同模型维护各自的提示词——这正是"模型专属提示词"能力的体现。

第三步：推理时动态使用模板

配置完成后，通过 OpenAI SDK 发送推理请求即可触发模板渲染。完整示例见 openai_sdk.py：

import openai client = openai.OpenAI(base_url="http://localhost:3000/openai/v1", api_key="not-used") result = client.chat.completions.create( model="tensorzero::function_name::fun_fact", messages=[ { "role": "user", "content": [ { "type": "tensorzero::template", # type: ignore "name": "fun_fact_topic", "arguments": {"topic": "artificial intelligence"}, } ], }, ], ) print(result)

三个要点：

• base_url指向 TensorZero Gateway（http://localhost:3000/openai/v1），API Key 在本地开发场景可随意填写（示例用"not-used"），实际鉴权由 tensorzero-auth 等模块处理；
• model使用 TensorZero 专属寻址格式tensorzero::function_name::<function>，即路由到名为fun_fact的函数（其内部默认使用gpt_5_mini变体）；
• content中放入tensorzero::template类型的内容块：name指定模板名（必须与配置中templates.fun_fact_topic一致），arguments传入模板变量字典。TensorZero 会先渲染模板Share a fun fact about: artificial intelligence，再连同消息一起发送给模型。

第四步：为模板定义 JSON Schema（推荐）

当函数有多个变体时，很容易出现"各变体模板变量名/类型不一致"的配置错误。Schema 以契约形式校验模板变量，把错误挡在生产环境之前。定义 Schema 是可选的，但官方强烈推荐。

创建 Schema

模板只有一个变量topic，对应 JSON Schema 见 fun_fact_topic_schema.json：

{ "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "topic": { "type": "string" } }, "required": ["topic"], "additionalProperties": false }

该 Schema 明确约束：入参必须是对象、topic字段必填且为字符串、不允许额外字段。你可以让 LLM 直接生成这样的 Schema（例如"Generate a JSON schema with a single field:topic. Thetopicfield is required. No additional fields are allowed."），也可以从 Pydantic 模型或 Zod Schema 导出 JSON Schema。

配置 Schema

在函数定义中用schemas.<schema名>.path声明。一旦声明，该函数下的每个变体都必须提供同名模板，从而保证所有变体的提示词输入契约一致：

[functions.fun_fact] type = "chat" schemas.fun_fact_topic.path = "functions/fun_fact/fun_fact_topic_schema.json" # relative to this file [functions.fun_fact.variants.gpt_5_mini] type = "chat_completion" model = "openai::gpt-5-mini" templates.fun_fact_topic.path = "functions/fun_fact/gpt_5_mini/fun_fact_topic_template.minijinja" # relative to this file

复用提示词片段

如果多个模板共享公共片段，可以开启模板文件系统访问：在配置中设置gateway.template_filesystem_access.base_path，即可在模板里使用 MiniJinja 的{% include %}与{% import %}指令复用共享片段。需要注意的是，配置存放在数据库（Config-in-DB）的场景下该能力被禁用——从 crates/tensorzero-core/src/config/gateway.rs 的源码注释可以看到这一点，因为文件系统访问与数据库托管的配置模型天然冲突。详细用法参见 组织你的配置。

从旧版提示词格式迁移

早期版本中，提示词模板只能命名为system_template、user_template、assistant_template（Schema 同理为system_schema等），每个角色最多一个模板，灵活度受限。新版templates.<name>.path格式支持任意命名与多模板，迁移映射如下：

迁移注意两点：

• 新建函数和模板一律使用新格式；
• 数据库中的历史可观测数据仍按旧格式存储。若希望数据前向兼容（例如用于微调），可按上表更新配置；随着旧格式被废弃，TensorZero 会自动为历史数据查找新格式的模板与 Schema。这一"模板名与角色解耦"的设计，在源码层的配置解析与写入逻辑中均有体现（参见 crates/tensorzero-core/src/db/postgres/function_config_writes.rs 等文件）。

运行完整示例

仓库中的示例附带完整的 Docker 编排（docker-compose.yml），包含三个服务：TensorZero Gateway（3000 端口）、TensorZero UI（4000 端口）和 Postgres（5432 端口），并在 Gateway 启动前通过gateway-run-postgres-migrations服务自动执行数据库迁移。按以下步骤运行：

# 1. 设置 OpenAI API Key export OPENAI_API_KEY="sk-..." # 替换为你的 OpenAI API Key # 2. 启动 Gateway 与本地 Postgres docker compose up # 3. 安装 Python 依赖（推荐使用 uv） uv sync # 4. 运行示例 uv run openai_sdk.py

依赖仅需openai一个包（见 pyproject.toml）。示例中OPENAI_API_KEY通过${OPENAI_API_KEY:?Environment variable OPENAI_API_KEY must be set.}强制校验，未设置时docker compose up会直接报错提示。配置目录以只读方式挂载进容器（./config:/app/config:ro），并通过--config-file /app/config/tensorzero.toml指定入口配置。注意该 compose 文件为教学用途的简化版本，生产部署请参考仓库内的 部署文档 与 Helm Charts。

运行成功后，print(result)会输出模型返回的冷知识响应，你可以把arguments.topic换成任意主题（如 "quantum computing"）验证模板的动态渲染效果，也可以修改fun_fact_topic_template.minijinja后重启 Gateway 观察提示词变更对输出的影响——整个过程无需改动任何应用代码，这正是提示词模板的核心价值所在。

【免费下载链接】tensorzeroTensorZero is an open-source LLMOps platform that unifies an LLM gateway, observability, evaluation, optimization, and experimentation.项目地址: https://gitcode.com/GitHub_Trending/te/tensorzero