Aktualizowanie lub ponowne kompilowanie indeksu w usłudze Azure AI Search

Artykuł
12/18/2024

W tym artykule wyjaśniono, jak zaktualizować istniejący indeks w usłudze Azure AI Search przy użyciu zmian schematu lub zmian zawartości za pomocą indeksowania przyrostowego. Wyjaśnia on okoliczności, w których są wymagane ponowne kompilacje, i udostępnia zalecenia dotyczące ograniczania skutków ponownego kompilowania bieżących żądań zapytań.

Podczas aktywnego programowania często porzucanie i ponowne kompilowanie indeksów podczas iteracji nad projektem indeksu. Większość deweloperów współpracuje z małą reprezentatywną próbką swoich danych, aby ponowne indeksowanie przebiegało szybciej.

W przypadku zmian schematu w aplikacjach już w środowisku produkcyjnym zalecamy utworzenie i przetestowanie nowego indeksu uruchamianego obok istniejącego indeksu. Użyj aliasu indeksu, aby zamienić się w nowym indeksie, aby uniknąć zmian w kodzie aplikacji.

Aktualizowanie zawartości

Indeksowanie przyrostowe i synchronizowanie indeksu ze zmianami w danych źródłowych ma podstawowe znaczenie dla większości aplikacji wyszukiwania. W tej sekcji wyjaśniono przepływ pracy aktualizowania zawartości pola w indeksie wyszukiwania za pośrednictwem interfejsu API REST, ale zestawy AZURE SDK zapewniają równoważne funkcje.

Treść żądania zawiera co najmniej jeden dokument do indeksowania. Dokumenty są identyfikowane przez unikatowy klucz uwzględniający wielkość liter. Każdy dokument jest skojarzony z akcją: "upload", "delete", "merge" lub "mergeOrUpload". Żądania przekazywania muszą zawierać dane dokumentu jako zestaw par klucz/wartość.

{  
  "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 (key/value pairs matching index schema)  
        ...  
    },  
    ...  
  ]  
}

Najpierw użyj interfejsów API do ładowania dokumentów, takich jak Dokumenty — indeks (REST) lub równoważny interfejs API w zestawach SDK platformy Azure. Aby uzyskać więcej informacji na temat technik indeksowania, zobacz Ładowanie dokumentów.
W przypadku dużej aktualizacji zalecane jest przetwarzanie wsadowe (do 1000 dokumentów na partię lub około 16 MB na partię, w zależności od tego, co nastąpi wcześniej) i znacznie poprawia wydajność indeksowania.

@search.action Ustaw parametr w interfejsie API, aby określić wpływ na istniejące dokumenty.

Akcja	Efekt
delete	Usuwa cały dokument z indeksu. Jeśli chcesz usunąć pojedyncze pole, użyj scalania, ustawiając pole, którego dotyczy wartość null. Usunięte dokumenty i pola nie zwalniają natychmiast miejsca w indeksie. Co kilka minut proces w tle wykonuje fizyczne usunięcie. Niezależnie od tego, czy używasz witryny Azure Portal, czy interfejsu API do zwracania statystyk indeksu, możesz oczekiwać małego opóźnienia, zanim usunięcie zostanie odzwierciedlone w witrynie Azure Portal i za pośrednictwem interfejsów API.
Scalanie	Aktualizuje dokument, który już istnieje, i kończy się niepowodzeniem dokumentu, którego nie można odnaleźć. Scalanie zastępuje istniejące wartości. Z tego powodu należy sprawdzić pola kolekcji zawierające wiele wartości, takie jak pola typu `Collection(Edm.String)`. Jeśli na przykład `tags` pole rozpoczyna się od wartości `["budget"]` i wykonujesz scalanie z wartością `["economy", "pool"]`, końcową wartością `tags` pola jest `["economy", "pool"]`. Nie będzie `["budget", "economy", "pool"]`to . To samo zachowanie dotyczy złożonych kolekcji. Jeśli dokument zawiera złożone pole kolekcji o nazwie Rooms z wartością `[{ "Type": "Budget Room", "BaseRate": 75.0 }]`, a wykonasz scalanie z wartością , ostateczną wartością `[{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]`pola Pokoje będzie `[{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]`. Nie będzie dołączać ani scalać nowych i istniejących wartości.
mergeOrUpload	Zachowuje się jak scalanie, jeśli dokument istnieje, i przekazuje, czy dokument jest nowy. Jest to najbardziej typowa akcja aktualizacji przyrostowych.
przekaż	Podobnie jak "upsert", w którym dokument jest wstawiany, jeśli jest on nowy, i aktualizowany lub zastępowany, jeśli istnieje. Jeśli w dokumencie brakuje wartości, których indeks wymaga, wartość pola dokumentu jest ustawiona na wartość null.

Zapytania nadal działają podczas indeksowania, ale jeśli aktualizujesz lub usuwasz istniejące pola, możesz oczekiwać mieszanych wyników i większej częstości ograniczania przepustowości.

Uwaga

Nie ma gwarancji kolejności, dla których akcja w treści żądania jest wykonywana jako pierwsza. Nie zaleca się posiadania wielu akcji "scalania" skojarzonych z tym samym dokumentem w jednej treści żądania. Jeśli dla tego samego dokumentu jest wymaganych wiele akcji "scalania", przed zaktualizowaniem dokumentu w indeksie wyszukiwania wykonaj scalanie po stronie klienta.

Odpowiedzi

Kod stanu 200 jest zwracany dla pomyślnej odpowiedzi, co oznacza, że wszystkie elementy zostały trwale przechowywane i zaczną być indeksowane. Indeksowanie jest uruchamiane w tle i udostępnia nowe dokumenty (czyli z możliwością wykonywania zapytań i wyszukiwania) kilka sekund po zakończeniu operacji indeksowania. Określone opóźnienie zależy od obciążenia usługi.

Pomyślne indeksowanie jest wskazywane przez właściwość statusu ustawioną na wartość true dla wszystkich elementów, a także statusCode właściwość ustawioną na wartość 201 (dla nowo przekazanych dokumentów) lub 200 (dla scalonych lub usuniętych dokumentów):

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

Kod stanu 207 jest zwracany, gdy co najmniej jeden element nie został pomyślnie indeksowany. Elementy, które nie zostały indeksowane, mają pole stanu ustawione na wartość false. Właściwości errorMessage i statusCode wskazują przyczynę błędu indeksowania:

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

Właściwość errorMessage wskazuje przyczynę błędu indeksowania, jeśli jest to możliwe.

W poniższej tabeli opisano różne kody stanu poszczególnych dokumentów, które można zwrócić w odpowiedzi. Niektóre kody stanu wskazują problemy z samym żądaniem, podczas gdy inne wskazują tymczasowe warunki błędu. Te ostatnie należy ponowić próbę po opóźnieniu.

Kod stanu	Znaczenie	Ponawianie próby	Uwagi
200	Dokument został pomyślnie zmodyfikowany lub usunięty.	nie dotyczy	Operacje usuwania są idempotentne. Oznacza to, że nawet jeśli klucz dokumentu nie istnieje w indeksie, próba wykonania operacji usuwania z tym kluczem powoduje wyświetlenie kodu stanu 200.
201	Dokument został pomyślnie utworzony.	nie dotyczy
400	Wystąpił błąd w dokumencie, który uniemożliwił indeksowanie.	Nie.	Komunikat o błędzie w odpowiedzi wskazuje, co jest nie tak z dokumentem.
404	Nie można scalić dokumentu, ponieważ dany klucz nie istnieje w indeksie.	Nie.	Ten błąd nie występuje w przypadku przekazywania, ponieważ tworzą nowe dokumenty i nie występuje w przypadku usuwania, ponieważ są idempotentne.
409	Wykryto konflikt wersji podczas próby indeksowania dokumentu.	Tak	Taka sytuacja może wystąpić, gdy równocześnie próbujesz indeksować ten sam dokument więcej niż jeden raz.
422	Indeks jest tymczasowo niedostępny, ponieważ został on zaktualizowany przy użyciu flagi „allowIndexDowntime” ustawionej na wartość „true”.	Tak
503	Usługa wyszukiwania jest tymczasowo niedostępna, prawdopodobnie ze względu na duże obciążenie.	Tak	W takim przypadku należy poczekać przed wykonaniem ponownej próby, aby nie ryzykować przedłużenia niedostępności usługi.

Jeśli kod klienta często napotyka odpowiedź 207, jedną z możliwych przyczyn jest to, że system jest pod obciążeniem. Możesz to potwierdzić, sprawdzając właściwość statusCode dla 503. Jeśli statusCode ma wartość 503, zalecamy ograniczanie żądań indeksowania. W przeciwnym razie, jeśli indeksowanie ruchu nie ustąpi, system może rozpocząć odrzucanie wszystkich żądań z błędami 503.

Kod stanu 429 wskazuje, że przekroczono limit przydziału liczby dokumentów na indeks. Musisz utworzyć nowy indeks lub uaktualnić, aby uzyskać wyższe limity pojemności.

Uwaga

Podczas przekazywania DateTimeOffset wartości z informacjami o strefie czasowej do indeksu usługa Azure AI Search normalizuje te wartości do czasu UTC. Na przykład 2024-01-13T14:03:00-08:00 jest przechowywany jako 2024-01-13T22:03:00Z. Jeśli musisz przechowywać informacje o strefie czasowej, dodaj dodatkową kolumnę do indeksu dla tego punktu danych.

Porady dotyczące indeksowania przyrostowego

Indeksatory automatyzują indeksowanie przyrostowe. Jeśli możesz użyć indeksatora, a źródło danych obsługuje śledzenie zmian, możesz uruchomić indeksator w harmonogramie cyklicznym, aby dodać, zaktualizować lub zastąpić zawartość z możliwością wyszukiwania, aby była synchronizowana z danymi zewnętrznymi.
Jeśli tworzysz wywołania indeksu bezpośrednio za pośrednictwem interfejsu API wypychania, użyj mergeOrUpload jako akcji wyszukiwania.
Ładunek musi zawierać klucze lub identyfikatory każdego dokumentu, który chcesz dodać, zaktualizować lub usunąć.
Jeśli indeks zawiera pola wektorowe, a właściwość ma stored wartość false, upewnij się, że wektor został określony w częściowej aktualizacji dokumentu, nawet jeśli wartość jest niezmieniona. Efektem ubocznym ustawienia stored false jest to, że wektory są porzucane na operację ponownego indeksowania. Podanie wektora w ładunku dokumentów uniemożliwia takie zdarzenie.
Aby zaktualizować zawartość prostych pól i pól podrzędnych w typach złożonych, wyświetl listę tylko pól, które chcesz zmienić. Jeśli na przykład musisz zaktualizować tylko pole opisu, ładunek powinien składać się z klucza dokumentu i zmodyfikowanego opisu. Pominięcie innych pól zachowuje istniejące wartości.
Aby scalić zmiany wbudowane w kolekcję ciągów, podaj całą wartość. tags Przypomnij sobie przykład pola z poprzedniej sekcji. Nowe wartości zastępują stare wartości dla całego pola i nie ma scalania w zawartości pola.

Oto przykład interfejsu API REST pokazujący następujące porady:

### Get Stay-Kay City Hotel by ID
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-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=2024-07-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=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Aktualizowanie schematu indeksu

Schemat indeksu definiuje fizyczne struktury danych utworzone w usłudze wyszukiwania, więc nie ma wielu zmian schematu, które można wprowadzić bez ponoszenia pełnej kompilacji.

Aktualizacje bez ponownej kompilacji

Poniższa lista wylicza zmiany schematu, które można bezproblemowo wprowadzić do istniejącego indeksu. Ogólnie rzecz biorąc, lista zawiera nowe pola i funkcje używane podczas wykonywania zapytania.

Dodaj nowe pole
Ustawianie atrybutu retrievable w istniejącym polu
Aktualizowanie searchAnalyzer pola o istniejącej indexAnalyzer
Dodawanie nowej definicji analizatora w indeksie (które można zastosować do nowych pól)
Dodawanie, aktualizowanie lub usuwanie profilów oceniania
Dodawanie, aktualizowanie lub usuwanie synonimówMapy
Dodawanie, aktualizowanie lub usuwanie konfiguracji semantycznych
Dodawanie, aktualizowanie lub usuwanie ustawień mechanizmu CORS

Kolejność operacji to:

Pobierz definicję indeksu.
Popraw schemat za pomocą aktualizacji z poprzedniej listy.
Zaktualizuj schemat indeksu w usłudze wyszukiwania.
Zaktualizuj zawartość indeksu, aby pasowała do zmienionego schematu, jeśli dodano nowe pole. W przypadku wszystkich pozostałych zmian istniejąca indeksowana zawartość jest używana jako.

Po zaktualizowaniu schematu indeksu w celu uwzględnienia nowego pola istniejące dokumenty w indeksie otrzymują wartość null dla tego pola. W następnym zadaniu indeksowania wartości z danych zewnętrznych źródeł zastępują wartości null dodane przez usługę Azure AI Search.

Podczas aktualizacji nie powinny występować żadne zakłócenia zapytań, ale wyniki zapytania będą się różnić w miarę wprowadzania aktualizacji.

Aktualizacje wymagające ponownej kompilacji

Niektóre modyfikacje wymagają upuszczania i ponownego kompilowania indeksu, zastępując bieżący indeks nowym.

Akcja	opis
Usuwanie pola	Aby fizycznie usunąć wszystkie ślady pola, należy ponownie skompilować indeks. Gdy natychmiastowa ponowna kompilacja nie jest praktyczna, można zmodyfikować kod aplikacji, aby przekierować dostęp z dala od przestarzałego pola lub użyć pola wyszukiwania , a następnie wybrać parametry zapytania, aby wybrać pola, które są przeszukiwane i zwracane. Fizycznie definicja i zawartość pola pozostają w indeksie do momentu następnego ponownego skompilowania, po zastosowaniu schematu, który pomija pole, którego dotyczy.
Zmienianie definicji pola	Poprawki nazwy pola, typu danych lub określonych atrybutów indeksu (z możliwością wyszukiwania, filtrowania, sortowania, tworzenia aspektów) wymagają pełnej kompilacji.
Przypisywanie analizatora do pola	Analizatory są definiowane w indeksie, przypisywane do pól, a następnie wywoływane podczas indeksowania w celu informowania o tworzeniu tokenów. W dowolnym momencie można dodać nową definicję analizatora do indeksu, ale można przypisać tylko analizator po utworzeniu pola. Dotyczy to zarówno właściwości analyzer , jak i indexAnalyzer . Właściwość searchAnalyzer jest wyjątkiem (tę właściwość można przypisać do istniejącego pola).
Aktualizowanie lub usuwanie definicji analizatora w indeksie	Nie można usunąć ani zmienić istniejącej konfiguracji analizatora (analizatora, tokenizatora, filtru tokenu lub filtru znaków) w indeksie, chyba że ponownie skompilujesz cały indeks.
Dodawanie pola do sugestora	Jeśli pole już istnieje i chcesz dodać je do konstrukcji sugestorów , skompiluj indeks.
Przełączanie warstw	Uaktualnienia w miejscu nie są obsługiwane. Jeśli potrzebujesz większej pojemności, utwórz nową usługę i od podstaw skompiluj indeksy. Aby zautomatyzować ten proces, możesz użyć przykładowego kodu index-backup-restore w tym repozytorium przykładowym usługi Azure AI Search .NET. Ta aplikacja wykonuje kopię zapasową indeksu w serii plików JSON, a następnie ponownie utworzy indeks w określonej usłudze wyszukiwania.

Kolejność operacji to:

Pobierz definicję indeksu, jeśli potrzebujesz jej do użycia w przyszłości lub jako podstawy dla nowej wersji.
Rozważ użycie rozwiązania do tworzenia kopii zapasowej i przywracania w celu zachowania kopii zawartości indeksu. Istnieją rozwiązania w języku C# i w języku Python. Zalecamy wersję języka Python, ponieważ jest ona bardziej aktualna.

Jeśli masz pojemność w usłudze wyszukiwania, zachowaj istniejący indeks podczas tworzenia i testowania nowego.
Usuń istniejący indeks. Zapytania skierowane do indeksu są natychmiast porzucane. Pamiętaj, że usunięcie indeksu jest nieodwracalne, niszczenie magazynu fizycznego dla kolekcji pól i innych konstrukcji.
Opublikuj poprawiony indeks, w którym treść żądania zawiera zmienione lub zmodyfikowane definicje pól i konfiguracje.
Załaduj indeks z dokumentami ze źródła zewnętrznego. Dokumenty są indeksowane przy użyciu definicji pól i konfiguracji nowego schematu.

Podczas tworzenia indeksu magazyn fizyczny jest przydzielany dla każdego pola w schemacie indeksu z odwróconym indeksem utworzonym dla każdego pola z możliwością wyszukiwania i indeksem wektorowym utworzonym dla każdego pola wektora. Pola, które nie można przeszukiwać, mogą być używane w filtrach lub wyrażeniach, ale nie mają odwróconych indeksów i nie są przeszukiwane pełnotekstowo ani rozmyte. Podczas odbudowy indeksu te odwrócone indeksy i indeksy wektorowe są usuwane i tworzone ponownie na podstawie podanego schematu indeksu.

Aby zminimalizować zakłócenia w kodzie aplikacji, rozważ utworzenie aliasu indeksu. Kod aplikacji odwołuje się do aliasu, ale można zaktualizować nazwę indeksu wskazywanego przez alias.

Równoważenie obciążeń

Indeksowanie nie działa w tle, ale usługa wyszukiwania równoważy wszystkie zadania indeksowania względem bieżących zapytań. Podczas indeksowania można monitorować żądania zapytań w witrynie Azure Portal, aby upewnić się, że zapytania są ukończone w odpowiednim czasie.

Jeśli obciążenia indeksowania wprowadzają niedopuszczalne poziomy opóźnienia zapytań, przeprowadź analizę wydajności i przejrzyj te porady dotyczące wydajności, aby uzyskać potencjalne środki zaradcze.

Sprawdź, czy są aktualizacje

Możesz rozpocząć wykonywanie zapytań dotyczących indeksu zaraz po załadowaniu pierwszego dokumentu. Jeśli znasz identyfikator dokumentu, interfejs API REST wyszukiwania dokumentów zwraca określony dokument. W przypadku szerszego testowania należy poczekać na pełne załadowanie indeksu, a następnie użyć zapytań, aby zweryfikować oczekiwany kontekst.

Aby sprawdzić zaktualizowaną zawartość, możesz użyć Eksploratora wyszukiwania lub klienta REST.

Jeśli dodano lub zmieniono nazwę pola, użyj opcji wybierz , aby zwrócić to pole:

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

Witryna Azure Portal udostępnia rozmiar indeksu i rozmiar indeksu wektora. Te wartości można sprawdzić po zaktualizowaniu indeksu, ale pamiętaj, aby spodziewać się małego opóźnienia, ponieważ usługa przetwarza zmianę i uwzględnia częstotliwość odświeżania portalu, co może potrwać kilka minut.

Usuwanie oddzielonych dokumentów

Usługa Azure AI Search obsługuje operacje na poziomie dokumentu, dzięki czemu można wyszukiwać, aktualizować i usuwać określony dokument w izolacji. W poniższym przykładzie pokazano, jak usunąć dokument.

Usunięcie dokumentu nie powoduje natychmiastowego zwolnienia miejsca w indeksie. Co kilka minut proces w tle wykonuje fizyczne usunięcie. Niezależnie od tego, czy używasz witryny Azure Portal, czy interfejsu API do zwracania statystyk indeksu, możesz oczekiwać małego opóźnienia, zanim usunięcie zostanie odzwierciedlone w witrynie Azure Portal i metrykach interfejsu API.

Zidentyfikuj, które pole jest kluczem dokumentu. W witrynie Azure Portal można wyświetlić pola poszczególnych indeksów. Klucze dokumentów są polami ciągów i są oznaczone ikoną klucza, aby ułatwić ich odnajdowanie.
Sprawdź wartości pola klucza dokumentu: search=*&$select=HotelId. Prosty ciąg jest prosty, ale jeśli indeks używa pola zakodowanego w formacie base-64 lub jeśli dokumenty wyszukiwania zostały wygenerowane na podstawie parsingMode ustawienia, możesz pracować z wartościami, których nie znasz.
Wyszukaj dokument , aby sprawdzić wartość identyfikatora dokumentu i przejrzeć jego zawartość przed jego usunięciem. Określ klucz lub identyfikator dokumentu w żądaniu. W poniższych przykładach przedstawiono prosty ciąg dla przykładowego indeksu Hotels i zakodowany ciąg base-64 dla klucza metadata_storage_path indeksu cog-search-demo.
```
GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2024-07-01
```
```
GET https://[service name].search.windows.net/indexes/cog-search-demo/docs/aHR0cHM6Ly9oZWlkaWJsb2JzdG9yYWdlMi5ibG9iLmNvcmUud2luZG93cy5uZXQvY29nLXNlYXJjaC1kZW1vL2d1dGhyaWUuanBn0?api-version=2024-07-01
```

Usuń dokument przy użyciu usuwania @search.action , aby usunąć go z indeksu wyszukiwania.

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/index?api-version=2024-07-01
Content-Type: application/json   
api-key: [admin key] 
{  
  "value": [  
    {  
      "@search.action": "delete",  
      "id": "1111"  
    }  
  ]  
}

Udostępnij za pośrednictwem