Aktualizace nebo opětovné sestavení indexu v Azure AI Vyhledávač

Tento článek vysvětluje, jak aktualizovat existující index v Azure AI Vyhledávač změnami schématu nebo změnami obsahu prostřednictvím přírůstkového indexování.

Požadavky

• Služba Azure AI Vyhledávač (libovolná úroveň). Vytvořte službu nebo najděte existující.

• Existující index vyhledávání s dokumenty. Tento článek předpokládá, že jste už vytvořili index a načetli dokumenty.

• Oprávnění k aktualizaci nebo opětovnému sestavení indexů:

  • Ověřování na základě klíčů: Klíč rozhraní API správce pro vaši vyhledávací službu.
  • Ověřování na základě role: Role Přispěvatel dat indexu vyhledávání pro aktualizace dokumentů nebo Přispěvatel vyhledávací služby pro změny schématu.

• Pro vývoj sady SDK nainstalujte klientskou knihovnu Azure Search:

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

Aktualizace obsahu

Přírůstkové indexování a synchronizace indexu proti změnám zdrojových dat je zásadní pro většinu vyhledávacích aplikací. Tato část vysvětluje pracovní postup pro přidání, odebrání nebo přepsání obsahu indexu vyhledávání prostřednictvím rozhraní REST API, ale Sady Azure SDK poskytují ekvivalentní funkce.

Text požadavku obsahuje jeden nebo více dokumentů, které se mají indexovat. V rámci požadavku je každý dokument v indexu následující:

• Identifikovaný jedinečným klíčem rozlišující malá a velká písmena.
• Přidruženo k akci: "upload", "delete", "merge" nebo "mergeOrUpload".
• Naplněno sadou párů název/hodnota pro každé pole, které přidáváte nebo aktualizujete.

{  
  "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)  
        ...  
    },  
    ...  
  ]  
}

Reference:Documents – index

• Nejprve použijte rozhraní API pro načítání dokumentů, jako jsou Documents – Index (REST) nebo ekvivalentní rozhraní API v Sady Azure SDK. Další informace o technikách indexování naleznete v tématu Načtení dokumentů.

• U velké aktualizace se doporučuje dávkování (až 1 000 dokumentů na dávku, nebo přibližně 16 MB na dávku, podle toho, co nastane dříve), což výrazně zvyšuje výkon indexování.

• @search.action Nastavte parametr rozhraní API tak, aby určil vliv na existující dokumenty. Slouží mergeOrUpload k přírůstkovým aktualizacím (nejběžnějším) delete k odebrání dokumentů nebo merge k částečným aktualizacím polí u existujících dokumentů.

  Úloha	Účinek
  odstranit	Odebere celý dokument z indexu. Pokud chcete odebrat jednotlivá pole, použijte místo toho sloučení a nastavujte příslušné pole na hodnotu null. Odstraněné dokumenty a pole okamžitě nezabírají místo v indexu. Proces na pozadí provede fyzické odstranění každých několik minut. Ať už k vrácení statistik indexu používáte portál Azure nebo rozhraní API, můžete očekávat malé zpoždění před tím, než se odstranění projeví na portálu Azure a prostřednictvím rozhraní API. Další informace najdete v tématu Odstranění dokumentů v indexu vyhledávání.
  sloučení	Aktualizuje existující dokument a selže, pokud dokument nelze najít. Sloučení nahradí existující hodnoty. Z tohoto důvodu nezapomeňte zkontrolovat pole kolekce, která obsahují více hodnot, například pole typu Collection(Edm.String). Pokud například tags pole začíná hodnotou ["budget"] a provedete sloučení s ["economy", "pool"], konečná hodnota tags pole je ["economy", "pool"]. ["budget", "economy", "pool"] to nebude. Stejné chování platí pro složité kolekce. Pokud dokument obsahuje komplexní pole kolekce s názvem Místnosti s hodnotou [{ "Type": "Budget Room", "BaseRate": 75.0 }], a provedete sloučení s hodnotou [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], bude konečná hodnota pole Místnosti [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. Nepřidá nebo sloučí nové a existující hodnoty.
  mergeOrUpload	Funguje jako sloučení, pokud dokument existuje, a jako nahrání, pokud je dokument nový. Toto je nejběžnější akce pro přírůstkové aktualizace.
  nahrání	Podobně jako "upsert", kde se dokument vloží, pokud je nový, a pokud již existuje, je aktualizován nebo nahrazen. Pokud v dokumentu chybí hodnoty, které index vyžaduje, je hodnota pole dokumentu nastavená na hodnotu null.

Dotazy se budou dál spouštět během indexování, ale pokud aktualizujete nebo odebíráte existující pole, můžete očekávat smíšené výsledky a vyšší výskyt omezování.

Reakce

Stavový kód 200 se vrátí pro úspěšnou odpověď, což znamená, že všechny položky byly uloženy trvale a začnou být indexovány. Indexování běží na pozadí a zpřístupní nové dokumenty (tj. dotazovatelné a prohledávatelné) několik sekund po dokončení operace indexování. Konkrétní zpoždění závisí na zatížení služby.

Úspěšné indexování označuje vlastnost stavu nastavená na hodnotu True pro všechny položky a statusCode vlastnost nastavenou na hodnotu 201 (pro nově nahrané dokumenty) nebo 200 (pro sloučené nebo odstraněné dokumenty):

{
  "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
    }
  ]
}

Stavový kód 207 se vrátí, pokud alespoň jedna položka nebyla úspěšně indexována. Položky, které nebyly indexovány, mají pole stavu nastaveno na false. Vlastnosti errorMessage a statusCode indikují důvod chyby indexování:

{
  "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
    }
  ]
}  

Vlastnost errorMessage označuje důvod chyby indexování, pokud je to možné.

Následující tabulka vysvětluje různé stavové kódy jednotlivých dokumentů, které lze vrátit v odpovědi. Některé stavové kódy označují problémy se samotným požadavkem, zatímco jiné označují dočasné chybové stavy. Druhý pokus byste měli opakovat po zpoždění.

Pokud váš klientský kód často narazí na odpověď 207, je jedním z možných důvodů, proč je systém zatížený. Můžete to potvrdit tak, že zkontrolujete vlastnost statusCode pro 503. Pokud je stavOvý kód 503, doporučujeme požadavky indexování omezovat. Jinak jestliže indexovací provoz neustává, může systém začít odmítat všechny požadavky s chybou 503.

Stavový kód 429 označuje, že jste překročili kvótu počtu dokumentů na index. Musíte buď upgradovat na vyšší limity kapacity , nebo vytvořit nový index.

Tipy pro přírůstkové indexování

• Indexery automatizují přírůstkové indexování. Pokud můžete použít indexer a pokud zdroj dat podporuje sledování změn, můžete indexer spustit podle plánu opakování a přidat, aktualizovat nebo přepsat prohledávatelný obsah tak, aby se synchronizoval s vašimi externími daty.

• Pokud provádíte volání indexu přímo prostřednictvím push API, použijte mergeOrUpload jako akci vyhledávání.

• Datová část musí obsahovat klíče nebo identifikátory každého dokumentu, který chcete přidat, aktualizovat nebo odstranit.

• Pokud index obsahuje vektorová pole a vlastnost nastavíte stored na false, ujistěte se, že jste v částečné aktualizaci dokumentu zadali vektor, i když se hodnota nezmění. Vedlejším účinkem nastavení stored na false je, že vektory se při přeindexaci odstraní. Poskytnutí vektoru v datové části dokumentů zabrání tomu, aby k tomu došlo.

• Chcete-li aktualizovat obsah jednoduchých polí a dílčích polí ve složitých typech, uveďte pouze pole, která chcete změnit. Pokud například potřebujete aktualizovat pole popisu, datová část by se měla skládat z klíče dokumentu a upraveného popisu. Vynechání jiných polí zachová jejich stávající hodnoty.

• Pokud chcete sloučit vložené změny do kolekce řetězců, zadejte celou hodnotu. Vzpomeňte si příklad tags pole z předchozí části. Nové hodnoty přepíší staré hodnoty pro celé pole, aniž by došlo ke sloučení v obsahu pole.

Tady je příklad rozhraní REST API , který ukazuje tyto tipy:

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

Reference:Documents - Index, Lookup Document

Příklady sady SDK

Následující příklady ukazují, jak aktualizovat dokumenty pomocí Sady Azure SDK.

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

Aktualizace schématu indexu

Schéma indexu definuje fyzické datové struktury vytvořené ve vyhledávací službě, takže neexistuje mnoho změn schématu, které můžete provést bez nutnosti úplné opětovné sestavení.

Aktualizace bez opětovného sestavení

Následující seznam uvádí změny schématu, které lze bezproblémově zavést do existujícího indexu. Obecně platí, že seznam obsahuje nová pole a funkce používané při provádění dotazů.

• Přidání popisu indexu
• Přidání nového pole
• Nastavení atributu retrievable u existujícího pole
• Aktualizujte searchAnalyzer u pole, které má existující indexAnalyzer.
• Přidání nové definice analyzátoru do indexu (které lze použít pro nová pole)
• Přidání, aktualizace nebo odstranění hodnoticího profilu
• Přidejte, aktualizujte nebo odstraňte mapy synonym
• Přidání, aktualizace nebo odstranění sémantických konfigurací
• Přidání, aktualizace nebo odstranění nastavení CORS

Pořadí operací je:

1. Získejte definici indexu.

2. Upravte schéma podle aktualizací z předchozího seznamu.

3. Aktualizujte schéma indexu ve vyhledávací službě.

4. Pokud jste přidali nové pole, aktualizujte obsah indexu tak, aby odpovídal upravenému schématu. Pro všechny ostatní změny se použije existující indexovaný obsah as-is.

Když aktualizujete schéma indexu tak, aby zahrnovalo nové pole, stávající dokumenty v indexu mají pro toto pole hodnotu null. V další úloze indexování nahradí hodnoty z externích zdrojových dat hodnoty null přidané Azure AI Vyhledávač.

Během aktualizací by nemělo dojít k přerušení dotazů, ale výsledky dotazů se budou lišit, jak se aktualizace projeví.

Aktualizace vyžadující opětovné sestavení

Některé úpravy vyžadují vyřazení a opětovné sestavení indexu a nahrazení aktuálního indexu novým indexem.

Pořadí operací je:

1. Získejte definici indexu pro případ, že ji potřebujete pro budoucí referenci, nebo ji použít jako základ pro novou verzi.

2. Zvažte použití řešení zálohování a obnovení k zachování kopie obsahu indexu. V C# a v Python existují řešení. Doporučujeme Python verzi, protože je aktuální.

   Pokud máte ve vyhledávací službě kapacitu, ponechte stávající index při vytváření a testování nového indexu.

3. Odstraňte existující index. Dotazy, které cílí na index, se okamžitě zahodí. Mějte na paměti, že odstranění indexu je nevratné, což zničí fyzické úložiště pro kolekci polí a dalších konstrukcí.

4. Publikuje revidovaný index, kde text požadavku obsahuje změněné nebo upravené definice polí a konfigurace.

5. Načtěte dokumenty do indexu z externího zdroje. Dokumenty se indexují pomocí definic polí a konfigurací nového schématu.

Při vytváření indexu je fyzické úložiště přiděleno pro každé pole ve schématu indexu s invertovaným indexem vytvořeným pro každé prohledávatelné pole a vektorový index vytvořený pro každé vektorové pole. Pole, která nejsou prohledávatelná, je možné použít ve filtrech nebo výrazech, ale nemají invertované indexy a nejsou prohledávatelná fulltextově nebo pomocí přibližného vyhledávání. Při opětovném sestavení indexu se tyto invertované indexy a vektorové indexy odstraní a znovu vytvoří na základě zadaného schématu indexu.

Pokud chcete minimalizovat přerušení kódu aplikace, zvažte vytvoření aliasu indexu. Kód aplikace odkazuje na alias, ale můžete aktualizovat název indexu, na který alias odkazuje.

Přidání popisu indexu

Index má description vlastnost, kterou můžete zadat a použít, když systém musí přistupovat k několika indexům a rozhodovat 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 na samotném názvu indexu.

Popis indexu je aktualizace schématu a můžete ji přidat, aniž byste museli znovu sestavit celý index.

• Délka řetězce je maximálně 4 000 znaků.
• Obsah musí být čitelný pro člověka v kódování Unicode. Váš případ použití by měl určit, který jazyk se má použít.

Popis indexu můžete přidat prostřednictvím portálu Azure, nejnovějšího stabilního rozhraní REST API nebo balíčku Azure SDK, který tuto funkci poskytuje.

Vyrovnávání zatížení

Indexování se nespustí na pozadí, ale vyhledávací služba vyrovnává všechny úlohy indexování s průběžnými dotazy. Během indexování můžete monitorovat požadavky na dotazy na portálu Azure, abyste zajistili včasné dokončení dotazů.

Pokud úlohy indexování představují nepřijatelné úrovně latence dotazů, proveďte analýzu výkonu a projděte si tyto tipy k výkonu , které vám pomůžou potenciální zmírnění rizik.

Kontrola aktualizací

Jakmile se načte první dokument, můžete začít dotazovat index. Pokud znáte ID dokumentu, vrátí rozhraní REST API pro vyhledávání dokumentu konkrétní dokument. Pro širší testování byste měli počkat, až se index plně načte, a pak pomocí dotazů ověřte kontext, který očekáváte.

K vyhledání aktualizovaného obsahu můžete použít Průzkumníka služby Search nebo klienta REST .

Pokud jste pole přidali nebo přejmenovali, použijte výběr k vrácení daného pole:

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

Portál Azure poskytuje velikost indexu a velikost vektorového indexu. Tyto hodnoty můžete zkontrolovat po aktualizaci indexu, ale nezapomeňte, že můžete očekávat malé zpoždění, protože služba zpracovává změnu a je třeba brát v úvahu rychlosti obnovování portálu, což může trvat několik minut.

Řešení potíží s přeindexováním

Následující tabulka uvádí běžné problémy při aktualizaci nebo opětovném sestavení indexů a jejich řešení.

Viz také

• Přehled indexeru
• Odstranění dokumentů z indexu vyhledávání
• Indexování velkých datových sad ve velkém měřítku
• Indexování na portálu Azure
• indexer služby Azure SQL Database
• Azure Cosmos DB pro indexer NoSQL
• Azure indexer objektů blob
• indexer tabulek Azure
• Ochrana dat, ochrany osobních údajů a integrovaná ochrana