用 Opik Prompt Library 管理提示词：版本、追踪与多轮对话的完整指南

如果你正在构建 AI Agent，大概率会遇到一个头疼的问题：提示词（Prompt）改得太频繁了。今天把系统提示改成"你是一个专业的客服助手"，明天又想加上"回答要简洁，不要超过三句话"。改来改去，最后连自己都不记得哪个版本效果最好，更别提复现某次线上运行的精确提示了。

Opik 的 Prompt Library 就是为解决这类问题而生的。它让你把提示词从代码库里抽出来，放在一个独立的地方管理，每次修改自动生成新版本，并且能把运行时的提示词版本和 Trace 关联起来。换句话说，你不仅能知道 Agent 当时说了什么，还能知道它为什么这么说------因为你可以精确回溯到那一版提示词。

这篇文章会从实际使用角度出发，带你了解 Opik Prompt Library 的核心能力：如何把它接入你的代码、如何创建和获取提示词、如何选择版本、如何处理多轮对话的 Chat Prompt，以及如何借助 AI 编码助手让整个流程更顺畅。文中会给出 Python 和 TypeScript 两套示例，方便你直接对照自己的技术栈。

为什么需要 Prompt Library

在传统开发里，提示词往往直接写在代码里，比如一个字符串常量，或者拼接在函数内部。这样做短期内没问题，但一旦提示词需要频繁调整，就会暴露几个痛点：

第一，版本混乱。每次修改提示词都会产生一次代码提交，但代码提交里可能混杂了其他逻辑改动，很难单独追踪提示词的变化历史。第二，无法关联运行结果。线上某次回答质量下降，你想知道当时用的是哪版提示词，只能靠猜或者翻 Git 记录。第三，多项目复用困难。两个 Agent 可能都需要一个"通用助手"提示词，但写在各自代码里，改一处就得同步改两处。

Opik Prompt Library 的思路很直接：把提示词当作一种可版本化的资源，放在 Opik 平台上管理。你的代码在运行时去"拉取"指定版本的提示词，然后渲染成最终文本。这样，提示词的修改不需要重新部署代码，而且每次拉取都会被记录，自动和 Trace 绑定。

官方文档里有一张截图，展示了 Prompt Library 页面上按版本列出的提示词。你可以看到每个版本的内容、创建时间，以及它被哪些 Trace 使用过。这种透明度，对于调试和迭代来说非常关键。

把 Prompt Library 接入你的代码

接入方式有两种：一种是借助 AI 集成，让编码助手帮你自动完成；另一种是手动集成，自己写几行代码。两种方式各有适用场景，下面分别来说。

方式一：AI 集成

如果你平时用 Claude Code、Codex、Cursor、OpenCode 这类编码助手，Opik 提供了一个技能（Skill）来简化接入过程。你只需要在终端运行：

bash 复制代码

uvx opik mcp configure

这条命令会安装 Opik 技能，并连接 Opik MCP 服务器。它依赖 [uv](https://docs.astral.sh/uv/)，所以确保你的环境里已经装好了 uv。

安装完成后，你可以在编码助手里输入这样一句话：

plain 复制代码

Version my prompts in Opik using the /opik-instrument command.

翻译过来就是："用 /opik-instrument 命令把我的提示词在 Opik 里做版本管理。" 编码助手会自动识别你的代码结构，帮你把提示词推送到 Opik，并在运行时改为从 Opik 获取。这个技能兼容所有主流编码助手，包括 Claude Code、Codex、Cursor、OpenCode 等。

对于不想手动改代码的团队来说，这种方式省时省力，而且能保证接入方式符合 Opik 的最佳实践。

方式二：手动集成

手动集成分为两步：先创建（推送）提示词，然后在运行时获取。创建操作通常只需要做一次，或者在你希望从代码里生成新版本时做。获取操作则每次运行 Agent 时都会执行。

第一步：定义并推送你的第一个提示词

假设你有一个系统提示词，内容如下：

plain 复制代码

You are a helpful assistant specializing in {{domain}}.

其中 {``{domain}} 是一个占位符，运行时会被替换成具体领域，比如"customer support"。在 Python 中，你可以这样把它推送到 Opik：

python 复制代码

import opik

client = opik.Opik()

client.create_prompt(
    name="system_prompt",
    prompt="You are a helpful assistant specializing in {{domain}}.",
    project_name="my-agent",
)

TypeScript 版本类似：

typescript 复制代码

import { Opik } from "opik";

const client = new Opik();

await client.createPrompt({
  name: "system_prompt",
  prompt: "You are a helpful assistant specializing in {{domain}}.",
  projectName: "my-agent",
});

这里有几个细节值得注意。name 是提示词的名称，同一个项目下可以有很多提示词。project_name（TypeScript 里是 projectName）指定了项目作用域。官方特别提醒：提示词是项目作用域的 。也就是说，两个不同的 Agent 可以在各自项目里使用相同的提示词名称，互不干扰。所以无论什么时候，都建议显式传入 project_name / projectName。

推送成功后，Opik 会自动为这个提示词创建第一个版本，通常标记为 v1。之后每次调用 create_prompt 并传入相同名称，就会生成新版本。

第二步：在运行时获取提示词

创建好之后，你的 Agent 在运行时需要拉取提示词，并用实际值渲染。Python 中通常这样写：

python 复制代码

import opik

client = opik.Opik()

@opik.track(project_name="my-agent")
def run_agent(user_input: str):
    prompt = client.get_prompt(
        name="system_prompt",
        project_name="my-agent",
    )

    system_prompt = prompt.format(domain="customer support")

    response = call_llm(
        model="gpt-4o-mini",
        system_prompt=system_prompt,
        user_input=user_input,
    )
    return response

TypeScript 版本：

typescript 复制代码

import { Opik, track } from "opik";

const client = new Opik();

const runAgent = track(
  { name: "run_agent", projectName: "my-agent" },
  async (userInput: string) => {
    const prompt = await client.getPrompt({
      name: "system_prompt",
      projectName: "my-agent",
    });

    const systemPrompt = prompt?.format({ domain: "customer support" });

    const response = await callLlm({
      model: "gpt-4o-mini",
      systemPrompt,
      userInput,
    });
    return response;
  },
);

注意 Python 里用了 @opik.track(project_name="my-agent") 装饰器，TypeScript 里用了 track() 包裹函数。官方提示：在 tracked 函数内部调用 get_prompt / getPrompt，Opik 会自动把提示词版本和 Trace 关联起来。 这意味着你不需要手动记录"这次运行用了哪个版本的提示词"，Opik 会帮你做好。当你在 Opik 界面上查看某条 Trace 时，可以直接看到它使用的提示词版本，甚至能点进去查看完整内容。

这个关联能力是 Prompt Library 最有价值的地方之一。它让"提示词迭代"和"效果评估"形成了闭环：你可以修改提示词、发布新版本、运行 Agent、查看 Trace，然后对比不同版本在相同输入下的表现。如果发现新版本效果变差，可以一键回滚到旧版本，或者直接指定旧版本运行。

如何选择提示词版本

默认情况下，get_prompt / getPrompt 会返回最近创建的版本。这对希望 Agent 自动获取最新提示词编辑的场景非常有用------你不需要重新部署代码，只要在 Opik 界面上改一下提示词，下一次运行就会生效。

但有时候你需要固定版本。比如你在复现一次过去的运行，或者在做 A/B 对比，这时候就要显式传入 version 参数。Python 示例：

python 复制代码

# 获取指定版本
v3 = client.get_prompt(name="system_prompt", version="v3", project_name="my-agent")

# 获取最新版本（省略 version）
latest = client.get_prompt(name="system_prompt", project_name="my-agent")

TypeScript 示例：

typescript 复制代码

// 获取指定版本
const v3 = await client.getPrompt({
  name: "system_prompt",
  version: "v3",
  projectName: "my-agent",
});

// 获取最新版本（省略 version）
const latest = await client.getPrompt({
  name: "system_prompt",
  projectName: "my-agent",
});

版本名称遵循 v<N> 格式，比如 v1、v2、v3。你可以把它理解成 Git 里的 tag，只不过这里是自动递增的。选择哪种方式，取决于你的使用场景：

**省略 **version：适合生产环境希望自动获取最新提示词的场景。每次你调整提示词，Agent 下次运行就会用新的，无需发版。
**指定 **"v3"：适合需要稳定复现的场景。比如你发现 v3 在某个数据集上表现最好，就可以在评估脚本里固定用 v3，避免新版本干扰对比结果。

这种灵活性让 Prompt Library 既能支持快速迭代，又能支持严谨的实验管理。

Chat prompts：多轮对话的提示词管理

前面的例子都是文本提示词（Text Prompt），适合单轮任务。但很多 Agent 需要多轮对话，涉及 system、user、assistant 三种角色。Opik 为此提供了 Chat Prompt，对应的创建和获取方法分别是 create_chat_prompt / createChatPrompt 和 get_chat_prompt / getChatPrompt。

Python 创建示例：

python 复制代码

client.create_chat_prompt(
    name="support_assistant",
    messages=[
        {"role": "system", "content": "You are a helpful support agent for {{company}}."},
        {"role": "user", "content": "{{user_query}}"},
    ],
    project_name="my-agent",
)

TypeScript 创建示例：

typescript 复制代码

await client.createChatPrompt({
  name: "support_assistant",
  messages: [
    { role: "system", content: "You are a helpful support agent for {{company}}." },
    { role: "user", content: "{{user_query}}" },
  ],
  projectName: "my-agent",
});

获取和格式化时，Python 的写法略有不同，需要用 variables 参数传入变量字典：

python 复制代码

chat_prompt = client.get_chat_prompt(
    name="support_assistant",
    version="v3",
    project_name="my-agent",
)

messages = chat_prompt.format(
    variables={"company": "Acme", "user_query": "How do I reset my password?"},
)

TypeScript 则直接传对象：

typescript 复制代码

const chatPrompt = await client.getChatPrompt({
  name: "support_assistant",
  version: "v3",
  projectName: "my-agent",
});

const messages = chatPrompt?.format({
  company: "Acme",
  user_query: "How do I reset my password?",
});

Chat Prompt 的好处是，它把多轮对话的结构也纳入了版本管理。你可以随时调整 system 消息、增删 few-shot 示例，而不用改动代码。官方文档还提到，关于文本提示词和 Chat 提示词的更详细对比、多模态内容以及模板引擎的支持，可以参考 Text and chat prompts 页面。如果你正在构建复杂的对话式 Agent，建议深入阅读。

推荐：让 AI 编码助手帮你管理提示词

如果你已经在用 AI 编码助手，Opik 官方给出了一个非常推荐的工作流。只需要一条命令：

bash 复制代码

opik configure

这条命令会同时安装 MCP 服务器和 Opik 技能。之后，你的编码助手就能在编辑提示词的同时，自动把它们版本化到 Opik，并且还能评估每次改动是否真的有效------而不是靠肉眼判断。

官方给了一个示例提示，你可以直接丢给编码助手：

"Rewrite this system prompt to cut hallucinations, save each attempt to the Opik prompt library, and evaluate every version against my dataset so we can see which one wins."

翻译过来就是："重写这个系统提示词以减少幻觉，把每次尝试都保存到 Opik 提示词库，并针对我的数据集评估每个版本，看看哪个效果最好。"

这个流程把提示词工程从"手工试错"变成了"可度量、可回溯"的工程实践。你不再需要手动记录每次改了什么，也不用担心忘记哪个版本效果更好。Opik 会帮你保存所有版本，评估结果也会和版本关联，最终你能用数据说话，选出最优提示词。

小结

Opik Prompt Library 解决的是 AI Agent 开发中一个非常实际的问题：提示词变化快，但缺少版本管理和运行关联。通过把提示词外置到 Opik，你可以：

在代码之外管理提示词，修改后无需重新部署；
每次修改自动生成新版本，历史可追溯；
在运行时获取指定版本或最新版本；
通过 tracked 函数自动把提示词版本和 Trace 关联；
支持文本提示词和 Chat 提示词，覆盖单轮和多轮场景；
结合 AI 编码助手，实现自动化版本管理和效果评估。

无论你是手动集成，还是让编码助手代劳，核心思路都是一致的：让提示词成为可管理、可观测、可复现的资源。对于任何认真对待 AI Agent 迭代的团队来说，这都是一项值得投入的基础设施。