Compartilhar via

Função ai_query

  • Artigo

Aplica-se a:marca de seleção positiva SQL do Databricks marca de seleção positiva Runtime do Databricks

Importante

Esse recurso está em uma versão prévia.

Invoca um ponto de extremidade existente do Azure Databricks Model Serving e analisa e retorna sua resposta.

Consulte os seguintes guias para saber como usar ai_query para diferentes casos de uso:

Requisitos

Observação

  • No Databricks Runtime 14.2 e versões posteriores, esta função tem suporte em notebooks do Databricks, incluindo notebooks executados como uma tarefa em um fluxo de trabalho do Databricks.
  • No Databricks Runtime 14.1 e versões anteriores, esta função não tem suporte nos notebooks do Databricks.

Sintaxe

Para consultar um ponto de extremidade que atenda a um modelo externo ou um modelo do Foundation:

ai_query(endpoint, request)

Para consultar um modelo personalizado que serve ao ponto de extremidade com um esquema de modelo:

ai_query(endpoint, request)

Para consultar um modelo personalizado que serve ao ponto de extremidade sem um esquema de modelo:

ai_query(endpoint, request, returnType, failOnError)

Argumentos

  • endpoint: um literal STRING, o nome de um ponto de extremidade do serviço do Modelo de Base do Databricks, um ponto de extremidade do serviço de modelo externo ou um ponto de extremidade de modelo personalizado no mesmo workspace para invocações. O definidor precisa ter a permissão CAN QUERY no ponto de extremidade.
  • request: uma expressão, a solicitação usada para invocar o ponto de extremidade.
    • Se o ponto de extremidade for um ponto de extremidade do Serviço de Modelo externo ou um ponto de extremidade das APIs do Modelo de Base do Databricks, a solicitação deverá ser um STRING.
    • Se o ponto de extremidade for um modelo personalizado que serve o ponto de extremidade, a solicitação poderá ser uma única coluna ou uma expressão struct. Os nomes dos campos struct devem corresponder aos nomes do recurso de entrada esperados pelo ponto de extremidade.
  • returnType: uma expressão, o returnType esperado do ponto de extremidade. Isso é semelhante ao parâmetro de esquema na função from_json, que aceita uma expressão STRING ou a invocação da função schema_of_json.
    • No Databricks Runtime 14.2 e versões posteriores, se essa expressão não for fornecida, ai_query() inferirá automaticamente o tipo de retorno com base no esquema do modelo do ponto de extremidade que serve ao modelo personalizado.
    • No Databricks Runtime 14.1 e anteriores, essa expressão é necessária para consultar um modelo personalizado que serve ao ponto de extremidade.
  • failOnError: (opcional) Um literal booleano padronizado como true. Esse sinalizador indica se o status do erro deve ser incluído na ai_query resposta.
  • modelParameters (opcional): um campo struct que contém parâmetros de modelo de chat, conclusão e incorporação para atender a modelos de fundação ou modelos externos. Esses parâmetros de modelo devem ser parâmetros constantes e não dependentes de dados. Quando esses parâmetros de modelo não são especificados ou configurados para null o valor padrão, é usado. Com exceção de temperature que tem um valor padrão de 0.0, os valores padrão para esses parâmetros de modelo são os mesmos listados na referência da API REST do modelo do Foundation.
  • responseFormat (opcional): um campo de cadeia de caracteres JSON que especifica o formato de resposta que você deseja que o modelo siga. Há suporte para três tipos de cadeia de caracteres de formato de resposta:
    • text
    • json_object
    • json_schema

Devoluções

A resposta analisada do ponto de extremidade.

  • Se failOnError => true, a função retornará o mesmo resultado que o comportamento existente, que é a resposta analisada do ponto de extremidade. O tipo de dados da resposta analisada é inferido do tipo de modelo, do ponto de extremidade do esquema do modelo ou do returnTypeai_query parâmetro na função.
  • Se failOnError => false, a função retornará a resposta analisada e a cadeia de caracteres de status de erro como um objeto STRUCT.
    • Se a inferência da linha tiver sido bem-sucedida, o campo errorStatus será null.
    • Se a inferência da linha falhar devido a erros de ponto de extremidade do modelo, o campo response será null.
    • Se a inferência da linha falhar devido a outros erros, toda a consulta falhará.
  • Dependendo do tipo de cadeia de caracteres JSON especificado em responseFormat, a seguinte resposta é retornada:
    • Para responseFormat => '{“type”, “text”}', a resposta é uma cadeia de caracteres como, “Here is the response”.
    • Para responseFormat => '{“type”, “json_object”}', a resposta é uma cadeia de caracteres JSON de par chave-valor, como {“key”: “value”}.
    • Para responseFormat => '{“type”, “json_schema”...}', a resposta é uma cadeia de caracteres JSON. Veja os exemplos .
  • Se failOnError => false e você especificou responseFormat, a função retornará a resposta analisada e a cadeia de caracteres de status de erro como um objeto STRUCT.

Exemplos

O exemplo a seguir especifica um formato de resposta json_schema:


SELECT
  ai_query(
    "llama-3-1-70b",
    <request>,
    responseFormat =>'{
                        "type": "json_schema",
                        "json_schema":
                          {
                           "name": "research_paper_extraction",
                           "schema":
                             {
                              "type": "object",
                              "properties":
                               {
                                "title": { "type": "string" }
                               }
                             },
                            "strict": true
                          }
                      }'
  )

Veja a seguir um exemplo de saída para o formato de resposta json_schema especificado:

{"title": "<the title of the paper>"}

Veja a seguir um exemplo de inferência em lote usando o failOnError e modelParameters com max_tokens e temperature. Este exemplo também mostra como concatenar o prompt do modelo e a coluna de inferência usando concat(). Há várias maneiras de realizar a concatenação, como usar ||, concat(), ou 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}
)

Para consultar um ponto de extremidade que atende um modelo externo:

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

Para consultar um modelo de fundação compatível com as APIs de Modelo do Databricks Foundation:

> 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

Opcionalmente, você também pode encapsular uma chamada a ai_query() em um UDF para chamada de função da seguinte maneira:

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

Para consultar um ponto de extremidade do serviço de modelo personalizado:


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

Exemplo de consulta para configurar o canal DLT para visualização:

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