벡터 검색 인덱스를 만들고 쿼리하는 방법

아티클
11/14/2024

이 문서에서는 Mosaic AI Vector Search를 사용하여 벡터 검색 인덱스를 만들고 쿼리하는 방법을 설명합니다.

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

요구 사항

Unity 카탈로그 사용 작업 영역.
서버리스 컴퓨팅 사용. 지침은 서버리스 컴퓨팅에 연결을 참조하세요.
원본 테이블에 데이터 피드 변경을 사용하도록 설정해야 합니다. 지침은 Azure Databricks에서 Delta Lake 변경 데이터 피드 사용을 참조하세요.
인덱스를 만들려면 카탈로그 스키마에 대한 CREATE TABLE 권한이 있어야 인덱스를 만들 수 있습니다. 다른 사용자가 소유한 인덱스를 쿼리하려면 추가 권한이 있어야 합니다. 벡터 검색 엔드포인트 쿼리를 참조하세요.
개인 액세스 토큰을 사용하려는 경우(프로덕션 워크로드에는 권장되지 않음) 개인 액세스 토큰이 사용하도록 설정되어 있는지 확인합니다. 대신 서비스 주체 토큰을 사용하려면 SDK 또는 API 호출을 사용하여 명시적으로 전달합니다.

SDK를 사용하려면 Notebook에 설치해야 합니다. 다음 코드를 사용합니다.

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

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

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

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

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

왼쪽 사이드바에서 컴퓨팅을 클릭합니다.
벡터 검색 탭을 클릭하고 만들기를 클릭합니다.
엔드포인트 양식 만들기가 열립니다. 이 엔드포인트의 이름을 입력합니다.
확인을 클릭합니다.

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 = VectorSearch(service_principal_client_id=<CLIENT_ID>,service_principal_client_secret=<CLIENT_SECRET>)

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

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

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

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

Databricks가 임베딩을 컴퓨팅하도록 선택한 경우 미리 구성된 Foundation Model API 엔드포인트를 사용하거나 엔드포인트를 제공하는 모델을 만들어 원하는 임베딩 모델을 제공할 수 있습니다. 지침은 토큰당 결제 Foundation Model API 또는 엔드포인트를 제공하는 생성형 AI 모델 만들기를 참조하세요. Notebook 예제는 임베딩 모델을 호출하는 Notebook 예제를 참조하세요.

임베딩 엔드포인트를 구성할 때 Databricks는 기본 선택의 크기 조정을 0으로 제거하는 것이 좋습니다. 엔드포인트 제공은 워밍업하는 데 몇 분 정도 걸릴 수 있으며, 크기가 축소된 엔드포인트가 있는 인덱스의 초기 쿼리는 시간 초과될 수 있습니다.

참고 항목

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

벡터 인덱스 만들기

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

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

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

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

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

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

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

엔드포인트: 사용할 벡터 검색 엔드포인트를 선택합니다.

동기화할 열: 벡터 인덱스와 동기화할 열을 선택합니다. 이 필드를 비워 두면 원본 테이블의 모든 열이 인덱스와 동기화됩니다. 기본 키 열 및 임베딩 원본 열 또는 임베딩 벡터 열은 항상 동기화됩니다.

임베딩 원본: Databricks가 델타 테이블(임베딩 컴퓨팅)의 텍스트 열에 대한 임베딩을 계산할지 또는 델타 테이블에 미리 계산된 임베딩 항목이 포함되어 있는지 여부를 나타냅니다(기존 임베딩 열 사용).
- 임베딩 컴퓨팅을 선택한 경우 계산할 임베딩 열과 임베딩 모델을 제공하는 엔드포인트를 선택합니다. 텍스트 열만 지원됩니다.
- 기존 임베딩 열 사용을 선택한 경우 미리 계산된 임베딩 및 임베딩 차원이 포함된 열을 선택합니다. 미리 계산된 임베딩 열의 형식은 array[float]이어야 합니다.
계산된 임베딩 동기화: 생성된 임베딩을 Unity 카탈로그 테이블에 저장하려면 이 설정을 토글합니다. 자세한 내용은 생성된 임베딩 테이블 저장을 참조하세요.

동기화 모드: 연속적으로 인덱스가 몇 초의 대기 시간 동안 동기화된 상태로 유지됩니다. 그러나 지속적인 동기화 스트리밍 파이프라인을 실행하기 위해 컴퓨팅 클러스터가 프로비전되므로 연결된 비용이 더 높습니다. 연속 및 트리거의 경우 업데이트는 증분이며 마지막 동기화가 처리된 이후 변경된 데이터만 있습니다.

트리거된 동기화 모드에서는 Python SDK 또는 REST API를 사용하여 동기화를 시작합니다. 델타 동기화 인덱스 업데이트를 참조하세요.
인덱스 구성을 마치면 다음을 클릭합니다.

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

다음 예제에서는 Databricks에서 계산하는 임베딩을 사용하여 델타 동기화 인덱스를 만듭니다.

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"
)

다음 예제에서는 자체 관리형 임베딩을 사용하여 델타 동기화 인덱스를 만듭니다. 또한 이 예제에서는 선택적 매개 변수 columns_to_sync를 사용하여 인덱스에 사용할 열의 하위 집합만 선택하는 방법을 보여 줍니다.

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

벡터 검색 인덱스 업데이트

델타 동기화 인덱스 업데이트

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

Python SDK

index.sync()

REST API

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

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

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

Python SDK

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

REST API

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

다음 코드 예제에서는 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": [...]}'

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

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": [...]}'

벡터 검색 엔드포인트 쿼리

Python SDK, REST API 또는 SQL vector_search() AI 함수를 사용하여 벡터 검색 엔드포인트만 쿼리할 수 있습니다.

참고 항목

엔드포인트를 쿼리하는 사용자가 벡터 검색 인덱스의 소유자가 아닌 경우 사용자에게 다음 UC 권한이 있어야 합니다.

벡터 검색 인덱스가 포함된 카탈로그에서 USE CATALOG.
벡터 검색 인덱스가 포함된 스키마에서 USE SCHEMA.
벡터 검색 인덱스에서 SELECT.

하이브리드 키워드 유사성 검색을 수행하려면 매개 변수 query_type를 hybrid로 설정합니다. 기본값은 ann(가장 인접한 항목)입니다.

Python SDK

# Delta Sync Index with embeddings computed by Databricks
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2
    )

# Delta Sync Index using hybrid search, with embeddings computed by Databricks
results3 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2,
    query_type="hybrid"
    )

# Delta Sync Index with pre-calculated embeddings
results2 = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    num_results=2
    )

REST API

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

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

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

# Query Vector Search index with `query_vector`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'

# Query Vector Search index with `query_text`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'

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

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": "ReadVectorIndex"}'
# If you are using an route_optimized embedding model endpoint (TODO: link), then you need to have additional authorization details to invoke the serving endpoint
# export EMBEDDING_MODEL_SERVING_ENDPOINT_ID=...
# export AUTHORIZATION_DETAILS="$AUTHORIZATION_DETAILS"',{"type":"workspace_permission","object_type":"serving-endpoints","object_path":"/serving-endpoints/'"$EMBEDDING_MODEL_SERVING_ENDPOINT_ID"'","actions": ["query_inference_endpoint"]}'

# 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 '"')

# Query Vector Search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'

# Query Vector Search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'

SQL

Important

vector_search() AI 함수는 공개 미리 보기에 있습니다.

이 AI 함수를 사용하려면 vector_search 함수를 참조하세요.

쿼리에 필터 사용

쿼리는 델타 테이블의 모든 열을 기반으로 필터를 정의할 수 있습니다. similarity_search는 지정된 필터와 일치하는 행만 반환합니다. 다음 필터가 지원됩니다.

필터 운영자	동작	예제
`NOT`	필터를 무효화합니다. 키는 "NOT"로 끝나야 합니다. 예를 들어 값이 "레드"인 "color NOT"은 색이 레드가 아닌 문서와 일치합니다.	`{"id NOT": 2}` `{“color NOT”: “red”}`
`<`	필드 값이 필터 값보다 작은지 확인합니다. 키는 ” <”로 끝나야 합니다. 예를 들어 값이 200인 "price <"는 가격이 200보다 작은 문서와 일치합니다.	`{"id <": 200}`
`<=`	필드 값이 필터 값보다 작거나 같은지 확인합니다. 키는 ” <=”로 끝나야 합니다. 예를 들어 값이 200인 "price <="는 가격이 200보다 작거나 같은 문서와 일치합니다.	`{"id <=": 200}`
`>`	필드 값이 필터 값보다 큰지 확인합니다. 키는 ” >”로 끝나야 합니다. 예를 들어 값이 200인 "price >"는 가격이 200보다 큰 문서와 일치합니다.	`{"id >": 200}`
`>=`	필드 값이 필터 값보다 크거나 같은지 확인합니다. 키는 ” >=”로 끝나야 합니다. 예를 들어 값이 200인 "price >="는 가격이 200보다 크거나 같은 문서와 일치합니다.	`{"id >=": 200}`
`OR`	필드 값이 필터 값과 일치하는지 확인합니다. 키는 여러 하위 키를 구분하기 위해 `OR`를 포함해야 합니다. 예를 들어 값이 `["red", "blue"]`인 `color1 OR color2`의 경우 `color1`이 `red`이거나 `color2`가 `blue`인 문서와 일치합니다.	`{"color1 OR color2": ["red", "blue"]}`
`LIKE`	부분 문자열과 일치합니다.	`{"column LIKE": "hello"}`
필터 연산자가 지정되지 않음	필터는 정확히 일치하는지 확인합니다. 여러 값을 지정하면 값 중 하나와 일치합니다.	`{"id": 200}` `{"id": [200, 300]}`

다음 코드 예제를 참조하세요.

Python SDK

# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title": ["Ares", "Athena"]},
    num_results=2
    )

# Match rows where `title` or `id` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title OR id": ["Ares", "Athena"]},
    num_results=2
    )

# Match only rows where `title` is not `Hercules`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title NOT": "Hercules"},
    num_results=2
    )

REST API

POST /api/2.0/vector-search/indexes/{index_name}/query를 참조하세요.

예제 Notebook

이 섹션의 예제에서는 벡터 검색 Python SDK를 사용하는 방법을 보여 줍니다.

LangChain 예제

Mosaic AI Vector Search를 LangChain 패키지와 통합하여 사용하려면 Mosaic AI Vector Search와 함께 LangChain을 사용하는 방법을 참조하세요.

다음 Notebook에서는 유사성 검색 결과를 LangChain 문서로 변환하는 방법을 보여 줍니다.

Python SDK Notebook을 사용하여 벡터 검색

Notebook 가져오기

임베딩 모델 호출을 위한 Notebook 예제

다음 Notebook에서는 임베딩 생성을 위해 Mosaic AI 모델 서비스 엔드포인트를 구성하는 방법을 보여 줍니다.

다음을 통해 공유

벡터 검색 인덱스를 만들고 쿼리하는 방법

요구 사항

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

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

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

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

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

벡터 인덱스 만들기

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

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

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

생성된 임베딩 테이블 저장

벡터 검색 인덱스 업데이트

델타 동기화 인덱스 업데이트

Python SDK

REST API

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

Python SDK

REST API

벡터 검색 엔드포인트 쿼리

Python SDK

REST API

SQL

쿼리에 필터 사용

Python SDK

REST API

예제 Notebook

LangChain 예제

Python SDK Notebook을 사용하여 벡터 검색

임베딩 모델 호출을 위한 Notebook 예제

Mosaic AI Model Serving Notebook을 사용하여 OpenAI 임베딩 모델 호출

Mosaic AI Model Serving Notebook을 사용하여 GTE 임베딩 모델 호출

OSS 임베딩 모델 Notebook 등록 및 제공

피드백

추가 리소스