임베딩
핵심 요약 Apache Doris는 내장 SQL 함수인
EMBED()를 제공합니다. 이 함수는 텍스트(또는 이미지, 동영상, 오디오 파일)를 외부 임베딩 모델로 보내고ARRAY<FLOAT>를 반환하며, 반환값은 컬럼에 저장하거나 거리 함수에 바로 사용할 수 있습니다. 모델을 AIRESOURCE로 한 번 설정하면 값을 사용할 수 있는 곳 어디에서나EMBED('your text')를 사용할 수 있습니다. UDF나 클라이언트 측 연동 코드가 필요 없고, 별도의 서비스를 운영할 필요도 없습니다.
Apache Doris에서 EMBED 함수를 사용하는 이유는 무엇인가요?
Apache Doris의 EMBED() 함수는 일반적으로 애플리케이션 측에서 처리하는 임베딩 파이프라인을 단일 SQL 호출로 통합합니다. 따라서 별도의 ETL 서비스 없이 데이터베이스 안에서 벡터를 생성하고 저장하고 쿼리할 수 있습니다. 벡터 검색에는 벡터가 필요하고, 벡터는 임베딩 모델에서 생성됩니다. 일반적인 구성에서는 애플리케이션 서버가 데이터베이스에서 행을 가져와 OpenAI나 로컬 모델로 보내고, 반환된 벡터를 벡터 테이블에 기록합니다. 쿼리 시점에도 검색 문자열에 대해 같은 왕복 과정이 반복됩니다. 결국 HTTP API를 호출하고 결과를 어딘가에 저장하는 일만 하는 소규모 ETL 서비스를 유지 관리하게 됩니다.
이 과정에서 다음과 같은 문제가 자주 발생합니다.
- 파이프라인과 원본 테이블의 동기화가 어긋납니다. 새 행이 들어와도 다음 배치 실행 전까지는 임베딩이 없습니다.
- 기존 데이터의 임베딩을 채우는 백필 자체가 별도의 작업이 되며, 최초 데이터 수집보다 느리고 비용이 많이 드는 경우도 흔합니다.
- 논리적으로 하나인 단계를 두 팀이 나누어 담당합니다. 데이터 팀은 행을, 애플리케이션 팀은 벡터를 담당하지만, 그 사이의 공백은 누구도 책임지지 않습니다.
EMBED()는 이 전체 과정을 SQL 안으로 가져옵니다. 모델은 Apache Doris 리소스가 되고, 호출은 함수가 되며, 결과는 INSERT로 저장하거나 필요할 때 계산할 수 있는 컬럼이 됩니다.
Apache Doris EMBED 함수란 무엇인가요?
Apache Doris의 EMBED() 함수는 내장 AI 함수로, 텍스트나 멀티모달 파일 참조를 받아 외부 임베딩 제공자에 벡터를 요청하고 ARRAY<FLOAT>를 반환합니다. Apache Doris는 CREATE RESOURCE로 한 번 설정한 AI 리소스를 통해 제공자에 접근합니다. 같은 함수 호출을 데이터 적재 시점에 사용해 임베딩을 컬럼에 저장하거나, 쿼리 시점에 사용해 SQL 안에서 사용자의 검색 문자열을 즉시 임베딩할 수 있습니다.
주요 용어
- AI 리소스: 임베딩 제공자에 대한 연결에 이름을 부여한 것입니다.
EMBED()는openai,gemini,voyageai,jina,qwen,minimax전용 어댑터와 자체 모델 서버를 위한local옵션을 제공합니다. 엔드포인트, 모델 이름, API 키, 선택적 차원 수를 저장합니다. EMBED([resource_name], input): SQL 함수입니다. 인수가 하나이면 Apache Doris는 세션 기본값을 사용하고, 둘이면 첫 번째 인수로 리소스 이름을 명시합니다.default_ai_resource: 해당 세션의 나머지 작업에서 사용할 리소스를 지정하는 세션 변수입니다.- 멀티모달 입력: 파일을 설명하는 JSON 값입니다(URI, 콘텐츠 유형, 선택적 S3 자격 증명). Apache Doris는 S3 URL에 사전 서명을 적용하고, 이미지, 동영상, 오디오 임베딩을 지원하는 제공자에 전달합니다.
Apache Doris EMBED 함수는 어떻게 작동하나요?
Apache Doris의 EMBED() 함수는 AI 리소스 등록, FE에서 호출 계획 수립, BE에서 행을 배치로 묶기, 실패 시 재시도, 행마다 하나의 ARRAY<FLOAT> 반환이라는 다섯 단계로 작동합니다.
- 모델을 등록합니다.
CREATE RESOURCE는 제공자 유형, 엔드포인트, 모델 이름, 자격 증명을 저장합니다. Apache Doris는 제공자에 시험 호출을 보내 리소스를 검증합니다. 단,provider_type = "local"인 경우에는 이 검사를 건너뜁니다. - 호출 계획을 수립합니다. 플래너가
EMBED()를 만나면 작업을 BE로 보냅니다. 함수는 입력 컬럼을 행별로 처리하지만, 제공자를 행마다 호출하지는 않습니다. - BE에서 배치로 묶습니다. BE는 행을 배치로 모으며,
embed_max_batch_size(기본값: 입력 5개)와ai_context_window_size(기본값: 누적 텍스트 128 KB)로 배치 크기를 제한합니다. 각 배치는 하나의 HTTP 요청이 되어 왕복 호출과 분당 요청 제한을 관리할 수 있게 합니다. - 재시도하고 실패 시 오류를 반환합니다. 제공자 호출은 리소스의
ai.max_retries와ai.retry_delay_second설정을 따릅니다. API가 잘못된 개수의 벡터를 반환하면, Apache Doris는 행과 벡터가 잘못 연결되는 일을 막기 위해 쿼리를 실패 처리합니다. - 컬럼을 반환합니다. 각 행은 고유한
ARRAY<FLOAT>를 받습니다. 이를 저장하거나,cosine_distance에 전달하거나, 벡터 검색용 ANN 인덱스에 적재할 수 있습니다.
빠른 시작
CREATE RESOURCE "openai_embed" PROPERTIES (
"type" = "ai", "ai.provider_type" = "openai",
"ai.endpoint" = "https://api.openai.com/v1/embeddings",
"ai.model_name" = "text-embedding-3-small",
"ai.api_key" = "sk-xxx", "ai.dimensions" = "8"
);
SET default_ai_resource = "openai_embed";
CREATE TABLE notes (id INT, body STRING, vec ARRAY<FLOAT>)
DUPLICATE KEY(id) DISTRIBUTED BY HASH(id) BUCKETS 1;
INSERT INTO notes VALUES
(1, 'travel reimbursement policy', EMBED('travel reimbursement policy')),
(2, 'VPN setup guide', EMBED('VPN setup guide'));
SELECT id, body, cosine_distance(vec, EMBED('how do I expense a trip?')) AS d
FROM notes ORDER BY d ASC LIMIT 1;
예상 결과
+----+-----------------------------+--------+
| id | body | d |
+----+-----------------------------+--------+
| 1 | travel reimbursement policy | 0.4463 |
+----+-----------------------------+--------+
INSERT는 행마다 하나의 벡터를 미리 계산합니다. SELECT는 실행 시점에 쿼리 문자열을 한 번 임베딩한 다음, 코사인 거리에 따라 행의 순위를 매깁니다. API 호출은 총 두 번이며, 모두 SQL 내부에서 이루어집니다.
멀티모달 빠른 시작
멀티모달 임베딩에는 텍스트 문자열 대신 JSON 객체를 전달합니다. 객체에는 파일의 uri와 MIME 유형인 content_type이 포함되어야 합니다. URI는 HTTP 또는 HTTPS URL이나 S3 호환 URI일 수 있습니다. 설정한 제공자와 모델이 입력 미디어 유형을 지원하는지 확인하세요.
다음 예제는 S3 호환 객체 스토리지에 저장된 동영상을 임베딩합니다.
SELECT ARRAY_SIZE(
EMBED(
'multimodal_embed_resource',
CAST('{
"uri": "s3://example-bucket/videos/demo.mp4",
"content_type": "video/mp4",
"endpoint": "s3.us-east-1.amazonaws.com",
"region": "us-east-1",
"ak": "<access_key>",
"sk": "<secret_key>"
}' AS JSON)
)
) AS video_embedding_dimension;
결과 예시
+---------------------------+
| video_embedding_dimension |
+---------------------------+
| 2560 |
+---------------------------+
벡터 차원 수는 설정한 제공자와 모델에 따라 달라지므로 위 결과는 예시일 뿐입니다. HTTP 또는 HTTPS URL에는 uri와 content_type만 필요합니다. S3 호환 URI의 경우 Doris는 사전 서명된 URL을 생성하며, AK/SK 자격 증명 또는 role_arn과 external_id를 사용하는 IAM 역할 인증을 지원합니다.
Apache Doris EMBED 함수는 언제 사용하면 좋을까요?
Apache Doris의 EMBED() 함수는 이미 Apache Doris에 저장된 문서 집합을 대상으로 하는 RAG 및 시맨틱 검색, SQL 안에서 처리하는 백필, 벡터와 키워드 필터를 결합하는 하이브리드 파이프라인, 원본 파일이 S3에 있는 멀티모달 임베딩에 적합합니다. 반면 주요 실행 경로에서 수백만 행을 행별로 임베딩하는 경우, 지원하는 제공자 목록에 없는 모델을 사용하는 경우, 제공자에 접근할 수 없는 폐쇄망 클러스터에는 적합하지 않습니다.
적합한 경우
- 문서 집합이 이미 Apache Doris에 있고, 데이터 수집부터 임베딩, 검색까지 하나의 시스템에서 처리하려는 RAG 및 시맨틱 검색.
- 기존 테이블의 백필:
UPDATE t SET vec = EMBED(body) WHERE vec IS NULL을 사용하면 데이터베이스 안에서 작업을 처리할 수 있습니다. EMBED()를 저장용 ANN 인덱스 및 키워드 필터링용MATCH_*조건자와 함께 사용하는 하이브리드 파이프라인. 하이브리드 검색을 참조하세요.- 파일이 S3에 있고, 다운로드한 뒤 다시 업로드하는 스크립트를 직접 작성하고 싶지 않은 경우의 멀티모달 임베딩(이미지, 동영상, 오디오).
적합하지 않은 경우
- 수백만 행을 대상으로 행별 임베딩을 수행하는 실시간 쿼리. 행마다 제공자를 한 번씩 호출하므로 비용과 지연 시간이 행 수에 따라 늘어납니다. 한 번 미리 계산한 뒤 계속 재사용하세요.
- 지원하는 제공자 목록에 없는 특정 임베딩 모델이 필요한 워크로드. 임베딩 어댑터가 있는 제공자는 OpenAI, Gemini, VoyageAI, Jina, Qwen, MiniMax이며, 자체 모델 서버를 위한
local도 지원합니다. Apache Doris의 전체 AI 리소스 목록에는 DeepSeek, MoonShot, Anthropic, Zhipu, Baichuan도 포함되지만, 이들은 LLM SQL 함수를 통해 채팅 및 완성 기능만 제공하며EMBED()는 지원하지 않습니다. 임베딩 어댑터가 없는 제공자를 연결하려면 OpenAI 또는 Gemini 호환 API를 제공해야 합니다. - 제공자에 접근할 수 없는 폐쇄망 클러스터.
provider_type = "local"로 자체 모델 서버를 사용하거나, 자체 파이프라인에서 벡터를 미리 계산하세요. - 임베딩 모델의 차원 수가 ANN 인덱스와 일치하지 않는 컬럼. ARRAY 길이는 모델에 의해 고정되며, 차원 수 축소를 허용하는 모델에서는
ai.dimensions로 정해집니다. 인덱스의 차원 수는 테이블 생성 시 고정됩니다. 서로 일치하지 않으면 쓰기 시점에 실패합니다.
비용 및 처리량 참고 사항
EMBED()의 처리 속도는 사용하는 제공자의 속도에 달려 있습니다. 주요 실행 경로에 EMBED()를 사용하기 전에 다음 사항을 알아 두세요.
- 외부 API에는 요청 속도 제한이 있습니다.
embed_max_batch_size를 높이면 왕복 호출은 줄어들지만 요청당 토큰 수가 늘어나므로 두 요소를 함께 조정하세요. - 입력이
ai_context_window_size를 초과하는 행은 자동으로 별도의 배치로 처리되므로, 지나치게 큰 문서 하나가 나머지 쿼리 처리를 지연시키지 않습니다. - 제공자는 행 수가 아닌 입력 토큰 수를 기준으로 요금을 부과합니다. 같은 텍스트를 두 번 임베딩하면 비용도 두 배가 듭니다. 벡터를 여러 번 읽을 예정이라면 저장해 두세요.
local제공자는 자격 증명 검사를 건너뛰고 내부 네트워크에서 실행됩니다. 토큰당 과금은 없어지지만 추론 서버를 직접 운영해야 합니다.
더 읽어보기
- EMBED 함수 참조: 전체 구문, 멀티모달 JSON 입력, 거리별 예제.
- AI 함수 개요: 지원하는 모든 제공자와
CREATE RESOURCE의 전체 속성 목록. - 하이브리드 검색: 하나의 쿼리에서
EMBED()를 전문 검색 조건자 및 ANN 인덱스와 결합하는 방법. - 벡터 인덱스 개요: ANN 검색을 위해 HNSW 또는 IVF 인덱스에 임베딩을 저장하는 방법.
- 역색인: 하이브리드 쿼리에서 벡터 순위를 매기기 전에 행을 사전 필터링하는 데 사용하는 인덱스.
- Reciprocal Rank Fusion: 임베딩이 준비된 후 BM25 순위와 벡터 순위를 결합하는 방법.
- LLM SQL 함수:
EMBED()는AI_*계열과 AI 리소스 모델을 공유합니다. AI SQL 기능의 나머지 부분을 소개합니다. - Doris의 AI: 분류, 생성, 여러 행에 걸친 집계 등 나머지 AI 함수 계열.