Aktualizowanie lub ponowne kompilowanie indeksu w Wyszukiwanie AI platformy Azure

W tym artykule wyjaśniono, jak zaktualizować istniejący indeks w Wyszukiwanie AI platformy Azure za pomocą zmian schematu lub zmian zawartości za pomocą indeksowania przyrostowego.

Wymagania wstępne

• Usługa Wyszukiwanie AI platformy Azure (dowolna warstwa). Utwórz usługę lub znajdź istniejącą usługę.

• Istniejący indeks wyszukiwania z dokumentami. W tym artykule założono, że utworzono już indeks i załadowano dokumenty.

• Uprawnienia do aktualizowania lub ponownego kompilowania indeksów:

  • Uwierzytelnianie oparte na kluczach: klucz interfejsu API administratora dla usługi wyszukiwania.
  • Uwierzytelnianie oparte na rolach: rola Współautor danych indeksu wyszukiwania dla aktualizacji dokumentów lub Współautor usługi wyszukiwania dla zmian schematu.

• W przypadku programowania zestawu SDK zainstaluj bibliotekę klienta usługi Azure Search:

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

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 dodawania, usuwania lub zastępowania zawartości indeksu wyszukiwania za pomocą interfejsu API REST, ale Azure SDKs zapewniają równoważne funkcje.

Treść żądania zawiera co najmniej jeden dokument do indeksowania. W żądaniu każdy dokument w indeksie to:

• Zidentyfikowany przez unikatowy klucz z uwzględnieniem wielkości liter.
• Skojarzone z akcją: "upload", "delete", "merge" lub "mergeOrUpload".
• Wypełnione zestawem par nazwa/wartość dla każdego pola, które dodajesz lub aktualizujesz.

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

Dokumentacja:Dokumenty — indeks

• Najpierw użyj interfejsów API do ładowania dokumentów, takich jak Documents — Index (REST) lub równoważnego interfejsu API w Azure SDKs. Aby uzyskać więcej informacji na temat technik indeksowania, zobacz Ładowanie dokumentów.

• W przypadku dużej aktualizacji zalecane jest procesowanie wsadowe (do 1000 dokumentów na partię lub około 16 MB na partię, w zależności od tego, która wartość jest niższa), co znacznie poprawia wydajność indeksowania.

• @search.action Ustaw parametr w interfejsie API, aby określić wpływ na istniejące dokumenty. Służy mergeOrUpload do przyrostowych aktualizacji (najczęściej), delete do usuwania dokumentów lub merge do aktualizowania części pól w istniejących dokumentach.

  Działania	Efekt
  usunąć	Usuwa cały dokument z indeksu. Jeśli chcesz usunąć pojedyncze pole, zamiast tego użyj scalania, ustawiając dane pole na 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 portalu Azure, czy interfejsu API do zwracania statystyk indeksu, możesz oczekiwać małego opóźnienia, zanim usunięcie zostanie odzwierciedlone w portalu Azure i za pośrednictwem interfejsów API. Aby uzyskać więcej informacji, zobacz Usuwanie dokumentów w indeksie wyszukiwania.
  scalać	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 pole tags zaczyna się od wartości ["budget"] i wykonasz scalanie z ["economy", "pool"], to końcowa wartość pola tags wynosi ["economy", "pool"]. To nie będzie ["budget", "economy", "pool"]. To samo zachowanie dotyczy złożonych kolekcji. Jeśli dokument zawiera złożone pole kolekcji o nazwie Pokoje z wartością [{ "Type": "Budget Room", "BaseRate": 75.0 }], a wykonasz scalanie z wartością [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], ostateczną wartością 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, a jak przesyłanie, jeśli dokument jest nowy. Jest to najbardziej typowa operacja aktualizacji przyrostowych.
  przekazywać	Podobnie jak w przypadku operacji "upsert", gdzie dokument jest wstawiany, jeśli jest nowy, lub aktualizowany bądź zastępowany, jeśli już 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.

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ść 'status' ustawioną jako true dla wszystkich elementów, a także przez właściwością statusCode ustawioną jako 201 (dla dokumentów nowo przesłanych) 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. To ostatnie należy spróbować ponownie po opóźnieniu.

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 wartości 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. Należy uaktualnić w celu zwiększenia limitów pojemności lub utworzyć nowy indeks.

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 czynność 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ść jest ustawiona na stored false, upewnij się, że wektor został uwzględniony w częściowej aktualizacji dokumentu, nawet jeśli wartość jest niezmieniona. Efektem ubocznym ustawienia stored na fałsz jest fakt, że wektory są porzucane podczas operacji 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 liniowe w kolekcji 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=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}}

Dokumentacja:Dokumenty — indeks, dokument odnośnika

Przykłady zestawu SDK

W poniższych przykładach pokazano, jak zaktualizować dokumenty przy użyciu Azure SDKs.

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

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.

• Dodawanie opisu indeksu
• Dodawanie nowego pola
• Ustawianie atrybutu retrievable w istniejącym polu
• Aktualizuj searchAnalyzer na polu z istniejącym 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 map synonimów
• Dodawanie, aktualizowanie lub usuwanie konfiguracji semantycznych
• Dodawanie, aktualizowanie lub usuwanie ustawień mechanizmu CORS

Kolejność operacji to:

1. Pobierz definicję indeksu.

2. Popraw schemat za pomocą aktualizacji z poprzedniej listy.

3. Zaktualizuj schemat indeksu w usłudze wyszukiwania.

4. Zaktualizuj zawartość indeksu , aby pasowała do zmienionego schematu, jeśli dodano nowe pole. W przypadku wszystkich innych zmian istniejąca indeksowana zawartość jest używana as-is.

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ętrznego źródła zastępują null-e dodane przez Wyszukiwanie AI platformy Azure.

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.

Kolejność operacji to:

1. Pobierz definicję indeksu , jeśli potrzebujesz jej do użycia w przyszłości lub jako podstawy dla nowej wersji.

2. Rozważ użycie rozwiązania do tworzenia kopii zapasowej i przywracania w celu zachowania kopii zawartości indeksu. Istnieją rozwiązania w C# i w Python. Zalecamy Python wersję, ponieważ jest ona bardziej aktualna.

   Jeśli masz pojemność w usłudze wyszukiwania, zachowaj istniejący indeks podczas tworzenia i testowania nowego.

3. Usuń istniejący indeks. Zapytania skierowane do indeksu są natychmiast porzucane. Pamiętaj, że usunięcie indeksu jest nieodwracalne, co spowoduje zniszczenie fizycznego przechowywania zbioru pól i innych konstrukcji.

4. Opublikuj poprawiony indeks, w którym treść żądania zawiera zmienione lub zmodyfikowane definicje pól i konfiguracje.

5. 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órych nie można wyszukiwać, mogą być używane w filtrach lub wyrażeniach, ale nie mają odwróconych indeksów i nie są przeszukiwane pełnotekstowo ani za pomocą wyszukiwania zbliżonego. 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.

Dodawanie opisu indeksu

Indeks ma description właściwość, którą można określić i użyć, gdy system musi uzyskać dostęp do kilku indeksów i podjąć decyzję na podstawie opisu. Rozważmy serwer protokołu MCP (Model Context Protocol), który musi wybrać prawidłowy indeks w czasie wykonywania. Decyzja może być oparta na opisie, a nie na samej nazwie indeksu.

Opis indeksu to aktualizacja schematu i można ją dodać bez konieczności ponownego kompilowania całego indeksu.

• Długość ciągu wynosi maksymalnie 4000 znaków.
• Zawartość musi być czytelna dla człowieka w formacie Unicode. Przypadek użycia powinien określać język do użycia.

Opis indeksu można dodać za pomocą portalu Azure, najnowszego stabilnego interfejsu API REST lub pakietu Azure SDK, który udostępnia tę funkcję.

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 portalu Azure, aby zapewnić wykonywanie zapytań 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.

Sprawdzanie dostępności aktualizacji

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

Portal Azure udostępnia rozmiar indeksu i rozmiar indeksu wektorowego. 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.

Rozwiązywanie problemów z ponownym indeksowaniem

W poniższej tabeli wymieniono typowe problemy występujące podczas aktualizowania lub ponownego kompilowania indeksów oraz sposobu ich rozwiązywania.

Zobacz też

• Omówienie indeksatora
• Usuwanie dokumentów z indeksu wyszukiwania
• Indeksowanie dużych zestawów danych na dużą skalę
• Indeksowanie w portalu Azure
• Indeksator bazy danych Azure SQL
• Azure Cosmos DB dla indeksatora NoSQL
• Azure indeksator obiektów blob
• indeksator tabel Azure
• Dane, prywatność i wbudowane zabezpieczenia