Funkce ai_query

Platí pro: Databricks SQL Databricks Runtime

Important

Tato funkce je ve verzi Public Preview a kompatibilní se standardem HIPAA.

Během náhledu:

• Základní jazykový model dokáže zpracovat několik jazyků, ale tato funkce AI je vyladěná pro angličtinu.
• Viz Funkce s omezenou regionální dostupností pro dostupnost oblasti AI Functions.

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

ai_query je funkce AI pro obecné účely, která umožňuje dotazovat existující koncové body pro odvozování v reálném čase nebo úlohy dávkového odvozování.

• Viz funkci pro všeobecné použití: ai_query pro podporované modely a požadované konfigurace koncových bodů.
• Můžete také použít ai_query k dotazování agenta AI nasazeného v koncovém bodu obsluhy modelu ML. Viz Dotazování nasazeného agenta Mosaic AI.
• Pokud chcete použít ai_query v produkčních pracovních postupech, viz Nasazení dávkových inferenčních kanálů.

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ů Sparku Lakeflow nepoužívá nejnovější verzi modulu 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;
  

Syntax

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

Argument	Description	Returns
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ý bod vlastním modelem obsluhující koncový bod, může být požadavek jedním sloupcem nebo výrazem STRUCT. Názvy polí STRUCT by měly odpovídat názvům vstupních funkcí očekávaným koncovým bodem.
returnType	(Volitelné pro Databricks Runtime 15.2 a vyšší) Očekávaná returnType hodnota z koncového bodu jako výraz. To se podobá parametru schématu v from_json funkce, který přijímá výraz STRING nebo vyvolání schema_of_json funkce. Pro Databricks Runtime 15.2 a vyšší je tento výraz volitelný. Pokud není zadaný, ai_query() automaticky odvodí návratový typ ze schématu modelu vlastního koncového bodu obsluhy modelu. Pro Databricks Runtime 15.1 a níže se tento výraz vyžaduje pro dotazování vlastního koncového bodu obsluhy modelu. Pomocí parametru responseFormat můžete určit formáty odpovědí pro základní modely chatu.
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. Příklad najdete v tématu Zpracování chyb pomocí failOnError.	Následuje popis chování při vrácení založený na scénáři failOnError. 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 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.
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 základu chatu ná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 .	Následující popis popisuje, co se stane, když failOnError je také nastaven, když responseFormat je zadán: 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 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", "json_schema"...}'je odpovědí řetězec JSON.
files	(Volitelné) Určete, které soubory a obsah se mají použít v multimodálních vstupních požadavcích pomocí files=>content. files je název parametru očekávaný modelem pro multimodální vstup a content odkazuje na sloupec v datovém rámci, který obsahuje binární obsah souborů obrázků, které chcete použít v dotazu. Vyžaduje se pro multimodální požadavky. Podporují se pouze vstupy obrázků: JPEG nebo PNG jsou podporovány. Příklad najdete ve vícemodálních vstupech . Jak je vidět v tomto příkladu, můžete zadat content sloupec výstupu z read_files do parametru files.

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;

Multimodální vstupy

ai_query nativně podporuje vstupy multimodálních imagí. Viz Základní typy modelů pro podporované modely zpracování obrazu hostované službou Databricks.

Následující typy vstupu jsou podporované:

• JPEG
• PNG

Následující příklad ukazuje, jak dotazovat základní model podporovaný rozhraními DATAbricks Foundation Model API pro multimodální vstup. V tomto příkladu files => content se parametr používá k předání dat souboru obrázku do ai_query

• files: Název parametru očekávaný modelem pro vícemodální vstup
• content: Sloupec v datovém rámci vrácený objektem READ_FILES, který obsahuje binární obsah souboru obrázku.

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

Dotazování základního modelu podporovaného rozhraními API modelu Databricks Foundation pro multimodální vstup a určení strukturovaného výstupu:

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

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

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.

Předejte pole zpráv

Následující příklad ukazuje, jak předat pole zpráv do modelu nebo aplikace agenta pomocí 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."]}

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

Alternatively:

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

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

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;