API model query (layanan model)

Gunakan Unity AI Gateway untuk melakukan query layanan model di Unity Catalog dengan API model Azure Databricks, menggunakan SDK yang kompatibel dengan OpenAI, API provider asli, atau SQL.

Note

Ketika layanan model dirutekan ke tujuan layanan penyedia model, hanya fitur Unity AI Gateway milik layanan model tersebut (seperti batas laju, pembatas pengaman, tabel inferensi, dan mekanisme fallback) yang diterapkan. Fitur Unity AI Gateway yang dikonfigurasi di layanan penyedia model itu sendiri akan diabaikan.

Mulailah melakukan query pada API model

Kueri API model dalam dua langkah:

Langkah 1: Pilih API model siap pakai

Azure Databricks menyediakan API model siap pakai dalam system.ai skema, seperti system.ai.databricks-claude-sonnet-4-5 dan system.ai.databricks-gpt-5-6-sol. Fitur ini langsung tersedia tanpa pengaturan tambahan.

Langkah 2: Kirim permintaan menggunakan API yang kompatibel dengan OpenAI terpadu

Gunakan API MLflow Chat Completions dengan OpenAI Python SDK:

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,  # your personal access token
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"  # your Databricks workspace instance
)

chat_completion = client.chat.completions.create(
  messages=[
    {"role": "user", "content": "What is Databricks?"},
  ],
  model="system.ai.databricks-claude-sonnet-4-5",
  max_tokens=256
)

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

Untuk opsi lain, lihat Mulai melakukan query LLM di Databricks.

Requirements

• Ruang kerja Azure Databricks di wilayah yang didukung gateway AI Unity.
• Katalog Unity diaktifkan untuk ruang kerja Anda. Lihat Mengaktifkan ruang kerja untuk Unity Catalog.

API dan integrasi yang didukung

Unity AI Gateway mendukung API dan integrasi berikut:

• API Terpadu: Antarmuka yang kompatibel dengan OpenAI untuk mengkueri model di Azure Databricks. Beralih antar model dengan mulus dari penyedia yang berbeda tanpa mengubah cara Anda mengkueri setiap model.
• API asli: Antarmuka khusus penyedia untuk mengakses model terbaru dan fitur khusus penyedia.
  • API Respons OpenAI
  • API Pesan Antropik
  • Google Gemini API
• Agen pengkodian: Integrasikan agen pengkodian Anda dengan Unity AI Gateway untuk menambahkan tata kelola dan pemantauan terpusat ke alur kerja pengembangan yang dibantu AI Anda. Lihat integrasi agen pengkodingan.
• Agen di Aplikasi Databricks: Menulis dan menyebarkan agen di Aplikasi Databricks yang merutekan lalu lintas LLM melalui Unity AI Gateway. Lihat Langkah 4. Mengatur penggunaan LLM dari agen Anda di Aplikasi Databricks dengan Unity AI Gateway.
• ai_query: Gunakan ai_query untuk mengkueri layanan model yang disediakan Azure Databricks dari SQL atau Python untuk inferensi batch. Lihat Layanan model kueri dengan ai_query.

Layanan model kueri dengan API terpadu

API Terpadu menawarkan antarmuka yang kompatibel dengan OpenAI untuk mengkueri model di Azure Databricks. Gunakan API terpadu untuk beralih antar model dengan lancar dari penyedia yang berbeda tanpa mengubah kode Anda.

API Pelengkap Chat MLflow

API Penyelesaian Percakapan MLflow

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
)

chat_completion = client.chat.completions.create(
  messages=[
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hello! How can I assist you today?"},
    {"role": "user", "content": "What is Databricks?"},
  ],
  model="<model-service>",
  max_tokens=256
)

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

REST API

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "Hello!"},
      {"role": "assistant", "content": "Hello! How can I assist you today?"},
      {"role": "user", "content": "What is Databricks?"}
    ]
  }' \
  https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions

Ganti <workspace-url> dengan URL ruang kerja Azure Databricks Anda dan <model-service> dengan nama layanan model Anda yang sepenuhnya memenuhi syarat.

MLflow Embeddings API

MLflow Embeddings API

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
)

embeddings = client.embeddings.create(
  input="What is Databricks?",
  model="<model-service>"
)

print(embeddings.data[0].embedding)

REST API

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "input": "What is Databricks?"
  }' \
  https://<workspace-url>/ai-gateway/mlflow/v1/embeddings

Ganti <workspace-url> dengan URL ruang kerja Azure Databricks Anda dan <model-service> dengan nama layanan model Anda yang sepenuhnya memenuhi syarat.

Supervisor API

Supervisor API

API Supervisor () adalah API yang agnostik terhadap penyedia dan kompatibel dengan OpenResponses untuk membangun agen dalam fase Beta. Administrator akun dapat mengaktifkan akses dari halaman Pratinjau. Lihat Kelola Pratinjau Azure Databricks. Pilih model terbaik untuk kasus penggunaan agen Anda di seluruh penyedia, tanpa mengubah kode Anda.

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
)

response = client.responses.create(
  model="<model-service>",
  input=[{"role": "user", "content": "What is Databricks?"}]
)

print(response.output_text)

REST API

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "input": [
      {"role": "user", "content": "What is Databricks?"}
    ]
  }' \
  https://<workspace-url>/ai-gateway/mlflow/v1/responses

Ganti <workspace-url> dengan URL ruang kerja Azure Databricks Anda dan <model-service> dengan nama layanan model Anda yang sepenuhnya memenuhi syarat.

Buat kueri ke layanan model dengan ai_query

Anda dapat menggunakan fungsi ini ai_query untuk melakukan query layanan model langsung dari SQL atau Python. Ini memungkinkan Anda menangkap informasi pelacakan penggunaan untuk beban kerja inferensi batch Anda.

Note

• ai_querydukungan untuk Unity AI Gateway hanya tersedia untuk layanan model di Azure Databricks (misalnya, databricks-claude-sonnet-4-5 atau databricks-gpt-5-6-sol). Layanan model yang Anda buat di Unity AI Gateway belum didukung.
• Hanya pelacakan penggunaan yang berlaku untuk ai_query beban kerja inferensi batch. Fitur Gateway AI Unity lainnya seperti batas tarif, pagar pembatas, tabel inferensi, dan fallback tidak berlaku.

Untuk melakukan query pada layanan model dengan ai_query, dijalankan ai_query terhadap layanan model:

SELECT ai_query(
  'databricks-claude-sonnet-4-5',
  'Summarize the following text: ' || text_column
) AS summary
FROM my_table
LIMIT 10

Tabel sistem pelacakan penggunaan (system.ai_gateway.usage) menangkap permintaan yang dibuat untuk ai_query layanan model. Permintaan ini juga muncul di dasbor penggunaan bawaan.

Untuk sintaks penuh ai_query dan referensi parameter, lihat ai_query fungsi. Untuk praktik terbaik dan model yang didukung, lihat Menggunakan ai_query.

Layanan model kueri dengan API asli

API asli menawarkan antarmuka khusus penyedia untuk mengkueri model di Azure Databricks. Gunakan API asli untuk mengakses fitur khusus penyedia terbaru.

Setiap API asli hanya berfungsi dengan layanan model yang model yang mendasarnya menggunakan format API yang cocok:

• Gunakan OPENAI Responses API untuk mengkueri layanan model yang didukung oleh model OpenAI (GPT).
• Gunakan ANTHROPIC Messages API untuk mengkueri layanan model yang didukung oleh model Claude.
• Gunakan Google Gemini API untuk mengkueri layanan model yang didukung oleh model Gemini.

Untuk mengkueri layanan model terlepas dari model yang mendasarnya, gunakan API terpadu sebagai gantinya.

API Respons OpenAI

API Respons OpenAI

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url="https://<workspace-url>/ai-gateway/openai/v1"
)

response = client.responses.create(
  model="<model-service>",
  max_output_tokens=256,
  input=[
    {
      "role": "user",
      "content": [{"type": "input_text", "text": "Hello!"}]
    },
    {
      "role": "assistant",
      "content": [{"type": "output_text", "text": "Hello! How can I assist you today?"}]
    },
    {
      "role": "user",
      "content": [{"type": "input_text", "text": "What is Databricks?"}]
    }
  ]
)

print(response.output)

REST API

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "max_output_tokens": 256,
    "input": [
      {
        "role": "user",
        "content": [{"type": "input_text", "text": "Hello!"}]
      },
      {
        "role": "assistant",
        "content": [{"type": "output_text", "text": "Hello! How can I assist you today?"}]
      },
      {
        "role": "user",
        "content": [{"type": "input_text", "text": "What is Databricks?"}]
      }
    ]
  }' \
  https://<workspace-url>/ai-gateway/openai/v1/responses

Ganti <workspace-url> dengan URL ruang kerja Azure Databricks Anda dan <model-service> dengan nama layanan model Anda yang sepenuhnya memenuhi syarat.

API Anthropic Messages

ANTHROPIC Messages API

Python

import anthropic
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = anthropic.Anthropic(
  api_key="unused",
  base_url="https://<workspace-url>/ai-gateway/anthropic",
  default_headers={
    "Authorization": f"Bearer {DATABRICKS_TOKEN}",
  },
)

message = client.messages.create(
  model="<model-service>",
  max_tokens=256,
  messages=[
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hello! How can I assist you today?"},
    {"role": "user", "content": "What is Databricks?"},
  ],
)

print(message.content[0].text)

REST API

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "Hello!"},
      {"role": "assistant", "content": "Hello! How can I assist you today?"},
      {"role": "user", "content": "What is Databricks?"}
    ]
  }' \
  https://<workspace-url>/ai-gateway/anthropic/v1/messages

Ganti <workspace-url> dengan URL ruang kerja Azure Databricks Anda dan <model-service> dengan nama layanan model Anda yang sepenuhnya memenuhi syarat.

Google Gemini API

Google Gemini API

Python

from google import genai
from google.genai import types
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = genai.Client(
  api_key="databricks",
  http_options=types.HttpOptions(
    base_url="https://<workspace-url>/ai-gateway/gemini",
    headers={
      "Authorization": f"Bearer {DATABRICKS_TOKEN}",
    },
  ),
)

response = client.models.generate_content(
  model="<model-service>",
  contents=[
    types.Content(
      role="user",
      parts=[types.Part(text="Hello!")],
    ),
    types.Content(
      role="model",
      parts=[types.Part(text="Hello! How can I assist you today?")],
    ),
    types.Content(
      role="user",
      parts=[types.Part(text="What is Databricks?")],
    ),
  ],
  config=types.GenerateContentConfig(
    max_output_tokens=256,
  ),
)

print(response.text)

REST API

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Hello!"}]
      },
      {
        "role": "model",
        "parts": [{"text": "Hello! How can I assist you today?"}]
      },
      {
        "role": "user",
        "parts": [{"text": "What is Databricks?"}]
      }
    ],
    "generationConfig": {
      "maxOutputTokens": 256
    }
  }' \
  https://<workspace-url>/ai-gateway/gemini/v1beta/models/<model-service>:generateContent

Ganti <workspace-url> dengan URL ruang kerja Azure Databricks Anda dan <model-service> dengan nama layanan model Anda yang sepenuhnya memenuhi syarat.

Permintaan tag untuk pelacakan penggunaan

Anda dapat melampirkan tag kunci-nilai kustom ke permintaan individual menggunakan Databricks-Ai-Gateway-Request-Tags header HTTP. Tag permintaan dicatat ke request_tags kolom dalam tabel sistem pelacakan penggunaan dan tabel inferensi, memungkinkan Anda melacak biaya, penggunaan atribut, dan memfilter analitik berdasarkan proyek, tim, lingkungan, atau dimensi lainnya.

Nilai header harus berupa objek JSON yang memetakan kunci string ke nilai string. Contohnya:

{ "project": "chatbot", "team": "ml-platform", "environment": "production" }

Gunakan parameter extra_headers (Python) atau teruskan header secara langsung (REST API) untuk melampirkan tag ke permintaan:

Python (OpenAI SDK)

from openai import OpenAI
import json
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
)

request_tags = {"project": "chatbot", "team": "ml-platform"}

chat_completion = client.chat.completions.create(
  messages=[
    {"role": "user", "content": "What is Databricks?"},
  ],
  model="<model-service>",
  max_tokens=256,
  extra_headers={
    "Databricks-Ai-Gateway-Request-Tags": json.dumps(request_tags)
  }
)

Python (Anthropic SDK)

import anthropic
import json
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

request_tags = {"project": "chatbot", "team": "ml-platform"}

client = anthropic.Anthropic(
  api_key="unused",
  base_url="https://<workspace-url>/ai-gateway/anthropic",
  default_headers={
    "Authorization": f"Bearer {DATABRICKS_TOKEN}",
    "Databricks-Ai-Gateway-Request-Tags": json.dumps(request_tags),
  },
)

message = client.messages.create(
  model="<model-service>",
  max_tokens=256,
  messages=[
    {"role": "user", "content": "What is Databricks?"},
  ],
)

REST API

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -H 'Databricks-Ai-Gateway-Request-Tags: {"project": "chatbot", "team": "ml-platform"}' \
  -d '{
    "model": "<model-service>",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "What is Databricks?"}
    ]
  }' \
  https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions

Ganti <workspace-url> dengan URL ruang kerja Azure Databricks Anda dan <model-service> dengan nama layanan model Anda yang sepenuhnya memenuhi syarat.

Langkah berikutnya

• Layanan model
• Membuat dan mengelola layanan model
• Menemukan dan mengatur akses ke layanan model
• Mengintegrasikan dengan agen pengkodian