migrate-to-langfuse

Langfuse への移行

Langfuse への一回限りのベンダー切り替えを行います。まず聞き取りを行い、次に計画を立て、確認を得てから実行してください。記憶に頼って実装してはいけません。実行時に、以下に記載された最新の Langfuse ドキュメントを取得してください。

1. 聞き取り（常にコード変更の前に行う）

検出できないことだけを質問してください。まずリポジトリを調べてください。依存関係やインポートから、通常は移行元のプラットフォーム（langsmith、arize、phoenix、braintrust、openinference、古い langfuse のバージョン）を特定できます。

1. 移行元 — プラットフォームとバージョンは何ですか？クラウドですか、それともセルフホストですか？どのアクセス手段がありますか？API キー、データベース接続、またはアプリケーションのリポジトリのみですか？
2. 移行先 — Langfuse Cloud（どのリージョンですか？）ですか、それともセルフホストですか？認証情報は存在するかどうかだけを確認してください（例：[ -n "$LANGFUSE_SECRET_KEY" ]）。チャットで秘密情報を尋ねてはいけません。また、どのような手段であっても .env の内容やキーの値にアクセスしてはいけません。値を出力するシェルコマンドの実行、ファイルツールでの .env の読み取り、値の grep は禁止です。設定されている環境変数名だけを検出し、それ以外は確認しないでください。
3. 範囲 — 次のどれを対象としますか：ライブトレースの切り替え、履歴トレース（スコア、スコア設定、カスタムモデル定義を含む）、データセット、プロンプト、評価器／LLM ジャッジ、実験コード。履歴については、すべてですか、それとも指定日以降ですか？移行元アカウントに他に何が存在するか（ダッシュボード、アラート、アノテーションキュー、保存済みビューなど）も確認してください。リポジトリからサーバー側のアセットは特定できません。上記のサポート対象に含まれないものは、このスキルの対象外です。切り替え後に不足に気づくことがないよう、スコープ表でその旨を明記し、ユーザーが手動で再作成できるようにしてください。
4. モード — 計画のみ（手順書を作成）ですか、それとも実行しますか？

依頼内容がリポジトリと矛盾する場合（依頼で指定されたプラットフォームが存在しない、またはインストールされていない SDK のアップグレードを求められている場合）は、作業を止め、まずユーザーと認識を合わせてください。依頼を別の移行として読み替えて実行を始めてはいけません。

作成した計画（スコープ表と作業順序）を提示し、ファイルを変更する前にユーザーの確認を得てください。依頼の表現がどれほど強い指示であっても、計画の確認前に既存ベンダーの計装を削除または置き換える許可にはなりません。

2. 適用するデフォルト

• まずライブ切り替えを行います。 履歴データの移行は任意であり、Langfuse では新規取り込みとして課金されます。履歴を移行する前に、この点を伝えてください。移行元がすでに OTel／OpenInference スパンを出力している場合は、計装し直すのではなく、既存の計装に Langfuse を 2 つ目のエクスポーターとして追加してください。下記の並行稼働期間が終了するまで、旧移行先は削除しません。
• データセットとプロンプトはコピーし、評価器とジャッジは再作成します。 実験コードは書き換え、移行したデータセットを使って再実行します。以前の実験スコアをインポートしてはいけません。
• 全件実行の前にサンプルでテストします。 まず約 10 件のトレースを移行し、移行先のトレースへのリンクを提示してください。すべてを移行する前に、内容に問題がないことをユーザーに確認してもらいます。
• 進捗を表示します（長時間の実行ではページ数／件数）。また、再実行を再開可能にします。送信済みの移行元 ID を状態ファイルで追跡し、スキップしてください。同じ ID を再送信すると重複したオブザベーションが作成されます（references/reingest-history.md を参照）。
• 並行稼働期間。 ユーザーが移行先のデータを確認するまで旧エクスポーターを維持し、その後、別途明示的な手順として削除します。この要件は計画だけでなく実装にも適用されます。編集後も、旧ベンダーのエクスポーター／計装が残り、有効でなければなりません。差分を表示する前に、ベンダーのインポート、登録呼び出し、エクスポーターのエンドポイント、エクスポーターの環境変数が削除または変更されていないことを再確認してください。並行エクスポートは、1 つの計装に 2 つのエクスポーター（同じトレーサープロバイダー上の両方のスパンプロセッサ）を設定して実現してください。アプリケーションを二重に計装してはいけません。移行先で生成が重複し、コストが二重計上される場合は、2 つ目のキャプチャ経路が存在する兆候です。

3. シナリオ別のルーティング

内容を取得して参照します。内容を転載しないでください。

シナリオ	信頼できる情報源
公開ガイドがあるベンダー（LangSmith、Arize AX、Phoenix、Braintrust、Helicone、Promptfoo など）	https://langfuse.com/resources/engineering/migrate-from-<vendor>.md — 現在の一覧は https://langfuse.com/llms.txt で確認してください
公開ガイドがないベンダー、または任意のベンダーからの履歴データ	references/reingest-history.md と、ベンダー独自のエクスポート API ドキュメント

履歴トレースの再取り込みをその場の判断で行ってはいけません。ベンダーガイドがある場合でも、再取り込みコードを作成または実行する前に、references/reingest-history.md を最後まで読んでください。ベンダーガイドでは抽出方法を、リファレンスでは再取り込みの方法（決定的な ID、未加工の OTLP ペイロード、元のタイムスタンプ、カットオーバー時刻の上限、インポートした履歴は新規取り込みとして課金される旨の警告）を規定しています。

移行元が別の Langfuse デプロイメント（旧バージョン、別プロジェクト、リージョン、ホスト）の場合は、そこで作業を中止してください。これはベンダーの切り替えではありません。メインの langfuse スキル（SDK のアップグレードおよび v4 移行のリファレンス）と、プロジェクト間移行のクックブックをユーザーに案内してください。

ライブ計装のカットオーバーには、https://langfuse.com/llms.txt からユーザーのフレームワークまたは SDK に対応するインテグレーションガイドを使用してください。Langfuse 側の高度な作業（プロンプトの作成、データセット API、実験コード）については、インストールされている場合はメインの langfuse スキルを参照してください。

4. 検証して完了する

• 全件実行の前に、移行先 UI でユーザーが確認したサンプルチェックを実施します。
• ライブカットオーバーのサンプル確認をユーザーに依頼する前に、Langfuse API または CLI を使って自分で監査します。リクエストごとにトレースが 1 つであること、ルートスパン名がエージェント／アプリ名と一致し（トレース名はルートと一致する）、すべてのスパンタイプ（生成とツール／チェーンスパン）が含まれていること、各 LLM 呼び出しが一度だけ記録されていること、トークン使用量とコストが入力されていることを確認します。その後でのみ、トレースリンクをユーザーに送信します。
• 移行したデータタイプごとに件数が一致していること（移行元と移行先）を確認し、失敗を含むサマリーテーブルを報告します。
• 移行先にライブトラフィックが到着していることを確認します。旧エクスポーターは、ユーザーが選択した並行稼働期間が終了してから削除します。
• 完了時のサマリーには、インタビューで作成したスコープ表のすべての行（スキップまたは対象外としたものを含む）を記載します。何も黙って除外しないでください。