Funkcja ai_query

Dotyczy: Databricks SQL Databricks Runtime

Ważne

Ta funkcja jest dostępna w publicznej wersji zapoznawczej.

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

Aby użyć ai_query w produkcyjnych procesach roboczych, zobacz Przeprowadzanie wsadowego wnioskowania LLM przy użyciu AI Functions.

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 Deklaratywnych Potoków Lakeflow nie korzysta z najnowszej wersji 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;
  

Składnia

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

Argumentacja	Opis	Zwraca
endpoint	Nazwa punktu końcowego obsługi modelu Databricks Foundation, punktu końcowego obsługi zewnętrznego modelu lub niestandardowego punktu końcowego modelu w tym samym obszarze roboczym dla wywołań jako literał STRING. Definiujący musi mieć uprawnienia CAN QUERY na końcówce.
request	Żądanie służące do wywoływania punktu końcowego w formie wyrażenia. Jeśli punkt końcowy to punkt końcowy dla zewnętrznego modelu albo punkt końcowy interfejsu API modelu Databricks Foundation, żądanie musi być STRING. Jeśli punkt końcowy jest punktem końcowym obsługi modelu niestandardowego, żądanie może być jedną kolumną lub wyrażeniem struktury. Nazwy pól struktury powinny być zgodne z nazwami cech wejściowych oczekiwanymi przez punkt końcowy.
returnType	Oczekiwana returnType wartość z punktu końcowego jako wyrażenie. Jest to podobne do parametru schematu w funkcji from_json, która akceptuje zarówno wyrażenie STRING, jak i wywołanie funkcji schema_of_json. Jeśli to wyrażenie nie zostanie podane, ai_query() w środowisku Databricks Runtime 15.2 lub nowszym automatycznie wywnioskuje typ zwracany ze schematu modelu niestandardowego punktu końcowego obsługującego model. W środowisku Databricks Runtime 15.1 lub nowszym to wyrażenie jest wymagane do wykonywania zapytań dotyczących niestandardowego punktu końcowego obsługującego model.
failOnError	(Opcjonalnie) Literał logiczny, który domyślnie ma wartość true. Wymaga środowiska Databricks Runtime w wersji 15.3 lub nowszej. Ta flaga wskazuje, czy w odpowiedzi ma być uwzględniny stan błędu ai_query .	Jeśli failOnError => truefunkcja zwraca ten sam wynik co istniejące zachowanie, czyli przeanalizowaną odpowiedź z punktu końcowego. Typ danych przeanalizowanej odpowiedzi jest wnioskowany z typu modelu, punktu końcowego schematu modelu lub parametru returnType w funkcji ai_query. Jeśli failOnError => false, funkcja zwraca obiekt STRUCT zawierający przeanalizowaną odpowiedź i ciąg stanu błędu. Jeśli wnioskowanie dla wiersza powiedzie się, pole errorStatus będzie null. Jeśli z powodu błędów punktu końcowego modelu wnioskowanie z wiersza kończy się niepowodzeniem, pole response jest null. Jeśli wnioskowanie wiersza zakończy się niepowodzeniem z powodu innych błędów, całe zapytanie zakończy się niepowodzeniem. Zobacz Obsługuj błędy używając failOnError jako przykład.
modelParameters	(Opcjonalnie) Pole struktury zawierające parametry modelu czatu, uzupełniania i osadzania, przeznaczone dla modeli podstawowych lub modeli zewnętrznych. Te parametry modelu muszą być stałymi parametrami, a nie zależne od danych. Wymaga środowiska Databricks Runtime w wersji 15.3 lub nowszej. Jeśli te parametry modelu nie są określone lub ustawione na null jest używana wartość domyślna. Z wyjątkiem temperature, który ma wartość domyślną 0.0, wartości domyślne tych parametrów modelu są takie same jak te wymienione w Foundation model REST API reference. Zobacz Konfigurowanie modelu, przekazując parametry modelu na przykład.
responseFormat	(Opcjonalnie) Określ format odpowiedzi, według którego model rozmowy ma działać. Wymaga środowiska Databricks Runtime 15.4 LTS lub nowszego. Dostępne tylko na potrzeby wykonywania zapytań dotyczących modeli podstaw czatów. Obsługiwane są dwa style formatu odpowiedzi. Ciąg JSON w stylu DDL Ciąg JSON. Obsługiwane są trzy typy ciągów JSON w formacie odpowiedzi: text json_object json_schema Aby zapoznać się z przykładami, zobacz Wymuszanie schematu wyjściowego ze strukturą .	Jeśli failOnError => false i określono responseFormat, funkcja zwraca przeanalizowaną odpowiedź i ciąg stanu błędu jako obiekt STRUCT. W zależności od typu ciągu JSON określonego w responseFormatzwracana jest następująca odpowiedź: W przypadku responseFormat => '{"type": "text"}'odpowiedź jest ciągiem, takim jak “Here is the response”. W przypadku responseFormat => '{"type": "json_object"}'odpowiedzią jest ciąg JSON w formie pary klucz-wartość, na przykład {“key”: “value”}. W przypadku responseFormat => '{"type": "json_schema", "json_schema"...}'odpowiedź jest ciągiem JSON. Aby zapoznać się z przykładami, zobacz Wymuszanie schematu wyjściowego ze strukturą .

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;

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

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

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.

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

Inna możliwość:

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

Alternatywnie użyj formatu odpowiedzi schematu JSON:

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;

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;