ai_query 기능

적용 대상: Databricks SQL Databricks Runtime

Important

이 기능은 공개 미리 보기 상태입니다.

기존 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 런타임 버전을 사용하지 않습니다. 테이블 속성의 pipelines.channel을 'preview'으로 설정하여 ai_query()를 사용합니다. 샘플 쿼리에 대한 예제를 참조하세요.
• 모델이 로드된 엔드포인트를 제공하는 기존 모델입니다. 엔드포인트를 제공하는 사용자 지정 모델 만들기를 참조하세요.
• 작업 영역은 지원되는 모델 서비스 지역에 있어야 합니다.
• 기본 모델 API 쿼리는 기본적으로 사용하도록 설정됩니다. 사용자 지정 모델 또는 외부 모델을 제공하는 엔드포인트를 쿼리하려면 다음을 수행합니다.
  • Databricks Preview UI에서 사용자 지정 모델 및 외부 모델에 대한 AI_Query 사용하도록 설정합니다.
  • ai_query을 사용하여 외부 모델을 쿼리하십시오. 을 참조하세요.
  • ai_query 사용하여 일괄 처리 LLM 유추 수행 참조

참고 항목

• Databricks Runtime 14.2 이상에서 이 함수는 Databricks 워크플로에서 태스크로 실행되는Notebooks를 포함하여 Databricks Notebooks에서 지원됩니다.
• Databricks Runtime 14.1 이하에서 이 함수는 Databricks Notebooks에서 지원되지 않습니다.

구문

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

ai_query(endpoint, request)

모델 스키마을 사용하는 엔드포인트에 사용자 지정 모델을 쿼리하려면 다음을 수행하십시오.

ai_query(endpoint, request)

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

ai_query(endpoint, request, returnType, failOnError)

인수

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

반품

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

• 이 경우 failOnError => true함수는 엔드포인트에서 구문 분석된 응답인 기존 동작과 동일한 결과를 반환합니다. 구문 분석된 응답의 데이터 형식은 모델 형식, 모델 스키마 엔드포인트 또는 returnType 함수의 ai_query 매개 변수에서 유추됩니다.
• 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()사용하여 모델 및 유추 열에 대한 프롬프트를 연결하는 방법도 보여 줍니다. 연결을 수행하는 방법에는 여러 가지가 있습니다(예: 사용 ||, 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;