벡터 검색 엔드포인트 및 인덱스 만들기

이 문서에서는 Mosaic AI 벡터 검색을 사용하여 벡터 검색 엔드포인트 및 인덱스를 만드는 방법을 설명합니다.

UI, Python SDK또는 REST API사용하여 벡터 검색 엔드포인트 및 벡터 검색 인덱스와 같은 벡터 검색 구성 요소를 만들고 관리할 수 있습니다.

벡터 검색 엔드포인트를 만들고 쿼리하는 방법을 보여 주는 예제 Notebook은 Vector 검색 예제 Notebook을 참조하세요. 참조 정보는 Python SDK 참조를 참조하세요.

요구 사항

Unity 카탈로그가 활성화된 작업 영역.
서버리스 컴퓨팅을 사용하도록 설정했습니다. 지침은 서버리스 컴퓨팅 연결하기를 참조하세요.
표준 엔드포인트의 경우 원본 테이블에 변경 데이터 피드를 사용하도록 설정해야 합니다. Azure Databricks에서 Delta Lake 변경 데이터 피드 사용을 참조하세요.
벡터 검색 인덱스를 만들려면 인덱스를 만들 카탈로그 스키마에 대한 CREATE TABLE 권한이 있어야 합니다.
다른 사용자가 소유한 인덱스를 쿼리하려면 추가 권한이 있어야 합니다. 벡터 검색 인덱스 쿼리 방법을 참조하세요.

벡터 검색 엔드포인트를 만들고 관리하는 권한은 액세스 제어 목록을 사용하여 구성됩니다. 벡터 검색 엔드포인트 ACL을 참조 하세요.

설치

벡터 검색 SDK를 사용하려면 Notebook에 설치해야 합니다. 다음 코드를 사용하여 패키지를 설치합니다.

%pip install databricks-vectorsearch
dbutils.library.restartPython()

그런 다음, 다음 명령을 사용하여 VectorSearchClient가져옵니다.

from databricks.vector_search.client import VectorSearchClient

인증에 대한 자세한 내용은 데이터 보호 및 인증을 참조하세요.

벡터 검색 엔드포인트 만들기

Databricks UI, Python SDK 또는 API를 사용하여 벡터 검색 엔드포인트를 만들 수 있습니다.

UI를 사용하여 벡터 검색 엔드포인트 만들기

다음 단계에 따라 UI를 사용하여 벡터 검색 엔드포인트를 만듭니다.

왼쪽 사이드바에서 컴퓨팅을 클릭합니다.
벡터 검색 탭을 클릭하고 만들기을 클릭하세요.

만들기
엔드포인트 만들기 양식 열립니다. 이 엔드포인트의 이름을 입력합니다.
형식 필드에서 표준 또는 스토리지 최적화를 선택합니다. 엔드포인트 옵션을 참조하세요.
(선택 사항) 고급 설정에서 예산 정책을 선택합니다. 모자이크 AI 벡터 검색: 예산 정책을 참조하세요.
확인을 클릭합니다.

Python SDK를 사용하여 벡터 검색 엔드포인트 만들기

다음 예제에서는 create_endpoint() SDK 함수를 사용하여 벡터 검색 엔드포인트를 만듭니다.

# The following line automatically generates a PAT Token for authentication
client = VectorSearchClient()

# The following line uses the service principal token for authentication
# client = VectorSearchClient(service_principal_client_id=<CLIENT_ID>,service_principal_client_secret=<CLIENT_SECRET>)

client.create_endpoint(
    name="vector_search_endpoint_name",
    endpoint_type="STANDARD" # or "STORAGE_OPTIMIZED"
)

REST API를 사용하여 벡터 검색 엔드포인트 만들기

REST API 참조 설명서를 참조하세요. POST /api/2.0/vector-search/endpoints.

(선택 사항) 포함 모델을 제공하도록 엔드포인트 만들기 및 구성

Databricks가 임베딩을 컴퓨팅하도록 선택한 경우, 미리 구성된 Foundation Model API 엔드포인트를 사용하거나 선택한 임베딩 모델을 제공하기 위해 모델 서빙 엔드포인트를 생성할 수 있습니다. 지침은 토큰당 종량제 모델 API 또는 엔드포인트 제공하는 기본 모델 만들기를 참조하세요. 예제 노트북은 벡터 검색 예제 노트북을 참조하세요.

임베딩 엔드포인트를 구성할 때, Databricks는 0으로 조정을 기본 선택에서 제거할 것을 권장합니다. 엔드포인트가 서비스할 준비를 하는 데 몇 분이 소요될 수 있으며, 크기가 줄어든 엔드포인트로 인덱스에 대한 초기 쿼리를 실행하면 시간 초과가 발생할 수 있습니다.

비고

포함 엔드포인트가 데이터 세트에 대해 적절하게 구성되지 않은 경우 벡터 검색 인덱스 초기화 시간이 초과될 수 있습니다. 작은 데이터 세트 및 테스트에만 CPU 엔드포인트를 사용해야 합니다. 더 큰 데이터 세트의 경우 최적의 성능을 위해 GPU 엔드포인트를 사용합니다.

벡터 검색 인덱스 만들기

UI, Python SDK 또는 REST API를 사용하여 벡터 검색 인덱스 만들 수 있습니다. UI는 가장 간단한 방법입니다.

인덱스에는 두 가지 유형이 있습니다.

델타 동기화 인덱스 자동으로 원본 델타 테이블과 동기화되고 델타 테이블의 기본 데이터가 변경됨에 따라 인덱스를 자동으로 증분 방식으로 업데이트합니다.
직접 벡터 액세스 인덱스 벡터 및 메타데이터의 직접 읽기 및 쓰기를 지원합니다. 사용자는 REST API 또는 Python SDK를 사용하여 이 테이블을 업데이트해야 합니다. 이 유형의 인덱스도 UI를 사용하여 만들 수 없습니다. REST API 또는 SDK를 사용해야 합니다.

비고

열 이름 _id은(는) 예약되어 있습니다. 소스 테이블에 _id라는 열이 있을 경우, 벡터 검색 인덱스를 생성하기 전에 그 열의 이름을 변경하십시오.

UI를 사용하여 인덱스 만들기

왼쪽 사이드바에서 카탈로그 클릭하여 카탈로그 탐색기 UI를 엽니다.
사용하려는 델타 테이블로 이동합니다.
오른쪽 위에 있는 만들기 단추를 클릭하고 드롭다운 메뉴에서 벡터 검색 인덱스 선택합니다.
대화 상자의 선택기를 사용하여 인덱스 구성

인덱스 만들기 대화 상자create index dialog

이름: Unity 카탈로그의 온라인 테이블에 사용할 이름입니다. 이름에는 <catalog>.<schema>.<name>세 개의 수준 네임스페이스가 필요합니다. 영숫자 문자와 밑줄만 허용됩니다.

기본 키: 기본 키로 사용할 열입니다.

동기화할 열: (표준 엔드포인트에 대해서만 지원됨) 벡터 인덱스와 동기화할 열을 선택합니다. 이 필드를 비워 두면 원본 테이블의 모든 열이 인덱스와 동기화됩니다. 기본 키 열과 임베딩 원본 열 또는 임베딩 벡터 열은 항상 동기화됩니다. 스토리지 최적화 엔드포인트의 경우 원본 테이블의 모든 열이 항상 동기화됩니다.

임베딩 원본: Databricks가 Delta 테이블 내 텍스트 열에 대한 임베딩을 계산하도록 할지(임베딩 계산), 또는 귀하의 Delta 테이블에 미리 계산된 임베딩이 있는 경우(기존 임베딩 열사용)를 나타내십시오.
- 컴퓨팅 포함을 선택한 경우 계산할 포함 열과 계산에 사용할 포함 모델을 선택합니다. 텍스트 열만 지원됩니다.
  - 표준 엔드포인트를 사용하는 프로덕션 애플리케이션의 경우 Databricks는 엔드포인트를 제공하는 프로비전된 처리량과 함께 기본 모델을 databricks-gte-large-en 사용하는 것이 좋습니다.
  - Databricks 호스팅 모델에서 스토리지 최적화된 엔드포인트를 사용하는 프로덕션 애플리케이션의 경우, 모델 이름을 그대로 임베딩 모델 엔드포인트로 사용합니다(예: databricks-gte-large-en). 스토리지 최적화 엔드포인트는 데이터 수집 시 ai_query와 함께 배치 추론에 사용되어 임베딩 작업에 높은 처리량을 제공합니다. 프로비전된 처리량 엔드포인트를 쿼리에 사용하려는 경우 인덱스 생성 시 필드에 지정 model_endpoint_name_for_query 합니다.
- 기존 임베딩 열 사용을 선택한 경우, 미리 계산된 임베딩과 임베딩 차원을 포함하는 열을 선택하십시오. 미리 계산된 포함 열의 형식은 array[float]합니다. 스토리지 최적화 엔드포인트의 경우 포함 차원을 16으로 균등하게 나눌 수 있어야 합니다.
계산된 임베딩동기화: 생성된 임베딩을 Unity 카탈로그 테이블에 저장하려면 이 설정을 켜거나 끕니다. 자세한 내용은 생성된 임베딩 테이블 저장을 참조하세요.

벡터 검색 엔드포인트: 인덱스 저장을 위한 벡터 검색 엔드포인트를 선택합니다.

동기화 모드: 연속 인덱스가 대기 시간(초)과 동기화된 상태로 유지됩니다. 그럼에도 불구하고, 연속 동기화 스트리밍 파이프라인을 실행하기 위해 컴퓨팅 클러스터를 준비해야 하므로 비용이 더 많이 듭니다.
- 표준 엔드포인트의 경우 연속 및 트리거가 모두 증분 업데이트를 수행하므로 마지막 동기화 이후 변경된 데이터만 처리됩니다.
- 스토리지 최적화 엔드포인트의 경우 모든 동기화에서 인덱스를 부분적으로 다시 작성합니다. 후속 동기화에서 관리되는 인덱스의 경우 원본 행이 변경되지 않은 생성된 임베딩은 다시 사용되며 다시 계산할 필요가 없습니다. 스토리지 최적화 엔드포인트 제한 사항을 참조하세요.
트리거된 동기화 모드에서는 Python SDK 또는 REST API를 사용하여 동기화를 시작합니다. 델타 동기화 인덱스 업데이트참조하세요.

스토리지 최적화 엔드포인트의 경우 트리거된 동기화 모드만 지원됩니다.

고급 설정: (선택 사항) 컴퓨팅 포함을 선택한 경우 별도의 포함 모델을 지정하여 벡터 검색 인덱스를 쿼리할 수 있습니다. 이는 수집을 위해 높은 처리량 엔드포인트가 필요하지만 인덱스 쿼리를 위한 대기 시간 엔드포인트가 낮은 경우에 유용할 수 있습니다. 포함 모델 필드에 지정된 모델은 항상 수집에 사용되며 여기에 다른 모델을 지정하지 않는 한 쿼리에도 사용됩니다. 다른 모델을 지정하려면 인덱스 쿼리를 위해 별도의 포함 모델 선택을 클릭하고 드롭다운 메뉴에서 모델을 선택합니다.
인덱스 구성을 마쳤으면 만들기클릭합니다.

Python SDK를 사용하여 인덱스 만들기

다음 예제에서는 Databricks에서 계산된 임베딩을 사용하여 델타 동기화 인덱스를 만듭니다. 자세한 내용은 Python SDK 참조를 참조하세요.

또한 이 예제에서는 인덱스를 쿼리하는 데 사용할 엔드포인트를 제공하는 별도의 포함 모델을 지정하는 선택적 매개 변수 model_endpoint_name_for_query를 보여줍니다.

client = VectorSearchClient()

index = client.create_delta_sync_index(
  endpoint_name="vector_search_demo_endpoint",
  source_table_name="vector_search_demo.vector_search.en_wiki",
  index_name="vector_search_demo.vector_search.en_wiki_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  embedding_source_column="text",
  embedding_model_endpoint_name="e5-small-v2", # This model is used for ingestion, and is also used for querying unless model_endpoint_name_for_query is specified.
  model_endpoint_name_for_query="e5-mini-v2"   # Optional. If specified, used only for querying the index.
)

다음 예제는 자동 관리 임베딩이 포함된 델타 동기화 인덱스를 생성합니다.

client = VectorSearchClient()

index = client.create_delta_sync_index(
  endpoint_name="vector_search_demo_endpoint",
  source_table_name="vector_search_demo.vector_search.en_wiki",
  index_name="vector_search_demo.vector_search.en_wiki_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  embedding_dimension=1024,
  embedding_vector_column="text_vector"
)

기본적으로 원본 테이블의 모든 열은 인덱스와 동기화됩니다.

표준 엔드포인트에서 columns_to_sync을 사용하여 동기화할 열의 하위 집합을 선택할 수 있습니다. 기본 키 및 포함 열은 항상 인덱스에 포함됩니다.

기본 키와 임베딩 열 만 동기화하려면, columns_to_sync에 표시된 대로 이를 지정해야 합니다.

index = client.create_delta_sync_index(
  ...
  columns_to_sync=["id", "text_vector"] # to sync only the primary key and the embedding column
)

추가 열을 동기화하려면 표시된 대로 지정합니다. 기본 키와 포함 열은 항상 동기화되므로 포함 열을 포함할 필요가 없습니다.

index = client.create_delta_sync_index(
  ...
  columns_to_sync=["revisionId", "text"] # to sync the `revisionId` and `text` columns in addition to the primary key and embedding column.
)

다음 예제에서는 직접 벡터 액세스 인덱스를 만듭니다.


client = VectorSearchClient()

index = client.create_direct_access_index(
  endpoint_name="storage_endpoint",
  index_name=f"{catalog_name}.{schema_name}.{index_name}",
  primary_key="id",
  embedding_dimension=1024,
  embedding_vector_column="text_vector",
  schema={
    "id": "int",
    "field2": "string",
    "field3": "float",
    "text_vector": "array<float>"}
)

REST API를 사용하여 인덱스 만들기

REST API 참조 설명서를 참조하세요. POST /api/2.0/vector-search/indexes.

생성된 임베딩 테이블 저장

Databricks가 포함을 생성하는 경우 생성된 포함을 Unity 카탈로그의 테이블에 저장할 수 있습니다. 이 테이블은 벡터 인덱스와 동일한 스키마에 만들어지고 벡터 인덱스 페이지에서 연결됩니다.

테이블의 이름은 _writeback_table추가된 벡터 검색 인덱스의 이름입니다. 이름을 편집할 수 없습니다.

Unity 카탈로그의 다른 테이블과 마찬가지로 테이블에 액세스하고 쿼리할 수 있습니다. 그러나 수동으로 업데이트할 수 없으므로 테이블을 삭제하거나 수정해서는 안 됩니다. 인덱스가 삭제되면 테이블이 자동으로 삭제됩니다.

벡터 검색 인덱스 업데이트

델타 동기화 인덱스를 업데이트하다.

연속 동기화 모드로 만든 인덱스는 원본 델타 테이블이 변경되면 자동으로 업데이트됩니다. 트리거된 동기화 모드를 사용하는 경우 UI, Python SDK 또는 REST API를 사용하여 동기화를 시작할 수 있습니다.

Databricks 사용자 인터페이스

카탈로그 탐색기에서 벡터 검색 인덱스로 이동합니다.
개요 탭의 데이터 수집 섹션에서 지금 동기화를 클릭합니다.

Python SDK

자세한 내용은 Python SDK 참조를 참조하세요.

client = VectorSearchClient()
index = client.get_index(index_name="vector_search_demo.vector_search.en_wiki_index")

index.sync()

REST API

REST API 참조 설명서를 참조하세요. POST /api/2.0/vector-search/indexes/{index_name}/sync.

직접 벡터 액세스 인덱스 업데이트

Python SDK 또는 REST API를 사용하여 직접 벡터 액세스 인덱스에서 데이터를 삽입, 업데이트 또는 삭제할 수 있습니다.

Python SDK

자세한 내용은 Python SDK 참조를 참조하세요.

index.upsert([
    {
        "id": 1,
        "field2": "value2",
        "field3": 3.0,
        "text_vector": [1.0] * 1024
    },
    {
        "id": 2,
        "field2": "value2",
        "field3": 3.0,
        "text_vector": [1.1] * 1024
    }
])

REST API

REST API 참조 설명서를 참조하세요. POST /api/2.0/vector-search/indexes.

프로덕션 애플리케이션의 경우 Databricks는 개인용 액세스 토큰 대신 서비스 주체를 사용하는 것이 좋습니다. 쿼리당 최대 100msec까지 성능을 향상시킬 수 있습니다.

다음 코드 예제에서는 서비스 주체를 사용하여 인덱스를 업데이트하는 방법을 보여 줍니다.

export SP_CLIENT_ID=...
export SP_CLIENT_SECRET=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...
export WORKSPACE_ID=...

# Set authorization details to generate OAuth token
export AUTHORIZATION_DETAILS='{"type":"unity_catalog_permission","securable_type":"table","securable_object_name":"'"$INDEX_NAME"'","operation": "WriteVectorIndex"}'

# Generate OAuth token
export TOKEN=$(curl -X POST --url $WORKSPACE_URL/oidc/v1/token -u "$SP_CLIENT_ID:$SP_CLIENT_SECRET" --data 'grant_type=client_credentials' --data 'scope=all-apis' --data-urlencode 'authorization_details=['"$AUTHORIZATION_DETAILS"']' | jq .access_token | tr -d '"')

# Get index URL
export INDEX_URL=$(curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME | jq -r '.status.index_url' | tr -d '"')

# Upsert data into vector search index.
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/upsert-data --data '{"inputs_json": "[...]"}'

# Delete data from vector search index
curl -X DELETE -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/delete-data --data '{"primary_keys": [...]}'

다음 코드 예제에서는 PAT(개인 액세스 토큰)를 사용하여 인덱스를 업데이트하는 방법을 보여 줍니다.

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

# Upsert data into vector search index.
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/upsert-data --data '{"inputs_json": "..."}'

# Delete data from vector search index
curl -X DELETE -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/delete-data --data '{"primary_keys": [...]}'

가동 중지 시간 없이 스키마를 변경하는 방법

원본 테이블에 있는 기존 열의 스키마가 변경되면 인덱스를 다시 작성해야 합니다. 쓰기 저장 테이블을 사용하는 경우 새 열이 원본 테이블에 추가될 때 인덱스도 다시 작성해야 합니다. 쓰기 저장 테이블을 사용하도록 설정하지 않으면 새 열에서 인덱스를 다시 작성할 필요가 없습니다.

가동 중지 시간 없이 인덱스 다시 빌드 및 배포를 수행하려면 다음 단계를 수행합니다.

원본 테이블에서 스키마 변경을 수행합니다.
새 인덱스 만들기
새 인덱스가 준비되면 트래픽을 새 인덱스로 전환합니다.
원래 인덱스 삭제

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-12-05

다음을 통해 공유

벡터 검색 엔드포인트 및 인덱스 만들기

요구 사항

설치

벡터 검색 엔드포인트 만들기

UI를 사용하여 벡터 검색 엔드포인트 만들기

Python SDK를 사용하여 벡터 검색 엔드포인트 만들기

REST API를 사용하여 벡터 검색 엔드포인트 만들기

(선택 사항) 포함 모델을 제공하도록 엔드포인트 만들기 및 구성

벡터 검색 인덱스 만들기

UI를 사용하여 인덱스 만들기

Python SDK를 사용하여 인덱스 만들기

REST API를 사용하여 인덱스 만들기

생성된 임베딩 테이블 저장

벡터 검색 인덱스 업데이트

델타 동기화 인덱스를 업데이트하다.

Databricks 사용자 인터페이스

Python SDK

REST API

직접 벡터 액세스 인덱스 업데이트

Python SDK

REST API

가동 중지 시간 없이 스키마를 변경하는 방법

피드백

추가 리소스