メインコンテンツまでスキップ

基盤モデルを使用する

この記事では、基盤モデルのクエリ要求を記述し、それをモデルサービングエンドポイントに送信する方法について説明します。 Databricks によってホストされている基盤モデルと、Databricks の外部でホストされている基盤モデルに対してクエリを実行できます。

従来の ML モデルまたは Python モデルのクエリ要求については、 カスタム モデルのクエリ サービング エンドポイントを参照してください。

Mosaic AI Model Serving は、基盤モデルにアクセスするための基盤モデル API と外部モデルをサポートしています。モデルサービングは、統一されたOpenAI互換の API とクエリ SDK を使用します。 これにより、エクスペリメントを行い、サポートされているクラウドやプロバイダー間での本番運用のための基盤モデルをカスタマイズすることが可能になります。

Mosaic AI Model Serving は、基盤モデルまたは外部モデルを提供するエンドポイントにスコアリング要求を送信するための次のオプションを提供します。

メソッド

詳細

オープンAIクライアント

OpenAI クライアントを使用して、 Mosaic AI Model Servingエンドポイントによってホストされているモデルをクエリします。 model入力としてモデルサーバーのエンドポイント名を指定します。 基盤モデルAPIまたは外部モデルによって提供されるチャット、埋め込み、補完モデルがサポートされます。

SQL 関数

ai_query SQL 関数を使用して、SQL から直接モデル推論を呼び出します。例: 基盤モデルのクエリを参照してください。

サービングUI

サービングエンドポイント ページから エンドポイントのクエリー を選択します。JSON形式のモデル入力データを挿入し、 リクエストを送信 をクリックします。 モデルに入力例がログに記録されている場合は、 例を表示 を使用して読み込みます。

REST API

REST API を使用してモデルを呼び出し、クエリを実行します。 詳細は POST /serving-endpoints/{name}/invocations を参照してください。 複数のモデルを提供するエンドポイントへの要求のスコアリングについては、エンドポイントの背後にある個々のモデルのクエリを参照してください。

MLflow Deployments SDK

MLflow Deployments SDK の predict() 関数を使用して、モデルに対してクエリを実行します。

Databricks Python SDK

Databricks Python SDK は、REST API の上位にあるレイヤーです。 認証などの低レベルの詳細を処理するため、モデルとの対話が容易になります。

必要条件​

important

本番運用シナリオのセキュリティのベスト プラクティスとして、 Databricks では、本番運用中の認証に マシン間 OAuth トークン を使用することをお勧めします。

テストと開発のために、 Databricks ワークスペース ユーザーではなく 、サービスプリンシパル に属する個人用アクセス トークンを使用することをお勧めします。 サービスプリンシパルのトークンを作成するには、「 サービスプリンシパルのトークンの管理」を参照してください。

パッケージのインストール​

クエリ方法を選択したら、まず適切なパッケージをクラスターにインストールする必要があります。

To use the OpenAI client, the databricks-sdk[openai] package needs to be installed on your cluster. Databricks SDK provides a wrapper for constructing the OpenAI client with authorization automatically configured to query generative AI models. Run the following in your notebook or your local terminal:

!pip install databricks-sdk[openai]>=0.35.0

The following is only required when installing the package on a Databricks Notebook

Python
dbutils.library.restartPython()

テキスト補完モデルのクエリ​

important

Querying text completion models made available using Foundation Model APIs pay-per-token using the OpenAI client is not supported. Only querying external models using the OpenAI client is supported as demonstrated in this section.

To use the OpenAI client, specify the model serving endpoint name as the model input. The following example queries the claude-2 completions model hosted by Anthropic using the OpenAI client. To use the OpenAI client, populate the model field with the name of the model serving endpoint that hosts the model you want to query.

This example uses a previously created endpoint, anthropic-completions-endpoint, configured for accessing external models from the Anthropic model provider. See how to create external model endpoints.

See Supported models for additional models you can query and their providers.

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
openai_client = w.serving_endpoints.get_open_ai_client()

completion = openai_client.completions.create(
model="anthropic-completions-endpoint",
prompt="what is databricks",
temperature=1.0
)
print(completion)

以下は、完了モデルで想定される要求形式です。 外部モデルの場合、特定のプロバイダーとエンドポイント構成に有効な追加のパラメーターを含めることができます。 追加のクエリ・パラメーターを参照してください。

Bash
{
  "prompt": "What is mlflow?",
  "max_tokens": 100,
  "temperature": 0.1,
  "stop": [
    "Human:"
  ],
  "n": 1,
  "stream": false,
  "extra_params":
  {
    "top_p": 0.9
  }
}

想定される応答形式は次のとおりです。

JSON
{
  "id": "cmpl-8FwDGc22M13XMnRuessZ15dG622BH",
  "object": "text_completion",
  "created": 1698809382,
  "model": "gpt-3.5-turbo-instruct",
  "choices": [
    {
      "text": "MLflow is an open-source platform for managing the end-to-end machine learning lifecycle. It provides tools for tracking experiments, managing and deploying models, and collaborating on projects. MLflow also supports various machine learning frameworks and languages, making it easier to work with different tools and environments. It is designed to help data scientists and machine learning engineers streamline their workflows and improve the reproducibility and scalability of their models.",
      "index": 0,
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 83,
    "total_tokens": 88
  }
}

チャット完了モデルのクエリ​

チャット モデルに対してクエリを実行する例を次に示します。 この例は、モデル サービス機能 (基盤モデルAPIまたは外部モデル) のいずれかを使用して使用可能になったチャット モデルのクエリに適用されます。

バッチ推論の例については、「AI関数を使用したバッチLLM 推論の実行 」を参照してください。

The following is a chat request for the Meta Llama 3.3 70B Instruct model made available by the Foundation Model APIs pay-per-token endpoint, databricks-meta-llama-3-3-70b-instruct in your workspace.

To use the OpenAI client, specify the model serving endpoint name as the model input.

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
openai_client = w.serving_endpoints.get_open_ai_client()

response = openai_client.chat.completions.create(
    model="databricks-meta-llama-3-3-70b-instruct",
    messages=[
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is a mixture of experts model?",
      }
    ],
    max_tokens=256
)

To query foundation models outside of your workspace, you must use the OpenAI client directly. You also need your Databricks workspace instance to connect the OpenAI client to Databricks. The following example assumes you have a Databricks API token and openai installed on your compute.

Python

import os
import openai
from openai import OpenAI

client = OpenAI(
    api_key="dapi-your-databricks-token",
    base_url="https://example.staging.cloud.databricks.com/serving-endpoints"
)

response = client.chat.completions.create(
    model="databricks-meta-llama-3-3-70b-instruct",
    messages=[
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is a mixture of experts model?",
      }
    ],
    max_tokens=256
)

例として、REST API を使用する場合のチャットモデルの想定されるリクエスト形式を次に示します。 外部モデルの場合、特定のプロバイダーとエンドポイント構成に有効な追加のパラメーターを含めることができます。 追加のクエリ・パラメーターを参照してください。

Bash
{
  "messages": [
    {
      "role": "user",
      "content": "What is a mixture of experts model?"
    }
  ],
  "max_tokens": 100,
  "temperature": 0.1
}

以下は、REST API を使用して行われたリクエストに対して想定されるレスポンス形式です。

JSON
{
  "model": "databricks-meta-llama-3-3-70b-instruct",
  "choices": [
    {
      "message": {},
      "index": 0,
      "finish_reason": null
    }
  ],
  "usage": {
    "prompt_tokens": 7,
    "completion_tokens": 74,
    "total_tokens": 81
  },
  "object": "chat.completion",
  "id": null,
  "created": 1698824353
}

推論モデル​

Mosaic AI Model Serving は、推論モデルと対話するための統一 API を提供します。推論により、基盤モデルは複雑なタスクに取り組むための強化された能力を得ることができます。 また、一部のモデルは、最終的な答えを出す前に、段階的な思考プロセスを明らかにすることで透明性を提供します。

モデルには、推論のみのモデルとハイブリッドの 2 種類があります。OpenAI oシリーズのような推論のみのモデルは、応答に常に内部推論を使用します。databricks-claude-3-7-sonnetなどのハイブリッド モデルは、高速で即時の返信と、必要に応じてより深い推論の両方をサポートします。

ハイブリッド モデルで推論を有効にするには、thinking パラメーターを含め、モデルが内部思考に使用できるトークンの数を制御する budget_tokens 値を設定します。予算を高くすると、複雑なタスクの品質を向上させることができますが、32Kを超える使用量は異なる場合があります。budget_tokens は max_tokens未満である必要があります。

すべての推論モデルは、 チャット完了 エンドポイントを介してアクセスされます。

Python
from openai import OpenAI
import base64
import httpx

client = OpenAI(
  api_key=os.environ.get('YOUR_DATABRICKS_TOKEN'),
  base_url=os.environ.get('YOUR_DATABRICKS_BASE_URL')
  )

response = client.chat.completions.create(
    model="databricks-claude-3-7-sonnet",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
    max_tokens=20480,
    extra_body={
        "thinking": {
            "type": "enabled",
            "budget_tokens": 10240
        }
    }
)

msg = response.choices[0].message
reasoning = msg.content[0]["summary"][0]["text"]
answer = msg.content[1]["text"]

print("Reasoning:", reasoning)
print("Answer:", answer)

API レスポンスには、思考コンテンツブロックとテキストコンテンツブロックの両方が含まれます。

Python
ChatCompletionMessage(
    role="assistant",
    content=[
        {
            "type": "reasoning",
            "summary": [
                {
                    "type": "summary_text",
                    "text": ("The question is asking about the scientific explanation for why the sky appears blue... "),
                    "signature": ("EqoBCkgIARABGAIiQAhCWRmlaLuPiHaF357JzGmloqLqkeBm3cHG9NFTxKMyC/9bBdBInUsE3IZk6RxWge...")
                }
            ]
        },
        {
            "type": "text",
            "text": (
                "# Why the Sky Is Blue\n\n"
                "The sky appears blue because of a phenomenon called Rayleigh scattering. Here's how it works..."
            )
        }
    ],
    refusal=None,
    annotations=None,
    audio=None,
    function_call=None,
    tool_calls=None
)

複数のターンにわたる推論の管理​

このセクションは、 databricks-claude-3-7-sonnet modelに固有のものです。

マルチターンの会話では、最後のアシスタントターンまたはツール使用セッションに関連付けられた推論ブロックのみがモデルに表示され、入力トークンとしてカウントされます。

推論トークンをモデルに戻さない場合 (たとえば、前の手順で推論する必要がない場合) は、推論ブロックを完全に省略できます。例えば：

Python
response = client.chat.completions.create(
    model="databricks-claude-3-7-sonnet",
    messages=[
        {"role": "user", "content": "Why is the sky blue?"},
        {"role": "assistant", "content": text_content},
        {"role": "user", "content": "Can you explain in a way that a 5-year-old child can understand?"}
    ],
    max_tokens=20480,
    extra_body={
        "thinking": {
            "type": "enabled",
            "budget_tokens": 10240
        }
    }
)

answer = response.choices[0].message.content[1]["text"]
print("Answer:", answer)

ただし、モデルが前の推論プロセスを推論する必要がある場合 (たとえば、中間推論を表示するエクスペリエンスを構築している場合) は、前のターンの推論ブロックを含む、変更されていない完全なアシスタント メッセージを含める必要があります。完全なアシスタントメッセージでスレッドを続ける方法は次のとおりです。

Python
assistant_message = response.choices[0].message

response = client.chat.completions.create(
    model="databricks-claude-3-7-sonnet",
    messages=[
        {"role": "user", "content": "Why is the sky blue?"},
        {"role": "assistant", "content": text_content},
        {"role": "user", "content": "Can you explain in a way that a 5-year-old child can understand?"},
        assistant_message,
        {"role": "user", "content": "Can you simplify the previous answer?"}
    ],
    max_tokens=20480,
    extra_body={
        "thinking": {
            "type": "enabled",
            "budget_tokens": 10240
        }
    }
)

answer = response.choices[0].message.content[1]["text"]
print("Answer:", answer)

推論モデルはどのように機能しますか?​

推論モデルでは、標準の入力トークンと出力トークンに加えて、特別な推論トークンが導入されます。これらのトークンにより、モデルはプロンプトを通じて「考え」、プロンプトを分解し、さまざまな応答方法を検討できます。この内部推論プロセスの後、モデルは最終的な回答を目に見える出力トークンとして生成します。databricks-claude-3-7-sonnetのような一部のモデルは、これらの推論トークンをユーザーに表示する一方で、OpenAI o シリーズなどの他のモデルはそれらを破棄し、最終出力で公開しません。

サポートされているモデル​

基盤モデル API (Databricks-hosted)​

  • databricks-claude-3-7-sonnet

外部モデル​

  • 推論機能を備えたOpenAIモデル
  • Anthropic クロードは推論能力を持つモデルです
  • 推論機能を備えたGoogle Geminiモデル

ビジョンモデル​

Mosaic AI Model Serving は、さまざまな基盤モデルを使用して画像を理解および分析するための統合 API を提供し、強力なマルチモーダル機能のロックを解除します。この機能は、Databricks基盤モデルAPIs の一部として、外部 モデル を提供するサービス エンドポイントの一部として、選択したホスト モデルを通じて使用できます。

コード例​

Python

from openai import OpenAI
import base64
import httpx

client = OpenAI(
  api_key=os.environ.get('YOUR_DATABRICKS_TOKEN'),
  base_url=os.environ.get('YOUR_DATABRICKS_BASE_URL')
  )

# encode image
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

# OpenAI request
completion = client.chat.completions.create(
    model="databricks-claude-3-7-sonnet",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "what's in this image?"},
                {
                    "type": "image_url",
                    "image_url": {"url": f"data:image/jpeg;base64,{image_data}"},
                },
            ],
        }
    ],
)

print(completion.choices[0].message.content)

Chat Completions API は複数の画像入力をサポートしているため、モデルは各画像を分析し、すべての入力から情報を合成してプロンプトへの応答を生成できます。

Python

from openai import OpenAI
import base64
import httpx

client = OpenAI(
api_key=os.environ.get('YOUR_DATABRICKS_TOKEN'),
base_url=os.environ.get('YOUR_DATABRICKS_BASE_URL')
)

# Encode multiple images

image1_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
image1_data = base64.standard_b64encode(httpx.get(image1_url).content).decode("utf-8")

image2_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
image2_data = base64.standard_b64encode(httpx.get(image1_url).content).decode("utf-8")

# OpenAI request

completion = client.chat.completions.create(
model="databricks-claude-3-7-sonnet",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "What are in these images? Is there any difference between them?"},
{
"type": "image_url",
"image_url": {"url": f"data:image/jpeg;base64,{image1_data}"},
},
{
"type": "image_url",
"image_url": {"url": f"data:image/jpeg;base64,{image2_data}"},
},
],
}
],
)

print(completion.choices[0].message.content)

サポートされているモデル​

基盤モデル API (Databricks-hosted)​

  • databricks-claude-3-7-sonnet

外部モデル​

  • ビジョン機能を備えたOpenAIGPTおよびoシリーズモデル
  • Anthropic 視覚機能を備えたクロードモデル
  • ビジョン機能を備えたGoogle Geminiモデル
  • OpenAI APIと互換性のあるビジョン機能を備えた他の外部基盤モデルもサポートされています。

入力画像の要件​

このセクションは、基盤モデル APIsにのみ適用されます。 外部モデルについては、プロバイダーのドキュメントを参照してください。

リクエストごとに複数の画像​

  • 最大20枚の画像 で Claude.AI
  • API リクエストの最大 100 枚の画像
  • 提供されたすべての画像はリクエストで処理されるため、それらを比較または対比するのに役立ちます。

サイズの制限​

  • 8000x8000 px より大きい画像は拒否されます。
  • 1 つの API リクエストで 20 を超える画像が送信された場合、 画像あたりの最大許容サイズは 2000 x 2000 px です。

画像のサイズ変更に関する推奨事項​

  • 最適なパフォーマンスを得るには、画像が大きすぎる場合は、アップロードする前にサイズを変更します。
  • 画像の 長辺が 1568 ピクセルを超える 場合、または サイズが ~1,600 トークンを超える 場合、アスペクト比を維持しながら 自動的に縮小されます 。
  • 非常に小さい画像 ( 任意のエッジで 200 ピクセル 未満)は 、パフォーマンスを低下させ る可能性があります。
  • レイテンシー を短縮するには、画像を 1.15 メガピクセル 以内、両次元で最大 1568 ピクセル に保ちます。

画質に関する考慮事項​

  • サポートされている形式: JPEG、PNG、GIF、WebPです。
  • 明快： ぼやけた画像やピクセル化された画像は避けてください。
  • 画像内のテキスト:
    • テキストが 読みやすく 、小さすぎないことを確認します。
    • テキストを拡大するためだけに主要な視覚的コンテキストを切り取ることは避けてください。

コストの計算​

このセクションは、基盤モデル APIsにのみ適用されます。 外部モデルについては、プロバイダーのドキュメントを参照してください。

要求から基盤モデルへの各イメージは、トークンの使用量に追加されます。

トークンの数と見積もり

サイズ変更が不要な場合は、次のようにトークンを見積もります。
トークン = (幅 px × 高さ px) / 750

さまざまな画像サイズのおおよそのトークン数:

画像サイズ

トークン

200×200ピクセル (0.04 MP)

~54

1000×1000ピクセル (1メガピクセル)

~1334年

1092×1092 ピクセル(1.19メガピクセル)

~1590年

画像理解の限界​

このセクションは、基盤モデル APIsにのみ適用されます。 外部モデルについては、プロバイダーのドキュメントを参照してください。

Databricks での Claude モデルの高度な画像理解には制限があります。

  • 人物の識別 : 画像内で人物を特定したり、名前を付けたりすることはできません。
  • 精度 : 低品質、回転した画像、または非常に小さい画像 (<200 px) を誤って解釈する可能性があります。
  • 空間的推論 : アナログ時計やチェスの位置を読み取るなど、正確なレイアウトに苦労しています。
  • カウント : おおよそのカウントを提供しますが、多くの小さなオブジェクトでは不正確になる場合があります。
  • AI が生成した画像 : 合成画像や偽の画像を確実に検出することはできません。
  • 不適切なコンテンツ : 露骨な表現を含む画像やポリシー違反の画像をブロックします。
  • ヘルスケア :複雑な医療スキャン(CTやMRIなど)には適していません。診断ツールではありません。

すべての出力を慎重に確認し、特にリスクの高いユースケースでは確認してください。完璧な精度や人間の監視なしに高感度な分析を必要とするタスクにClaudeを使用することは避けてください。

モデルクエリの埋め込み​

以下は、基盤モデルAPIによって利用可能になった gte-large-en モデルのエンベディングのリクエストです。 この例は、モデルサービング機能 (基盤モデルAPIまたは外部モデル) のいずれかを使用して使用可能になったエンベディングモデルのクエリに適用されます。

To use the OpenAI client, specify the model serving endpoint name as the model input.

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
openai_client = w.serving_endpoints.get_open_ai_client()

response = openai_client.embeddings.create(
  model="databricks-gte-large-en",
  input="what is databricks"
)

To query foundation models outside your workspace, you must use the OpenAI client directly, as demonstrated below. The following example assumes you have a Databricks API token and openai installed on your compute. You also need your Databricks workspace instance to connect the OpenAI client to Databricks.

Python

import os
import openai
from openai import OpenAI

client = OpenAI(
    api_key="dapi-your-databricks-token",
    base_url="https://example.staging.cloud.databricks.com/serving-endpoints"
)

response = client.embeddings.create(
  model="databricks-gte-large-en",
  input="what is databricks"
)

以下は、エンベディングモデルで想定される要求形式です。 外部モデルの場合、特定のプロバイダーとエンドポイント構成に有効な追加のパラメーターを含めることができます。 追加のクエリ・パラメーターを参照してください。

Bash

{
  "input": [
    "embedding text"
  ]
}

想定される応答形式は次のとおりです。

JSON
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": []
    }
  ],
  "model": "text-embedding-ada-002-v2",
  "usage": {
    "prompt_tokens": 2,
    "total_tokens": 2
  }
}

埋め込みが正規化されているかどうかを確認する​

モデルによって生成されたエンべディングが正規化されているかどうかを確認するには、次を使用します。

Python

  import numpy as np

  def is_normalized(vector: list[float], tol=1e-3) -> bool:
      magnitude = np.linalg.norm(vector)
      return abs(magnitude - 1) < tol

関数呼び出し​

Databricks Function Calling は OpenAI と互換性があり、 基盤モデル APIs の一部としてモデルサービング中のみ使用でき、 外部モデルを提供するサービング エンドポイントを利用できます。 詳細については、「 Databricks での関数呼び出し」を参照してください。

構造化された出力​

Structured outputs は OpenAI と互換性があり、基盤モデル APIsの一部としてモデルサービング中のみ使用できます。詳細については、「 Databricks での構造化出力」を参照してください。

AI Playground を使用してサポートされている LLM とチャットする​

サポートされている大規模言語モデルは、 AI Playgroundを使用して操作できます。 AI Playground は、Databricks ワークスペースから LLM をテスト、プロンプト、比較できるチャットのような環境です。

AI playground

追加のリソース​

に最終更新