적용 대상:
Databricks SQL Databricks Runtime
Important
이 기능은 공개 미리 보기 및 HIPAA 규격에 있습니다.
미리 보기 중:
- 기본 언어 모델은 여러 언어를 처리할 수 있지만 이 AI 함수는 영어로 조정됩니다.
- AI Functions의 지역 가용성에 대한 지역별로 제한된 기능을 참조하세요.
기존 Azure Databricks 모델 서비스 엔드포인트를 호출하고 구문 분석하고 응답을 반환합니다.
ai_query 는 실시간 유추 또는 일괄 처리 유추 워크로드에 대한 기존 엔드포인트를 쿼리할 수 있는 범용 AI 함수 입니다.
- 지원되는 모델 및 필수 엔드포인트 구성은 범용 함수
ai_query를 참조하세요. - 엔드포인트를 제공하는 ML 모델에 배포된 AI 에이전트를 쿼리하는 데 사용할
ai_query수도 있습니다. 배포된 Mosaic AI 에이전트 쿼리를 참조하세요. - 프로덕션 워크플로에서 사용
ai_query하려면 일괄 처리 유추 파이프라인 배포를 참조하세요.
요구 사항
이 기능은 Azure Databricks SQL 클래식에서는 사용할 수 없습니다.
Pro SQL Warehouse에서 이 기능을 사용하려면 Azure Private Link를 사용하도록 설정해야 합니다.
Databricks Runtime 15.4 LTS 이상을 사용하는 것이 좋습니다. Databricks Runtime 15.3 이하를 사용하면 성능 속도가 느려질 수 있습니다.
작업 영역은 지원되는 모델 서비스 지역에 있어야 합니다.
모델을 로드한 상태로 서비스하는 기존의 엔드포인트입니다. Databricks 호스티드 파운데이션 모델을 사용하는 경우 엔드포인트가 만들어집니다. 그렇지 않으면 엔드포인트 서비스하는 사용자 지정 모델 만들기 또는 엔드포인트제공하는 기본 모델 만들기를 참조하세요.
기본 모델 API 쿼리는 기본적으로 사용하도록 설정됩니다. 사용자 지정 모델 또는 외부 모델을(를) 제공하는 엔드포인트를 쿼리하려면:
- Databricks Preview UI에서 사용자 지정 모델 및 외부 모델에 대한 AI_Query 사용하도록 설정합니다.
현재Lakeflow Spark 선언적 파이프라인 웨어하우스 채널은 지원하는
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-meta-llama-3-3-70b-instruct", text) as response FROM messages LIMIT 10;
Syntax
기본 모델을 제공하는 엔드포인트를 쿼리하려면 다음을 수행합니다.
ai_query(endpoint, request)
모델 스키마을 사용하는 엔드포인트에 사용자 지정 모델을 쿼리하려면 다음을 수행하십시오.
ai_query(endpoint, request)
모델 스키마 없이 엔드포인트를 제공하는 사용자 지정 모델을 쿼리하려면 다음을 수행합니다.
ai_query(endpoint, request, returnType, failOnError)
인수 및 반환
| Argument | Description | Returns |
|---|---|---|
endpoint |
Databricks Foundation Model 서비스 엔드포인트, 외부 모델 서비스 엔드포인트 또는 같은 작업 공간에서 호출을 위한 사용자 정의 모델 엔드포인트의 이름을 STRING 리터럴로 제공합니다. 정의자는 엔드포인트에 대한 CAN QUERY 권한이 있어야 합니다. |
|
request |
엔드포인트를 식으로 호출하는 데 사용되는 요청입니다.
|
|
returnType |
(Databricks Runtime 15.2 이상에 대한 선택 사항) 엔드포인트에서 식으로 예상되는 returnType 값입니다. 이는 from_json 식 또는 호출을 모두 허용하는 STRING스키마 매개 변수와 비슷합니다.
매개 변수를 responseFormat 사용하여 채팅 기반 모델에 대한 응답 형식을 지정합니다. |
|
failOnError |
(선택 사항) 기본값이 true인 부울 리터럴입니다. Databricks Runtime 15.3 이상이 필요합니다. 이 플래그는 응답에 ai_query 오류 상태를 포함할지 여부를 나타냅니다.오류를 처리하는 방법은 failOnError를 사용하여 예제를 참조하세요. |
다음은 failOnError 시나리오를 기준으로 한 반환 동작을 설명합니다.
|
modelParameters |
(선택 사항) 기본 모델 또는 외부 모델을 제공하기 위한 채팅, 완성 및 포함 모델 매개 변수가 포함된 구조체 필드입니다. 이러한 모델 매개 변수는 데이터가 종속되지 않고 상수 매개 변수여야 합니다.
예시로는 모델 매개변수를 전달하여 모델을 구성하는 방법을에서 참조하세요. |
|
responseFormat |
(선택 사항) 채팅 기반 모델을 따를 응답 형식을 지정합니다.
예제는 구조적 출력을 사용하여 출력 스키마 적용 을 참조하세요. |
다음에서는 failOnError가 지정되고 또한 responseFormat가 설정될 때 무엇이 발생하는지 설명합니다.
|
files |
(선택 사항) 를 사용하여 files=>content멀티모달 입력 요청에 사용할 파일 및 콘텐츠를 지정합니다.
files 는 모델에서 다중 모달 입력에 대해 예상하는 매개 변수 이름이며 content 쿼리에 사용할 이미지 파일의 이진 콘텐츠가 포함된 DataFrame의 열을 참조합니다.
|
예제: 기본 모델 쿼리
엔드포인트를 제공하는 외부 모델을 쿼리하려면 다음을 수행합니다.
> 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;
다중 모드 입력
ai_query 기본적으로 다중 모달 이미지 입력을 지원합니다. 지원되는 Databricks 호스팅 비전 모델에 대한 Foundation 모델 유형을 참조하세요.
지원되는 입력 형식은 다음과 같습니다.
JPEGPNG
다음 예제에서는 Multimodal 입력에 대해 Databricks Foundation 모델 API에서 지원하는 기초 모델을 쿼리하는 방법을 보여 줍니다. 이 예제에서는 매개 변수를 files => content 사용하여 이미지 파일 데이터를 에 전달합니다. ai_query
-
files: 모델에서 다중 모달 입력에 대해 예상하는 매개 변수 이름입니다. -
content:READ_FILES이 반환한 DataFrame에서, 이미지 파일의 이진 콘텐츠를 포함한 열입니다.
> SELECT *, ai_query(
'databricks-llama-4-maverick',
'what is this image about?', files => content)
as output FROM READ_FILES("/Volumes/main/multimodal/unstructured/image.jpeg");
Databricks Foundation 모델 API에서 지원하는 기본 모델을 쿼리하여 다중 모드 입력을 쿼리하고 구조적 출력을 지정하려면 다음을 수행합니다.
> SELECT *, ai_query(
'databricks-llama-4-maverick', 'What is interesting or important about this image?',
responseFormat => ‘{
"type": "json_schema",
"json_schema": {
"name": "output",
"schema": {
"type": "object",
"properties": {
"summary": {"type": "string"},
"num_people": {"type": "integer"},
"num_animals": {"type": "integer"},
"interesting_fact": {"type": "string"},
"possible_context": {"type": "string"}
}
},
"strict": true
}
}’,
files => content
)
as output FROM READ_FILES("/Volumes/main/user/volume1/image.jpeg");
예: 기존 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
고급 시나리오의 예
다음 섹션에서는 오류 처리 또는 사용자 정의 함수에 통합 ai_query 하는 방법과 같은 고급 사용 사례에 대한 예제를 제공합니다.
메시지 배열 전달
다음 예제에서는 를 사용하여 ai_query모델 또는 에이전트 애플리케이션에 메시지 배열을 전달하는 방법을 보여 줍니다.
> 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."]}
프롬프트 및 유추 열 연결
프롬프트 및 유추 열을 연결하는 여러 가지 방법이 있습니다(예: ||, CONCAT()또는 format_string()사용).
SELECT
CONCAT('${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};
Alternatively:
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 사용하여 오류 처리
failOnError에 대해 ai_query 인수를 사용하여 오류를 처리합니다. 다음 예제에서는 한 행에 오류가 있는 경우 전체 쿼리 실행이 중지되지 않도록 하는 방법을 보여줍니다.
인수를 참조하고 이 인수를 설정하는 방법에 따라 예상되는 동작에 대한 반환합니다.
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;
구조적 출력을 통해 출력 스키마를 강화하다
를 사용하여 responseFormat다운스트림 처리를 더 쉽게 수행하려면 출력이 특정 스키마를 준수하는지 확인합니다. Azure Databricks에서 구조적 출력 을(를) 참조하세요.
다음 예제에서는 DDL 스타일 JSON 문자열 스키마를 적용합니다.
SELECT ai_query(
"databricks-gpt-oss-20b",
"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;
또는 JSON 스키마 응답 형식을 사용합니다.
SELECT ai_query(
"databricks-gpt-oss-20b",
"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;