Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Note
Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie interfejsy API indeksowania i zapytań, a także interfejsy API wyższego poziomu dla źródeł wiedzy i baz wiedzy do zarządzanego pobierania. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te możliwości lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.
Po utworzeniu indeksu możesz użyć portalu Azure, aby uzyskać dostęp do statystyk i definicji lub usunąć go z usługi IQ usługi Foundry.
Po utworzeniu indeksu możesz użyć interfejsów API REST usługi Foundry IQ, aby uzyskać dostęp do jego statystyk i definicji lub usunąć go z usługi Foundry IQ.
Po utworzeniu indeksu można użyć Azure SDK dla .NET, Java, JavaScript lub Python, aby uzyskać dostęp do statystyk i definicji lub usunąć go z usługi IQ usługi Foundry.
W tym artykule opisano sposób zarządzania indeksem bez wpływu na jego zawartość. Aby uzyskać wskazówki dotyczące modyfikowania definicji indeksu, zobacz Aktualizowanie lub ponowne tworzenie indeksu w Foundry IQ.
Ograniczenia
Poziom cenowy usługi Foundry IQ określa maksymalną liczbę i rozmiar indeksów, pól i dokumentów. Aby uzyskać więcej informacji, zobacz Limity usługi Foundry IQ.
W przeciwnym razie następujące ograniczenia dotyczą zarządzania indeksami:
Nie można ustawić indeksu w trybie offline na potrzeby konserwacji. Indeksy są zawsze dostępne dla operacji wyszukiwania.
Nie można bezpośrednio skopiować ani zduplikować indeksu w obrębie usług Foundry IQ lub między nimi. Przykłady kopii zapasowych i przywracania dla .NET i Python ilustrują eksportowanie definicji i dokumentów. Przed przywróceniem definicji zawierającej wpisy tajne wykonaj czynności opisane w sekcji Tworzenie kopii zapasowej, przywracanie lub klonowanie indeksu. Przykładowy eksport nie jest kopią zapasową poświadczeń.
Obsługa sekretów w definicjach indeksów
Operacje GET i LIST zwracają definicje zasobów, a nie kopie poświadczeń. Odpowiedzi mogą utajniać lub pomijać wpisy tajne potrzebne do utworzenia innego zasobu:
| Configuration | Odczyt reprezentacji | Utwórz lub skopiuj wymaganie |
|---|---|---|
wektoryzator Azure OpenAI azureOpenAIParameters.apiKey |
Zapisany klucz jest zwracany jako <redacted>. |
Podaj klucz zasobu modelu docelowego lub skonfiguruj obsługiwane uwierzytelnianie i autoryzację tożsamości zarządzanej. |
Niestandardowy wektoryzator internetowego interfejsu API customWebApiParameters.httpHeaders |
Każda wartość nagłówka jest zwracana jako <redacted>. |
Podaj wartości nagłówka docelowego punktu końcowego. |
Niestandardowy wektoryzator interfejsu API sieci Web customWebApiParameters.uri |
Poufne wartości kwerendy code i sig są ukrywane. |
Podaj rzeczywiste poświadczenia zapytania docelowego, jeśli jest to wymagane. |
<redacted> i <unchanged> nie są poświadczeniami. Tylko obsługiwana aktualizacja tego samego istniejącego zasobu i właściwości zawierającej klucz tajny może zachować przechowywaną wartość. Nowy indeks, kopia o zmienionej nazwie lub indeks w innej usłudze nie mają źródłowego sekretu do zachowania. Nie zakładaj, że każdy wektoryzator lub interfejs API obsługuje ten sam sposób zachowania.
W przypadku wektoryzatorów Azure OpenAI pominięcie apiKey powoduje wybranie uwierzytelniania tożsamością zarządzaną zgodnie z kontraktem uwierzytelniania wektoryzatora. Pominięcie nie jest neutralnym stanem „skonfiguruj później”. Przed użyciem tego trybu skonfiguruj wybraną tożsamość usługi Search i przypisania ról dla zasobu modelu dla niej.
Tworzenie indeksu przy użyciu klucza modelu
Poniższa kompletna treść REST tworzy indeks przy użyciu wdrożenia text-embedding-3-small. Najpierw zastąp wartości zasobu i wdrożenia wartościami z konfiguracji modelu. Przed wysłaniem żądania zastąp ${AZURE_OPENAI_API_KEY} kluczem w kliencie. Ta notacja to podstawianie po stronie klienta, a nie interpolacja po stronie usługi. Nie wysyłaj dosłownej nazwy zmiennej ani nie przechowuj podstawionej treści w kontroli źródła lub dziennikach.
Użyj istniejącego uwierzytelniania wyszukiwania, aby wysłać POST https://<search-service>.search.windows.net/indexes?api-version=2026-10-01 za pomocą polecenia Content-Type: application/json:
{
"name": "model-index",
"fields": [
{ "name": "id", "type": "Edm.String", "key": true },
{
"name": "contentVector", "type": "Collection(Edm.Single)",
"searchable": true, "dimensions": 1536, "vectorSearchProfile": "model-profile"
}
],
"vectorSearch": {
"algorithms": [{ "name": "hnsw", "kind": "hnsw" }],
"profiles": [{
"name": "model-profile", "algorithm": "hnsw", "vectorizer": "model-vectorizer"
}],
"vectorizers": [{
"name": "model-vectorizer", "kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "https://contoso.openai.azure.com",
"deploymentId": "text-embedding-3-small",
"modelName": "text-embedding-3-small",
"apiKey": "${AZURE_OPENAI_API_KEY}"
}
}]
}
}
Dokumentacja: Indeksy — tworzenie.
Zachowaj klucz w aktualizacji tego samego indeksu
Po pomyślnym wykonaniu powyższej operacji tworzenia z rzeczywistym kluczem ta pełna treść żądania aktualizuje opis tego samego indeksu przy zachowaniu jego przechowywanego klucza. Wyślij PUT https://<search-service>.search.windows.net/indexes/model-index?api-version=2026-10-01 z tym samym uwierzytelnianiem usługi Search i typem zawartości JSON.
W tym przykładzie nazwa wektoryzatora, rodzaj, identyfikator URI zasobu, wdrożenie, model i tryb uwierzytelniania pozostają niezmienione. Wektoryzator Azure OpenAI akceptuje <redacted> lub <unchanged> dla istniejącej wartości apiKey, gdy może dopasować istniejący wektoryzator na podstawie nazwy, rodzaju i identyfikatora URI zasobu. Nie traktuj pominięcia jako zachowania klucza. W przypadku innej konfiguracji modelu lub trybu uwierzytelniania podaj zamierzone poświadczenia lub jawnie skonfiguruj obsługiwaną tożsamość zarządzaną.
{
"name": "model-index", "description": "Updated description",
"fields": [
{ "name": "id", "type": "Edm.String", "key": true },
{
"name": "contentVector", "type": "Collection(Edm.Single)",
"searchable": true, "dimensions": 1536, "vectorSearchProfile": "model-profile"
}
],
"vectorSearch": {
"algorithms": [{ "name": "hnsw", "kind": "hnsw" }],
"profiles": [{
"name": "model-profile", "algorithm": "hnsw", "vectorizer": "model-vectorizer"
}],
"vectorizers": [{
"name": "model-vectorizer", "kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "https://contoso.openai.azure.com",
"deploymentId": "text-embedding-3-small",
"modelName": "text-embedding-3-small",
"apiKey": "<redacted>"
}
}]
}
}
Dokumentacja: Indeksy — tworzenie lub aktualizowanie.
Niestandardowe wektoryfikatory internetowego interfejsu API mają różne reguły zachowywania identyfikatora URI i nagłówka. Te reguły nie zapewniają obsługi zachowywania właściwości innego wektoryzatora.
Rozwiązywanie problemów z błędami weryfikacji poświadczeń
Żądania tworzenia i aktualizacji weryfikują konfigurację przed aprowizowaniem lub zastosowaniem definicji. Nie twórz nieprawidłowego zasobu z symbolami zastępczymi redakcji i zaplanuj jego naprawę później.
Jeśli żądanie nie może dopasować symbolu zastępczego przechowywania do istniejącego wpisu tajnego hasła, podaj rzeczywiste poświadczenia docelowe. Sprawdź nazwę indeksu, nazwę wektoryzatora i rodzaj, punkt końcowy i właściwość. W przypadku niestandardowych błędów dopasowywania zapytań lub nagłówków internetowych interfejsu API postępuj zgodnie z regułami specyficznymi dla właściwości.
W przypadku brakującego lub pustego klucza Azure OpenAI sprawdź, czy chcesz wybrać tożsamość zarządzaną. Sprawdź autoryzację wybranej tożsamości zamiast zakładać, że klucz został zachowany. Nie łącz niezgodnych ustawień uwierzytelniania, takich jak klucz i authIdentity. W przypadku zmiany punktów końcowych, modeli lub uwierzytelniania uzyskaj poświadczenia docelowe lub skonfiguruj tożsamość docelową przed ponownym przesłaniem.
Tworzenie kopii zapasowej, przywracanie lub klonowanie indeksu
Eksportuj definicje i dokumenty możliwe do odzyskania oddzielnie od poświadczeń. Definicje zwracane przez polecenie GET lub LIST mogą zawierać symbole zastępcze redakcji lub pomijać właściwości tylko do zapisu. Przejrzyj kontrakt każdego typu zasobu; wyszukiwanie tylko elementu <redacted> nie jest wystarczające.
Jeśli narzędzie kopii zapasowej kopiuje odpowiedź GET, zmienia tylko nazwę indeksu i przesyła je bez zmian, dostosuj krok przywracania, aby najpierw podać uwierzytelnianie docelowe. Nie używaj tego przepływu pracy bez zmian dla indeksu zawierającego dane tajne.
- Wyeksportuj definicje niesekretowe i dokumenty potrzebne do przywrócenia. Trzymaj sekrety z dala od kopii zapasowych schematu, repozytoriów i dzienników.
- Sprawdź właściwości zawierające wpisy tajne pod kątem zanonimizowanych wartości i pominięć pól tylko do zapisu. Rejestruj wymagane źródła poświadczeń bez rejestrowania samych poświadczeń.
- Mapowanie zależności źródłowych na cel: wdrożenia modelu, połączenia zewnętrzne, konfiguracja bramy, zasady punktu końcowego, tożsamości zarządzane, przypisania ról, łączność prywatna i dostęp do klucza zarządzanego przez klienta.
- Odtwórz zależności docelowe i uprawnienia. Tożsamość nowej usługi IQ rozwiązania Foundry nie dziedziczy ról starej tożsamości ani dostępu do sieci.
- Uzyskiwanie kluczy docelowych, wpisów tajnych OAuth lub innych poświadczeń z bezpiecznego magazynu i wstrzykiwanie ich do klienta przed przesłaniem każdej pełnej definicji. Alternatywnie skonfiguruj jawnie obsługiwany tryb tożsamości zarządzanej. Nie należy przenosić symboli zastępczych zachowywania źródła do żądania utworzenia.
- Utwórz prawidłowe zasoby docelowe w kolejności zależności. Pomyślne utworzenie lub GET nie dowodzi, że model wychodzący lub niestandardowe wywołanie interfejsu API zakończy się powodzeniem.
- Zweryfikuj docelowe uwierzytelnianie, łączność oraz zachowanie modelu lub niestandardowego interfejsu API przy użyciu kontrolowanego żądania. Następnie załaduj dokumenty lub uruchom indeksatory i sprawdź wyniki wyszukiwania przed przełączeniem aplikacji.
Aby uzyskać informacje o przeniesieniu regionu, zobacz Przenoszenie usługi Foundry IQ do innego regionu Azure.
Wyświetlanie wszystkich indeksów
Aby wyświetlić wszystkie indeksy:
Przejdź do usługi Foundry IQ w portalu Azure.
W okienku po lewej stronie wybierz zarządzanie wyszukiwaniem>Indeksy.
Domyślnie indeksy są sortowane według nazwy w kolejności rosnącej. Możesz sortować według nazwy, liczby dokumentów, użycia przydziału indeksu wektorowego lub łącznego rozmiaru magazynu , wybierając odpowiedni nagłówek kolumny.
Użyj Indexes - List (REST API), aby pobrać wszystkie indeksy w usłudze Foundry IQ.
### List all indexes
GET https://[service name].search.windows.net/indexes?api-version=[api version]
Content-Type: application/json
api-key: [admin key]
W interfejsach 2026-10-01 API REST i 2026-11-01-preview operacje listy używają stronicowania po stronie serwera. Gdy dostępnych jest więcej wyników, odpowiedź zawiera adres URL kontynuacji. Postępuj zgodnie z każdym adresem URL kontynuacji, dopóki odpowiedź nie będzie go zawierać. Pełny wzorzec i przykłady można znaleźć w artykule Stronicowanie wyników listy usługi Foundry IQ.
Użyj preferowanego Azure SDK, aby pobrać wszystkie indeksy w usłudze Foundry IQ.
Azure SDK dla .NET zawiera GetIndexesAsync dla tego zadania.
// Create a SearchIndexClient
var endpoint = new Uri("[service endpoint]");
var credential = new AzureKeyCredential("[admin key]");
var indexClient = new SearchIndexClient(endpoint, credential);
// List all indexes
await foreach (var index in indexClient.GetIndexesAsync())
{
Console.WriteLine(index.Name);
}
Operacje wyświetlania listy używające stronicowania po stronie serwera zwracają adres URL kontynuacji, gdy dostępnych jest więcej wyników. Aby zapoznać się z obsługiwanymi wersjami biblioteki klienta i przykładami, zobacz Page through Foundry IQ list results.
Wyświetlanie statystyk indeksu
Na stronie indeksu portal udostępnia następujące statystyki:
- Liczba dokumentów w indeksie.
- Miejsce do magazynowania używane przez indeks.
- Miejsce do magazynowania wektorów używane przez indeks.
- Maksymalna przestrzeń magazynowa dla każdego indeksu w usłudze Foundry IQ, która zależy od planu cenowego. Ta wartość nie reprezentuje całkowitego magazynu obecnie dostępnego dla indeksu.
Użyj Indexes - Get Statistics (REST API), aby uzyskać liczbę dokumentów, wykorzystanie przestrzeni dyskowej oraz wykorzystanie przestrzeni dyskowej wektorowego indeksu.
### Get index statistics
GET https://[service name].search.windows.net/indexes/[index name]/stats?api-version=[api version]
Content-Type: application/json
api-key: [admin key]
Użyj preferowanego usługi SDK Azure, aby pobrać liczbę dokumentów, wykorzystanie magazynu oraz wykorzystanie magazynu wektorowego indeksu.
Azure SDK dla .NET zawiera GetIndexStatisticsAsync dla tego zadania.
// Create a SearchIndexClient
var endpoint = new Uri("[service endpoint]");
var credential = new AzureKeyCredential("[admin key]");
var indexClient = new SearchIndexClient(endpoint, credential);
// Get index statistics
var statsResponse = await indexClient.GetIndexStatisticsAsync("[index name]");
var stats = statsResponse.Value;
Console.WriteLine($"Number of documents: {stats.DocumentCount:N0}");
Console.WriteLine($"Storage consumed by index: {stats.StorageSize:N0} bytes");
Console.WriteLine($"Storage consumed by vectors: {stats.VectorIndexSize:N0} bytes");
Wyświetlanie definicji indeksu
Każdy indeks jest definiowany przez pola i opcjonalne składniki, które zwiększają możliwości wyszukiwania, takie jak analizatory, normalizacje, tokenizatory i mapy synonimów. Ta definicja określa strukturę i zachowanie indeksu podczas indeksowania i wykonywania zapytań.
Użyj Indexes - Get (REST API) do pobrania definicji JSON indeksu.
### Get index definition
GET https://[service name].search.windows.net/indexes/[index name]?api-version=[api version]
Content-Type: application/json
api-key: [admin key]
Użyj preferowanego Azure SDK, aby pobrać definicję JSON indeksu.
Azure SDK dla .NET udostępnia GetIndexAsync dla tego zadania.
// Create a SearchIndexClient
var endpoint = new Uri("[service endpoint]");
var credential = new AzureKeyCredential("[admin key]");
var indexClient = new SearchIndexClient(endpoint, credential);
// Get index definition
var index = await indexClient.GetIndexAsync("[index name]");
string indexJson = JsonSerializer.Serialize(index.Value, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(indexJson);
Usuwanie indeksu
Ostrzeżenie
Nie można cofnąć usuwania indeksu. Przed kontynuowaniem upewnij się, że chcesz trwale usunąć indeks i jego dokumenty z usługi Foundry IQ.
Na stronie indeksu wybierz pozycję Usuń , aby zainicjować proces usuwania.
W portalu zostanie wyświetlony monit o potwierdzenie usunięcia. Po wybraniu pozycji Usuń sprawdź powiadomienia, aby potwierdzić, że usunięcie zakończyło się pomyślnie.
Użyj Usuń indeksy (interfejs API REST) aby trwale usunąć indeks.
### Delete an index
DELETE https://[service name].search.windows.net/indexes/[index name]?api-version=[api version]
Content-Type: application/json
api-key: [admin key]
Jeśli indeks został pomyślnie usunięty, otrzymasz HTTP/1.1 204 No Content odpowiedź.
Użyj preferowanego Azure SDK, aby trwale usunąć indeks.
Azure SDK dla .NET zawiera DeleteIndexAsync dla tego zadania.
// Create a SearchIndexClient
var endpoint = new Uri("[service endpoint]");
var credential = new AzureKeyCredential("[admin key]");
var indexClient = new SearchIndexClient(endpoint, credential);
// Delete the index
await indexClient.DeleteIndexAsync("[index name]");
Console.WriteLine("Index deleted successfully.");