Integration の設定
AI サービスのログストレージを接続し、パーサーコードでログを Turn 単位に変換して、モニタリング(Observability)と連携します。
1. Integration の開始
①Integration
Integration は、AI サービスのユーザーログを Datumo Platform に取り込むための接続設定です。Application ごとに、使用中の Integration は 1 つです。
- 現在は AWS CloudWatch のログを連携します。
- 設定は 2 ステップです。ステップ 1 で接続情報を確認し、ステップ 2 でパーサーコードを実行します。
- 設定を変更するたびにバージョンが 1 つずつ上がります。以前の設定は Integration History に残ります。
ログの階層と評価単位は、モニタリングのコアコンセプトで説明しています。
②事前に準備するもの
| 項目 | 説明 |
|---|---|
| AWS Region | ログが保存されているリージョン |
| Access Key、Secret Key | その Region にアクセスできる AWS のキー |
| Log Path | ログを読み込むパス(例:/aws/lambda/my-service)。 |
| パーサーコード | ログを Turn に分割する Python コード |
- キーとパスはインフラ担当チームに依頼してください。
1-1設定画面を開く
- 左メニュー下部の
Settingをクリックします。 Observabilityタブをクリックします。
- 左メニュー下部の
1-2新しい Integration の開始
Integrationで+ New Integrationをクリックします。
Integration がない場合、Fail Case 画面に
There are no integrations yet.と表示されます。
2. 接続情報の入力
①Basic Setting の項目
| 項目 | 説明 |
|---|---|
Region | ログが保存されている AWS Region。一覧から選びます。 |
Access Key / Secret Key | Region にアクセスするための AWS のキー。入力値はマスクされます。 |
Log Path | ログを読み込むパス |
②接続テスト
Test Connection は、入力した情報で実際に接続を試みます。成功すると、読み込んだログが Integrated Logs に表示されます。
- 最新のログを最大 100 件まで読み込みます。
- 読み込んだログは、ステップ 2 でパーサーコードの結果を確認するときに使います。
- 接続に成功すると、入力欄がロックされます。
接続に失敗すると、エラーメッセージが表示されます。
| エラー | 原因 | 確認すること |
|---|---|---|
Invalid access credentials | キーが誤っているか、Region へのアクセス権限がない | キーの値と Region の権限 |
Log path not found | 入力したパスが存在しない | パスと表記方法 |
No logs found | 接続はできたがログがない | パスと照会期間 |
2-1接続情報の入力
Regionを選びます。Access KeyとSecret Keyを入力します。Log Pathを入力します。
2-2接続の確認
Test Connectionをクリックします。Integrated Logsで読み込んだログを確認します。Nextをクリックします。
4 つの項目をすべて入力すると
Test Connectionが有効になります。2-3接続失敗時の対応
- エラーメッセージを確認します。
Set up againをクリックして値を修正します。
エラーごとの原因は Test Connection にまとめています。
3. パーサーコードの実行
①パーサーコード
パーサーコードは、元のログからユーザーの質問と AI の回答を見つけて Turn にまとめる Python コードです。ログの形式はサービスごとに異なるため、自分で作成します。
- 書き方は画面の
Check Parser Guideで確認します。 - コードは JSON を返す必要があります。
| エラー | 原因 |
|---|---|
Json Format Error | コードは実行されましたが、結果が正しい JSON ではありません。 |
SyntaxError (Compile Error) | コードの構文が誤っているため実行されません。 |
TypeError (Runtime Error) | 実行中に互換性のないデータ型どうしで演算しました。 |
②マッピングプレビュー
Mapping Preview は、パーサーの結果が評価用の列にどのように対応付けられるかを示します。
| 列 | 意味 |
|---|---|
session_id | Turn が属する Session の ID |
turn_id | Turn ID |
timestamp | メッセージの時刻 |
type | User Input または App Output |
message | メッセージの内容 |
- 必須値が空の行は赤く表示され、評価から除外されます。
- 評価できる行が 1 つもない場合、
Completeは無効になります。 User InputとApp Outputが交互に並んでいるか確認します。ずれていると、評価結果が正しく出ません。
3-1コードの実行
- 左側の
Integrated Logsで元のログを確認します。 Parser Code (Python)にコードを入力します。Runをクリックします。
書き方は
Check Parser GuideのGo to Docsで確認します。- 左側の
3-2結果の確認
Parser Code Outputで返された JSON を確認します。Mapping Previewで列の対応付けを確認します。- 赤い行は必須値が空のため、評価から除外されます。
列ごとの意味は Mapping Preview で確認します。
3-3コードの修正
- 結果が想定と異なる場合は
Editをクリックします。 - コードを修正し、もう一度
Runをクリックします。
- 結果が想定と異なる場合は
3-4連携の完了
Completeをクリックします。
- 完了した日時と作業者が Integration カードに記録されます。
- 保存せずにウィンドウを閉じると、確認ダイアログが開きます。
4. Integration の管理
①Integration 情報カード
| 項目 | 意味 |
|---|---|
Integrated at | 最後に Complete をクリックした日時 |
Integrated by | 最後に Complete をクリックしたユーザー |
latest logged at | 連携された Turn のうち最新の Turn の日時 |
total turns | 連携された Turn の総数 |
Ingestion Settings | 連携タイプ、Region、Log Path |
Integrated atは設定を完了した日時です。latest logged atはログが実際に取り込まれた日時です。- 説明欄には、バージョンの説明を 255 文字まで入力できます。
②新しい Integration への切り替え
ログの形式や保存場所が変わった場合は、Switch to new integration で新しいバージョンを作成します。
- 設定ウィンドウは、以前の Region、Log Path、パーサーコードが入力された状態で開きます。
Access KeyとSecret Keyは、セキュリティのため空欄になっています。再入力してください。- 完了するとバージョンが 1 つ上がります。以前の設定は Integration History に移動します。
- Gen & Judge モデルがない場合、ボタンは無効になります。
③Integration の連携解除
連携を解除するには、Integration カード右上の Disconnect をクリックします。ボタンは Integration History と Switch to new integration の間にあります。
Disconnectをクリックすると確認ウィンドウが開きます。この時点ではまだ解除されません。- 確認ウィンドウで
Disconnectをクリックすると解除されます。処理中はボタンをクリックできません。 - 解除されると
Integration disconnected.の通知が表示され、Integration カードがThere are no integrations.の状態に変わります。
| 解除後 | 内容 |
|---|---|
| ログの取り込み | この Integration では新しいログを取り込まなくなります。 |
| 再接続 | 解除した Integration は再び有効にできません。+ New Integration で新しく連携します。 |
| 過去の結果 | 解除前の評価結果は残ります。 |
| 設定 | サンプリング確率と Metric の設定はそのまま維持されます。 |
- ログの取り込み状態に関係なく解除できます。
- 解除に失敗すると、確認ウィンドウが開いたままエラー通知が表示されます。もう一度
Disconnectをクリックしてください。
4-1情報の確認
- Integration カードでバージョンと連携情報を確認します。
Ingestion Settingsで Region と Log Path を確認します。
項目ごとの意味は Integration 情報カードにあります。
4-2説明の入力
- 説明欄にこのバージョンの説明を入力し、
Saveをクリックします。
- 説明欄にこのバージョンの説明を入力し、
4-3履歴の確認
Integration Historyをクリックします。- 過去のバージョンの設定を新しい順に確認します。
4-4新しいバージョンの作成
Switch to new integrationをクリックします。Access KeyとSecret Keyを再入力します。- ステップ 2〜3 と同じ手順で完了します。
以前の設定は Integration History に移動します。
4-5連携解除
Disconnectをクリックします。- 確認ウィンドウで
Disconnectをクリックします。 - Integration カードが空の状態に変わったことを確認します。
解除した Integration は再び有効にできません。
+ New Integrationで新しく連携します。
よくある質問
Test Connection を押せないのはなぜですか?未入力の項目があるためです。
- 原因
- Region、Access Key、Secret Key、Log Path をすべて入力すると、ボタンが有効になります。
- 解決方法
- 空欄を入力してください。
Invalid access credentials と表示されるのはなぜですか?キーが誤っているか、Region へのアクセス権限がないためです。
- 原因
- 有効なキーでも、選んだ Region へのアクセス権限がなければ失敗します。
- 解決方法
- キーの値と Region の権限をインフラ担当チームと確認してください。
No logs found と表示されるのはなぜですか?接続はできていますが、パスにログがないためです。
- 原因
- パスが空であるか、別のパスである可能性があります。
- 解決方法
Log Pathと照会期間をもう一度確認してください。
パーサーのステップで Complete を押せないのはなぜですか?評価できる行がないためです。
- 原因
- 必須値が空の行は評価から除外されます。すべての行が空の場合は
There are no valid rows available for evaluation.と表示されます。 - 解決方法
Editでパーサーコードを修正し、もう一度実行してください。
Switch to new integration を押せないのはなぜですか?Gen & Judge モデルがないためです。
- 原因
- 登録済みの Gen & Judge モデルが 0 件の場合、ボタンは無効になります。
- 解決方法
Go to Gen & Judge Model Settingで先にモデルを登録してください。
接続されているのにデータが表示されない場合はどうすればよいですか?latest logged at が更新されているか確認してみてください。更新されていない場合は、ログの収集状況を点検してください。
- 原因
latest logged atは、最後に連携された Turn の日時です。- 解決方法
latest logged atが更新されているか確認してください。更新されていない場合は、ログの収集状況を点検してください。