A `ai_query` függvény

A következőkre vonatkozik: jelölje be az igennel jelölt jelölőnégyzetet Databricks SQL Databricks Runtime

Important

Ez a funkció nyilvános előzetes verzióban és HIPAA-kompatibilis.

Az előzetes verzióban:

A mögöttes nyelvi modell több nyelvet is képes kezelni, de ez az AI-függvény angolra van hangolva.
Az korlátozott elérhetőségű régiók listáját tekintse meg, hogy tájékozódjon az AI Functions elérhetőségéről.

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

ai_query Egy általános célú AI-függvény , amely lehetővé teszi a meglévő végpontok lekérdezését valós idejű következtetési vagy kötegelt következtetési számítási feladatokhoz.

Lásd : Általános célú függvény: ai_query támogatott modellek és szükséges végpontkonfigurációk.
Az ML-modell kiszolgáló végpontján üzembe helyezett AI-ügynök lekérdezésére is használható ai_query , lásd: Üzembe helyezett Mozaik AI-ügynök lekérdezése
A ai_query alkalmazását éles munkafolyamatokban lásd a kötegelt következtetési folyamatok üzembe helyezése című szakaszban.

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 Spark Deklaratív folyamatok raktárcsatornája 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;
```

Syntax

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

Argument	Description	Returns
`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 STRUCT-kifejezés. A STRUCT mezőneveknek meg kell egyeznie a végpont által várt bemeneti funkciók nevével.
`returnType`	(Nem kötelező a Databricks Runtime 15.2-s vagy újabb verziója esetén) 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-s vagy újabb verziója esetén ez a kifejezés nem kötelező. Ha nincs megadva, `ai_query()` a visszatérési típus automatikusan az egyéni modell végpontját kiszolgáló modellsémából következtet. A Databricks Runtime 15.1 és újabb verzió esetén ez a kifejezés szükséges egy végpontot kiszolgáló egyéni modell lekérdezéséhez. A paraméter használatával `responseFormat` válaszformátumokat adhat meg a csevegés alapmodelljeihez.
`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. Lásd: Hibák kezelése `failOnError` példaként.	Az alábbi leírás a `failOnError` forgatókönyv alapján a visszatérési viselkedést írja le: 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.
`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és alapmodelljének követnie kell. 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_objectjson_schema` Példákért lásd: Kimeneti séma kényszerítése strukturált kimenettel .	Az alábbiak azt ismertetik, hogy mi történik, ha `failOnError` is be van állítva, amikor `responseFormat` meg van adva: 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.
`files`	(Nem kötelező) Adja meg, hogy mely fájlokat és tartalmakat szeretné használni a multimodális bemeneti kérésekben a használatával `files=>content`. `files` a modell által a multimodális bemenethez várt paraméternév, és `content` a DataFrame oszlopára hivatkozik, amely tartalmazza a lekérdezésben használni kívánt képfájlok bináris tartalmát. Multimodális kérésekhez szükséges. Csak képbemenetek: `JPEG` vagy `PNG` támogatottak. Példa: Multimodális bemenetek . A példában látható módon megadhatja a `content` kimenetének `read_files` oszlopát a `files` paraméter számára.

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;

Multimodális bemenetek

ai_query natív módon támogatja a multimodális képbemeneteket. Tekintse meg a támogatott, Databricks által üzemeltetett látásmodellek alapmodellek típusait.

A következő bemeneti típusok támogatottak:

JPEG
PNG

Az alábbi példa bemutatja, hogyan kérdezhetők le a Databricks Foundation Model API-k által támogatott alapmodellek a multimodális bemenethez. Ebben a példában a paraméter a files => content képfájl adatainak átadására szolgál ai_query

files: A modell által a multimodális bemenethez várt paraméternév
content: A dataFrame által visszaadott READ_FILESoszlop, amely a képfájl bináris tartalmát tartalmazza.


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

A Databricks Foundation Model API-k által támogatott alapmodell lekérdezése többmodális bemenethez és strukturált kimenet megadása:

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

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 .

Üzenettömböt átadni

Az alábbi példa bemutatja, hogyan továbbíthat egy üzenettömböt a modellnek vagy az ügynökalkalmazásnak a használatával 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."]}

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

Alternatively:

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

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

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;

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;

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-11-24