Aracılığıyla paylaş

ai_query işlev

Şunlar için geçerlidir:onay işareti evet olarak işaretlenmiş Databricks SQL onay işareti evet olarak işaretlenmiş Databricks Runtime

Önemli

Bu özellik Genel Önizlemededir.

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

Üretim iş akışlarında ai_query kullanmak için, AI işlevlerini kullanarak toplu LLM çıkarımı gerçekleştirme işlemi için 'e bakın.

Gereksinimler

  • Bu işlev Azure Databricks SQL Classic'te kullanılamaz.

  • Bu özelliği profesyonel SQL ambarlarında kullanmak için Azure Özel Bağlantı etkinleştirmeniz gerekir.

  • Databricks Runtime 15.4 LTS veya üzeri önerilir. Databricks Runtime 15.3 veya üzerini kullanmak daha düşük performans hızlarına neden olabilir.

  • Ç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.

  • Temel Model API'lerini sorgulama varsayılan olarak etkindir. özel modeller veya dış modeller sunan uç noktaları sorgulamak için:

  • GeçerliLakeflow Deklaratif İşlem Hatları ambar kanalı, ai_query()'yi destekleyen en son Databricks Runtime sürümünü kullanmıyor. Tablo özelliklerindeki pipelines.channel'ı, 'preview'kullanmak amacıyla ai_query() olarak ayarlayın.

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

Sözdizimi

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

Tartışma Açıklama İadeler
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 yapı ifadesi olabilir. Yapı alanı adları, uç nokta tarafından beklenen giriş özelliği adlarla eşleşmelidir.
returnType Beklenen ifade olarak uç noktadan 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 üzerinde, bu ifade sağlanmazsa, ai_query() dönüş türünü özel model sunum uç noktasının model şemasından otomatik olarak çıkartır.
  • Databricks Runtime 15.1 ve altında, bu ifade uç noktaya hizmet veren özel bir modeli sorgulamak için gereklidir.
failOnError (İsteğe bağlı) Varsayılan değeri true olan boole literali. Databricks Runtime 15.3 veya üzerini gerektirir. Bu bayrak, yanıta hata durumunun eklenip eklenmeyeceğini ai_query gösterir.
  • 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.
  • Eğer failOnError => falseolursa, işlev, ayrıştırılmış yanıtı ve hata durum dizesini içeren bir STRUCT nesnesi döndürür.
  • Satırın çıkarımı başarılı olursa, errorStatus 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.

Örnek için bkz. failOnError kullanarak hataları işleme.
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 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.
  • failOnError => false ve responseFormatbelirttiyseniz, işlev ayrıştırılmış yanıtı ve hata durum dizesini STRUCT nesnesi 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.

Örnekler için bkz. Yapılandırılmış çıktıyla çıkış şemasını zorlamak.

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

Ö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

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

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.

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

Alternatif olarak:

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-meta-llama-3-3-70b-instruct",
    "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-meta-llama-3-3-70b-instruct",
    "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;