Samouczek: zestawy umiejętności w usłudze Azure AI Search

Dowiedz się, jak używać zestawu Azure SDK dla platformy .NET do tworzenia potoku wzbogacania sztucznej inteligencji na potrzeby wyodrębniania i przekształcania zawartości podczas indeksowania.

Zestawy umiejętności dodają przetwarzanie AI do surowych treści, sprawiając, że stają się bardziej jednolite i łatwiejsze do wyszukiwania. Gdy już wiesz, jak działają zestawy umiejętności, możesz wspierać szeroki zakres transformacji, od analizy obrazu po przetwarzanie języka naturalnego, aż po zewnętrznie dostarczane, dostosowane przetwarzanie.

W tym samouczku nauczysz się następujących rzeczy:

Zdefiniuj obiekty w procesie wzbogacania.
Tworzenie zestawu umiejętności. Wywołaj rozpoznawanie znaków OCR, wykrywanie języka, rozpoznawanie jednostek i wyodrębnianie kluczowych fraz.
Uruchom potok danych. Tworzenie i ładowanie indeksu wyszukiwania.
Sprawdź wyniki przy użyciu wyszukiwania pełnotekstowego.

Overview

W tym samouczku użyto języka C# i biblioteki klienta Azure.Search.Documents do utworzenia źródła danych, indeksu, indeksatora i zestawu umiejętności.

Indeksator steruje każdym krokem w potoku, począwszy od wyodrębniania zawartości przykładowych danych (tekstów bez struktury i obrazów) w kontenerze blobów na platformie Azure Storage.

Po wyodrębnieniu zawartości, pakiet narzędzi umiejętności wykonuje wbudowane umiejętności firmy Microsoft, aby znaleźć i wyodrębnić informacje. Te umiejętności obejmują optyczne rozpoznawanie znaków (OCR) na obrazach, wykrywanie języka tekstu, wyodrębnianie kluczowych fraz i rozpoznawanie jednostek (organizacje). Nowe informacje utworzone przez zestaw umiejętności są wysyłane do pól w indeksie. Po wypełnieniu indeksu można użyć pól w zapytaniach, aspektach i filtrach.

Prerequisites

Konto Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Azure Storage.
azure AI Search.
Pakiet Azure.Search.Documents.
Visual Studio.

Note

Możesz użyć bezpłatnej usługi wyszukiwania do tego samouczka. Warstwa Bezpłatna ogranicza do trzech indeksów, trzech indeksatorów i trzech źródeł danych. W ramach tego samouczka tworzony jest jeden element każdego z tych typów. Przed rozpoczęciem upewnij się, że masz wystarczającą ilość miejsca w swojej usłudze, aby przyjąć nowe zasoby.

Pobieranie plików

Pobierz plik zip z przykładowego repozytorium danych i wyodrębnij zawartość. Dowiedz się, jak to zrobić.
Pobierz przykładowe pliki danych (nośnik mieszany)

Przekazywanie przykładowych danych do usługi Azure Storage

W usłudze Azure Storage utwórz nowy kontener i nadaj mu nazwę mieszanych typów zawartości.
Przekaż przykładowe pliki danych.
Uzyskaj parametry połączenia magazynu, aby można było sformułować połączenie w usłudze Azure AI Search.
1. Po lewej stronie wybierz pozycję Klucze dostępu.
2. Skopiuj parametry połączenia dla jednego lub drugiego klucza. Łańcuch połączenia jest podobny do poniższego przykładu:
  
  DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net

Narzędzia odlewni

Wbudowane wzbogacanie sztucznej inteligencji jest wspierane przez narzędzia Foundry Tools, w tym język platformy Azure i usługę Azure Vision na potrzeby przetwarzania języka naturalnego i obrazów. W przypadku małych obciążeń, takich jak w tym samouczku, możesz użyć bezpłatnej alokacji 20 transakcji na indeksator. W przypadku większych obciążeń dołącz zasób Microsoft Foundry do zestawu umiejętności w ramach cen Standard.

Kopiowanie adresu URL usługi wyszukiwania i klucza interfejsu API

Na potrzeby tego samouczka połączenia z usługą Azure AI Search wymagają punktu końcowego i klucza API. Te wartości można uzyskać w witrynie Azure Portal.

Zaloguj się do witryny Azure Portal i wybierz usługę wyszukiwania.
W okienku po lewej stronie wybierz pozycję Przegląd i skopiuj punkt końcowy. Powinien mieć następujący format: https://my-service.search.windows.net
W okienku po lewej stronie wybierz pozycję Ustawienia>Klucze i skopiuj klucz administratora, aby uzyskać pełne prawa do usługi. Istnieją dwa zamienne klucze administratora, które zapewniają ciągłość działania na wypadek gdyby trzeba było jednego zastąpić. Możesz użyć któregokolwiek z kluczy w żądaniach, aby dodawać, modyfikować lub usuwać obiekty.

Konfigurowanie środowiska

Zacznij od otwarcia programu Visual Studio i utworzenia nowego projektu aplikacji konsolowej.

Instalowanie pliku Azure.Search.Documents

Zestaw .NET SDK usługi Azure AI Search składa się z biblioteki klienta, która umożliwia zarządzanie indeksami, źródłami danych, indeksatorami i zestawami umiejętności, a także przekazywanie dokumentów i wykonywanie zapytań oraz zarządzanie nimi bez konieczności obsługi szczegółów protokołu HTTP i JSON. Ta biblioteka klienta jest dystrybuowana jako pakiet NuGet.

W tym projekcie zainstaluj wersję 11 lub nowszą Azure.Search.Documents i najnowszą wersję programu Microsoft.Extensions.Configuration.

W programie Visual Studio wybierz pozycję >>
Przeglądaj Azure.Search.Document.
Wybierz najnowszą wersję, a następnie wybierz pozycję Zainstaluj.
Powtórz poprzednie kroki, aby zainstalować plik Microsoft.Extensions.Configuration i Microsoft.Extensions.Configuration.Json.

Dodawanie informacji o połączeniu z usługą

Kliknij prawym przyciskiem myszy na projekcie w Eksploratorze rozwiązań i wybierz Dodaj>Nowy element...
Nadaj plikowi appsettings.json nazwę i wybierz pozycję Dodaj.
Dołącz ten plik do katalogu wyjściowego.
1. Kliknij prawym przyciskiem myszy appsettings.json i wybierz polecenie Właściwości.
2. Zmień wartość Copy to Output Directory na Copy if newer.

Skopiuj poniższy kod JSON do nowego pliku JSON.

{
  "SearchServiceUri": "<YourSearchServiceUri>",
  "SearchServiceAdminApiKey": "<YourSearchServiceAdminApiKey>",
  "SearchServiceQueryApiKey": "<YourSearchServiceQueryApiKey>",
  "AzureAIServicesKey": "<YourMultiRegionAzureAIServicesKey>",
  "AzureBlobConnectionString": "<YourAzureBlobConnectionString>"
}

Dodaj informacje o usłudze wyszukiwania i koncie magazynu blob. Pamiętaj, że te informacje można uzyskać z kroków aprowizacji usług wskazanych w poprzedniej sekcji.

W polu SearchServiceUri wprowadź pełny adres URL.

Dodawanie przestrzeni nazw

W Program.cs dodaj następujące przestrzenie nazw.

using Azure;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Microsoft.Extensions.Configuration;
using System;
using System.Collections.Generic;
using System.Linq;

namespace EnrichwithAI

Tworzenie klienta

Utwórz wystąpienie SearchIndexClient i SearchIndexerClient pod Main.

public static void Main(string[] args)
{
    // Create service client
    IConfigurationBuilder builder = new ConfigurationBuilder().AddJsonFile("appsettings.json");
    IConfigurationRoot configuration = builder.Build();

    string searchServiceUri = configuration["SearchServiceUri"];
    string adminApiKey = configuration["SearchServiceAdminApiKey"];
    string azureAiServicesKey = configuration["AzureAIServicesKey"];

    SearchIndexClient indexClient = new SearchIndexClient(new Uri(searchServiceUri), new AzureKeyCredential(adminApiKey));
    SearchIndexerClient indexerClient = new SearchIndexerClient(new Uri(searchServiceUri), new AzureKeyCredential(adminApiKey));
}

Note

Klienci łączą się z twoją usługą wyszukiwania. Aby uniknąć otwierania zbyt wielu połączeń, spróbuj udostępnić jedną instancję w aplikacji, jeśli to możliwe. Metody są bezpieczne wątkowo, aby umożliwić takie udostępnianie.

Dodawanie funkcji w celu zakończenia programu podczas awarii

Niniejszy samouczek ma pomóc w zrozumieniu każdego kroku procesu indeksowania. Jeśli występuje krytyczny problem uniemożliwiający programowi utworzenie źródła danych, zestawu umiejętności, indeksu lub indeksatora, program wyświetli komunikat o błędzie i zakończy działanie, aby można było zrozumieć i rozwiązać problem.

Dodaj ExitProgram do Main w celu obsługi scenariuszy, które wymagają zakończenia działania programu.

private static void ExitProgram(string message)
{
    Console.WriteLine("{0}", message);
    Console.WriteLine("Press any key to exit the program...");
    Console.ReadKey();
    Environment.Exit(0);
}

Utwórz potok

W usłudze Azure AI Search przetwarzanie sztucznej inteligencji odbywa się podczas indeksowania (lub pozyskiwania danych). Ta część przewodnika tworzy cztery obiekty: źródło danych, definicję indeksu, zestaw umiejętności, indeksator.

Krok 1. Tworzenie źródła danych

SearchIndexerClient ma właściwość DataSourceName, którą można ustawić na obiekt SearchIndexerDataSourceConnection. Ten obiekt udostępnia wszystkie metody, które należy utworzyć, wyświetlić, zaktualizować lub usunąć źródła danych usługi Azure AI Search.

Utwórz nowe SearchIndexerDataSourceConnection wystąpienie, wywołując indexerClient.CreateOrUpdateDataSourceConnection(dataSource). Poniższy kod tworzy źródło danych typu AzureBlob.

private static SearchIndexerDataSourceConnection CreateOrUpdateDataSource(SearchIndexerClient indexerClient, IConfigurationRoot configuration)
{
    SearchIndexerDataSourceConnection dataSource = new SearchIndexerDataSourceConnection(
        name: "demodata",
        type: SearchIndexerDataSourceType.AzureBlob,
        connectionString: configuration["AzureBlobConnectionString"],
        container: new SearchIndexerDataContainer("mixed-content-type"))
    {
        Description = "Demo files to demonstrate Azure AI Search capabilities."
    };

    // The data source does not need to be deleted if it was already created
    // since we are using the CreateOrUpdate method
    try
    {
        indexerClient.CreateOrUpdateDataSourceConnection(dataSource);
    }
    catch (Exception ex)
    {
        Console.WriteLine("Failed to create or update the data source\n Exception message: {0}\n", ex.Message);
        ExitProgram("Cannot continue without a data source");
    }

    return dataSource;
}

W przypadku pomyślnego żądania metoda zwraca utworzone źródło danych. Jeśli występuje problem z żądaniem, taki jak nieprawidłowy parametr, metoda zgłasza wyjątek.

Teraz dodaj wiersz w Main, aby wywołać funkcję, którą właśnie dodałeś.

// Create or Update the data source
Console.WriteLine("Creating or updating the data source...");
SearchIndexerDataSourceConnection dataSource = CreateOrUpdateDataSource(indexerClient, configuration);

Skompiluj i uruchom rozwiązanie. Ponieważ jest to pierwsze żądanie, sprawdź witrynę Azure Portal, aby potwierdzić, że źródło danych zostało utworzone w usłudze Azure AI Search. Na stronie przeglądu usługi wyszukiwania sprawdź, czy lista Źródła danych zawiera nowy element. Może być konieczne odczekenie kilku minut na odświeżenie strony witryny Azure Portal.

Krok 2. Tworzenie zestawu umiejętności

W tej sekcji zdefiniujesz zestaw kroków wzbogacania, które chcesz zastosować do danych. Każdy krok wzbogacania jest nazywany umiejętnością i zestawem kroków wzbogacania, zestawu umiejętności. W tym samouczku są używane wbudowane umiejętności dla zestawu umiejętności :

Optyczne rozpoznawanie znaków w celu rozpoznawania tekstu drukowanego i odręcznego w plikach obrazów.
Połączenie tekstu w celu skonsolidowania tekstu z kolekcji pól w jedno pole "scalonej zawartości".
Wykrywanie języka — identyfikowanie języka zawartości.
Rozpoznawanie jednostek do wyodrębniania nazw organizacji z zawartości w kontenerze obiektów blob.
Podział tekstu w celu podzielenia dużej zawartości na mniejsze fragmenty przed wywołaniem umiejętności wyodrębniania kluczowych fraz i umiejętności rozpoznawania jednostek. Wyodrębnianie kluczowych fraz i rozpoznawanie jednostek akceptuje dane wejściowe o 50 000 znaków lub mniej. Kilka przykładowych plików należy podzielić, aby zmieścić się w tym limicie.
Wyodrębnianie kluczowych fraz — określanie najczęściej występujących fraz kluczowych.

Podczas początkowego przetwarzania usługa Azure AI Search pęka w każdym dokumencie w celu wyodrębnienia zawartości z różnych formatów plików. Tekst pochodzący z pliku źródłowego jest umieszczany w wygenerowanym content polu , po jednym dla każdego dokumentu. W związku z tym ustaw dane wejściowe tak "/document/content" , aby używały tego tekstu. Zawartość obrazu jest umieszczana w wygenerowanym normalized_images polu określonym w zestawie umiejętności jako /document/normalized_images/*.

Dane wyjściowe można mapować na indeks i/lub używać ich jako danych wejściowych umiejętności podrzędnej — jak w przypadku kodu języka. W indeksie kod języka jest przydatny do filtrowania. Kod języka jest używany jako dane wejściowe przez narzędzia analizy tekstu do określania zasad podziału wyrazów.

Aby uzyskać więcej podstawowych informacji na temat zestawów umiejętności, zobacz Jak zdefiniować zestaw umiejętności.

Umiejętność OCR

Element OcrSkill wyodrębnia tekst z obrazów. Ta umiejętność zakłada, że istnieje pole normalized_images. Aby wygenerować to pole, w dalszej części samouczka ustawiliśmy konfigurację "imageAction" w definicji indeksatora na "generateNormalizedImages".

private static OcrSkill CreateOcrSkill()
{
    List<InputFieldMappingEntry> inputMappings = new List<InputFieldMappingEntry>();
    inputMappings.Add(new InputFieldMappingEntry("image")
    {
        Source = "/document/normalized_images/*"
    });

    List<OutputFieldMappingEntry> outputMappings = new List<OutputFieldMappingEntry>();
    outputMappings.Add(new OutputFieldMappingEntry("text")
    {
        TargetName = "text"
    });

    OcrSkill ocrSkill = new OcrSkill(inputMappings, outputMappings)
    {
        Description = "Extract text (plain and structured) from image",
        Context = "/document/normalized_images/*",
        DefaultLanguageCode = OcrSkillLanguage.En,
        ShouldDetectOrientation = true
    };

    return ocrSkill;
}

Umiejętność scalania

W tej sekcji utworzysz MergeSkill element, który scala pole zawartości dokumentu z tekstem utworzonym przez funkcję OCR.

private static MergeSkill CreateMergeSkill()
{
    List<InputFieldMappingEntry> inputMappings = new List<InputFieldMappingEntry>();
    inputMappings.Add(new InputFieldMappingEntry("text")
    {
        Source = "/document/content"
    });
    inputMappings.Add(new InputFieldMappingEntry("itemsToInsert")
    {
        Source = "/document/normalized_images/*/text"
    });
    inputMappings.Add(new InputFieldMappingEntry("offsets")
    {
        Source = "/document/normalized_images/*/contentOffset"
    });

    List<OutputFieldMappingEntry> outputMappings = new List<OutputFieldMappingEntry>();
    outputMappings.Add(new OutputFieldMappingEntry("mergedText")
    {
        TargetName = "merged_text"
    });

    MergeSkill mergeSkill = new MergeSkill(inputMappings, outputMappings)
    {
        Description = "Create merged_text which includes all the textual representation of each image inserted at the right location in the content field.",
        Context = "/document",
        InsertPreTag = " ",
        InsertPostTag = " "
    };

    return mergeSkill;
}

Umiejętność wykrywania języka

Funkcja LanguageDetectionSkill wykrywa język tekstu wejściowego i zgłasza pojedynczy kod języka dla każdego dokumentu przesłanego na żądanie. Używamy danych wyjściowych umiejętności weryfikacji języka jako części danych wejściowych do umiejętności dzielenia tekstu.

private static LanguageDetectionSkill CreateLanguageDetectionSkill()
{
    List<InputFieldMappingEntry> inputMappings = new List<InputFieldMappingEntry>();
    inputMappings.Add(new InputFieldMappingEntry("text")
    {
        Source = "/document/merged_text"
    });

    List<OutputFieldMappingEntry> outputMappings = new List<OutputFieldMappingEntry>();
    outputMappings.Add(new OutputFieldMappingEntry("languageCode")
    {
        TargetName = "languageCode"
    });

    LanguageDetectionSkill languageDetectionSkill = new LanguageDetectionSkill(inputMappings, outputMappings)
    {
        Description = "Detect the language used in the document",
        Context = "/document"
    };

    return languageDetectionSkill;
}

Umiejętność dzielenia tekstu

Poniższy SplitSkill tekst dzieli tekst według stron i ogranicza długość strony do 4000 znaków mierzonych przez String.Lengthwartość . Algorytm próbuje podzielić tekst na fragmenty, które mają największy maximumPageLength rozmiar. W tym przypadku algorytm robi wszystko, co w jego mocy, aby przerwać zdanie na granicy zdania, więc rozmiar fragmentu może być nieco mniejszy niż maximumPageLength.

private static SplitSkill CreateSplitSkill()
{
    List<InputFieldMappingEntry> inputMappings = new List<InputFieldMappingEntry>();
    inputMappings.Add(new InputFieldMappingEntry("text")
    {
        Source = "/document/merged_text"
    });
    inputMappings.Add(new InputFieldMappingEntry("languageCode")
    {
        Source = "/document/languageCode"
    });

    List<OutputFieldMappingEntry> outputMappings = new List<OutputFieldMappingEntry>();
    outputMappings.Add(new OutputFieldMappingEntry("textItems")
    {
        TargetName = "pages",
    });

    SplitSkill splitSkill = new SplitSkill(inputMappings, outputMappings)
    {
        Description = "Split content into pages",
        Context = "/document",
        TextSplitMode = TextSplitMode.Pages,
        MaximumPageLength = 4000,
        DefaultLanguageCode = SplitSkillLanguage.En
    };

    return splitSkill;
}

Umiejętność rozpoznawania jednostek

To EntityRecognitionSkill wystąpienie ma rozpoznawać typ organizationkategorii . Element EntityRecognitionSkill może również rozpoznawać kategorie typu person i location.

Zwróć uwagę, że pole "kontekst" jest ustawione na "/document/pages/*" z gwiazdką, co oznacza, że krok wzbogacania jest wywoływany dla każdej strony pod "/document/pages".

private static EntityRecognitionSkill CreateEntityRecognitionSkill()
{
    List<InputFieldMappingEntry> inputMappings = new List<InputFieldMappingEntry>();
    inputMappings.Add(new InputFieldMappingEntry("text")
    {
        Source = "/document/pages/*"
    });

    List<OutputFieldMappingEntry> outputMappings = new List<OutputFieldMappingEntry>();
    outputMappings.Add(new OutputFieldMappingEntry("organizations")
    {
        TargetName = "organizations"
    });

    // Specify the V3 version of the EntityRecognitionSkill
    var skillVersion = EntityRecognitionSkill.SkillVersion.V3;

    var entityRecognitionSkill = new EntityRecognitionSkill(inputMappings, outputMappings, skillVersion)
    {
        Description = "Recognize organizations",
        Context = "/document/pages/*",
        DefaultLanguageCode = EntityRecognitionSkillLanguage.En
    };
    entityRecognitionSkill.Categories.Add(EntityCategory.Organization);
    return entityRecognitionSkill;
}

Umiejętność wyodrębniania kluczowych fraz

EntityRecognitionSkill Podobnie jak wystąpienie, które zostało właśnie utworzone, KeyPhraseExtractionSkill element jest wywoływany dla każdej strony dokumentu.

private static KeyPhraseExtractionSkill CreateKeyPhraseExtractionSkill()
{
    List<InputFieldMappingEntry> inputMappings = new List<InputFieldMappingEntry>();
    inputMappings.Add(new InputFieldMappingEntry("text")
    {
        Source = "/document/pages/*"
    });
    inputMappings.Add(new InputFieldMappingEntry("languageCode")
    {
        Source = "/document/languageCode"
    });

    List<OutputFieldMappingEntry> outputMappings = new List<OutputFieldMappingEntry>();
    outputMappings.Add(new OutputFieldMappingEntry("keyPhrases")
    {
        TargetName = "keyPhrases"
    });

    KeyPhraseExtractionSkill keyPhraseExtractionSkill = new KeyPhraseExtractionSkill(inputMappings, outputMappings)
    {
        Description = "Extract the key phrases",
        Context = "/document/pages/*",
        DefaultLanguageCode = KeyPhraseExtractionSkillLanguage.En
    };

    return keyPhraseExtractionSkill;
}

Budować i tworzyć umiejętności

Zbuduj SearchIndexerSkillset używając umiejętności, które utworzyłeś.

private static SearchIndexerSkillset CreateOrUpdateDemoSkillSet(SearchIndexerClient indexerClient, IList<SearchIndexerSkill> skills,string azureAiServicesKey)
{
    SearchIndexerSkillset skillset = new SearchIndexerSkillset("demoskillset", skills)
    {
        // Foundry Tools was formerly known as Cognitive Services.
        // The APIs still use the old name, so we need to create a CognitiveServicesAccountKey object.
        Description = "Demo skillset",
        CognitiveServicesAccount = new CognitiveServicesAccountKey(azureAiServicesKey)
    };

    // Create the skillset in your search service.
    // The skillset does not need to be deleted if it was already created
    // since we are using the CreateOrUpdate method
    try
    {
        indexerClient.CreateOrUpdateSkillset(skillset);
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine("Failed to create the skillset\n Exception message: {0}\n", ex.Message);
        ExitProgram("Cannot continue without a skillset");
    }

    return skillset;
}

Dodaj następujące wiersze do Main.

// Create the skills
Console.WriteLine("Creating the skills...");
OcrSkill ocrSkill = CreateOcrSkill();
MergeSkill mergeSkill = CreateMergeSkill();
EntityRecognitionSkill entityRecognitionSkill = CreateEntityRecognitionSkill();
LanguageDetectionSkill languageDetectionSkill = CreateLanguageDetectionSkill();
SplitSkill splitSkill = CreateSplitSkill();
KeyPhraseExtractionSkill keyPhraseExtractionSkill = CreateKeyPhraseExtractionSkill();

// Create the skillset
Console.WriteLine("Creating or updating the skillset...");
List<SearchIndexerSkill> skills = new List<SearchIndexerSkill>();
skills.Add(ocrSkill);
skills.Add(mergeSkill);
skills.Add(languageDetectionSkill);
skills.Add(splitSkill);
skills.Add(entityRecognitionSkill);
skills.Add(keyPhraseExtractionSkill);

SearchIndexerSkillset skillset = CreateOrUpdateDemoSkillSet(indexerClient, skills, azureAiServicesKey);

Krok 3. Tworzenie indeksu

W tej sekcji zdefiniujesz schemat indeksu przez określenie pól do umieszczenia w indeksie z możliwością wyszukiwania oraz atrybutów wyszukiwania dla każdego pola. Pola mogą mieć typ i atrybuty, które określają sposób używania pola (z możliwością wyszukiwania, sortowania itp.). Nazwy pól w indeksie nie są wymagane do identycznego dopasowania nazw pól w źródle. W kolejnym kroku są dodawane mapowania pól w indeksatorze w celu połączenia pól źródłowych z polami docelowymi. W tym kroku zdefiniuj indeks przy użyciu konwencji nazewnictwa pól właściwej dla aplikacji wyszukiwania.

W tym ćwiczeniu są używane następujące pola i typy pól:

Nazwy pól	Typy pól
`id`	Edm.String
`content`	Edm.String
`languageCode`	Edm.String
`keyPhrases`	Wyświetlanie listy<ciągów Edm.String>
`organizations`	Wyświetlanie listy<ciągów Edm.String>

Tworzenie klasy DemoIndex

Pola dla tego indeksu są definiowane przy użyciu klasy modelu. Każda właściwość klasy modelu ma atrybuty, które określają zachowania związane z wyszukiwaniem odpowiedniego pola indeksu.

Dodamy klasę modelu do nowego pliku C#. Wybierz prawym przyciskiem myszy projekt i wybierz pozycję Dodaj>, wybierz pozycję "Klasa" i nadaj plikowi DemoIndex.csnazwę , a następnie wybierz pozycję Dodaj.

Upewnij się, że zaznaczysz chęć używania typów z przestrzeni nazw Azure.Search.Documents.Indexes i System.Text.Json.Serialization.

Dodaj poniższą definicję klasy modelu do DemoIndex.cs i dołącz ją do tej samej przestrzeni nazw, w której tworzysz indeks.

using Azure.Search.Documents.Indexes;
using System.Text.Json.Serialization;

namespace EnrichwithAI
{
    // The SerializePropertyNamesAsCamelCase is currently unsupported as of this writing. 
    // Replace it with JsonPropertyName
    public class DemoIndex
    {
        [SearchableField(IsSortable = true, IsKey = true)]
        [JsonPropertyName("id")]
        public string Id { get; set; }

        [SearchableField]
        [JsonPropertyName("content")]
        public string Content { get; set; }

        [SearchableField]
        [JsonPropertyName("languageCode")]
        public string LanguageCode { get; set; }

        [SearchableField]
        [JsonPropertyName("keyPhrases")]
        public string[] KeyPhrases { get; set; }

        [SearchableField]
        [JsonPropertyName("organizations")]
        public string[] Organizations { get; set; }
    }
}

Teraz po zdefiniowaniu klasy modelu, w Program.cs możesz łatwo utworzyć definicję indeksu. Nazwa tego indeksu to demoindex. Jeśli indeks już istnieje o tej nazwie, zostanie usunięty.

private static SearchIndex CreateDemoIndex(SearchIndexClient indexClient)
{
    FieldBuilder builder = new FieldBuilder();
    var index = new SearchIndex("demoindex")
    {
        Fields = builder.Build(typeof(DemoIndex))
    };

    try
    {
        indexClient.GetIndex(index.Name);
        indexClient.DeleteIndex(index.Name);
    }
    catch (RequestFailedException ex) when (ex.Status == 404)
    {
        //if the specified index not exist, 404 will be thrown.
    }

    try
    {
        indexClient.CreateIndex(index);
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine("Failed to create the index\n Exception message: {0}\n", ex.Message);
        ExitProgram("Cannot continue without an index");
    }

    return index;
}

Podczas testowania może się okazać, że próbujesz utworzyć indeks więcej niż raz. W związku z tym sprawdź, czy indeks, który chcesz utworzyć, już istnieje przed próbą jego utworzenia.

Dodaj następujące wiersze do Main.

// Create the index
Console.WriteLine("Creating the index...");
SearchIndex demoIndex = CreateDemoIndex(indexClient);

Dodaj następującą instrukcję using, aby rozwiązać niejednoznaczne odwołanie.

using Index = Azure.Search.Documents.Indexes.Models;

Aby dowiedzieć się więcej na temat pojęć dotyczących indeksu, zobacz Tworzenie indeksu (interfejs API REST).

Krok 4. Tworzenie i uruchamianie indeksatora

Do tej pory utworzono źródło danych, zestaw umiejętności i indeks. Te trzy składniki staną się częścią indeksatora, który łączy wszystkie części w pojedynczą operację obejmującą wiele faz. Aby powiązać je razem w indeksatorze, należy zdefiniować mapowania pól.

Mapowania pól są przetwarzane przed zestawem umiejętności, aby zmapować pola źródłowe ze źródła danych na pola docelowe w indeksie. Jeśli nazwy pól i typy są takie same na obu końcach, żadne mapowanie nie jest wymagane.
Mapowania pól wyjściowych są przetwarzane po zestawie funkcji, odwołując się do nazw pól źródłowych, które nie istnieją, dopóki nie zostaną utworzone przez rozbijanie dokumentu lub wzbogacanie. TargetFieldName jest polem w indeksie.

Oprócz podłączania danych wejściowych do danych wyjściowych można również używać mapowań pól do spłaszczania struktur danych. Aby uzyskać więcej informacji, zobacz Jak mapować wzbogacone pola na indeks z możliwością wyszukiwania.

private static SearchIndexer CreateDemoIndexer(SearchIndexerClient indexerClient, SearchIndexerDataSourceConnection dataSource, SearchIndexerSkillset skillSet, SearchIndex index)
{
    IndexingParameters indexingParameters = new IndexingParameters()
    {
        MaxFailedItems = -1,
        MaxFailedItemsPerBatch = -1,
    };
    indexingParameters.Configuration.Add("dataToExtract", "contentAndMetadata");
    indexingParameters.Configuration.Add("imageAction", "generateNormalizedImages");

    SearchIndexer indexer = new SearchIndexer("demoindexer", dataSource.Name, index.Name)
    {
        Description = "Demo Indexer",
        SkillsetName = skillSet.Name,
        Parameters = indexingParameters
    };

    FieldMappingFunction mappingFunction = new FieldMappingFunction("base64Encode");
    mappingFunction.Parameters.Add("useHttpServerUtilityUrlTokenEncode", true);

    indexer.FieldMappings.Add(new FieldMapping("metadata_storage_path")
    {
        TargetFieldName = "id",
        MappingFunction = mappingFunction

    });
    indexer.FieldMappings.Add(new FieldMapping("content")
    {
        TargetFieldName = "content"
    });

    indexer.OutputFieldMappings.Add(new FieldMapping("/document/pages/*/organizations/*")
    {
        TargetFieldName = "organizations"
    });
    indexer.OutputFieldMappings.Add(new FieldMapping("/document/pages/*/keyPhrases/*")
    {
        TargetFieldName = "keyPhrases"
    });
    indexer.OutputFieldMappings.Add(new FieldMapping("/document/languageCode")
    {
        TargetFieldName = "languageCode"
    });

    try
    {
        indexerClient.GetIndexer(indexer.Name);
        indexerClient.DeleteIndexer(indexer.Name);
    }
    catch (RequestFailedException ex) when (ex.Status == 404)
    {
        //if the specified indexer not exist, 404 will be thrown.
    }

    try
    {
        indexerClient.CreateIndexer(indexer);
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine("Failed to create the indexer\n Exception message: {0}\n", ex.Message);
        ExitProgram("Cannot continue without creating an indexer");
    }

    return indexer;
}

Dodaj następujące wiersze do Main.

// Create the indexer, map fields, and execute transformations
Console.WriteLine("Creating the indexer and executing the pipeline...");
SearchIndexer demoIndexer = CreateDemoIndexer(indexerClient, dataSource, skillset, demoIndex);

Spodziewaj się, że przetwarzanie indeksatora zajmie trochę czasu. Mimo że zestaw danych jest mały, umiejętności analityczne wykorzystują znaczną moc obliczeniową. Wykonywanie niektórych umiejętności, takich jak analiza obrazu, jest długotrwałe.

Tip

Eksplorowanie tworzenia indeksatora

Kod ustawia "maxFailedItems" wartość -1, co instruuje aparat indeksowania, aby ignorował błędy podczas importowania danych. Jest to przydatne, ponieważ pokazowe źródło danych zawiera tak mało dokumentów. W przypadku większego źródła danych należy ustawić wartość większą od 0.

Zwróć również uwagę, że "dataToExtract" parametr jest ustawiony na "contentAndMetadata"wartość . Ta instrukcja nakazuje indeksatorowi automatyczne wyodrębnianie zawartości z plików w różnych formatach, a także metadanych związanych z każdym plikiem.

Gdy zawartość zostanie wyodrębniona, możesz ustawić element imageAction, aby wyodrębnić tekst z obrazów znalezionych w źródle danych. Ustawienie konfiguracji "imageAction" na "generateNormalizedImages", w połączeniu z umiejętnością OCR i scalania tekstu, informuje indeksator o wyodrębnieniu tekstu z obrazów (na przykład słowa "stop" z znaku Stop) i osadzenie go w ramach pola zawartości. To zachowanie dotyczy zarówno obrazów osadzonych w dokumentach (np. w pliku PDF), jak i znalezionych w źródle danych (np. pliku JPG).

Monitorowanie indeksowania

Po zdefiniowaniu indeksatora jest on uruchamiany automatycznie przy przesyłaniu żądania. W zależności od zdefiniowanych umiejętności indeksowanie może trwać dłużej niż oczekiwano. Aby dowiedzieć się, czy indeksator jest nadal uruchomiony, użyj GetStatus metody .

private static void CheckIndexerOverallStatus(SearchIndexerClient indexerClient, SearchIndexer indexer)
{
    try
    {
        var demoIndexerExecutionInfo = indexerClient.GetIndexerStatus(indexer.Name);

        switch (demoIndexerExecutionInfo.Value.Status)
        {
            case IndexerStatus.Error:
                ExitProgram("Indexer has error status. Check the Azure portal to further understand the error.");
                break;
            case IndexerStatus.Running:
                Console.WriteLine("Indexer is running");
                break;
            case IndexerStatus.Unknown:
                Console.WriteLine("Indexer status is unknown");
                break;
            default:
                Console.WriteLine("No indexer information");
                break;
        }
    }
    catch (RequestFailedException ex)
    {
        Console.WriteLine("Failed to get indexer overall status\n Exception message: {0}\n", ex.Message);
    }
}

demoIndexerExecutionInfo reprezentuje bieżący stan i historię wykonywania indeksatora.

Ostrzeżenia są typowe w przypadku niektórych kombinacji plików źródłowych i umiejętności i nie zawsze wskazują problem. W tym samouczku ostrzeżenia są niegroźne (np. brak tekstowych danych wejściowych dla plików JPEG).

Dodaj następujące wiersze do Main.

// Check indexer overall status
Console.WriteLine("Check the indexer overall status...");
CheckIndexerOverallStatus(indexerClient, demoIndexer);

Search

W aplikacjach konsolowych używanych w samouczkach Azure AI Search, zwykle dodajemy 2-sekundowe opóźnienie przed uruchomieniem zapytań, które zwracają wyniki. Jednak ponieważ wzbogacanie zajmuje kilka minut, zamykamy aplikację konsolową i stosujemy inne podejście.

Najprostszą opcją jest Eksplorator wyszukiwania w witrynie Azure Portal. Najpierw można uruchomić puste zapytanie, które zwraca wszystkie dokumenty, lub wykonać bardziej ukierunkowane wyszukiwanie, zwracające nową zawartość pól utworzoną przez pipeline.

W portalu Azure, na stronach usługi wyszukiwania, rozwiń Zarządzanie wyszukiwaniem>Indeksy.
Znajdź demoindex na liście. Powinien zawierać 14 dokumentów. Jeśli liczba dokumentów wynosi zero, indeksator jest nadal uruchomiony lub strona nie została jeszcze odświeżona.
Wybierz opcję demoindex. Eksplorator wyszukiwania to pierwsza karta.
Zawartość można przeszukiwać zaraz po załadowaniu pierwszego dokumentu. Aby sprawdzić, czy zawartość istnieje, uruchom nieokreślone zapytanie, klikając pozycję Wyszukaj. To zapytanie zwraca wszystkie aktualnie indeksowane dokumenty, co daje wyobrażenie o tym, co zawiera indeks.
Aby uzyskać bardziej możliwe do zarządzania wyniki, przejdź do widoku JSON i ustaw parametry, aby wybrać pola:
```
{
    "search": "*",
    "count": true,
    "select": "id, languageCode, organizations"
}
```

Resetowanie i ponowne uruchamianie

Na wczesnym etapie eksperymentalnym programowania najbardziej praktycznym podejściem do iteracji projektowej jest usunięcie obiektów z usługi Azure AI Search i umożliwienie ponownego kompilowania kodu. Nazwy zasobów są unikatowe. Usunięcie obiektu umożliwia jego ponowne utworzenie przy użyciu tej samej nazwy.

Przykładowy kod tego samouczka sprawdza istniejące obiekty i usuwa je, aby można było ponownie uruchomić kod. Za pomocą witryny Azure Portal można również usuwać indeksy, indeksatory, źródła danych i zestawy umiejętności.

Takeaways

W tym samouczku przedstawiono podstawowe kroki tworzenia wzbogaconego potoku indeksowania poprzez stworzenie elementów składowych: źródła danych, zestawu umiejętności, indeksu i indeksatora.

Wprowadzono wbudowane umiejętności wraz z definicją zestawu umiejętności i mechaniką łączenia umiejętności za pośrednictwem danych wejściowych i wyjściowych. Wiesz również, że outputFieldMappings w definicji indeksatora jest wymagany do routingu wzbogaconych wartości z potoku do wyszukiwalnego indeksu w usłudze wyszukiwania Azure AI.

Ponadto przedstawiono sposób testowania wyników i resetowania systemu na potrzeby przyszłych iteracji. Dowiedziałeś się, że wysyłanie zapytań do indeksu zwraca dane wyjściowe utworzone przez wzbogacony potok indeksowania. Nauczyłeś się także, jak sprawdzać stan indeksatora oraz jakie obiekty usunąć przed ponownym uruchomieniem pipeline.

Uprzątnij zasoby

Gdy pracujesz we własnej subskrypcji, warto na końcu projektu usunąć zasoby, których już nie potrzebujesz. Zasoby pozostawione w stanie aktywnym mogą generować koszty. Zasoby można usunąć pojedynczo lub usunąć grupę zasobów, aby usunąć cały zestaw zasobów.

Zasoby można znaleźć w witrynie Azure Portal i zarządzać nimi, korzystając z linku Wszystkie zasoby lub Grupy zasobów w okienku nawigacji po lewej stronie.

Dalsze kroki

Teraz, gdy znasz już wszystkie obiekty w ścieżce wzbogacania sztucznej inteligencji, przyjrzyjmy się bliżej definicjom zestawów umiejętności i poszczególnym umiejętnościom.

Jak utworzyć zestaw umiejętności

Dowiedz się, jak wywoływać interfejsy API REST, które tworzą potok wzbogacania sztucznej inteligencji na potrzeby wyodrębniania i przekształcania zawartości podczas indeksowania.

W tym samouczku nauczysz się następujących rzeczy:

Zdefiniuj obiekty w procesie wzbogacania.
Tworzenie zestawu umiejętności. Wywołaj rozpoznawanie znaków OCR, wykrywanie języka, rozpoznawanie jednostek i wyodrębnianie kluczowych fraz.
Uruchom potok danych. Tworzenie i ładowanie indeksu wyszukiwania.
Sprawdź wyniki przy użyciu wyszukiwania pełnotekstowego.

Overview

W tym samouczku użyto klienta REST i interfejsów API REST usługi Azure AI Search do utworzenia źródła danych, indeksu, indeksatora i zestawu umiejętności.

Indeksator steruje każdym krokem w potoku, począwszy od wyodrębniania zawartości przykładowych danych (tekstów bez struktury i obrazów) w kontenerze blobów na platformie Azure Storage.

Prerequisites

Konto Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
Azure Storage
Wyszukiwanie AI w usłudze Azure
Program Visual Studio Code z klientem REST

Note

Pobieranie plików

Pobierz plik zip z przykładowego repozytorium danych i wyodrębnij zawartość. Dowiedz się, jak to zrobić.

Przekazywanie przykładowych danych do usługi Azure Storage

W usłudze Azure Storage utwórz nowy kontener i nadaj mu nazwę cog-search-demo.
Przekaż przykładowe pliki danych.
Uzyskaj parametry połączenia magazynu, aby można było sformułować połączenie w usłudze Azure AI Search.
1. Po lewej stronie wybierz pozycję Klucze dostępu.
2. Skopiuj parametry połączenia dla jednego lub drugiego klucza. Łańcuch połączenia jest podobny do poniższego przykładu:
  
  DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net

Narzędzia odlewni

Wbudowane wzbogacanie sztucznej inteligencji jest wspierane przez narzędzia Foundry Tools, w tym język platformy Azure i usługę Azure Vision na potrzeby przetwarzania języka naturalnego i obrazów. W przypadku małych obciążeń, takich jak w tym samouczku, możesz użyć bezpłatnego przydziału dwudziestu transakcji na potrzeby indeksatora. W przypadku większych obciążeń dołącz zasób Microsoft Foundry do zestawu umiejętności w ramach cen Standard.

Kopiowanie adresu URL usługi wyszukiwania i klucza interfejsu API

Na potrzeby tego samouczka połączenia z usługą Azure AI Search wymagają punktu końcowego i klucza API. Te wartości można uzyskać w witrynie Azure Portal.

Zaloguj się do witryny Azure Portal i wybierz usługę wyszukiwania.
W okienku po lewej stronie wybierz pozycję Przegląd i skopiuj punkt końcowy. Powinien mieć następujący format: https://my-service.search.windows.net
W okienku po lewej stronie wybierz pozycję Ustawienia>Klucze i skopiuj klucz administratora, aby uzyskać pełne prawa do usługi. Istnieją dwa zamienne klucze administratora, które zapewniają ciągłość działania na wypadek gdyby trzeba było jednego zastąpić. Możesz użyć któregokolwiek z kluczy w żądaniach, aby dodawać, modyfikować lub usuwać obiekty.

Konfigurowanie pliku REST

Uruchom program Visual Studio Code i otwórz plik skillset-tutorial.rest . Zobacz Szybki start: wyszukiwanie pełnotekstowe , jeśli potrzebujesz pomocy dotyczącej klienta REST.
Podaj wartości zmiennych: punkt końcowy usługi wyszukiwania, klucz interfejsu API administratora usługi wyszukiwania, nazwę indeksu, parametry połączenia z kontem usługi Azure Storage i nazwę kontenera obiektów blob.

Utwórz potok

Wzbogacanie sztucznej inteligencji jest oparte na indeksatorze. Ta część przewodnika tworzy cztery obiekty: źródło danych, definicję indeksu, zestaw umiejętności, indeksator.

Krok 1. Tworzenie źródła danych

Wywołaj Create Data Source (Utwórz źródło danych), aby ustawić ciąg połączenia do kontenera obiektów blob zawierającego przykładowe pliki danych.

### Create a data source
POST {{baseUrl}}/datasources?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "name": "cog-search-demo-ds",
        "description": null,
        "type": "azureblob",
        "subtype": null,
        "credentials": {
            "connectionString": "{{storageConnectionString}}"
        },
        "container": {
            "name": "{{blobContainer}}",
            "query": null
        },
        "dataChangeDetectionPolicy": null,
        "dataDeletionDetectionPolicy": null
    }

Krok 2. Tworzenie zestawu umiejętności

Wywołaj polecenie Utwórz Zestaw Umiejętności, aby określić, jakie kroki wzbogacania zostaną zastosowane do Twojej zawartości. Umiejętności są wykonywane równolegle, chyba że istnieje zależność.

### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "name": "cog-search-demo-ss",
        "description": "Apply OCR, detect language, extract entities, and extract key-phrases.",
        "cognitiveServices": null,
        "skills":
        [
            {
            "@odata.type": "#Microsoft.Skills.Vision.OcrSkill",
            "context": "/document/normalized_images/*",
            "defaultLanguageCode": "en",
            "detectOrientation": true,
            "inputs": [
                {
                    "name": "image",
                    "source": "/document/normalized_images/*"
                }
            ],
            "outputs": [
                {
                    "name": "text"
                }
            ]
            },
            {
            "@odata.type": "#Microsoft.Skills.Text.MergeSkill",
            "description": "Create merged_text, which includes all the textual representation of each image inserted at the right location in the content field. This is useful for PDF and other file formats that supported embedded images.",
            "context": "/document",
            "insertPreTag": " ",
            "insertPostTag": " ",
            "inputs": [
                {
                    "name":"text", 
                    "source": "/document/content"
                },
                {
                    "name": "itemsToInsert", 
                    "source": "/document/normalized_images/*/text"
                },
                {
                    "name":"offsets", 
                    "source": "/document/normalized_images/*/contentOffset" 
                }
            ],
            "outputs": [
                {
                    "name": "mergedText", 
                    "targetName" : "merged_text"
                }
            ]
            },
            {
            "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
            "textSplitMode": "pages",
            "maximumPageLength": 4000,
            "defaultLanguageCode": "en",
            "context": "/document",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_text"
                }
            ],
            "outputs": [
                {
                    "name": "textItems",
                    "targetName": "pages"
                }
            ]
            },
            {
            "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
            "description": "If you have multilingual content, adding a language code is useful for filtering",
            "context": "/document",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_text"
                }
            ],
            "outputs": [
                {
                    "name": "languageName",
                    "targetName": "language"
                }
            ]
            },
            {
            "@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
            "context": "/document/pages/*",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/pages/*"
                }
            ],
            "outputs": [
                {
                    "name": "keyPhrases",
                    "targetName": "keyPhrases"
                }
            ]
            },
            {
            "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
            "categories": ["Organization"],
            "context": "/document",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_text"
                }
            ],
            "outputs": [
                {
                    "name": "organizations",
                    "targetName": "organizations"
                }
            ]
            },
            {
            "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
            "categories": ["Location"],
            "context": "/document",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_text"
                }
            ],
            "outputs": [
                {
                    "name": "locations",
                    "targetName": "locations"
                }
            ]
            },
            {
            "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
            "categories": ["Person"],
            "context": "/document",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_text"
                }
            ],
            "outputs": [
                {
                    "name": "persons",
                    "targetName": "persons"
                }
            ]
            }
        ]
    }

Kluczowe punkty:

Treść żądania określa następujące wbudowane umiejętności:

Skill	Description
Optyczne rozpoznawanie znaków	Rozpoznaje tekst i liczby w plikach obrazów.
Scalanie tekstu	Tworzy "scaloną zawartość", która ponownie łączy wcześniej oddzieloną zawartość, przydatną w przypadku dokumentów z obrazami osadzonymi (PDF, DOCX itd.). Obrazy i tekst są oddzielane w fazie pękania dokumentu. Umiejętność scalania łączy je ponownie, wstawiając dowolny rozpoznany tekst, podpisy obrazów lub tagi utworzone podczas wzbogacania do tej samej lokalizacji, w której obraz został wyodrębniony z dokumentu. Podczas pracy z scaloną zawartością w zestawie narzędzi ten węzeł obejmuje cały tekst dokumentu, w tym dokumenty tekstowe, które nie podlegają analizie OCR ani analizy obrazów.
Wykrywanie języka	Wykrywa język i zwraca nazwę języka lub kod. W wielojęzycznych zestawach danych pole języka może być przydatne w przypadku filtrów.
Rozpoznawanie jednostek	Wyodrębnia nazwy osób, organizacji i lokalizacji z scalonej zawartości.
Podział tekstu	Dzieli dużą scaloną zawartość na mniejsze fragmenty przed wywołaniem umiejętności wyodrębniania kluczowych fraz. Wyodrębnianie kluczowych fraz akceptuje dane wejściowe o 50 000 znaków lub mniej. Kilka przykładowych plików należy podzielić, aby zmieścić się w tym limicie.
Ekstrakcja Kluczowych Frazy	Wyciąga najważniejsze kluczowe frazy.

Każda funkcja działa na zawartości dokumentu. Podczas przetwarzania usługa Azure AI Search analizuje każdy dokument w celu odczytania zawartości z różnych formatów plików. Znaleziony tekst pochodzący z pliku źródłowego jest umieszczany w wygenerowanym content polu , po jednym dla każdego dokumentu. W związku z tym dane wejściowe stają się ."/document/content"
W przypadku wyodrębniania kluczowych fraz, ponieważ używamy umiejętności dzielenia tekstu do dzielenia większych plików na strony, kontekstem umiejętności wyodrębniania kluczowych fraz jest "document/pages/*" (dla każdej strony w dokumencie) zamiast "/document/content".

Note

Dane wyjściowe można mapować na indeks i/lub używać ich jako danych wejściowych umiejętności podrzędnej — jak w przypadku kodu języka. W indeksie kod języka jest przydatny do filtrowania. Aby uzyskać więcej podstawowych informacji na temat zestawów umiejętności, zobacz Jak zdefiniować zestaw umiejętności.

Krok 3. Tworzenie indeksu

Wywołaj metodę Create Index (Utwórz indeks ), aby udostępnić schemat używany do tworzenia indeksów odwróconych i innych konstrukcji w usłudze Azure AI Search.

Największym składnikiem indeksu jest kolekcja pól, w której typ danych i atrybuty określają zawartość i zachowanie w usłudze Azure AI Search. Upewnij się, że masz pola dla nowo wygenerowanych danych wyjściowych.

### Create an index
POST {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "name": "cog-search-demo-idx",
        "defaultScoringProfile": "",
        "fields": [
            {
                "name": "content",
                "type": "Edm.String",
                "searchable": true,
                "sortable": false,
                "filterable": false,
                "facetable": false
            },
            {
                "name": "text",
                "type": "Collection(Edm.String)",
                "facetable": false,
                "filterable": true,
                "searchable": true,
                "sortable": false
            },
            {
                "name": "language",
                "type": "Edm.String",
                "searchable": false,
                "sortable": true,
                "filterable": true,
                "facetable": false
            },
            {
                "name": "keyPhrases",
                "type": "Collection(Edm.String)",
                "searchable": true,
                "sortable": false,
                "filterable": true,
                "facetable": true
            },
            {
                "name": "organizations",
                "type": "Collection(Edm.String)",
                "searchable": true,
                "sortable": false,
                "filterable": true,
                "facetable": true
            },
            {
                "name": "persons",
                "type": "Collection(Edm.String)",
                "searchable": true,
                "sortable": false,
                "filterable": true,
                "facetable": true
            },
            {
                "name": "locations",
                "type": "Collection(Edm.String)",
                "searchable": true,
                "sortable": false,
                "filterable": true,
                "facetable": true
            },
            {
                "name": "metadata_storage_path",
                "type": "Edm.String",
                "key": true,
                "searchable": true,
                "sortable": false,
                "filterable": false,
                "facetable": false
            },
            {
                "name": "metadata_storage_name",
                "type": "Edm.String",
                "searchable": true,
                "sortable": false,
                "filterable": false,
                "facetable": false
            }
        ]
    }

Krok 4. Tworzenie i uruchamianie indeksatora

Wywołaj metodę Create Indexer , aby napędzać potok. Trzy składniki utworzone do tej pory (źródło danych, zestaw umiejętności, indeks) to dane wejściowe indeksatora. Tworzenie indeksatora w usłudze Azure AI Search to zdarzenie, które wprawia cały przepływ w ruch.

Ten krok może potrwać kilka minut. Mimo że zestaw danych jest mały, umiejętności analityczne wykorzystują znaczną moc obliczeniową.

### Create and run an indexer
POST {{baseUrl}}/indexers?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "name": "cog-search-demo-idxr",
        "description": "",
        "dataSourceName" : "cog-search-demo-ds",
        "targetIndexName" : "cog-search-demo-idx",
        "skillsetName" : "cog-search-demo-ss",
        "fieldMappings" : [
            {
                "sourceFieldName" : "metadata_storage_path",
                "targetFieldName" : "metadata_storage_path",
                "mappingFunction" : { "name" : "base64Encode" }
            },
            {
                "sourceFieldName": "metadata_storage_name",
                "targetFieldName": "metadata_storage_name"
            }
        ],
        "outputFieldMappings" : 
        [
            {
                "sourceFieldName": "/document/merged_text",
                "targetFieldName": "content"
            },
            {
                "sourceFieldName" : "/document/normalized_images/*/text",
                "targetFieldName" : "text"
            },
            {
                "sourceFieldName" : "/document/organizations", 
                "targetFieldName" : "organizations"
            },
            {
                "sourceFieldName": "/document/language",
                "targetFieldName": "language"
            },
            {
                "sourceFieldName" : "/document/persons", 
                "targetFieldName" : "persons"
            },
            {
                "sourceFieldName" : "/document/locations", 
                "targetFieldName" : "locations"
            },
            {
                "sourceFieldName" : "/document/pages/*/keyPhrases/*", 
                "targetFieldName" : "keyPhrases"
            }
        ],
        "parameters":
        {
        "batchSize": 1,
        "maxFailedItems":-1,
        "maxFailedItemsPerBatch":-1,
        "configuration": 
            {
                "dataToExtract": "contentAndMetadata",
                "imageAction": "generateNormalizedImages"
            }
        }
    }

Kluczowe punkty:

Treść żądania zawiera odwołania do poprzednich obiektów, właściwości konfiguracji wymagane do przetwarzania obrazów i dwa typy mapowań pól.
"fieldMappings" są przetwarzane przed zestawem umiejętności, wysyłając zawartość ze źródła danych do pól docelowych w indeksie. Mapowania pól służą do wysyłania istniejącej, niezmodyfikowanej zawartości do indeksu. Jeśli nazwy pól i typy są takie same na obu końcach, żadne mapowanie nie jest wymagane.
"outputFieldMappings" są przeznaczone dla pól utworzonych przez umiejętności po realizacji zestawu umiejętności. Odwołania do sourceFieldName w programie outputFieldMappings nie istnieją, dopóki nie zostaną one utworzone przez pęknięcie dokumentu lub wzbogacenie. Pole targetFieldName jest elementem indeksu, zdefiniowanym w schemacie indeksu.
Parametr "maxFailedItems" jest ustawiony na -1, co instruuje aparat indeksowania, aby ignorował błędy podczas importowania danych. Jest to dopuszczalne, ponieważ w źródle danych demonstracyjnych jest tak mało dokumentów. W przypadku większego źródła danych należy ustawić wartość większą od 0.
Instrukcja "dataToExtract":"contentAndMetadata" nakazuje indeksatorowi automatyczne wyodrębnianie wartości z właściwości zawartości obiektu blob i metadanych każdego obiektu.
Parametr imageAction informuje indeksator o wyodrębnieniu tekstu z obrazów znalezionych w źródle danych. Konfiguracja "imageAction":"generateNormalizedImages" w połączeniu z umiejętnością OCR i umiejętnością scalania tekstu informuje indeksatora o wyodrębnianiu tekstu z obrazów (na przykład słowa "stop" z znaku zatrzymania ruchu) i osadzeniu go w ramach pola zawartości. To zachowanie dotyczy zarówno obrazów osadzonych (pomyśl o obrazie wewnątrz pliku PDF), jak i autonomicznych plikach obrazów, na przykład w pliku JPG.

Note

Utworzenie indeksatora powoduje wywołanie potoku. Jeśli występują problemy z dostępem do danych, mapowaniem danych wejściowych i wyjściowych lub kolejnością operacji, pojawią się one na tym etapie. Aby przeprowadzić ponowną realizację pipeline ze zmianami kodu lub skryptu, może zajść potrzeba najpierw usunięcia elementów. Aby uzyskać więcej informacji, zobacz Resetowanie i ponowne uruchamianie.

Monitorowanie indeksowania

Indeksowanie i wzbogacanie rozpoczyna się zaraz po przesłaniu żądania Tworzenia indeksatora. W zależności od złożoności i operacji zestawu umiejętności indeksowanie może zająć trochę czasu.

Aby dowiedzieć się, czy indeksator jest nadal uruchomiony, wywołaj metodę Pobierz stan indeksatora , aby sprawdzić stan indeksatora.

### Get Indexer Status (wait several minutes for the indexer to complete)
GET {{baseUrl}}/indexers/cog-search-demo-idxr/status?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

Kluczowe punkty:

Ostrzeżenia są typowe w niektórych scenariuszach i nie zawsze wskazują problem. Jeśli na przykład kontener blobów zawiera pliki obrazów, a potok nie obsługuje obrazów, zostanie wyświetlony komunikat, że obrazy nie zostały przetworzone.
W tym przykładzie istnieje plik PNG, który nie zawiera tekstu. Wszystkie pięć umiejętności opartych na tekście (wykrywanie języka, rozpoznawanie jednostek lokalizacji, organizacji, osób i wyodrębniania kluczowych fraz) nie może zostać wykonane w tym pliku. Wyświetlone powiadomienie zostanie wyświetlone w historii wykonywania.

Sprawdzanie wyników

Po utworzeniu indeksu zawierającego zawartość wygenerowaną przez sztuczną inteligencję wywołaj funkcję Search Documents , aby uruchomić kilka zapytań, aby wyświetlić wyniki.

### Query the index\
POST {{baseUrl}}/indexes/cog-search-demo-idx/docs/search?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}
  
  {
    "search": "*",
    "select": "metadata_storage_name,language,organizations",
    "count": true
  }

Filtry mogą ułatwić zawężenie wyników do interesujących elementów:

### Filter by organization
POST {{baseUrl}}/indexes/cog-search-demo-idx/docs/search?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}
  
  {
    "search": "*",
    "filter": "organizations/any(organizations: organizations eq 'Microsoft')",
    "select": "metadata_storage_name,organizations",
    "count": true
  }

Te zapytania ilustrują kilka sposobów pracy ze składnią zapytań i filtrami w nowych polach utworzonych przez usługę Azure AI Search. Aby uzyskać więcej przykładów zapytań, zobacz Przykłady w interfejsie API REST dokumentów wyszukiwania, przykłady prostych zapytań składniowych i przykłady pełnych zapytań Lucene.

Resetowanie i ponowne uruchamianie

We wczesnych etapach opracowywania iteracja nad projektem jest powszechna. Resetowanie i ponowne uruchamianie ułatwia iterację.

Takeaways

W tym samouczku przedstawiono podstawowe kroki używania interfejsów API REST do tworzenia pipeline'u do wzbogacania danych przy użyciu sztucznej inteligencji: źródła danych, zestawu umiejętności, indeksu i indeksatora.

Wprowadzono wbudowane umiejętności wraz z definicją zestawu umiejętności, która pokazuje mechanikę łączenia umiejętności za pośrednictwem danych wejściowych i wyjściowych. Wiesz również, że outputFieldMappings w definicji indeksatora jest wymagany do routingu wzbogaconych wartości z potoku do wyszukiwalnego indeksu w usłudze wyszukiwania Azure AI.

Uprzątnij zasoby

Zasoby można znaleźć w witrynie Azure Portal i zarządzać nimi, korzystając z linku Wszystkie zasoby lub Grupy zasobów w okienku nawigacji po lewej stronie.

Dalsze kroki

Teraz, gdy znasz już wszystkie elementy w procesie wzbogacania za pomocą sztucznej inteligencji, przyjrzyj się bliżej definicjom zestawów umiejętności oraz poszczególnym umiejętnościom.

Jak utworzyć zestaw umiejętności

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-11-21

Udostępnij przez

Samouczek: zestawy umiejętności w usłudze Azure AI Search

Overview

Prerequisites

Pobieranie plików

Przekazywanie przykładowych danych do usługi Azure Storage

Narzędzia odlewni

Kopiowanie adresu URL usługi wyszukiwania i klucza interfejsu API

Konfigurowanie środowiska

Instalowanie pliku Azure.Search.Documents

Dodawanie informacji o połączeniu z usługą

Dodawanie przestrzeni nazw

Tworzenie klienta

Dodawanie funkcji w celu zakończenia programu podczas awarii

Utwórz potok

Krok 1. Tworzenie źródła danych

Krok 2. Tworzenie zestawu umiejętności

Umiejętność OCR

Umiejętność scalania

Umiejętność wykrywania języka

Umiejętność dzielenia tekstu

Umiejętność rozpoznawania jednostek

Umiejętność wyodrębniania kluczowych fraz

Budować i tworzyć umiejętności

Krok 3. Tworzenie indeksu

Tworzenie klasy DemoIndex

Krok 4. Tworzenie i uruchamianie indeksatora

Eksplorowanie tworzenia indeksatora

Monitorowanie indeksowania

Search

Resetowanie i ponowne uruchamianie

Takeaways

Uprzątnij zasoby

Dalsze kroki

Overview

Prerequisites

Pobieranie plików

Przekazywanie przykładowych danych do usługi Azure Storage

Narzędzia odlewni

Kopiowanie adresu URL usługi wyszukiwania i klucza interfejsu API

Konfigurowanie pliku REST

Utwórz potok

Krok 1. Tworzenie źródła danych

Krok 2. Tworzenie zestawu umiejętności

Krok 3. Tworzenie indeksu

Krok 4. Tworzenie i uruchamianie indeksatora

Monitorowanie indeksowania

Sprawdzanie wyników

Resetowanie i ponowne uruchamianie

Takeaways

Uprzątnij zasoby

Dalsze kroki

Sprzężenie zwrotne

Dodatkowe źródła