Megosztás a következőn keresztül:

Vektorkeresési index létrehozása és lekérdezése

  • Cikk

Ez a cikk bemutatja, hogyan hozhat létre és kérdezhet le vektorkeresési indexet a Mozaik AI Vector Search használatával.

Vektorkeresési összetevőket, például vektorkeresési végpontot és vektorkeresési indexeket hozhat létre és kezelhet a felhasználói felületen, a Python SDK-val vagy a REST API-val.

Követelmények

  • Unity Catalog-kompatibilis munkaterület.
  • A kiszolgáló nélküli számítás engedélyezve van. Útmutatásért lásd : Csatlakozás kiszolgáló nélküli számításhoz.
  • A forrástáblának engedélyezve kell lennie az Adatcsatorna módosítása funkcióval. Útmutatásért lásd: Delta Lake change data feed on Azure Databricks.
  • Index létrehozásához a katalógusséma(ok)on a CREATE TABLE jogosultságokkal kell rendelkeznie az indexek létrehozásához. Egy másik felhasználó tulajdonában lévő index lekérdezéséhez további jogosultságokkal kell rendelkeznie. Lásd: Vektorkeresési végpont lekérdezése.
  • Ha személyes hozzáférési jogkivonatokat szeretne használni (éles számítási feladatokhoz nem ajánlott), ellenőrizze, hogy engedélyezve vannak-e a személyes hozzáférési jogkivonatok. Ha inkább szolgáltatásnév-jogkivonatot szeretne használni, adja át explicit módon SDK- vagy API-hívások használatával.

Az SDK használatához telepítenie kell azt a jegyzetfüzetbe. Használja a következő kódot:

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

Vektorkeresési végpont létrehozása

Vektorkeresési végpontot a Databricks felhasználói felületén, a Python SDK-val vagy az API-val hozhat létre.

Vektorkeresési végpont létrehozása a felhasználói felületen

Az alábbi lépéseket követve hozzon létre egy vektorkeresési végpontot a felhasználói felületen.

  1. A bal oldali oldalsávon kattintson a Számítás gombra.

  2. Kattintson a Vektorkeresés fülre, majd a Létrehozás gombra.

    Végpontűrlap létrehozása

  3. Megnyílik a Végpont létrehozása űrlap . Adja meg a végpont nevét.

  4. Kattintson a Megerősítés gombra.

Vektorkeresési végpont létrehozása a Python SDK használatával

Az alábbi példa a create_endpoint() SDK függvény használatával hoz létre vektorkeresési végpontot.

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

Vektorkeresési végpont létrehozása a REST API használatával

Tekintse meg a REST API referenciadokumentációját: POST /api/2.0/vector-search/endpoints.

(Nem kötelező) Végpont létrehozása és konfigurálása a beágyazási modell kiszolgálásához

Ha úgy dönt, hogy a Databricks kiszámítja a beágyazásokat, használhat egy előre konfigurált Alapmodell API-végpontot, vagy létrehozhat egy modellt kiszolgáló végpontot a választott beágyazási modell kiszolgálásához. Útmutatásért lásd: Pay-per-token Foundation Model API-k vagy végpontokat kiszolgáló generatív AI-modell létrehozása. Például a jegyzetfüzetek esetében lásd a beágyazási modell meghívására vonatkozó jegyzetfüzet-példákat.

Beágyazási végpont konfigurálásakor a Databricks azt javasolja, hogy távolítsa el a skálázás alapértelmezett beállítását nullára. A végpontok kiszolgálása néhány percet is igénybe vehet, és a leskálázott végponttal rendelkező index kezdeti lekérdezése időtúllépést okozhat.

Feljegyzés

A vektorkeresési index inicializálása időtúllépést eredményezhet, ha a beágyazási végpont nincs megfelelően konfigurálva az adathalmazhoz. Csak kis adathalmazokhoz és tesztekhez használjon CPU-végpontokat. Nagyobb adathalmazok esetén használjon GPU-végpontot az optimális teljesítmény érdekében.

Vektorkeresési index létrehozása

Vektorkeresési indexet a felhasználói felületen, a Python SDK-val vagy a REST API-val hozhat létre. A felhasználói felület a legegyszerűbb megközelítés.

Az indexek két típusa létezik:

  • A Delta Sync Index automatikusan szinkronizálódik egy forrás deltatáblával, és automatikusan és növekményesen frissíti az indexet, ahogy a Delta-tábla alapjául szolgáló adatok változnak.
  • A Direct Vector Access Index támogatja a vektorok és metaadatok közvetlen olvasását és írását. A felhasználó feladata a tábla frissítése a REST API vagy a Python SDK használatával. Ez az indextípus nem hozható létre a felhasználói felületen. A REST API-t vagy az SDK-t kell használnia.

Index létrehozása a felhasználói felületen

  1. A bal oldali oldalsávon kattintson a Katalógus elemre a Katalóguskezelő felhasználói felületének megnyitásához.

  2. Lépjen a használni kívánt Delta-táblára.

  3. Kattintson a jobb felső sarokban található Létrehozás gombra, és válassza a Vektorkeresési index lehetőséget a legördülő menüből.

    Index létrehozása gomb

  4. Az index konfigurálásához használja a párbeszédpanel választóit.

    index létrehozása párbeszédpanel

    Név: A Unity Catalog online táblázatához használandó név. A névhez háromszintű névtér szükséges. <catalog>.<schema>.<name> Csak alfanumerikus karakterek és aláhúzásjelek engedélyezettek.

    Elsődleges kulcs: Elsődleges kulcsként használandó oszlop.

    Végpont: Válassza ki a használni kívánt vektorkeresési végpontot.

    Szinkronizálandó oszlopok: Jelölje ki a vektorindexkel szinkronizálni kívánt oszlopokat. Ha ezt a mezőt üresen hagyja, a forrástábla összes oszlopa szinkronizálva lesz az indexel. Az elsődleges kulcs oszlopa és a forrásoszlop beágyazása vagy a vektoroszlop beágyazása mindig szinkronizálva lesz.

    Beágyazási forrás: Jelzi, hogy szeretné-e, hogy a Databricks egy szövegoszlop beágyazását számítsa ki a Delta táblában (Számítási beágyazások), vagy ha a Delta-tábla előre összeállított beágyazásokat tartalmaz (meglévő beágyazási oszlop használata).

    • Ha a Számítási beágyazások lehetőséget választotta, válassza ki azt az oszlopot, amelyre a beágyazási modellt kiszolgáló végpontot ki szeretné számítani. Csak a szöveges oszlopok támogatottak.
    • Ha a Meglévő beágyazási oszlop használata lehetőséget választotta, jelölje ki azt az oszlopot, amely az előre összeállított beágyazásokat és a beágyazási dimenziót tartalmazza. Az előre összeállított beágyazási oszlop formátumának meg kell egyezőnek array[float]lennie.

    Számítási beágyazások szinkronizálása: Ezzel a beállítással mentheti a létrehozott beágyazásokat egy Unity Catalog-táblába. További információ: Save generated embedding table.

    Szinkronizálási mód: A folyamatosság szinkronban tartja az indexet másodperces késéssel. Azonban magasabb költségekkel jár, mivel egy számítási fürt ki van építve a folyamatos szinkronizálási streamelési folyamat futtatásához. A folyamatos és az aktivált verzió esetében a frissítés növekményes – csak az utolsó szinkronizálás óta megváltozott adatokat dolgozza fel a rendszer.

    Aktivált szinkronizálási mód esetén a Python SDK-val vagy a REST API-val indíthatja el a szinkronizálást. Lásd: Változásszinkronizálási index frissítése.

  5. Ha befejezte az index konfigurálását, kattintson a Létrehozás gombra.

Index létrehozása a Python SDK használatával

Az alábbi példa létrehoz egy Delta Sync-indexet a Databricks által kiszámított beágyazásokkal.

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

Az alábbi példa létrehoz egy deltaszinkronizálási indexet önkiszolgáló beágyazásokkal. Ez a példa azt is bemutatja, hogy az opcionális paraméter columns_to_sync használatával csak az indexben használni kívánt oszlopok egy részhalmazát választhatja ki.

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

Alapértelmezés szerint a forrástábla összes oszlopa szinkronizálva lesz az indexel. Ha csak az oszlopok egy részhalmazát szeretné szinkronizálni, használja a következőt columns_to_sync: . Az elsődleges kulcs és a beágyazási oszlopok mindig szerepelnek az indexben.

Ha csak az elsődleges kulcsot és a beágyazási oszlopot szeretné szinkronizálni, az alábbi módon columns_to_sync kell megadnia őket:

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

További oszlopok szinkronizálásához adja meg azokat az ábrán látható módon. Nem kell tartalmaznia az elsődleges kulcsot és a beágyazási oszlopot, mivel azok mindig szinkronizálva vannak.

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

Az alábbi példa létrehoz egy közvetlen vektorelérési indexet.


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

Index létrehozása a REST API használatával

Lásd a REST API referenciadokumentációját: POST /api/2.0/vector-search/indexes.

Létrehozott beágyazási tábla mentése

Ha a Databricks létrehozza a beágyazásokat, mentheti a létrehozott beágyazásokat egy táblába a Unity Catalogban. Ez a tábla ugyanabban a sémában jön létre, mint a vektorindex, és a vektorindex oldaláról van csatolva.

A tábla neve a vektorkeresési index neve, hozzáfűzve _writeback_table. A név nem szerkeszthető.

A Unity Catalogban bármely más táblához hasonlóan elérheti és lekérdezheti a táblát. A táblát azonban nem szabad elvetni vagy módosítani, mert nem manuálisan kell frissíteni. Az index törlésekor a rendszer automatikusan törli a táblát.

Vektorkeresési index frissítése

Delta-szinkronizálási index frissítése

A folyamatos szinkronizálási módban létrehozott indexek automatikusan frissülnek, amikor a forrás Delta-tábla megváltozik. Aktivált szinkronizálási mód használata esetén a Python SDK vagy a REST API használatával indítsa el a szinkronizálást.

Python SDK

index.sync()

REST API

Lásd a REST API referenciadokumentációját: POST /api/2.0/vector-search/indexes/{index_name}/sync.

Közvetlen vektorelérési index frissítése

A Python SDK-val vagy a REST API-val adatokat szúrhat be, frissíthet vagy törölhet egy közvetlen vektoros hozzáférési indexből.

Python SDK

   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

Lásd a REST API referenciadokumentációját: POST /api/2.0/vector-search/indexes.

Az alábbi kódpélda bemutatja, hogyan frissíthet indexet személyes hozzáférési jogkivonat (PAT) használatával.

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

Az alábbi példakód bemutatja, hogyan frissíthet egy indexet egy szolgáltatásnév használatával.

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

Vektorkeresési végpont lekérdezése

A vektorkeresési végpontot csak a Python SDK, a REST API vagy az SQL vector_search() AI függvény használatával kérdezheti le.

Feljegyzés

Ha a végpontot lekérdező felhasználó nem a vektorkeresési index tulajdonosa, a felhasználónak a következő UC-jogosultságokkal kell rendelkeznie:

  • A USE CATALOG a vektorkeresési indexet tartalmazó katalógusban.
  • A SÉMA HASZNÁLATA a vektorkeresési indexet tartalmazó sémán.
  • SELECT a vektorkeresési indexen.

Hibrid kulcsszó-hasonlósági keresés végrehajtásához állítsa a paramétert a következőre query_type hybrid: . Az alapértelmezett érték (a ann legközelebbi szomszéd).

Python SDK

# 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

Lásd a REST API referenciadokumentációját: POST /api/2.0/vector-search/indexes/{index_name}/query.

Az alábbi kódpélda bemutatja, hogyan kérdezhet le egy indexet személyes hozzáférési jogkivonat (PAT) használatával.

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

Az alábbi példakód bemutatja, hogyan kérdezhet le egy indexet egy szolgáltatásnév használatával.

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

Fontos

Az vector_search() AI-függvény nyilvános előzetes verzióban érhető el.

Az AI-függvény használatához lásd vector_search függvényt.

Szűrők használata lekérdezéseken

A lekérdezések a Delta tábla bármely oszlopa alapján definiálhatnak szűrőket. similarity_search Csak a megadott szűrőknek megfelelő sorokat adja vissza. A következő szűrők támogatottak:

Szűrő operátor Működés Példák
NOT A szűrőt nem lehet kivenni. A kulcsnak "NOT" végződéssel kell végződnie. A "COLOR NOT" (NEM szín) értéke például megegyezik azokkal a dokumentumokkal, ahol a szín nem piros. {"id NOT": 2} {“color NOT”: “red”}
< Ellenőrzi, hogy a mező értéke kisebb-e a szűrőértéknél. A kulcsnak a következővel kell végződnie: " <. A 200-as értékkel rendelkező "ár <" például megegyezik azokkal a dokumentumokkal, ahol az ár kisebb, mint 200. {"id <": 200}
<= Ellenőrzi, hogy a mező értéke kisebb vagy egyenlő-e a szűrőértéknél. A kulcsnak a következővel kell végződnie: " <=". A 200-as értékkel rendelkező "price <=" például megegyezik azokkal a dokumentumokkal, ahol az ár kisebb vagy egyenlő 200-nál. {"id <=": 200}
> Ellenőrzi, hogy a mező értéke nagyobb-e a szűrőértéknél. A kulcsnak a következővel kell végződnie: " >. A 200-as értékkel rendelkező "ár >" például megegyezik azokkal a dokumentumokkal, ahol az ár nagyobb, mint 200. {"id >": 200}
>= Ellenőrzi, hogy a mező értéke nagyobb vagy egyenlő-e a szűrőértéknél. A kulcsnak a következővel kell végződnie: " >=". A 200-as értékkel rendelkező "price >=" például megegyezik azokkal a dokumentumokkal, ahol az ár nagyobb vagy egyenlő 200-nál. {"id >=": 200}
OR Ellenőrzi, hogy a mező értéke megfelel-e valamelyik szűrőértéknek. A kulcsnak több alkulcsot kell tartalmaznia OR . Ha például az érték megegyezik azokkal a dokumentumokkal, color1 OR color2 ahol color1 van red vagy color2 vanblue.["red", "blue"] {"color1 OR color2": ["red", "blue"]}
LIKE Egyezik a részleges sztringekkel. {"column LIKE": "hello"}
Nincs megadva szűrőoperátor A szűrő pontos egyezést keres. Ha több érték van megadva, az bármelyik értéknek megfelel. {"id": 200} {"id": [200, 300]}

Lásd a következő kód példákat:

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
    )

REST API

Lásd: POST /api/2.0/vector-search/indexes/{index_name}/query.

Példajegyzetfüzetek

Az ebben a szakaszban szereplő példák a Python SDK vektorkeresésének használatát mutatják be.

Példák LangChain-példákra

Lásd : A LangChain használata a Mozaik AI-vektorkereséssel a Mozaik AI Vector Search használatához, mint a LangChain-csomagokkal való integráció során.

Az alábbi jegyzetfüzet bemutatja, hogyan konvertálhatja a hasonlósági keresési eredményeket LangChain-dokumentumokká.

Vektorkeresés a Python SDK-jegyzetfüzettel

Jegyzetfüzet beszerzése

Jegyzetfüzet-példák beágyazási modell meghívására

Az alábbi jegyzetfüzetek bemutatják, hogyan konfigurálhat egy Mozaik AI-modellkiszolgáló végpontot a beágyazások generálásához.

OpenAI-beágyazási modell meghívása a Mozaik AI-modellkiszolgáló jegyzetfüzet használatával

Jegyzetfüzet beszerzése

GTE-beágyazási modell meghívása a Mozaik AI-modellkiszolgáló jegyzetfüzet használatával

Jegyzetfüzet beszerzése

OSS-beágyazási modelljegyzetfüzet regisztrálása és kiszolgálása

Jegyzetfüzet beszerzése