벡터 검색 인덱스 쿼리

이 페이지에서는 페이지 매김, 필터 및 재정렬을 포함하여 벡터 검색 인덱스를 쿼리하는 방법을 설명합니다.

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

설치

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

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

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

from databricks.vector_search.client import VectorSearchClient

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

벡터 검색 인덱스 쿼리 방법

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

기본 쿼리 유형은 ann (근사값 최근접 이웃)입니다. 다양한 검색 알고리즘에 대한 자세한 내용은 검색 알고리즘을 참조하세요.

• 하이브리드 키워드 유사성 검색을 수행하려면 매개 변수 query_typehybrid설정합니다. 하이브리드 검색을 사용하면 모든 텍스트 메타데이터 열이 포함되고 최대 200개의 결과가 반환됩니다.
• 쿼리에서 재랜커를 사용하려면 쿼리 에서 재랜커 사용을 참조하세요.

Python SDK 표준 엔드포인트

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

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

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

# Delta Sync Index using full-text search (Beta)
results4 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "field2"],
    num_results=2,
    query_type="FULL_TEXT"
    )

# Delta Sync Index with pre-calculated embeddings
results2 = index.similarity_search(
    query_vector=[0.9] * 1024,
    columns=["id", "text"],
    num_results=2
    )

Python SDK 스토리지 최적화 엔드포인트

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

기존 필터 인터페이스는 스토리지 최적화 벡터 검색 인덱스가 표준 벡터 검색 엔드포인트에 사용되는 필터 사전 대신 SQL과 유사한 필터 문자열을 채택하도록 다시 설계되었습니다.

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

# similarity search with query vector
results = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    num_results=2
)

# similarity search with query vector and filter string
results = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    # this is a single filter string similar to SQL WHERE clause syntax
    filters="language = 'en' AND country = 'us'",
    num_results=2
)

REST API

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

프로덕션 애플리케이션의 경우 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": "ReadVectorIndex"}'
# If you are using an route_optimized embedding model endpoint, 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}'

다음 코드 예제에서는 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}'

SQL

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

페이지 나누기

쿼리가 1,000개 이상의 결과를 요청하면 최대 1,000페이지의 페이지에서 결과가 자동으로 반환됩니다. 단일 쿼리가 모든 페이지에서 반환할 수 있는 최대 결과 수는 10,000개입니다. 표준 엔드포인트와 스토리지 최적화 엔드포인트는 모두 페이지 매김을 지원합니다.

페이지 매김은 모든 쿼리 형식에서 작동합니다.

Python SDK

Python SDK는 페이지 매김을 투명하게 처리합니다. 1,000보다 큰 값으로 설정 num_results 하면 SDK는 자동으로 모든 페이지를 검색하고 전체 결과 집합을 반환합니다. 추가 코드가 필요하지 않습니다.

# The SDK automatically paginates and returns all 5000 results
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=5000
)

REST API

REST API를 직접 사용하는 경우 페이지 매김을 수동으로 처리해야 합니다. 더 많은 결과를 사용할 수 있는 경우 응답에는 필드가 next_page_token 포함됩니다. 결과의 다음 페이지를 검색하려면 이 토큰을 쿼리-다음 페이지 엔드포인트에 전달합니다.

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

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

# Initial query - if num_results exceeds 1000, the response includes next_page_token
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": 5000, "query_text": "...", "columns": ["id", "text"]}'

# Use next_page_token from the response to get the next page
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \
  --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query-next-page \
  --data '{"page_token": "<next_page_token from previous response>"}'

토큰이 비어 있거나 없을 때까지 각 응답에서 쿼리-다음 페이지 엔드포인트 next_page_token 를 계속 호출합니다. 이는 모든 결과가 반환되었음을 나타냅니다.

쿼리에 필터 사용

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

다음 표에서는 지원되는 필터를 나열합니다.

사용 현황에 대한 참고 사항 LIKE

LIKE 표준 엔드포인트에 대한 예제

{"column LIKE": "apple"}: 문자열 "apple" 및 "apple pear"와 일치하지만 "파인애플"과 일치하지 않습니다. 부분 문자열 "apple"이 포함되어 있어도 "파인애플"과 일치하지 않습니다. "apple pear"와 같이 공백으로 구분된 토큰과 정확히 일치하는 항목을 찾습니다.

{"column NOT LIKE": "apple"} 그 반대의 경우도 마찬가지입니다. "파인애플"과 "배"와 일치하지만 "사과" 또는 "사과 배"와 일치하지 않습니다.

LIKE 스토리지에 최적화된 엔드포인트에 대한 예제

코드 예제

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
    )

Python SDK 스토리지 최적화 엔드포인트

# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters='title IN ("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 = "Ares" OR id = "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 != "Hercules"',
    num_results=2
    )

REST API

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

쿼리에서 재랜커 사용

에이전트 성능은 쿼리에 가장 관련된 정보를 검색하는 데 따라 달라집니다. 재배열은 검색 결과 문서를 평가하여 의미상 가장 관련성이 큰 문서를 식별함으로써 검색 결과의 품질을 향상시키는 기술입니다. Databricks는 이러한 문서를 식별하는 연구 기반 복합 AI 시스템을 개발했습니다. 또한 각 문서의 관련성을 평가할 때 재전송자가 추가 컨텍스트에 사용할 메타데이터가 포함된 열을 지정할 수도 있습니다.

재전송은 짧은 대기 시간 지연을 발생하지만 검색 품질 및 에이전트 성능을 크게 향상시킬 수 있습니다. Databricks는 RAG 에이전트 사용 사례에 대해 재정렬을 시도하는 것을 추천합니다.

이 섹션의 예제에서는 벡터 검색 재정렬기를 사용하는 방법을 보여 줍니다. 재랜커를 사용하는 경우 반환할 열() 및 다시 실행(columnscolumns_to_rerank)에 사용할 메타데이터 열을 별도로 설정합니다. num_results 는 반환할 최종 결과 수입니다. 이는 재랜킹에 사용되는 결과 수에 영향을 주지 않습니다.

쿼리 디버그 메시지에는 재랜킹 단계가 소요된 기간에 대한 정보가 포함됩니다. 다음은 그 예입니다.

'debug_info': {'response_time': 1647.0, 'ann_time': 29.0, 'reranker_time': 1573.0}

리랭커 호출이 실패하면 해당 정보가 디버그 메시지에 포함됩니다.

'debug_info': {'response_time': 587.0, 'ann_time': 331.0, 'reranker_time': 246.0, 'warnings': [{'status_code': 'RERANKER_TEMPORARILY_UNAVAILABLE', 'message': 'The reranker is temporarily unavailable. Results returned have not been processed by the reranker. Please try again later for reranked results.'}]}

Python SDK

# Install the most recent version.
# Databricks SDK version 0.57 or above is required to use the reranker.
%pip install databricks-vectorsearch --force-reinstall
dbutils.library.restartPython()

from databricks.vector_search.reranker import DatabricksReranker

results = index.similarity_search(
    query_text = "How to create a Vector Search index",
    columns = ["id", "text", "parent_doc_summary", "date"],
    num_results = 10,
    query_type = "hybrid",
    reranker=DatabricksReranker(columns_to_rerank=["text", "parent_doc_summary", "other_column"])
    )

REST API

대기 시간 정보를 얻으려면 1 이상으로 설정합니다 debug_level .

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

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": 10, "query_text": "How to create a Vector Search index", "columns": ["id", "text", "parent_doc_summary", "date"], "reranker": {"model": "databricks_reranker",
             "parameters": {
               "columns_to_rerank":
                 ["text", "parent_doc_summary"]
              }
             },
"debug_level": 1}'

지점 조회

지점 조회를 수행하려면 기본 키 열에 필터를 사용합니다.

검색 알고리즘

이 섹션에서는 다양한 검색 알고리즘 또는 쿼리 유형과 각 검색 알고리즘을 사용할 수 있는 시기에 대해 설명합니다. 매개 변수를 query_type 사용하여 사용할 검색 알고리즘을 지정합니다. 인덱스에 대한 다양한 알고리즘의 성능을 자동으로 비교하려면 평가 벡터 검색 검색 품질을 참조하세요.

ANN(벡터 검색)

ANN 검색은 쿼리를 벡터 포함으로 변환하고 포함이 가장 유사한 문서를 찾습니다. 이는 의미를 이해하는 데 효과적입니다. 예를 들어 "고장난 파이프를 수정하는 방법"이라는 쿼리는 정확한 단어가 없는 경우에도 배관에 대한 문서와 일치합니다.

• ANN이 잘 수행되는 경우: 쿼리는 개념적이거나 대화형이거나 문서와 다른 어휘를 사용합니다.
• ANN의 성능이 저하될 수 있는 경우: 쿼리가 정확한 키워드, 고유 명사, 또는 임베딩이 정확하게 캡처하지 못할 수 있는 도메인별 용어에 의존하는 경우.

전체 텍스트(키워드 검색)

전체 텍스트 검색은 쿼리 용어를 포함하는 문서와 일치합니다. 전체 텍스트 검색은 정밀도가 높습니다. 사용자가 특정 이름, 코드 또는 기술 용어를 검색할 때, 키워드 일치는 벡터 검색에서 놓칠 수 있는 정확한 일치 항목을 정확히 찾아냅니다.

• 전체 텍스트가 잘 수행되는 경우: 쿼리에는 특정 식별자, 제품 이름, 오류 코드 또는 도메인별 용어가 포함됩니다.
• 전체 텍스트의 성능이 저하될 수 있는 경우: 쿼리는 문서와 다르게 표현되거나 동의어 및 매개 변수를 사용합니다.

하이브리드 검색

하이브리드 검색은 ANN 및 전체 텍스트 검색을 병렬로 실행한 다음 RRF(상호 순위 Fusion)를 사용하여 결과를 병합합니다. 이는 벡터 검색의 의미 체계 이해와 키워드 일치의 정밀도를 결합합니다.

• 하이브리드 검색이 잘 수행되는 경우: 쿼리 워크로드는 개념적 쿼리와 키워드가 많은 쿼리의 조합입니다. 하이브리드는 가장 강력한 범용 전략입니다.

재정렬기

리랭커는 모든 전략 위에 적용되는 선택적인 두 번째 단계입니다. 초기 검색 후 크로스 인코더 모델은 쿼리 컨텍스트에서 각 결과를 다시 평가하여 보다 정확한 관련성 순서를 생성합니다.

재정렬기는 일반적으로 약 10% 품질을 향상시키지만 지연 시간을 초래합니다. RAG 챗봇과 같이 품질이 가장 중요하지만 처리량이 높고 대기 시간이 짧은 검색 애플리케이션에는 적합하지 않은 애플리케이션에 적합합니다.