opik

opik — オープンソースのLLMオブザーバビリティ、評価、最適化

Opik（Comet が開発）は、LLM アプリケーションのライフサイクル全体を効率化します。LLM 呼び出しやエージェントのアクティビティの詳細なトレース、LLM-as-a-judge による評価、実験管理、大規模な本番環境のモニタリング（1 日あたり 4,000 万件以上のトレース）に加え、Opik Agent Optimizer と Opik Guardrails を提供します。このスキルはルーティングを優先するラッパーです。適切なデプロイモードを選び、SDK を接続して、トレース → 評価 → モニタリング → 最適化のループを実行します。

このスキルを使用する場合

• ユーザーが Opik のインストールまたは設定を求めている場合（pip install opik、opik configure、./opik.sh）
• ユーザーが LLM 呼び出しやエージェントのトレースを求めている場合 — @opik.track またはフレームワーク統合（OpenAI、Anthropic、LangChain、LangGraph、LlamaIndex、CrewAI、DSPy、Haystack、Ollama、Bedrock、Vercel AI SDK、Pydantic AI など）を利用
• ユーザーが LLM-as-a-judge のメトリクスを求めている場合：ハルシネーション検出、モデレーション、回答の関連性、RAG のコンテキスト適合率／再現率
• ユーザーがデータセットと実験による評価、または CI/CD での PyTest 統合 LLM 評価を求めている場合
• ユーザーが本番環境の LLM モニタリングダッシュボード、オンライン評価ルール、プロンプトプレイグラウンドでの実験、エージェント／プロンプトの最適化、またはガードレールを求めている場合

このスキルを使用しない場合

• スタックが Opik ではなく LangSmith の場合 → langsmith を使用
• ユーザーが 汎用サービスのダッシュボード／アラート（LLM 以外のテレメトリ、稼働時間、インフラメトリクス）を必要としている場合 → monitoring-observability を使用
• ユーザーが LLM のトレース／評価の設定ではなく、オフラインのデータセット／KPI の解釈を求めている場合 → data-analysis を使用
• ユーザーがアプリ／コンテナのログを対象に根本原因のログフォレンジックを行っている場合 → log-analysis を使用

前提条件

要件	備考
Python 3.8+（SDK）	pip install opik または uv pip install opik
Docker + Docker Compose	./opik.sh を使ったローカルのセルフホストに限ります
Kubernetes + Helm	拡張性の高いセルフホスト型デプロイに限ります
Comet.com アカウント	セットアップ不要のクラウドオプションに限ります

手順

ステップ 1 — サーバーモードを選択する

モード	用途	方法
Comet.com クラウド（最も簡単）	すぐに開始したい場合、メンテナンス不要	無料アカウントを作成し、API キーとワークスペースを取得
Docker Compose（ローカル）	ローカルでの開発とテスト、完全な制御	git clone https://github.com/comet-ml/opik.git && cd opik && ./opik.sh → localhost:5173 の UI
Kubernetes / Helm	本番規模のセルフホスト	上流の Helm チャートガイド

Docker サービスプロファイル（開発シナリオ）：

./opik.sh              # full Opik suite (default)
./opik.sh --infra      # infrastructure only (databases, caches)
./opik.sh --backend    # infrastructure + backend services
./opik.sh --guardrails # enable guardrails with any profile
./opik.sh --help       # troubleshooting

Windows：powershell -ExecutionPolicy ByPass -c ".\opik.ps1"。

ステップ 2 — SDK をインストールして設定する

pip install opik        # or: uv pip install opik
opik configure          # prompts for server address (self-hosted) or API key + workspace (cloud)

または、コード内で設定します：

import opik
opik.configure(use_local=True)   # local self-hosted instance

TypeScript および Ruby（OpenTelemetry 経由）用の SDK も利用できます。詳しくはクライアントリファレンスドキュメントをご覧ください。

ステップ 3 — トレースを記録する

フレームワークがサポートされている場合は、ネイティブ統合を優先してください（利用可能な統合は 50 種類以上：ADK、AG2、Agno、Anthropic、Autogen、Bedrock、CrewAI、DSPy、Dify、Flowise、Gemini、Haystack、Instructor、LangChain、LangGraph、LiteLLM、LlamaIndex、Mastra、Ollama、OpenAI、OpenAI Agents、OpenRouter、OpenTelemetry、Pydantic AI、Ragas、Semantic Kernel、Smolagents、Spring AI、Vercel AI SDK、WatsonX など）。完全な一覧は references/commands.md をご覧ください。

任意のコードパスで使える代替手段は track デコレーターです（ネストに対応し、統合と組み合わせ可能）：

import opik

@opik.track
def my_llm_function(user_question: str) -> str:
    # Your LLM code here
    return "Hello"

SDK または UI から、フィードバックスコアでトレース／スパンに注釈を付けます。

ステップ 4 — LLM-as-a-judge メトリクスで評価する

from opik.evaluation.metrics import Hallucination

metric = Hallucination()
score = metric.score(
    input="What is the capital of France?",
    output="Paris",
    context=["France is a country in Europe."],
)
print(score)

組み込みの評価器には、ハルシネーション、モデレーション、回答の関連性、コンテキスト適合率／再現率があります。ヒューリスティックメトリクスとカスタムメトリクスにも対応しています。

ステップ 5 — データセット、実験、CI ゲート

• データセットを管理し、実験を実行して、開発中にプロンプト／モデルのバリエーションを比較します
• PyTest 統合を使って評価を CI/CD に組み込み、リグレッションがあればマージをブロックします
• プロンプトプレイグラウンドでプロンプト／モデルを反復的に改善します

ステップ 6 — 本番環境のモニタリングと最適化

• Opik は大規模な運用を想定して構築されています。1 日あたり 4,000 万件以上のトレースを取り込みます
• Opik ダッシュボードでフィードバックスコア、トレース数、トークン使用量を追跡します
• オンライン評価ルール（本番トラフィックに対する LLM-as-a-judge）を追加して、問題をリアルタイムで検出します
• Opik Agent Optimizer（専用 SDK）を使ってプロンプト／エージェントを改善し、安全な AI ポリシーには Opik Guardrails を利用します

ステップ 7 — jeo-skills と併用するプラグイン形式のインストール

このスキルフォルダーは、標準の jeo-skills フローを通じてプラグインとしてインストールできます。これにより、ラッパー、リファレンス、インストーラースクリプトがディスクに配置され、サポート対象のエージェントランタイムで利用できます。

# Project install (writes into .agents/skills/opik/)
npx skills add https://github.com/akillness/jeo-skills --skill opik

# Global install for every detected agent
npx skills add -g https://github.com/akillness/jeo-skills --skill opik

# Target specific agents
npx skills add -g https://github.com/akillness/jeo-skills --skill opik -a claude-code -a codex -y

このスキルには、SDK のインストール（uv → pip のフォールバック）と、オプションのローカルセルフホスティング（OPIK_INSTALL_MODE=local）に対応するワンショットインストーラーとして、scripts/install.sh も含まれています。

出力形式

ユーザーが opik にヘルプを求めた場合、簡潔な概要を返します。

# opik Routing Brief

## Scope
- Server mode: cloud | docker-local | kubernetes | undecided
- SDK: python | typescript | ruby-otel
- Lifecycle stage: tracing | evaluation | ci-gate | production-monitoring | optimization | guardrails

## Recommended next move
- install-sdk | opik-configure | start-local-server | wire-integration | add-judge-metric | create-dataset-experiment | enable-online-rules

## Why
- 2-3 bullets grounded in the user's packet

## Route-outs
- `langsmith` when the observability stack is LangSmith
- `monitoring-observability` for non-LLM dashboards/alerts
- `data-analysis` for offline KPI/metric interpretation

ベストプラクティス

1. Kubernetes ではなく、クラウドまたは ./opik.sh から始める — Helm は本番規模の運用向けです。ローカルの Docker Compose なら、トレースが機能するかどうかを数分で確認できます。
2. フレームワークがサポート一覧にある場合は、独自に @opik.track を実装するよりネイティブ統合を優先する — 統合機能はプロバイダーのメタデータ（トークン、モデル、レイテンシ）を自動で取得します。
3. セルフホストサーバーをアップグレードする前に変更履歴を確認する — たとえば、v1.7.0 では破壊的変更が導入されました。
4. 評価指標の判断にはコンテキストが必要です — Hallucination および RAG 指標は、渡した context に基づいてスコアを算出します。コンテキストが空だと、誤解を招くスコアになります。
5. 小規模で安定したデータセットを CI のゲートにする — PyTest 統合の実験は高速かつ決定論的であるべきです。大規模な一括実行は、スケジュール実行に回してください。
6. 本番環境でのチェックは、ライブトラフィックに対してオフライン実験を再実行するのではなく、オンライン評価ルールにする

参考資料

• 上流リポジトリ：https://github.com/comet-ml/opik
• ドキュメント：https://www.comet.com/docs/opik/
• クイックスタート：https://www.comet.com/docs/opik/quickstart/
• 統合機能の概要：https://www.comet.com/docs/opik/integrations/overview/
• 指標の概要：https://www.comet.com/docs/opik/evaluation/metrics/overview/
• セルフホスト（ローカル）：https://www.comet.com/docs/opik/self-host/local_deployment
• セルフホスト（Kubernetes）：https://www.comet.com/docs/opik/self-host/kubernetes/
• インストーラースクリプト：scripts/install.sh
• コマンドと統合機能のリファレンス：references/commands.md
• 関連スキル：../langsmith/SKILL.md、../monitoring-observability/SKILL.md、 ../data-analysis/SKILL.md、../log-analysis/SKILL.md
• ライセンス：Apache-2.0（上流の LICENSE を参照）