POML Python 集成参考：AgentOps / LangChain / MLflow / Pydantic / Weave

POML Python 集成参考：AgentOps / LangChain / MLflow / Pydantic / Weave

导语

本文基于 POML 官方文档的 Integration 参考页面，梳理 Python 端提供的集成模块与关键 API/类，包括 agentops、langchain、mlflow、pydantic 与 weave。内容严格来自文档页面，并以结构化方式呈现功能说明与示例。

模块总览

• poml.integration.agentops
• poml.integration.langchain
• poml.integration.mlflow
• poml.integration.pydantic
• poml.integration.weave

---

AgentOps 集成（poml.integration.agentops）

功能介绍

• log_poml_call(name, prompt, context, stylesheet, result)：将一次完整的 poml 调用记录到 AgentOps。

关键 API

• log_poml_call(name, prompt, context, stylesheet, result)
  • 说明："Log the entire poml call to agentops."

文档示例

# 文档中的函数实现示例（节选）
@agentops.operation(name="poml")
def poml(prompt, context, stylesheet):
    return result

poml(prompt, context, stylesheet)

---

LangChain 集成（poml.integration.langchain）

功能介绍

• LangchainPomlTemplate：兼容 LangChain 的 PromptTemplate，实现以 POML 进行格式化；支持"说话人模式（speaker modes）"与结构化内容。

关键类与属性

• LangchainPomlTemplate(PromptTemplate)
  • template_file: Union[str, Path, None]：模板文件路径（若由文件加载）。
  • speaker_mode: bool：是否输出为聊天消息（True）或纯文本（False），默认 True。
  • 说明：
    • speaker_mode=True 时返回 ChatPromptValue；
    • speaker_mode=False 时返回 StringPromptValue；
    • from_examples() 不支持，调用会抛出 NotImplementedError。

使用示例（来自文档）

# 由模板字符串创建
>>> template = LangchainPomlTemplate.from_template(
...     "Hello {{name}}!", speaker_mode=True
... )
>>> result = template.format(name="Alice")

# 由 POML 文件加载
>>> template = LangchainPomlTemplate.from_file(
...     "path/to/template.poml", speaker_mode=False
... )
>>> result = template.format(user_input="What is AI?")

---

MLflow 集成（poml.integration.mlflow）

功能介绍

• log_poml_call(name, prompt, context, stylesheet, result)：将一次完整的 poml 调用记录到 MLflow。

关键 API

• log_poml_call(name, prompt, context, stylesheet, result)
  • 说明："Log the entire poml call to mlflow."

文档示例

# 文档中的函数实现示例（节选）
@mlflow.trace
def poml(prompt, context, stylesheet):
    return result

prompt_registered = mlflow.genai.register_prompt(
    name=name,
    template=prompt,
    tags={"format": "poml", "source": "auto"},
)

poml(prompt, context, stylesheet)

---

Pydantic 集成（poml.integration.pydantic）

功能介绍

• NotGiven：用于区分"未提供实参"与显式传入 None 的哨兵单例。
• is_dataclass_like_type(typ)：判断给定类型是否可能使用了 @pydantic.dataclass。
• to_strict_json_schema(model)：将 Pydantic 模型转换为严格 JSON Schema，适配 OpenAI 的函数调用与响应格式（对象 additionalProperties: false，属性均为必填）。

关键 API

• NotGiven
• is_dataclass_like_type(typ) -> bool
• to_strict_json_schema(model) -> dict[str, Any]
  • 说明：
    • 接收 BaseModel 类或 TypeAdapter；
    • 输出严格 JSON Schema；
    • 非 BaseModel 类型在 Pydantic v1 下不支持；
    • 实现参考自 OpenAI Python SDK（文档内给出来源链接）。

使用示例（来自文档）

from pydantic import BaseModel, Field
from poml.integration.pydantic import to_strict_json_schema

class Query(BaseModel):
    name: str = Field(description="Query name")
    limit: int = Field(description="Result limit", default=10)

schema = to_strict_json_schema(Query)
# 返回一个严格 JSON Schema（additionalProperties: false）

---

Weave 集成（poml.integration.weave）

功能介绍

• log_poml_call(name, prompt, context, stylesheet, result)：将一次完整的 poml 调用记录到 Weave。

关键 API

• log_poml_call(name, prompt, context, stylesheet, result)
  • 说明："Log the entire poml call to weave."

文档示例

# 文档中的函数实现示例（节选）
@weave.op
def poml(prompt, context, stylesheet):
    return result

prompt_ref = weave.publish(prompt, name=name)
if context is not None:
    context_ref = weave.publish(context, name=name + ".context")
else:
    context_ref = context

if stylesheet is not None and stylesheet != "{}":
    stylesheet_ref = weave.publish(stylesheet, name=name + ".stylesheet")
else:
    stylesheet_ref = stylesheet

poml(prompt_ref, context_ref, stylesheet_ref)

---

总结

本文按官方 Integration 参考页面整理了五个 Python 集成模块的用途与核心 API/类，并给出了文档中的示例片段：

• 记录调用：agentops、mlflow、weave 的 log_poml_call(...)；
• 模板集成：langchain 的 LangchainPomlTemplate（支持 speaker 模式与结构化内容）；
• 模型到 Schema：pydantic 的 to_strict_json_schema(...) 及辅助类型/判断。

更多细节请参考官方文档页面：

• microsoft.github.io/poml/stable...