Index frissítése vagy újraépítése a Azure AI Keresés

Ez a cikk azt ismerteti, hogyan frissíthet egy meglévő indexet Azure AI Keresés sémaváltozásokkal vagy tartalomváltozásokkal növekményes indexeléssel.

Előfeltételek

• Egy Azure AI Keresés szolgáltatás (bármely szint). Szolgáltatás létrehozása vagy találjon meg egy meglévőt.

• Meglévő keresési index dokumentumokkal. Ez a cikk feltételezi, hogy már létrehozott egy indexet és betöltött dokumentumokat.

• Indexek frissítésére vagy újraépítésére vonatkozó engedélyek:

  • Kulcsalapú hitelesítés: A keresési szolgáltatás rendszergazdai API-kulcsa .
  • Szerepköralapú hitelesítés: Keresési index adatszolgáltató szerepköre a dokumentumfrissítésekhez, vagy keresési szolgáltatás hozzájárulója a sémamódosításokhoz.

• SDK-fejlesztéshez telepítse a Azure Search ügyfélkódtárat:

  • Python: azure-search-documents
  • .NET: Azure. Search.Documents
  • JavaScript: @azure/search-documents
  • Java: azure-search-documents

Tartalom frissítése

Az index növekményes indexelése és szinkronizálása a forrásadatok változásaival alapvető fontosságú a legtöbb keresési alkalmazás számára. Ez a szakasz a keresési index tartalmának REST API-val történő hozzáadására, eltávolítására vagy felülírására szolgáló munkafolyamatot ismerteti, de a Azure SDK-k egyenértékű funkciókat biztosítanak.

A kérelem törzse egy vagy több indexelendő dokumentumot tartalmaz. A kérésen belül az index minden dokumentuma a következő:

• Egyedi, kis- és nagybetű érzékeny kulccsal azonosítva.
• Művelethez társítva: „feltöltés” (upload), „törlés” (delete), „összevonás” (merge) vagy „összevonásVagyFeltöltés” (mergeOrUpload).
• A hozzáadott vagy frissített mezőkhöz tartozó név-érték párok készletével van feltöltve.

{  
  "value": [  
    {  
      "@search.action": "upload (default) | merge | mergeOrUpload | delete",  
      "key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)  
      "field_name": field_value (name/value pairs matching index schema)  
        ...  
    },  
    ...  
  ]  
}

Referencia:Dokumentumok – Index

• Először használja az API-kat a dokumentumok betöltéséhez, például a Documents - Index (REST) vagy egy egyenértékű API-t az Azure SDK-kban. További információ az indexelési technikákról: Dokumentumok betöltése.

• Nagy frissítés esetén a kötegelés (kötegenként legfeljebb 1000 dokumentum, vagy kötegenként körülbelül 16 MB, bármelyik korlát is az első) ajánlott, és jelentősen javítja az indexelési teljesítményt.

• Állítsa be a paramétert @search.action az API-n a meglévő dokumentumokra gyakorolt hatás meghatározásához. Növekményes frissítésekhez (leggyakoribb), mergeOrUpload dokumentumok eltávolításához vagy delete meglévő dokumentumok részleges mezőfrissítéseihez használhatómerge.

  Akció	Hatás
  töröl	Eltávolítja a teljes dokumentumot az indexből. Ha el szeretne távolítani egy egyéni mezőt, használja az egyesítést, és állítsa a kérdéses mezőt null értékre. A törölt dokumentumok és mezők nem szabadít fel azonnal helyet az indexben. Néhány percenként egy háttérfolyamat végrehajtja a fizikai törlést. Függetlenül attól, hogy a Azure portált vagy egy API-t használ az indexstatisztikák visszaadásához, kis késésre számíthat, mielőtt a törlés megjelenik a Azure portálon és API-kon keresztül. További információ: Dokumentumok törlése keresési indexben.
  egyesít	Frissíti a már létező dokumentumot, és sikertelen, ha a dokumentum nem található. Az egyesítés lecseréli a meglévő értékeket. Ezért mindenképpen ellenőrizze, hogy a gyűjteménymezők több értéket tartalmaznak-e, például a típusmezőket Collection(Edm.String). Ha például egy tags mező egy értékkel ["budget"] kezdődik, és amikor ["economy", "pool"]-tel összevonást hajt végre, akkor a tags mező végső értéke a ["economy", "pool"]. Nem lesz ["budget", "economy", "pool"]. Ugyanez a viselkedés összetett gyűjteményekre is vonatkozik. Ha a dokumentum tartalmaz egy Szobák nevű összetett gyűjteménymezőt, amelynek az értéke [{ "Type": "Budget Room", "BaseRate": 75.0 }], és Ön egyesítést hajt végre az [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] értékkel, akkor a Szobák mező végső értéke [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] lesz. Új és meglévő értékek hozzáfűzése és egyesítése nem fog sikerülni.
  mergeOrUpload	Úgy viselkedik, mint az egyesítés, ha a dokumentum létezik, és feltölti, ha a dokumentum új. Ez a növekményes frissítések leggyakoribb művelete.
  feltölt	Hasonlóan az "upsert" művelethez, amikor a dokumentum beillesztésre kerül, ha új, illetve frissítésre vagy cserére kerül, ha már létezik. Ha a dokumentum nem rendelkezik az index által igényelt értékekkel, a dokumentummező értéke null értékre van állítva.

A lekérdezések továbbra is futnak az indexelés során, de ha meglévő mezőket frissít vagy távolít el, vegyes eredményekre és a korlátozás gyakoribb előfordulására számíthat.

Válaszok

A rendszer a 200-ás állapotkódot adja vissza a sikeres válaszhoz, ami azt jelenti, hogy az összes elem tartósan lett tárolva, és elkezd indexelni. Az indexelés a háttérben fut, és az indexelési művelet befejeződése után néhány másodperccel elérhetővé teszi az új dokumentumokat (azaz lekérdezhető és kereshető). Az adott késés a szolgáltatás terhelésétől függ.

A sikeres indexelést jelzi, hogy az állapottulajdonság az összes elem esetében igaz értékre van állítva, valamint a statusCode tulajdonság értéke 201 (újonnan feltöltött dokumentumok esetén) vagy 200 (egyesített vagy törölt dokumentumok esetén):

{
  "value": [
    {
      "key": "unique_key_of_new_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 201
    },
    {
      "key": "unique_key_of_merged_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    },
    {
      "key": "unique_key_of_deleted_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    }
  ]
}

A rendszer a 207-s állapotkódot adja vissza, ha legalább egy elem indexelése sikertelen volt. Az indexeletlen elemek állapotmezője hamis. A errorMessage tulajdonságok az statusCode indexelési hiba okát jelzik:

{
  "value": [
    {
      "key": "unique_key_of_document_1",
      "status": false,
      "errorMessage": "The search service is too busy to process this document. Please try again later.",
      "statusCode": 503
    },
    {
      "key": "unique_key_of_document_2",
      "status": false,
      "errorMessage": "Document not found.",
      "statusCode": 404
    },
    {
      "key": "unique_key_of_document_3",
      "status": false,
      "errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
      "statusCode": 422
    }
  ]
}  

A errorMessage tulajdonság jelzi az indexelési hiba okát, ha lehetséges.

Az alábbi táblázat a válaszban visszaadható dokumentumonkénti állapotkódokat ismerteti. Egyes állapotkódok a kéréssel kapcsolatos problémákat, míg mások átmeneti hibafeltételeket jeleznek. Az utóbbit egy késleltetés után újra meg kell próbálkoznia.

Ha az ügyfélkód gyakran találkozik egy 207-ben megadott válaszsal, az egyik lehetséges ok az, hogy a rendszer terhelés alatt van. Ezt az 503-ra vonatkozó statusCode tulajdonság ellenőrzésével ellenőrizheti. Ha a statusCode értéke 503, javasoljuk az indexelési kérelmek korlátozását. Ellenkező esetben, ha a forgalom indexelése nem csökken, a rendszer 503 hibával elkezdheti elutasítani az összes kérést.

A 429-es állapotkód azt jelzi, hogy túllépte az indexenkénti dokumentumok számával kapcsolatos kvótát. Magasabb kapacitáskorlátokra kell frissítenie , vagy létre kell hoznia egy új indexet.

Tippek növekményes indexeléshez

• Az indexelők automatizálják a növekményes indexelést. Ha használhat indexelőt, és ha az adatforrás támogatja a változáskövetést, az indexelőt ismétlődő ütemezés szerint futtathatja a kereshető tartalom hozzáadásához, frissítéséhez vagy felülírásához, hogy az szinkronizálva legyen a külső adatokkal.

• Ha indexhívásokat indít közvetlenül a leküldéses API-val, használja mergeOrUpload keresési műveletként.

• A hasznos adatnak tartalmaznia kell minden hozzáadni, frissíteni vagy törölni kívánt dokumentum kulcsait vagy azonosítóit.

• Ha az index vektormezőket tartalmaz, és astored tulajdonságot hamis értékre állítja, győződjön meg arról, hogy a vektort a részleges dokumentumfrissítésben adja meg, még akkor is, ha az érték változatlan. Annak a mellékhatása, ha a stored hamis értékre van állítva, hogy a vektorokat eltávolítják egy újraindexelési művelet során. A vektor dokumentumok nyersadataiban való megadása megakadályozza ezt.

• Ha összetett típusok egyszerű mezőinek és almezőinek tartalmát szeretné frissíteni, csak a módosítani kívánt mezőket listázhatja. Ha például csak egy leírásmezőt kell frissítenie, a hasznos adatoknak a dokumentumkulcsból és a módosított leírásból kell állniuk. Ha más mezőket kihagy, az megőrzi a meglévő értékeket.

• Ha a beágyazott módosításokat sztringgyűjteménybe szeretné egyesíteni, adja meg a teljes értéket. Idézze fel az tags előző szakasz mező példáját. Az új értékek felülírják egy teljes mező régi értékeit, és a mező tartalmában nincs egyesítés.

Íme egy REST API-példa , amely az alábbi tippeket mutatja be:

### Get Stay-Kay City Hotel by ID
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2026-04-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

### Change the description, city, and tags for Stay-Kay City Hotel
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search.index?api-version=2026-04-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "value": [
            {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "Description": "I'm overwriting the description for Stay-Kay City Hotel.",
            "Tags": ["my old item", "my new item"],
            "Address": {
                "City": "Gotham City"
                }
            }
        ]
    }
       
### Retrieve the same document, confirm the overwrites and retention of all other values
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2026-04-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Referencia:Dokumentumok – Index, Keresési dokumentum

SDK-példák

Az alábbi példák bemutatják, hogyan frissítheti a dokumentumokat a Azure SDK-k használatával.

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Set up the client
service_name = "<your-search-service-name>"
index_name = "hotels-sample"
api_key = "<your-admin-api-key>"

endpoint = f"https://{service_name}.search.windows.net"
credential = AzureKeyCredential(api_key)
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

# Update documents using merge_or_upload
documents = [
    {
        "HotelId": "1",
        "Description": "Updated description for the hotel.",
        "Tags": ["updated", "renovated"]
    }
]

result = client.merge_or_upload_documents(documents=documents)
print(f"Updated {len(result)} document(s)")

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

// Set up the client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample";
string apiKey = "<your-admin-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Update documents using MergeOrUpload
var batch = IndexDocumentsBatch.MergeOrUpload(
    new[]
    {
        new Hotel { HotelId = "1", Description = "Updated description.", Tags = new[] { "updated", "renovated" } }
    });

IndexDocumentsResult result = await searchClient.IndexDocumentsAsync(batch);
Console.WriteLine($"Updated {result.Results.Count} document(s)");

Indexséma frissítése

Az indexséma meghatározza a keresési szolgáltatásban létrehozott fizikai adatstruktúrákat, így nem sok sémamódosítást hajthat végre teljes újraépítés nélkül.

Frissítések újraépítés nélkül

Az alábbi lista felsorolja azokat a sémamódosításokat, amelyek zökkenőmentesen bevezethetők egy meglévő indexbe. A lista általában a lekérdezés végrehajtása során használt új mezőket és funkciókat tartalmazza.

• Indexleírás hozzáadása
• Új mező hozzáadása
• Az retrievable attribútum beállítása egy meglévő mezőben
• Frissítse a searchAnalyzer egy olyan mezőn, amely már rendelkezik egy indexAnalyzer-vel.
• Új elemződefiníció hozzáadása indexhez (amely új mezőkre alkalmazható)
• Pontozási profilok hozzáadása, frissítése vagy törlése
• Szinonimatérképek hozzáadása, frissítése vagy törlése
• Szemantikai konfigurációk hozzáadása, frissítése vagy törlése
• CORS-beállítások hozzáadása, frissítése vagy törlése

A műveletek sorrendje a következő:

1. Kérje le az indexdefiníciót.

2. Módosítsa a sémát az előző lista frissítéseivel.

3. Frissítse az indexsémát a keresési szolgáltatásban.

4. Ha új mezőt adott hozzá, frissítse az index tartalmát úgy, hogy megfeleljen a módosított sémának. Az összes többi módosítás esetén a meglévő indexelt tartalmat változtatás nélkül használják.

Amikor új mezőre módosít egy indexsémát, az index meglévő dokumentumai null értéket kapnak az adott mezőhöz. A következő indexelési feladatban a külső forrásadatok értékei felülírják a Azure AI Keresés által hozzáadott null értékeket.

A frissítések során nem lehetnek lekérdezési fennakadások, de a lekérdezési eredmények a frissítések érvénybe lépésekor eltérőek lesznek.

Újraépítést igénylő frissítések

Egyes módosításokhoz az indexek elvetése és újraépítése szükséges, és az aktuális indexet egy újra kell cserélni.

A műveletek sorrendje a következő:

1. Szerezze be az indexdefiníciót arra az esetre, ha a jövőben szüksége lenne rá, vagy egy új verzió alapjául szolgál.

2. Fontolja meg biztonsági mentési és visszaállítási megoldás használatát az indextartalom másolatának megőrzéséhez. A C# és Python megoldásokat is kínál. A Python verziót javasoljuk, mert naprakészebb.

   Ha rendelkezik kapacitással a keresési szolgáltatásban, tartsa meg a meglévő indexet az új létrehozása és tesztelése során.

3. A meglévő index elvetése. Az indexet megcélzó lekérdezéseket a rendszer azonnal elveti. Ne feledje, hogy az index törlése visszafordíthatatlan, ami megsemmisíti a mezők gyűjteményének és egyéb szerkezeteinek fizikai tárolását.

4. Módosított index közzététele, amelyben a kérelem törzse módosított vagy módosított meződefiníciókat és konfigurációkat tartalmaz.

5. Töltse be az indexet külső forrásból származó dokumentumokkal. A dokumentumok indexelése az új séma meződefiníciói és konfigurációi alapján történik.

Az index létrehozásakor a rendszer lefoglalja a fizikai tárolót az indexséma egyes mezőihez, az egyes kereshető mezőkhöz pedig fordított indexet, az egyes vektormezőkhöz pedig egy vektorindexet. A nem kereshető mezők szűrőkben vagy kifejezésekben használhatók, de nem rendelkeznek fordított indexekkel, és nem teljes szöveges vagy homályos kereshetőek. Az indexek újraépítésekor ezek az invertált indexek és vektorindexek törlődnek és újra létrejönnek a megadott indexséma alapján.

Az alkalmazáskód megszakadásának minimalizálása érdekében érdemes lehet létrehozni egy index aliast. Az alkalmazáskód az aliasra hivatkozik, de frissítheti annak az indexnek a nevét, amelyre az alias mutat.

Indexleírás hozzáadása

Az index rendelkezik egy description olyan tulajdonságokkal, amelyeket megadhat és használhat, ha egy rendszernek több indexhez kell hozzáférnie, és a leírás alapján kell döntést 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, nem csak az index neve alapján.

Az index leírása sémafrissítés, és hozzáadhatja anélkül, hogy újra kellene építenie a teljes indexet.

• A sztring hossza legfeljebb 4000 karakter lehet.
• A tartalomnak emberi olvasásra alkalmasnak kell lennie Unicode-ban. A használati esetnek meg kell határoznia, hogy melyik nyelvet használja.

Indexleírást a Azure portálon, a legújabb stabil REST API-val vagy a funkciót biztosító Azure SDK csomagon keresztül adhat hozzá.

Terhelések kiegyensúlyozása

Az indexelés nem fut a háttérben, de a keresési szolgáltatás kiegyensúlyozza az indexelési feladatokat a folyamatban lévő lekérdezésekkel. Az indexelés során az Azure portálon monitorozhatja a lekérdezési kérelmeket, hogy a lekérdezések megfelelő időben befejeződjenek.

Ha a számítási feladatok indexelése elfogadhatatlan mértékű lekérdezési késést eredményez, végezzen teljesítményelemzést , és tekintse át ezeket a teljesítménytippeket a lehetséges kockázatcsökkentés érdekében.

Frissítések keresése

Az első dokumentum betöltése után azonnal megkezdheti az index lekérdezését. Ha ismeri egy dokumentum azonosítóját, a Keresési dokumentum REST API visszaadja az adott dokumentumot. A szélesebb körű teszteléshez meg kell várnia, amíg az index teljesen betöltődik, majd lekérdezésekkel ellenőrizheti a várt környezetet.

A frissített tartalom kereséséhez használhatja a Search Explorert vagy a REST-ügyfelet .

Ha hozzáadott vagy átnevezett egy mezőt, akkor a SELECT segítségével kérdezze le azt a mezőt:

"search": "*",
"select": "document-id, my-new-field, some-old-field",
"count": true

A Azure portál indexméretet és vektorindex-méretet biztosít. Az index frissítése után ellenőrizheti ezeket az értékeket, de ne felejtsen el kis késést várni, mivel a szolgáltatás feldolgozza a módosítást, és figyelembe veszi a portál frissítési gyakoriságát, ami néhány perc is lehet.

Újraindexelés hibaelhárítása

Az alábbi táblázat felsorolja az indexek frissítésekor vagy újraépítésénél előforduló gyakori problémákat, valamint azok megoldásának módját.

Lásd még:

• Az Indexelő áttekintése
• Dokumentumok törlése keresési indexből
• Nagy méretű adathalmazok indexelése
• Indexelés a Azure portálon
• Azure SQL Database Indexer
• Azure Cosmos DB NoSQL indexelőhöz
• Azure blob indexelő
• Azure táblák indexelője
• Adatok, adatvédelem és beépített védelem