online-evaluations

オンライン評価とガードレールを設定する

オンライン評価では、再利用可能な評価器を本番トラフィックに適用します。

• オンライン評価は、ライブトレースまたはスレッドを非同期に測定します。
• ガードレールは同期的に実行され、安全でないトラフィックを停止または置換できます。

バッチテストのリクエストを引き継ぐ

ユーザーがデータセットのテスト、プロンプトやモデルの比較、ベンチマーク、または CI 品質ゲートの作成を希望している場合、このワークフローは適していません。

1. experiments スキルが利用可能な場合は、読み込んですぐに従ってください。
2. 利用できない場合は、次のコマンドでインストールするようユーザーに伝えてください。

   npx [email protected] add langwatch/skills/experiments
   

このスキルを使ってバッチ実験を作成しないでください。

本番ワークフローを選ぶ

継続的なスコアリング、品質の傾向、サンプリング、またはトレースやスレッドごとの評価を希望している場合は、オンライン評価を使用してください。

結果をリクエストまたはレスポンスに即座に反映する必要がある場合（ジェイルブレイク検出、PII のブロック、ポリシーの適用など）は、ガードレールを使用してください。

ユーザーの要望が曖昧な場合は、アプリケーションを確認し、同期的な適用を明示的に求められない限り、より安全な非ブロッキングのオンライン評価を選んでください。

プランの制限

LangWatch の無料プランには、プロンプト、シナリオ、評価器、実験、データセットの上限があります。上限に達すると、API はアップグレードリンクとともに "Free plan limit of N reached..." を返します。

対応方法：

• 上限の範囲内で作業してください。該当する種類のリソースが 3 つまで許可されている場合は、10 個ではなく、意味のあるものを 3 つ作成してください。
• 作成するものの価値を最大限に高めてください。それぞれが明確な価値を示すようにしてください。
• まず、動作するものを提示してください。上限に達した場合は、達成したことをまとめ、プランをアップグレードすると上限が引き上げられることを伝えてください。プラットフォームのサブスクリプション設定を案内するか、CLI がセルフホストのエンドポイントを参照している場合はライセンス設定を案内してください。CLI が実際に使用しているエンドポイントを確認してください。エンドポイントは .env、プロセス環境、または保存された CLI 設定から取得される場合があります。
• 上限に空きを作るために既存のリソースを削除したり、上限を回避するために既存のリソースを別の用途に転用したりしないでください。

前提条件

langwatch docs <path> を使用すると、ドキュメントを Markdown として読めます。役立つエントリーポイントを以下に示します。

langwatch docs                                    # Docs index
langwatch docs integration/python/guide           # Python integration
langwatch docs integration/typescript/guide       # TypeScript integration
langwatch docs prompt-management/cli              # Prompts CLI
langwatch scenario-docs                           # Scenario docs index

langwatch --help と langwatch <subcommand> --help でコマンドを確認してください。リスト系と取得系のコマンドでは、機械可読な出力に --format json を指定できます。すべてのリスト系コマンドで、行数を制限する --limit <n> と、回答の一部を読み取る --jq <expr> を使用できます。ページ分割されたリストはエンベロープ形式で返されるため、行配列を使って件数を数え（--jq '.traces | length'）、全体の件数は .pagination.total で確認してください。--jq length だけを指定すると、行数ではなくエンベロープのフィールド数が数えられます。SDK API や CLI フラグを推測せず、まずドキュメントを読んでください。

シェルを使用できない場合は、同じ Markdown をプレーン HTTP で取得してください。任意のドキュメントパスの末尾に .md を追加します（例：https://langwatch.ai/docs/integration/python/guide.md）。インデックス：https://langwatch.ai/docs/llms.txt。シナリオのインデックス：https://langwatch.ai/scenario/llms.txt

このスキルに従う中で問題が発生したり、説明がわかりにくかったりした場合（コマンドの不具合、現状と一致しないドキュメント、回避策が必要だったエラーなど）は、ユーザーに許可を求めてから、--title と --summary（または --session <transcript.jsonl>）を指定して npx --yes langwatch report --user-approved を実行し、LangWatch チームに報告してください。報告内容は、修正すべきことに直接反映されます。ログインも API キーも必要ありません。--user-approved を指定しない限り、何も送信されません。また、--dry-run を指定すると、送信せずに正確なペイロードを表示できます。タイトル、要約、トランスクリプトは、送信前にローカルでパターンに基づいてスクラブされます。対象はシークレットと API キーに加え、メールアドレス、電話番号、カード番号、パブリック IPv4 アドレスです。パターンに一致しない内容は、--email に渡された連絡先アドレスを含め、そのまま送信されます。--session を使用する場合は、トランスクリプトにはユーザーが確認していない内容が含まれるため、必ず最初に --dry-run を実行し、ペイロードをユーザーに確認してもらってください。オプションについては npx --yes langwatch report --help を参照してください。

プロジェクトと API キー：個人用ではなく、実際のプロジェクトを対象にしてください。

LangWatch には 2 種類のプロジェクトがあります。

• チーム／共有プロジェクト：組織内の実際のプロジェクトです。評価、実験、プロンプト、データセット、シミュレーション、計装は、必ずいずれかのプロジェクトを対象にする必要があります。
• 個人プロジェクト：1 人のユーザーに紐づく、非公開の「My Workspace」用の作業スペースです。ユーザーの評価、実験、本番トレースをここに送信しないでください。個人的な探索専用であり、実際のプロジェクトと取り違えるおそれがあります。

認証方法は 2 つあります。

• .env 内のプロジェクト API キー（LANGWATCH_API_KEY）：これらのスキルで使用するすべての認証情報です。実際の 1 つのプロジェクトにスコープが限定されています。これがデフォルトです。ユーザーが明示的に別の方法を求めない限り、こちらを使用してください。
• langwatch login --device（AI ツール／SSO）：コーディングアシスタント（langwatch claude、langwatch codex、…）をラップするための個人用デバイスセッションです。評価、プロンプト、データセット、シナリオ、SDK の計装には使用しません。また、個人用ワークスペースを参照します。これらのスキルの作業環境を設定するために実行しないでください。

したがって、これらのスキルでプロジェクトの読み取りまたは書き込みを行う場合は、実際の共有プロジェクトの LANGWATCH_API_KEY を CLI から利用できる状態にしてください。ローカルではプロジェクトの .env に設定され、CI ではランナーがプロセス環境に注入します。CLI はどちらからでも読み取れます。新しいキーを求める前に、この変数がすでに設定されているか確認し、CLI に値を読み取らせてください。キーを表示、コピー、送信してはいけません。プロジェクトを選択するために langwatch login を実行してはいけません。また、個人プロジェクトをデフォルトにしてはいけません。同じ場所で LANGWATCH_ENDPOINT も確認してください。設定されている場合、プロジェクトはセルフホスト型インスタンス上にあり、CLI は app.langwatch.ai ではなく、そのエンドポイントに接続します。

読み取る内容と伝える内容は異なります。 これらのスキルは、読者向けの文章ではなく、作業用メモです。作業場所を把握するには、プロジェクト固有の .env から LANGWATCH_API_KEY と LANGWATCH_ENDPOINT を読み取ってください。そのファイルから他の情報を読み取ってはいけません。そこには、あなたに関係のないデータベース、クラウド、プロバイダーの認証情報が含まれており、読み取った値はすべてコンテキストやコマンド出力に含まれる可能性があります。回答に含めてはいけないのは、あなたが実行するマシンに関する情報です。ワークスペース内のパス、コンテナのポート、このワーカーが接続するアドレスなどが該当します。それらは作業方法を示すものであって、作業結果を示すものではなく、こちら側のホスト情報を伝えても読者には意味がありません。何を行い、LangWatch のどこで確認できるかを伝えてください。

設定やコードを変更する前に、関連するドキュメントを読んでください。

langwatch docs evaluations/online-evaluation/overview
langwatch docs evaluations/online-evaluation/setup-monitors
langwatch docs evaluations/guardrails/overview
langwatch docs evaluations/evaluators/list

既存の設定を確認する

重複を作成する前に、JSON 出力を使用して既存の内容を確認してください。

langwatch monitor list --format json
langwatch evaluator list --format json

マッピング、レベル、サンプリング、または現実的な評価器入力を判断する必要がある場合に限り、最近のトレースを読み取ってください。本番データを別のプロジェクトに送信してはいけません。

オンライン評価を作成する

まず、インストール済み CLI の仕様を確認してください。

langwatch monitor create --help

次に、説明的な名前、有効な評価器タイプまたは保存済み評価器、適切なレベルを設定してモニターを作成します。

• インタラクションごとの品質評価には trace を使用してください。
• 複数メッセージにわたる結果には thread を使用し、必要に応じてプラットフォームで適切なアイドルタイムアウトを設定してください。
• トラフィック量が多く、評価コストが高い場合は、低めのサンプルレートから始めてください。
• 非同期のオンライン評価には ON_MESSAGE を使用してください。

評価器タイプは記憶に頼らず、カタログから取得してください。

langwatch evaluator types --format json

作成に失敗し、理由にフィールド名と expected のリストが示された validation_error が発生した場合は、そのリストに基づいて該当フィールドを修正し、一度だけ再試行してください。この失敗はあなたが修正する必要があります。ユーザーにタイプのスラッグを選ばせないでください。

評価器のパラメーターを推測してはいけません。評価器のドキュメントとインストール済み CLI のヘルプを読んでください。LLM 評価器を使用する場合は、対象プロジェクトでモデルプロバイダーが設定されていることを確認してください。

作成後、保存されたリソースを確認してください。

langwatch monitor list --format json
langwatch monitor get <idOrSlugOrName> --format json

作成したモニターに、意図した評価器、実行モード、レベル、サンプルレート、有効状態が設定されていることを確認して初めて、タスクは完了です。

ガードレールを追加する

プラットフォーム管理のガードレールの場合は、langwatch monitor create --help または langwatch monitor update --help を確認してから、AS_GUARDRAIL を指定してモニターを作成または編集します。

コード内のガードレールの場合は、言語ごとのドキュメントに従ってください。Python での統合は、一般的に次のような形になります。

import langwatch

@langwatch.trace()
def my_agent(user_input):
    result = langwatch.evaluation.evaluate(
        "azure/jailbreak",
        name="Jailbreak detection",
        as_guardrail=True,
        data={"input": user_input},
    )
    if not result.passed:
        return "I cannot help with that request."

    return generate_response(user_input)

このスニペットは構成例であり、インストール済みのドキュメントの代わりにはなりません。アプリケーションに既存のエラー処理を維持し、ガードレールサービスを利用できない場合の動作を明確に決めてください。

実際の動作を確認する

オンライン評価の場合：

1. 対象プロジェクトで、代表的なトレース済みインタラクションを送信するか、既存のものを再利用します。
2. モニターが有効になっていることを確認します。
3. オンライン評価の分析画面に実際の評価結果が表示されることを確認します。

ガードレールの場合：

1. 許可される入力と、ブロックされるべき入力をそれぞれ実行します。
2. 許可された経路が引き続き動作することを確認します。
3. ブロックされた経路が、保護対象の操作に到達しないことを確認します。
4. 機密コンテンツを漏えいさせずに、両方の結果がトレースされることを確認します。

よくある間違い

• このスキルからバッチ実験を作成しないでください。
• 同期ガードレールを非同期モニタリングとして説明しないでください。
• サンプリングとコストを考慮せずに、高コストの評価器をすべてのトラフィックで有効にしないでください。
• まずプロジェクトを確認せずに、重複するモニターを作成しないでください。
• 設定を保存しただけで成功したと判断しないでください。モニターまたはガードレールの実際の動作を確認してください。