Verwalten eines Indexes in Foundry IQ (Azure KI-Suche)

Note

Foundry IQ (Azure KI-Suche) bietet direkte Indizierungs- und Abfrage-APIs zusammen mit Wissensquellen- und Knowledge Base-APIs auf höherer Ebene für den verwalteten Abruf. Verwenden Sie das Azure Portal, REST-APIs oder Azure SDKs, um diese Funktionen zu konfigurieren, oder verbinden Sie Agents mit Wissensdatenbanken im Microsoft Foundry-Portal.

Nachdem Sie einen Index erstellt haben, können Sie das Azure Portal verwenden, um auf seine Statistiken und Definition zuzugreifen oder ihn aus Ihrem Foundry IQ-Dienst zu entfernen.

Nachdem Sie einen Index erstellt haben, können Sie die Foundry IQ REST-APIs verwenden, um auf seine Statistiken und Definition zuzugreifen oder ihn aus Ihrem Foundry IQ-Dienst zu entfernen.

Nachdem Sie einen Index erstellt haben, können Sie die Azure SDK für .NET, Java, JavaScript oder Python verwenden, um auf ihre Statistiken und Definition zuzugreifen oder sie aus Ihrem Foundry IQ-Dienst zu entfernen.

In diesem Artikel wird beschrieben, wie Sie einen Index verwalten, ohne sich auf den Inhalt auswirken zu müssen. Hinweise zum Ändern einer Indexdefinition finden Sie unter Aktualisieren oder Neu erstellen eines Indexes in Foundry IQ.

Einschränkungen

Das Preisniveau Ihres Foundry IQ-Diensts bestimmt die maximale Anzahl und Größe Ihrer Indizes, Felder und Dokumente. Weitere Informationen finden Sie unter Dienstlimits in Foundry IQ.

Andernfalls gelten die folgenden Einschränkungen für die Indexverwaltung:

  • Sie können keinen Index zur Wartung offline nehmen. Indizes sind für Suchvorgänge immer verfügbar.

  • Sie können einen Index nicht unmittelbar innerhalb eines Foundry IQ-Dienstes oder dienstübergreifend kopieren bzw. duplizieren. Die Sicherungs- und Wiederherstellungsbeispiele für .NET und Python das Exportieren von Definitionen und Dokumenten veranschaulichen. Bevor Sie eine geheime Definition wiederherstellen, folgen Sie "Sichern", "Wiederherstellen" oder "Klonen eines Indexes". Ein Beispielexport ist keine Sicherung von Anmeldeinformationen.

Umgang mit Geheimnissen in Indexdefinitionen

GET und LIST geben Ressourcendefinitionen zurück, keine Backups von Anmeldeinformationen. Antworten können Geheimnisse, die zum Erstellen einer anderen Ressource erforderlich sind, schwärzen oder weglassen:

Configuration Lesedarstellung Anforderung erstellen oder kopieren
Azure OpenAI-VektorizerazureOpenAIParameters.apiKey Ein gespeicherter Schlüssel wird als <redacted>zurückgegeben. Geben Sie den Schlüssel der Zielmodellressource an, oder konfigurieren Sie unterstützte Verwaltete Identitätsauthentifizierung und Autorisierung.
Benutzerdefinierter Web-API-Vektorizer customWebApiParameters.httpHeaders Jeder Headerwert wird als <redacted>. Geben Sie die Headerwerte des Zielendpunkts an.
Benutzerdefinierter Web-API-Vektorizer customWebApiParameters.uri Vertrauliche code- und sig-Abfragewerte sind geschwärzt. Geben Sie bei Bedarf tatsächliche Zielabfrageanmeldeinformationen an.

<redacted> und <unchanged> sind keine Anmeldeinformationen. Nur eine unterstützte Aktualisierung derselben vorhandenen Ressource und derselben Eigenschaft, die das Geheimnis enthält, kann einen gespeicherten Wert beibehalten. Ein neuer Index, eine umbenannte Kopie oder ein Index in einem anderen Dienst verfügt über kein Quellgeheimnis. Gehen Sie nicht davon aus, dass jeder Vektorisierer oder jede API dasselbe Beibehaltungsverhalten unterstützt.

Bei Azure OpenAI-Vektorizern bewirkt das Weglassen von apiKey, dass die Authentifizierung mit verwalteter Identität gemäß dem Authentifizierungsvertrag des Vektorizers ausgewählt wird. Das Weglassen ist kein neutraler „später konfigurieren“-Zustand. Konfigurieren Sie die ausgewählte Suchidentität und ihre Rollenzuweisungen für Modellressourcen, bevor Sie diesen Modus verwenden.

Erstellen eines Indexes mit einem Modellschlüssel

Der folgende vollständige REST-Text erstellt einen Index mithilfe einer text-embedding-3-small Bereitstellung. Ersetzen Sie zunächst die Ressourcenwert- und Bereitstellungswerte durch Ihre Modellkonfiguration. Ersetzen Sie ${AZURE_OPENAI_API_KEY} durch den Schlüssel in Ihrem Client, bevor Sie die Anforderung senden. Diese Notation ist eine clientseitige Ersetzung, keine dienstseitige Interpolation. Senden Sie die Literalvariable nicht, oder speichern Sie den ersetzten Inhalt nicht in der Quellcodeverwaltung oder in Protokollen.

Verwenden Sie Ihre vorhandene Suchauthentifizierung, um POST https://<search-service>.search.windows.net/indexes?api-version=2026-10-01 mit Content-Type: application/json zu senden:

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

Referenz: Indizes - Erstellen.

Schlüssel bei der Aktualisierung desselben Index beibehalten

Nachdem die vorherige Erstellung mit einem echten Schlüssel erfolgreich war, aktualisiert dieser vollständige Anforderungstext die Beschreibung desselben Indexes, wobei der gespeicherte Schlüssel beibehalten wird. Senden PUT https://<search-service>.search.windows.net/indexes/model-index?api-version=2026-10-01 mit derselben Search-Authentifizierung und dem JSON-Inhaltstyp.

In diesem Beispiel wird der Vektorizername, die Art, der Ressourcen-URI, die Bereitstellung, das Modell und der Authentifizierungsmodus unverändert beibehalten. Der Azure OpenAI-Vektorizer akzeptiert <redacted> oder <unchanged> für das vorhandene apiKey, wenn der vorhandene Vektorizer anhand von Name, Art und Ressourcen-URI abgeglichen werden kann. Behandeln Sie Auslassungen nicht als Beibehaltung von Schlüsseln. Geben Sie für eine andere Modellkonfiguration oder einen anderen Authentifizierungsmodus die vorgesehenen Anmeldeinformationen an, oder konfigurieren Sie die unterstützte verwaltete Identität explizit.

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

Referenz: Indizes – Erstellen oder Aktualisieren.

Benutzerdefinierte Web-API-Vektorisierer weisen unterschiedliche URI- und Header-Erhaltungsregeln auf. Diese Regeln legen keine Unterstützung für die Beibehaltung der Eigenschaften eines anderen Vektorizers fest.

Beheben von Fehlern bei der Überprüfung von Anmeldeinformationen

Anfragen zum Erstellen und Aktualisieren validieren die Konfiguration vor der Bereitstellung oder Anwendung der Definition. Erstellen Sie keine ungültige Ressource mit Redaction-Platzhaltern, und planen Sie die Reparatur danach.

Wenn eine Anfrage keinen vorhandenen geheimen Schlüssel einem Aufbewahrungsplatzhalter zuordnen kann, geben Sie die tatsächlichen Zielanmeldeinformationen an. Überprüfen Sie den Indexnamen, den Vektorizernamen und die Art, den Endpunkt und die Eigenschaft. Befolgen Sie für benutzerdefinierte Web-API-Abfrage- oder Headerabgleichsfehler die eigenschaftsspezifischen Regeln.

Überprüfen Sie bei fehlenden oder leeren Azure OpenAI-Schlüssel, ob Sie die verwaltete Identität auswählen möchten. Überprüfen Sie die Autorisierung der ausgewählten Identität, anstatt davon auszugehen, dass der Schlüssel beibehalten wird. Kombinieren Sie keine inkompatiblen Authentifizierungseinstellungen, z. B. einen Schlüssel und authIdentity. Wenn Sie Endpunkte, Modelle oder Authentifizierung ändern, rufen Sie die Zielanmeldeinformationen ab, oder konfigurieren Sie die Zielidentität, bevor Sie sie erneut übermitteln.

Sichern, Wiederherstellen oder Klonen eines Indexes

Exportieren Sie Definitionen und abrufbare Dokumente separat von Anmeldeinformationen. Von GET oder LIST zurückgegebene Definitionen können Platzhalter für Redaction enthalten oder nur schreibbare Eigenschaften weglassen. Überprüfen Sie die Spezifikation jedes Ressourcentyps; nur nach <redacted> zu suchen, reicht nicht aus.

Wenn ein Sicherungshilfsprogramm die GET-Antwort kopiert, nur den Indexnamen ändert und ihn unverändert sendet, passen Sie den Wiederherstellungsschritt an, um zuerst die Zielauthentifizierung bereitzustellen. Verwenden Sie diesen Workflow nicht unverändert für einen Index mit geheimen Daten.

  1. Exportieren Sie nicht geheime Definitionen und die Dokumente, die Sie für die Wiederherstellung benötigen. Halten Sie Geheimnisse von Schemasicherungen, Repositorys und Protokollen fern.
  2. Überprüfen Sie Eigenschaften, die Geheimnisse enthalten, auf redacted-Werte und Nur-Schreiben-Auslassungen. Notieren Sie die erforderlichen Anmeldeinformationsquellen, ohne die Anmeldeinformationen selbst aufzuzeichnen.
  3. Zuordnen von Quellabhängigkeiten zum Ziel: Modellbereitstellungen, externe Verbindungen, Gatewaykonfiguration, Endpunktrichtlinien, verwaltete Identitäten, Rollenzuweisungen, private Konnektivität und vom Kunden verwalteter Schlüsselzugriff.
  4. Erstellen Sie die Zielabhängigkeiten und die Autorisierung neu. Die Identität eines neuen Foundry IQ-Diensts erbt nicht die Rollen oder den Netzwerkzugriff der alten Identität.
  5. Rufen Sie Zielschlüssel, OAuth-Schlüssel oder andere Anmeldeinformationen aus dem sicheren Speicher ab, und fügen Sie sie in den Client ein, bevor Sie jede vollständige Definition übermitteln. Alternativ können Sie einen explizit unterstützten Modus für verwaltete Identität konfigurieren. Tragen Sie keine Quellbeibehaltungsplatzhalter in eine Erstellungsanforderung.
  6. Erstellen Sie gültige Zielressourcen in Abhängigkeitsreihenfolge. Eine erfolgreiche Erstellung oder GET beweist nicht, dass ein ausgehender Modell- oder benutzerdefinierter API-Aufruf funktioniert.
  7. Überprüfen Sie die Zielauthentifizierung, die Konnektivität und das Modell- oder benutzerdefinierte API-Verhalten mit einer kontrollierten Anforderung. Laden Sie dann Dokumente, oder führen Sie Indexer aus, und überprüfen Sie die Suchergebnisse, bevor Sie Anwendungen wechseln.

Für einen Regionsumzug finden Sie unter Verschieben Ihres Foundry IQ-Diensts in eine andere Azure-Region weitere Informationen.

Alle Indizes anzeigen

So zeigen Sie alle Indizes an

  1. Wechseln Sie im Azure Portal zu Ihrem Foundry IQ Service.

  2. Wählen Sie im linken Bereich "Suchverwaltungsindizes>" aus.

    Screenshot der Seite

    Standardmäßig werden die Indizes nach Namen in aufsteigender Reihenfolge sortiert. Sie können nach Name, Dokumentanzahl, Vektorindexkontingentnutzung oder Gesamtspeichergröße sortieren, indem Sie die entsprechende Spaltenüberschrift auswählen.

Verwenden Sie Indexes - List (REST API), um alle Indizes in Ihrem Foundry IQ-Dienst abzurufen.

### List all indexes
GET https://[service name].search.windows.net/indexes?api-version=[api version]
    Content-Type: application/json
    api-key: [admin key]

In den 2026-10-01 und 2026-11-01-preview REST-APIs verwenden Listenvorgänge eine serverseitige Paginierung. Wenn weitere Ergebnisse verfügbar sind, enthält die Antwort eine Fortsetzungs-URL. Folgen Sie jeder Fortsetzungs-URL, bis sie von einer Antwort weggelassen wird. Die vollständige Vorgehensweise und Beispiele finden Sie unter Page through Foundry IQ list results.

Verwenden Sie Ihre bevorzugte Azure SDK, um alle Indizes für Ihren Foundry IQ-Dienst abzurufen.

Die Azure SDK für .NET stellt GetIndexesAsync für diese Aufgabe bereit.

// 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);
}

Listenvorgänge, die serverseitige Paging verwenden, geben eine Fortsetzungs-URL zurück, wenn weitere Ergebnisse verfügbar sind. Die unterstützten Clientbibliotheksversionen und -beispiele finden Sie unter Durch Foundry IQ-Listenergebnisse blättern.

Anzeigen der Statistiken eines Indexes

Auf der Indexseite stellt das Portal die folgenden Statistiken bereit:

  • Die Anzahl der Dokumente im Index.
  • Vom Index verwendeter Speicherplatz.
  • Vektorspeicherplatz, der vom Index verwendet wird.
  • Maximaler Speicherplatz für jeden Index ihres Foundry IQ-Diensts, der von Ihrem Preisniveau abhängt. Dieser Wert stellt nicht den gesamt für den Index verfügbaren Speicher dar.

Screenshot der Indexstatistiken im Portal.

Verwenden Sie Indizes : Abrufen von Statistiken (REST-API) zum Abrufen der Dokumentanzahl, der Speichernutzung und der Vektorspeichernutzung eines Indexes.

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

Verwenden Sie Ihre bevorzugte Azure SDK, um die Dokumentanzahl, die Speichernutzung und die Vektorspeichernutzung eines Indexes abzurufen.

Die Azure SDK für .NET stellt GetIndexStatisticsAsync für diese Aufgabe bereit.

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

Anzeigen der Definition eines Indexes

Jeder Index wird durch Felder und optionale Komponenten definiert, die Suchfunktionen verbessern, z. B. Analysefunktionen, Normalisierer, Tokenizer und Synonymzuordnungen. Diese Definition bestimmt die Struktur und das Verhalten des Indexes während der Indizierung und Abfrage.

Wählen Sie auf der Indexseite "JSON bearbeiten" aus, um die vollständige Definition anzuzeigen.

Screenshot der Schaltfläche

Verwenden Sie Indizes – ABRUFEN (REST-API), um die JSON-Definition eines Indexes abzurufen.

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

Verwenden Sie Ihre bevorzugte Azure SDK, um die JSON-Definition eines Indexes abzurufen.

Die Azure SDK für .NET stellt GetIndexAsync für diese Aufgabe bereit.

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

Löschen eines Indexes

Warnung

Sie können keine Indexlöschung rückgängigmachen. Bevor Sie fortfahren, stellen Sie sicher, dass Sie den Index und die zugehörigen Dokumente endgültig aus Ihrem Foundry IQ-Dienst entfernen möchten.

Wählen Sie auf der Indexseite " Löschen" aus, um den Löschvorgang zu initiieren.

Screenshot der Schaltfläche

Das Portal fordert Sie auf, den Löschvorgang zu bestätigen. Nachdem Sie "Löschen" ausgewählt haben, überprüfen Sie Ihre Benachrichtigungen, um zu bestätigen, dass der Löschvorgang erfolgreich war.

Screenshot der Löschbestätigung im Portal.

Verwenden Sie Indizes – Löschen (REST-API), um einen Index endgültig zu löschen.

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

Wenn der Index erfolgreich gelöscht wurde, sollten Sie eine HTTP/1.1 204 No Content Antwort erhalten.

Verwenden Sie Ihre bevorzugte Azure SDK, um einen Index endgültig zu löschen.

Die Azure SDK für .NET stellt DeleteIndexAsync für diese Aufgabe bereit.

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