다음을 통해 공유

벡터 검색 인덱스 쿼리

이 문서에서는 필터 사용 및 재전송 방법을 포함하여 벡터 검색 인덱스를 쿼리하는 방법을 설명합니다.

벡터 검색 엔드포인트 및 인덱스를 만들고 쿼리하는 방법을 보여 주는 예제 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 함수를 사용하여 벡터 검색 인덱스만 쿼리할 수 있습니다.

비고

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

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

기본 쿼리 유형은 ann (근사값 최근접 이웃)입니다. 하이브리드 키워드 유사성 검색을 수행하려면 매개 변수 query_typehybrid설정합니다. 하이브리드 검색을 사용하면 모든 텍스트 메타데이터 열이 포함되고 최대 200개의 결과가 반환됩니다.

쿼리에서 재랜커를 사용하려면 쿼리 에서 재랜커 사용을 참조하세요.

중요합니다

전체 텍스트 검색은 베타 기능으로 사용할 수 있습니다. 전체 텍스트 검색을 수행하려면 매개 변수 query_typeFULL_TEXT를 .로 설정합니다. 전체 텍스트 검색을 사용하면 벡터 포함을 사용하지 않고 키워드 일치를 기반으로 최대 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

중요합니다

vector_search() AI 기능은 공개 미리보기 상태에 있습니다.

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

쿼리에 필터 사용

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

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

필터 연산자 행동 예시
NOT 표준: 필터를 부정합니다. 키는 "NOT"으로 끝나야 합니다. 예를 들어 값이 "빨강"인 "color NOT"은 색이 빨간색이 아닌 문서와 일치합니다.
스토리지 최적화: (bangeq sign) 연산자 참조!=		 표준: {"id NOT": 2}{“color NOT”: “red”}
스토리지 최적화: "id != 2" "color != 'red'"
< 표준: 필드 값이 필터 값보다 작은지 확인합니다. 키는 "<"로 끝나야 합니다. 예를 들어 값이 200인 "price <"는 가격이 200보다 작은 문서와 일치합니다.
스토리지 최적화: (lt 기호) 연산자 참조<		 표준: {"id <": 200}
스토리지 최적화: "id < 200"
<= 표준: 필드 값이 필터 값보다 작거나 같은지 확인합니다. 키는 "<="로 끝나야 합니다. 예를 들어 값이 200인 "price <="는 가격이 200보다 작거나 같은 문서와 일치합니다.
스토리지 최적화: <= (lt eq sign) 연산자 참조		 표준: {"id <=": 200}
스토리지 최적화: "id <= 200"
> 표준: 필드 값이 필터 값보다 큰지 확인합니다. 키는 ">"로 끝나야 합니다. 예를 들어 값이 200인 "price >"은 가격이 200보다 큰 문서와 일치합니다.
스토리지 최적화: (gt 기호) 연산자 참조>		 표준: {"id >": 200}
스토리지 최적화: "id > 200"
>= 표준: 필드 값이 필터 값보다 크거나 같은지 확인합니다. 키는 ">="로 끝나야 합니다. 예를 들어 값이 200인 "price >="는 가격이 200보다 크거나 같은 문서와 일치합니다.
스토리지 최적화: (gt eq sign) 연산자 참조>=		 표준: {"id >=": 200}
스토리지 최적화: "id >= 200"
OR 표준: 필드 값이 필터 값과 일치하는지 확인합니다. 키에는 여러 하위 키를 구분하는 OR 포함되어야 합니다. 예를 들어, 값이 color1 OR color2 인 ["red", "blue"]는 color1가 red이거나 color2가 blue인 문서와 일치합니다.
스토리지 최적화: or 운영자를 참조하세요.		 표준: {"color1 OR color2": ["red", "blue"]}
스토리지 최적화: "color1 = 'red' OR color2 = 'blue'"
LIKE 표준: 문자열에서 공백으로 구분된 토큰과 일치합니다. 아래 코드 예제를 참조하세요.
스토리지 최적화: like 운영자를 참조하세요.		 표준: {"column LIKE": "hello"}
스토리지 최적화: "column LIKE 'hello'"
필터 연산자가 지정되지 않음 표준: 필터가 정확히 일치하는지 확인합니다. 여러 값을 지정하면 값 중 하나와 일치합니다.
스토리지 최적화: (eq sign) 연산자 및 조건자를 참조=하세요.in		 표준: {"id": 200}{"id": [200, 300]}
스토리지 최적화: "id = 200""id IN (200, 300)"
to_timestamp (스토리지 최적화 엔드포인트만 해당) 스토리지 최적화: 타임스탬프를 필터링합니다. to_timestamp 함수 참조 스토리지 최적화: "date > TO_TIMESTAMP('1995-01-01')"

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

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참조하세요.

LIKE

LIKE 예제

{"column LIKE": "apple"}: 문자열 "사과"와 "사과 배"에는 일치하지만 "파인애플"이나 "배"에는 일치하지 않습니다. "pineapple"은 "apple"이라는 부분 문자열을 포함하고 있음에도 불구하고 일치하지 않는다는 점에 유의하세요. 이는 "apple pear"와 같이 공백으로 분리된 토큰에서 정확한 일치를 찾습니다.

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

쿼리에서 재랜커 사용

에이전트 성능은 쿼리에 가장 관련된 정보를 검색하는 데 따라 달라집니다. 재전송은 검색된 문서를 평가하여 의미상 가장 관련성이 큰 문서를 식별하여 검색 품질을 향상시키는 기술입니다. 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.'}]}

비고

열이 나열되는 columns_to_rerank 순서가 중요합니다. 재랜킹 계산은 열이 나열된 순서대로 사용되며 처음 2000자만 고려합니다.

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}'

지점 조회

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

  • Last updated on