이 글에서는 Unity Gateway가 제공하는 비전 작업에 최적화된 기초 모델에 대한 쿼리 요청을 작성하는 방법을 배웁니다.
Tip
지니 코드 (에이전트 모드)는 이 작업을 수행할 수 있습니다. 다음 예제 프롬프트를 사용해 보세요.
Query the databricks-claude-sonnet-4-5 model using the OpenAI client, sending a base64-encoded image from a URL alongside a text question, and print the response.
모델 제공은 다양한 기본 모델을 사용하여 이미지를 이해하고 분석하는 통합 API를 제공하여 강력한 멀티모달 기능을 잠금 해제합니다. 이 기능은 기본 모델 API의 일부로 Databricks 호스팅 모델을 선택하고 외부 모델을 제공하는 엔드포인트를 통해 사용할 수 있습니다.
요구 사항
- 요구 사항을 참조하세요.
- 선택한 쿼리 클라이언트 옵션에 따라 클러스터에 적절한 패키지를 설치합니다.
쿼리 예제
메모
다음 예시들은 Unity 게이트웨이와 모델 서비스를 기반으로 합니다. 모델 서비스 대신 엔드포인트를 제공하는 모델을 사용하는 경우 모델 서비스 이름을 엔드포인트 이름으로 바꿉니다. 사용 가능한 파운데이션 모델과 해당 모델 서비스 및 엔드포인트 이름 목록은 Foundation Model API에서 사용할 수 있는 Databricks 호스팅 파운데이션 모델을 참조하세요.
OpenAI 클라이언트
OpenAI 클라이언트를 사용하려면 모델 서비스 이름을 입력으로 model 지정합니다.
from openai import OpenAI
import base64
import requests
# Get the workspace API URL and token from the notebook context
API_ROOT = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiUrl().get()
API_TOKEN = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiToken().get()
client = OpenAI(
api_key=API_TOKEN,
base_url=f"{API_ROOT}/ai-gateway/mlflow/v1",
)
# Download and encode image
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
resp = requests.get(image_url)
resp.raise_for_status()
image_data = base64.b64encode(resp.content).decode("utf-8")
# OpenAI request
completion = client.chat.completions.create(
model="system.ai.claude-sonnet-4-5",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "what's in this image?"},
{
"type": "image_url",
"image_url": {"url": f"data:image/jpeg;base64,{image_data}"},
},
],
}
],
)
print(completion.choices[0].message.content)
채팅 완료 API는 여러 이미지 입력을 지원하므로 모델은 각 이미지를 분석하고 모든 입력의 정보를 합성하여 프롬프트에 대한 응답을 생성할 수 있습니다.
from openai import OpenAI
import base64
import requests
# Get the workspace API URL and token from the notebook context
API_ROOT = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiUrl().get()
API_TOKEN = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiToken().get()
client = OpenAI(
api_key=API_TOKEN,
base_url=f"{API_ROOT}/ai-gateway/mlflow/v1",
)
# Download and encode multiple images
image1_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
resp1 = requests.get(image1_url)
resp1.raise_for_status()
image1_data = base64.b64encode(resp1.content).decode("utf-8")
image2_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
resp2 = requests.get(image2_url)
resp2.raise_for_status()
image2_data = base64.b64encode(resp2.content).decode("utf-8")
# OpenAI request
completion = client.chat.completions.create(
model="system.ai.claude-sonnet-4-5",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "What are in these images? Is there any difference between them?"},
{
"type": "image_url",
"image_url": {"url": f"data:image/jpeg;base64,{image1_data}"},
},
{
"type": "image_url",
"image_url": {"url": f"data:image/jpeg;base64,{image2_data}"},
},
],
}
],
)
print(completion.choices[0].message.content)
SQL
다음은 AI 함수 ai_query()를 사용하는 다중 모드 입력에 대해 Databricks Foundation Model API에서 지원하는 기본 모델을 쿼리합니다.
SELECT *, ai_query(
'system.ai.llama-4-maverick',
'what is this image about?', files => content)
as output FROM READ_FILES("/Volumes/main/multimodal/unstructured/image.jpeg");
지원되는 모델
Foundation 모델 유형에서 지원되는 비전 모델을 참조하세요.
입력 이미지 요구 사항
| 모델(들) | 지원되는 형식 | 요청당 여러 이미지 | 이미지 크기 제한 사항 | 이미지 크기 조정 권장 사항 | 이미지 품질 고려 사항 |
|---|---|---|---|---|---|
databricks-gpt-5 |
|
요청당 최대 500개의 개별 이미지 입력 | 파일 크기 제한: 요청당 최대 10MB의 총 페이로드 크기 | N/A |
|
databricks-gpt-5-mini |
|
요청당 최대 500개의 개별 이미지 입력 | 파일 크기 제한: 요청당 최대 10MB의 총 페이로드 크기 | N/A |
|
databricks-gpt-5-nano |
|
요청당 최대 500개의 개별 이미지 입력 | 파일 크기 제한: 요청당 최대 10MB의 총 페이로드 크기 | N/A |
|
databricks-gemma-3-12b |
|
API 요청에 대해 최대 5개의 이미지
|
파일 크기 제한: API 요청당 모든 이미지에서 총 10MB | N/A | N/A |
databricks-llama-4-maverick |
|
API 요청에 대해 최대 5개의 이미지
|
파일 크기 제한: API 요청당 모든 이미지에서 총 10MB | N/A | N/A |
|
|
|
|
최적의 성능을 위해 너무 큰 경우 업로드하기 전에 이미지 크기를 조정합니다.
|
|
이미지 토큰 변환
이 섹션은 Foundation Model API에만 적용됩니다. 외부 모델의 경우 공급자의 설명서를 참조하세요.
기본 모델에 대한 요청의 각 이미지는 토큰 사용량에 추가됩니다. 사용 중인 토큰 사용량 및 모델을 기반으로 이미지 가격 책정을 예측하려면 가격 계산기를 참조하세요.
이미지 이해의 제한 사항
이 섹션은 Foundation Model API에만 적용됩니다. 외부 모델의 경우 공급자의 설명서를 참조하세요.
다음은 지원되는 Databricks 호스팅 기반 모델에 대한 이미지 이해 제한 사항입니다.
| Model | 제한점 |
|---|---|
지원되는 클로드 모델은 다음과 같습니다.
|
Databricks의 Claude 모델에 대한 제한은 다음과 같습니다.
|