logfire-evals

Logfire で AI コードを評価する

仕組み

Python の pydantic_evals と Node.js の logfire/evals は、ケースに対してタスクを実行し、評価器を適用して、レポートを返します。有効な Logfire または OpenTelemetry プロバイダーがあれば、このスキルで設定していなくても、入力と出力がエクスポートされることがあります。意図的にアップロードするには、Python では logfire.configure()、Node.js では設定済みのエクスポーターが必要です。

スパンベースの評価器は、タスクの OpenTelemetry スパンツリーを調べます。Logfire のインストルメンテーションが機能していない場合、Python は「No span tree available」と報告します。Node.js の HasMatchingSpan は、評価結果をまったく返さないことがあります。いずれのシグナルもエージェントについての証拠ではなく、セットアップの失敗として扱ってください。

ステップ 1：まず既存の Braintrust スイートを確認する

何よりも先に、手早く確認してください。このリポジトリには既存の Braintrust スイートがありますか？ソース内に実際の Eval(...) 呼び出し、または from braintrust import Eval がある場合を指します。実際の使用箇所がなく、依存関係に braintrust が記載されているだけの場合は該当しません。この方法ではCLI 認証は一切不要です。このためにステップ 2 を実行しないでください。互換エンドポイントについて文書化されているのは Logfire Cloud の US と EU のみです。それ以外の指定されたオリジンでは、ネイティブ評価方法を使用してください。

既存の Eval() コード（Python braintrust>=0.30.1／TypeScript braintrust>=3.24.0 — 検証済みバージョン）をそのまま使用し、環境変数のみを変更して、次回の実行先を Logfire に切り替えます。pydantic_evals は関与しません。

export BRAINTRUST_APP_URL="https://logfire-us.pydantic.dev/v1/braintrust"  # EU: logfire-eu.pydantic.dev
export BRAINTRUST_API_KEY="<logfire-project-api-key>"                     # Settings -> API Keys
unset BRAINTRUST_API_URL BRAINTRUST_PROXY_URL  # these override the endpoint above if set — the #1 "it still hit Braintrust" cause

宛先プロジェクトの API キーには、project:write_otlp と project:read_datasets が必要です。SDK は実行結果を書き込んだ後、概要のために実験メタデータを読み取ります。取り込み専用の書き込みトークンでは 403 エラーになります。

この互換性プレビューは、インライン／呼び出し可能なデータ、ローカルタスクと採点器、複数のスコア、名前ごとに 1 つのラベル、通常の概要確定処理に対応しています。Braintrust ホストのリソース、BTQL、モデルプロキシ、サーバー側の採点、確定後のフィードバックは対象外です。Rust、summarize_scores=False、および比較を伴わない手動の flush() では、投影に必要な概要は要求されません。対応範囲と概念の対応付けの全容を参照してください。

ステップ 5（検証）に進んでください。SDK が出力する結果 URL も Logfire で直接開けます。また、この方法ではここに記載されている他の手順（認証、データセットの定義）は適用されません。

**既存の Braintrust スイートがない場合は、今すぐステップ 2 に進んでください。**ステップ 3 で詳しく特定する前に実施します。この時点以降の手順では、関数／エージェントやデータセットの形式を知る必要はありません。

ステップ 2：実行に Logfire が必要な場合は認証する

スパン評価器を使用せず、明示的にローカルのみで実行する場合は、アプリケーションのテレメトリーを事前に読み込まず、インポートもしない新しいプロセスを使用してください。Python の logfire.configure() と、Node.js のエクスポーターの初期化は省略します。タスクがエクスポーターを設定し、無効化する方法が文書化されていない場合は、ローカルのみで実行できると主張せずに中止してください。アップロード、ホスト型データセット、スパン評価器には、対象のプロジェクトへの Logfire 認証が必要です。

Logfire を使用する実行では、認証して対象のプロジェクトを正確に選択するに従って、指定された Logfire URL から CLI の対象を特定し、検証済みの CLI パスを使って対象を指定した whoami チェックを実行してください。uv を使用しない JS／TS プロジェクトでは、通常の npx ではなく、外部プレフィックスの npm フォールバックを使用してください。通常の npx では、リポジトリ内のローカルバイナリが実行される場合があります。チェックで正しいプロジェクトと解決済みの --region または --base-url の対象がすでに示されている場合は、ステップ 3 に進んでください。そうでない場合は、該当ページに記載された認証とプロジェクト選択の手順をすべて続けてください。この CLI の手順は logfire.configure() 用です。ステップ 3 のホスト型データセット操作では、スコープの異なる別の API キーを使用します。

ステップ 3: 評価対象を特定する

実際のタスクとデータセットを特定します。リポジトリのパッケージ、テスト、依存関係の規約に従います。最初の評価では、テスト、スキーマ、サンプル、または合成フィクスチャから3〜5件のケースを選び、定義された動作を決定論的にチェックすることを優先します。サンプルが適合しない場合はコピーせず、評価フレームワークを置き換えたり、無関係なコードをリファクタリングしたりしないでください。実行可能なタスクや安全な期待動作がない場合は、どちらも作り上げず、焦点を絞った質問を1つしてください。

• コード内データセット: pydantic_evals を使う Python モジュール、または logfire/evals を使う Node.js モジュールです。エージェント主導のワークフローでは、これをデフォルトとします。
• ホスト型／マネージドデータセット: ケースを Logfire UI に保存し、エンジニア以外の人が編集して、別の LogfireAPIClient（from logfire.experimental.api_client import LogfireAPIClient）を通じて取得／プッシュします。ホスト型の入力と出力は JSON オブジェクトである必要があります。コード定義のデータセットでは受け付けられるスカラー型のルート値も、ここでは拒否されます。型引数なしの client.get_dataset(name) は生の dict を返すため、push_dataset や .evaluate_sync() に渡せるものではありません。入力／出力の型（および使用する場合はメタデータの型）を渡して、実際の pydantic_evals.Dataset を取得してください: client.get_dataset(name, MyInputType, MyOutputType)。保存されたデータセットにカスタム評価器が含まれている場合は、デシリアライズできるよう、そのクラスも custom_evaluator_types=[MyEvaluator] で渡してください（カスタムレポート評価器の場合は custom_report_evaluator_types=[...] を渡します）。client.push_dataset(dataset) でプッシュします。この方法には、ステップ2の CLI 認証フローではなく、Settings → API Keys で発行する専用の API キー（project:read_datasets／project:write_datasets のスコープ）が必要です。ケースをコードの外で編集したいとユーザーが明示的に希望している場合にのみ該当します。

ステップ 4: データセットを定義して実行する

リポジトリで既存のパッケージマネージャーとロックファイルを使用します。対象言語に不足している統合機能のみをインストールします。

Python

検出した Python マネージャーを使って pydantic-evals[logfire] を追加します: uv add、poetry add、または pdm add を使用してください。pip／requirements を使うプロジェクトでは、宣言済みの requirements を更新し、そのファイルからインストールします。別のマネージャーやロックファイルを新たに導入しないでください。

import logfire
from pydantic_evals import Case, Dataset
from pydantic_evals.evaluators import EqualsExpected, IsInstance

logfire.configure()  # omit only in the isolated local-only process described above

def classify_sentiment(text: str) -> str:
    return 'positive' if 'love' in text else 'negative'


dataset = Dataset[str, str, None](
    name='sentiment-eval',
    cases=[
        Case(name='positive', inputs='I love this', expected_output='positive'),
        Case(name='negative', inputs='This is terrible', expected_output='negative'),
    ],
    evaluators=[EqualsExpected(), IsInstance(type_name='str')],
)

report = dataset.evaluate_sync(classify_sentiment)  # or `await dataset.evaluate(...)`
report.print(include_input=True, include_output=True)

ステップ3のホスト型データセット API がタスクで明示的に必要な場合に限り、代わりに logfire[datasets] を使用します。

Node.js 上の JavaScript または TypeScript

このセクションは Deno、Bun、ブラウザー、ワーカーには適用しないでください。これらのエクスポーター設定は、このスキルでは検証されていません。

既存のロックファイルに応じて選択したマネージャーで、logfire と @pydantic/logfire-node を追加します: pnpm add、yarn add、bun add、または npm install を使用してください。別のロックファイルを新たに導入しないでください。

タスクを読み込む前に Logfire を設定します。設定を二重に行わず、既存の計測エントリーポイントを再利用してください。

import * as logfire from '@pydantic/logfire-node'
import { Case, Dataset, EqualsExpected, renderReport } from 'logfire/evals'

logfire.configure()

const classifySentiment = (text: string) => (text.includes('love') ? 'positive' : 'negative')
const dataset = new Dataset<string, string>({
  name: 'sentiment-eval',
  cases: [new Case({ name: 'positive', inputs: 'I love this', expectedOutput: 'positive' })],
  evaluators: [new EqualsExpected()],
})

await dataset.evaluate(classifySentiment).then((report) => {
  console.log(renderReport(report, { includeInput: true, includeOutput: true }))
}).finally(() => logfire.shutdown({ timeoutMillis: 5000 }))

その他の組み込み機能には Equals、Contains、IsInstance、MaxDuration、HasMatchingSpan、LLMJudge があります。Node.js のカスタム評価器は Evaluator を拡張し、LLMJudge には判定コールバックが必要です。ホスト型データセットには @pydantic/logfire-node/datasets のみを使用してください。

有料実行または全件実行の前のスモークテスト

データセットが大規模な場合、または LLMJudge や、モデル呼び出しに料金が発生する評価器を使用する場合は、全件実行の前に2〜3件でスモークテストを実行してください。これにより、セットアップのエラーがデータセット全体にわたるコストの増加につながる前に発見できます。

Python：

smoke = Dataset(
    name=dataset.name,
    cases=dataset.cases[:3],
    evaluators=dataset.evaluators,
    report_evaluators=dataset.report_evaluators,
)
smoke_report = smoke.evaluate_sync(classify_sentiment)
smoke_report.print(include_input=True, include_output=True)

Node.js：

const smoke = new Dataset({
  name: dataset.name,
  cases: dataset.cases.slice(0, 3),
  evaluators: dataset.evaluators,
  reportEvaluators: dataset.reportEvaluators,
})
await smoke.evaluate(classifySentiment).then((report) => {
  console.log(renderReport(report, { includeInput: true, includeOutput: true }))
}).finally(() => logfire.shutdown({ timeoutMillis: 5000 }))

スモークテストで予期しないエラーが発生せず、成功すべきアサーションが成功することを確認してください。その後、データセットが大規模な場合、または有料のモデル呼び出しを使用する場合は、全件数とモデル呼び出しを行う評価器をユーザーに伝え、全件実行の前に明示的な確認を得てください。スモークテストが問題なく完了したというだけで、知らせずにコストの高い全件実行をしてはいけません。

このセクションの残りの説明はPython固有の内容です。カスタム評価器は Evaluator を継承して evaluate を実装します。設定可能なフィールドと移植可能なシリアライズには @dataclass を使用してください。ケース名はデータセット内で一意である必要があります。よく使用される評価器は次のとおりです。

評価器	チェック内容
Equals(value) / EqualsExpected()	リテラル値 / expected_output との完全一致（expected_output が設定されていない場合は何も行いません。その場合も暗黙に検出されると期待しないでください）
IsInstance(type_name)	出力の型が名前で指定した型と一致すること
LLMJudge(rubric, model=None, score=False)	主観的な判断、またはルーブリックに基づく判断。料金が発生するモデルリクエストを行うため、品質の合格基準として扱う前に、人間が確認した例を使ってルーブリックを検証してください
ToolCorrectness(expected_tools, ...)	エージェントが呼び出したツール。スパンツリーを読み取るため、アップロードだけでなく、動作させるには Step 2 の logfire.configure() が必要です

その他に利用できる評価器は、Contains、MaxDuration、TrajectoryMatch、ArgumentCorrectness、MaxToolCalls、MaxModelRequests です。ツールや軌跡に関するものは、ToolCorrectness と同じスパンツリーへの依存があります。すべての評価器については pydantic_evals.evaluators を参照してください。これら5つのエージェント型（スパンベース）評価器には pydantic-evals>=2.4.0 が必要です。古いバージョンに固定されている場合は、これらを使う前に pyproject.toml / uv.lock を確認してアップグレードしてください。何もせずに実行されないのではなく、インポート自体が失敗するためです。

任意のコードを実行する Python 評価器は、セキュリティ上の理由で削除されました。古い例で言及されていても、使用しないでください。

ホストされたデータセットを編集する場合：client.push_dataset(dataset) は、削除した評価器も含め、プッシュするたびにサーバー側の評価器を上書きします。UI で他のユーザーが編集したデータセットに、古いローカルコピーをプッシュしないでください。

ステップ 5：検証

ターミナルにレポートが出力されても、Logfire に届いた証拠にはなりません。実行結果が実際に反映されたことを確認してください。このセッションで実際に確認していないケースを合格と報告したり、スコアを報告したり、実行が完了したと報告したりしてはいけません。実行が失敗、キャンセル、またはスコアなしで終わった場合は、その失敗を明確に報告してください。作り上げたスコアや、結果が「こうなるはず」という手動の推測で代用してはいけません。

ステップ 1 の Braintrust パスを経由しましたか（ステップ 2 をスキップ）？ ここでは whoami で解決されたプロジェクトがないため、SDK 自身が出力した結果 URL を使用してください。この URL からは、適切な Logfire プロジェクトが直接開きます。名前で検索するのではなく、そのページで以下の項目（完了状況、合否の内訳、ケースの詳細）を確認してください。

1. Logfire MCP サーバーまたは API に接続している場合は、実行を直接クエリします。実行のルートスパン名は evaluate {name} で、gen_ai.operation.name = 'experiment'、dataset_name、task_name の属性を持っています。データセット名に一致する最新のスパンを見つけ、logfire.experiment.metadata に予想されるケース数と合格率が表示されていることを確認してください。それ以外の場合は、ステップ 2 で指定した正確なプロジェクトの Logfire で AI Evaluations → Datasets & Experiments → Experiments を開き、名前またはタイムスタンプから実行を見つけてください。
2. まず Overview タブ（またはクエリしたメタデータ）を確認します。完了数、アサーションの合否の内訳、タスクエラー、平均所要時間を確認してください。完了状況が「Not reported」の場合、実行はケースデータを送信したものの、完了を通知していません。合格ではなく、壊れた実行として扱ってください。
3. Cases タブを開き、全件リストではなく、Needs Review／Failed／Errors から確認します。
4. 失敗したケースのトレースを Live ビューで詳しく調べ、要約スコアだけを信用せず、実際の証拠を確認します。
5. 合格すべきケースが合格し、ツール呼び出し／軌跡のチェックに「No span tree available」ではなく実際のスパンデータが表示されるまで、修正して再実行します。

実際に確認した結果をもとに、最終レポートを作成してください。実行名、クエリで確認した正確なケース数と合格率、実行された評価器を記載し、テンプレートで済ませないでください。この実験への直接リンク（SDK 自身が出力した結果 URL、または実験を開いた Datasets & Experiments ページへのリンク）を含め、ユーザーが参照先を尋ねずに実行結果を確認できるようにしてください。