Prompt Poet

Prompt Poet 通过低代码方式，为开发者和非技术用户简化并优化提示词设计流程。它结合 YAML 和 Jinja2 模板语言，支持灵活、动态的提示词生成，从而提升与 AI 模型交互的效率和质量。使用 Prompt Poet 可以节省大量字符串处理的工程工作，让团队成员能够更专注于为用户提供最佳的提示词设计。

安装

pip install prompt-poet

基本用法

import os
import getpass

from prompt_poet import Prompt
from langchain import ChatOpenAI

# 如果需要设置 OPENAI_API_KEY，请取消注释。
# os.environ["OPENAI_API_KEY"] = getpass.getpass()

raw_template = """
- name: 系统指令
  role: system
  content: |
    你的名字是 {{ character_name }}，你应当乐于助人，绝不会对人类造成任何伤害。

- name: 用户问题
  role: user
  content: |
   {{ username}}: {{ user_query }}

- name: 回答
  role: assistant
  content: |
    {{ character_name }}:
"""

template_data = {
  "character_name": "角色助手",
  "username": "杰夫",
  "user_query": "你能帮我做作业吗？"
}

prompt = Prompt(
    raw_template=raw_template,
    template_data=template_data
)

model = ChatOpenAI(model="gpt-4o-mini")
response = model.invoke(prompt.messages)

提示模板

Prompt Poet 模板结合使用 YAML 和 Jinja2。模板处理主要分为两个阶段：

• 渲染：首先，Jinja2 会处理输入数据。在此阶段，控制流逻辑会被执行，数据会被验证并正确绑定到变量上，模板中的函数也会被适当地评估。
• 加载：渲染完成后，输出是一个结构化的 YAML 文件。该 YAML 结构由多个重复的块或部分组成，每个部分都被封装为一个 Python 数据结构。这些部分具有以下几个属性：
  • 名称：清晰、易于理解的部分标识符。
  • 内容：实际的字符串内容，构成提示的一部分。
  • 角色（可选）：指定参与者的角色，有助于区分不同的用户或系统组件。
  • 截断优先级（可选）：在需要截断时决定截断顺序，具有相同优先级的部分会按照它们出现的顺序进行截断。

示例：基础问答机器人

- name: system instructions
  role: system
  content: |
    你的名字是 {{ character_name }}，你应当乐于助人，绝不能对人类造成伤害。

- name: user query
  role: user
  content: |
   {{ username}}: {{ user_query }}

- name: reply_prompt
  role: user
  content: |
    {{ character_name }}:

插值列表

如果你有一个包含元素（例如消息）的列表，可以将其解析到模板中，如下所示：

{% for message in current_chat_messages %}
- name: chat_message
  role: user
  content: |
    {{ message.author }}: {{ message.content }}
{% endfor %}

截断旧消息

上下文长度有限，有时无法容纳整个聊天历史——因此我们可以为消息部分设置截断优先级，Prompt Poet 会按照它们出现的顺序（从最旧到最新）来截断这些部分。

{% for message in current_chat_messages %}
- name: chat_message
  role: user
  truncation_priority: 1
  content: |
    {{ message.author }}: {{ message.content }}
{% endfor %}

根据用户模式调整

根据用户当前的模式（音频或文本）定制指令：

{% if modality == "audio" %}
- name: special audio instruction
  role: system
  content: |
    {{ username }} 目前正在使用音频模式。请保持回答简洁明了。
{% endif %}

针对特定查询

在需要时加入与上下文相关的示例，例如作业辅导：

{% if extract_user_query_topic(user_query) == "homework_help" %}
{% for homework_example in fetch_few_shot_homework_examples(username, character_name) %}
- name: homework_example_{{ loop.index }}
  role: user
  content: |
    {{ homework_example }}
{% endfor %}
{% endif %}

处理空白字符

默认情况下，Prompt Poet 会去除空白字符，以避免最终提示中出现不必要的换行。如果需要保留明确的空格，请使用内置的特殊空格标记“<|space|>”，以确保格式正确。

- name: system instructions
  role: system
  content: |
    你的名字是 {{ character_name }}，你应当乐于助人，绝不能对人类造成伤害。

- name: user query
  role: user
  content: |
   <|space|>{{ username}}: {{ user_query }}

综合应用

组合性是 Prompt Poet 模板的核心优势之一，它能够创建复杂且动态的提示。

- name: system instructions
  role: system
  content: |
    你的名字是 {{ character_name }}，你应当乐于助人，绝不能对人类造成伤害。

{% if modality == "audio" %}
- name: special audio instruction
  role: system
  content: |
    {{ username }} 目前正在使用音频模式。请保持回答简洁明了。
{% endif %}

{% if extract_user_query_topic(user_query) == "homework_help" %}
{% for homework_example in fetch_few_shot_homework_examples(username, character_name) %}
- name: homework_example_{{ loop.index }}
  role: user
  content: |
    {{ homework_example }}
{% endfor %}
{% endif %}

{% for message in current_chat_messages %}
- name: chat_message
  role: user
  truncation_priority: 1
  content: |
    {{ message.author }}: {{ message.content }}
{% endfor %}

- name: user query
  role: user
  content: |
   {{ username}}: {{ user_query }}

- name: reply_prompt
  role: user
  content: |
    {{ character_name }}:

分解为小节

为了遵循 DRY 原则，你可以将模板分解为可重用的小节，以便在不同模板中复用，比如在进行新提示的 A/B 测试时。

{% include 'sections/system_instruction.yml.j2' %}

{% include 'sections/audio_instruction.yml.j2' %}

{% if extract_user_query_topic(user_query) == "homework_help" %}
{% include 'sections/homework_examples.yml.j2' %}
{% endif %}

{% include 'sections/chat_messages.yml.j2' %}

{% include 'sections/user_query.yml.j2' %}

{% include 'sections/reply_prompt.yml.j2' %}

嵌套小节用于统计 token 使用情况

为了详细监控不同内容组件中的 token 使用情况，可以使用嵌套小节。这在需要细粒度统计哪些部分的提示占用了 token 时非常有用（例如，角色定义 vs. 安全规则 vs. 对话风格）。

- name: system_instructions
  role: system
  sections:
    - name: character_intro
      content: |
        你的名字是 {{ character_name }}，你是一位乐于助人的助手。
    - name: safety_rules
      content: |
        绝不伤害人类。始终保持尊重和友善。
    - name: conversation_style
      content: |
        回答应简洁而富有吸引力。

随后可以访问详细的统计信息：

prompt = Prompt(raw_template=raw_template, template_data=template_data)
prompt.tokenize()

# 获取分层统计
stats = prompt.section_stats
print(stats)
>>> [
    {
        "part_name": "system_instructions",
        "part_tokens": 150,
        "part_role": "system",
        "has_sections": True,
        "sections": [
            {"section_name": "character_intro", "section_tokens": 50},
            {"section_name": "safety_rules", "section_tokens": 60},
            {"section_name": "conversation_style", "section_tokens": 40}
        ]
    }
]

# 或者获取标记计数的扁平映射
counts = prompt.get_section_token_counts()
print(counts)
>>> {
    "system_instructions": {
        "character_intro": 50,
        "safety_rules": 60,
        "conversation_style": 40
    }
}

重要提示：

• 部分可以拥有 内容 或 章节，但不能同时拥有两者。
• 章节使用 YAML 块标量（|）来保留换行符，以便在拼接时正确分隔。
• 章节内容会自动拼接成该部分的内容。
• 由于标记化边界效应，各个章节的标记计数之和可能不完全等于该部分的标记计数。
• 此功能完全向后兼容——现有的无章节模板无需更改即可正常工作。

设计选择

Prompt Poet 库

Prompt Poet 库提供了多种功能和设置，包括提示属性。关键功能如标记化和截断有助于高效缓存和低延迟响应。

prompt.tokenize()
prompt.truncate(token_limit=TOKEN_LIMIT, truncation_step=TRUNCATION_STEP)

# 检查提示作为原始字符串。
prompt.string: str
>>> "..."

# 检查提示作为原始标记。
prompt.tokens: list[int]
>>> [...]

# 检查提示作为 LLM API 消息字典。
prompt.messages: list[dict]
>>> [...]

# 检查提示作为一等公民部分。
prompt.parts: list[PromptPart]
>>> [...]

模板语言

Jinja2 和 YAML 的结合提供了一种极具扩展性和表现力的模板语言。Jinja2 支持直接的数据绑定、任意函数调用以及模板内的基本控制流。YAML 则为我们的模板提供了结构（深度为 1），使我们在达到标记限制时能够进行复杂的截断操作。这种 Jinja2 和 YAML 的组合并不独特——最著名的例子就是 Ansible 所使用的组合。

模板原生函数调用

Jinja2 的一个突出特点是能够在运行时直接在模板中调用任意 Python 函数。这一特性对于实时数据检索、处理和验证至关重要，从而简化了提示的构建过程。例如，extract_user_query_topic 可以对用户查询进行任意处理，并将其用于模板的控制流中——比如通过与主题分类器进行一次往返调用来实现。

{% if extract_user_query_topic(user_query) == "homework_help" %}
{% for homework_example in fetch_few_shot_homework_examples(username, character_name) %}
- name: homework_example_{{ loop.index }}
  role: user
  content: |
    {{ homework_example }}
{% endfor %}
{% endif %}

自定义编码函数

默认情况下，Prompt Poet 会使用 TikToken 的 “o200k_base” 编码器，不过也可以在顶层指定其他编码名称 tiktoken_encoding_name。此外，用户还可以通过顶层参数 encode_func: Callable[[str], list[int]] 提供自己的编码函数。

from tiktoken import get_encoding
encode_func = get_encoding("o200k_base")

prompt = Prompt(
    raw_template=raw_template,
    template_data=template_data,
    encode_func=encode_func
)
prompt.tokenize()
prompt.tokens
>>> [...]

截断

如果您的 LLM 提供商支持 GPU 关联性和前缀缓存，请使用 Character.AI 的截断算法来最大化前缀缓存率。前缀缓存率定义为从缓存中检索到的提示标记数占提示总标记数的比例。请根据您的具体用例找到最佳的截断步长和标记限制值。随着截断步长的增加，前缀缓存率也会提高，但同时会有更多的标记被截断。

TOKEN_LIMIT = 128000
TRUNCATION_STEP = 4000

# 对提示进行标记化并截断。
prompt.tokenize()
prompt.truncate(token_limit=TOKEN_LIMIT, truncation_step=TRUNCATION_STEP)

response = model.invoke(prompt.messages)

缓存感知截断详解

简而言之，缓存感知截断会在每次调用时都截断到一个固定的截断点——只有平均每 k 轮才会移动这个截断点。这样可以让您的 LLM 提供商最大限度地利用 优化推理 中描述的 GPU 前缀缓存。相反，如果我们只是简单地截断到标记限制（L），那么截断点每轮都会移动，这将显著降低前缀缓存率。这种方法的权衡在于，我们往往会截断比实际需要更多的内容。

模板注册表

模板注册表的概念就是将模板文件存储在磁盘上。使用模板注册表可以使模板文件与 Python 代码分离，并可以直接从磁盘加载这些文件。在生产系统中，这些模板文件可以在后续使用时选择从内存缓存中加载，从而节省磁盘 I/O。未来，模板注册表可能会成为 Prompt Poet 的一等公民。

文件名：chat_template.yml.j2

- name: 系统指令
  role: 系统
  content: |
    你的名字是 {{ character_name }}，你应当乐于助人，绝不会伤害人类。

- name: 用户提问
  role: 用户
  content: |
    {{ username}}: {{ user_query }}

- name: 回答
  role: 用户
  content: |
    {{ character_name }}:

请在保存了 chat_template.yml.j2 文件的同一目录下运行以下 Python 代码。

from prompt_poet import Prompt

prompt = Prompt(
    template_path="chat_template.yml.j2",
    template_data=template_data
)
print(prompt.string)
>>> '你的名字是角色助手，你应当乐于助人，绝不会伤害人类。杰夫：你能帮我做作业吗？角色助手：'

相关工作

• Priompt：Priompt（优先级 + 提示）是一个基于 JSX 的提示库。它通过优先级来决定哪些内容应被纳入上下文窗口。该项目实现了类似的目标，即在 TypeScript 为基础的用法中，将模板层与逻辑构建层分离，并保持兼容性。
• dspy：提供了一种自动优化针对不同模型的提示的优秀方法，但缺乏对提示的确定性控制，而这对于缓存以及高吞吐、低延迟的生产系统来说至关重要。
• Prompt Engine：该 TypeScript 包源于一个常见的问题——生产环境中的提示工程需要大量代码来操作和更新字符串。它同样为提示模板化过程增加了结构，不过显得较为主观，基于使用场景做出了一些假设。由于最近的提交是在两年前，目前看来该包并未处于积极开发状态。
• llm：允许以 YAML 格式定义基础提示，并启用 Jinja2 的功能，如动态控制流、函数调用和数据绑定。
• 原生 Python f-string：有多个项目通过封装 f-string 来采用略有不同的提示模板化方法：
  • LangChain：LangChain 的覆盖范围远超提示模板，但它确实提供了一些基础的模板化抽象。适用于简单的模板化场景，但随着提示复杂度的增加，会变得越来越笨重。
  • LlamaIndex：与 LangChain 类似，LlamaIndex 的覆盖范围也远超提示模板，同时提供了一些基础的模板化抽象。
  • Mirascope：实现了一种新颖的提示模板化方法，即将所有内容封装在一个 Python 类中，并使用该类的文档字符串作为 f-string，用于绑定数据。

Prompt Poet 快速上手指南

Prompt Poet 是一款专为开发者和非技术用户设计的提示词（Prompt）工程工具。它结合了 YAML 的结构化优势与 Jinja2 的模板灵活性，支持动态数据绑定、逻辑控制流以及智能截断策略，帮助你高效构建高质量的 AI 交互提示词。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Windows, macOS, 或 Linux
• Python 版本：Python 3.8 或更高版本
• 前置依赖：
  • pip (Python 包管理工具)
  • 推荐使用虚拟环境 (如 venv 或 conda) 隔离项目依赖
• API Key：若需调用 OpenAI 模型，请准备好 OPENAI_API_KEY

国内加速建议：如果安装过程中遇到网络问题，建议使用国内镜像源（如清华源或阿里源）进行安装。

安装步骤

使用 pip 直接安装 Prompt Poet：

pip install prompt-poet

推荐使用国内镜像源加速安装：

pip install prompt-poet -i https://pypi.tuna.tsinghua.edu.cn/simple

如需同时安装 LangChain（用于示例中的模型调用）：

pip install langchain openai -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是使用 Prompt Poet 构建并调用一个大语言模型的最简示例。该示例展示了如何定义模板、注入数据并生成最终的消息列表。

1. 编写 Python 脚本

创建一个名为 main.py 的文件，并填入以下代码：

import os
import getpass

from prompt_poet import Prompt
from langchain import ChatOpenAI

# 如果未设置环境变量，请在运行时输入 API Key
# os.environ["OPENAI_API_KEY"] = getpass.getpass()

# 定义原始模板 (混合 YAML 结构与 Jinja2 语法)
raw_template = """
- name: system instructions
  role: system
  content: |
    Your name is {{ character_name }} and you are meant to be helpful and never harmful to humans.

- name: user query
  role: user
  content: |
   {{ username}}: {{ user_query }}

- name: response
  role: user
  content: |
    {{ character_name }}:
"""

# 准备模板数据
template_data = {
  "character_name": "Character Assistant",
  "username": "Jeff",
  "user_query": "Can you help me with my homework?"
}

# 初始化 Prompt 对象
prompt = Prompt(
    raw_template=raw_template,
    template_data=template_data
)

# 初始化模型 (以 OpenAI GPT-4o-mini 为例)
model = ChatOpenAI(model="gpt-4o-mini")

# 调用模型并获取响应
# prompt.messages 会自动转换为 LLM API 所需的消息字典格式
response = model.invoke(prompt.messages)

print(response.content)

2. 运行脚本

在终端中执行脚本：

python main.py

程序将自动渲染模板，将 template_data 中的变量填入 YAML 结构，生成标准的消息列表发送给模型，并打印返回结果。

核心特性简述

• 动态渲染：利用 Jinja2 语法（如 {% if %}, {% for %}）在模板中实现逻辑判断和循环。
• 结构化输出：模板渲染后自动解析为包含 name, role, content 的标准消息块。
• 智能截断：支持通过 truncation_priority 属性控制长上下文时的截断顺序，优化 Token 使用。