opik

Opik SDK リファレンス

Opik は、オープンソースの LLM オブザーバビリティプラットフォームです。このスキルは SDK のリファレンスです。コードベースに段階的に計測を追加する（フレームワークを検出し、設定を追加し、トレースを出力して検証する）には、タスクに特化した opik-instrument スキルを使用してください。

コアコンセプト

トレースは、1 つの実行経路（1 つのリクエスト → 1 つのレスポンス）です。スパンはその内部の処理で、階層を形成します。

スパンの種類 — 有効な値はこれだけです

種類	用途
general	オーケストレーション、エージェントのエントリーポイント
llm	モデル呼び出し
tool	ツール、検索、API／DB 呼び出し
guardrail	安全性／検証チェック

retrieval やその他の値は使用しないでください。

Python — トレーシング

import opik

@opik.track(name="agent", type="general")
def agent(query: str) -> str:
    return generate(retrieve(query))

@opik.track(type="tool")
def retrieve(query): ...

@opik.track(type="llm")
def generate(ctx): ...

opik.flush_tracker()   # required in scripts

TypeScript — トレーシング

import { Opik } from "opik";
const client = new Opik({ projectName: "my-project" });

const trace = client.trace({ name: "agent", input: { query } });
const span = trace.span({ name: "llm-call", type: "llm" });
span.end({ output });
trace.end({ output });
await client.flush();

フレームワーク連携

手動の @opik.track よりも連携機能を優先してください。連携機能はトークン、モデル、コストを自動的に取得します。パターンの全一覧は references/integrations.md を参照してください。

• クライアントのラップ — track_openai(OpenAI())、track_anthropic(...)
• グローバル有効化 — track_crewai(crew=crew)
• コールバック — dspy.configure(callbacks=[OpikCallback()])
• トレーサー — LangChain／LangGraph／LlamaIndex 用の OpikTracer()
• エージェント固有 — track_adk_agent_recursive(agent, OpikTracer())

@opik.track 内での LiteLLM（よくある落とし穴）

コードで litellm を使用し、さらに @opik.track を追加する場合は、すべての completion 呼び出しで current_span_data をメタデータ経由で渡してください。そうしないと、OpikLogger はスパンの下にネストされたトレースではなく、孤立したトップレベルのトレースを出力します。

from opik.opik_context import get_current_span_data

@opik.track
def call_llm(messages):
    return litellm.completion(
        model="gpt-4o", messages=messages,
        metadata={"opik": {"current_span_data": get_current_span_data()}},
    )

スレッド（会話）

thread_id を使ってターンをグループ化します。1 ターンは 1 つのトレースで、同じ thread_id は 1 つのスレッドになります。チャットや複数ターンの会話で使用し、単発の場合は省略してください。

@opik.track(entrypoint=True)
def handle(session_id: str, message: str) -> str:
    opik.update_current_trace(thread_id=session_id)
    return reply(message)

プロンプトライブラリ

client.get_prompt／create_prompt でプロンプトをバージョン管理します（チャット用のバリエーションは get_chat_prompt／create_chat_prompt）。モデルと temperature は、テキストとともにバージョン管理されるよう、プロンプトの metadata に保存してください。バージョンをトレースに紐付けるには、@opik.track 関数の内部で get_prompt を呼び出してください。

@opik.track(entrypoint=True)
def run(question: str) -> str:
    p = client.get_prompt(name="system") or client.create_prompt(
        name="system",
        prompt="You help with {{product}}.",
        metadata={"model": "gpt-4o", "temperature": 0.7},
    )
    return llm(p.format(product="Opik"), model=p.metadata["model"])

プロジェクトの状況を確認する

MCP を接続したら、トレースではなくプロジェクトから始めてください。

read("project", "<project name or id>")

1 回の呼び出しで、過去 7 日間とその前の 7 日間を比較した結果が返されます。トレース数、エラー率、平均所要時間、合計コスト（SDK トラフィックのみ。Logs ページの 4 つのカードに表示される内容）に加え、プロジェクトで実際に記録されているスコア名と使用状況キー、および最新の実験、データセット、プロンプトバージョン、最適化実行も確認できます。since／until で別の期間を指定できます。UI の初期表示で使用されるのは since="30d" です。期間内にトレースがない場合、レートや平均は 0 ではなく null になります。サンプルがない場合のレートは定義できず、「エラー率 0％」という情報を見た人がそれに基づいて行動する可能性があるためです。

次に、変化を言い換えるのではなく、その原因を特定します。

list("project_metric", project_name="<project>", metric_type="trace_cost")
list("project_metric", project_name="<project>", metric_type="span_count",
     breakdown="model", since="30d")

行はレコードではなく時間の区切りです。interval は hourly／daily／weekly／total で、page／size／sort は適用されません。schema("list.project_metric") では、指標の一覧、それぞれの内容、各指標で使用できるグループ化を確認できます。7 つの指標はグループ化を受け付けません。概要で返されるスコア名がフィルタリングに適した項目で、残りは list("score_name", project_name=…) で確認できます。

トレースの検索

ホスト型 MCP の list ツールと、SDK の search_traces / search_spans / search_threads の両方で、同じフィルター文法 OQL を使用します。

<field>[.<key>] <op> <value> [AND ...]
ops: = != > >= < <= contains not_contains starts_with ends_with is_empty is_not_empty in not_in

文字列は二重引用符で囲み、数値はそのまま記述します。duration の単位はミリ秒です。日付はタイムゾーン付きの ISO-8601 形式の日時（"2026-09-08T10:00:00Z"）で指定します。スコアと辞書ではキーを指定します。例：feedback_scores.accuracy < 0.5、 metadata.environment = "prod"。接続詞として使用できるのは AND のみです。

error_info is_not_empty AND duration > 5000
type = "llm" AND usage.total_tokens > 10000            # spans
feedback_scores.hallucination > 0.5 AND start_time >= "2026-09-08T00:00:00Z"

MCP に接続している場合は、list を優先してください。並べ替え（sort="duration desc"）、期間指定（since="1h"、"7d"）、フリーテキスト検索（search="order-42"）も行えます。

list(entity_type="trace", project_name="<project>", since="1h",
     filters="error_info is_not_empty", sort="duration desc")

トレース、スパン、スレッドのリストでは、source を指定しない限り source = "sdk" が追加されるため、評価器、プレイグラウンド、実験のトレースに煩わされることはありません。フィルターが拒否された場合は、修正方法が返されます。schema("list.trace")（または list.span、list.thread、list.experiment）に、フィールドと演算子の完全なリファレンスがあります。

MCP を使用しない場合は、同じ文字列を SDK に渡します。

client.search_traces(project_name="<project>", filter_string="error_info is_not_empty")

アンチパターン

アンチパターン	修正方法
スパンの型が retrieval / カスタム	tool（または general）を使用します
@opik.track の外で get_prompt を呼び出す	内部で取得します。そうしないとトレースへのリンクが作成されません
非推奨の opik.Prompt / opik.Config	client.get_prompt / 設定ファイルを使用します
current_span_data を指定せずに litellm を使用する	渡してください。そうしないとトレースが孤立します
スクリプトで flush を呼び出さない	opik.flush_tracker() / await client.flush() を呼び出します

リファレンス

トピック	ファイル
Python SDK（非同期、分散、コンテキスト）	references/tracing-python.md
TypeScript SDK	references/tracing-typescript.md
REST API	references/tracing-rest-api.md
すべてのインテグレーション	references/integrations.md
コア概念（トレース、スパン、スレッド）	references/observability.md
ベストプラクティス（ライフサイクル、モニタリング、アンチパターン）	references/best-practices.md
エージェントのアーキテクチャ、信頼性、セキュリティ	references/agent-patterns.md
本番環境のモニタリング、アラート、ガードレール	references/production.md
評価データセットとテストスイート（リファレンス）	references/evaluation-datasets.md、references/evaluation-test-suites.md

評価を構築して実行するには、opik-evaluate スキルを使用します。リポジトリの計装と設定には、opik-instrument スキルを使用します。