在应用中使用提示

在 MLflow 提示词注册表 (Prompt Registry) 中创建并版本化提示词后，接下来的关键步骤是将它们集成到您的 LLM 应用程序和 AI 代理中。本页面将指导您如何加载提示词、绑定变量、处理版本控制，并通过将提示词版本链接到已记录的 MLflow 模型来确保完整的血缘关系 (lineage)。

从注册表中加载提示词

在应用程序代码中访问已注册提示词的主要方式是使用 mlflow.genai.load_prompt() 函数。此函数会从注册表中检索特定的提示词版本（或由别名指向的版本）。

它使用一种特殊的 URI 格式：prompts:/<prompt_name>/<version_or_alias>。

• <prompt_name>：提示词在注册表中的唯一名称。
• <version_or_alias>：可以是具体的版本号（例如 1、2）或别名（例如 production、latest-dev）。

python

import mlflow

prompt_name = "my-sdk-prompt"

# Load the latest version of the prompt
mlflow.genai.load_prompt(name_or_uri=f"prompts:/{prompt_name}@latest")

# Load by specific version (assuming version 1 exists)
mlflow.genai.load_prompt(name_or_uri=f"prompts:/{prompt_name}/1")

# Load by alias (assuming an alias 'staging' points to a version of a prompt)
mlflow.genai.load_prompt(name_or_uri=f"prompts:/{prompt_name}@staging")

使用变量格式化提示词

加载提示词对象（即 Prompt 实例）后，您可以使用 prompt.format() 方法填充其模板变量。该方法接收关键字参数，其中键应与提示词模板中的变量名匹配（不带 {{ }} 大括号）。

python

import mlflow

# define a prompt template
prompt_template = """\
You are an expert AI assistant. Answer the user's question with clarity, accuracy, and conciseness.

## Question:
{{question}}

## Guidelines:
- Keep responses factual and to the point.
- If relevant, provide examples or step-by-step instructions.
- If the question is ambiguous, clarify before answering.

Respond below:
"""
prompt = mlflow.genai.register_prompt(
    name="ai_assistant_prompt",
    template=prompt_template,
    commit_message="Initial version of AI assistant",
)

question = "What is MLflow?"
response = (
    client.chat.completions
    .create(
        messages=[{"role": "user", "content": prompt.format(question=question)}],
        model="gpt-4o-mini",
        temperature=0.1,
        max_tokens=2000,
    )
    .choices[0]
    .message.content
)

与其他框架（LangChain、LlamaIndex）配合使用

MLflow 提示词使用 {{variable}} 双大括号语法进行模板化。其他一些流行框架（如 LangChain 和 LlamaIndex）通常期望使用单大括号语法（例如 {variable}）。为了促进无缝集成，MLflow 的 Prompt 对象提供了 prompt.to_single_brace_format() 方法。该方法返回转换为单大括号格式的提示词模板字符串，可供这些框架直接使用。

python

import mlflow
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

# Load registered prompt
prompt = mlflow.genai.load_prompt("prompts:/summarization-prompt/2")

# Create LangChain prompt object
langchain_prompt = ChatPromptTemplate.from_messages([
    (
        # IMPORTANT: Convert prompt template from double to single curly braces format
        "system",
        prompt.to_single_brace_format(),
    ),
    ("placeholder", "{messages}"),
])

# Define the LangChain chain
llm = ChatOpenAI()
chain = langchain_prompt | llm

# Invoke the chain
response = chain.invoke({"num_sentences": 1, "sentences": "This is a test sentence."})
print(response)

自动提示词链接

与追踪 (Trace) 链接

当您在追踪函数内从注册表加载提示词（通过 mlflow.genai.load_prompt()）时，MLflow 会自动跟踪正在使用的提示词，并与活动追踪建立链接，这些链接可在 MLflow UI 中查看。这使您可以即时了解提示词的使用情况，并比较您的代理在不同提示词版本下的表现。

python

from openai import OpenAI


@mlflow.trace
def question(name):
    # Load the prompt - this creates an automatic link to the trace
    prompt = mlflow.genai.load_prompt("prompts:/question@latest")
    client = OpenAI()

    messages = [{"role": "user", "content": prompt.format(name=name)}]

    response = client.chat.completions.create(
        model="gpt-5-mini",
        messages=messages,
    )
    return response.choices[0].message.content


question("1+1")  # The prompt is linked to the trace created for this call

与运行 (Run) 链接

同样，当您在 MLflow 运行期间（例如在 with mlflow.start_run(): 块内）从注册表加载提示词时，MLflow 会自动记录该运行中使用了哪些提示词版本。这种链接会出现在运行的元数据和 MLflow UI 中，从而便于跟踪提示词依赖关系，以实现可重现性和可审计性。

python

from openai import OpenAI

with mlflow.start_run():
    # Load the prompt - this creates an automatic link to the run
    prompt = mlflow.genai.load_prompt("prompts:/question@latest")
    client = OpenAI()

    messages = [{"role": "user", "content": prompt.format(name="1+1")}]

    response = client.chat.completions.create(
        model="gpt-5-mini",
        messages=messages,
    )
    response.choices[0].message.content

将提示词链接到已记录的模型以实现完整血缘关系

为了实现完全的可重现性和可追溯性，记录您的应用程序（或模型）使用了哪些特定提示词版本至关重要。当您将 LLM 应用程序或 AI 代理记录为 MLflow 模型（例如使用 mlflow.pyfunc.log_model()、mlflow.langchain.log_model() 等）时，应包含有关其使用的注册表提示词的信息。

MLflow 旨在促进这一点。当模型被记录，且该模型的代码通过 prompts:/ URI 使用 mlflow.genai.load_prompt() 加载提示词时，MLflow 可以自动将这些提示词依赖项记录为已记录模型元数据的一部分。

这种链接的好处

• 可重现性：了解模型版本所使用的确切提示词版本，使您能够精确重现其行为。
• 调试：如果模型版本开始表现异常，您可以轻松检查是否由底层提示词的更改（即使是通过别名更新）引起。
• 审计与治理：保留任何给定模型版本所使用提示词的清晰记录。
• 影响分析：了解如果某个特定提示词版本被发现存在问题，哪些模型可能会受到影响。