将 AI 搜索索引资源添加到 Databricks 应用

将 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 搜索索引添加为资源之前,请查看 应用资源先决条件。

  1. 在创建或编辑应用时,在 “应用资源 ”部分中,单击“ + 添加资源>矢量搜索索引”。
  2. 从工作区中的可用索引中选择 AI 搜索索引。 索引必须已存在于 Unity 目录中。
  3. 选择应用的权限级别:
    • 可以选择: 授予应用查询 AI 搜索索引以查找相似性搜索的权限。 对应于 SELECT 特权。
  4. (可选)指定自定义资源键,即在应用配置中引用索引的方式。 默认键为 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 秒轮询一次,如果索引离线或超过超时时间,则会报错。