이전 기사에서 Databricks MCP를 Free Edition으로 테스트하며, AI Search 엔드포인트의 UI가 준비되어 있음을 확인했습니다. 이 기사에서는 실제로 벡터 인덱스 (vector index)를 생성하고, 자연어로 유사 검색 (similarity search)을 실행하기까지의 절차를 노트북 위에서 구동합니다.
- Databricks Community Cloud (Free Edition)
- 컴퓨팅: Serverless Starter Warehouse
- 검증일: 2026년 7월 19일
Databricks AI Search (구 Vector Search)는 서버리스 유사 검색 엔진입니다. 텍스트 데이터로부터 벡터 임베딩 (embedding)을 자동으로 생성하며, 자연어 쿼리로 의미적으로 가까운 문서를 검색할 수 있습니다.
Databricks AI Search is a serverless similarity search engine that allows you to store a vector representation of your data, including metadata, in a vector database.
이번에 사용할 구성은 Delta Sync 인덱스 (Databricks 관리형 임베딩)입니다. 소스 테이블의 변경을 자동으로 감지하여 인덱스를 동기화하는 메커니즘으로, 임베딩 모델 지정만으로 동작합니다.
- 샘플 데이터를 확인하고 자신의 카탈로그로 복사하기
- Change Data Feed 활성화하기
- Python SDK로 벡터 인덱스 생성하기
- 인덱스가 온라인 상태가 될 때까지 기다리기
- 유사 검색 실행하기
Free Edition에는 samples.bakehouse라는 샘플 데이터셋이 공유되어 있습니다. 이번에는 media_gold_reviews_chunked 테이블 (베이커리 리뷰를 청크(chunk) 단위로 분할 완료한 데이터)을 사용합니다.
%sql
SELECT * FROM samples.bakehouse.media_gold_reviews_chunked;
196행의 리뷰 데이터가 저장되어 있습니다. chunk_id (청크의 고유 키)와 chunked_text (리뷰 본문)를 사용합니다.
samples 카탈로그의 테이블은 읽기 전용 공유 데이터입니다. AI Search 인덱스 생성에는 본인이 소유한 테이블이 필요하므로, demo_catalog로 복사합니다.
스키마를 생성하고, 샘플에서 20행만 복사합니다 (데모이므로 작게 유지합니다).
%sql
CREATE SCHEMA IF NOT EXISTS demo_catalog.ai_search_demo;
%sql
CREATE OR REPLACE TABLE demo_catalog.ai_search_demo.reviews AS
SELECT chunk_id, chunked_text AS text
...
Delta Sync 인덱스는 소스 테이블의 변경을 추적하기 위해 Change Data Feed (CDF)를 사용합니다. 테이블 속성에서 활성화합니다.
%sql
ALTER TABLE demo_catalog.ai_search_demo.reviews
SET TBLPROPERTIES (delta.enableChangeDataFeed = true);
데이터를 확인합니다.
%sql
SELECT * FROM demo_catalog.ai_search_demo.reviews LIMIT 5;
chunk_id와 text 두 개의 컬럼만 있는 심플한 테이블이 만들어졌습니다.
노트북에서 Python SDK를 사용하려면 먼저 패키지를 설치합니다.
%pip install databricks-vectorsearch --quiet
설치 후, 커널을 재시작하여 새로운 패키지를 로드합니다.
dbutils.library.restartPython()
databricks-vectorsearch는 권장되지 않으며 (deprecated), databricks-ai-search로 이름이 변경되었습니다. 현재 시점에서는 둘 다 동작하지만, 향후에는 databricks-ai-search를 사용해야 합니다.
로 전환하십시오.
VectorSearchClient를 사용하여 인덱스를 생성합니다.
from databricks.vector_search.client import VectorSearchClient
vsc = VectorSearchClient()
vsc.create_delta_sync_index(
...
각 파라미터의 의미는 다음과 같습니다.
| 파라미터 | 값 | 설명 |
|---|
endpoint_name | mcp-demo | AI Search 엔드포인트 이름 (미생성 시 자동 생성됨) |
index_name | demo_catalog.ai_search_demo.reviews_index | 인덱스의 전체 이름 (catalog.schema.name) |
source_table_name | demo_catalog.ai_search_demo.reviews | 소스 테이블 |
pipeline_type | TRIGGERED | 온디맨드 동기화 (수동 트리거로 동기화 실행) |
primary_key | chunk_id | 행의 고유 키 |
embedding_source_column | text | 임베딩 (Embedding)을 생성할 원본 컬럼 |
embedding_model_endpoint_name | databricks-bge-large-en | Databricks가 제공하는 임베딩 모델 |
pipeline_type에는 TRIGGERED (수동 동기화)와 CONTINUOUS (자동 동기화)가 있습니다. 데모에서는 TRIGGERED를 사용합니다.
인덱스 생성을 실행하면 백그라운드에서 엔드포인트 프로비저닝 (Provisioning)과 인덱스 구축이 시작됩니다. describe()로 상태를 확인할 수 있습니다.
from databricks.vector_search.client import VectorSearchClient
import json
vsc = VectorSearchClient(disable_notice=True)
...
상태는 다음과 같이 전이됩니다.
detailed_state | 상태 |
|---|
PROVISIONING_ENDPOINT | 엔드포인트를 시작하는 중 |
PROVISIONING_INDEX | 인덱스를 구축하는 중 (임베딩 생성 포함) |
ONLINE_NO_PENDING_UPDATE | 준비 완료 |
Free Edition에서의 소요 시간은 약 20~30분이었습니다 (엔드포인트 시작에 대부분의 시간이 소요됩니다). indexed_row_count: 16이 되어, 20개 행 중 16개 행이 인덱스에 등록되었습니다.
Compute → AI Search 탭을 열면 mcp-demo 엔드포인트가 Ready 상태로 표시됩니다.
인덱스가 온라인 상태가 되면, similarity_search()를 통해 자연어 유사 검색을 할 수 있습니다.
results = index.similarity_search(
columns=["chunk_id", "text"],
query_text="best bakery experience",
...
"best bakery experience" (최고의 베이커리 경험)라는 쿼리에 대해, 의미적으로 가까운 리뷰 3건이 점수와 함께 반환되었습니다. 점수가 높을수록 쿼리와의 유사도가 높음을 나타냅니다.
similarity_search()의 주요 파라미터는 다음과 같습니다.
| 파라미터 | 설명 |
|---|
columns | 결과에 포함할 컬럼 이름 리스트 |
query_text | 자연어 검색 쿼리 |
num_results | 반환할 결과 개수 |
filters | 메타데이터를 통한 필터 조건 (선택 사항) |
첫 번째 기사에서 정리한 바와 같이, Databricks MCP에는 AI Search용 엔드포인트가 있습니다.
/api/2.0/mcp/ai-search/{catalog}/{schema}/{index_name}
이번에 생성한 인덱스를 MCP를 통해 사용할 경우, URL은 다음과 같습니다.
Claude나 Cursor에서 PAT 인증으로 연결하면, AI 어시스턴트가 이 인덱스를 검색 도구 (Search Tool)로 사용할 수 있게 됩니다.
위의 절차를 정리한, 1개 셀에서 실행 가능한 코드입니다. 테이블 생성부터 인덱스 생성, 상태 대기, 유사 검색까지 한 번에 실행합니다.
spark.sql("CREATE SCHEMA IF NOT EXISTS demo_catalog.ai_search_demo")
spark.sql("""
...
databricks-vectorsearch가 설치되어 있지 않은 경우, 사전에 별도의 셀에서 %pip install databricks-vectorsearch --quiet와 dbutils.library.restartPython()을 실행해 주세요.
| 문제 | 원인 및 대처 |
|---|
| 공유 테이블에 인덱스를 만들 수 없음 | samples 카탈로그는 읽기 전용입니다. 자신의 카탈로그로 테이블을 복사하세요. |
ModuleNotFoundError: No module named 'databricks.vector_search' | %pip install databricks-vectorsearch + dbutils.library.restartPython()으로 해결 |
| 엔드포인트 프로비저닝 (Provisioning)이 오래 걸림 | Free Edition에서는 20~30분 정도 소요될 수 있습니다. describe()로 상태를 정기적으로 확인하세요. |
DeprecationWarning: databricks-vectorsearch renamed to databricks-ai-search | 패키지명이 변경되었습니다. 현재는 구 명칭으로도 동작하지만, 신규 설치 시에는 databricks-ai-search를 사용하세요. |
Databricks AI Search의 인덱스 생성부터 유사 검색까지를 Free Edition 노트북에서 실행했습니다.
-
샘플 데이터를 자신의 카탈로그로 복사하고, Change Data Feed를 활성화합니다.
-
VectorSearchClient.create_delta_sync_index()로 인덱스를 생성합니다 (임베딩 모델 (Embedding Model)은 databricks-bge-large-en을 지정).
-
엔드포인트와 인덱스의 프로비저닝 (Provisioning)을 위해 20~30분 정도 기다립니다.
-
index.similarity_search()로 자연어 유사 검색을 수행할 수 있습니다.
-
생성한 인덱스는 MCP 엔드포인트 /api/2.0/mcp/ai-search/...를 통해서도 이용 가능합니다.
-
Databricks AI Search
-
Create a vector search index
-
Query a vector search index
-
Databricks managed MCP servers
본 기사의 기술 기술은 2026년 7월 시점의 공식 문서에 기반합니다. AI Search는 GA(General Availability) 상태이며, 패키지명 이전 (databricks-vectorsearch → databricks-ai-search)이 진행 중이므로 향후 사양이 변경될 가능성이 있습니다.
![[Databricks] AI Search (구 Vector Search)를 Free Edition에서 구동하기 — 인덱스 생성부터 유사 검색까지 대표 이미지](/api/thumb?u=https%3A%2F%2Fqiita-user-contents.imgix.net%2Fhttps%253A%252F%252Fqiita-user-contents.imgix.net%252Fhttps%25253A%25252F%25252Fcdn.qiita.com%25252Fassets%25252Fpublic%25252Farticle-ogp-background-afbab5eb44e0b055cce1258705637a91.png%253Fixlib%253Drb-4.1.1%2526w%253D1200%2526blend64%253DaHR0cHM6Ly9xaWl0YS11c2VyLXByb2ZpbGUtaW1hZ2VzLmltZ2l4Lm5ldC9odHRwcyUzQSUyRiUyRnMzLWFwLW5vcnRoZWFzdC0xLmFtYXpvbmF3cy5jb20lMkZxaWl0YS1pbWFnZS1zdG9yZSUyRjAlMkY0NDExNTY5JTJGOTcwMTlkNGQwOTFlNjg2OTQxNjVlODdjZjU2Mjk0ZDc0NmVkNzIyNiUyRmxhcmdlLnBuZyUzRjE3ODE0MTI1MzY_aXhsaWI9cmItNC4xLjEmYXI9MSUzQTEmZml0PWNyb3AmbWFzaz1lbGxpcHNlJmJnPUZGRkZGRiZmbT1wbmczMiZzPTczYTQ1ODkwYzAxODk2NmQ5OGUxZGUwOTc0OThhOGZl%2526blend-x%253D120%2526blend-y%253D467%2526blend-w%253D82%2526blend-h%253D82%2526blend-mode%253Dnormal%2526s%253Da654625c15b54b504fd5f9ca21f0f55b%3Fixlib%3Drb-4.1.1%26w%3D1200%26fm%3Djpg%26mark64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjEuMSZ3PTk2MCZoPTMyNCZ0eHQ9JTVCRGF0YWJyaWNrcyU1RCUyMEFJJTIwU2VhcmNoJUVGJUJDJTg4JUU2JTk3JUE3JTIwVmVjdG9yJTIwU2VhcmNoJUVGJUJDJTg5JUUzJTgyJTkyJTIwRnJlZSUyMEVkaXRpb24lMjAlRTMlODElQTclRTUlOEIlOTUlRTMlODElOEIlRTMlODElOTklMjAlRTIlODAlOTQlMjAlRTMlODIlQTQlRTMlODMlQjMlRTMlODMlODclRTMlODMlODMlRTMlODIlQUYlRTMlODIlQjklRTQlQkQlOUMlRTYlODglOTAlRTMlODElOEIlRTMlODIlODklRTklQTElOUUlRTQlQkMlQkMlRTIlODAlQTYmdHh0LWFsaWduPWxlZnQlMkN0b3AmdHh0LWNvbG9yPSUyMzFFMjEyMSZ0eHQtZm9udD1IaXJhZ2lubyUyMFNhbnMlMjBXNiZ0eHQtc2l6ZT01NiZ0eHQtcGFkPTAmcz0yNGIyZjczNmJkOWVkZjY0NTdmMjdkNzdkMjhiZDQ4MA%26mark-x%3D120%26mark-y%3D112%26blend64%3DaHR0cHM6Ly9xaWl0YS11c2VyLWNvbnRlbnRzLmltZ2l4Lm5ldC9-dGV4dD9peGxpYj1yYi00LjEuMSZ3PTgzOCZoPTU4JnR4dD0lNDAwZmYwMGRleDdmM2EmdHh0LWNvbG9yPSUyMzFFMjEyMSZ0eHQtZm9udD1IaXJhZ2lubyUyMFNhbnMlMjBXNiZ0eHQtc2l6ZT0zNiZ0eHQtcGFkPTAmcz1mNmE2YmU2YjMzZDcwY2I5Yjg3ZTExZGVmZTgwMDdkZA%26blend-x%3D242%26blend-y%3D480%26blend-w%3D838%26blend-h%3D46%26blend-fit%3Dcrop%26blend-crop%3Dleft%252Cbottom%26blend-mode%3Dnormal%26s%3D7d549cd1d96256b0ef1f1fae585202f1&w=640&s=5KYBL2In6BrR5A2QgDiC7Me5)