`ai_query` fungsi

Berlaku untuk: Ditandai centang ya Databricks SQL Databricks Runtime

Important

Fungsionalitas ini sesuai dengan Pratinjau Umum dan HIPAA.

Selama pratinjau:

Model bahasa yang mendasar dapat menangani beberapa bahasa, tetapi Fungsi AI ini disetel untuk bahasa Inggris.
Lihat Fitur dengan ketersediaan regional terbatas untuk mengetahui ketersediaan regional dari Fungsi AI.

Memanggil endpoint Model Serving Azure Databricks yang ada, mengurai, dan mengembalikan responsnya.

ai_query adalah Fungsi AI tujuan umum yang memungkinkan Anda meminta titik akhir yang ada untuk inferensi real time atau beban kerja inferensi kelompok.

Lihat Model yang didukung untuk model yang didukung dan konfigurasi titik akhir yang diperlukan.
Anda juga bisa menggunakan ai_query untuk mengkueri agen AI yang disebarkan pada model ML yang melayani titik akhir, lihat Mengkueri agen yang disebarkan di Azure Databricks
Untuk digunakan ai_query dalam alur kerja produksi, lihat Menyebarkan alur inferensi batch.

Persyaratan

Fungsi ini tidak tersedia di Azure Databricks SQL Classic.
Anda harus mengaktifkan Azure Private Link untuk menggunakan fitur ini di gudang pro SQL.
Databricks Runtime 15.4 LTS atau lebih tinggi direkomendasikan. Menggunakan Databricks Runtime 15.3 atau di bawahnya dapat mengakibatkan kecepatan performa yang lebih lambat.
Ruang kerja Anda harus berada di wilayah Layanan Model yang didukung.
Titik akhir penyajian model yang ada dengan model Anda dimuat. Jika Anda menggunakan model fondasi yang dihosting Databricks, sebuah endpoint dibuat untuk Anda. Jika tidak, lihat Membuat model kustom yang melayani titik akhir atau Membuat model fondasi yang melayani titik akhir.
Fungsi pemanggilan API Model Foundation diaktifkan secara default. Untuk mengkueri titik akhir yang melayani model kustom atau model eksternal :
- Aktifkan AI_Query untuk Model Kustom dan Model Eksternal di Antarmuka Pengguna Pratinjau Databricks.

Saluran gudang Lakeflow Spark Declarative Pipelinessaat ini tidak menggunakan versi Databricks Runtime terbaru yang mendukung ai_query(). Atur pipelines.channel dalam properti tabel sebagai 'preview' untuk menggunakan ai_query().

> create or replace materialized view
    ai_query_mv
    TBLPROPERTIES('pipelines.channel' = 'PREVIEW') AS
  SELECT
    ai_query("databricks-meta-llama-3-3-70b-instruct", text) as response
  FROM
    messages
  LIMIT 10;

Syntax

Untuk mengkueri titik akhir yang melayani model fondasi:

ai_query(endpoint, request)

Untuk melakukan kueri pada model kustom yang melayani endpoint dengan skema model :

ai_query(endpoint, request)

Untuk mengkueri model kustom yang melayani titik akhir tanpa skema model:

ai_query(endpoint, request, returnType, failOnError)

Argumen dan pengembalian

Argument	Description	Returns
`endpoint`	Nama titik akhir penyajian model pada Databricks Foundation, model eksternal, atau titik akhir model kustom di ruang kerja yang sama untuk pemanggilan sebagai literal `STRING`. Pendefinisi harus memiliki izin `CAN QUERY` pada titik akhir.
`request`	Permintaan yang digunakan untuk memanggil titik akhir sebagai ekspresi. Jika titik akhir adalah titik akhir layanan model eksternal atau titik akhir API Model Databricks Foundation, permintaan harus `STRING`. Jika titik akhir adalah model kustom yang melayani titik akhir, permintaan dapat berupa kolom tunggal atau ekspresi STRUCT. Nama field STRUCT harus cocok dengan nama fitur input yang diharapkan oleh endpoint.
`returnType`	(Opsional untuk Databricks Runtime 15.2 ke atas) Yang diharapkan `returnType` dari titik akhir sebagai ekspresi. Ini mirip dengan parameter skema dalam fungsi `from_json`, yang menerima ekspresi `STRING` atau pemanggilan fungsi `schema_of_json`. Untuk Databricks Runtime 15.2 ke atas, ekspresi ini bersifat opsional. Jika tidak disediakan, `ai_query()` secara otomatis menyimpulkan jenis pengembalian dari skema model model kustom yang melayani titik akhir. Untuk Databricks Runtime 15.1 ke bawah, ekspresi ini diperlukan untuk mengkueri model kustom yang melayani titik akhir. Gunakan parameter `responseFormat` untuk menentukan format respons untuk model dasar obrolan.
`failOnError`	(Opsional) Sebuah literal boolean yang secara bawaan bernilai benar. Memerlukan Databricks Runtime 15.3 atau lebih tinggi. Bendera ini menunjukkan apakah akan menyertakan status kesalahan dalam `ai_query` respons. Lihat Menangani kesalahan menggunakan `failOnError` misalnya.	Berikut ini menjelaskan perilaku pengembalian berdasarkan `failOnError` skenario: Jika `failOnError => true`, fungsi mengembalikan hasil yang sama dengan perilaku yang ada, yang merupakan respons yang diurai dari titik akhir. Jenis data respons yang diurai disimpulkan dari jenis model, titik akhir skema model, atau parameter `returnType` dalam fungsi `ai_query`. Jika `failOnError => false`, fungsi mengembalikan objek `STRUCT` yang berisi respons yang diurai dan string status kesalahan. Jika inferensi baris berhasil, bidang `errorStatus` adalah `null`. Jika inferensi baris gagal karena kesalahan titik akhir model, bidang `response` akan menjadi `null`. Jika inferensi baris gagal karena kesalahan lain, seluruh kueri gagal.
`modelParameters`	(Opsional) Bidang struct yang berisi parameter model obrolan, penyelesaian, dan penyematan untuk melayani model dasar atau model eksternal. Parameter model ini harus berupa parameter konstan dan bukan dependen data. Memerlukan Databricks Runtime 15.3 atau lebih tinggi. Ketika parameter model ini tidak ditentukan atau diatur ke `null` nilai default digunakan. Dengan pengecualian `temperature` yang memiliki nilai default `0.0`, nilai default untuk parameter model ini sama dengan yang tercantum dalam referensi REST API model Foundation. Lihat Mengonfigurasi model dengan meneruskan parameter model misalnya.
`responseFormat`	(Opsional) Tentukan format respons yang Anda inginkan untuk diikuti model dasar percakapan. Memerlukan Databricks Runtime 15.4 LTS atau lebih tinggi. Hanya tersedia untuk pencarian model dasar obrolan. Dua gaya format respons didukung. String JSON gaya DDL Sebuah string JSON. Tiga jenis string JSON format respons didukung:`text`, `json_object`, `json_schema` Lihat Menerapkan skema output dengan output terstruktur misalnya.	Berikut ini menjelaskan apa yang terjadi ketika `failOnError` juga diatur ketika `responseFormat` ditentukan: Jika `failOnError => false` dan Anda telah menentukan `responseFormat`, fungsi mengembalikan respons yang diurai dan string status kesalahan sebagai objek `STRUCT`. Bergantung pada jenis string JSON yang ditentukan dalam `responseFormat`, respons berikut dikembalikan: Untuk `responseFormat => '{"type": "text"}'`, responsnya adalah string seperti, `“Here is the response”`. Untuk `responseFormat => '{"type": "json_object"}'`, responsnya adalah string JSON pasangan kunci-nilai, seperti `{“key”: “value”}`. Untuk `responseFormat => '{"type": "json_schema", "json_schema"...}'`, responsnya adalah string JSON.
`files`	(Opsional) Tentukan file dan konten mana yang akan digunakan dalam permintaan input multimodal Anda menggunakan `files=>content`. `files` adalah nama parameter yang diharapkan oleh model untuk input multimodal, dan `content` mengacu pada kolom di DataFrame yang berisi konten biner file gambar yang ingin Anda gunakan dalam kueri Anda. Diperlukan untuk permintaan multimodal. Hanya input gambar: `JPEG` atau `PNG` yang didukung. Lihat Input multimodal misalnya. Seperti yang terlihat dalam contoh ini, Anda dapat menentukan kolom `content` dari output `read_files` ke parameter `files`.

Contoh : Mengkueri model fondasi

Untuk melakukan kueri pada model eksternal yang berfungsi sebagai titik akhir:

> SELECT ai_query(
    'my-external-model-openai-chat',
    'Describe Databricks SQL in 30 words.'
  ) AS summary

  "Databricks SQL is a cloud-based platform for data analytics and machine learning, providing a unified workspace for collaborative data exploration, analysis, and visualization using SQL queries."

Untuk mengkueri model fondasi yang didukung oleh API Model Databricks Foundation:

> SELECT *,
  ai_query(
    'databricks-meta-llama-3-3-70b-instruct',
    "Can you tell me the name of the US state that serves the provided ZIP code? zip code: " || pickup_zip
    )
  FROM samples.nyctaxi.trips
  LIMIT 10

Secara opsional, Anda juga dapat membungkus panggilan ke ai_query() dalam UDF untuk panggilan fungsi sebagai berikut:

 CREATE FUNCTION correct_grammar(text STRING)
  RETURNS STRING
  RETURN ai_query(
    'databricks-meta-llama-3-3-70b-instruct',
    CONCAT('Correct this to standard English:\n', text));
> GRANT EXECUTE ON correct_grammar TO ds;
- DS fixes grammar issues in a batch.
> SELECT
    * EXCEPT text,
    correct_grammar(text) AS text
  FROM articles;

Masukan multimodal

ai_query secara asli mendukung input gambar multimodal. Lihat Jenis model dasar untuk model visi yang didukung dan dihosting oleh Databricks.

Berikut ini adalah jenis input yang didukung:

JPEG
PNG

Contoh berikut menunjukkan cara mengkueri model fondasi yang didukung oleh API Model Databricks Foundation untuk input multimodal. Dalam contoh ini, files => content parameter digunakan untuk meneruskan data file gambar ke ai_query

files: Nama parameter yang diharapkan oleh model untuk input multimodal
content: Kolom dalam DataFrame yang dikembalikan oleh READ_FILES, yang berisi konten biner file gambar.


> SELECT *, ai_query(
  'databricks-llama-4-maverick',
 'what is this image about?', files => content)
as output FROM READ_FILES("/Volumes/main/multimodal/unstructured/image.jpeg");

Untuk mengkueri model fondasi yang didukung oleh API Model Databricks Foundation untuk input multimodal dan menentukan output terstruktur:

> SELECT *, ai_query(
  'databricks-llama-4-maverick', 'What is interesting or important about this image?',
    responseFormat => ‘{
      "type": "json_schema",
        "json_schema": {
          "name": "output",
          "schema": {
            "type": "object",
            "properties": {
              "summary": {"type": "string"},
              "num_people": {"type": "integer"},
              "num_animals": {"type": "integer"},
              "interesting_fact": {"type": "string"},
              "possible_context": {"type": "string"}
            }
        },
        "strict": true
      }
    }’,
    files => content
  )
  as output FROM READ_FILES("/Volumes/main/user/volume1/image.jpeg");

Contoh: Mengkueri model ML tradisional

Untuk mengkueri model kustom atau model ML tradisional yang melayani titik akhir:


> SELECT text, ai_query(
    endpoint => 'spam-classification-endpoint',
    request => named_struct(
      'timestamp', timestamp,
      'sender', from_number,
      'text', text),
    returnType => 'BOOLEAN') AS is_spam
  FROM messages
  LIMIT 10

> SELECT ai_query(
    'weekly-forecast',
    request => struct(*),
    returnType => 'FLOAT') AS predicted_revenue
  FROM retail_revenue

Contoh untuk skenario tingkat lanjut

Bagian berikut memberikan contoh untuk kasus penggunaan tingkat lanjut seperti penanganan kesalahan atau cara menggabungkan ai_query ke dalam fungsi yang ditentukan pengguna.

Kirimkan array pesan

Contoh berikut menunjukkan cara meneruskan array pesan ke model atau aplikasi agen Anda menggunakan ai_query.

> SELECT ai_query(
    'custom-llama-chat',
    request => named_struct("messages",
        ARRAY(named_struct("role", "user", "content", "What is ML?"))),
    returnType => 'STRUCT<candidates:ARRAY<STRING>>')

  {"candidates":["ML stands for Machine Learning. It's a subfield of Artificial Intelligence that involves the use of algorithms and statistical models to enable machines to learn from data, make decisions, and improve their performance on a specific task over time."]}

Menggabungkan kolom perintah dan inferensi

Ada beberapa cara untuk menggabungkan perintah dan kolom inferensi, seperti menggunakan ||, CONCAT(), atau format_string():

SELECT
CONCAT('${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};

Alternatively:

SELECT
'${prompt}' || ${input_column_name} AS concatenated_prompt
FROM ${input_table_name};

Atau menggunakan format_string():

SELECT
format_string('%s%s', '${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};

Mengonfigurasi model dengan meneruskan parameter model

Sesuaikan perilaku model dengan meneruskan parameter tertentu seperti token dan suhu maksimum. Contohnya:

SELECT text, ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "Please summarize the following article: " || text,
    modelParameters => named_struct('max_tokens', 100, 'temperature', 0.7)
) AS summary
FROM uc_catalog.schema.table;

Menangani kesalahan menggunakan `failOnError`

Gunakan argumen failOnError untuk ai_query menangani kesalahan. Contoh berikut menunjukkan cara memastikan bahwa jika satu baris memiliki kesalahan, itu tidak akan menghentikan seluruh kueri untuk berjalan. Lihat Argumen dan Pengembalian mengenai perilaku yang diharapkan berdasarkan cara pengaturan argumen ini.


SELECT text, ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "Summarize the given text comprehensively, covering key points and main ideas concisely while retaining relevant details and examples. Ensure clarity and accuracy without unnecessary repetition or omissions: " || text,
failOnError => false
) AS summary
FROM uc_catalog.schema.table;

Menerapkan skema output dengan output terstruktur

Pastikan bahwa output sesuai dengan skema tertentu untuk pemrosesan hilir yang lebih mudah menggunakan responseFormat. Lihat Output terstruktur di Azure Databricks.

Contoh berikut memberlakukan skema string JSON gaya DDL:

SELECT ai_query(
    "databricks-gpt-oss-20b",
    "Extract research paper details from the following abstract: " || abstract,
    responseFormat => 'STRUCT<research_paper_extraction:STRUCT<title:STRING, authors:ARRAY<STRING>, abstract:STRING, keywords:ARRAY<STRING>>>'
)
FROM research_papers;

Atau, menggunakan format respons skema JSON:

SELECT ai_query(
    "databricks-gpt-oss-20b",
    "Extract research paper details from the following abstract: " || abstract,
    responseFormat => '{
      "type": "json_schema",
      "json_schema": {
        "name": "research_paper_extraction",
        "schema": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "authors": {"type": "array", "items": {"type": "string"}},
            "abstract": {"type": "string"},
            "keywords": {"type": "array", "items": {"type": "string"}}
          }
      },
      "strict": true
    }
  }'
)
FROM research_papers;

Output yang diharapkan mungkin terlihat seperti:

{ "title": "Understanding AI Functions in Databricks", "authors": ["Alice Smith", "Bob Jones"], "abstract": "This paper explains how AI functions can be integrated into data workflows.", "keywords": ["Databricks", "AI", "LLM"] }

Menggunakan `ai_query` dalam fungsi yang ditentukan pengguna

Anda dapat membungkus panggilan ke ai_query dalam UDF, sehingga mudah untuk menggunakan fungsi di berbagai alur kerja dan membagikannya.

CREATE FUNCTION correct_grammar(text STRING)
  RETURNS STRING
  RETURN ai_query(
    'databricks-meta-llama-3-3-70b-instruct',
    CONCAT('Correct this to standard English:\n', text));

GRANT EXECUTE ON correct_grammar TO ds;

SELECT
    * EXCEPT text,
    correct_grammar(text) AS text
  FROM articles;

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-27