POML Python Core API 参考

导语

本文基于 POML 官方文档的 Python Core APIs 参考页面，梳理核心接口的用途与用法。POML（Prompt Orchestration Markup Language）用于创建结构化的提示与对话；核心 API 提供对 POML 标记的处理能力，并支持可选的追踪与多种后端集成。

概览与功能说明

poml()：处理 POML 标记，按指定格式返回结果，可选择聊天模式或单次提示，并支持将输出保存到文件。
set_trace()：启用/关闭追踪，并按需接入后端（local、weave、agentops、mlflow）。
clear_trace() / get_trace()：清理或获取追踪日志副本。
trace_artifact()：为最近一次 poml 调用写入额外的工件文件（实验性）。
说明要点：
- 在启用 set_trace() 时，会自动记录调用详情。
- 支持多种输出格式（如 raw、message_dict、dict、openai_chat、langchain、pydantic）。
- 在聊天格式下支持多模态内容（例如图片）。

核心 API 与参数

set_trace(enabled=True, /, *, trace_dir=None)

作用：启用或禁用 poml 调用的追踪，并可选择后端集成。
参数：
- enabled: bool | List[str] | str
  - True：仅启用本地追踪（等价于 ["local"]）
  - False：关闭所有追踪（等价于 []）
  - "local" | "weave" | "agentops" | "mlflow"：启用单个后端
  - List[str]：启用多个后端（指定任一后端时会自动启用本地追踪）
- trace_dir: Optional[str | Path]：为本地追踪指定目录；开启本地追踪时会在其中创建以时间戳命名的子目录。
返回：Optional[Path]，若启用本地追踪则返回追踪目录路径，否则为 None。
其他：可通过环境变量 POML_TRACE 与 Node.js 共享目录。可用后端：
- local：将追踪文件保存到磁盘
- weave：上报到 Weights & Biases Weave（需要本地追踪）
- agentops：上报到 AgentOps（需要本地追踪）
- mlflow：上报到 MLflow（需要本地追踪）

poml(markup, context=None, stylesheet=None, chat=True, output_file=None, format='message_dict', extra_args=None)

作用：处理 POML 标记并按指定格式返回结果。
参数（节选）：
- markup: str | Path：POML 源文本，或指向 .poml 文件的路径；若字符串看起来像路径但文件不存在，会发出警告并按源文本处理。
- context: dict | str | Path | None：注入模板的上下文，可为字典、JSON 字符串或 JSON 文件路径。
- stylesheet: dict | str | Path | None：渲染样式，支持字典、JSON 字符串或 JSON 文件路径。
- chat: bool：是否按"聊天"处理（默认 True；False 时按单条提示处理）。
- output_file: str | Path | None：可选的输出保存路径；未提供则直接返回结果而不落盘。
- format：输出格式，支持：
  - "raw"：返回原始字符串
  - "message_dict"：仅返回消息数组（兼容旧格式）
  - "dict"：包含 messages、schema、tools、runtime 的完整结构
  - "openai_chat"：OpenAI Chat Completion 兼容格式（含工具/模式）
  - "langchain"：LangChain 消息与元数据
  - "pydantic"：返回强类型 PomlFrame
- extra_args: Optional[List[str]]：额外传给 POML 处理器的命令行参数。
返回：list | dict | str | PomlFrame，与 format 对应。
说明：
- openai_chat：在有工具/模式时包含 tools 与 response_format；运行时参数转换为 snake_case。
- langchain：保留全部元数据并返回 LangChain 格式的 messages。
- pydantic：返回 PomlFrame，其中 messages 为 PomlMessage 对象，并带 output_schema、tools、runtime。
异常：
- FileNotFoundError：指定的文件路径不存在时
- RuntimeError：处理器失败或后端追踪要求未满足时
- ValueError：输出格式非法时

clear_trace()

作用：清空已收集的追踪日志。

get_trace()

作用：返回追踪日志的副本。

trace_artifact(file_suffix, contents)

作用：为最近一次 poml 调用写入额外工件文件（实验性）。
返回：Optional[Path]，若没有可用前缀则返回 None。

示例（来自文档）

python 复制代码

>>> result = poml("<p>Hello {{name}}!</p>", context={"name": "World"})

python 复制代码

>>> result = poml("template.poml", context="context.json")

python 复制代码

>>> messages = poml("chat.poml", format="openai_chat")

python 复制代码

>>> result = poml(
...     markup="template.poml",
...     context={"user": "Alice"},
...     stylesheet={"role": {"captionStyle": "bold"}},
...     format="pydantic"
... )

python 复制代码

>>> poml("template.poml", output_file="output.json", format="raw")

参考链接

文档：microsoft.github.io/poml/stable...

总结

Core API 提供了对 POML 标记的处理、结果格式化、追踪与工件写入等能力。根据需求选择合适的 format 与追踪后端，并参考文档中的示例与参数说明进行集成与调用。