Funkce `ai_query`

2025-05-20

Platí pro: je zaškrtnuto ano Databricks SQL 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ěď.

Pokud chcete použít ai_query v produkčních pracovních postupech, přečtěte si téma Provedení dávkového odvozování LLM pomocí funkcí AI.

Požadavky

Tato funkce není dostupná v Azure Databricks SQL Classic.
Abyste mohli tuto funkci používat ve službě Pro SQL Warehouse, musíte povolit službu Azure Private Link .
Doporučuje se Databricks Runtime 15.4 LTS nebo vyšší. Použití Databricks Runtime 15.3 nebo nižší může vést k pomalejšímu výkonu.
Váš pracovní prostor musí být v podporované oblasti obsluhy modelů.
Existující model obsluhující koncový bod s načteným modelem Pokud používáte model základní úrovně hostovaný službou Databricks, vytvoří se pro vás koncový bod. V opačném případě se podívejte na Vytvoření vlastních modelů obsluhujících koncové body nebo Vytvoření základního modelu obsluhujícího koncové body.
Dotazování rozhraní API základního modelu je ve výchozím nastavení povolené. Pro dotazy ke koncovým bodům, které obsluhují vlastní modely nebo externí modely:
- V uživatelském rozhraní Databricks Preview povolte AI_Query pro vlastní modely a externí modely.
Aktuálníkanál skladu deklarativních kanálů Lakeflow nepoužívá nejnovější verzi databricks Runtime, která podporuje ai_query(). Nastavte pipelines.channel ve vlastnostech tabulky na 'preview' tak, aby používal 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;
```

Syntaxe

Dotazování koncového bodu, který slouží jako základní model:

ai_query(endpoint, request)

Pro dotazování koncového bodu obsluhujícího vlastní model 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 a návraty

důvod	Popis	Návraty
`endpoint`	Název koncového bodu obsluhy modelu Databricks Foundation, externího koncového bodu obsluhy modelu nebo vlastního koncového bodu modelu ve stejném pracovním prostoru, které jsou používány pro vyvolání jako `STRING` literále. Určovatel musí mít ke koncovému bodu oprávnění `CAN QUERY`.
`request`	Požadavek použitý k vyvolání koncového bodu jako výrazu. Pokud je koncový bod koncovým bodem pro obsluhu externího modelu nebo koncovým bodem API modelu nadace Databricks, 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`	Očekávaná hodnota `returnType` z koncového bodu jako výrazu. To se podobá parametru schématu v `from_json` funkce, který přijímá výraz `STRING` nebo vyvolání `schema_of_json` funkce. V Databricks Runtime 15.2 a vyšším, pokud tento výraz není zadaný, `ai_query()` automaticky odvodí návratový typ ze schématu modelu koncového bodu obsluhy vlastního modelu. V Databricks Runtime 15.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ý má výchozí hodnotu true. Vyžaduje Databricks Runtime 15.3 nebo novější. Tento příznak označuje, jestli se má do `ai_query` odpovědi zahrnout stav chyby.	Pokud `failOnError => true`funkce 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 objekt `STRUCT`, který obsahuje analyzovanou odpověď a řetězec stavu chyby. Pokud je odvození řádku úspěšné, `errorStatus` pole je `null`. Pokud dojde k selhání odvozování řádku kvůli chybám na koncovém bodě modelu, pole `response` je `null`. Pokud odvozování řádku selže kvůli jiným chybám, celý dotaz selže. Příklad najdete v tématu Zpracování chyb pomocí `failOnError`.
`modelParameters`	(Volitelné) Pole struktury, které obsahuje parametry modelů pro chat, dokončování a vkládání, určené pro základní nebo externí modely. Tyto parametry modelu musí být konstantní parametry, nikoli závislé na datech. Vyžaduje Databricks Runtime 15.3 nebo novější. 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 . Příklad najdete v tématu Konfigurace modelu předáním parametrů modelu.
`responseFormat`	(Volitelné) Zadejte formát odpovědi, který má model chatu sledovat. Vyžaduje Databricks Runtime 15.4 LTS nebo vyšší. K dispozici pouze pro dotazování základních modelů chatu. Podporují se dva styly formátu odpovědi. Řetězec JSON ve stylu DDL Řetězec JSON. Podporují se tři typy řetězců JSON formátu odpovědi: `text` `json_object` `json_schema` Příklady najdete v tématu Vynucení výstupního schématu se strukturovaným výstupem .	Pokud `failOnError => false` a zadali jste `responseFormat`, vrátí funkce analyzovanou odpověď a řetězec stavu chyby jako objekt `STRUCT`. V závislosti na typu řetězce JSON zadaném v `responseFormat`se 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", "json_schema"...}'`je odpovědí řetězec JSON. Příklady najdete v tématu Vynucení výstupního schématu se strukturovaným výstupem .

příklad : Dotazování základního modelu

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

Volitelně můžete také zabalit výzvu ai_query() do uživatelské funkce (UDF) následujícím způsobem:

 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;

Příklad: Dotazování tradičního modelu ML

Pro dotazování vlastního modelu nebo tradičního koncového bodu pro obsluhu modelů strojového učení:


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

Příklady pro pokročilé scénáře

Následující části obsahují příklady pokročilých případů použití, jako je zpracování chyb nebo postup začlenění ai_query do uživatelem definované funkce.

Zřetěte sloupec s výzvou a sloupec s odvozením

Existuje několik způsobů propojení výzvy a sloupce usuzování, například pomocí ||, CONCAT()nebo format_string():

SELECT
CONCAT('${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};

Alternativně:

SELECT
'${prompt}' || ${input_column_name} AS concatenated_prompt
FROM ${input_table_name};

Nebo pomocí format_string():

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

Konfigurace modelu předáním parametrů modelu

Přizpůsobte chování modelu předáním konkrétních parametrů, jako jsou maximální tokeny a teplota. Například:

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;

zpracování chyb pomocí `failOnError`

K zpracování chyb použijte argument failOnError pro ai_query. Následující příklad ukazuje, jak se ujistit, že pokud jeden řádek obsahuje chybu, nezastaví to běh celého dotazu. Viz Argumenty a návraty pro očekávané chování na základě toho, jak je tento argument nastaven.


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;

Vynucení výstupního schématu použitím strukturovaného výstupu

Ujistěte se, že výstup odpovídá určitému schématu pro snadnější následné zpracování pomocí responseFormat. Viz strukturované výstupy v Azure Databricks.

Následující příklad vynucuje schéma řetězce JSON ve 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;

Alternativně můžete použít formát odpovědi schématu 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;

Očekávaný výstup může vypadat takto:

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

Použití `ai_query` v uživatelem definovaných funkcích

Volání funkce ai_query můžete zabalit do UDF, což umožní snadné používání funkcí napříč různými pracovními postupy a jejich sdílení.

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;

Sdílet prostřednictvím

Funkce ai_query