Opik Agent Optimizer 快速入门：10 分钟让提示词自动进化

如果你已经在用 Opik 做 LLM 应用的追踪和评估，那么下一步很自然就会想到：能不能让提示词和 Agent 自己变得更好？Opik Agent Optimizer 就是为这个目标准备的。它提供了一套 SDK，把"手工改提示词、反复跑测试、凭感觉判断好坏"的过程，变成可复用、可追踪、可分析的自动化优化流程。

这篇快速入门的目标很明确：从"hello world"到跑通第一次优化，时间控制在 10 分钟以内。前提是你已经有一个 Opik 账号，并且本地 Python 环境能正常使用。如果你之前走过 Opik 的主快速入门，也就是 tracing 加 evaluation 那套流程，那么这篇文章就是顺理成章的下一站。它会加上 opik-optimizer SDK，让你可以自动改进提示词和 Agent。当然，如果你更喜欢图形界面，也可以直接使用 Optimization Studio，那是另一条 UI 工作流。

为什么需要 Opik Agent Optimizer

提示词工程听起来简单，实际做起来却很磨人。写一个系统提示词，跑几条样本，发现回答不太对，改几个词，再跑一遍。样本一多，指标一复杂，人就容易迷失：到底是提示词变好了，还是这次只是运气好？不同版本之间怎么对比？失败模式藏在哪些样本里？如果全靠手动记录，很快就是一锅粥。

Opik Agent Optimizer 想解决的就是这些问题。它有三个比较实在的特点。

第一，生产级工作流。你可以直接复用在 Opik 里已经建好的数据集、评估指标和追踪记录，不需要重新搭一套体系。数据集是现成的，指标是现成的，trace 也是现成的。优化器跑出来的每一次尝试，都会进入同一套可观测性系统里，不会变成孤立的实验。

第二，多种优化策略。它支持 MetaPrompt、Hierarchical Reflective Prompt Optimizer（HRPO）、Evolutionary、GEPA 等算法，而且可以通过统一的 API 切换。今天想用元提示策略，明天想试试进化算法，不需要重写整个调用逻辑。对于不同任务，比如问答、分类、工具调用、多轮对话，适合的策略可能不一样，能快速切换就很有价值。

第三，深度分析。每一次 trial 都会记录到 Opik 里，你可以查看提示词、工具调用、失败模式。也就是说，优化器不只是给你一个"更好的提示词"，它还让你知道为什么变好了，哪些样本仍然有问题，下一轮该往哪个方向改。对于严肃的 LLM 应用来说，这种可解释性比单纯提升几个百分点更重要。

文档里给了一个时间估计：如果你已经配置好 Python 和 Opik API key，整个过程不超过 10 分钟。这个时间不算夸张，因为大部分基础设施------数据集、指标、追踪------都可以复用。真正要做的，就是装包、认证、写一小段优化代码，然后看结果。

开始之前需要准备什么

先把前置条件说清楚，免得中途卡住。

• Python 3.10 或更高版本。Opik Optimizer 用了一些较新的 Python 特性，版本太低会出问题。
• 一个 Opik 账号。没有账号的话，先去官网注册，拿到 API key。
• 能访问一个 OpenAI 兼容的 LLM，通过 LiteLLM 调用。也就是说，你需要有 OPENAI_API_KEY、ANTHROPIC_API_KEY 之类的环境变量。LiteLLM 的好处是统一了 100 多个提供商的接口，OpenAI、Anthropic、Gemini、Azure、Ollama 都能接。你不需要为每个提供商写不同的适配代码。

这里有一个容易混淆的点：优化器本身需要一个 LLM 来"改进提示词"，而被优化的提示词在运行时也需要一个 LLM 来"执行任务"。这两个模型可以相同，也可以不同。文档示例里都用了 openai/gpt-5-nano，但实际使用时，你完全可以让一个便宜的小模型负责优化，让一个更强的模型负责线上推理，或者反过来。关键是把两个角色分清楚。

第一步：安装与认证

安装命令很直接：

pip install --upgrade opik opik-optimizer
opik configure  # 粘贴你的 API key
export OPIK_PROJECT_NAME="optimization-quickstart"

pip install --upgrade 会同时更新 opik 和 opik-optimizer。前者是 Opik 的核心 SDK，后者是优化器。opik configure 会引导你输入 API key，并把配置写到本地。之后设置 OPIK_PROJECT_NAME 环境变量，这一步看起来不起眼，但很实用。它确保所有 trace、experiment 和 optimization run 都记录到同一个项目里，不需要在每次 SDK 调用时都传 project_name。项目名可以理解为一个工作区，把相关的东西放在一起，后面在 dashboard 里找起来方便。

如果你换了机器，或者 CI 环境里没有交互式终端，也可以直接复制 ~/.opik/config 文件，或者用环境变量传入 key。认证失败是新手常见问题，后面会专门说。

第二步：创建数据集和评估指标

优化不能凭空进行，得有"题目"和"评分标准"。数据集就是题目，指标就是评分标准。Opik 的 API 设计得比较顺手：

import opik
from opik.evaluation.metrics import LevenshteinRatio

client = opik.Opik()
dataset = client.get_or_create_dataset(name="agent-opt-quickstart")
dataset.insert([
    {"question": "What is Opik?", "answer": "Opik is an LLM observability and optimization platform."},
    {"question": "How do I reduce hallucinations?", "answer": "Use evaluations and prompt optimization to enforce grounding."},
])

def answer_quality(item, output):
    metric = LevenshteinRatio()
    return metric.score(reference=item["answer"], output=output)

这段代码做了几件事。opik.Opik() 创建客户端，get_or_create_dataset 按名字找数据集，找不到就新建。dataset.insert 插入两条样本，每条包含 question 和 answer。这里的 answer 是参考答案，不是模型输出。answer_quality 函数定义了评分逻辑：用 LevenshteinRatio 计算参考答案和模型输出之间的相似度。

LevenshteinRatio 只是一个示例，实际项目中你可能会用更复杂的指标，比如语义相似度、LLM 裁判、精确匹配、F1、工具调用正确率等。Opik 的评估体系支持自定义指标，所以不必被示例限制。关键是要有一个稳定、可重复的评分函数，优化器才能判断哪个提示词更好。

数据集也不需要很大。快速入门里只有两条样本，目的是跑通流程。真实场景中，几十到几百条代表性样本比较常见。样本要覆盖典型情况和边界情况，否则优化器可能过拟合到少数几个例子。

第三步：运行优化器

这是核心步骤。代码不长，但信息量不小：

from opik_optimizer import MetaPromptOptimizer, ChatPrompt

prompt = ChatPrompt(
    messages=[
        {"role": "system", "content": "You are a precise assistant."},
        {"role": "user", "content": "{question}"},
    ],
    model="openai/gpt-5-nano"  # The model your prompt runs on
)

optimizer = MetaPromptOptimizer(model="openai/gpt-5-nano")  # The model that improves your prompt
result = optimizer.optimize_prompt(
    prompt=prompt,
    dataset=dataset,
    metric=answer_quality,
    max_trials=3,
    n_samples=2,
)

result.display()

先看 ChatPrompt。它接收一个 messages 列表，里面是标准的聊天格式：system 消息设定角色，user 消息里用 {question} 占位。这个占位符会在运行时被数据集里的 question 字段替换。model 参数指定这个提示词在哪个模型上运行。换句话说，这是"被优化对象"的执行模型。

然后创建 MetaPromptOptimizer，它的 model 参数指定"优化器模型"，也就是负责生成和改进提示词的那个模型。文档里两个模型都用了 openai/gpt-5-nano，但正如前面说的，它们可以不同。MetaPrompt 策略的思路是让 LLM 根据当前提示词的表现，自动生成新的提示词变体，然后评估，再迭代。

optimize_prompt 的参数值得解释一下。prompt 是要优化的 ChatPrompt，dataset 是刚才建的数据集，metric 是评分函数。max_trials=3 表示最多尝试 3 轮，n_samples=2 表示每轮用 2 个样本评估。这两个数字在快速入门里很小，所以跑得快。生产环境中，trial 数和样本数会更大，但也要考虑成本和延迟。

运行结束后，result.display() 会在 notebook 或终端里展示优化结果，包括最佳提示词、得分变化等。这个过程背后，Opik 会把每一次 trial 都记录下来，包括用的提示词、模型输出、指标得分。这些记录就是后续分析的素材。

文档里还有一个 Tip：如果你用其他 LLM 提供商，优化器支持 OpenAI、Anthropic、Gemini、Azure、Ollama 以及 100 多个通过 LiteLLM 接入的提供商。具体配置可以参考"Configure LLM Providers"指南。这意味着你不需要被某一家绑定，切换提供商时只需要改模型名称和环境变量。

第四步：查看和分析结果

跑完优化后，结果不只是在终端里显示一下。你可以运行：

opik dashboard

或者直接打开 https://www.comet.com/opik。在左侧导航里找到 Evaluation → Optimization runs，然后选择最新的一次运行。这里可以看到优化进度图表、trial 表格，以及每个 trial 的 trace。

优化进度图表能直观地看出得分随 trial 的变化。如果曲线一直在上升，说明优化器在找到更好的提示词；如果很快平坦，可能说明当前策略不适合这个任务，或者数据集太小、指标不够敏感。trial 表格列出了每次尝试的提示词和得分，方便横向对比。per-trial traces 则深入到每次模型调用，能看到具体的输入输出、工具调用、错误信息。

这些信息对决定是否上线新提示词很关键。不要只看最高分。还要看稳定性：新提示词在多个样本上是否都表现良好？有没有在某类问题上变差？失败模式是什么？如果优化后的提示词只是记住了训练样本，换一批数据就崩，那就不值得上线。Opik 的 trace 分析能帮你发现这些问题。

常见的第一批问题

文档里列了三个常见问题，都很典型。

第一个：提示词必须是 ChatPrompt 对象。很多人习惯直接传字符串或字典，但优化器需要 ChatPrompt 结构。解决办法是从 opik_optimizer 导入 ChatPrompt，把 messages 列表包进去，再传给优化器。这个错误通常发生在从其他框架迁移过来的时候。

第二个：认证失败。重新运行 opik configure，确认账号有 Agent Optimizer 的访问权限。如果换了机器，复制 ~/.opik/config 文件，或者重新输入 key。有时候 API key 是对的，但项目名或工作区不对，也会报错。仔细看错误信息，通常能定位到具体原因。

第三个：LiteLLM 提供商错误。确保提供商密钥，比如 OPENAI_API_KEY，在运行脚本的同一个 shell 里导出。如果你在 IDE 里运行，可能环境变量没有继承终端配置。还要确认所选模型对当前 key 是启用的。有些模型需要申请权限，或者地区限制。LiteLLM 的报错有时候比较笼统，可以先用一个最简单的调用测试 key 是否有效。

接下来可以做什么

跑通快速入门后，有几条路可以继续深入。

如果你喜欢 notebook，可以启动 Quickstart notebook，里面把整个流程串起来，适合交互式实验。链接是 /development/optimization-runs/cookbooks/optimizer_introduction_cookbook。

如果你要解决实际问题，建议深入阅读"Define datasets"和"Define metrics"。数据集的质量和指标的设计，往往比优化算法本身更影响最终效果。一个糟糕的指标会让优化器朝着错误方向努力。一个覆盖不全的数据集会让优化结果过拟合。

还可以看"Optimization Algorithms overview"，了解不同策略的适用场景。MetaPrompt 适合通用提示词改进，HRPO 适合分层反思，Evolutionary 适合探索大面积搜索空间，GEPA 可能在某些任务上有独特优势。选对策略，能省下不少时间和 token。

最后，不要忘记 Opik 的核心优势：所有优化过程都是可追踪、可比较、可复现的。你可以把优化运行当成实验记录，和团队分享，和之前的版本对比。提示词不再是某个人的"祖传秘方"，而是有数据支撑、有迭代历史的工程资产。

从手工调参到自动优化，门槛没有想象中那么高。装两个包，配置好 key，准备一个小数据集和一个指标，跑一次 MetaPrompt，看看 dashboard 里的曲线。10 分钟之后，你对提示词优化的理解可能会发生一点变化。