ai_query 기능

적용 대상: Databricks SQL Databricks Runtime

기존 Azure Databricks 모델 서비스 엔드포인트를 호출하고 구문 분석하고 응답을 반환합니다.

다양한 사용 사례에 사용하는 ai_query 방법은 다음 가이드를 참조하세요.

• ai_query을 사용하여 LLM 일괄 추론 수행
• ai_query 사용하여 외부 모델 쿼리
• 제공된 모델을 ai_query로 쿼리하십시오.

요구 사항

• 이 기능은 Azure Databricks SQL 클래식에서는 사용할 수 없습니다.
• Pro SQL Warehouse에서 이 기능을 사용하려면 Azure Private Link를 사용하도록 설정해야 합니다.
• Databricks Runtime 15.3 이상을 사용하는 것이 좋습니다. Databricks Runtime 15.2 이하를 사용하면 성능 속도가 느려질 수 있습니다.
• 현재DLT 웨어하우스 채널은 지원하는 ai_query()최신 Databricks 런타임 버전을 사용하지 않습니다. Set pipelines.channel이 table 속성에 'preview'로 사용할 ai_query(). 샘플 쿼리에 대한 예제를 참조하세요.
• 모델이 로드된 엔드포인트를 제공하는 기존 모델입니다. 엔드포인트를 제공하는 사용자 지정 모델 만들기를 참조하세요.
• 작업 영역은 지원되는 모델 서비스 지역에 있어야 합니다.
• 기본 모델 API 쿼리는 기본적으로 사용하도록 설정됩니다. 사용자 지정 모델 또는 외부 모델을 제공하는 엔드포인트를 쿼리하려면 다음을 수행합니다.
  • Databricks Preview UI에서 사용자 지정 모델 및 외부 모델에 대한 AI_Query 사용하도록 설정합니다.
  • ai_query을 사용하여 외부 모델을 쿼리하십시오. 을 참조하세요.
  • ai_query 사용하여 일괄 처리 LLM 유추 수행 참조

구문

외부 모델 또는 기본 모델을 제공하는 엔드포인트를 쿼리하려면 다음을 수행합니다.

ai_query(endpoint, request)

모델을 사용하여 엔드포인트를 제공하는 사용자 지정 모델을 쿼리하려면 다음을 schema.

ai_query(endpoint, request)

모델 schema없이 엔드포인트를 제공하는 사용자 지정 모델을 쿼리하려면 다음을 수행합니다.

ai_query(endpoint, request, returnType, failOnError)

인수

• endpoint: 호출을 위한 Databricks Foundation 모델 서비스 엔드포인트, 외부 모델 서비스 엔드포인트, 또는 동일한 작업 영역 내 사용자 지정 모델 엔드포인트의 이름인 STRING 리터럴입니다. 정의자는 엔드포인트에 대한 CAN QUERY 권한이 있어야 합니다.
• request: 엔드포인트를 호출하는 데 사용되는 요청인 식입니다.
  • 엔드포인트가 외부 모델 서빙 엔드포인트이거나 Databricks Foundation Model APIs 엔드포인트인 경우, 요청은 반드시 STRING이어야 합니다.
  • 엔드포인트가 사용자 지정 모델을 제공하는 엔드포인트인 경우, 요청은 단일 column 또는 구조체 식일 수 있습니다. 구조체 필드 이름은 엔드포인트에서 예상하는 입력 기능 이름과 일치해야 합니다.
• returnType: 식, 엔드포인트에서 예상되는 returnType. 이는 from_json 함수schema 매개 변수와 유사합니다. 이 매개 변수는 STRING 식 또는 schema_of_json 함수호출을 모두 허용합니다.
  • Databricks Runtime 14.2 이상에서 이 식이 제공되지 않으면, 시스템은 사용자 지정 모델 서빙 엔드포인트 ai_query()의 모델 schema로부터 자동으로 반환 유형을 유추합니다.
  • Databricks Runtime 14.1 이하에서 이 식은 엔드포인트를 제공하는 사용자 지정 모델을 쿼리하는 데 필요합니다.
• failOnError: (선택 사항) true로 기본값이 되는 부울 리터럴입니다. 이 플래그는 응답에 ai_query 오류 상태를 포함할지 여부를 나타냅니다.
• modelParameters(선택 사항): 기본 모델 또는 외부 모델을 제공하기 위한 채팅, 완성 및 포함 모델 parameters 포함하는 구조체 필드입니다. 이러한 모델 parameters 데이터가 종속되지 않고 일정한 parameters 되어야 합니다. 이 모델 parameters가 지정되지 않았거나 set에서 null로 지정되는 경우 기본값이 사용됩니다. 기본값이 0.0인 temperature을 제외하고, 이러한 모델 parameters의 기본 values는 Foundation 모델 REST API 참조에 나열된 것과 동일합니다.
• responseFormat(선택 사항): 모델이 따라야 할 응답 형식을 지정하는 JSON 문자열 필드입니다. 다음과 같은 세 가지 문자열 형식의 응답 형식이 지원됩니다.
  • text
  • json_object
  • json_schema

반품

엔드포인트에서 구문 분석된 응답입니다.

• 이 경우 failOnError => true함수는 엔드포인트에서 구문 분석된 응답인 기존 동작과 동일한 결과를 반환합니다. 구문 분석된 응답의 데이터 유형은 모델 유형, 모델 schema 엔드포인트 또는 ai_query 함수의 returnType 매개 변수에서 유추됩니다.
• failOnError => false경우 함수는 구문 분석된 응답과 오류 상태 문자열을 STRUCT 개체로 반환합니다.
  • 행의 추론에 성공하면 errorStatus 필드가 null입니다.
  • 모델 엔드포인트 오류로 인해 행 추론에 실패한 경우 response 필드는 null.
  • 다른 오류로 인해 행의 유추가 실패하면 전체 쿼리가 실패합니다.
• responseFormat지정된 JSON 문자열 형식에 따라 다음 응답이 반환됩니다.
  • responseFormat => '{“type”, “text”}'경우 응답은 “Here is the response”같은 문자열입니다.
  • responseFormat => '{“type”, “json_object”}'경우 응답은 {“key”: “value”}같은 키-값 쌍 JSON 문자열입니다.
  • responseFormat => '{“type”, “json_schema”...}'경우 응답은 JSON 문자열입니다. 예제참조하세요.
• failOnError => false 및 responseFormat을 지정한 경우 함수는 구문 분석된 응답과 오류 상태 문자열을 STRUCT 개체로 반환합니다.

예제

다음 예제에서는 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
                          }
                      }'
  )

다음은 지정된 json_schema 응답 형식에 대한 예제 출력입니다.

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

다음은 and with 및 failOnErrormodelParametersmax_tokens.를 사용하는 temperature 일괄 처리 유추 예제입니다. 이 예제에서는 concat()사용하여 모델에 대한 프롬프트와 유추 column 연결하는 방법도 보여 줍니다. 연결을 수행하는 방법에는 여러 가지가 있습니다(예: 사용 ||, concat()또는 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}
)

엔드포인트를 제공하는 외부 모델을 쿼리하려면 다음을 수행합니다.

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

Databricks Foundation 모델 API에서 지원하는 기본 모델을 쿼리하려면 다음을 수행합니다.

> 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

필요에 따라 다음과 같이 함수 호출을 위해 UDF에서 호출을 래핑할 ai_query() 수도 있습니다.

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

엔드포인트를 제공하는 사용자 지정 모델을 쿼리하려면 다음을 수행합니다.

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

DLT 채널을 미리 보기로 설정하는 예제 쿼리:

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