Vytvoření indexu ve službě Azure AI Vyhledávač

V tomto článku se dozvíte, jak definovat schéma indexu vyhledávání a nasdílit ho do vyhledávací služby. Vytvoření indexu vytvoří fyzické datové struktury ve vyhledávací službě. Jakmile existuje index, načtěte index jako samostatný úkol.

Požadavky

• Předplatné služby Azure. Vytvořte si ho zdarma.

• Služba Azure AI Vyhledávač, libovolná oblast a úroveň, ale musí se jednat o fakturovatelnou úroveň (Basic nebo vyšší) pro přístup na základě role.

• Oprávnění k vytvoření indexu: Role Přispěvatel vyhledávací služby nebo klíč rozhraní API správce pro ověřování na základě klíčů.

• Jedinečné pole ve zdrojových datech, které lze použít jako klíč dokumentu v indexu.

• Pochopení schématu dat Chcete-li získat pokyny k návrhu pro vyhledávání, načítání, filtrování, rozčlenění podle aspektů a řazení polí, podívejte se na kontrolní seznam schématu.

Vytvoření indexu

Až budete připraveni vytvořit index, použijte vyhledávacího klienta, který může požadavek odeslat. K počátečnímu vývoji a testování konceptu můžete použít azure Portal nebo rozhraní REST API, jinak je běžné používat sady Azure SDK.

Během vývoje naplánujte časté přebudování. Vzhledem k tomu, že se ve službě vytvářejí fyzické struktury, je pro mnoho úprav nezbytné vyřazení a opětovné vytvoření indexů . Můžete zvážit, že budete pracovat s podmnožinou dat, aby opětovné sestavení bylo rychlejší.

POST https://[servicename].search.windows.net/indexes?api-version=[api-version] 
{
  "name": "hotels",
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "retrievable": true, "searchable": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Address", "type": "Edm.ComplexType", 
      "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "retrievable": true, "filterable": false, "sortable": false, "facetable": false, "searchable": true },
          { "name": "City", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true },
          { "name": "StateProvince", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": true, "sortable": true, "facetable": true }
        ]
    }
  ],
  "suggesters": [ ],
  "scoringProfiles": [ ],
  "analyzers":(optional)[ ... ]
}

using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

// Create the index
string indexName = "hotels";
SearchIndex index = new SearchIndex(indexName)
{
    Fields =
    {
        new SimpleField("hotelId", SearchFieldDataType.String) { IsKey = true, IsFilterable = true, IsSortable = true },
        new SearchableField("hotelName") { IsFilterable = true, IsSortable = true },
        new SearchableField("description") { AnalyzerName = LexicalAnalyzerName.EnLucene },
        new SearchableField("descriptionFr") { AnalyzerName = LexicalAnalyzerName.FrLucene },
        new ComplexField("address")
        {
            Fields =
            {
                new SearchableField("streetAddress"),
                new SearchableField("city") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("stateProvince") { IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("country") { SynonymMapNames = new[] { synonymMapName }, IsFilterable = true, IsSortable = true, IsFacetable = true },
                new SearchableField("postalCode") { IsFilterable = true, IsSortable = true, IsFacetable = true }
            }
        }
    }
};

await indexClient.CreateIndexAsync(index);

Ověření vytvoření indexu

Po vytvoření indexu ověřte, že existuje, a to výpisem indexů ve vyhledávací službě.

GET https://[servicename].search.windows.net/indexes?api-version=[api-version]

// List all indexes to verify creation
var indexNames = indexClient.GetIndexNames();
foreach (var name in indexNames)
{
    Console.WriteLine(name);
}

Klíče dokumentu

Vytvoření indexu vyhledávání má dva požadavky: index musí mít jedinečný název vyhledávací služby a musí mít klíč dokumentu. Logický key atribut pole lze nastavit na hodnotu true, aby bylo možné určit, které pole poskytuje klíč dokumentu.

Klíč dokumentu je jedinečný identifikátor hledaného dokumentu a hledaný dokument je kolekce polí, která něco úplně popisují. Pokud například indexujete datovou sadu filmů, obsahuje hledaný dokument název, žánr a dobu trvání jednoho filmu. Názvy filmů jsou v této datové sadě jedinečné, takže název videa můžete použít jako klíč dokumentu.

Ve službě Azure AI Vyhledávač je klíč dokumentu řetězec a musí pocházet z jedinečných hodnot ve zdroji dat, který poskytuje obsah, který se má indexovat. Obecně platí, že vyhledávací služba negeneruje klíčové hodnoty, ale v některých scénářích (například indexer tabulky Azure) syntetizuje existující hodnoty, aby vytvořila jedinečný klíč pro dokumenty, které se indexují. Dalším scénářem je indexování jednoho k mnoha pro rozdělená nebo particiovaná data, v takovém případě se klíče dokumentů generují pro každý blok.

Během přírůstkového indexování, kde se indexuje nový a aktualizovaný obsah, se přidají příchozí dokumenty s novými klíči, zatímco příchozí dokumenty s existujícími klíči se buď sloučí, nebo přepíšou v závislosti na tom, jestli jsou pole indexu null nebo naplněná.

Mezi důležité body týkající se klíčů dokumentu patří:

• Maximální délka hodnot v poli klíče je 1 024 znaků.
• Jako klíčové pole musí být vybráno přesně jedno pole nejvyšší úrovně v každém indexu a musí být typu Edm.String.
• Výchozí hodnota atributu key je false pro jednoduchá pole a hodnotu null pro složitá pole.

Klíčová pole se dají použít k přímému vyhledání dokumentů a aktualizaci nebo odstranění konkrétních dokumentů. Hodnoty klíčových polí jsou zpracovávány s ohledem na rozlišování malých a velkých písmen při vyhledávání nebo indexování dokumentů. Podrobnosti najdete v tématu GET Document (REST) a Index Documents (REST).

Kontrolní seznam schématu

Tento kontrolní seznam vám pomůže při rozhodování o návrhu indexu vyhledávání.

1. Zkontrolujte zásady vytváření názvů, aby názvy indexů a polí odpovídaly pravidlům pojmenování.

2. Viz Podporované datové typy. Datový typ ovlivňuje způsob použití pole. Například číselný obsah je filtrovatelný, ale není prohledávatelný pomocí fulltextu. Nejběžnějším datovým typem pro prohledávatelný text je Edm.String, který se tokenizuje a dotazuje pomocí fulltextového vyhledávacího modulu. Nejběžnějším datovým typem vektorového pole je Edm.Single , ale můžete použít i jiné typy.

3. Zadejte popis indexu, maximálně 4 000 znaků. Tento čitelný text pro člověka je neocenitelný, když systém musí získat přístup k několika indexům a rozhodnout se na základě popisu. Vezměte v úvahu server MCP (Model Context Protocol), který musí vybrat správný index za běhu. Rozhodnutí může být založeno na popisu, nikoli jenom na názvu indexu.

4. Identifikace klíče dokumentu Klíč dokumentu je požadavek na index. Jedná se o jedno řetězcové pole naplněné zdrojovým datovým polem, které obsahuje jedinečné hodnoty. Pokud například indexujete ze služby Blob Storage, jako klíč dokumentu se často používá cesta k úložišti metadat, protože jednoznačně identifikuje každý objekt blob v kontejneru.

5. Identifikujte pole ve zdroji dat, která přispívají k prohledávatelnému obsahu v indexu.

   Prohledávatelný ne-vektorový obsah zahrnuje krátké nebo dlouhé řetězce, které jsou dotazovány pomocí full-textového vyhledávače. Pokud je obsah podrobný (Krátké fráze nebo větší bloky dat), experimentujte s různými analyzátory a zjistěte, jak se text tokenizuje.

   Prohledávatelný vektorový obsah může být obrázky nebo text (v libovolném jazyce), které existují jako matematická reprezentace. Pomocí úzkých datových typů nebo komprese vektorů můžete zmenšit vektorová pole.

   Atributy nastavené u polí, například retrievable nebo filterable, určují chování hledání i fyzické vyjádření indexu ve vyhledávací službě. Určení způsobu, jakým mají být pole přiřazena, je iterativní proces pro mnoho vývojářů. Pokud chcete iterace urychlit, začněte ukázkovými daty, abyste je mohli snadno zahodit a znovu sestavit.

6. Určete, která zdrojová pole je možné použít jako filtry. Vhodné je použít pole s číselným obsahem a pole s krátkým textem, zejména pole s opakujícími se hodnotami. Při práci s filtry nezapomeňte:

   • Filtry se dají použít ve vektorových a nevektorových dotazech, ale samotný filtr se použije na pole čitelná pro člověka (nevektorová) ve vašem indexu.

   • Filtrovatelná pole se dají volitelně použít ve fasetové navigaci.

   • Filtrovatelná pole se vrací v libovolném pořadí a neprocházejí vyhodnocováním relevance, proto zvažte jejich seřazení.

7. U vektorových polí zadejte konfiguraci vektorového vyhledávání a algoritmy používané k vytváření navigačních cest a vyplňování vloženého prostoru. Další informace naleznete v tématu Přidání vektorových polí.

   Vektorová pole mají další vlastnosti, které skalární pole nemají, jako například použití určitých algoritmů a kompresi vektorů.

   Vektorová pole vynechají atributy, které nejsou užitečné pro vektorová data, jako jsou řazení, filtrování a fasety.

8. U polí, která nejsou typuvector, určete, jestli se má použít výchozí analyzátor ("analyzer": null) nebo jiný analyzátor. Analyzátory se používají k tokenizaci textových polí během indexování a k provádění dotazů.

   U vícejazyčných řetězců zvažte použití analyzátoru jazyka.

   U řetězců se spojovníky nebo zvláštními znaky zvažte specializované analyzátory. Jedním z příkladů je klíčové slovo , které zachází s celým obsahem pole jako s jedním tokenem. Toto chování je užitečné pro data, jako jsou PSČ, ID a některé názvy produktů. Další informace najdete v tématu Hledání zkrácených termínů a vzorce se zvláštními znaky.

Konfigurace definic polí

Kolekce polí definuje strukturu hledaného dokumentu. Všechna pole mají název, datový typ a atributy.

Nastavení pole jako prohledávatelného, filtrovatelného, řaditelného nebo facetable má vliv na velikost indexu a výkon dotazů. Nenastavujte tyto atributy u polí, na která se nemají odkazovat ve výrazech dotazu.

Pokud pole není nastavené tak, aby bylo prohledávatelné, filtrovatelné, řaditelné nebo facetable, pole se nedá odkazovat v žádném výrazu dotazu. To je žádoucí pro pole, která se nepoužívají v dotazech, ale jsou potřeba ve výsledcích hledání.

Rozhraní REST API mají výchozí přiřazení na základě datových typů, které používá také průvodce importem dat na webu Azure Portal. Sady Azure SDK nemají výchozí hodnoty, ale mají podtřídy polí, které zahrnují vlastnosti a chování, například SearchableField pro řetězce a SimpleField pro primitiva.

Výchozí přiřazení polí pro rozhraní REST API jsou shrnuté v následující tabulce.

Pole řetězců můžou být také volitelně přidružená k analyzátorům a mapám synonym. Pole typu Edm.String , která jsou filtrovatelná, řaditelná nebo facetable, můžou mít maximálně 32 kilobajtů. Důvodem je, že hodnoty těchto polí se považují za jeden hledaný termín a maximální délka termínu ve službě Azure AI Vyhledávač je 32 kilobajtů. Pokud potřebujete do jednoho textového pole uložit více textu, měli byste v definici indexu explicitně nastavit vlastnosti filtrovatelné, řaditelné a rozčlenitelné na skupiny na false.

Vektorová pole musí být přidružená k dimenzím a vektorovým profilům. Načitatelné je ve výchozím nastavení nastaveno na hodnotu true, pokud přidáte vektorové pole pomocí Průvodce importem dat na webu Azure portál. Pokud používáte rozhraní REST API, je to nepravda.

Atributy pole jsou popsány v následující tabulce.

Povolené aktualizace existujících indexů

Vytvořit index vytvoří ve vyhledávací službě fyzické datové struktury (soubory a invertované indexy). Po vytvoření indexu může vaše schopnost projevit změny pomocí funkce Vytvořit nebo Aktualizovat index na základě toho, jestli vaše úpravy zneplatní tyto fyzické struktury. Většinu atributů pole nelze po vytvoření pole v indexu změnit.

Pokud chcete minimalizovat četnost změn v kódu aplikace, můžete vytvořit alias indexu, který slouží jako stabilní odkaz na index vyhledávání. Místo aktualizace názvů indexů ve vašem kódu můžete aktualizovat alias indexu tak, aby odkazoval na novější verze indexu.

Pokud chcete minimalizovat četnost změn v procesu návrhu, následující tabulka popisuje, které prvky jsou ve schématu pevné a flexibilní. Změna pevného prvku vyžaduje opětovné sestavení indexu, zatímco flexibilní prvky lze kdykoli změnit, aniž by to mělo vliv na fyzickou implementaci. Další informace naleznete v tématu Aktualizace nebo opětovné sestavení indexu.

Nastavení corsOptions pro dotazy mezi zdroji

Schémata indexu obsahují oddíl pro nastavení corsOptions. Ve výchozím nastavení nemůže JavaScript na straně klienta volat žádná rozhraní API, protože prohlížeče blokují všechny křížové požadavky na zdroje. Pokud chcete povolit dotazy mezi zdroji prostřednictvím indexu, povolte CORS (sdílení prostředků mezi zdroji) nastavením atributu corsOptions . Z bezpečnostních důvodů podporují rozhraní API dotazů CORS jenom.

"corsOptions": {
  "allowedOrigins": [
    "*"
  ],
  "maxAgeInSeconds": 300

Pro CORS je možné nastavit následující vlastnosti:

• allowedOrigins (povinné): Toto je seznam původů, které mají povolený přístup k vašemu indexu. Kód JavaScriptu obsluhovaný z těchto zdrojů může přistupovat k vašemu indexu, pokud volající poskytne platný klíč nebo má oprávnění. Každý původ je obvykle ve tvaru protocol://<fully-qualified-domain-name>:<port>, i když <port> je často vynechán. Další informace najdete v tématu Sdílení prostředků mezi různými doménami (Wikipedie).

  Pokud chcete povolit přístup ke všem zdrojům, zahrňte * jako jednu položku do pole allowedOrigins . To není doporučený postup pro produkční vyhledávací služby , ale často je užitečný pro vývoj a ladění.

• maxAgeInSeconds (volitelné): Prohlížeče používají tuto hodnotu k určení doby trvání (v sekundách) pro ukládání předběžných odpovědí CORS do mezipaměti. Musí to být nezáporné celé číslo. Delší období mezipaměti poskytuje lepší výkon, ale prodlužuje dobu, po kterou se zásady CORS musí projevit. Pokud tato hodnota není nastavená, použije se výchozí doba trvání 5 minut.

Další kroky

Pomocí následujících odkazů se dozvíte o specializovaných funkcích, které je možné přidat do indexu:

• Přidání vektorových polí a vektorových profilů
• Přidání profilů bodování
• Přidání sémantického řazení
• Přidat navrhovatele
• Přidejte mapy synonym
• Přidání analyzátorů
• Přidání šifrování

K načtení nebo aktualizaci indexu použijte tyto odkazy:

• Přehled importu dat
• Načtení dokumentů
• Aktualizace nebo opětovné sestavení indexu