如果你已经开始用 Opik 追踪和评估 LLM 应用，那么接下来最想做的事情之一，大概就是让提示词自己变好。手工改提示词、反复跑测试、凭感觉判断哪个版本更强，这套流程不仅累，而且很难复现。Opik Agent Optimizer 就是为解决这个问题而生的。它把提示词优化变成一个可追踪、可比较、可迭代的工程流程。而今天要聊的这个 Notebook，就是带你走完从零到一的最佳入口。
这个 Notebook 的名字叫 Optimizer Introduction Cookbook ，副标题是"Quick example notebook using HotPotQA dataset"。它用一个经典的多跳问答数据集 HotPotQA，把 Opik Agent Optimizer 的完整工作流串了起来。你不需要在本地装任何东西，打开浏览器就能跑。所有步骤、代码和解释都在 Colab Notebook 里。官方文档里有一句话很准确：这个 Notebook 就是 Agent Optimization 导航里的 Quickstart notebook 入口。换句话说，如果你想快速感受一下优化器到底能做什么，从这里开始最省事。
这个 Notebook 能给你什么
先看官方列出的学习目标，我把它翻译成更直白的话：
- 学会安装和配置 Opik Agent Optimizer SDK。
- 学会设置 Opik Cloud（也就是 Comet 账号），让优化过程有地方记录和展示。
- 学会使用 HotPotQA 数据集，这是一个专门用来测试多跳问答能力的数据集。
- 学会定义评估指标和任务配置（task configs）。
- 学会运行
FewShotBayesianOptimizer，并看懂它给出的结果。 - 学会在 Opik UI 里可视化优化运行，观察每一次尝试的变化。
这六件事基本覆盖了提示优化的核心环节：环境、数据、指标、算法、结果分析、可视化。很多工具只教你调 API，但 Opik 这套流程更强调"可观测性"。优化不是黑盒，每一步都能看到。
准备工作：Opik Cloud 和 Colab
Notebook 提供了两个入口。首选是 Google Colab，点击那个徽章就能直接打开：
latex
https://colab.research.google.com/github/comet-ml/opik/blob/main/sdks/opik_optimizer/notebooks/OpikOptimizerIntro.ipynb如果你更喜欢在 GitHub 上看源码，也可以访问：
latex
https://github.com/comet-ml/opik/blob/main/sdks/opik_optimizer/notebooks/OpikOptimizerIntro.ipynbColab 的好处是零配置。你不需要在本地装 Python、配虚拟环境、折腾依赖。浏览器里直接运行，改代码、试参数都很方便。对于快速验证一个想法来说，这种低摩擦体验非常重要。当然，如果你要在生产环境里用，最终还是要把流程搬到自己的代码库里。但先用 Notebook 跑通逻辑，再迁移，会顺很多。
在开始之前，你需要一个 Opik Cloud 账号。Opik 是 Comet 旗下的产品，所以账号体系和 Comet 是打通的。注册之后拿到 API key，在 Notebook 里配置一下，后续所有 trace、experiment 和 optimization run 都会记录到你的账号里。这一步很关键，因为优化器不是跑完就完了，它的价值很大一部分在于历史记录和对比分析。没有云端记录，你就只能看到最后一次结果，没法回溯。
HotPotQA：为什么选它来演示
HotPotQA 是一个多跳问答数据集。什么叫多跳？简单说，回答问题需要不止一个信息片段，而且这些片段之间需要推理连接。比如问"某部电影的导演出生在哪个城市"，你可能先要找到电影，再找到导演，再找到导演的出生地。单跳问答可能只需要检索一个段落，多跳问答则要求模型把多个事实串起来。
这种任务对提示词非常敏感。提示词里有没有引导模型分步思考？有没有要求它先找证据再回答？有没有给出足够的示例？不同的提示词会导致完全不同的表现。所以 HotPotQA 很适合用来演示提示词优化：优化空间大，指标区分度也高。
而且 HotPotQA 在学术界和工业界都很常见，大家比较熟悉。用它做示例，你更容易把 Notebook 里的经验迁移到自己的任务上。你的任务可能不是多跳问答，但优化流程是相通的：准备数据、定义指标、选择优化器、跑实验、分析结果。
核心概念：指标、任务配置与优化器
在跑代码之前，有几个概念需要先弄清楚。
指标（Metric） 是优化的指南针。它告诉优化器什么样的输出算好。在 HotPotQA 里，常见的指标包括精确匹配（EM）、F1 分数，或者用 LLM 做裁判。Notebook 里会演示如何定义指标。指标设计得好不好，直接决定优化方向对不对。如果指标只奖励简短回答，模型可能会学会偷懒；如果指标太宽松，优化器就找不到改进空间。
任务配置（Task Config） 是把数据集、指标、模型和提示词组织在一起的结构。你可以把它理解为一个实验的完整定义：用哪个数据集、用哪个指标评分、用哪个模型执行、初始提示词是什么。优化器拿到任务配置后，才知道要优化什么、怎么评估。Notebook 里会展示如何构建 task config，这是连接数据和算法的桥梁。
FewShotBayesianOptimizer 是这次要用的优化器。名字有点长，拆开看就清楚了。"FewShot"指的是少样本，也就是在提示词里加入少量示例来引导模型。"Bayesian"指的是贝叶斯优化，一种在昂贵评估场景下常用的黑盒优化方法。它的核心思想是：根据已经尝试过的提示词和得分，建立一个概率模型，预测哪些新提示词可能更好，然后选择最有希望的点去尝试。这样不需要暴力遍历所有组合，就能在较少 trial 内找到不错的解。
为什么用这个优化器来演示？因为它很适合少样本提示词的场景。你不需要准备大量标注数据，也不需要理解复杂的梯度。它通过尝试不同的示例组合和提示词结构，逐步找到更优的方案。对于很多实际任务来说，这种"黑盒优化 + 少量样本"的思路既实用又容易上手。
实战流程：从加载数据到运行优化
Notebook 的结构很清晰，跟着走就行。大致会经历这几个阶段。
第一步，安装和导入。在 Colab 里，通常是一行 pip install opik opik-optimizer，然后导入必要的模块。配置 Opik 客户端，填入 API key 和项目名。项目名可以自定义，比如 hotpotqa-optimization。这样所有相关记录都会归到这个项目下，后面在 UI 里查找方便。
第二步，加载 HotPotQA 数据集。Notebook 会从某个来源读取数据，可能是 Hugging Face Datasets，也可能是 Opik 内置的数据集接口。数据会被分成训练集和验证集。训练集用来让优化器尝试不同的提示词，验证集用来评估最终效果。这里要注意数据泄露问题：优化器不能看到验证集的答案，否则得分会虚高。Notebook 通常会处理好这一点，但你自己在做项目时要特别小心。
第三步，定义指标函数。比如写一个 answer_quality 函数，接收样本和模型输出，返回一个分数。可以用精确匹配、F1，或者调用 LLM 做语义判断。如果指标计算成本高，优化速度会变慢。所以有时候会用轻量级指标做初步筛选，再用重指标做最终评估。
第四步，构建任务配置。把数据集、指标、模型、初始提示词打包。初始提示词不需要很完美，甚至可以很简单，比如"请回答以下问题"。优化器的任务就是在这个基础上改进。模型可以选择 OpenAI、Anthropic 等，通过 LiteLLM 接入。
第五步，创建 FewShotBayesianOptimizer。设置优化器模型（用来生成新提示词的模型）和执行模型（用来跑任务的模型）。这两个可以相同，也可以不同。然后调用 optimize_prompt，传入任务配置和 trial 数量。trial 越多，搜索越充分，但成本也越高。Notebook 里通常用比较小的数字，比如 5 到 10，方便快速跑完。
第六步，查看结果。优化器会返回最佳提示词和对应的得分。你可以直接在 Notebook 里打印出来，也可以调用 result.display() 查看摘要。但更推荐去 Opik UI 里看，因为那里有更丰富的可视化。
解读结果：不只看最高分
跑完优化后，最容易犯的错误是只看最高分。最高分当然重要，但它不是全部。你需要关注几个方面。
第一，得分变化曲线。在 Opik UI 的 Optimization runs 页面，你能看到每次 trial 的得分。如果曲线在前几轮快速上升，然后趋于平缓，说明优化器找到了不错的区域。如果曲线一直震荡，可能说明指标噪声太大，或者数据集太小。如果曲线一直不升，可能是初始提示词太差、优化器模型能力不足，或者任务本身不适合这种优化策略。
第二，最佳提示词的内容。看看优化器改了什么。是增加了分步思考的指令？还是补充了示例？还是调整了输出格式？理解这些变化，能帮你积累提示词工程的经验。有时候优化器会给出出人意料的改写，效果却很好。这正是自动化优化的魅力。
第三，失败样本。Opik 会记录每个 trial 的 trace，你可以点进去看模型在哪些问题上答错了。是检索错了？还是推理断了？还是格式不对？这些失败模式比总分更有信息量。如果优化后的提示词在某一类问题上仍然很差，你可能需要补充数据，或者调整指标。
第四，验证集表现。如果 Notebook 划分了验证集，一定要看最佳提示词在验证集上的得分。训练集得分高不代表泛化好。如果验证集得分明显低于训练集，说明过拟合了。这时候可以增加数据多样性，或者减少 trial 数量，或者换一种优化策略。
在 Opik UI 中可视化优化运行
Notebook 里的代码跑完后，打开 Opik 的 dashboard，进入 Evaluation → Optimization runs，找到你刚才的运行。这里有几个视图值得仔细看。
优化进度图：横轴是 trial，纵轴是得分。你能一眼看出优化是否有效。如果多条曲线（比如训练集和验证集）放在一起，还能对比泛化情况。
Trial 表格：列出了每次尝试的提示词、得分、耗时、token 消耗。你可以按得分排序，快速找到最佳 trial。也可以对比不同 trial 的提示词差异，看看哪些改动带来了提升。
Trace 详情：点进任意一个 trial，能看到每次模型调用的输入输出。对于 HotPotQA，你可以看到模型读了哪些段落、生成了什么推理链、最终答案是什么。如果模型调用了工具，也能看到工具调用的参数和返回。这些细节是调试和迭代的基础。
对比功能：Opik 支持把多个 optimization run 放在一起对比。比如你第一次用 FewShotBayesianOptimizer 跑了 5 个 trial，第二次换了指标又跑了 5 个 trial。你可以把两次运行并排看，判断哪个配置更好。这种实验管理能力，是手工调参很难做到的。
常见坑与实用建议
虽然 Notebook 已经尽量简化，但实际操作中还是会遇到一些问题。这里列几个常见的。
API key 配置错误。最常见的是环境变量没设置，或者 key 复制错了。在 Colab 里，有时候需要把 key 存到 Secrets 里，而不是直接写在代码中。如果报认证失败，先检查 key 是否有效，再检查项目名是否正确。
LiteLLM 模型名称写错 。不同提供商的模型名称格式不一样，比如 openai/gpt-4、anthropic/claude-3。写错了会报模型不存在。建议先在 LiteLLM 文档里确认一下。
数据集太大导致跑得慢。HotPotQA 完整版很大，Notebook 通常会采样一部分。如果你自己换数据集，也要注意控制规模。优化器需要反复评估，数据量太大会让每个 trial 都很慢。可以先在小数据集上验证流程，再逐步扩大。
指标计算太贵 。如果用 LLM 做裁判，每次评估都要调用一次模型，成本会很高。可以考虑用更便宜的模型做裁判，或者用规则指标做初步筛选。也可以减少 n_samples，用更少的样本评估每个 trial。
过拟合。小数据集上尤其容易过拟合。优化器可能会找到一组示例，恰好能答对训练集，但换一批问题就不行了。解决办法是划分验证集，并且关注验证集得分。如果验证集得分下降，即使训练集得分上升，也要警惕。
优化器模型太弱。如果优化器模型本身能力不足，它生成的提示词可能没什么改进。可以尝试换一个更强的模型来做优化，而执行模型保持便宜。或者换一种优化策略，比如 MetaPrompt 或 Evolutionary。
总结与延伸
这个 Notebook 的价值在于，它用 HotPotQA 这个具体例子，把 Opik Agent Optimizer 的完整流程串了起来。你学到的不仅是几个 API 调用，而是一套可复用的方法论：准备数据、定义指标、配置任务、选择优化器、运行实验、分析结果、可视化追踪。这套方法可以迁移到任何 LLM 任务上，无论是问答、摘要、分类还是工具调用。
如果你已经跑完了 Notebook，接下来可以尝试几件事。第一，换成你自己的数据集，看看优化器能不能带来提升。第二，试试不同的优化器，比如 MetaPrompt 或 HRPO，对比它们的效果。第三，调整指标，观察优化方向的变化。第四，把优化后的提示词部署到线上，用 Opik 继续追踪实际表现。
提示词优化不是一锤子买卖，而是一个持续迭代的过程。Opik 提供的可观测性，让这个过程变得透明、可比较、可积累。每一次优化运行都是一次实验记录，积累下来就是团队的宝贵资产。从 HotPotQA 开始，你迈出的是一小步，但掌握的方法可以走得很远。
官方文档里还有更多细节，比如"Define datasets"、"Define metrics"和"Optimization Algorithms overview"。当你需要深入某个环节时，可以去查阅。但最重要的是先跑起来。打开 Colab，点下运行按钮，看着优化曲线一点点上升，那种感觉比读十篇文章都实在。