Создание и запрос индекса векторного поиска

В этой статье описывается, как создать и запросить векторный индекс поиска векторов с помощью векторного поиска Мозаики ИИ.

Вы можете создавать и управлять компонентами векторного поиска, такими как конечная точка векторного поиска и индексы векторного поиска, с помощью пользовательского интерфейса, пакета SDK Python или REST API.

Требования

• Рабочая область с поддержкой каталога Unity.
• Бессерверные вычисления включены. Инструкции см. в разделе "Подключение к бессерверным вычислениям".
• Исходная таблица должна быть включена в канале измененных данных. Инструкции см. в разделе "Использование веб-канала изменений Delta Lake" в Azure Databricks.
• Чтобы создать индекс, необходимо иметь права CREATE TABLE для схем каталога для создания индексов. Чтобы запросить индекс, принадлежащий другому пользователю, необходимо иметь дополнительные привилегии. См. статью "Запрос конечной точки векторного поиска".
• Если вы хотите использовать личные маркеры доступа (не рекомендуется для рабочих нагрузок), проверьте, включены ли личные маркеры доступа. Чтобы использовать токен субъекта-службы, передайте его явным образом с помощью вызовов ПАКЕТА SDK или API.

Чтобы использовать пакет SDK, необходимо установить его в записную книжку. Используйте следующий код:

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

Создание конечной точки векторного поиска

Вы можете создать конечную точку векторного поиска с помощью пользовательского интерфейса Databricks, пакета SDK для Python или API.

Создание конечной точки векторного поиска с помощью пользовательского интерфейса

Выполните следующие действия, чтобы создать конечную точку векторного поиска с помощью пользовательского интерфейса.

1. На левой боковой панели щелкните " Вычисления".

2. Щелкните вкладку "Векторный поиск " и нажмите кнопку "Создать".

   

3. Откроется форма создания конечной точки. Введите имя этой конечной точки.

4. Нажмите кнопку Подтвердить.

Создание конечной точки векторного поиска с помощью пакета SDK для Python

В следующем примере функция ПАКЕТА SDK create_endpoint() используется для создания конечной точки векторного поиска.

# The following line automatically generates a PAT Token for authentication
client = VectorSearchClient()

# The following line uses the service principal token for authentication
# client = VectorSearch(service_principal_client_id=<CLIENT_ID>,service_principal_client_secret=<CLIENT_SECRET>)

client.create_endpoint(
    name="vector_search_endpoint_name",
    endpoint_type="STANDARD"
)

Создание конечной точки векторного поиска с помощью REST API

См. справочную документацию по REST API: POST /api/2.0/vector-search/endpoints.

(Необязательно) Создание и настройка конечной точки для обслуживания модели внедрения

Если вы решили вычислить внедрение Databricks, можно использовать предварительно настроенную конечную точку API-интерфейсов модели Foundation или создать конечную точку обслуживания модели для обслуживания выбранной модели внедрения. Инструкции см . в API-интерфейсах модели модели модели для модели создания оплаты за токен или создании модели создания модели ИИ, обслуживающей конечные точки. Примеры записных книжек см . в примерах для вызова модели внедрения записных книжек.

При настройке конечной точки внедрения Databricks рекомендует удалить выбор по умолчанию масштабирования до нуля. Время ожидания конечных точек обслуживания может занять несколько минут, а начальный запрос в индексе с горизонтально масштабируемой конечной точкой может занять некоторое время ожидания.

Создание индекса векторного поиска

Индекс векторного поиска можно создать с помощью пользовательского интерфейса, пакета SDK Для Python или REST API. Пользовательский интерфейс — это самый простой подход.

Существует два типа индексов:

• Индекс разностной синхронизации автоматически синхронизируется с исходной таблицей Delta, автоматически и добавочно обновляя индекс в виде базовых данных в разностной таблице.
• Индекс прямого векторного доступа поддерживает прямое чтение и запись векторов и метаданных. Пользователь отвечает за обновление этой таблицы с помощью REST API или пакета SDK для Python. Этот тип индекса нельзя создать с помощью пользовательского интерфейса. Необходимо использовать REST API или пакет SDK.

Создание индекса с помощью пользовательского интерфейса

1. На левой боковой панели щелкните "Каталог ", чтобы открыть пользовательский интерфейс обозревателя каталогов.

2. Перейдите к таблице Delta, которую вы хотите использовать.

3. Нажмите кнопку "Создать" в правом верхнем углу и выберите индекс векторного поиска в раскрывающемся меню.

   

4. Используйте селекторы в диалоговом окне для настройки индекса.

   

   Имя: имя, используемое для интерактивной таблицы в каталоге Unity. Для имени требуется трехуровневое пространство <catalog>.<schema>.<name>имен. Разрешены только буквенно-цифровые символы и символы подчеркивания.

   Первичный ключ: столбец для использования в качестве первичного ключа.

   Конечная точка. Выберите конечную точку поиска векторов, которую вы хотите использовать.

   Столбцы для синхронизации: выберите столбцы для синхронизации с векторным индексом. Если оставить это поле пустым, все столбцы из исходной таблицы синхронизируются с индексом. Столбец первичного ключа и внедрение исходного столбца или встраиваемого векторного столбца всегда синхронизируются.

   Источник внедрения. Укажите, требуется ли Databricks вычислить внедренные данные для текстового столбца в таблице Delta (внедрение вычислений) или если таблица Delta содержит предварительно компьютированные внедренные столбцы (используйте существующий столбец внедрения).

   • Если вы выбрали внедрение вычислений, выберите столбец, для которого вы хотите внедрить данные, и конечную точку, обслуживающую модель внедрения. Поддерживаются только текстовые столбцы.
   • При выборе "Использовать существующий столбец внедрения", выберите столбец, содержащий предварительно компьютерированные вставки и измерение внедрения. Должен быть array[float]формат предварительно вычисляемого столбца внедрения.

   Синхронизация вычисляемых внедрения: переключите этот параметр, чтобы сохранить созданные внедрения в таблицу каталога Unity. Дополнительные сведения см. в статье "Сохранить созданную таблицу внедрения".

   Режим синхронизации: непрерывный режим сохраняет индекс в синхронизации с секундами задержки. Однако она имеет более высокую стоимость, так как вычислительный кластер подготавливается для запуска конвейера потоковой передачи непрерывной синхронизации. Для непрерывного и триггерного обновления обновление является добавочным — только данные, которые изменились с момента последней синхронизации.

   В режиме синхронизации с активацией вы используете пакет SDK для Python или REST API для запуска синхронизации. См. раздел "Обновление индекса разностной синхронизации".

5. Завершив настройку индекса, нажмите кнопку "Создать".

Создание индекса с помощью пакета SDK для Python

В следующем примере создается индекс разностной синхронизации с внедрением, вычисляемыми Databricks.

client = VectorSearchClient()

index = client.create_delta_sync_index(
  endpoint_name="vector_search_demo_endpoint",
  source_table_name="vector_search_demo.vector_search.en_wiki",
  index_name="vector_search_demo.vector_search.en_wiki_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  embedding_source_column="text",
  embedding_model_endpoint_name="e5-small-v2"
)

В следующем примере создается индекс разностной синхронизации с самоуправляемыми внедрениями. В этом примере также показано использование необязательного параметра columns_to_sync для выбора только подмножества столбцов, используемых в индексе.

client = VectorSearchClient()

index = client.create_delta_sync_index(
  endpoint_name="vector_search_demo_endpoint",
  source_table_name="vector_search_demo.vector_search.en_wiki",
  index_name="vector_search_demo.vector_search.en_wiki_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  embedding_dimension=1024,
  embedding_vector_column="text_vector"
)

По умолчанию все столбцы из исходной таблицы синхронизируются с индексом. Чтобы синхронизировать только подмножество столбцов, используйте columns_to_sync. Первичный ключ и столбцы внедрения всегда включаются в индекс.

Чтобы синхронизировать только первичный ключ и столбец внедрения, необходимо указать их, columns_to_sync как показано ниже.

index = client.create_delta_sync_index(
  ...
  columns_to_sync=["id", "text_vector"] # to sync only the primary key and the embedding column
)

Чтобы синхронизировать дополнительные столбцы, укажите их, как показано ниже. Не нужно включать первичный ключ и столбец внедрения, так как они всегда синхронизируются.

index = client.create_delta_sync_index(
  ...
  columns_to_sync=["revisionId", "text"] # to sync the `revisionId` and `text` columns in addition to the primary key and embedding column.
)

В следующем примере создается индекс прямого векторного доступа.

client = VectorSearchClient()

index = client.create_direct_access_index(
  endpoint_name="storage_endpoint",
  index_name="{catalog_name}.{schema_name}.{index_name}",
  primary_key="id",
  embedding_dimension=1024,
  embedding_vector_column="text_vector",
  schema={
    "id": "int",
    "field2": "string",
    "field3": "float",
    "text_vector": "array<float>"}
)

Создание индекса с помощью REST API

См. справочную документацию по REST API: POST /api/2.0/vector-search/indexes.

Сохранение созданной таблицы внедрения

Если Databricks создает встраиваемые элементы, можно сохранить созданные внедрения в таблицу в каталоге Unity. Эта таблица создается в той же схеме, что и векторный индекс и связана с страницей векторного индекса.

Имя таблицы — это имя индекса векторного поиска, добавленного _writeback_table. Имя не редактируется.

Вы можете получить доступ и запросить таблицу, как и любую другую таблицу в каталоге Unity. Однако не следует удалять или изменять таблицу, так как она не предназначена для обновления вручную. Таблица удаляется автоматически, если индекс удаляется.

Обновление индекса векторного поиска

Обновление индекса разностной синхронизации

Индексы, созданные с помощью режима непрерывной синхронизации, автоматически обновляются при изменении исходной таблицы Delta. Если вы используете режим синхронизации с активацией , используйте пакет SDK Python или REST API для запуска синхронизации.

Пакет SDK для Python

index.sync()

REST API

См. справочную документацию по REST API: POST /api/2.0/vector-search/indexes/{index_name}/sync.

Обновление индекса прямого векторного доступа

Пакет SDK для Python или REST API можно использовать для вставки, обновления или удаления данных из индекса прямого векторного доступа.

Пакет SDK для Python

   index.upsert([{"id": 1,
       "field2": "value2",
       "field3": 3.0,
       "text_vector": [1.0, 2.0, 3.0]
       },
       {"id": 2,
        "field2": "value2",
        "field3": 3.0,
        "text_vector": [1.1, 2.1, 3.0]
        }
        ])

REST API

См. справочную документацию по REST API: POST /api/2.0/vector-search/indexes.

В следующем примере кода показано, как обновить индекс с помощью личного маркера доступа (PAT).

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

# Upsert data into Vector Search index.
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/upsert-data --data '{"inputs_json": "..."}'

# Delete data from Vector Search index
curl -X DELETE -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/delete-data --data '{"primary_keys": [...]}'

В следующем примере кода показано, как обновить индекс с помощью субъекта-службы.

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": "WriteVectorIndex"}'

# 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 '"')

# Upsert data into Vector Search index.
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/upsert-data --data '{"inputs_json": "[...]"}'

# Delete data from Vector Search index
curl -X DELETE -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/delete-data --data '{"primary_keys": [...]}'

Запрос конечной точки векторного поиска

Вы можете запрашивать только конечную точку векторного поиска с помощью пакета SDK для Python, REST API или функции ИИ SQL vector_search() .

Чтобы выполнить поиск сходства с гибридными ключевыми словами, задайте для параметра значение query_type hybrid. Значение по умолчанию — приблизительное ann ближайшее соседство.

Пакет SDK для Python

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

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

# Delta Sync Index with pre-calculated embeddings
results2 = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    num_results=2
    )

REST API

См. справочную документацию по REST API: POST /api/2.0/vector-search/indexes/{index_name}/query.

В следующем примере кода показано, как запрашивать индекс с помощью личного маркера доступа (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}'

В следующем примере кода показано, как запросить индекс с помощью субъекта-службы.

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 (TODO: link), 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}'

SQL

Сведения об использовании этой функции ИИ см. в разделе vector_search функции.

Использование фильтров для запросов

Запрос может определять фильтры на основе любого столбца в таблице Delta. similarity_search возвращает только строки, соответствующие указанным фильтрам. Поддерживаются следующие фильтры:

См. следующие примеры кода:

Пакет SDK для Python

# 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
    )

REST API

См. раздел POST /api/2.0/vector-search/indexes/{index_name}/query.

Примеры записных книжек

В примерах этого раздела демонстрируется использование пакета SDK для поиска векторов Python.

Примеры LangChain

Узнайте , как использовать LangChain с векторным поиском вектора мозаики для использования векторного поиска Мозаики ИИ, как в интеграции с пакетами LangChain.

В следующей записной книжке показано, как преобразовать результаты поиска сходства в документы LangChain.

Векторный поиск с помощью записной книжки пакета SDK для Python

Получить записную книжку

Примеры записной книжки для вызова модели внедрения

В следующих записных книжках показано, как настроить конечную точку обслуживания модели ИИ для внедрения.

Вызов модели внедрения OpenAI с помощью записной книжки для обслуживания модели ИИ Для мозаики

Получить записную книжку

Вызов модели внедрения GTE с помощью записной книжки для обслуживания модели ИИ для мозаики

Получить записную книжку

Регистрация и обслуживание записной книжки модели внедрения OSS

Получить записную книжку