Sdílet prostřednictvím

Vytvoření vektorového indexu

Ve službě Azure AI Search můžete k ukládání vektorů do indexu vyhledávání použít rozhraní REST API (Create or Update Index ). Vektorový index je definován schématem indexu, který obsahuje vektorová pole, nevectorová pole a oddíl konfigurace vektoru.

Při vytváření vektorového indexu implicitně vytvoříte vložený prostor , který slouží jako korpus pro vektorové dotazy. Prostor pro vložení se skládá ze všech vektorových polí naplněných vkládáním ze stejného modelu vkládání. V době dotazu systém porovnává vektorový dotaz s indexovanými vektory a vrací výsledky na základě sémantické podobnosti.

Pokud chcete indexovat vektory ve službě Azure AI Search, postupujte takto:

  • Začněte základní definicí schématu.
  • Přidejte vektorové algoritmy a volitelnou kompresi.
  • Přidání definic vektorových polí
  • Načtěte předvectorizovaná data jako samostatný krok nebo použijte integrovanou vektorizaci pro vytváření bloků dat a vkládání během indexování.

Tento článek používá rest pro ilustraci. Jakmile porozumíte základnímu pracovnímu postupu, pokračujte ukázkami kódu sady Azure SDK v úložišti azure-search-vector-samples , které poskytují pokyny k používání vektorů v testovacím a produkčním kódu.

Návod

Pomocí webu Azure Portal můžete také vytvořit vektorový index a vyzkoušet integrované bloky dat a vektorizaci.

Požadavky

  • Služba Azure AI Search v libovolné oblasti a na libovolné úrovni. Pokud plánujete používat integrovanou vektorizaci s dovednostmi a vektorizátory Azure AI, azure AI Search musí být ve stejné oblasti jako modely vkládání hostované ve službě Azure AI Vision.

  • Vaše zdrojové dokumenty musí obsahovat vektorové vkládání k nahrání do indexu. Pro tento krok můžete také použít integrovanou vektorizaci .

  • Měli byste znát limit dimenzí modelu, který vytváří vložené hodnoty, abyste ho mohli přiřadit k vektorovém poli. Pro vkládání textu ada-002 jsou rozměry pevné na 1536. Pro vkládání textu -3-small nebo text-embedding-3-large, rozměry jsou v rozsahu od 1 do 1536 a od 1 do 3072.

  • Měli byste vědět, jakou metriku podobnosti použít. Pro vkládání modelů do Azure OpenAI se podobnost počítá pomocí cosine.

  • Měli byste vědět, jak vytvořit index. Schéma vždy obsahuje pole pro klíč dokumentu, pole pro vyhledávání nebo filtry a další konfigurace pro chování potřebné při indexování a dotazech.

Omezení

Některé vyhledávací služby vytvořené před lednem 2019 nemůžou vytvořit vektorový index. Pokud se to týká vás, vytvořte novou službu, která bude používat vektory.

Příprava dokumentů pro indexování

Před indexováním sestavte datovou část dokumentu, která obsahuje pole vektorových a nevectorových dat. Struktura dokumentu musí odpovídat kolekci polí schématu indexu.

Ujistěte se, že zdrojové dokumenty obsahují následující obsah:

Obsah Popis
Jedinečný identifikátor Pole nebo vlastnost metadat, která jednoznačně identifikuje každý dokument. Všechny indexy vyhledávání vyžadují klíč dokumentu. Aby bylo možné splnit požadavky na klíč dokumentu, musí mít zdrojový dokument jedno pole nebo vlastnost, které ho jednoznačně identifikuje v indexu. Pokud indexujete objekty blob, může se jednat o metadata_storage_path, která jednoznačně identifikuje jednotlivé objekty blob. Pokud indexujete z databáze, může to být primární klíč. Toto zdrojové pole musí být namapováno na pole indexu typu Edm.String a key=true v indexu vyhledávání.
Obsah bez vektoru Zadejte další pole s obsahem čitelným pro člověka. Obsah čitelný pro člověka je užitečný pro odpověď na dotazy a pro hybridní dotazy , které obsahují fulltextové vyhledávání nebo sémantické řazení ve stejném požadavku. Pokud používáte model dokončování chatu, většina modelů, jako je ChatGPT, očekává čitelný text pro člověka a nepřijímá nezpracované vektory jako vstup.
Vektorový obsah Vektorizovaná reprezentace vašeho nevektorového obsahu pro použití při dotazu. Vektor je pole čísel s plovoucí desetinnou čárkou s jednoduchou přesností vygenerované modelem vložením. Každé vektorové pole obsahuje pole generované modelem. Pro každé pole existuje jedno vložené pole, kde pole je pole nejvyšší úrovně (není součástí vnořeného nebo složitého typu). Pro jednoduchou integraci doporučujeme vkládat modely do Azure OpenAI, například vkládání textu-3 pro textové dokumenty nebo rozhraní REST API pro načítání obrázků pro obrázky a multimodální vkládání.

Pokud můžete použít indexery a sady dovedností, zvažte integrované vektorizace, které během indexování kóduje obrázky a text. Definice polí jsou určené pro vektorová pole, ale příchozí zdrojová data můžou být text nebo obrázky, které se během indexování převedou na vektorová pole.

Index vyhledávání by měl obsahovat pole a obsah pro všechny scénáře dotazů, které chcete podporovat. Předpokládejme, že chcete vyhledávat nebo filtrovat názvy produktů, verze, metadata nebo adresy. V tomto případě není hledání vektorové podobnosti užitečné. Lepší volbou by bylo hledání klíčových slov, geografické vyhledávání nebo filtry, které iterují přes doslovný obsah. Index vyhledávání, který zahrnuje vektorová i nevectorová pole, poskytuje maximální flexibilitu pro vytváření dotazů a složení odpovědí.

Krátký příklad datové části dokumentů, která obsahuje vektorová a nevektorová pole, najdete v části načíst vektorová data tohoto článku.

Začínáme se základním indexem

Začněte s minimálním schématem, abyste měli definici pro práci před přidáním vektorové konfigurace a vektorových polí. Jednoduchý index může vypadat v následujícím příkladu. Další informace o schématu indexu naleznete v tématu Vytvoření vyhledávacího indexu.

Všimněte si, že index má požadovaný název, požadovaný klíč dokumentu ("key": true) a pole pro obsah čitelný člověkem ve formátu prostého textu. Je běžné mít čitelné verze obsahu, který chcete vektorizovat. Pokud například máte blok textu ze souboru PDF, mělo by schéma indexu obsahovat pole pro bloky prostého textu a druhé pole pro vektorizované bloky dat.

Tady je základní index s "name", "fields" kolekcí a dalšími strukturami pro další konfiguraci:

POST https://[servicename].search.windows.net/indexes?api-version=[api-version] 
{
  "name": "example-index",
  "description": "This is an example index."
  "fields": [
    { "name": "documentId", "type": "Edm.String", "key": true, "retrievable": true, "searchable": true, "filterable": true },
    { "name": "myHumanReadableNameField", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "myHumanReadableContentField", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
  ],
  "analyzers": [ ],
  "scoringProfiles": [ ],
  "suggesters": [ ],
  "vectorSearch": [ ]
}

Přidání konfigurace vektorového vyhledávání

Dále přidejte do schématu "vectorSearch" konfiguraci. Je užitečné zadat konfiguraci před definicemi polí, protože profily, které zde definujete, se stanou součástí definice vektorového pole. Ve schématu je vektorová konfigurace obvykle vložena za kolekci polí, možná za "analyzers", "scoringProfiles"a "suggesters". Na objednávce ale nezáleží.

Konfigurace vektoru zahrnuje:

  • vectorSearch.algorithms používá se při indexování k vytvoření informací "nejbližšího souseda" mezi vektorovými uzly.
  • vectorSearch.compressions pro skalární nebo binární kvantování, převzorkování a opětovné řazení s původními vektory.
  • vectorSearch.profiles pro zadání více kombinací algoritmů a konfigurací komprese.

Tady jsou kroky:

  1. K vytvoření indexu použijte rozhraní REST API pro vytvoření nebo aktualizaci indexu .

  2. vectorSearch Do indexu přidejte oddíl, který určuje vyhledávací algoritmy použité k vytvoření prostoru pro vložení.

     "vectorSearch": {
     "compressions": [
         {
             "name": "scalar-quantization",
             "kind": "scalarQuantization",
             "scalarQuantizationParameters": {
                 "quantizedDataType": "int8"
                 },
             "rescoringOptions": {
                 "enableRescoring": true,
                 "defaultOversampling": 10,
                 "rescoreStorageMethod": "preserveOriginals"
             }
         },
         {
             "name": "binary-quantization",
             "kind": "binaryQuantization",
             "rescoringOptions": {
                 "enableRescoring": true,
                 "defaultOversampling": 10,
                 "rescoreStorageMethod": "discardOriginals"
         }
         }
     ],
     "algorithms": [
         {
             "name": "hnsw-1",
             "kind": "hnsw",
             "hnswParameters": {
                 "m": 4,
                 "efConstruction": 400,
                 "efSearch": 500,
                 "metric": "cosine"
             }
         },
         {
             "name": "hnsw-2",
             "kind": "hnsw",
             "hnswParameters": {
                 "m": 8,
                 "efConstruction": 800,
                 "efSearch": 800,
                 "metric": "hamming"
             }
         },
         {
             "name": "eknn",
             "kind": "exhaustiveKnn",
             "exhaustiveKnnParameters": {
                 "metric": "euclidean"
             }
         }

     ],
     "profiles": [
       {
         "name": "vector-profile-hnsw-scalar",
         "compression": "scalar-quantization",
         "algorithm": "hnsw-1"
       }
     ]
 }

    Klíčové body:

    • Názvy pro každou konfiguraci komprese, algoritmu a profilu musí být jedinečné pro jeho typ v rámci indexu.

    • vectorSearch.compressions může být scalarQuantization nebo binaryQuantization. Skalární kvantování komprimuje hodnoty float do užších datových typů. Binární kvantování převede plovoucí hodnoty na binární 1bitové hodnoty.

    • vectorSearch.compressions.rescoringOptions používá původní nekomprimované vektory k přepočtu podobnosti a opětovnému seřazení nejlepších výsledků vrácených počátečním vyhledávacím dotazem. Nekomprimované vektory existují v indexu vyhledávání, i když stored jsou false. Tato vlastnost je nepovinná. Výchozí hodnota je true.

    • vectorSearch.compressions.rescoringOptions.defaultOversampling považuje širší sadu potenciálních výsledků k posunu snížení informací od kvantování. Vzorec pro potenciální výsledky se skládá z k dotazu s násobitelem převzorkování. Pokud například dotaz určuje k 5 a převzorkování je 20, dotaz efektivně požaduje 100 dokumentů pro použití při opětovném řazení pomocí původního nekomprimovaného vektoru pro tento účel. Vrátí se pouze nejlépe k seřazené výsledky. Tato vlastnost je nepovinná. Výchozí hodnota je 4.

    • vectorSearch.compressions.scalarQuantizationParameters.quantizedDataType musí být nastavena na int8hodnotu . V tuto chvíli se jedná o jediný primitivní datový typ podporovaný. Tato vlastnost je nepovinná. Výchozí hodnota je int8.

    • vectorSearch.algorithms je buď hnsw nebo exhaustiveKnn. Jedná se o přibližné algoritmy ANN (Nearest Neighbors) sloužící k uspořádání vektorového obsahu během indexování.

    • vectorSearch.algorithms.m je obousměrný počet propojení. Výchozí hodnota je 4. Rozsah je 4 až 10. Nižší hodnoty by měly ve výsledcích vracet méně šumu.

    • vectorSearch.algorithms.efConstruction je počet nejbližších sousedů použitých při indexování. Výchozí hodnota je 400. Rozsah je 100 až 1 000.

    • "vectorSearch.algorithms.efSearch je počet nejbližších sousedů použitých při hledání. Výchozí hodnota je 500. Rozsah je 100 až 1 000.

    • vectorSearch.algorithms.metric cosine pokud používáte Azure OpenAI, jinak použijte metriku podobnosti přidruženou k modelu vkládání, který používáte. Podporované hodnoty jsou cosine, dotProduct, euclideana hamming (používá se k indexování binárních dat).

    • vectorSearch.profiles přidejte vrstvu abstrakce pro zajištění širších definic. Profil je definován v vectorSearch a odkazován podle názvu v každém vektorovém poli. Jedná se o kombinaci komprese a konfigurace algoritmů. Tuto vlastnost přiřadíte vektorovým polím a určíte algoritmus a kompresi polí.

Přidání vektorového pole do kolekce polí

Jakmile máte konfiguraci vektoru, můžete do kolekce polí přidat vektorové pole. Pamatujte si, že kolekce polí musí obsahovat pole pro klíč dokumentu, vektorová pole a všechna další nevektorová pole, která potřebujete pro scénáře hybridního vyhledávání nebo dokončování konverzačních modelů v úlohách RAG.

Vektorová pole jsou charakterizována jejich datovým typem, dimensions vlastností založenou na modelu vkládání použitém k výstupu vektorů a profilu vektoru, který jste vytvořili v předchozím kroku.

  1. Pomocí rozhraní REST API pro vytvoření nebo aktualizaci indexu vytvořte index a přidejte do kolekce polí vektorové pole.

    {
  "name": "example-index",
  "fields": [
    {
        "name": "contentVector",
        "type": "Collection(Edm.Single)",
        "searchable": true,
        "retrievable": false,
        "stored": false,
        "dimensions": 1536,
        "vectorSearchProfile": "vector-profile-1"
    }
  ]
}

  2. Zadejte vektorové pole s následujícími atributy. Pro každé pole můžete uložit jedno vygenerované vkládání. Pro každé vektorové pole:

    • type musí být datový typ vektoru. Collection(Edm.Single) je nejběžnější pro vkládání modelů.
    • dimensions je počet dimenzí vygenerovaných modelem vkládání. U vkládání textu-ada-002 je opraveno na 1536. Pro řadu modelů vkládání textu-3 existuje rozsah hodnot. Pokud k vygenerování vektorů používáte integrovanou vektorizaci a dovednost vkládání, ujistěte se, že je tato vlastnost nastavená na stejnou hodnotu dimenzí, kterou používá dovednost vkládání.
    • vectorSearchProfile je název profilu definovaného jinde v indexu.
    • searchable musí být pravdivé.
    • retrievable může být true nebo false. True vrátí nezpracované vektory (1 536 z nich) jako prostý text a spotřebovává úložný prostor. Pokud předáváte výsledek vektoru podřízené aplikaci, nastavte na hodnotu true.
    • stored může být true nebo false. Určuje, zda je pro načtení uložena další kopie vektorů. Další informace naleznete v tématu Zmenšení velikosti vektoru.
    • filterable, facetablea sortable musí být false.

  3. Pokud chcete vyvolat title vektorového filterable, přidejte do kolekce filtrovatelná nevectorová pole, například s nastaveným na hodnotu True.

  4. Přidejte další pole, která definují látku a strukturu textového obsahu, který indexujete. Minimálně potřebujete klíč dokumentu.

    Měli byste také přidat pole, která jsou užitečná v dotazu nebo v odpovědi. Následující příklad ukazuje vektorová pole pro název a obsah (titleVector a contentVector), které jsou ekvivalentní vektorům. Poskytuje také pole pro ekvivalentní textový obsah (title a content), které jsou užitečné pro řazení, filtrování a čtení ve výsledcích hledání.

    Následující příklad ukazuje kolekci polí:

    PUT https://my-search-service.search.windows.net/indexes/my-index?api-version=2025-09-01&allowIndexDowntime=true
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "name": "{{index-name}}",
    "fields": [
        {
            "name": "id",
            "type": "Edm.String",
            "key": true,
            "filterable": true
        },
        {
            "name": "title",
            "type": "Edm.String",
            "searchable": true,
            "filterable": true,
            "sortable": true,
            "retrievable": true
        },
        {
            "name": "titleVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "stored": true,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-1"
        },
        {
            "name": "content",
            "type": "Edm.String",
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "contentVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": false,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-1"
        }
    ],
    "vectorSearch": {
        "algorithms": [
            {
                "name": "hnsw-1",
                "kind": "hnsw",
                "hnswParameters": {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            }
        ],
        "profiles": [
            {
                "name": "vector-profile-1",
                "algorithm": "hnsw-1"
            }
        ]
    }
}

Načtení vektorových dat pro indexování

Obsah, který zadáte pro indexování, musí odpovídat schématu indexu a obsahovat jedinečnou řetězcovou hodnotu klíče dokumentu. Předvectorizovaná data se načtou do jednoho nebo více vektorových polí, která mohou existovat společně s jinými poli obsahujícími obsah nevectoru.

Pro příjem dat můžete použít metodologie push nebo pull.

Použití dokumentů – Index k načtení vektorových a nevectorových dat do indexu. Rozhraní API nabízených oznámení pro indexování jsou stejná napříč všemi stabilními verzemi a verzemi Preview. K načtení dokumentů použijte některá z následujících rozhraní API:

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/index?api-version=2025-09-01

{
    "value": [
        {
            "id": "1",
            "title": "Azure App Service",
            "content": "Azure App Service is a fully managed platform for building, deploying, and scaling web apps. You can host web apps, mobile app backends, and RESTful APIs. It supports a variety of programming languages and frameworks, such as .NET, Java, Node.js, Python, and PHP. The service offers built-in auto-scaling and load balancing capabilities. It also provides integration with other Azure services, such as Azure DevOps, GitHub, and Bitbucket.",
            "category": "Web",
            "titleVector": [
                -0.02250031754374504,
                 . . . 
                        ],
            "contentVector": [
                -0.024740582332015038,
                 . . .
            ],
            "@search.action": "upload"
        },
        {
            "id": "2",
            "title": "Azure Functions",
            "content": "Azure Functions is a serverless compute service that enables you to run code on-demand without having to manage infrastructure. It allows you to build and deploy event-driven applications that automatically scale with your workload. Functions support various languages, including C#, F#, Node.js, Python, and Java. It offers a variety of triggers and bindings to integrate with other Azure services and external services. You only pay for the compute time you consume.",
            "category": "Compute",
            "titleVector": [
                -0.020159931853413582,
                . . .
            ],
            "contentVector": [
                -0.02780858241021633,
                 . . .
            ],
            "@search.action": "upload"
        }
        . . .
    ]
}

Provést dotaz na index pro vektorový obsah

Pro účely ověřování můžete dotazovat index pomocí Průzkumníka služby Search na webu Azure Portal nebo volání rozhraní REST API. Protože Azure AI Search nemůže převést vektor na čitelný text, zkuste vrátit pole ze stejného dokumentu, který poskytuje důkaz shody. Pokud například vektorový dotaz cílí na titleVector pole, můžete pro výsledky hledání vybrat title.

Pole musí být přiřazená jako retrievable, aby byla zahrnuta do výsledků.

  • Zkontrolujte indexy v indexech správy>vyhledávání a zobrazte velikost indexu all-up a vector index. Velikost indexu kladného vektoru označuje, že jsou přítomny vektory.

  • K dotazování indexu použijte Průzkumníka služby Search. Průzkumník služby Search má dvě zobrazení: zobrazení dotazu (výchozí) a zobrazení JSON.

    • Nastavte možnosti>dotazu Skrýt vektorové hodnoty ve výsledcích hledání pro čitelnější výsledky.

    • Použití zobrazení JSON pro vektorové dotazy. Můžete vložit definici JSON vektorového dotazu, který chcete spustit. Pokud má index přiřazení vektorizátoru, můžete také použít předdefinovaný převod textu na vektor nebo převod obrázků na vektor. Další informace o hledání obrázků najdete v tématu Rychlý start: Hledání obrázků v Průzkumníku služby Search.

    • Pro rychlé potvrzení, že index obsahuje vektory, použijte výchozí zobrazení dotazu. Zobrazení dotazu je určené pro fulltextové vyhledávání. I když ho nemůžete použít pro vektorové dotazy, můžete odeslat prázdné vyhledávání (search=*) a zkontrolovat obsah. Obsah všech polí, včetně vektorových polí, se vrátí jako prostý text.

Další informace naleznete v tématu Vytvoření vektorového dotazu.

Aktualizace vektorového indexu

Pokud chcete aktualizovat vektorový index, upravte schéma a znovu načtěte dokumenty, aby se naplnila nová pole. Rozhraní API pro aktualizace schématu zahrnují rozhraní REST (Create or Update Index), CreateOrUpdateIndex v sadě Azure SDK pro .NET, create_or_update_index v sadě Azure SDK pro Python a podobné metody v jiných sadách Azure SDK.

Standardní pokyny k aktualizaci indexu najdete v tématu Aktualizace nebo opětovné sestavení indexu.

Mezi klíčové body patří:

  • Vyřazení a úplné přestavění indexu se často vyžaduje při aktualizaci a odstraňování existujících polí.

  • Bez požadavku na opětovné sestavení můžete provést následující úpravy:

    • Přidejte nová pole do kolekce polí.
    • Přidejte nové konfigurace vektorů přiřazené k novým polím, ale ne existujícím polím, která jsou již vektorizována.
    • Změna retrievable (hodnoty jsou true nebo false) u existujícího pole Vektorová pole musí být prohledávatelná a načístelná, ale pokud chcete zakázat přístup k vektorovým polím v situacích, kdy přetažení a opětovné sestavení není možné, můžete nastavit načtení na false.

Další kroky

Jako další krok doporučujeme vytvořit vektorový dotaz.

Ukázky kódu v úložišti azure-search-vector-samples ukazují ucelené pracovní postupy, které zahrnují definici schématu, vektorizaci, indexování a dotazy.

Existuje ukázkový kód pro Python, C# a JavaScript.

  • Last updated on