A `ai_query` függvény

2025-05-20

A következőkre vonatkozik: igen, bejelölve Databricks SQL Databricks Runtime

Fontos

Ez a funkció nyilvános előzetes verzióban érhető el.

Meghív egy meglévő Azure Databricks-modellszolgáltatás végpontját , elemzi és visszaadja a választ.

Az éles munkafolyamatokban való használatról ai_query lásd: Batch LLM-következtetés végrehajtása az AI Functions használatával.

Követelmények

Ez a függvény nem érhető el a klasszikus Azure Databricks SQL-ben.
Engedélyeznie kell az Azure Private Linket, hogy ezt a funkciót pro SQL-raktárakban használja.
A Databricks Runtime 15.4 LTS vagy újabb verziója ajánlott. A Databricks Runtime 15.3 vagy újabb használata lassabb teljesítménysebességet eredményezhet.
A munkaterületnek támogatott modellkiszolgáló régióban kell lennie.
Egy meglévő modellkiszolgáló végpont, amelyre a modell fel van töltve. Ha Databricks által üzemeltetett alapmodellt használ, a rendszer létrehoz egy végpontot. Ellenkező esetben lásd: Végpontokat kiszolgáló egyéni modell létrehozása vagy végpontokat kiszolgáló alapmodell létrehozása.
Az alapmodell API-k lekérdezése alapértelmezés szerint engedélyezve van. Egyéni vagy külső modelleket kiszolgáló végpontok lekérdezése:
- Engedélyezze AI_Query egyéni modellekhez és külső modellekhez a Databricks előnézeti felületén.
Az aktuálisLakeflow Deklarative Pipelines adattárcsatorna nem a legújabb Databricks Runtime verziót használja, amely támogatja ai_query(). Állítsa be a táblázat tulajdonságaiban a pipelines.channel-t 'preview'-re, hogy használhassa a ai_query()-t.
```
> 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;
```

Szintaxis

Alapmodellt kiszolgáló végpont lekérdezése:

ai_query(endpoint, request)

A végpontot kiszolgáló egyéni modell lekérdezése modellsémával:

ai_query(endpoint, request)

A végpontot modellséma nélkül kiszolgáló egyéni modell lekérdezése:

ai_query(endpoint, request, returnType, failOnError)

Argumentumok és visszatérési értékek

érvelés	Leírás	Visszaküldések
`endpoint`	A Databricks Foundation-modell kiszolgáló végpontjának neve, egy külső modellkiszolgáló végpont vagy egy egyéni modellvégpont neve ugyanabban a munkaterületen, a meghívások során mint `STRING` literál. A definiálónak `CAN QUERY` engedéllyel kell rendelkeznie a végponton.
`request`	A végpont kifejezésként való meghívásához használt kérés. Ha a végpont egy végpontot kiszolgáló külső modell vagy a Databricks Foundation modell API-végpontja, a kérésnek `STRING`kell lennie. Ha a végpont egy végpontot kiszolgáló egyéni modell, a kérés lehet egyetlen oszlop vagy egy strukturált kifejezés. A struct mezőneveknek meg kell egyeznie a végpont által várt bemeneti szolgáltatásnevekkel.
`returnType`	A végponttól elvárt `returnType` kifejezés. Ez hasonló a függvény sémaparaméteréhez`from_json`, amely a függvény kifejezését `STRING` vagy meghívását `schema_of_json`egyaránt elfogadja. A Databricks Runtime 15.2-es és újabb verzióiban, ha ez a kifejezés nincs megadva, `ai_query()` automatikusan a végpontot kiszolgáló egyéni modell modellséma alapján következtet a visszatérési típusra. A Databricks Runtime 15.1-ben és alatta ez a kifejezés szükséges egy végpontot kiszolgáló egyéni modell lekérdezéséhez.
`failOnError`	(Nem kötelező) Logikai literál, amely alapértelmezés szerint igaz. A Databricks Runtime 15.3-at vagy újabb verzióját igényli. Ez a jelző azt jelzi, hogy szerepel-e hibaállapot a `ai_query` válaszban.	Ha `failOnError => true`a függvény ugyanazt az eredményt adja vissza, mint a meglévő viselkedés, amely a végpontból származó elemzési válasz. Az elemezett válasz adattípusa a modelltípusból, a modellsémavégpontból vagy a `returnType` függvény `ai_query` paraméteréből származik. Ha `failOnError => false`, a függvény egy `STRUCT` objektumot ad vissza, amely tartalmazza az elemezett választ és a hibaállapot-sztringet. Ha sikeres a sor következtetése, akkor a `errorStatus` mező `null`. Ha a sor értelmezése modell végponti hibák miatt meghiúsul, a `response` mező `null`. Ha a sor következtetése más hibák miatt meghiúsul, a teljes lekérdezés meghiúsul. Lásd: Hibák kezelése `failOnError` példaként.
`modelParameters`	(Nem kötelező) Egy strukturálási mező, amely az alapmodellek vagy külső modellek kiszolgálásához használható csevegési, befejezési és beágyazási modellparamétereket tartalmazza. Ezeknek a modellparamétereknek állandó paramétereknek kell lenniük, és nem adatfüggőnek. A Databricks Runtime 15.3-at vagy újabb verzióját igényli. Ha ezek a modellparaméterek nincsenek megadva, vagy `null`-ra vannak állítva, az alapértelmezett érték kerül alkalmazásra. Azon kivételével `temperature` , amelynek alapértelmezett értéke `0.0`van, a modellparaméterek alapértelmezett értékei megegyeznek az Foundation-modell REST API-referenciajában felsorolt értékekkel. Lásd : Modell konfigurálása modellparaméterek átadásával egy példához.
`responseFormat`	(Nem kötelező) Adja meg azt a válaszformátumot, amelyet a csevegőmodell követni szeretne. A Databricks Runtime 15.4 LTS-t vagy újabb verziót igényel. Csak a csevegési alapmodellek lekérdezéséhez érhető el. A válaszformátum két stílusa támogatott. DDL stílusú JSON-sztring Egy JSON-sztring. A válaszformátum három JSON-sztringtípusa támogatott: `text` `json_object` `json_schema` Példákért lásd: Kimeneti séma kényszerítése strukturált kimenettel .	Ha `failOnError => false`, és megadta a `responseFormat`, a függvény az elemzési választ és a hibaállapot-sztringet adja vissza `STRUCT` objektumként. A `responseFormat`megadott JSON-sztringtípustól függően a rendszer a következő választ adja vissza: A `responseFormat => '{"type": "text"}'`esetében a válasz egy karaktersorozat, például `“Here is the response”`. A `responseFormat => '{"type": "json_object"}'`esetén a válasz egy kulcs-érték pár JSON-sztring, például `{“key”: “value”}`. A `responseFormat => '{"type": "json_schema", "json_schema"...}'`esetében a válasz egy JSON-sztring. Példákért lásd: Kimeneti séma kényszerítése strukturált kimenettel .

Példa: Alapmodell lekérdezése

Végpontot kiszolgáló külső modell lekérdezése:

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

A Databricks Foundation Model API-k által támogatott alapmodell lekérdezése:

> 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

Opcionálisan, a ai_query() hívást egy UDF-ben is becsomagolhatja a függvényhíváshoz az alábbiak szerint:

 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élda: Hagyományos ml-modell lekérdezése

Egyéni modell vagy egy végpontot kiszolgáló hagyományos ML-modell lekérdezése:


> 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éldák speciális forgatókönyvekre

Az alábbi szakaszok olyan speciális használati esetekre mutatnak be példákat, mint a hibakezelés vagy a felhasználó által definiált függvények beépítése ai_query .

Fűzd össze a kérés és a következtetés oszlopot

A parancssort és a következtetési oszlopot többféleképpen is összefűzheti, például ||, CONCAT()vagy format_string():

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

Alternatív megoldás:

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

Vagy format_string()használata:

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

Modell konfigurálása modellparaméterek átadásával

Testre szabhatja a modell viselkedését bizonyos paraméterek, például a maximális tokenek és a hőmérséklet átadásával. Például:

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;

Hibák kezelése `failOnError`

Használja a failOnError argumentumot a ai_query hibák kezeléséhez. Az alábbi példa bemutatja, hogyan győződhet meg arról, hogy ha egy sor hibával rendelkezik, az nem állítja le a teljes lekérdezés futtatását. Tekintse meg az Arguments és returns részt a várt viselkedések kapcsán, attól függően, hogyan van beállítva az argumentum.


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;

Adja meg a kimeneti sémát strukturált kimenettel

Győződjön meg arról, hogy a kimenet megfelel egy adott sémának a könnyebb továbbfeldolgozás responseFormatérdekében. Lásd az Azure Databricks strukturált kimeneteit.

Az alábbi példa egy DDL-stílusú JSON-sztringsémát kényszerít ki:

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;

Másik lehetőségként JSON-séma válaszformátumot is használhat:

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;

A várt kimenet a következőképpen nézhet ki:

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

`ai_query` használata felhasználó által definiált függvényekben

A ai_query hívásait egy UDF-ben is becsomagolhatja, így egyszerűen használhat függvényeket különböző munkafolyamatokban, és megoszthatja őket.

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;

Megosztás a következőn keresztül:

A ai_query függvény