ai_query işlev

Şunun için geçerlidir:Evet olarak işaretlendi Databricks SQL Evet olarak işaretlendi Databricks Runtime

Mevcut bir Azure Databricks Model Sunum uç noktasını çağırır ve yanıtını ayrıştırıp döndürür.

ai_query , mevcut uç noktaları gerçek zamanlı çıkarım veya toplu çıkarım iş yükleri için sorgulamanızı sağlayan genel amaçlı bir AI İşlevidir .

Gereksinimler

  • Bu işlev Pro veya Klasik SQL ambarlarında kullanılamaz.
  • Databricks Runtime 15.4 LTS veya üzeri gereklidir. Databricks Runtime 18.2 veya üzeri en iyi performans ve en son özelliklere erişim için önerilir.
  • Not defterleri ve Databricks iş akışları için sunucusuz işlem gereklidir.
  • Çalışma alanınız desteklenen model sunma bölgesinde olmalıdır.
  • Modelinizin yüklü olduğu uç noktaya hizmet veren mevcut bir model. Databricks tarafından barındırılan bir temel modeli kullanıyorsanız, sizin için bir uç nokta oluşturulur. Aksi takdirde bkz. Uç noktaları sunan özel model oluşturma veya uç noktaları sunan temel model oluşturma.
  • Desteklenen bölgelerde özel model uç noktalarının ve dış model uç noktalarının sorgulanması varsayılan olarak etkindir. Özel veya dış uç noktaya karşı bir izin hatası döndürürse ai_query() , çalışma alanı yöneticiniz önizlemeleri yönetme bölümünde devre dışı bırakmış olabilir.

Syntax

Temel modele hizmet eden bir uç noktayı sorgulamak için:

ai_query(endpoint, request)

Özel bir model sunum uç noktasını, model şemasıile sorgulamak için:

ai_query(endpoint, request)

Model şeması olmadan uç noktaya hizmet veren özel bir modeli sorgulamak için:

ai_query(endpoint, request, returnType, failOnError)

Bağımsız Değişkenler ve Dönüş Değerleri

Argument Description Returns
endpoint Sabit değer olarak çağırmalar için aynı çalışma alanında uç noktaya hizmet veren bir dış model veya özel model uç noktası olan STRING Databricks Foundation Modeli adı. Tanımlayıcının uç noktada CAN QUERY izni olmalıdır.
request Uç noktayı ifade olarak çağırmak için kullanılan istek.
  • Uç nokta, harici bir model sunma noktası veya Databricks Foundation Model API uç noktası ise, istek bir STRINGolmalıdır.
  • Uç nokta, uç noktaya hizmet veren özel bir modelse, istek tek bir sütun veya STRUCT ifadesi olabilir. STRUCT alan adları, uç nokta tarafından beklenen giriş özelliği adlarla eşleşmelidir.
returnType (Databricks Runtime 15.2 ve üzeri için isteğe bağlı) Uç noktadan ifade olarak beklenen returnType . Bu, from_json işlevindeki şema parametresine benzer ve hem STRING bir ifadeyi hem de schema_of_json işleviçağrısını kabul eder.
  • Databricks Runtime 15.2 ve üzeri için bu ifade isteğe bağlıdır. Sağlanmazsa, ai_query() dönüş türünü özel model sunum uç noktasının model şemasından otomatik olarak çıkarsar.
  • Databricks Runtime 15.1 ve altı için bu ifade uç nokta sunan özel bir modeli sorgulamak için gereklidir.

responseFormat parametresini, sohbet tabanlı modeller için yanıt biçimlerini belirtmek amacıyla kullanın.
failOnError (İsteğe bağlı) Varsayılan değeri true olan boole literali. Databricks Runtime 15.3 veya üzerini gerektirir. Bu bayrak, yanıta bir hata iletisi eklenip eklenmeyeceğini ai_query gösterir.
Örnek için bkz. failOnError kullanarak hataları işleme.		 Aşağıda, senaryoya göre failOnError dönüş davranışı açıklanmaktadır:
  • ise failOnError => trueişlevi, uç noktadan ayrıştırılan yanıt olan mevcut davranışla aynı sonucu döndürür. Ayrıştırılan yanıtın veri türü model türünden, model şeması uç noktasından veya returnType işlevindeki ai_query parametresinden çıkarılır.
  • ise failOnError => falseişlevi, ayrıştırılmış yanıtı ve hata iletisi dizesini içeren bir STRUCT nesne döndürür.
    • Satırın çıkarımı başarılı olursa, errorMessage alanı nullolur.
    • Eğer model uç noktası hataları nedeniyle satır çıkarımı başarısız olursa, response alanı null olur.
    • Satırın çıkarımı diğer hatalardan dolayı başarısız olursa sorgunun tamamı başarısız olur.
modelParameters (İsteğe bağlı) Temel modellere veya dış modellere hizmet etmek için sohbet, tamamlama ve ekleme modeli parametrelerini içeren bir yapı alanı. Bu model parametreleri verilere bağımlı değil sabit parametreler olmalıdır.
  • Databricks Runtime 15.3 veya üzerini gerektirir.
  • Bu model parametreleri belirtilmediğinde veya null olarak ayarlanmadığında varsayılan değer kullanılır. Varsayılan değeri temperatureolan 0.0 dışında, bu model parametreleri için varsayılan değerler Foundation modeli REST API başvurusuiçinde listelenenlerle aynıdır.

Örnek için bkz. Model parametrelerini geçirerek modeli yapılandırma.
responseFormat (İsteğe bağlı) Sohbet temeli modelinin izlemesini istediğiniz yanıt biçimini belirtin.
  • Databricks Runtime 15.4 LTS veya üzerini gerektirir. Yalnızca sohbet temeli modellerini sorgulamak için kullanılabilir.
  • İki yanıt biçimi stili desteklenir.
    • DDL stili JSON dizesi
    • JSON dizesi. Yanıt biçiminin üç JSON dize türü desteklenir:text, json_object, json_schema

Örnekler için bkz. Yapılandırılmış çıktıyla çıkış şemasını zorlamak.		 Aşağıda, belirtildiğinde failOnError de ayarlandığında responseFormat ne olacağı açıklanmaktadır:
  • failOnError => false ve belirttiysenizresponseFormat, işlev ayrıştırılmış yanıtı ve hata iletisi dizesini bir STRUCT nesne olarak döndürür.
  • responseFormat'de belirtilen JSON dize türüne bağlı olarak aşağıdaki yanıt döndürülür:
    • responseFormat => '{"type": "text"}'için yanıt, “Here is the response”gibi bir dizedir.
    • responseFormat => '{"type": "json_object"}'için yanıt, {“key”: “value”}gibi bir anahtar-değer çifti JSON dizesidir.
    • responseFormat => '{"type": "json_schema", "json_schema"...}'için yanıt bir JSON dizesidir.
files (İsteğe bağlı) kullanarak files=>contentçok modüllü giriş isteklerinizde hangi dosyaların ve içeriğin kullanılacağını belirtin. files model tarafından çok modüllü giriş için beklenen parametre adıdır ve content DataFrame'de sorgunuzda kullanmak istediğiniz görüntü dosyalarının ikili içeriğini içeren sütuna başvurur.
  • Çok modlu istekler için gereklidir.
  • Yalnızca görüntü girişleri: JPEG veya PNG desteklenir. Bir örnek için bkz. Çok modüllü girişler . Bu örnekte görüldüğü gibi, content çıkışının read_files sütununu files parametresine belirtebilirsiniz.

Örnek: Temel modeli sorgulama

Bir harici model sunum uç noktasını sorgulamak için:

> 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."

Databricks Foundation Model API'leri tarafından desteklenen bir temel modeli sorgulamak için:

> 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

İsteğe bağlı olarak, ai_query() çağrısını işlev çağrısı için aşağıdaki gibi bir UDF içinde sarabilirsiniz:

 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;

Çok modüllü girişler

ai_query yerel olarak çok modüllü görüntü girişlerini destekler. Desteklenen Databricks tarafından barındırılan görüntü işleme modelleri için temel model türleri bölümüne bakın.

Desteklenen giriş türleri şunlardır:

  • JPEG
  • PNG

Aşağıdaki örnekte, databricks Foundation Model API'leri tarafından desteklenen bir temel modelin çok modüllü giriş için nasıl sorgu yapılacağı gösterilmektedir. Bu örnekte, files => content parametresi, görüntü dosyası verilerini ai_query'e geçirmek için kullanılır.

  • files: Model tarafından çok modüllü giriş için beklenen parametre adı
  • content: Tarafından döndürülen READ_FILESDataFrame'de bulunan ve görüntü dosyasının ikili içeriğini içeren sütun.

> 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");

Databricks Foundation Model API'leri tarafından desteklenen bir temel modeli çok modüllü giriş için sorgulamak ve yapılandırılmış çıktıyı belirtmek için:

> 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");

Aşağıdaki örnek, bulut depolamadan görüntü dosyalarında çıkarım çalıştırmak için ile ai_queryread_files biçimini kullanırbinaryFile. Yan tümcesi WHERE , belirli dosyaları boyuta ve ada göre hedeflemek için alanlar üzerinde _metadata filtreler.

SELECT
  path AS file_path,
  ai_query(
    'databricks-llama-4-maverick',
    'Describe this image in ten words or less: ',
    files => content
  ) AS result
FROM read_files(
  's3://my-s3-bucket/path/to/images/',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,png,JPG,JPEG,PNG}'
)
WHERE _metadata.file_size < 1000000
  AND _metadata.file_name LIKE '%robots%';

Örnek: Geleneksel ml modelini sorgulama

Özel bir modeli veya geleneksel ML modeli hizmet uç noktasını sorgulamak için:


> 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

Gelişmiş senaryolar için örnekler

Aşağıdaki bölümlerde hata işleme veya kullanıcı tanımlı bir işleve ekleme ai_query gibi gelişmiş kullanım örnekleri verilmiştir.

Bir mesajlar dizisi aktarın

Aşağıdaki örnekte ai_query kullanarak model veya aracı uygulamanıza ileti dizisi geçirmenin nasıl yapıldığı gösterilmektedir.

> 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."]}

istem ve çıkarım sütununu birleştirme

||, CONCAT()veya format_string()gibi istemi ve çıkarım sütununu birleştirmenin birden çok yolu vardır:

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};

Veya format_string()kullanarak:

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

Model parametrelerini geçirerek model yapılandırma

Maksimum belirteçler ve sıcaklık gibi belirli parametreleri geçirerek model davranışını özelleştirin. Örneğin:

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;

failOnError kullanarak hataları işleme

failOnError için hataları işlemek amacıyla ai_query bağımsız değişkenini kullanın. Aşağıdaki örnekte, bir satırda hata varsa sorgunun tamamının çalışmasını durdurmayacağından nasıl emin olunduğu gösterilmektedir. Bağımsız Değişkenler ve Dönüş Değerleri'ne bakın. Bu bağımsız değişkenin nasıl ayarlandığına bağlı olarak beklenen davranışları anlamak için döndürmelerine göz atın.


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;

Yapılandırılmış bir çıkışla çıkış şemasının uygulanmasını sağlama

Çıkışın, responseFormat kullanarak daha kolay bir sonraki aşama işlemleri için belirli bir şemaya uygun olduğundan emin olun. Azure Databricks'te yapılandırılmış çıktıları görün.

Aşağıdaki örnek bir DDL stili JSON dize şemasını zorunlu kılmıştır:

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;

Alternatif olarak, bir JSON şeması yanıt biçimi kullanarak:

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;

Beklenen çıkış şöyle görünebilir:

{ "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"] }

Kullanıcı tanımlı işlevlerde ai_query kullanma

ai_query çağrısını bir UDF içinde sararak, işlevleri farklı iş akışlarında kullanmayı ve paylaşmayı kolaylaştırabilirsiniz.

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;
  • Last updated on