Sdílet prostřednictvím


Funkce ai_query

Platí pro:zaškrtnutí označeného ano Databricks SQL zaškrtnutí označeného ano Databricks Runtime

Důležité

Tato funkce je ve verzi Public Preview.

Vyvolá existující koncový bod služby Azure Databricks Model Serving a parsuje a vrátí její odpověď.

Informace o použití ai_query pro různé případy použití najdete v následujících příručkách:

Požadavky

Poznámka:

  • V Databricks Runtime 14.2 a novějších je tato funkce podporovaná v poznámkových blocích Databricks, včetně poznámkových bloků, které se spouští jako úkol v pracovním postupu Databricks.
  • V databricks Runtime 14.1 a níže není tato funkce v poznámkových blocích Databricks podporovaná.

Syntaxe

Dotazování koncového bodu, který obsluhuje externí model nebo základní model:

ai_query(endpoint, request)

Dotazování vlastního modelu obsluhujícího koncový bod pomocí schématu modelu :

ai_query(endpoint, request)

Dotazování vlastního modelu obsluhujícího koncový bod bez schématu modelu:

ai_query(endpoint, request, returnType, failOnError)

Argumenty

  • endpoint: Literál STRING, název koncového bodu pro obsluhu modelu Databricks Foundation, externí koncový bod pro obsluhu modelu nebo vlastní koncový bod modelu ve stejném pracovním prostoru pro vyvolání. Určovatel musí mít ke koncovému bodu oprávnění CAN QUERY.
  • request: Výraz, požadavek použitý k vyvolání koncového bodu.
    • Pokud je koncový bod externím modelem, který obsluhuje koncový bod nebo koncový bod rozhraní API modelu Databricks Foundation, musí být požadavek STRING.
    • Pokud je koncovým bodem vlastní model obsluhující koncový bod, může být požadavek jedním sloupcem nebo výrazem struktury. Názvy polí struktury by měly odpovídat názvům vstupních funkcí očekávaným koncovým bodem.
  • returnType: Výraz, který má být očekáván jako returnType z koncového bodu. Podobá se to parametru schématu ve funkci from_json, která přijímá buď výraz STRING, nebo vyvolání funkce schema_of_json.
    • Pokud tento výraz není zadaný, databricks Runtime 14.2 a vyšší ai_query() automaticky odvodí návratový typ ze schématu modelu vlastního koncového bodu obsluhy modelu.
    • V Databricks Runtime 14.1 a níže se tento výraz vyžaduje pro dotazování vlastního koncového bodu obsluhy modelu.
  • failOnError: (volitelné) Logický literál, který se ve výchozím nastavení nastaví na true. Tento příznak označuje, jestli se má do ai_query odpovědi zahrnout stav chyby.
  • modelParameters (volitelné): Pole struktury, které obsahuje parametry modelu chatu, dokončování a vkládání pro poskytování základních modelů nebo externích modelů. Tyto parametry modelu musí být konstantní parametry, nikoli závislé na datech. Pokud tyto parametry modelu nejsou zadány nebo nastaveny na null použije se výchozí hodnota. S výjimkou , která má výchozí hodnotu , jsou výchozí hodnoty pro tyto parametry modelu stejné jako hodnoty uvedené v referenčnírozhraní REST API modelu Foundation .
  • responseFormat (volitelné): Pole řetězce JSON, které určuje formát odpovědi, který má model sledovat. Podporují se tři typy řetězců formátu odpovědi:
    • text
    • json_object
    • json_schema

Návraty

Analyzovaná odpověď z koncového bodu.

  • Pokud failOnError => truefunkce vrátí stejný výsledek jako existující chování, což je analyzovaná odpověď z koncového bodu. Datový typ analyzované odpovědi se odvodí z typu modelu, koncového bodu schématu modelu nebo parametru returnType ve funkci ai_query.
  • Pokud failOnError => false, vrátí funkce analyzovanou odpověď a řetězec stavu chyby jako objekt STRUCT.
    • Pokud bylo odvození řádku úspěšné, pole errorStatus je null.
    • Pokud se inference řádku nezdařilo kvůli chybám koncového bodu modelu, response pole je null.
    • Pokud se odvozování řádku nezdařilo kvůli jiným chybám, celý dotaz selže.
  • V závislosti na typu řetězce JSON zadaném v responseFormatse vrátí následující odpověď:
    • Pro responseFormat => '{“type”, “text”}'je odpověď řetězec, například “Here is the response”.
    • Pro responseFormat => '{“type”, “json_object”}'je odpovědí řetězec JSON páru klíč-hodnota, například {“key”: “value”}.
    • Pro responseFormat => '{“type”, “json_schema”...}'je odpovědí řetězec JSON. Viz Příklady.
  • Pokud failOnError => false a zadali jste responseFormat, vrátí funkce analyzovanou odpověď a řetězec stavu chyby jako objekt STRUCT.

Příklady

Následující příklad určuje formát odpovědi 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
                          }
                      }'
  )

Následuje příklad výstupu pro zadaný formát odpovědi json_schema:

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

Následuje příklad dávkového odvození pomocí a failOnErrormodelParameters s max_tokens a temperature. Tento příklad také ukazuje, jak spojit výzvu pro váš model a sloupec inferencí pomocí concat(). Existuje několik způsobů, jak provést zřetězení, například pomocí ||, concat()nebo 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}
)

Dotazování externího modelu obsluhujícího koncový bod:

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

Dotazování základního modelu podporovaného rozhraními API modelu 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

Volitelně můžete také zabalit volání ai_query() do funkce pro volání funkcí následujícím způsobem:

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

Dotazování vlastního modelu obsluhujícího koncový bod:


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

Příklad dotazu pro nastavení kanálu DLT na náhled:

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