Delen via

ai_query functie

  • Artikel

Van toepassing op:aangevinkt ja Databricks SQL aangevinkt ja Databricks Runtime

Belangrijk

Deze functie is beschikbaar als openbare preview.

Roept een bestaand Azure Databricks Model Serving-eindpunt aan en parseert en retourneert het antwoord.

Om ai_query in productiewerkstromen te gebruiken, raadpleeg Voer batch LLM-afleiding uit met AI Functions.

Eisen

Notitie

  • In Databricks Runtime 14.2 en hoger wordt deze functie ondersteund in Databricks-notebooks, waaronder notebooks die worden uitgevoerd als een taak in een Databricks-werkstroom.
  • In Databricks Runtime 14.1 en lager wordt deze functie niet ondersteund in Databricks-notebooks.

  • Deze functie is niet beschikbaar in Azure Databricks SQL Classic.

  • U moet Azure Private Link inschakelen om deze functie te kunnen gebruiken in pro SQL Warehouses.

  • Databricks Runtime 15.3 of hoger wordt aanbevolen. Het gebruik van Databricks Runtime 15.2 of lager kan leiden tot tragere prestatiesnelheden.

  • Uw werkruimte moet zich in een ondersteunde regio voor het leveren van modellen bevinden.

  • Een bestaand model dat het eindpunt bedient terwijl uw model is geladen. Als u een door Databricks gehost basismodel gebruikt, wordt er een eindpunt voor u gemaakt. Zie anders Aangepast model maken voor eindpunten of Basismodel maken voor eindpunten.

  • Query's uitvoeren op Foundation Model-API's is standaard ingeschakeld. Eindpunten die specifieke aangepaste modellen of externe modellenbedienen, opvragen.

    • Schakel AI_Query in voor aangepaste modellen en externe modellen in de gebruikersinterface van Databricks Previews.

  • Het huidigeDLT-magazijnkanaal gebruikt niet de nieuwste versie van Databricks Runtime die ai_query() ondersteunt. Stel de pipelines.channel in de tabeleigenschappen in als 'preview' om ai_query()te gebruiken.

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

Syntaxis

Een query uitvoeren op een eindpunt dat een basismodel dient, inclusief externe modellen of een aangepast basismodel:

ai_query(endpoint, request)

Een query uitvoeren op een aangepast model voor eindpunten met een modelschema:

ai_query(endpoint, request)

Een query uitvoeren op een aangepast model voor eindpunten zonder modelschema:

ai_query(endpoint, request, returnType, failOnError)

Argumenten en retourwaarden

Betoog Beschrijving Retouren
endpoint Een STRING literal, de naam van een Databricks Foundation Model voor het bedienen van een eindpunt, een extern model dat eindpunt bedient of een aangepast modeleindpunt in dezelfde werkruimte voor oproepen. De definieerder moet CAN QUERY machtiging hebben voor het eindpunt.
request Een expressie, de aanvraag die wordt gebruikt om het eindpunt aan te roepen.
  • Als het eindpunt een extern modelbedieningseindpunt of een Databricks Foundation Model API-eindpunt is, moet de aanvraag een STRINGzijn.
  • Als het eindpunt een aangepast modeluitvoerings-eindpunt is, kan het verzoek één kolom of een struct-expressie zijn. De veldnamen van de struct moeten overeenkomen met de namen van invoerfuncties die door het eindpunt worden verwacht.
returnType Een expressie, de verwachte returnType van het eindpunt. Dit is vergelijkbaar met de schemaparameter in from_json functie, die zowel een STRING expressie als aanroep van schema_of_json functie accepteert.
  • In Databricks Runtime 14.2 en hoger, als deze expressie niet is opgegeven, wordt ai_query() automatisch het retourtype afgeleid uit het modelschema van het aangepaste model-bedieningseindpunt.
  • In Databricks Runtime 14.1 en lager is deze expressie vereist voor het uitvoeren van query's op een aangepast model voor eindpunten.
failOnError (Optioneel) Een booleaanse letterlijke waarde die standaard waar is. Met deze vlag wordt aangegeven of de foutstatus in het ai_query antwoord moet worden opgenomen.
  • Als failOnError => true, de functie retourneert hetzelfde resultaat als het bestaande gedrag. Dit is het geparseerde antwoord van het eindpunt. Het gegevenstype van het geparseerde antwoord wordt afgeleid van het modeltype, het eindpunt van het modelschema of de parameter returnType in de functie ai_query.
  • Als failOnError => false, retourneert de functie een STRUCT object dat het geparseerde antwoord en de foutstatustekenreeks bevat.
  • Als de afleiding van de rij slaagt, is het veld errorStatusnull.
  • Als de inferentie van de rij mislukt vanwege fouten in het modeleindpunt, is het response veld null.
  • Als de deductie van de rij mislukt vanwege andere fouten, mislukt de hele query.

Zie Fouten verwerken met behulp van failOnError voor een voorbeeld.
modelParameters (Optioneel) Een structveld dat chat-, voltooiings- en insluitmodelparameters bevat voor het leveren van basismodellen of externe modellen. Deze modelparameters moeten constante parameters zijn en niet gegevensafhankelijk. Wanneer deze modelparameters niet zijn opgegeven of zijn ingesteld op null wordt de standaardwaarde gebruikt. Met uitzondering van temperature die een standaardwaarde van 0.0heeft, zijn de standaardwaarden voor deze modelparameters hetzelfde als die worden vermeld in Rest API-verwijzingvan het Foundation-model.
Zie Een model configureren door modelparameters door te geven voor een voorbeeld.
responseFormat (Optioneel) Een JSON-tekenreeksveld dat de antwoordindeling aangeeft die het model moet volgen. Er worden drie tekenreekstypen van de antwoordindeling ondersteund:
  • text
  • json_object
  • json_schema
  • Als failOnError => false en u responseFormathebt opgegeven, retourneert de functie het geparseerde antwoord en de foutstatustekenreeks als een STRUCT-object.
  • Afhankelijk van het JSON-tekenreekstype dat is opgegeven in responseFormat, wordt het volgende antwoord geretourneerd:
  • Voor responseFormat => '{"type": "text"}'is het antwoord een tekenreeks zoals “Here is the response”.
  • Voor responseFormat => '{"type": "json_object"}'is het antwoord een JSON-tekenreeks met sleutel-waardeparen, zoals {“key”: “value”}.
  • Voor responseFormat => '{"type": "json_schema", "json_schema"...}'is het antwoord een JSON-tekenreeks.

Zie Handhaaf het uitvoerschema met gestructureerde uitvoer voor een voorbeeld.

de prompt en deductiekolom samenvoegen

Er zijn meerdere manieren om de prompt en de deductiekolom samen te voegen, zoals het gebruik van ||, CONCAT()of format_string():

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

U kunt ook het volgende doen:

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

Of met behulp van format_string():

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

een model configureren door modelparameters door te geven

Pas modelgedrag aan door specifieke parameters, zoals maximumtokens en temperatuur, door te geven. Voorbeeld:

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;

fouten verwerken met behulp van failOnError

Gebruik het argument failOnError voor ai_query om fouten te verwerken. In het volgende voorbeeld ziet u hoe u ervoor kunt zorgen dat als één rij een fout bevat, de hele query niet wordt uitgevoerd. Zie Argumenten en retourneert voor verwacht gedrag op basis van hoe dit argument is ingesteld.


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;

Het uitvoerschema afdwingen met gestructureerde output

Zorg ervoor dat de uitvoer voldoet aan een specifiek schema voor eenvoudiger downstreamverwerking. U kunt bijvoorbeeld een JSON-schemaresponsformaat afdwingen.

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;

U kunt ook een JSON-schema in DDL-stijl gebruiken:

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;

Een verwachte uitvoer kan er als volgt uitzien:

{ "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 gebruiken in door de gebruiker gedefinieerde functies

U kunt een aanroep naar ai_query in een UDF laten teruglopen, zodat u functies eenvoudig kunt gebruiken in verschillende werkstromen en deze kunt delen.

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;

voorbeeld: een query uitvoeren op een basismodel

Om een query uit te voeren op een extern model dat wordt bediend via een eindpunt:

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

Een query uitvoeren op een basismodel dat wordt ondersteund door Databricks Foundation Model-API's:

> 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

U kunt desgewenst ook een oproep naar ai_query() in een UDF verpakken om een functie als volgt aan te roepen:

 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;

Voorbeeld: Gebruiksscenario voor batchafleiding

Hieronder volgt een voorbeeld van batch-inferentie met behulp van failOnError en modelParameters en met max_tokens en temperature. In dit voorbeeld ziet u ook hoe u de prompt voor uw model en de deductiekolom kunt samenvoegen met behulp van CONCAT().

Er zijn meerdere manieren om samenvoeging uit te voeren, zoals het gebruik ||, concat()of 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}
)

Voorbeeld: Een query uitvoeren op een traditioneel ML-model

Een query uitvoeren op een aangepast model of een traditioneel ML-model voor eindpunten:


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