ai_query 기능
적용 대상:
Databricks SQL Databricks Runtime
중요합니다
이 기능은 공개 미리 보기 상태입니다.
기존 Azure Databricks 모델 서비스 엔드포인트를 호출하고 구문 분석하고 응답을 반환합니다.
프로덕션 워크플로에서 ai_query 사용하려면 AI Functions사용하여 일괄 처리 LLM 유추 수행을 참조하세요.
요구 사항
참고
- Databricks Runtime 14.2 이상에서는 이 함수가 Databricks 노트북에서 지원되며, Databricks 워크플로에서 태스크로 실행되는 노트북도 포함됩니다.
- Databricks Runtime 14.1 이하에서 이 함수는 Databricks Notebooks에서 지원되지 않습니다.
이 기능은 Azure Databricks SQL 클래식에서는 사용할 수 없습니다.
Pro SQL Warehouse에서 이 기능을 사용하려면 Azure Private Link를 사용하도록 설정해야 합니다.
Databricks Runtime 15.3 이상을 사용하는 것이 좋습니다. Databricks Runtime 15.2 이하를 사용하면 성능 속도가 느려질 수 있습니다.
작업 영역은 지원되는 모델 서비스 지역에 있어야 합니다.
모델을 로드한 상태로 서비스하는 기존의 엔드포인트입니다. Databricks 호스티드 파운데이션 모델을 사용하는 경우 엔드포인트가 만들어집니다. 그렇지 않으면 엔드포인트 서비스하는 사용자 지정 모델 만들기 또는 엔드포인트제공하는 기본 모델 만들기를 참조하세요.
기본 모델 API 쿼리는 기본적으로 사용하도록 설정됩니다. 사용자 지정 모델 또는 외부 모델을(를) 제공하는 엔드포인트를 쿼리하려면:
- Databricks Preview UI에서 사용자 지정 모델 및 외부 모델에 대한 AI_Query 사용하도록 설정합니다.
현재DLT 웨어하우스 채널은 지원하는
ai_query()최신 Databricks 런타임 버전을 사용하지 않습니다. 테이블 속성의pipelines.channel을'preview'으로 설정하여ai_query()를 사용합니다.> 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;
구문
외부 모델 또는 사용자 지정 기본 모델포함하여 기본 모델을 제공하는 엔드포인트를 쿼리하려면 다음을 수행합니다.
ai_query(endpoint, request)
모델 스키마을 사용하는 엔드포인트에 사용자 지정 모델을 쿼리하려면 다음을 수행하십시오.
ai_query(endpoint, request)
모델 스키마 없이 엔드포인트를 제공하는 사용자 지정 모델을 쿼리하려면 다음을 수행합니다.
ai_query(endpoint, request, returnType, failOnError)
인수 및 반환
| 논쟁 | 설명 | 반품 |
|---|---|---|
endpoint |
STRING 리터럴, Databricks Foundation 모델 호출을 위한 엔드포인트 이름, 외부 모델 제공 엔드포인트, 또는 동일한 작업 영역 내 사용자 지정 모델 호출을 위한 엔드포인트입니다. 정의자는 엔드포인트에 대한 CAN QUERY 권한이 있어야 합니다. |
|
request |
엔드포인트를 호출하기 위해 사용되는 요청의 식입니다.
|
|
returnType |
엔드포인트에서 예상되는 값 returnType의 식. 이는 STRING 식 또는 schema_of_json 함수호출을 모두 허용하는 from_json 함수스키마 매개 변수와 비슷합니다.
|
|
failOnError |
(선택 사항) true로 기본값이 되는 부울 리터럴입니다. 이 플래그는 응답에 ai_query 오류 상태를 포함할지 여부를 나타냅니다. |
오류를 처리하는 방법은 failOnError를 사용하여 예제를 참조하세요. |
modelParameters |
(선택 사항) 기본 모델 또는 외부 모델을 제공하기 위한 채팅, 완성 및 포함 모델 매개 변수가 포함된 구조체 필드입니다. 이러한 모델 매개 변수는 데이터가 종속되지 않고 상수 매개 변수여야 합니다. 이러한 모델 매개 변수를 지정하지 않거나 null 설정하면 기본값이 사용됩니다.
temperature을(를) 제외하고 기본값이 0.0인 이러한 모델 매개변수의 기본값은 Foundation 모델 REST API 참조에 나열된 값과 동일합니다.예시로는 모델 매개변수를 전달하여 모델을 구성하는 방법을에서 참조하세요. |
|
responseFormat |
(선택 사항) 모델이 따를 응답 형식을 지정하는 JSON 문자열 필드입니다. 다음과 같은 세 가지 문자열 형식의 응답 형식이 지원됩니다.
|
예를 보려면 출력 스키마 적용을 위해 구조화된 출력을 사용한을 참조하세요. |
프롬프트 및 유추 열 연결
프롬프트 및 유추 열을 연결하는 여러 가지 방법이 있습니다(예: ||, CONCAT()또는 format_string()사용).
SELECT
CONCAT('${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};
또는 다음과 같습니다.
SELECT
'${prompt}' || ${input_column_name} AS concatenated_prompt
FROM ${input_table_name};
또는 format_string()사용:
SELECT
format_string('%s%s', '${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};
모델 매개 변수를 전달하여 모델 구성
최대 토큰 및 온도와 같은 특정 매개 변수를 전달하여 모델 동작을 사용자 지정합니다. 다음은 그 예입니다.
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;
failOnError 사용하여 오류 처리
ai_query에 대해 failOnError 인수를 사용하여 오류를 처리합니다. 다음 예제에서는 한 행에 오류가 있는 경우 전체 쿼리 실행이 중지되지 않도록 하는 방법을 보여줍니다.
인수를 참조하고 이 인수를 설정하는 방법에 따라 예상되는 동작에 대한 반환합니다.
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;
구조적 출력을 사용하여 출력 스키마 적용
출력이 더 쉬운 다운스트림 처리를 위해 특정 스키마를 준수하는지 확인합니다. 예를 들어 JSON 스키마 응답 형식을 적용할 수 있습니다.
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;
또는 DDL 스타일 JSON 스키마를 사용합니다.
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;
예상 출력은 다음과 같습니다.
{ "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 사용
UDF에서 ai_query 호출을 래핑하여 다양한 워크플로에서 함수를 쉽게 사용하고 공유할 수 있습니다.
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;
예제: 기본 모델 쿼리
엔드포인트를 제공하는 외부 모델을 쿼리하려면 다음을 수행합니다.
> 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-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
선택적으로, ai_query() 호출을 UDF로 래핑하여 함수 호출을 다음과 같이 수행할 수도 있습니다.
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;
예: 일괄 처리 유추 사용 사례
다음은 failOnError 및 modelParameters와 max_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}
)
예: 기존 ML 모델 쿼리
엔드포인트를 제공하는 사용자 지정 모델 또는 기존 ML 모델을 쿼리하려면 다음을 수행합니다.
> 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."]}