POML 与 OpenAI 集成

本文基于官方页面（microsoft.github.io/poml/stable... POML 与 OpenAI Python SDK 的集成方式，包括基础用法、消息参数获取、运行参数、结构化输出以及工具调用。

导语/背景介绍

官方页面说明：POML 提供与 OpenAI Python SDK 的无缝集成（seamless integration），可将 POML 文件直接用于 OpenAI 的 Chat Completions API。

功能介绍

生成 OpenAI 兼容参数：通过 format="openai_chat" 从 POML Prompt 文件生成可直接用于 chat.completions.create 的参数。
消息与模型参数：返回的参数字典包含 messages、以及在 POML 中可选定义的 model、temperature 等。
运行参数：使用 <runtime> 标签声明运行时参数，自动转换为 OpenAI 兼容的 snake_case。
结构化输出：使用 <output-schema> 支持 OpenAI 的 Structured Output（结构化输出）。
工具调用：通过 <tool-definition> 定义函数调用，并用 <tool-request>/<tool-response> 处理往返交互。

使用方法

1) 基础用法（Basic Usage）

python 复制代码

import poml
from openai import OpenAI

client = OpenAI()
# 加载 POML 并获取 OpenAI 兼容参数
params = poml.poml("prompt.poml", format="openai_chat")
# 直接与 OpenAI SDK 一起使用
response = client.chat.completions.create(**params)

2) 获取 Chat Completion 消息参数（Getting Chat Completion Messages）

python 复制代码

params = poml.poml("prompt.poml", format="openai_chat")
# params 包含：
# {
#   "messages": [...],      # 聊天消息列表
#   "model": "gpt-4",       # 若在 POML 中指定
#   "temperature": 0.7,     # 若在 POML 中指定
#   ...
# }

3) 运行参数（Runtime Parameters）

xml 复制代码

<poml>
  <system-msg>You are a helpful assistant.</system-msg>
  <human-msg>Hello!</human-msg>
  <runtime
    model="gpt-4.1"
    temperature="0.7"
    max-tokens="150"
    top-p="1.0"
    frequency-penalty="0.5"
    presencePenalty="0.0" /> <!-- can be camelCase -->
</poml>

运行参数会自动转换为 OpenAI 兼容的 snake_case。

4) 结构化输出（Response Format / Structured Output）

xml 复制代码

<poml>
  <system-msg>Extract the event information.</system-msg>
  <human-msg>Alice and Bob are going to a science fair on Friday.</human-msg>
  <output-schema>
    z.object({
      name: z.string(),
      date: z.string(),
      participants: z.array(z.string()),
    });
  </output-schema>
</poml>

python 复制代码

params = poml.poml("response_format.poml", format="openai_chat")
# params 将包含 "response_format"（用于结构化输出）
response = client.chat.completions.create(model="gpt-4.1", **params)
result = json.loads(response.choices[0].message.content)
print(result)  # {'name': 'Science Fair', 'date': 'Friday', 'participants': ['Alice', 'Bob']}

5) 工具调用（Tool Calls）

xml 复制代码

<poml>
  <p>What is my horoscope? I am an Aquarius.</p>
  <tool-definition name="get_horoscope" description="Get today's horoscope for an astrological sign.">
    {
      "type": "object",
      "properties": {
        "sign": {
          "type": "string",
          "description": "An astrological sign like Taurus or Aquarius"
        }
      },
      "required": ["sign"]
    }
  </tool-definition>

  <!-- Handle tool interactions with context -->
  <tool-request if="tool_request"
                id="{{ tool_request.id }}"
                name="{{ tool_request.name }}"
                parameters="{{ tool_request.parameters }}" />
  <tool-response if="tool_response"
                 id="{{ tool_response.id }}"
                 name="{{ tool_response.name }}">
    <object data="{{ tool_response.result }}"/>
  </tool-response>
</poml>

python 复制代码

# Initial request
context = {
    "tool_request": None,
    "tool_response": None,
}
params = poml.poml("tool_call.poml", context=context, format="openai_chat")
response = client.chat.completions.create(model="gpt-4.1", **params)

# Process tool call
tool_call = response.choices[0].message.tool_calls[0]
context["tool_request"] = {
    "name": tool_call.function.name,
    "parameters": json.loads(tool_call.function.arguments),
    "id": tool_call.id,
}

# Execute the function
result = {"horoscope": get_horoscope(**context["tool_request"]["parameters"])}

# Send tool response back
context["tool_response"] = {
    "name": tool_call.function.name,
    "result": result,
    "id": tool_call.id,
}
params = poml.poml("tool_call.poml", context=context, format="openai_chat")
response = client.chat.completions.create(model="gpt-4.1", **params)
print(response.choices[0].message.content)

使用场景

官方页面未提供具体使用场景示例。

优势亮点（基于页面表述）

与 OpenAI Python SDK 的无缝集成，可直接将 POML 文件用于 Chat Completions API。
从 POML 生成 OpenAI 兼容参数（format="openai_chat"），可直接传入 chat.completions.create。
<runtime> 声明的运行时参数自动转换为 snake_case，以兼容 OpenAI。
通过 <output-schema> 支持 OpenAI 的结构化输出（Structured Output）。
通过 <tool-definition> 支持 OpenAI 的函数调用（Function Calling），并可在上下文中处理 <tool-request>/<tool-response>。

总结/展望

本页展示了 POML 与 OpenAI 集成的关键能力：基础用法、参数获取、运行参数、结构化输出与工具调用。
如需进一步细节与代码，请参考官方页面：
- microsoft.github.io/poml/stable...