opik-optimizer

Opik Optimizer

用途

设计、运行并解读 Opik Optimizer 工作流，用于优化提示词、工具和模型参数，同时确保数据集与指标的配置一致，并支持可复现的评估。

适用场景

当用户提出以下需求时，使用此技能：

• 选择并配置 Opik Optimizer 算法，用于提示词／Agent 优化。
• 编写基于 ChatPrompt 的优化运行和自定义指标函数。
• 使用工具（函数调用或 MCP）、指定的提示词角色或提示词片段进行优化。
• 使用 optimize_parameter 调优 LLM 调用参数。
• 比较优化器输出并解读 OptimizationResult。

工作流

1. 根据目标选择优化器策略（MetaPromptOptimizer、FewShotBayesianOptimizer、HRPO 等）。
2. 配置提示词、数据集和指标，并验证占位符与字段是否匹配。
3. 使用明确的控制参数（n_threads、n_samples、max_trials、seed）运行提示词、工具或参数优化。
4. 检查 OptimizationResult，并将分数变化与初始基线进行比较。
5. 总结建议、风险和后续实验。

输入

• 优化目标（提示词／工具／参数）和成功指标。
• 数据集来源和预期的 schema 字段。
• 模型／提供商限制和运行时限制。
• 可选的范围限制（optimize_prompts 片段、工具字段、项目名称）。

输出

• 优化器运行配置及其理由。
• 结果解读（score、initial_score、历史趋势）。
• 建议的后续更改和后续实验计划。

实现代码前，请使用此技能中的参考文件了解详情：

• references/algorithms.md
• references/prompt_agent_workflow.md
• references/example_patterns.md

Opik Optimizer 快速入门

1. 安装并导入：

pip install opik-optimizer

from opik_optimizer import ChatPrompt, MetaPromptOptimizer, HRPO, FewShotBayesianOptimizer
from opik_optimizer import datasets

2. 构建提示词和指标：

from opik.evaluation.metrics import LevenshteinRatio

prompt = ChatPrompt(
    system="You are a concise answerer.",
    user="{question}",
)

def metric(dataset_item: dict, output: str) -> float:
    return LevenshteinRatio().score(
        reference=dataset_item["answer"],
        output=output,
    ).value

3. 加载数据集并运行：

dataset = datasets.hotpot(count=30)

result = MetaPromptOptimizer(model="openai/gpt-5-nano").optimize_prompt(
    prompt=prompt,
    dataset=dataset,
    metric=metric,
    n_samples=20,
    max_trials=10,
)
result.display()

请遵循的核心工作流

1. 选择优化器类：
   • 少样本示例 + 贝叶斯选择：FewShotBayesianOptimizer
   • LLM 元推理：MetaPromptOptimizer
   • 遗传算法 + MOO／LLM 交叉：EvolutionaryOptimizer
   • 分层反思式诊断：HierarchicalReflectiveOptimizer（HRPO）
   • 基于帕累托的遗传策略：GepaOptimizer
   • 仅调优参数：ParameterOptimizer
2. 定义单个 ChatPrompt（或在多提示词场景下定义提示词字典）。
3. 提供来自 opik_optimizer.datasets 的数据集。
4. 提供指标可调用对象，其签名为 (dataset_item, llm_output) -> float（或返回 ScoreResult／ScoreResult 列表）。
5. 设置优化器控制参数（n_threads、n_samples、max_trials、seed 等）。
6. 运行以下其中一项：
   • 使用 optimize_prompt(...) 更改提示词／系统行为。
   • 使用 optimize_parameter(...) 调整模型调用超参数。
7. 检查 OptimizationResult（score、initial_score、history、optimization_id、get_optimized_parameters）。

必须遵守的关键执行细节

• 如果使用组织级可观测性，优先显式指定 project_name，以便进行 Opik 跟踪。
• 确保提示词中的占位符与数据集字段一致（例如 {question}）。
• 需要限制优化范围时，从 optimize_prompts="system" 或 "user" 开始。
• 确保 MetaPrompt／reasoning 调用中的 model 名称与帐户所用的提供商兼容。
• 验证多模态输入载荷时，仅保留非空内容片段。
• 对于小型数据集，请谨慎设置 n_samples 和 n_samples_strategy；若分配量超出数据集大小，系统会自动回退到使用完整数据集。

工具与基于片段的控制

• 可以通过 MCP/函数架构字段优化工具，而不只是修改提示词措辞。
• 如需精细更新文本，请使用 optimize_prompts 值以及 prompt_segments 中的辅助函数：
  • extract_prompt_segments(ChatPrompt) 用于检查稳定的片段 ID。
  • apply_segment_updates(ChatPrompt, updates) 用于执行确定性编辑。
• 工具优化与提示词优化不同。

可运行示例位于上游 Opik 仓库：

• https://github.com/comet-ml/opik/tree/main/sdks/opik_optimizer/src/opik_optimizer

如果需要本地可运行脚本，请将上游示例纳入 scripts/ 文件夹，并将引用保持在一层深。

应避免的常见错误

• 传入空数据集或不匹配的占位符名称。
• 将已弃用的构造函数参数 num_threads 与 n_threads 混用。
• 误以为工具优化与 Agent 函数调用优化相同。
• 运行 ParameterOptimizer.optimize_prompt（该方法会引发异常，不应使用）。

后续操作

• 如需深入了解行为和各类参数表：references/algorithms.md
• 如需了解准确的 optimize_prompt 签名、提示词、工具限制和结果用法：references/prompt_agent_workflow.md
• 如需了解模式示例和基于源代码的工作流：references/example_patterns.md

流程

stateDiagram-v2
    [*] --> SelectObjective
    SelectObjective --> ConfigurePromptOrTools: prompt, agent, or tool objective
    SelectObjective --> ConfigureParameters: parameter objective
    ConfigurePromptOrTools --> ValidateDatasetAndControls
    ConfigureParameters --> ValidateDatasetAndControls
    ValidateDatasetAndControls --> ReportBlocked: fields, metric, or limits invalid
    ValidateDatasetAndControls --> OptimizePrompt: prompt or tool strategy
    ValidateDatasetAndControls --> OptimizeParameter: ParameterOptimizer
    OptimizePrompt --> CompareBaseline
    OptimizeParameter --> CompareBaseline
    OptimizePrompt --> ReportBlocked: run fails
    OptimizeParameter --> ReportBlocked: run fails
    CompareBaseline --> ReportRecommendations
    ReportRecommendations --> [*]
    ReportBlocked --> [*]