Funkcja ai_query

Dotyczy: Databricks SQL Databricks Runtime

Wywołuje istniejący punkt końcowy obsługujący model usługi Azure Databricks i analizuje i zwraca odpowiedź.

ai_query to funkcja sztucznej inteligencji ogólnego przeznaczenia, która umożliwia wykonywanie zapytań dotyczących istniejących punktów końcowych dla obciążeń wnioskowania w czasie rzeczywistym lub wnioskowania wsadowego.

• Zobacz Funkcja ogólnego przeznaczenia: ai_query aby zapoznać się z obsługiwanymi modelami i wymaganymi konfiguracjami punktów końcowych.
• Możesz również użyć ai_query, aby zapytać agenta sztucznej inteligencji wdrożonego w punkcie końcowym obsługującym model uczenia maszynowego, zobacz Wykonywanie zapytań do wdrożonego agenta sztucznej inteligencji Mosaic
• Aby użyć ai_query w produkcyjnych przepływach pracy, zobacz Wdrażanie potoków wnioskowania wsadowego.

Wymagania

• Ta funkcja nie jest dostępna w usłudze Azure Databricks SQL Classic.

• Aby korzystać z tej funkcji w usłudze Pro SQL Warehouse, musisz włączyć usługę Azure Private Link .

• Zalecane jest środowisko Databricks Runtime 15.4 LTS lub nowsze. Użycie środowiska Databricks Runtime w wersji 15.3 lub nowszej może spowodować obniżenie szybkości wydajności.

• Obszar roboczy musi znajdować się w obsługiwanym regionie serwowania modeli.

• Istniejący model obsługujący punkt końcowy z załadowanym modelem. Jeśli używasz modelu bazowego hostowanego przez Databricks, zostanie utworzony dla Ciebie punkt końcowy. W przeciwnym razie zobacz Tworzenie niestandardowego modelu obsługującego punkty końcowe lub Tworzenie modelu podstawowego obsługującego punkty końcowe.

• Wysyłanie zapytań do interfejsów API Modelu Fundacji jest domyślnie włączone. Aby wykonywać zapytania dotyczące punktów końcowych obsługujących modele niestandardowe lub modele zewnętrzne:

  • Włącz AI_Query dla modeli niestandardowych i zewnętrznych w interfejsie użytkownika wersji zapoznawczej Databricks.

• Bieżącykanał magazynu Deklaratywne potoki Lakeflow Spark nie korzysta z najnowszej wersji środowiska Databricks Runtime, która obsługuje ai_query(). Ustaw pipelines.channel we właściwościach tabeli jako 'preview', aby użyć 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

Aby wysłać zapytanie do punktu końcowego obsługującego model podstawowy:

ai_query(endpoint, request)

Aby wysłać zapytanie do punktu końcowego obsługującego niestandardowy model przy użyciu schematu modelu:

ai_query(endpoint, request)

Aby wykonywać zapytania dotyczące niestandardowego punktu końcowego obsługującego model bez schematu modelu:

ai_query(endpoint, request, returnType, failOnError)

Argumenty i wartości zwracane

Przykład: wykonywanie zapytań względem modelu podstawowego

Aby wysłać zapytanie do zewnętrznego punktu końcowego obsługującego model:

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

Aby wykonywać zapytania do modelu bazowego obsługiwanego przez API Databricks Foundation Model:

> 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

Opcjonalnie, można również owinąć wywołanie ai_query() w UDF w celu wywołania funkcji w następujący sposób:

 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;

Dane wejściowe wielomodalne

ai_query natywnie obsługuje dane wejściowe obrazów wielomodalnych. Zobacz Typy modeli bazowych dla obsługiwanych modeli wizyjnych hostowanych w usłudze Databricks.

Obsługiwane są następujące typy danych wejściowych:

• JPEG
• PNG

W poniższym przykładzie pokazano, jak wykonywać zapytania do modelu foundation obsługiwanego przez interfejsy API Databricks Foundation Model dla wielomodalnych danych wejściowych. W tym przykładzie files => content parametr jest używany do przekazywania danych pliku obrazu do ai_query

• files: Nazwa parametru oczekiwana przez model dla danych wejściowych wielomodalnych
• content: kolumna w ramce danych zwróconej przez element READ_FILES, która zawiera zawartość binarną pliku obrazu.

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

Aby wysłać zapytanie do modelu bazowego obsługiwanego przez interfejsy API modeli podstawowych Databricks dla danych wejściowych wielomodalnych oraz określić ustrukturyzowane dane wyjściowe:

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

Przykład: Wykonywanie zapytań względem tradycyjnego modelu uczenia maszynowego

Aby wysłać zapytanie do modelu niestandardowego lub tradycyjnego modelu uczenia maszynowego obsługującego punkt końcowy:

> 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

Przykłady dla zaawansowanych scenariuszy

W poniższych sekcjach przedstawiono przykłady zaawansowanych przypadków użycia, takich jak obsługa błędów lub jak włączyć ai_query do funkcji zdefiniowanej przez użytkownika.

Przekazywanie tablicy komunikatów

W poniższym przykładzie pokazano, jak przekazać tablicę komunikatów do modelu lub aplikacji agenta przy użyciu polecenia 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."]}

Połączenie kolumn zapytania i wnioskowania

Istnieje wiele sposobów łączenia monitu i kolumny wnioskowania, takich jak używanie ||, CONCAT()lub 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};

lub używając format_string():

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

Konfigurowanie modelu przez przekazywanie parametrów modelu

Dostosuj zachowanie modelu, przekazując określone parametry, takie jak maksymalne tokeny i temperatura. Przykład:

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;

Obsługa błędów przy użyciu failOnError

Użyj argumentu failOnError dla ai_query do obsługi błędów. W poniższym przykładzie pokazano, jak upewnić się, że jeśli jeden wiersz zawiera błąd, nie zatrzyma uruchomienia całego zapytania. Zobacz Argumenty i zwracane wartości dla oczekiwanych zachowań na podstawie sposobu ustawienia tego argumentu.

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;

Wymuszanie schematu wyjściowego poprzez uporządkowaną strukturę

Upewnij się, że dane wyjściowe są zgodne z określonym schematem, aby ułatwić przetwarzanie podrzędne przy użyciu polecenia responseFormat. Zobacz Dane wyjściowe ze strukturą w usłudze Azure Databricks.

Poniższy przykład wymusza schemat ciągu JSON stylu 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;

Alternatywnie użyj formatu odpowiedzi schematu 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;

Oczekiwane dane wyjściowe mogą wyglądać następująco:

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

Używanie ai_query w funkcjach zdefiniowanych przez użytkownika

Można opakować wywołanie ai_query w funkcji zdefiniowanej przez użytkownika, co ułatwia użycie funkcji w różnych przepływach pracy i ich udostępnianie.

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;