`ai_query` functie

2025-05-20

Van toepassing op: aangevinkt ja Databricks SQL 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

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.4 LTS of hoger wordt aanbevolen. Het gebruik van Databricks Runtime 15.3 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 huidigeLakeflow Declarative Pipelines Warehouse-kanaal gebruikt niet de nieuwste Databricks Runtime-versie die ai_query()ondersteuning biedt. 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-meta-llama-3-3-70b-instruct", text) as response
  FROM
    messages
  LIMIT 10;
```

Syntaxis

Een query uitvoeren op een eindpunt dat een basismodel dient:

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`	De naam van een Databricks Foundation-model dat een eindpunt bedient, een extern model dat het eindpunt of een aangepast modeleindpunt in dezelfde werkruimte biedt voor aanroepen als letterlijke `STRING` aanroepen. De definieerder moet `CAN QUERY` machtiging hebben voor het eindpunt.
`request`	De aanvraag die wordt gebruikt om het eindpunt aan te roepen als een expressie. Als het eindpunt een extern modelbedieningseindpunt of een Databricks Foundation Model API-eindpunt is, moet de aanvraag een `STRING`zijn. 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`	De verwachte `returnType` van het eindpunt als een expressie. Dit is vergelijkbaar met de schemaparameter in `from_json` functie, die zowel een `STRING` expressie als aanroep van `schema_of_json` functie accepteert. Als deze expressie niet is opgegeven in Databricks Runtime 15.2 en hoger, `ai_query()` wordt automatisch het retourtype afgeleid van het modelschema van het aangepaste eindpunt voor het leveren van modellen. In Databricks Runtime 15.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. Vereist Databricks Runtime 15.3 of hoger. 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. Vereist Databricks Runtime 15.3 of hoger. Wanneer deze modelparameters niet zijn opgegeven of zijn ingesteld op `null` wordt de standaardwaarde gebruikt. Met uitzondering van `temperature` die een standaardwaarde van `0.0`heeft, 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) Geef de antwoordindeling op die u wilt volgen in het chatmodel. Vereist Databricks Runtime 15.4 LTS of hoger. Alleen beschikbaar voor het uitvoeren van query's op chatondersteunende modellen. Er worden twee stijlen van antwoordindeling ondersteund. Een JSON-tekenreeks in DDL-stijl Een JSON-tekenreeks. Er worden drie typen JSON-tekenreeksen van de antwoordindeling ondersteund: `text` `json_object` `json_schema` Zie Uitvoerschema afdwingen met gestructureerde uitvoer voor voorbeelden.	Als `failOnError => false` en u `responseFormat`hebt 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 Uitvoerschema afdwingen met gestructureerde uitvoer voor voorbeelden.

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

Voorbeelden voor geavanceerde scenario's

De volgende secties bevatten voorbeelden voor geavanceerde gebruiksvoorbeelden, zoals foutafhandeling of het opnemen ai_query in een door de gebruiker gedefinieerde functie.

de prompt- en informatiekolom 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 eenvoudigere downstreamverwerking met behulp van responseFormat. Zie gestructureerde uitvoer in Azure Databricks.

In het volgende voorbeeld wordt een JSON-tekenreeksschema van de DDL-stijl afgedwongen:

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;

Als alternatief kunt u gebruik maken van een JSON-schema voor responseformats.

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;

Delen via

ai_query functie