Vektör arama dizini oluşturma ve sorgulama

Bu makalede Mozaik AI Vektör Araması kullanarak vektör arama dizini oluşturma ve sorgulama işlemleri açıklanmaktadır.

Kullanıcı arabirimini, Python SDK'sını veya REST API'yi kullanarak vektör arama uç noktası ve vektör arama dizinleri gibi vektör arama bileşenleri oluşturabilir ve yönetebilirsiniz.

Gereksinimler

• Unity Kataloğu etkin çalışma alanı.
• Sunucusuz işlem etkinleştirildi. Yönergeler için bkz . Sunucusuz işlemle bağlantı kurma.
• Kaynak tabloda Veri Akışını Değiştir etkinleştirilmelidir. Yönergeler için bkz . Azure Databricks'te Delta Lake değişiklik veri akışını kullanma.
• Dizin oluşturmak için, dizin oluşturmak için katalog şemalarında CREATE TABLE ayrıcalıklarına sahip olmanız gerekir. Başka bir kullanıcıya ait bir dizini sorgulamak için ek ayrıcalıklara sahip olmanız gerekir. Bkz. Vektör arama uç noktasını sorgulama.
• Kişisel erişim belirteçlerini kullanmak istiyorsanız (üretim iş yükleri için önerilmez), Kişisel erişim belirteçlerinin etkinleştirilip etkinleştirilmediğini denetleyin. Bunun yerine hizmet sorumlusu belirtecini kullanmak için SDK veya API çağrılarını kullanarak bunu açıkça geçirin.

SDK'yı kullanmak için not defterinize yüklemeniz gerekir. Aşağıdaki kodu kullanın:

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

Vektör arama uç noktası oluşturma

Databricks kullanıcı arabirimini, Python SDK'sını veya API'yi kullanarak vektör arama uç noktası oluşturabilirsiniz.

Kullanıcı arabirimini kullanarak vektör arama uç noktası oluşturma

Kullanıcı arabirimini kullanarak vektör arama uç noktası oluşturmak için bu adımları izleyin.

1. Sol kenar çubuğunda İşlem'e tıklayın.

2. Vektör Arama sekmesine tıklayın ve Oluştur'a tıklayın.

   

3. Uç nokta oluştur formu açılır. Bu uç nokta için bir ad girin.

4. Onayla'yı tıklatın.

Python SDK'sını kullanarak vektör arama uç noktası oluşturma

Aşağıdaki örnekte vektör arama uç noktası oluşturmak için create_endpoint() SDK işlevi kullanılmaktadır.

# 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 kullanarak vektör arama uç noktası oluşturma

REST API başvuru belgelerine bakın: POST /api/2.0/vector-search/endpoints.

(İsteğe bağlı) Ekleme modeline hizmet vermek için uç nokta oluşturma ve yapılandırma

Databricks'in eklemeleri hesaplamasını seçerseniz, önceden yapılandırılmış bir Temel Model API'leri uç noktasını kullanabilir veya tercih ettiğiniz ekleme modeline hizmet vermek için uç nokta sunan bir model oluşturabilirsiniz. Yönergeler için bkz. Belirteç başına ödeme temel modeli API'leri veya Uç noktaları sunan üretken yapay zeka modeli oluşturma. Örneğin not defterleri için bkz . Ekleme modelini çağırmak için not defteri örnekleri.

Bir ekleme uç noktasını yapılandırdığınızda Databricks, varsayılan Sıfıra ölçeklendir seçimini kaldırmanızı önerir. Hizmet veren uç noktaların ısınması birkaç dakika sürebilir ve ölçeği azaltılmış uç noktaya sahip bir dizindeki ilk sorgu zaman aşımına neden olabilir.

Not

Ekleme uç noktası veri kümesi için uygun şekilde yapılandırılmamışsa vektör arama dizini başlatma zaman aşımına neden olabilir. Cpu uç noktalarını yalnızca küçük veri kümeleri ve testler için kullanmanız gerekir. Daha büyük veri kümeleri için en iyi performans için bir GPU uç noktası kullanın.

Vektör arama dizini oluşturma

Kullanıcı arabirimini, Python SDK'sını veya REST API'yi kullanarak vektör arama dizini oluşturabilirsiniz. Kullanıcı arabirimi en basit yaklaşımdır.

İki tür dizin vardır:

• Delta Eşitleme Dizini , delta tablosundaki temel veriler değiştikçe dizini otomatik olarak ve artımlı olarak güncelleştirerek kaynak Delta Tablosu ile otomatik olarak eşitlenir.
• Doğrudan Vektör Erişim Dizini , vektörlerin ve meta verilerin doğrudan okunmasını ve yazmasını destekler. Kullanıcı, REST API veya Python SDK'sını kullanarak bu tabloyu güncelleştirmekle sorumludur. Bu dizin türü kullanıcı arabirimi kullanılarak oluşturulamaz. REST API'sini veya SDK'sını kullanmanız gerekir.

Kullanıcı arabirimini kullanarak dizin oluşturma

1. Sol kenar çubuğunda Katalog'a tıklayarak Katalog Gezgini kullanıcı arabirimini açın.

2. Kullanmak istediğiniz Delta tablosuna gidin.

3. Sağ üst köşede bulunan Oluştur düğmesine tıklayın ve açılan menüden Vektör arama dizini'ni seçin.

   

4. dizini yapılandırmak için iletişim kutusundaki seçicileri kullanın.

   

   Ad: Unity Kataloğu'ndaki çevrimiçi tablo için kullanılacak ad. Ad için üç düzeyli bir ad alanı gerekir: <catalog>.<schema>.<name>. Yalnızca alfasayısal karakterlere ve alt çizgilere izin verilir.

   Birincil anahtar: Birincil anahtar olarak kullanılacak sütun.

   Uç nokta: Kullanmak istediğiniz vektör arama uç noktasını seçin.

   Eşitlenecek sütunlar: Vektör diziniyle eşitlenecek sütunları seçin. Bu alanı boş bırakırsanız, kaynak tablodaki tüm sütunlar dizinle eşitlenir. Birincil anahtar sütunu ve ekleme kaynak sütunu veya ekleme vektör sütunu her zaman eşitlenir.

   Ekleme kaynağı: Databricks'in Delta tablosundaki bir metin sütunu için eklemeleri hesaplamasını isteyip istemediğinizi (İşlem eklemeleri) veya Delta tablonuzun önceden derlenmiş eklemeler içerip içermediğini belirtin (Mevcut ekleme sütununu kullanın).

   • İşlem eklemeleri'ni seçtiyseniz, ekleme işleminin hesaplanmasını istediğiniz sütunu ve ekleme modeline hizmet veren uç noktayı seçin. Yalnızca metin sütunları desteklenir.
   • Var olan ekleme sütununu kullan'ı seçtiyseniz, önceden derlenmiş eklemeleri ve ekleme boyutunu içeren sütunu seçin. Önceden derlenmiş ekleme sütununun biçimi olmalıdır array[float].

   Hesaplanan eklemeleri eşitle: Oluşturulan eklemeleri bir Unity Kataloğu tablosuna kaydetmek için bu ayarı değiştirin. Daha fazla bilgi için bkz . Oluşturulan ekleme tablosunu kaydetme.

   Eşitleme modu: Sürekli , dizini saniyeler boyunca gecikme süresiyle eşitlenmiş durumda tutar. Ancak, sürekli eşitleme akışı işlem hattını çalıştırmak için bir işlem kümesi sağlandığından onunla ilişkili maliyeti daha yüksektir. Hem Sürekli hem de Tetiklenen için güncelleştirme artımlı olur; yalnızca son eşitleme işlendiğinden bu yana değişen verilerdir.

   Tetiklenen eşitleme modu ile, eşitlemeyi başlatmak için Python SDK'sını veya REST API'yi kullanırsınız. Bkz. Delta Eşitleme Dizinini Güncelleştirme.

5. Dizini yapılandırmayı bitirdiğinizde Oluştur'a tıklayın.

Python SDK'sını kullanarak dizin oluşturma

Aşağıdaki örnek, Databricks tarafından hesaplanan eklemelerle bir Delta Eşitleme Dizini oluşturur.

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

Aşağıdaki örnek, kendi kendine yönetilen eklemelerle bir Delta Eşitleme Dizini oluşturur. Bu örnek, dizinde kullanılacak sütunların yalnızca bir alt kümesini seçmek için isteğe bağlı parametresinin columns_to_sync kullanımını da gösterir.

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

Varsayılan olarak, kaynak tablodaki tüm sütunlar dizinle eşitlenir. Sütunların yalnızca bir alt kümesini eşitlemek için kullanın columns_to_sync. Birincil anahtar ve ekleme sütunları her zaman dizine eklenir.

Yalnızca birincil anahtarı ve ekleme sütununu eşitlemek için, bunları gösterildiği gibi içinde columns_to_sync belirtmeniz gerekir:

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

Ek sütunları eşitlemek için bunları gösterildiği gibi belirtin. Her zaman eşitlendikleri için birincil anahtarı ve ekleme sütununu eklemeniz gerekmez.

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

Aşağıdaki örnek bir Doğrudan Vektör Erişim Dizini oluşturur.

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": "str",
    "field3": "float",
    "text_vector": "array<float>"}
)

REST API kullanarak dizin oluşturma

REST API başvuru belgelerine bakın: POST /api/2.0/vector-search/indexes.

Oluşturulan ekleme tablosunu kaydetme

Databricks eklemeleri oluşturursa, oluşturulan eklemeleri Unity Kataloğu'ndaki bir tabloya kaydedebilirsiniz. Bu tablo vektör diziniyle aynı şemada oluşturulur ve vektör dizini sayfasından bağlanır.

Tablonun adı, tarafından _writeback_tableeklenen vektör arama dizininin adıdır. Ad düzenlenemez.

Unity Kataloğu'ndaki diğer tablolarda olduğu gibi tabloya erişebilir ve tabloya sorgulayabilirsiniz. Ancak, el ile güncelleştirilmesi amaçlanmadığından tabloyu bırakmamalı veya değiştirmemelisiniz. Dizin silinirse tablo otomatik olarak silinir.

Vektör arama dizinini güncelleştirme

Delta Eşitleme Dizinini Güncelleştirme

Sürekli eşitleme moduyla oluşturulan dizinler, kaynak Delta tablosu değiştiğinde otomatik olarak güncelleştirilir. Tetiklenen eşitleme modunu kullanıyorsanız eşitlemeyi başlatmak için Python SDK'sını veya REST API'yi kullanın.

Python SDK'sı

index.sync()

REST API

REST API başvuru belgelerine bakın: POST /api/2.0/vector-search/indexes/{index_name}/sync.

Doğrudan Vektör Erişim Dizinini Güncelleştirme

Doğrudan Vektör Erişim Dizini'nden veri eklemek, güncelleştirmek veya silmek için Python SDK'sını veya REST API'yi kullanabilirsiniz.

Python SDK'sı

   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 başvuru belgelerine bakın: POST /api/2.0/vector-search/indexes.

Aşağıdaki kod örneği, kişisel erişim belirteci (PAT) kullanarak dizini güncelleştirme işlemini gösterir.

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": [...]}'

Aşağıdaki kod örneği, hizmet sorumlusu kullanarak dizini güncelleştirme işlemini gösterir.

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": [...]}'

Vektör arama uç noktasını sorgulama

Vektör arama uç noktasını yalnızca Python SDK'sını, REST API'yi veya SQL vector_search() AI işlevini kullanarak sorgulayabilirsiniz.

Not

Uç noktayı sorgulayan kullanıcı vektör arama dizininin sahibi değilse, kullanıcının aşağıdaki UC ayrıcalıklarına sahip olması gerekir:

• Katalogda vektör arama dizinini içeren KATALOĞU KULLANIN.
• Vektör arama dizinini içeren şemada SCHEMA kullanın.
• Vektör arama dizininde SELECT.

Karma anahtar sözcük benzerliği araması yapmak için parametresini query_type olarak hybridayarlayın. Varsayılan değerdir ann (yaklaşık en yakın komşu).

Python SDK'sı

# 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 başvuru belgelerine bakın: POST /api/2.0/vector-search/indexes/{index_name}/query.

Aşağıdaki kod örneği, kişisel erişim belirteci (PAT) kullanarak dizini sorgulamayı gösterir.

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

Aşağıdaki kod örneği, hizmet sorumlusu kullanarak dizini sorgulamayı gösterir.

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

Önemli

AI vector_search() işlevi Genel Önizleme aşamasındadır.

Bu yapay zeka işlevini kullanmak için bkz . vector_search işlevi.

Sorgularda filtre kullanma

Sorgu, Delta tablosundaki herhangi bir sütunu temel alan filtreler tanımlayabilir. similarity_search yalnızca belirtilen filtrelerle eşleşen satırları döndürür. Aşağıdaki filtreler desteklenir:

Filtre işleci	Davranış	Örnekler
NOT	Filtreyi olumsuzlar. Anahtar "DEĞİl" ile bitmelidir. Örneğin, "kırmızı" değerine sahip "RENK DEĞİl" değeri, rengin kırmızı olmadığı belgelerle eşleşir.	{"id NOT": 2} {“color NOT”: “red”}
<	Alan değerinin filtre değerinden küçük olup olmadığını denetler. Anahtar " " <ile bitmelidir. Örneğin, değeri 200 olan "fiyat <", fiyatın 200'den küçük olduğu belgelerle eşleşir.	{"id <": 200}
<=	Alan değerinin filtre değerinden küçük veya buna eşit olup olmadığını denetler. Anahtar " =" <ile bitmelidir. Örneğin, 200 değerine sahip "price <=" değeri, fiyatın 200'den küçük veya buna eşit olduğu belgelerle eşleşir.	{"id <=": 200}
>	Alan değerinin filtre değerinden büyük olup olmadığını denetler. Anahtar " " >ile bitmelidir. Örneğin, değeri 200 olan "fiyat >", fiyatın 200'den büyük olduğu belgelerle eşleşir.	{"id >": 200}
>=	Alan değerinin filtre değerinden büyük veya buna eşit olup olmadığını denetler. Anahtar " =" >ile bitmelidir. Örneğin, 200 değerine sahip "price >=" değeri, fiyatın 200'den büyük veya buna eşit olduğu belgelerle eşleşir.	{"id >=": 200}
OR	Alan değerinin filtre değerlerinden herhangi biri ile eşleşip eşleşmediğini denetler. Anahtarın birden çok alt anahtarı ayırmak için içermesi OR gerekir. Örneğin, color1 OR color2 değeri ["red", "blue"] ile veya olan red color1 color2 belgelerle eşleşirblue.	{"color1 OR color2": ["red", "blue"]}
LIKE	Kısmi dizelerle eşleşir.	{"column LIKE": "hello"}
Filtre işleci belirtilmedi	Filtre tam eşleşmeyi denetler. Birden çok değer belirtilirse, değerlerden herhangi biri ile eşleşir.	{"id": 200} {"id": [200, 300]}

Aşağıdaki kod örneklerine bakın:

Python SDK'sı

# 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

Bkz . POST /api/2.0/vector-search/indexes/{index_name}/query.

Örnek not defterleri

Bu bölümdeki örneklerde vektör arama Python SDK'sının kullanımı gösterilmektedir.

LangChain örnekleri

LangChain paketleriyle tümleştirmede Mozaik AI Vektör Arama özelliğini kullanmak için bkz . Mozaik AI Vektör Araması ile LangChain'i kullanma.

Aşağıdaki not defterinde benzerlik arama sonuçlarınızı LangChain belgelerine nasıl dönüştürdüğünüz gösterilmektedir.

Python SDK not defteriyle vektör araması

Not defterini alma

Ekleme modelini çağırmak için not defteri örnekleri

Aşağıdaki not defterleri, ekleme oluşturma için Mozaik Yapay Zeka Modeli Sunma uç noktasının nasıl yapılandırıldığını gösterir.

Mozaik AI Modeli Sunma not defterini kullanarak OpenAI ekleme modelini çağırma

Not defterini alma

Mozaik AI Modeli Sunma not defterini kullanarak GTE ekleme modelini çağırma

Not defterini alma

İşletim sistemi ekleme modeli not defterini kaydetme ve sunma

Not defterini alma