Genieエージェントのトラブルシューティング

Genie Agent の作成と保守における一般的な問題を解決します：誤解されたビジネス専門用語、不正確なテーブルまたは列の使用法、特定の値に関するフィルタリングエラー、長い会話におけるトークン制限による切り捨て。以下の各セクションでは、症状、原因、解決策について説明します。

注記

Genieエージェントは以前、Genie Spaceとして知られていました。

これらの問題の多くにとって、修正への最短パスはGenie Codeです。Genie Codeに問題を説明すると、レビューし、承認できるコンテキスト変更を提案します。単一の誤った応答を診断するには、Genie Codeで応答をデバッグするを参照してください。ベンチマークの失敗をまとめて確認するには、Genie Codeでベンチマークランを分析するを参照してください。

誤解されたビジネス用語

ほとんどの企業やドメインには、ビジネス固有のイベントについて伝えるために使用する特定の略語があります。 たとえば、年を指す場合、常に会計年度を意味し、この会計年度は 1 月ではなく 2 月または 3 月に始まる場合があります。 Genieがこれらの質問に自然かつ正確に答えられるようにするには、ビジネス用語をGenieが理解できる単語や概念に明示的にマッピングする指示を含めます。 指示を提供するを参照してください。

不正なテーブルまたは列の使用法

Genieが間違ったテーブルからデータを取得しようとしたり、間違った列で分析を実行しようとしたりする場合は、次のいずれかの方法でデータを調整できます。

• 明確で正確な説明を提供する ：テーブルと関連するメタデータを確認して、そこに適用されている用語が、ユーザーが送信した質問で使用されている用語と一致していることを確認してください。一致しない場合は、説明を改善するか、テーブルで使用されている用語を質問で使用されている用語に対応付ける指示を追加します。
• サンプルクエリの追加 : Genie が特定の質問に回答する方法を学習するために使用できるサンプル SQL クエリを提供します。 指示を提供するを参照してください。
• エージェントからテーブルまたは列を削除する : 一部のテーブルには重複する列や概念が含まれていることがあり、Genieが応答で使用するデータを判断するのが困難になる場合があります。可能であれば、不要な、または重複するテーブルや列を削除してください。基盤となるデータオブジェクトを変更せずにGenie Agent UIから列を非表示にするには、関連する列を非表示または表示するをご覧ください。

エラーのフィルタリング

生成されたクエリーには、特定の値に基づいて結果をフィルターするためのWHERE句がよく含まれています。Genieがデータ値に対する可視性を持たない場合、WHERE句を誤った値でフィルターするように設定する可能性があります。例えば、テーブルが「CA.」のような略語を使用している場合、「California」という名前と一致させようとする可能性があります。

このような状況では、関連する列で 例の値 と 値の辞書 が有効になっていることを確認してください。関連するテーブルに新しいデータが追加された場合は、値を更新します。プロンプトマッチングの概要をご覧ください。

誤った結合

Unity Catalogで外部キー参照が定義されていない場合、エージェントは異なるテーブルを結合する方法を認識できない可能性があります。

以下のソリューションを1つ以上実装してみてください：

• 可能な場合は、Unity Catalog で外部キー参照を定義します。CONSTRAINT 句を参照してください。
• テーブルの外部キー関係がUnity Catalogで指定されていない場合は、Genie Agentのナレッジストアで結合関係を定義してください。この戦略は、自己結合などのより複雑な結合シナリオや、基になるテーブルを変更するための十分な権限がない場合に役立ちます。結合関係の定義を参照してください。
• 標準的な方法でテーブルを結合するクエリーの例を提供します。

これらのいずれも問題を解決しない場合は、テーブルをビューに事前に結合し、代わりにそれをエージェントの入力として使用します。

フォーリンテーブルから列コメントが同期されません

Databricksは、フォーリンテーブルへの書き込みに関して、メタデータ、データ、またはセマンティクスを管理しません。ソーステーブルによっては、Databricksからコメントにアクセスできない場合があります。コメントを利用可能にするには、Databricksでは次のいずれかを実行することをお勧めします。

• Genie Agent UIで列メタデータを編集します。編集されたメタデータは、それが記述されているGenie Agent にのみ適用されます。列メタデータを編集をご覧ください。
• フェデレーションテーブル上にマテリアライズドビューを作成します。マネージドテーブルの場合と同様に、マテリアライズドビューにコメントを追加および編集できます。このビューを複数のGenieエージェントで再利用できます。フォーリンテーブルからマテリアライズドビューにデータをロードする方法の詳細については、マテリアライズドビューを使用してフォーリンテーブルからデータをロードするを参照してください。マテリアライズドビューの操作の詳細については、マテリアライズドビューを参照してください。

メトリクスの計算に関する問題

メトリクスがコンピュートされ、ロールアップされる方法は、任意に複雑になり、エージェントが理解できない多くのビジネスの詳細を含む可能性があります。これにより、誤ったレポートにつながる可能性があります。

以下のソリューションを1つ以上実装してみてください：

• メトリクスをナレッジ ストアでSQL式として定義します。SQL式は、Genieが常に適用できるメジャー、フィルター、ディメンションに対して、再利用可能で正確な定義を提供します。「SQL式の定義」を参照してください。
• メトリクスがベーステーブルから集計されている場合は、各ロールアップ値を計算するSQLクエリーの例を提供してください。
• メトリクスが事前に計算されており、集計テーブルに格納されている場合は、このことをテーブルコメントで説明してください。そのテーブルのメトリクスをさらにロールアップできる場合は、各メトリクスに有効な集計を指定してください。
• 生成しようとしているSQLが非常に複雑な場合は、エージェントのためにメトリクスを集計済みのビューを作成してみてください。

不正な時間ベースの計算

明示的に追加のガイダンスを提供しない限り、Genieはデータに表示されているタイムゾーンや分析を実行する必要があるタイムゾーンを常に推測できるとは限りません。

元のタイムゾーン、変換関数、およびターゲットタイムゾーンを詳述する、より明確な指示を含めてください。より信頼性の高いタイムゾーン変換のために一般的な指示を変更する方法を、以下の例に示します：

• 常に時間を特定のタイムゾーンに変換してください : この例では、ソース Timestamp が UTC で、America/Los_Angeles タイムゾーンで結果が必要であると仮定します。以下の手順を指示に追加します。<timezone-column> を適切な列名に置き換えてください:

  • テーブルのタイムゾーンはUTCです。
  • 次の関数を使用して、すべてのタイムゾーンを変換します: convert_timezone('UTC', 'America/Los_Angeles', <timezone-column>)。

• 非UTCの日付時刻形式をUTCに変換します ：ワークスペースのdefaultタイムゾーンがUTC であっても、ロサンゼルスのユーザーが特定のレコードセットに対して「今日」を参照する必要がある場合は、エージェントの一般的な指示に以下を追加します。

  • 今日 を参照するには、 date(convert_timezone('UTC', 'America/Los_Angeles', current_timestamp()))を使用します。

詳細と構文については、convert_timezone関数を参照してください。

指示の無視

コメントでテーブルと列を説明し、一般的な指示を提供した場合でも、エージェントがそれらを正しく使用していない可能性があります。

次のいずれかの戦略を試してください：

• テーブルを正しく使用するクエリーの例を提供してください。クエリーの例は、エージェントがデータを使用する方法を教えるのに特に効果的です。
• Genie Agentで不要な列を非表示にします。関連する列を非表示または表示するをご覧ください。
• テーブルから、データへのよりシンプルなビューを提供するビューを作成します。
• 指示を見直し、不要なテーブルや指示を削除して、エージェントが集中できるようにしてください。
• 新しいチャットの開始をお試しください。以前のやり取りは、特定のチャットにおけるGenieの応答に影響を与える可能性がありますが、新しいチャットを開始すると、新しい命令をテストするための白紙の開始点が得られます。

パフォーマンスの問題

Genieが非常に長いクエリーまたはテキスト応答を生成する必要がある場合、応答に時間がかかったり、思考フェーズ中にタイムアウトになったりすることがあります。

パフォーマンスを向上させるために、次のいずれかまたは複数のアクションを試してください。

• クエリー履歴を確認して、実行の遅いクエリーを特定してください。多くのパフォーマンスの問題は、Genie Agentの構成を変更するのではなく、生成されたSQLクエリーを最適化することで解決できます。SQLウェアハウスのクエリー履歴でクエリーの実行時間とクエリープランを確認し、ボトルネックと最適化の機会を特定してください。
• 信頼できるアセットまたはビューを使用して、複雑なクエリーをカプセル化します。信頼できるアセットを参照してください。
• 可能な場合は常に、SQLクエリーの長さを短縮してください。
• Genieの応答が遅くなったり、失敗するようになった場合は、新しいチャットを起動してください。

ミッションクリティカルな質問に対する信頼性の低い応答

信頼できるアセットを使用して、ユーザーが尋ねると予想される特定の質問に対して検証済みの回答を提供します。信頼できるアセットを参照してください。

トークン制限警告

トークンは、Genieが言語を処理および理解するために使用するテキストの基本単位です。Genie Agent内のテキストの命令とメタデータはトークンに変換されます。エージェントがトークン制限に近づくと、警告が表示されます。Genieはコンテキストフィルタリングを使用して、質問に最も関連性が高いと見なすトークンに優先順位を付けます。警告が表示された場合でも応答は生成されますが、重要なコンテキストがフィルタリングされると品質が低下する可能性があります。トークン制限を超過した場合、Genie Agentでメッセージを送受信できなくなります。

トークン数を削減するために、以下の方法をご検討ください。

• 不要な列を削除する ：テーブル内の不要な列は、トークンの使用量に大きく影響する可能性があります。可能な場合は、生テーブルから冗長なフィールドや不要なフィールドを除外するビューを作成してください。Genie Agentで不要な列を非表示にすることもできます。「関連する列の表示または非表示」を参照してください。
• 列の説明を簡素化する： 列の説明は重要ですが、列名によってすでに伝えられている情報との重複は避けてください。例えば、列名が account_name の場合、「アカウント名」のような説明は冗長となるため、省略できます。
• Genie Agentでの列メタデータの編集 ：列メタデータで説明を編集し、同義語を提供する方法については、列メタデータの編集を参照してください。
• SQLクエリーの例を整理します ：多様なSQLクエリーの例を含め、さまざまな種類の質問に対応できるようにしますが、重複または冗長な例は削除します。
• **指示を簡素化する**: 指示が明確で簡潔であることを確認してください。不必要な言葉は避けてください。

お客様のアカウントは Geo 間処理に対応していません

Genie は Databricks によって管理される指定サービスです。指定サービスは Databricks Geos を使用してデータ所在地を管理します。データは、一部のリージョンではワークスペースと同じ Geo では処理できません。ワークスペースがそれらのリージョンのいずれかにある場合、Geo 間処理はアカウント管理者によって有効にする必要があります。

最後のエージェント作成者はワークスペースから削除されます

Genie Agentは、エージェントのSQL Warehouseを最も最近構成した作成者によって埋め込まれたコンピュート認証情報を使用して、すべてのクエリーを処理します。作成者がワークスペースから削除された場合、埋め込まれた認証情報は無効になり、エージェントを使用するすべてのユーザーのクエリーが失敗します。

エージェントを復元するには、Genie Agentに対する少なくともCAN EDIT権限を持つ別のユーザーにエージェントのSQLウェアハウスを再構成してもらってください。warehouseの選択を保存すると、編集中のユーザーのコンピュート資格情報が削除された作成者のものに代わって埋め込まれます。設定を構成するを参照してください。