Udostępnij za pośrednictwem

Funkcja ai_query

  • Artykuł

Dotyczy:zaznacz pole wyboru oznaczone jako tak Databricks SQL zaznacz pole wyboru oznaczone jako tak 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ź.

Zapoznaj się z następującymi przewodnikami, aby dowiedzieć się, jak używać ai_query różnych przypadków użycia:

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.3 lub nowsze. Użycie środowiska Databricks Runtime 15.2 lub nowszego może spowodować obniżenie szybkości wydajności.
  • Bieżący kanał magazynu DLT nie używa najnowszej wersji środowiska Databricks Runtime obsługującej program ai_query(). Set pipelines.channel we właściwościach table jako 'preview' do użycia ai_query(). Zobacz Przykłady przykładowego zapytania.
  • Istniejący model obsługujący punkt końcowy z załadowanym modelem. Zobacz Tworzenie niestandardowych punktów końcowych obsługujących model.
  • Obszar roboczy musi znajdować się w obsługiwanym regionie obsługa modeli.
  • Interfejsy API modelu programu Querying Foundation są domyślnie włączone. Aby wykonywać zapytania dotyczące punktów końcowych obsługujących modele niestandardowe lub modele zewnętrzne:

Uwaga

  • W środowisku Databricks Runtime 14.2 lub nowszym ta funkcja jest obsługiwana w notesach usługi Databricks, w tym notesach uruchamianych jako zadanie w przepływie pracy usługi Databricks.
  • W środowisku Databricks Runtime 14.1 lub nowszym ta funkcja nie jest obsługiwana w notesach usługi Databricks.

Składnia

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

ai_query(endpoint, request)

Aby wysłać zapytanie do niestandardowego modelu obsługującego punkt końcowy za pomocą modelu schema:

ai_query(endpoint, request)

Aby wysłać zapytanie do niestandardowego punktu końcowego obsługującego modele bez konieczności wskazywania konkretnego modelu schema:

ai_query(endpoint, request, returnType, failOnError)

Argumenty

  • endpoint: literał STRING, nazwa punktu końcowego do obsługi modelu Databricks Foundation, zewnętrznego punktu końcowego do obsługi modelu lub punktu końcowego modelu niestandardowego w tym samym obszarze roboczym do wywołań. Definiujący musi mieć uprawnienia CAN QUERY na końcówce.
  • request: wyrażenie , żądanie użyte do wywołania punktu końcowego.
    • 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ługującym model niestandardowy, żądanie może być pojedynczym column lub wyrażeniem strukturalnym. Nazwy pól struktury powinny być zgodne z nazwami funkcji wejściowych oczekiwaną przez punkt końcowy.
  • returnType: Wyrażenie, oczekiwane returnType z punktu końcowego. Jest to podobne do parametru schema w funkcji from_json, który akceptuje zarówno wyrażenie STRING, jak i wywołanie funkcji schema_of_json.
    • W środowisku Databricks Runtime 14.2 i nowszym, jeśli to wyrażenie nie zostanie podane, ai_query() automatycznie wywnioskuje typ zwracany z modelu schema niestandardowego punktu końcowego obsługującego model.
    • W środowisku Databricks Runtime 14.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 domyślnie ma wartość true. Ta flaga wskazuje, czy w odpowiedzi ma być uwzględniny stan błędu ai_query .
  • modelParameters (opcjonalnie): pole struktury zawierające czat, uzupełnianie i osadzanie modelu parameters do obsługi modeli podstawowych lub modeli zewnętrznych. Te modele parameters muszą być stałe parameters, a nie zależne od danych. Jeśli modele parameters nie są określone lub zakres od set do null, używana jest wartość domyślna. Z wyjątkiem temperature, która ma domyślną wartość 0.0, domyślne values dla tych modeli parameters są takie same jak te wymienione w dokumentacji REST API modelu bazowego .
  • responseFormat (opcjonalnie): pole ciągu JSON określające format odpowiedzi, którego model ma przestrzegać. Obsługiwane są trzy typy ciągów w formacie odpowiedzi:
    • text
    • json_object
    • json_schema

Zwraca

Przeanalizowana odpowiedź z punktu końcowego.

  • 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 schema modelu lub parametru returnType w funkcji ai_query.
  • Jeśli failOnError => false, funkcja zwraca przeanalizowaną odpowiedź i ciąg stanu błędu jako obiekt STRUCT.
    • Jeśli wnioskowanie wiersza zakończyło się pomyślnie, pole errorStatus jest null.
    • Jeśli wnioskowanie wiersza nie powiodło się z powodu błędów punktu końcowego modelu, pole response jest null.
    • Jeśli wnioskowanie wiersza nie powiodło się z powodu innych błędów, całe zapytanie kończy się niepowodzeniem.
  • 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”...}'odpowiedź jest ciągiem JSON. Zobacz przykłady .
  • Jeśli failOnError => false i określono responseFormat, funkcja zwraca przeanalizowaną odpowiedź i ciąg stanu błędu jako obiekt STRUCT.

przykłady

W poniższym przykładzie określono format odpowiedzi json_schema:


SELECT
  ai_query(
    "llama-3-1-70b",
    <request>,
    responseFormat =>'{
                        "type": "json_schema",
                        "json_schema":
                          {
                           "name": "research_paper_extraction",
                           "schema":
                             {
                              "type": "object",
                              "properties":
                               {
                                "title": { "type": "string" }
                               }
                             },
                            "strict": true
                          }
                      }'
  )

Poniżej przedstawiono przykładowe dane wyjściowe dla określonego formatu odpowiedzi json_schema:

{"title": "<the title of the paper>"}

Poniżej przedstawiono przykład wnioskowania wsadowego przy użyciu elementów failOnError i modelParameters i max_tokens .temperature W tym przykładzie pokazano również, jak połączyć monit dla modelu i proces wnioskowania column z użyciem concat(). Istnieje wiele sposobów łączenia, takich jak używanie ||metody , concat()lub format_string().


CREATE OR REPLACE TABLE ${output_table_name} AS (
  SELECT
      ${input_column_name},
      AI_QUERY(
        "${endpoint}",
        CONCAT("${prompt}", ${input_column_name}),
        failOnError => false,
        modelParameters => named_struct('max_tokens', ${num_output_tokens},'temperature', ${temperature})
      ) as response
    FROM ${input_table_name}
    LIMIT ${input_num_rows}
)

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 dotyczące modelu podstawowego obsługiwanego przez interfejsy API modelu usługi Databricks Foundation:

> SELECT *,
  ai_query(
    'databricks-meta-llama-3-1-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ż opakowować wywołanie w ai_query() funkcji zdefiniowanej przez użytkownika w celu wywoływania funkcji w następujący sposób:

> CREATE FUNCTION correct_grammar(text STRING)
  RETURNS STRING
  RETURN ai_query(
    'databricks-meta-llama-3-1-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;

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


> 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-2-7b-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ładowe zapytanie dotyczące ustawiania kanału DLT na podgląd:

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