レビューアプリを使用して、生成AIアプリの人間によるレビューを行います

この記事では、レビュー アプリを使用して、対象分野の専門家 (SME) からフィードバックを収集する方法について説明します。レビュー アプリを使用して、次の操作を実行できます。

• 関係者が本番運用前の生成AI アプリとチャットしてフィードバックを提供できるようにします。
• Unity Catalog の Delta テーブルによってサポートされる評価データセットを作成します。
• SME を活用して、その評価データセットを拡張し、反復します。
• SMEを活用して本番運用のトレースにラベルを付け、生成 AI アプリの品質を理解します。

人間による評価では何が起こるのでしょうか?

Databricks レビュー アプリは、関係者が対話できる環境、つまり、会話をしたり、質問をしたり、フィードバックを提供したりできる環境をステージングします。

レビューアプリを使用するには、主に2つの方法があります。

1. ボットとチャットする : 質問、回答、フィードバックを推論テーブルに収集して、AI 生成アプリのパフォーマンスをさらに分析できるようにします。このように、レビューアプリは、アプリケーションが提供する回答の品質と安全性を確保するのに役立ちます。
2. セッションでの回答のラベル付け : ラベル付けセッションで SME からの フィードバック と 期待 を収集し、MLFLow 実行で保存します。必要に応じて、これらのラベルを評価データセットに同期できます。

必要条件

• 開発者は、 databricks-agents SDK をインストールして、アクセス許可を設定し、レビュー アプリを構成する必要があります。

Python

  %pip install databricks-agents
  dbutils.library.restartPython()

• ボットとのチャットの場合:

  • 推論テーブル は、エージェントにサービスを提供するエンドポイントで有効にする必要があります。
  • 各人間のレビュー担当者は、レビュー アプリのワークスペースにアクセスできるか、SCIM を使用して Databricks アカウントに同期されている必要があります。次のセクション「 レビュー アプリを使用するためのアクセス許可を設定する」を参照してください。

• ラベリングセッションの場合:

  • 各人間のレビュー担当者は、レビュー アプリ ワークスペースにアクセスできる必要があります。

レビュー アプリを使用するためのアクセス許可を設定する

注記

• ボットとチャットするために、人間のレビュー担当者はワークスペースにアクセスする 必要はありません 。
• ラベル付けセッションの場合、人間のレビュー担当者 は ワークスペースにアクセスする必要があります。

「ボットとチャットする」の権限を設定する

• ワークスペースにアクセスできないユーザーの場合、アカウント管理者はアカウント レベルの SCIM プロビジョニングを使用して、ユーザーとグループを ID プロバイダーから Databricks アカウントに自動的に同期します。また、これらのユーザーとグループを手動で登録して、 Databricksで ID を設定するときにアクセス権を付与することもできます。 「SCIM を使用した ID プロバイダーからのユーザーとグループの同期」を参照してください。
• レビュー アプリを含むワークスペースへのアクセス権を既に持っているユーザーの場合、追加の構成は必要ありません。

次のコード例は、 agents.deployを使用してデプロイされたモデルに対するアクセス許可をユーザーに付与する方法を示しています。users パラメーターは、Eメール アドレスの一覧を受け取ります。

Python

from databricks import agents

# Note that <user_list> can specify individual users or groups.
agents.set_permissions(model_name=<model_name>, users=[<user_list>], permission_level=agents.PermissionLevel.CAN_QUERY)

注記

ワークスペース内のすべてのユーザーに権限を付与するには、 users=["users"]を設定します。

ラベル付けセッションのアクセス許可を設定する

ユーザーには、ラベル付けセッションを作成して assigned_users 引数を指定すると、適切なアクセス許可 (エクスペリメントへの書き込みアクセス権とデータセットへの読み取りアクセス権) が自動的に付与されます。詳しくは、以下の「 ラベル付けセッションを作成してレビュー用に送信する 」をご覧ください。

レビュー アプリを作成する

自動的に使用する agents.deploy()

agents.deploy()を使用して 生成AI アプリをデプロイすると、レビュー アプリが自動的に有効になり、デプロイされます。コマンドの出力には、レビュー アプリの URL が表示されます。AI gen アプリ ("エージェント" とも呼ばれます) のデプロイに関する情報については、「 AI アプリケーションを生成するためのエージェントをデプロイする」を参照してください。

注記

エージェントは、エンドポイントが完全にデプロイされるまで、レビューアプリのUIに表示されません。

レビュー アプリの UI へのリンクを紛失した場合は、 get_review_app()を使用して見つけることができます。

Python

import mlflow
from databricks.agents import review_app

# The review app is tied to the current MLFlow experiment.
mlflow.set_experiment("same_exp_used_to_deploy_the_agent")
my_app = review_app.get_review_app()
print(my_app.url)
print(my_app.url + "/chat") # For "Chat with the bot".

Python API を手動で使用する

次のコード スニペットは、レビュー アプリを作成してモデルサービングに関連付ける方法を示しています ボットとチャットするためのエンドポイント。 ラベリングセッションの作成については、以下を参照してください。

• ラベル付けセッションを作成し、 評価データセットのラベル付けのためにレビューに送信します。
• トレースにラベルを付けるためのトレースに関するフィードバックを収集します。これにはライブエージェントは必要ありません。

Python

from databricks.agents import review_app

# The review app is tied to the current MLFlow experiment.
my_app = review_app.get_review_app()

# TODO: Replace with your own serving endpoint.
my_app.add_agent(
    agent_name="llama-70b",
    model_serving_endpoint="databricks-meta-llama-3-3-70b-instruct",
)
print(my_app.url + "/chat") # For "Chat with the bot".

概念

データセット

データセットは、生成 AI アプリケーションを評価するために使用される例のコレクションです。データセット レコードには、生成 AI アプリケーションへの入力と、オプションで 期待 値 (expected_facts や guidelinesなどのグラウンド トゥルース ラベル) が含まれます。データセットは MLFlow エクスペリメントにリンクされており、 mlflow.evaluate()への入力として直接使用できます。 データセットは、Unity Catalog の Delta テーブルによってサポートされ、Delta テーブルによって定義されたアクセス許可を継承します。データセットを作成するには、「 データセットの作成」を参照してください。

入力列とエクスペクテーション列のみを示す評価データセットの例:

評価データセットには、次のスキーマがあります。

列	データ型	説明
dataset_record_id	string	レコードの一意の識別子。
inputs	string	シリアル化された JSON としての評価への入力 dict<str, Any>
expectations	string	シリアル化された JSON の期待値 dict<str, Any>
create_time	timestamp	レコードが作成された時刻。
created_by	string	レコードを作成したユーザー。
last_update_time	timestamp	レコードが最後に更新された時刻。
last_updated_by	string	レコードを最後に更新したユーザー。
source	struct	データセットレコードのソース
source.human	struct	ソースが人間からのものである場合に定義されます
source.human.user_name	string	レコードに関連付けられているユーザーの名前。
source.document	string	レコードがドキュメントから合成されたときに定義されます
source.document.doc_uri	string	ドキュメントの URI。
source.document.content	string	ドキュメントの内容。
source.trace	string	レコードがトレースから作成されたときに定義されます
source.trace.trace_id	string	トレースの一意の識別子。
tags	map	データセットレコードのキーと値のタグ

ラベリングセッション

LabelingSessionは、レビューアプリのUIでSMEによってラベル付けされるトレースまたはデータセットレコードの有限セットです。トレースは、本番運用のアプリケーションの推論テーブル、または MLFlow エクスペリメントのオフライン・トレースから取得できます。 結果は MLFlow 実行として保存されます。ラベルは MLFlow トレースに Assessment秒として保存されます。「エクスペクテーション」のラベルは、評価データセットに同期して戻すことができます。

評価とラベル

SME がトレースにラベルを付けると、 Assessmentはトレースの Trace.info.assessments フィールドに書き込まれます。Assessmentには、次の 2 つのタイプがあります。

• expectation: 正しいトレースに何が必要かを表すラベル。 例: expected_facts は、理想的な応答に存在するべき事実を表す expectation ラベルとして使用できます。 これらの expectation ラベルは、評価データセットに同期して、 mlflow.evaluate()で使用できます。
• feedback: トレースに対する単純なフィードバック ("thumbs up" や "thumbs down" など) を表すラベル、または自由形式のコメント。タイプ feedback の Assessmentは、特定の MLFLow トレースを人間が評価するものであるため、評価データセットでは使用されません。これらの評価は、 mlflow.search_traces()で読み取ることができます。

データセット

このセクションでは、次の操作を行う方法について説明します。

• データセットを作成し、SME を使用せずに評価に使用します。
• SME にラベル付けセッションを要求して、より優れた評価データセットをキュレーションします。

データセットの作成

次の例では、 データセット を作成し、評価を挿入します。合成評価を使用してデータセットをシードするには、「 評価セットの合成」を参照してください。

Python

from databricks.agents import datasets
import mlflow

# The following call creates an empty dataset. To delete a dataset, use datasets.delete_dataset(uc_table_name).
dataset = datasets.create_dataset("cat.schema.my_managed_dataset")

# Optionally, insert evaluations.
eval_set = [{
  "request": {"messages": [{"role": "user", "content": "What is the capital of France?"}]},
  "guidelines": ["The response must be in English", "The response must be clear, coherent, and concise"],
}]

dataset.insert(eval_set)

このデータセットのデータは、Unity Catalog の Delta テーブルによってサポートされ、Catalog Explorer に表示されます。

注記

名前付きガイドライン (ディクショナリを使用) は、現在、ラベル付けセッションではサポートされていません。

評価のためのデータセットの使用

次の例では、評価データセットを使用して単純なシステム プロンプト エージェントを評価し、Unity Catalog からデータセットを読み取ります。

Python

import mlflow
from mlflow.deployments import get_deploy_client

# Define a very simple system-prompt agent to test against our evaluation set.
@mlflow.trace(span_type="AGENT")
def llama3_agent(request):
  SYSTEM_PROMPT = """
    You are a chatbot that answers questions about Databricks.
    For requests unrelated to Databricks, reject the request.
  """
  return get_deploy_client("databricks").predict(
    endpoint="databricks-meta-llama-3-3-70b-instruct",
    inputs={
      "messages": [
        {"role": "system", "content": SYSTEM_PROMPT},
        *request["messages"]
      ]
    }
  )

evals = spark.read.table("cat.schema.my_managed_dataset")

mlflow.evaluate(
  data=evals,
  model=llama3_agent,
  model_type="databricks-agent"
)

ラベル付けセッションを作成し、レビュー用に送信する

次の例では、ReviewApp.create_labeling_session を使用して上記のデータセットからLabelingSession を作成します。セッションの構成 ReviewApp.label_schemasを利用して専門家からguidelines・expected_factsを回収するフィールド。また、ReviewApp.create_label_schema を使用してカスタムラベルスキーマを作成することもできます

注記

• ラベリングセッションを作成するときに割り当てられるユーザーは以下のとおりです。

  • MLFlow エクスペリメントに WRITE 権限が付与されました。
  • レビューアプリに関連付けられている任意のモデルサービングエンドポイントに対するQUERY権限を付与します。

• ラベリングセッションにデータセットを追加すると、割り当てられたユーザーには、ラベリングセッションのシードに使用されるデータセットのデルタテーブルに対するSELECT権限が付与されます。

ワークスペース内のすべてのユーザーに権限を付与するには、 assigned_users=["users"]を設定します。

Python

from databricks.agents import review_app
import mlflow

# The review app is tied to the current MLFlow experiment.
my_app = review_app.get_review_app()

# You can use the following code to remove any existing agents.
# for agent in list(my_app.agents):
#     my_app.remove_agent(agent.agent_name)

# Add the llama3 70b model serving endpoint for labeling. You should replace this with your own model serving endpoint for your
# own agent.
# NOTE: An agent is required when labeling an evaluation dataset.
my_app.add_agent(
    agent_name="llama-70b",
    model_serving_endpoint="databricks-meta-llama-3-3-70b-instruct",
)

# Create a labeling session and collect guidelines and/or expected-facts from SMEs.
# Note: Each assigned user is given QUERY access to the serving endpoint above and write access.
# to the MLFlow experiment.
my_session = my_app.create_labeling_session(
  name="my_session",
  agent="llama-70b",
  assigned_users = ["email1@company.com", "email2@company.com"],
  label_schemas = [review_app.label_schemas.GUIDELINES, review_app.label_schemas.EXPECTED_FACTS]
)

# Add the records from the dataset to the labeling session.
# Note: Each assigned user above is given SELECT access to the UC delta table.
my_session.add_dataset("cat.schema.my_managed_dataset")

# Share the following URL with your SMEs for them to bookmark. For the given review app linked to an experiment, this URL never changes.
print(my_app.url)

# You can also link them directly to the labeling session URL, however if you
# request new labeling sessions from SMEs there will be new URLs. Use the review app
# URL above to keep a permanent URL.
print(my_session.url)

この時点で、上記の URL を SME に送信できます。

SME がラベル付けを行っている間は、次のコードを使用してラベル付けの状態を表示できます。

Python

mlflow.search_traces(run_id=my_session.mlflow_run_id)

ラベリングセッションのエクスペクテーションをデータセットに同期する

SME がラベル付けを完了したら、LabelingSession.sync_expectations を使用して expectation ラベルをデータセットに同期し直すことができます。タイプが expectation のラベルの例としては、 GUIDELINES、 EXPECTED_FACTS、またはタイプ expectationの独自のカスタムラベルスキーマがあります。

Python

my_session.sync_expectations(to_dataset="cat.schema.my_managed_dataset")
display(spark.read.table("cat.schema.my_managed_dataset"))

これで、次の評価データセットを使用できるようになりました。

Python

eval_results = mlflow.evaluate(
    model=llama3_agent,
    data=dataset.to_df(),
    model_type="databricks-agent"
)

トレースに関するフィードバックの収集

このセクションでは、次のいずれかから取得できる MLFlow トレース オブジェクトのラベルを収集する方法について説明します。

• MLFlow エクスペリメントまたは実行。
• 推論テーブル。
• 任意の MLFlow Python トレースオブジェクト。

MLFlow エクスペリメントまたは実行からフィードバックを収集する

この例では、SME によってラベル付けされる一連のトレースを作成します。

Python

import mlflow
from mlflow.deployments import get_deploy_client

@mlflow.trace(span_type="AGENT")
def llama3_agent(messages):
  SYSTEM_PROMPT = """
    You are a chatbot that answers questions about Databricks.
    For requests unrelated to Databricks, reject the request.
  """
  return get_deploy_client("databricks").predict(
    endpoint="databricks-meta-llama-3-3-70b-instruct",
    inputs={"messages": [{"role": "system", "content": SYSTEM_PROMPT}, *messages]}
  )

# Create a trace to be labeled.
with mlflow.start_run(run_name="llama3") as run:
    run_id = run.info.run_id
    llama3_agent([{"content": "What is databricks?", "role": "user"}])
    llama3_agent([{"content": "How do I set up a SQL Warehouse?", "role": "user"}])

トレースのラベルを取得し、それらからラベル付けセッションを作成できます。この例では、Agent の応答に関する "形式的な" フィードバックを収集するために、1 つのラベル スキーマを使用してラベル付けセッションを設定します。SME からのラベルは、MLFlow トレースに 評価 として保存されます。

スキーマ入力のその他の種類については、「 databricks-agents SDK」を参照してください。

Python

# The review app is tied to the current MLFlow experiment.
my_app = review_app.get_review_app()

# Use the run_id from above.
traces = mlflow.search_traces(run_id=run_id)

formality_label_schema = my_app.create_label_schema(
  name="formal",
  # Type can be "expectation" or "feedback".
  type="feedback",
  title="Is the response formal?",
  input=review_app.label_schemas.InputCategorical(options=["Yes", "No"]),
  instruction="Please provide a rationale below.",
  enable_comment=True
)

my_session = my_app.create_labeling_session(
  name="my_session",
  # NOTE: An `agent` is not required. If you do provide an Agent, your SME can ask follow up questions in a converstion and create new questions in the labeling session.
  assigned_users=["email1@company.com", "email2@company.com"],
  # More than one label schema can be provided and the SME will be able to provide information for each one.
  # We use only the "formal" schema defined above for simplicity.
  label_schemas=["formal"]
)
# NOTE: This copies the traces into this labeling session so that labels do not modify the original traces.
my_session.add_traces(traces)

# Share the following URL with your SMEs for them to bookmark. For the given review app, linked to an experiment, this URL will never change.
print(my_app.url)

# You can also link them directly to the labeling session URL, however if you
# request new labeling sessions from SMEs there will be new URLs. Use the review app
# URL above to keep a permanent URL.
print(my_session.url)

SME がラベル付けを完了すると、結果として得られるトレースと評価は、ラベル付けセッションに関連付けられた実行の一部になります。

Python

mlflow.search_traces(run_id=my_session.mlflow_run_id)

これらの評価を使用して、モデルを改善したり、評価データセットを更新したりできるようになりました。

推論テーブルからフィードバックを収集する

この例では、推論テーブル (リクエストペイロードログ) からラベリングセッションにトレースを直接追加する方法を示します。

Python

# CHANGE TO YOUR PAYLOAD REQUEST LOGS TABLE
PAYLOAD_REQUEST_LOGS_TABLE = "catalog.schema.my_agent_payload_request_logs"
traces = spark.table(PAYLOAD_REQUEST_LOGS_TABLE).select("trace").limit(3).toPandas()

my_session = my_app.create_labeling_session(
  name="my_session",
  assigned_users = ["email1@company.com", "email2@company.com"],
  label_schemas=[review_app.label_schemas.EXPECTED_FACTS]
)

# NOTE: This copies the traces into this labeling session so that labels do not modify the original traces.
my_session.add_traces(traces)
print(my_session.url)

ノートブックの例

次のノートブックは、Mosaic AI Agent Evaluation でデータセットとラベリング セッションを使用するさまざまな方法を示しています。

レビュー アプリの例 ノートブック

Open notebook in new tab

エージェント評価のカスタムメトリクス、ガイドライン、およびドメインエキスパートラベルノートブック

Open notebook in new tab