Delen via

ai_query-functie

  • Artikel

Van toepassing op: vinkje als ja aan Databricks SQL vinkje als ja aan 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.

Zie de volgende handleidingen voor het gebruik ai_query van verschillende gebruiksvoorbeelden:

Eisen

  • 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.
  • Het huidige DLT-magazijnkanaal gebruikt niet de nieuwste Databricks Runtime-versie die ondersteuning biedt ai_query()voor . Stel de pipelines.channel eigenschappen in de tabel zo in dat 'preview' deze moeten worden gebruikt ai_query(). Zie Voorbeelden voor een voorbeeldquery.
  • Een bestaand model dat het eindpunt bedient terwijl uw model is geladen. Zie Aangepast model maken voor eindpunten.
  • Uw werkruimte moet zich in een ondersteunde regio voor het leveren van modellen bevinden.
  • Query's uitvoeren op Foundation Model-API's is standaard ingeschakeld. Eindpunten opvragen die aangepaste modellen of externe modellen leveren:

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.

Syntaxis

Een query uitvoeren op een eindpunt dat een extern model of een basismodel dient:

ai_query(endpointName, request)

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

ai_query(endpointName, request)

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

ai_query(endpointName, request, returnType, failOnError)

Argumenten

  • endpointName: Een letterlijke tekenreeks, de naam van een Databricks Foundation-model voor eindpunten, een extern model dat eindpunt dient of een aangepast modeleindpunt in dezelfde werkruimte voor aanroepen. De definitier moet de machtiging CAN QUERY hebben voor het eindpunt.
  • request: Een expressie, de aanvraag die wordt gebruikt om het eindpunt aan te roepen.
    • Als het eindpunt een extern model is dat een eindpunt of Databricks Foundation Model-API-eindpunt biedt, moet de aanvraag een TEKENREEKS zijn.
    • Als het eindpunt een aangepast model voor eindpunt is, kan de aanvraag éé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, het verwachte returnType van het eindpunt. Dit is vergelijkbaar met de schemaparameter in from_json functie, die zowel een tekenreeksexpressie als aanroep van schema_of_json functie accepteert.
    • Als deze expressie niet is opgegeven, ai_query() wordt in Databricks Runtime 14.2 en hoger automatisch het retourtype afgeleid van het modelschema van het aangepaste eindpunt voor het leveren van het model.
    • 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. De antwoordindeling verschilt wanneer dit is ingesteld op false.
  • modelParameters (optioneel): Een structveld dat chat-, voltooiings- en insluitingsmodelparameters bevat voor het leveren van basismodellen of externe modellen. Deze modelparameters moeten constante parameters zijn en niet gegevensafhankelijk. Wanneer deze modelparameters niet worden opgegeven of ingesteld op null de standaardwaarde, wordt gebruikt. Met uitzondering van temperature een standaardwaarde van 0.0 zijn de standaardwaarden voor deze modelparameters hetzelfde als de waarden die worden vermeld in de REST API-verwijzing van het Foundation-model.

Retouren

Het geparseerde antwoord van het eindpunt.

  • 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 returnType parameter in de ai_query functie.
  • Als failOnError => false, de functie retourneert het geparseerde antwoord en de foutstatustekenreeks als een STRUCT-object.
    • Als de deductie van de rij is geslaagd, is het errorStatus veld null.
    • Als de deductie van de rij is mislukt vanwege fouten in het modeleindpunt, is het response veld null.
    • Als de deductie van de rij is mislukt vanwege andere fouten, mislukt de hele query.

Voorbeelden

Hier volgt een voorbeeld van batchdeductie met behulp van en failOnError modelParameters 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}
)

Een query uitvoeren op een extern model voor eindpunten:

> 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-1-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 aanroep in ai_query() een UDF verpakken voor functie-aanroepen als volgt:

> CREATE FUNCTION correct_grammar(text STRING)
  RETURNS STRING
  RETURN ai_query(
    'databricks-meta-llama-3-1-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;

Ga als volgende te werk om een query uit te voeren op een aangepast 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

> SELECT ai_query(
    'weekly-forecast',
    request => struct(*),
    returnType => 'FLOAT') AS predicted_revenue
  FROM retail_revenue

> SELECT ai_query(
    'custom-llama-2-7b-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."]}

Voorbeeldquery voor het instellen van het DLT-kanaal als voorbeeld:

> create or replace materialized view
    ai_query_mv
    TBLPROPERTIES('pipelines.channel' = 'PREVIEW') AS
  SELECT
    ai_query("databricks-dbrx-instruct", text) as response
  FROM
    messages