通过

查询矢量搜索索引

本文介绍如何查询矢量搜索索引，包括如何使用筛选器和重新调整。

有关如何创建和查询矢量搜索终结点和索引的示例笔记本，请参阅 矢量搜索示例笔记本。 有关参考信息，请参阅 Python SDK 参考。

Installation

若要使用矢量搜索 SDK，必须在笔记本中安装它。 使用以下代码安装包：

%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_type 设置为 hybrid。 使用混合搜索时，将包含所有文本元数据列，最多返回 200 个结果。

若要在查询中使用重新调用程序，请参阅 在查询中使用重新调用程序。

重要

全文搜索可用作 beta 功能。 若要执行全文搜索，请将参数 query_type 设置为 FULL_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 建议使用服务主体而不是个人访问令牌。 除了增强安全性和访问管理之外，使用服务主体还可以将每个查询的性能提高最多至 100 毫秒。

下面的代码示例演示如何使用服务主体查询索引。

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 函数。

对查询使用筛选器

查询可以根据 Delta 表中的任何列定义筛选器。 similarity_search 仅返回与指定筛选器匹配的行。

下表列出了支持的筛选器。

筛选器运算符 行为 例子
NOT 标准：否定筛选器。 密钥必须以“NOT”结尾。 例如，值为“red”的“color NOT”与颜色不为红色的文档匹配。
存储优化：请参阅 !=（感叹号等于号）运算符。		 标准： {"id NOT": 2}{“color NOT”: “red”}
存储优化： "id != 2" "color != 'red'"
< 标准：检查字段值是否小于筛选器值。 键必须以“ <”结尾。 例如，值为 200 的“price <”与价格小于 200 的文档匹配。
存储优化：请参阅 <（小于号）运算符。		 标准： {"id <": 200}
存储优化： "id < 200"
<= 标准：检查字段值是否小于或等于筛选器值。 密钥必须以“ <=”结尾。 例如，值为 200 的“price <=”与价格小于或等于 200 的文档匹配。
存储优化：请参阅 <=（小于等于号）运算符。		 标准： {"id <=": 200}
存储优化： "id <= 200"
> 标准：检查字段值是否大于筛选器值。 键必须以“ >”结尾。 例如，值为 200 的“price >”与价格大于 200 的文档匹配。
存储优化：请参阅 >（大于号）运算符。		 标准： {"id >": 200}
存储优化： "id > 200"
>= 标准：检查字段值是否大于或等于筛选器值。 密钥必须以“ >=”结尾。 例如，值为 200 的“price >=”与价格大于或等于 200 的文档匹配。
存储优化：请参阅 >=（大于等于号）运算符。		 标准： {"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'"
未指定筛选器运算符 标准：筛选检查是否完全匹配。 如果指定了多个值，则它与任何值匹配。
存储优化：请参阅 =（等号）运算符 和 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"}：与字符串“apple”和“apple pear”匹配，但与“pineapple”或“pear”不匹配。 请注意，即使包含“apple”子字符串，也与“pineapple”不匹配，它查找的是包含空格分隔标记的完全匹配内容，例如“apple pear”。

{"column NOT LIKE": "apple"} 则相反。 它匹配“菠萝”和“梨”，但不匹配“苹果”或“苹果梨”。

在查询中使用重新调用程序

代理性能取决于检索查询的最相关信息。 重新调整是一种技术，通过评估检索的文档来识别语义上最相关的文档，从而提高检索质量。 Databricks 开发了一个基于研究的复合 AI 系统，用于识别这些文档。 还可以指定包含希望重新创建器用于其他上下文的元数据的列，因为它评估每个文档的相关性。

重新调用会产生较小的延迟延迟，但可以显著提高检索质量和代理性能。 Databricks 建议尝试重新调整任何 RAG 代理用例。

本节中的示例演示如何使用矢量搜索重新创建器。 使用重新ranker 时，将列设置为返回（columns）和用于重新调整的元数据列（columns_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

若要确保获得延迟信息，请设置为 debug_level 至少 1。

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