Index létrehozása az Azure AI Keresésben

Ebben a cikkben megismerheti a keresési index sémájának meghatározásának és egy keresési szolgáltatásba való leküldésének lépéseit. Az index létrehozása létrehozza a keresési szolgáltatás fizikai adatstruktúráit. Ha az index létezik, töltse be az indexet külön feladatként.

Előfeltételek

• Egy Azure-előfizetés. Hozzon létre egyet ingyen.

• Egy Azure AI Keresés szolgáltatás, bármely régió és szint, de a szerepköralapú hozzáféréshez számlázható (alapszintű vagy magasabb) szintnek kell lennie.

• Index létrehozásához szükséges engedélyek: Keresési szolgáltatás közreműködői szerepköre vagy rendszergazdai API-kulcs kulcsalapú hitelesítéshez.

• A forrásadatok egyedi mezője, amely az index dokumentumkulcsaként használható.

• Az adatséma ismerete. A mezők kereshetővé, lekérthetővé, szűrhetővé, facetable-sá és rendezhetővé tételével kapcsolatos tervezési útmutatót a séma ellenőrzőlistájában talál.

Index létrehozása

Ha készen áll az index létrehozására, használjon egy keresési ügyfelet, amely elküldheti a kérést. Az Azure Portalt vagy a REST API-kat használhatja a korai fejlesztéshez és a megvalósíthatósági vizsgálathoz, ellenkező esetben gyakran használják az Azure SDK-kat.

A fejlesztés során tervezze meg a gyakori újraépítéseket. Mivel a fizikai struktúrák a szolgáltatásban jönnek létre, az indexek elvetése és újbóli létrehozása számos módosításhoz szükséges. Érdemes lehet az adatok egy részhalmazával dolgozni, hogy az újraépítések gyorsabbak legyenek.

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

Index létrehozásának ellenőrzése

Miután létrehozott egy indexet, ellenőrizze, hogy létezik-e, ha felsorolja az indexeket a keresési szolgáltatásban.

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

Dokumentum kulcsok

A keresési index létrehozásának két követelménye van: az indexnek egyedi névvel kell rendelkeznie a keresési szolgáltatásban, és rendelkeznie kell egy dokumentumkulcstal. Egy mező logikai key attribútuma igaz értékre állítható, amely jelzi, hogy melyik mező biztosítja a dokumentumkulcsot.

A dokumentumkulcs a keresési dokumentum egyedi azonosítója, a keresődokumentum pedig olyan mezők gyűjteménye, amelyek teljesen leírnak valamit. Ha például egy filmadatkészletet indexel, a keresődokumentum egy film címét, műfaját és időtartamát tartalmazza. A filmnevek egyediek ebben az adatkészletben, ezért a film nevét használhatja dokumentumkulcsként.

Az Azure AI Keresésben a dokumentumkulcs egy sztring, amely az indexelendő tartalmat biztosító adatforrás egyedi értékeiből származik. A keresési szolgáltatás általában nem hoz létre kulcsértékeket, de bizonyos esetekben (például az Azure-tábla indexelője) szintetizálja a meglévő értékeket, hogy egyedi kulcsot hozzon létre az indexelt dokumentumokhoz. Egy másik forgatókönyv az egy-a-többhöz indexelés a darabolt vagy particionált adatok esetében, amely esetben minden egyes darabhoz dokumentumkulcsokat hoznak létre.

A növekményes indexelés során, ahol új és frissített tartalom indexelődik, a rendszer új kulcsokkal rendelkező bejövő dokumentumokat ad hozzá, míg a meglévő kulcsokkal rendelkező bejövő dokumentumokat egyesítik vagy felülírják attól függően, hogy az indexmezők null értékűek vagy fel vannak-e töltve.

A dokumentumkulcsokkal kapcsolatos fontos szempontok a következők:

• Egy kulcsmező értékeinek maximális hossza 1024 karakter.
• Minden indexben pontosan egy legfelső szintű mezőt kell kiválasztani kulcsmezőként, és típusának Edm.Stringkell lennie.
• Az attribútum alapértelmezése key az egyszerű mezők esetében hamis, az összetett mezők esetében null.

A kulcsmezők a dokumentumok közvetlen keresésére és adott dokumentumok frissítésére vagy törlésére használhatók. A kulcsmezők értékei kis- és nagybetű-érzékenyek, amikor dokumentumokat keresünk vagy indexelünk. A részletekért lásd a GET Dokumentum (REST) és az Indexdokumentumok (REST) című témakört.

Séma ellenőrzőlista

Ezzel az ellenőrzőlistával segítheti a keresési indexével kapcsolatos tervezési döntéseit.

1. Tekintse át az elnevezési konvenciókat, hogy az index- és mezőnevek megfeleljenek az elnevezési szabályoknak.

2. Nézze át a támogatott adattípusokat. Az adattípus befolyásolja a mező használatának módját. A numerikus tartalom például szűrhető, de teljes szöveges tartalomként nem kereshető. A leggyakoribb adattípus kereshető szöveg esetén a Edm.String, amelynek tokenizálása és lekérdezése a teljes szöveges keresőmotor használatával történik. A vektormezők leggyakoribb adattípusa az, Edm.Single de más típusokat is használhat.

3. Adja meg az index leírását, legfeljebb 4000 karaktert. Ez az ember által olvasható szöveg felbecsülhetetlen értékű, ha egy rendszernek több indexhez kell hozzáférnie, és a leírás alapján döntést kell hoznia. Fontolja meg a Model Context Protocol (MCP) kiszolgálót, amely futásidőben a megfelelő indexet kell kiválasztania. A döntés a leíráson alapulhat, és nem csak az index neve alapján.

4. Azonosítson egy dokumentumkulcsot. A dokumentumkulcs indexkövetelmény. Egyetlen sztringmező, amely egyedi értékeket tartalmazó forrásadatmezőből van kitöltve. Ha például a Blob Storage-ból indexel, a metaadattár elérési útja gyakran használatos dokumentumkulcsként, mert egyedileg azonosít a tárolóban lévő minden egyes blobot.

5. Azonosítsa az adatforrás azon mezőit, amelyek kereshető tartalommal járulnak hozzá az indexben.

   A kereshető nem-vektoriális tartalom rövid vagy hosszú karakterláncokat tartalmaz, amelyeket a teljes szöveges keresőmotorral kérdeznek le. Ha a tartalom részletes (kis kifejezések vagy nagyobb adattömbök), kísérletezzen különböző elemzőkkel, hogy lássa, hogyan történik a szöveg tokenizálása.

   A kereshető vektortartalmak lehetnek képek vagy szövegek (bármilyen nyelven), amelyek matematikai ábrázolásként léteznek. A vektormezők kicsinyítéséhez keskeny adattípusokat vagy vektortömörítést használhat.

   A mezőkön beállított attribútumok ( például retrievable vagy filterable) meghatározzák a keresési viselkedést és az index fizikai megjelenítését a keresési szolgáltatásban. A mezők attribútumainak meghatározása sok fejlesztő számára iteratív folyamat. Az iterációk felgyorsítása érdekében kezdjen mintaadatokkal, hogy könnyen eldobhassa és újraépíthesse azokat.

6. Határozza meg, hogy mely forrásmezők használhatók szűrőkként. A numerikus tartalom és a rövid szövegmezők, különösen az ismétlődő értékekkel rendelkezők jó választást jelentenek. Szűrők használatakor ne feledje:

   • Szűrők vektoros és nem vektoros lekérdezésekben is használhatók, de maga a szűrő az index emberi olvasásra alkalmas (nem vektoros) mezőkre lesz alkalmazva.

   • Szűrhető mezők opcionálisan használhatók a szűrőalapú navigációban.

   • A szűrhető mezők tetszőleges sorrendben jelennek meg, és nem kerülnek relevancia szerinti pontozásba, ezért érdemes lehet őket is rendezhetővé tenni.

7. Vektormezők esetén adja meg a vektorkeresés konfigurációját, valamint a navigációs útvonalak létrehozásához és a beágyazási terület kitöltéséhez használt algoritmusokat. További információ: Vektormezők hozzáadása.

   A vektormezők olyan extra tulajdonságokkal rendelkeznek, amelyekkel a nem vektormezők nem rendelkeznek, például hogy mely algoritmusokat kell használni és a vektortömörítés.

   A vektormezők kihagyják azokat az attribútumokat, amelyek nem hasznosak a vektoradatok esetén, például a rendezést, a szűrést és a facettázást.

8. A nem vektorterek esetében döntse el, hogy az alapértelmezett elemzőt ("analyzer": null) vagy egy másik elemzőt használja-e. Az elemzők a szövegmezők tokenizálására szolgálnak az indexelés és a lekérdezés-végrehajtás során.

   Többnyelvű sztringek esetén fontolja meg a nyelvelemző használatát.

   Kötőjeles sztringek vagy speciális karakterek esetén fontolja meg a speciális elemzőket. Ilyen például a kulcsszó , amely egy mező teljes tartalmát egyetlen jogkivonatként kezeli. Ez a viselkedés olyan adatok esetében hasznos, mint az irányítószámok, az azonosítók és néhány terméknév. További információért lásd: Részleges kifejezéskeresés és minták speciális karakterekkel.

Meződefiníciók konfigurálása

A mezők gyűjteménye határozza meg a keresési dokumentum struktúráját. Minden mező rendelkezik névvel, adattípussal és attribútumokkal.

Ha egy mezőt kereshető, szűrhető, rendezhető vagy facetable típusúként állít be, az hatással van az index méretére és a lekérdezési teljesítményre. Ne állítsa be ezeket az attribútumokat olyan mezőkre, amelyekre nem kíván hivatkozni a lekérdezési kifejezésekben.

Ha egy mező nincs beállítva kereshető, szűrhető, rendezhető vagy facetable értékűre, akkor a mező nem hivatkozható egyetlen lekérdezési kifejezésben sem. Ez a lekérdezésekben nem használt, de a keresési eredményekben szükséges mezők esetében kívánatos.

A REST API-k alapértelmezett hozzárendeléssel rendelkeznek az adattípusok alapján, amelyet az Adatok importálása varázsló is használ az Azure Portalon. Az Azure SDK-k nem rendelkeznek alapértelmezett értékekkel, de olyan mező-alosztályokkal rendelkeznek, amelyek tulajdonságokat és viselkedéseket tartalmaznak, például a sztringek kereshető mezője és a SimpleField a primitívek számára.

A REST API-k alapértelmezett mező-hozzárendeléseit az alábbi táblázat foglalja össze.

A sztringmezők opcionálisan társíthatók elemzőkkel és szinonimatérképekkel is. A szűrhető, rendezhető vagy facetable típusú Edm.String mezők hossza legfeljebb 32 kilobájt lehet. Ennek az az oka, hogy az ilyen mezők értékei egyetlen keresési kifejezésként vannak kezelve, és az Azure AI Keresésben egy kifejezés maximális hossza 32 kilobájt. Ha ennél több szöveget kell tárolnia egyetlen sztringmezőben, az indexdefinícióban explicit módon false értékre kell beállítania a szűrhetőséget, rendezhetőséget és a facetable tulajdonságot.

A vektormezőket dimenziókkal és vektorprofilokkal kell társítani. A visszakereshető érték alapértelmezés szerint igaz, ha a vektormezőt az Adatok importálása varázslóval adja hozzá az Azure portálon. Ha a REST API-t használja, az hamis.

A mezőattribútumokat az alábbi táblázat ismerteti.

Meglévő indexek engedélyezett frissítései

Az Index létrehozása létrehozza a fizikai adatstruktúrákat (fájlokat és fordított indexeket) a keresési szolgáltatásban. Az index létrehozása után az Index létrehozása vagy frissítése funkcióval végrehajtott módosítások attól függenek, hogy a módosítások érvénytelenítenék-e ezeket a fizikai struktúrákat. A legtöbb mezőattribútum nem módosítható, ha a mező létrejött az indexben.

Az alkalmazáskódban a változás minimalizálása érdekében létrehozhat egy index aliast, amely stabil hivatkozásként szolgál a keresési indexre. A kód indexnevekkel való frissítése helyett frissítheti az index aliasát, hogy az újabb indexverziókra mutasson.

A tervezési folyamat során a változás minimalizálása érdekében az alábbi táblázat ismerteti, hogy mely elemek rögzítettek és rugalmasak a sémában. A rögzített elemek módosítása index-újraépítést igényel, míg a rugalmas elemek bármikor módosíthatók a fizikai megvalósítás befolyásolása nélkül. További információ: Index frissítése vagy újraépítése.

Forrásközi lekérdezések beállítása corsOptions

Az indexsémák egy szakaszt tartalmaznak a corsOptions beállításához. Alapértelmezés szerint az ügyféloldali JavaScript nem tud api-kat meghívni, mert a böngészők megakadályozzák az összes forrásközi kérést. Ha engedélyezni szeretné a forrásközi lekérdezéseket az indexen keresztül, engedélyezze a CORS-t (forrásközi erőforrás-megosztást) a corsOptions attribútum beállításával. Biztonsági okokból csak a lekérdezési API-k támogatják a CORS-t.

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

A CORS esetében a következő tulajdonságok állíthatók be:

• allowedOrigins (kötelező): Ez az indexhez hozzáféréssel rendelkező eredetek listája. Az ilyen forrásból kiszolgált JavaScript-kód lekérdezheti az indexet (feltéve, hogy a hívó érvényes kulcsot biztosít vagy rendelkezik engedélyekkel). Az egyes eredetek általában a protocol://<fully-qualified-domain-name>:<port> formájúak, bár a <port> gyakran elmarad. További információ: Forrásközi erőforrás-megosztás (Wikipédia).

  Ha engedélyezni szeretné az összes forráshoz való hozzáférést, az engedélyezettOrigins tömbben egyetlen elemként szerepeljen*. Ez nem ajánlott eljárás éles keresési szolgáltatásokhoz , de gyakran hasznos a fejlesztéshez és a hibakereséshez.

• maxAgeInSeconds (nem kötelező): A böngészők ezt az értéket használják a CORS elővizsgálati válaszok gyorsítótárazási időtartamának (másodpercben) meghatározásához. Ennek nem negatív egész számnak kell lennie. A hosszabb gyorsítótárazási időszak jobb teljesítményt nyújt, de meghosszabbítja azt az időt, amely szükséges ahhoz, hogy a CORS-szabályzat érvénybe lépjen. Ha ez az érték nincs beállítva, a rendszer az alapértelmezett öt perces időtartamot használja.

Következő lépések

Az alábbi hivatkozásokon megismerheti az indexhez hozzáadható speciális funkciókat:

• Vektormezők és vektorprofilok hozzáadása
• Pontozási profilok hozzáadása
• Szemantikai rangsorolás hozzáadása
• Javaslattevők hozzáadása
• Szinonimatérképek hozzáadása
• Elemzők hozzáadása
• Titkosítás hozzáadása

Index betöltéséhez vagy frissítéséhez használja az alábbi hivatkozásokat:

• Adatimportálás áttekintése
• Dokumentumok betöltése
• Index frissítése vagy újraépítése