opik-optimizer

Opik Optimizer

目的

プロンプト、ツール、モデルパラメーター向けの Opik Optimizer ワークフローを設計、実行、解釈します。データセットとメトリクスの一貫した連携により、再現可能な評価を実現します。

使用する場面

次のような依頼には、このスキルを使用します。

• プロンプト／エージェントの最適化に向けた Opik Optimizer アルゴリズムの選定と設定。
• ChatPrompt ベースの最適化実行や、カスタムメトリクス関数の作成。
• ツール（関数呼び出しまたは MCP）、選択したプロンプトのロール、またはプロンプトのセグメントを使った最適化。
• optimize_parameter による LLM 呼び出しパラメーターの調整。
• オプティマイザーの出力比較と、OptimizationResult の解釈。

ワークフロー

1. 最適化の目標に応じて、最適化戦略（MetaPromptOptimizer、FewShotBayesianOptimizer、HRPO など）を選択します。
2. プロンプト、データセット、メトリクスの連携を構築し、プレースホルダーとフィールドの対応を検証します。
3. 明示的な制御値（n_threads、n_samples、max_trials、seed）を指定して、プロンプト、ツール、またはパラメーターの最適化を実行します。
4. OptimizationResult を確認し、初期ベースラインとのスコア差を比較します。
5. 推奨事項、リスク、次に実施する実験をまとめます。

入力

• 最適化の対象（プロンプト／ツール／パラメーター）と成功指標。
• データセットのソースと想定されるスキーマフィールド。
• モデル／プロバイダーの制約と実行時の制限。
• 任意のスコープ制約（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）を確認します。

実行時に守るべき重要事項

• 組織レベルのオブザーバビリティを使用する場合は、Opik のトラッキングで project_name を明示的に指定してください。
• プロンプト内のプレースホルダーとデータセットのフィールド（例：{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/ フォルダーにベンダーとして取り込み、参照先が 1 階層の深さに収まるようにしてください。

よくある間違い

• 空のデータセットや、プレースホルダー名が一致しないデータセットを渡す。
• 非推奨のコンストラクター引数 num_threads と n_threads を混在させる。
• ツールの最適化が、エージェントの関数呼び出し最適化と同じだと考える。
• 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 --> [*]