将 AI 搜索索引 添加为 Databricks Apps 资源,以便在应用程序中启用语义搜索和基于相似性的检索。 AI 搜索索引存储和查询高维矢量嵌入,为用例提供支持,例如检索扩充生成(RAG)、语义搜索和建议系统。
Databricks AI 搜索以前称为 Databricks 矢量搜索。
特权要求
若要访问 AI 搜索索引,应用的服务主体必须具有 USE CATALOG 父目录、 USE SCHEMA 父架构特权和 SELECT 索引特权。 添加索引资源时,Azure Databricks会自动向应用的服务主体授予这些权限。
要使此自动授予成功,对于每个权限,以下条件之一必须为真:
-
对于
USE CATALOG: 所有帐户用户都对目录具有USE CATALOG权限,或者你对目录具有MANAGE特权。 -
对于
USE SCHEMA: 所有帐户用户都对架构具有USE SCHEMA权限,或者你对架构拥有MANAGE权限。 -
对于
SELECT: 所有帐户用户都对索引具有SELECT权限,或者你对索引具有MANAGE特权。
如果索引在预配吞吐量或自定义服务终结点上使用 Databricks 托管嵌入模型,还需将该终结点作为应用资源添加,并授予可以查询权限,同时添加任何单独的查询嵌入终结点 (model_endpoint_name_for_query)。
get_index() 读取这些端点,且在无访问权限的情况下失败。 按令牌计费的基础模型 API 终结点(例如 databricks-gte-large-en)不需要应用资源,除非你的帐户通过 Unity Catalog 权限限制基础模型;在这种情况下,服务主体需要拥有该模型的 EXECUTE 权限。 参见 设置服务主体。
有关使用这些权限查询 AI 搜索索引的详细信息,请参阅 如何查询 AI 搜索索引。
请参阅 Unity Catalog 权限参考。
添加 AI 搜索索引资源
在将 AI 搜索索引添加为资源之前,请查看 应用资源先决条件。
- 在创建或编辑应用时,在 “应用资源 ”部分中,单击“ + 添加资源>矢量搜索索引”。
- 从工作区中的可用索引中选择 AI 搜索索引。 索引必须已存在于 Unity 目录中。
- 选择应用的权限级别:
- 可以选择: 授予应用查询 AI 搜索索引以查找相似性搜索的权限。 对应于 SELECT 特权。
- (可选)指定自定义资源键,即在应用配置中引用索引的方式。 默认键为
vector-search-index.
注释
AI 搜索索引是类型为 TABLE_ONLINE_VECTOR_INDEX_REPLICA 或 TABLE_ONLINE_VECTOR_INDEX_DIRECT 的 Unity Catalog 表。 选择 AI 搜索索引时,会选择支持语义搜索操作的专门配置的表。
环境变量
使用 AI Search 索引资源部署应用时,Azure Databricks 会通过环境变量提供完整的三级名称,你可以使用 valueFrom 字段来引用该名称。
示例配置:
env:
- name: VECTOR_SEARCH_INDEX
valueFrom: vector-search-index # Use your custom resource key if different
在应用程序中使用索引:
用 databricks-ai-search Python SDK 和应用的服务主体凭证查询索引。 当工作区满足 索引 URL 要求时,SDK 会向索引 URL 发送查询,该索引 URL 可以利用具有目标每秒查询数(QPS)的端点的额外容量。 通过 WorkspaceClient().vector_search_indexes.query_index 发送的查询会使用工作区查询 URL,而该 URL 的上限为几十 QPS。
将 databricks-ai-search 版本 0.81 或更高版本添加到应用的依赖中。 请参阅 管理 Databricks 应用的依赖项。
import os
from databricks.ai_search.client import AISearchClient
# DATABRICKS_HOST can be set without a scheme, and the SDK requires one.
host = os.environ["DATABRICKS_HOST"]
if not host.startswith(("https://", "http://")):
host = f"https://{host}"
# Pass the app's service principal credentials so queries use the index URL.
client = AISearchClient(
workspace_url=host,
service_principal_client_id=os.environ["DATABRICKS_CLIENT_ID"],
service_principal_client_secret=os.environ["DATABRICKS_CLIENT_SECRET"],
)
# Create the index object when the app starts and reuse it for every query.
index = client.get_index(index_name=os.environ["VECTOR_SEARCH_INDEX"])
results = index.similarity_search(
query_text="What is machine learning?", # Or pass query_vector for self-managed embeddings.
columns=["id", "text"],
num_results=10,
)
# Each row lists values in the same order as the manifest columns.
column_names = [column["name"] for column in results["manifest"]["columns"]]
for row in results["result"]["data_array"]:
print(dict(zip(column_names, row)))
用你的索引列替换 columns 。 为了达到更高的吞吐量,可以在标准端点上设置目标QPS。
有关详细信息,请参阅 使用环境变量访问资源。
删除 AI 搜索索引资源
从应用中删除 AI 搜索索引资源时,应用的服务主体将失去对索引的访问权限。 索引本身保持不变,并继续可供具有适当权限的其他用户和应用程序使用。
最佳做法
使用 AI 搜索索引资源时,请考虑以下事项:
- 如果索引引用其他表,请确保应用的服务主体有权访问基础数据源。
- 监视查询性能,并在响应时间下降时调整索引配置或嵌入模型。
- 请考虑索引刷新计划,以保持嵌入与源数据同步。
- 根据嵌入模型使用适当的相似性指标(余弦、euclidean、点积)。
- 端点可以在其索引准备好可供查询之前就已上线。 要检查索引而不阻塞,请读取
index.describe()返回的status字段中的ready和detailed_state。 要等待索引,请调用index.wait_until_ready(),它每 30 秒轮询一次,如果索引离线或超过超时时间,则会报错。