Tutorial: Keterampilan dalam Pencarian Azure AI

Pelajari cara menggunakan Azure SDK untuk .NET untuk membuat alur pengayaan AI untuk ekstraksi dan transformasi konten selama pengindeksan.

Skillset menambahkan pemrosesan AI ke konten mentah, membuatnya lebih seragam dan mudah dicari. Setelah Anda memahami cara kerja set keterampilan, Anda dapat mendukung berbagai transformasi, mulai dari analisis gambar hingga pemrosesan bahasa alami hingga pemrosesan yang disesuaikan yang Anda berikan secara eksternal.

Di tutorial ini, Anda akan:

Overview

Tutorial ini menggunakan C# dan pustaka klien Azure.Search.Documents untuk membuat sumber data, indeks, pengindeks, dan set keterampilan.

Pengindeks mendorong setiap langkah dalam alur, dimulai dengan ekstraksi konten data sampel (teks dan gambar yang tidak terstruktur) dalam kontainer blob di Azure Storage.

Setelah konten diekstrak, kumpulan keterampilan menjalankan fungsi bawaan dari Microsoft untuk menemukan dan mengekstrak informasi. Keterampilan ini termasuk Pengenalan Karakter Optik (OCR) pada gambar, deteksi bahasa pada teks, ekstraksi frasa kunci, dan pengenalan entitas (organisasi). Informasi baru yang dihasilkan oleh kumpulan keterampilan dikirim ke bidang dalam indeks. Setelah indeks telah diisi, Anda dapat menggunakan bidang dalam kueri, faset, dan filter.

Prerequisites

• Sebuah akun Azure dengan langganan aktif. Buat akun secara gratis.

• Azure Storage.

• Pencarian Azure AI.

• Paket Azure.Search.Documents.

• Visual Studio.

Mengunduh file

• Unduh file zip dari repositori data sampel dan ekstrak kontennya. Pelajari caranya.

• Mengunduh file data sampel (media campuran)

Mengunggah data sampel ke Azure Storage

1. Di Azure Storage, buat kontainer baru dan beri nama mixed-content-types.

2. Unggah file data sampel.

3. Dapatkan string koneksi penyimpanan sehingga Anda bisa merumuskan koneksi di Pencarian Azure AI.

   1. Di sebelah kiri, pilih Tombol akses.

   2. Salin string koneksi untuk kunci satu atau kunci dua. string koneksi mirip dengan contoh berikut:

      DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net

Alat Pengecoran

Pengayaan AI bawaan didukung oleh Foundry Tools, termasuk Bahasa Azure dan Azure Vision untuk pemrosesan bahasa dan gambar alami. Untuk beban kerja kecil seperti tutorial ini, Anda dapat menggunakan alokasi gratis 20 transaksi per pengindeks. Untuk beban kerja yang lebih besar, lampirkan sumber daya Microsoft Foundry ke kumpulan keterampilan untuk harga Standar.

Menyalin URL layanan pencarian dan kunci API

Untuk tutorial ini, koneksi ke Pencarian Azure AI memerlukan titik akhir dan kunci API. Anda bisa mendapatkan nilai-nilai ini dari portal Azure.

1. Buka layanan pencarian Anda di portal Microsoft Azure.

2. Dari panel kiri, pilih Gambaran Umum dan salin titik akhir. Harus dalam format ini: https://my-service.search.windows.net

3. Dari panel kiri, pilihKunci> dan salin kunci admin untuk hak penuh pada layanan. Ada dua kunci admin yang dapat dipertukarkan, disediakan untuk menjaga kelangsungan bisnis jika Anda perlu mengganti salah satunya. Anda dapat menggunakan kunci pada permintaan untuk menambahkan, mengubah, atau menghapus objek.

Atur lingkungan Anda

Mulailah dengan membuka Visual Studio dan membuat proyek Aplikasi Konsol baru.

Menginstal Azure.Search.Documents

Pencarian Azure AI .NET SDK terdiri dari pustaka klien yang memungkinkan Anda mengelola indeks, sumber data, pengindeks, dan set keterampilan, serta mengunggah dan mengelola dokumen dan menjalankan kueri, semuanya tanpa harus berurusan dengan detail HTTP dan JSON. Pustaka klien ini didistribusikan sebagai paket NuGet.

Untuk proyek ini, instal versi 11 atau yang lebih baru dari Azure.Search.Documents dan versi terbaru dari Microsoft.Extensions.Configuration.

1. Di Visual Studio, pilih Alat> Pengelola >Kelola Paket NuGet untuk Solusi...

2. Jelajahi Azure.Search.Document.

3. Pilih versi terbaru lalu pilih Instal.

4. Ulangi langkah-langkah sebelumnya untuk menginstal Microsoft.Extensions.Configuration dan Microsoft.Extensions.Configuration.Json.

Menambahkan informasi koneksi layanan

1. Klik kanan pada proyek Anda di Penjelajah Solusi dan pilih Tambahkan>Item Baru... .

2. Beri nama file appsettings.json dan pilih Tambahkan.

3. Sertakan file ini dalam direktori output Anda.

   1. Klik kanan pada appsettings.json dan pilih Properti.
   2. Ubah nilai Salin ke Direktori Output menjadi Salin jika lebih baru.

4. Salin JSON berikut ke dalam file JSON baru Anda.

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

Tambahkan layanan pencarian dan informasi akun penyimpanan blob Anda. Perlu diingat bahwa Anda bisa mendapatkan informasi ini dari langkah-langkah penyediaan layanan yang ditunjukkan di bagian sebelumnya.

Untuk SearchServiceUri, masukkan URL lengkap.

Menambahkan namespace

Di Program.cs, tambahkan namespace berikut.

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

Membuat klien

Buat instans dari SearchIndexClient dan SearchIndexerClient di bawah 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));
}

Tambahkan fungsi untuk keluar dari program selama kegagalan

Tutorial ini dimaksudkan untuk membantu Anda memahami setiap langkah alur pengindeksan. Jika ada masalah penting yang mencegah program membuat sumber data, set keterampilan, indeks, atau pengindeks, program menghasilkan pesan kesalahan dan keluar sehingga masalah dapat dipahami dan ditangani.

Tambahkan ExitProgram ke Main untuk menangani skenario yang mengharuskan program keluar.

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

Membuat alur kerja

Dalam Pencarian Azure AI, pemrosesan AI terjadi selama pengindeksan (atau penyerapan data). Bagian dari panduan ini akan membuat empat objek: sumber data, definisi indeks, skillset, pengindeks.

Langkah 1: Membuat sumber data

SearchIndexerClient memiliki DataSourceName properti yang dapat Anda atur ke SearchIndexerDataSourceConnection objek. Objek ini menyediakan semua metode yang Anda butuhkan untuk membuat, mencantumkan, memperbarui, atau menghapus sumber data Pencarian Azure AI.

Buat instans baru SearchIndexerDataSourceConnection dengan memanggil indexerClient.CreateOrUpdateDataSourceConnection(dataSource). Kode berikut membuat sumber data jenis 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;
}

Agar permintaan berhasil, metode mengembalikan sumber data yang dibuat. Jika ada masalah dengan permintaan, seperti parameter yang tidak valid, metode akan memberikan pengecualian.

Sekarang tambahkan baris di Main untuk memanggil CreateOrUpdateDataSource fungsi yang baru saja Anda tambahkan.

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

Bangun dan jalankan solusinya. Karena ini adalah permintaan pertama Anda, periksa portal Microsoft Azure untuk mengonfirmasi sumber data dibuat di Pencarian Azure AI. Pada halaman gambaran umum layanan pencarian, pastikan bahwa daftar Sumber Data memiliki item baru. Anda mungkin perlu menunggu beberapa menit agar halaman portal Microsoft Azure di-refresh.

Langkah 2: Buat kumpulan keterampilan

Di bagian ini, Anda menentukan serangkaian langkah pengayaan yang ingin Anda terapkan ke data Anda. Setiap langkah pengayaan disebut keterampilan dan serangkaian langkah pengayaan disebut set keterampilan. Tutorial ini menggunakan keterampilan bawaan untuk kumpulan keterampilan:

• Pengenalan Karakter Optik untuk mengenali teks cetak dan tulisan tangan dalam file gambar.

• Penggabungan Teks untuk mengonsolidasikan teks dari kumpulan bidang ke dalam satu bidang "konten gabungan".

• Deteksi Bahasa untuk mengidentifikasi bahasa konten.

• Pengenalan Entitas untuk mengekstrak nama organisasi dari konten dalam kontainer blob.

• Pemisahan Teks untuk memecah konten besar menjadi gugus yang lebih kecil sebelum memanggil keterampilan ekstraksi frasa kunci dan keterampilan pengenalan entitas. Ekstraksi frasa kunci dan pengenalan entitas menerima input 50.000 karakter atau kurang. Beberapa file sampel perlu dipisahkan agar sesuai dalam batas ini.

• Ekstraksi Frasa Kunci untuk menarik frasa kunci teratas.

Selama pemrosesan awal, Pencarian Azure AI memecahkan setiap dokumen untuk mengekstrak konten dari format file yang berbeda. Teks yang berasal dari file sumber ditempatkan ke dalam bidang yang dihasilkan content , satu untuk setiap dokumen. Dengan demikian, atur input sebagai "/document/content" untuk menggunakan teks ini. Konten gambar ditempatkan ke dalam bidang yang dihasilkan normalized_images, yang ditentukan dalam kumpulan keterampilan sebagai /document/normalized_images/*.

Output dapat dipetakan ke indeks, digunakan sebagai input ke keterampilan downstream, atau keduanya seperti halnya dengan kode bahasa. Dalam indeks, kode bahasa berguna untuk pemfilteran. Sebagai input, kode bahasa digunakan oleh keterampilan analisis teks untuk menginformasikan aturan linguistik seputar pemecahan kata.

Untuk mengetahui informasi selengkapnya tentang dasar-dasar skillset, lihat Cara menentukan skillset.

Keterampilan OCR

Mengekstrak OcrSkill teks dari gambar. Keterampilan ini mengasumsikan bahwa bidang normalized_images ada. Agar dapat menghasilkan bidang ini, nanti dalam tutorial diatur konfigurasi "imageAction" dalam definisi pengindeks menjadi "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;
}

Keterampilan penggabungan

Di bagian ini, Anda membuat MergeSkill yang menggabungkan bidang konten dokumen dengan teks yang dihasilkan oleh keterampilan 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;
}

Keterampilan deteksi bahasa

LanguageDetectionSkill mendeteksi bahasa dari teks input dan melaporkan satu kode bahasa untuk setiap dokumen yang dikirimkan atas permintaan. Kami menggunakan output keterampilan Deteksi Bahasa sebagai bagian dari input ke keterampilan Pemisahan Teks .

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

Keterampilan segmentasi teks

Berikut ini SplitSkill memisahkan teks menurut halaman dan membatasi panjang halaman menjadi 4.000 karakter seperti yang diukur oleh String.Length. Algoritma mencoba membagi teks menjadi potongan yang paling berukuran maximumPageLength . Dalam hal ini, algoritma melakukan yang terbaik untuk memutus kalimat pada batas kalimat, sehingga ukuran gugus mungkin sedikit kurang dari 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;
}

Keterampilan pengenalan entitas

Instans EntityRecognitionSkill ini diatur untuk mengenali jenis kategori organization. EntityRecognitionSkill juga dapat mengenali tipe kategori person dan location.

Perhatikan bahwa bidang "konteks" diatur ke "/document/pages/*" dengan tanda bintang, yang berarti langkah pengayaan dipanggil untuk setiap halaman di bawah "/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;
}

Keterampilan ekstraksi frasa kunci

Seperti instans EntityRecognitionSkill yang baru saja dibuat, KeyPhraseExtractionSkill dipanggil untuk setiap halaman dokumen.

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

Membangun dan mengembangkan keterampilan

Bangun SearchIndexerSkillset dengan menggunakan keterampilan yang telah Anda ciptakan.

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

Tambahkan baris berikut ke 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);

Langkah 3: Membuat indeks

Di bagian ini, Anda menentukan skema indeks dengan menentukan bidang mana yang akan disertakan dalam indeks yang dapat dicari, dan atribut pencarian untuk setiap bidang. Bidang memiliki jenis dan dapat mengambil atribut yang menentukan bagaimana bidang digunakan (dapat dicari, dapat diurutkan, dan sebagainya). Nama bidang dalam indeks tidak diperlukan untuk mencocokkan nama bidang di sumber secara identik. Di langkah selanjutnya, Anda menambahkan pemetaan bidang di pengindeks untuk menyambungkan bidang tujuan sumber. Untuk langkah ini, tentukan indeks menggunakan konvensi penamaan bidang yang berkaitan dengan aplikasi pencarian Anda.

Latihan ini menggunakan bidang dan jenis bidang berikut:

Nama bidang	Jenis bidang
id	Edm.String
content	Edm.String
languageCode	Edm.String
keyPhrases	Daftar<Edm.String>
organizations	Daftar<Edm.String>

Membuat Kelas DemoIndex

Bidang untuk indeks ini didefinisikan menggunakan kelas model. Setiap properti kelas model memiliki atribut yang menentukan perilaku terkait pencarian dari bidang indeks yang sesuai.

Kita akan menambahkan kelas model ke file C# baru. Pilih kanan pada proyek Anda dan pilih Tambahkan>Item Baru... , pilih "Kelas" dan beri nama file DemoIndex.cs, lalu pilih Tambahkan.

Pastikan untuk menyatakan bahwa Anda ingin menggunakan jenis dari ruang nama Azure.Search.Documents.Indexes dan System.Text.Json.Serialization.

Tambahkan definisi kelas model berikut ke DemoIndex.cs dan sertakan dalam namespace yang sama tempat Anda membuat 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; }
    }
}

Sekarang setelah Anda mendefinisikan kelas model, kembali di Program.cs Anda dapat dengan mudah membuat definisi indeks. Nama untuk indeks ini adalah demoindex. Jika indeks sudah ada dengan nama tersebut, indeks akan dihapus.

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

Selama pengujian, Anda mungkin menemukan bahwa Anda mencoba membuat indeks lebih dari sekali. Karena itu, periksa untuk melihat apakah indeks yang akan Anda buat sudah ada sebelum mencoba membuatnya.

Tambahkan baris berikut ke Main.

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

Tambahkan pernyataan penggunaan berikut untuk mengatasi referensi yang telah disambiguasi.

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

Untuk mempelajari selengkapnya tentang konsep indeks, lihat Membuat Indeks (REST API).

Langkah 4 - Buat dan jalankan pengindeks

Sejauh ini Anda telah membuat sumber data, set keterampilan, dan indeks. Ketiga komponen ini menjadi bagian dari pengindeks yang menarik setiap bagian menjadi satu operasi multi-fase. Untuk mengikatnya bersama-sama dalam pengindeks, Anda harus menentukan pemetaan bidang.

• FieldMappings diproses sebelum skillset, memetakan bidang sumber dari sumber data ke bidang target di indeks. Jika nama dan jenis bidang sama di kedua ujungnya, tidak diperlukan pemetaan.

• OutputFieldMappings diproses setelah skillset, mengacu pada sourceFieldNames yang tidak ada sampai proses pemecahan atau pengayaan dokumen membuatnya. targetFieldName adalah bidang dalam indeks.

Selain menghubungkan input ke output, Anda juga dapat menggunakan pemetaan bidang untuk meratakan struktur data. Untuk informasi selengkapnya, lihat Cara memetakan bidang yang diperkaya ke indeks yang dapat dicari.

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

Tambahkan baris berikut ke 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);

Harapkan pemrosesan pengindeks membutuhkan waktu untuk menyelesaikannya. Meskipun himpunan datanya memang kecil, keterampilan analitis sangat berkomputasi intensif. Beberapa keterampilan, seperti analisis gambar, berjalan lama.

Mengeksplorasi pembuatan pengindeks

Kode diatur "maxFailedItems" ke -1, yang menginstruksikan mesin pengindeksan untuk mengabaikan kesalahan selama impor data. Ini berguna karena ada begitu sedikit dokumen di sumber data demo. Untuk sumber data yang lebih besar, Anda akan menetapkan nilainya menjadi lebih besar dari 0.

Perhatikan "dataToExtract" juga diatur ke "contentAndMetadata". Pernyataan ini memberi tahu pengindeks untuk secara otomatis mengekstrak konten dari format file yang berbeda serta metadata yang terkait dengan setiap file.

Saat konten diekstrak, Anda dapat mengatur imageAction untuk mengekstrak teks dari gambar yang ditemukan di sumber data. Atur "imageAction" ke konfigurasi "generateNormalizedImages", digabungkan dengan Kemampuan OCR dan Kemampuan Penggabungan Teks, menginstruksikan pengindeks untuk mengekstrak teks dari gambar (misalnya, kata "berhenti" dari rambu Berhenti lalu lintas) dan memasukkannya sebagai bagian dari bidang konten. Perilaku ini berlaku untuk gambar yang disematkan dalam dokumen (pikirkan gambar di dalam PDF), serta gambar yang ditemukan di sumber data, misalnya file JPG.

Memantau pengindeksan

Setelah pengindeks ditentukan, pengindeks berjalan secara otomatis saat Anda mengirimkan permintaan. Tergantung pada keterampilan mana yang Anda tentukan, pengindeksan dapat memakan waktu lebih lama dari yang Anda harapkan. Untuk mengetahui apakah pengindeks masih berjalan, gunakan metode .GetStatus

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 mewakili status saat ini dan riwayat eksekusi pengindeks.

Peringatan sering terjadi pada beberapa kombinasi file sumber dan keterampilan dan tidak selalu menunjukkan adanya masalah. Dalam tutorial ini, peringatan tersebut tidak berbahaya (misalnya, tidak ada pembacaan input teks dari file JPEG).

Tambahkan baris berikut ke Main.

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

Search

Di aplikasi konsol tutorial Pencarian Azure AI, kami biasanya menambahkan penundaan 2 detik sebelum menjalankan kueri yang mengembalikan hasil, tetapi karena pengayaan membutuhkan waktu beberapa menit untuk diselesaikan, kami akan menutup aplikasi konsol dan menggunakan pendekatan lain sebagai gantinya.

Opsi term mudah adalah Search Explorer di portal Microsoft Azure. Anda dapat terlebih dahulu menjalankan kueri kosong yang mengembalikan semua dokumen, atau pencarian yang lebih ditargetkan yang mengembalikan konten bidang baru yang dibuat oleh alur.

1. Di portal Azure, di halaman layanan pencarian, perluas Manajemen Pencarian>Indeks.

2. Temukan demoindex dalam daftar. Ini harus memiliki 14 dokumen. Jika jumlah dokumen nol, pengindeks masih berjalan atau halaman belum disegarkan.

3. Pilih demoindex. Penjelajah Pencarian adalah tab pertama.

4. Konten dapat dicari segera setelah dokumen pertama dimuat. Untuk memverifikasi konten ada, jalankan kueri yang tidak ditentukan dengan mengklik Cari. Kueri ini mengembalikan semua dokumen yang saat ini diindeks, memberi Anda gambaran tentang apa yang dikandung indeks.

5. Untuk hasil yang lebih mudah dikelola, beralihlah ke tampilan JSON dan atur parameter untuk memilih bidang:

   {
       "search": "*",
       "count": true,
       "select": "id, languageCode, organizations"
   }
   

Atur ulang dan jalankan ulang

Pada tahap pengembangan eksperimental awal, pendekatan paling praktis untuk iterasi desain adalah menghapus objek dari Pencarian Azure AI dan memungkinkan kode Anda untuk membangunnya kembali. Nama sumber daya bersifat unik. Menghapus objek memungkinkan Anda membuatnya kembali menggunakan nama yang sama.

Kode sampel untuk tutorial ini memeriksa objek yang ada dan menghapusnya agar Anda dapat menjalankan kembali kode Anda. Anda juga dapat menggunakan portal Microsoft Azure untuk menghapus indeks, pengindeks, sumber data, dan set keterampilan.

Takeaways

Tutorial ini menunjukkan langkah-langkah dasar untuk membangun alur pengindeksan yang diperkaya melalui pembuatan bagian komponen: sumber data, set keterampilan, indeks, dan pengindeks.

Keterampilan bawaan diperkenalkan, bersama dengan definisi set keterampilan dan mekanisme menghubungkan keterampilan secara berantai melalui input dan output. Anda juga mempelajari bahwa outputFieldMappings dalam definisi pengindeks diperlukan untuk merutekan nilai yang diperkaya dari pipeline ke dalam indeks yang dapat dicari pada layanan Pencarian Azure AI.

Akhirnya, Anda sudah belajar cara menguji hasil dan mengatur ulang sistem untuk iterasi lebih lanjut. Anda sudah belajar bahwa memasukkan kueri terhadap indeks menyajikan output yang dibuat oleh alur pengindeksan yang diperkaya. Anda juga mempelajari cara memeriksa status pengindeks, dan objek mana yang akan dihapus sebelum menjalankan ulang alur.

Membersihkan sumber daya

Saat Anda bekerja di langganan milik Anda sendiri, di akhir proyek, sebaiknya hapus sumber daya yang tidak lagi Anda butuhkan. Sumber daya yang dibiarkan tetap aktif dapat merugikan Anda secara finansial. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus seluruh kumpulan sumber daya.

Anda dapat menemukan dan mengelola sumber daya di portal Azure, menggunakan tautan Semua sumber daya atau Grup sumber daya di panel navigasi kiri.

Langkah selanjutnya

Sekarang setelah Anda terbiasa dengan semua objek dalam alur pengayaan AI, mari kita telaah lebih dalam definisi keterampilan dan keterampilan individu secara spesifik.

Pelajari cara memanggil REST API yang membuat alur pengayaan AI untuk ekstraksi konten dan transformasi selama pengindeksan.

Skillset menambahkan pemrosesan AI ke konten mentah, membuatnya lebih seragam dan mudah dicari. Setelah Anda memahami cara kerja set keterampilan, Anda dapat mendukung berbagai transformasi, mulai dari analisis gambar hingga pemrosesan bahasa alami hingga pemrosesan yang disesuaikan yang Anda berikan secara eksternal.

Di tutorial ini, Anda akan:

Overview

Tutorial ini menggunakan klien REST dan REST API Pencarian Azure AI untuk membuat sumber data, indeks, pengindeks, dan set keterampilan.

Pengindeks mendorong setiap langkah dalam alur, dimulai dengan ekstraksi konten data sampel (teks dan gambar yang tidak terstruktur) dalam kontainer blob di Azure Storage.

Setelah konten diekstrak, kumpulan keterampilan menjalankan fungsi bawaan dari Microsoft untuk menemukan dan mengekstrak informasi. Keterampilan ini termasuk Pengenalan Karakter Optik (OCR) pada gambar, deteksi bahasa pada teks, ekstraksi frasa kunci, dan pengenalan entitas (organisasi). Informasi baru yang dihasilkan oleh kumpulan keterampilan dikirim ke bidang dalam indeks. Setelah indeks telah diisi, Anda dapat menggunakan bidang dalam kueri, faset, dan filter.

Prerequisites

• Sebuah akun Azure dengan langganan aktif. Buat akun secara gratis.

• Azure Storage

• Pencarian Azure AI

• Visual Studio Code dengan klien REST

Mengunduh file

Unduh file zip dari repositori data sampel dan ekstrak kontennya. Pelajari caranya.

• File data sampel (media campuran).

• File sampel REST

Mengunggah data sampel ke Azure Storage

1. Di Azure Storage, buat kontainer baru dan beri nama cog-search-demo.

2. Unggah file data sampel.

3. Dapatkan string koneksi penyimpanan sehingga Anda bisa merumuskan koneksi di Pencarian Azure AI.

   1. Di sebelah kiri, pilih Tombol akses.

   2. Salin string koneksi untuk kunci satu atau kunci dua. string koneksi mirip dengan contoh berikut:

      DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net

Alat Pengecoran

Pengayaan AI bawaan didukung oleh Foundry Tools, termasuk Bahasa Azure dan Azure Vision untuk pemrosesan bahasa dan gambar alami. Untuk beban kerja kecil seperti tutorial ini, Anda dapat menggunakan alokasi gratis dua puluh transaksi per pengindeks. Untuk beban kerja yang lebih besar, lampirkan sumber daya Microsoft Foundry ke kumpulan keterampilan untuk harga Standar.

Menyalin URL layanan pencarian dan kunci API

Untuk tutorial ini, koneksi ke Pencarian Azure AI memerlukan titik akhir dan kunci API. Anda bisa mendapatkan nilai-nilai ini dari portal Azure.

1. Buka layanan pencarian Anda di portal Microsoft Azure.

2. Dari panel kiri, pilih Gambaran Umum dan salin titik akhir. Harus dalam format ini: https://my-service.search.windows.net

3. Dari panel kiri, pilihKunci> dan salin kunci admin untuk hak penuh pada layanan. Ada dua kunci admin yang dapat dipertukarkan, disediakan untuk menjaga kelangsungan bisnis jika Anda perlu mengganti salah satunya. Anda dapat menggunakan kunci pada permintaan untuk menambahkan, mengubah, atau menghapus objek.

   

Menyiapkan file REST Anda

1. Mulai Visual Studio Code dan buka file skillset-tutorial.rest . Lihat Mulai Cepat: Pencarian teks lengkap jika Anda memerlukan bantuan dengan klien REST.

2. Berikan nilai untuk variabel: titik akhir layanan pencarian, kunci API admin layanan pencarian, nama indeks, string koneksi ke akun Azure Storage Anda, dan nama kontainer blob.

Membuat alur kerja

Pengayaan AI digerakkan oleh pengindeks. Bagian dari panduan ini akan membuat empat objek: sumber data, definisi indeks, skillset, pengindeks.

Langkah 1: Membuat sumber data

Panggil Buat Sumber Data untuk mengatur string koneksi ke kontainer Blob yang berisi file data sampel.

### Create a data source
POST {{baseUrl}}/datasources?api-version=2026-04-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
    }

Langkah 2: Buat kumpulan keterampilan

Panggil Create Skillset untuk menentukan langkah pengayaan mana yang diterapkan ke konten Anda. Keterampilan dijalankan secara paralel kecuali ada dependensi.

### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2026-04-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"
                }
            ]
            }
        ]
    }

Poin utama:

• Isi permintaan menentukan keterampilan bawaan berikut:

  Skill	Description
  Pengenalan Karakter Optik	Mengenali teks dan angka dalam file gambar.
  Penggabungan Teks	Membuat "konten gabungan" yang menggabungkan ulang konten yang dipisahkan sebelumnya, berguna untuk dokumen dengan gambar yang disematkan (PDF, DOCX, dan sebagainya). Gambar dan teks dipisahkan selama fase pemecahan dokumen. Kemampuan penggabungan menyatukan kembali elemen-elemen tersebut dengan memasukkan teks, keterangan gambar, atau tag yang dikenali, yang dibuat selama proses pengayaan, ke lokasi yang sama dari mana gambar tersebut diekstraksi dalam dokumen. Saat Anda bekerja dengan konten yang digabungkan dalam set keterampilan, simpul ini termasuk semua teks dalam dokumen, termasuk dokumen teks saja yang tidak pernah menjalani OCR atau analisis gambar.
  Deteksi Bahasa	Mendeteksi bahasa dan menghasilkan dalam bentuk nama bahasa atau kode. Dalam himpunan data multibahasa, bidang bahasa dapat berguna untuk filter.
  Pengenalan Entitas	Mengekstrak nama orang, organisasi, dan lokasi dari konten gabungan.
  Pemisahan Teks	Memecah konten gabungan besar menjadi gugus yang lebih kecil sebelum memanggil keterampilan ekstraksi frasa kunci. Ekstraksi frasa kunci menerima input 50.000 karakter atau kurang. Beberapa file sampel perlu dipisahkan agar sesuai dalam batas ini.
  Ekstraksi Frasa Kunci	Mengeluarkan frasa kunci terpenting.

• Setiap keterampilan dijalankan pada konten dokumen. Selama pemrosesan, Pencarian Azure AI memecahkan setiap dokumen untuk membaca konten dari format file yang berbeda. Teks yang ditemukan berasal dari file sumber ditempatkan di dalam bidang content yang dihasilkan, satu untuk setiap dokumen. Dengan demikian, masukan menjadi "/document/content".

• Untuk ekstraksi frasa kunci, karena kita menggunakan keterampilan pemisah teks untuk memecah file yang lebih besar ke dalam halaman, konteks untuk keterampilan ekstraksi frasa kunci adalah "document/pages/*" (untuk setiap halaman dalam dokumen) bukan "/document/content".

Langkah 3: Membuat indeks

Panggil Buat Indeks untuk menyediakan skema yang digunakan untuk membuat indeks terbalik dan konstruksi lain di Pencarian Azure AI.

Komponen terbesar indeks adalah kumpulan bidang, di mana jenis data dan atribut menentukan konten dan perilaku di Pencarian Azure AI. Pastikan Anda memiliki bidang untuk output yang baru dihasilkan.

### Create an index
POST {{baseUrl}}/indexes?api-version=2026-04-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
            }
        ]
    }

Langkah 4 - Buat dan jalankan pengindeks

Panggil Buat Pengindeks untuk mendorong alur. Tiga komponen yang sudah Anda buat sejauh ini (sumber data, skillset, indeks) adalah input ke pengindeks. Membuat pengindeks di Pencarian Azure AI adalah peristiwa yang membuat seluruh alur bergerak.

Diperlukan waktu beberapa menit untuk menyelesaikan langkah ini. Meskipun himpunan datanya memang kecil, keterampilan analitis sangat berkomputasi intensif.

### Create and run an indexer
POST {{baseUrl}}/indexers?api-version=2026-04-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"
            }
        }
    }

Poin utama:

• Isi permintaan mencakup referensi ke objek sebelumnya, properti konfigurasi yang diperlukan untuk pemrosesan gambar, dan dua jenis pemetaan bidang.

• "fieldMappings" diproses sebelum kumpulan keterampilan, mengirimkan konten dari sumber data ke bidang target dalam indeks. Anda menggunakan pemetaan bidang untuk mengirim konten yang sudah ada dan tidak dimodifikasi ke indeks. Jika nama dan jenis bidang sama di kedua ujungnya, tidak diperlukan pemetaan.

• "outputFieldMappings" digunakan untuk kolom yang dibuat oleh kemampuan, setelah pelaksanaan skillset. Referensi ke sourceFieldName dalam outputFieldMappings baru ada setelah dokumen dipecahkan atau diperkaya. targetFieldName adalah bidang dalam indeks, didefinisikan dalam skema indeks.

• Parameter "maxFailedItems" diatur ke -1, yang menginstruksikan mesin pengindeksan untuk mengabaikan kesalahan selama impor data. Ini dapat diterima karena ada sedikit dokumen dalam sumber data demo. Untuk sumber data yang lebih besar, Anda akan menetapkan nilainya menjadi lebih besar dari 0.

• Pernyataan ini "dataToExtract":"contentAndMetadata" memberi tahu pengindeks untuk secara otomatis mengekstrak nilai dari properti konten blob dan metadata setiap objek.

• Parameter imageAction memberi tahu pengindeks untuk mengekstrak teks dari gambar yang ditemukan di sumber data. Konfigurasi "imageAction":"generateNormalizedImages", dikombinasikan dengan Keterampilan OCR dan Keterampilan Penggabungan Teks, memberi tahu pengindeks untuk mengekstrak teks dari gambar (misalnya, kata "berhenti" dari tanda Berhenti lalu lintas), dan menyematkannya sebagai bagian dari bidang konten. Perilaku ini berlaku untuk gambar yang disematkan (pikirkan gambar di dalam PDF) dan file gambar mandiri, misalnya file JPG.

Memantau pengindeksan

Pengindeksan dan pengayaan dimulai segera setelah Anda mengirimkan permintaan Create Indexer. Tergantung pada kompleksitas dan operasi skillset, pengindeksan dapat memakan waktu cukup lama.

Untuk mengetahui apakah pengindeks masih berjalan, panggil Dapatkan Status Pengindeks untuk memeriksa status pengindeks.

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

Poin utama:

• Peringatan umum dalam beberapa skenario dan tidak selalu menunjukkan masalah. Misalnya, jika kontainer blob menyertakan file gambar, dan alur tidak menangani gambar, Anda mendapatkan peringatan yang menyatakan bahwa gambar tidak diproses.

• Dalam sampel ini, ada file PNG yang tidak berisi teks. Kelima keterampilan berbasis teks (deteksi bahasa, pengenalan entitas lokasi, organisasi, orang, dan ekstraksi frasa kunci) gagal dijalankan pada file ini. Pemberitahuan yang dihasilkan tercantum dalam riwayat eksekusi.

Memeriksa hasil

Sekarang setelah Anda membuat indeks yang berisi konten yang dihasilkan AI, panggil Cari Dokumen untuk menjalankan beberapa kueri untuk melihat hasilnya.

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

Filter dapat membantu Anda mempersempit hasil ke item yang menarik:

### Filter by organization
POST {{baseUrl}}/indexes/cog-search-demo-idx/docs/search?api-version=2026-04-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
  }

Kueri ini mengilustrasikan beberapa cara Anda dapat bekerja dengan sintaks kueri dan filter pada bidang baru yang dibuat oleh Pencarian Azure AI. Untuk contoh kueri lainnya, lihat Contoh di REST API Search Documents, Contoh kueri sintaks sederhana, dan contoh kueri Lucene Penuh.

Atur ulang dan jalankan ulang

Selama tahap awal pengembangan, iterasi atas desain adalah umum. Reset dan mulai ulang membantu iterasi.

Takeaways

Tutorial ini menunjukkan langkah-langkah dasar untuk menggunakan REST API untuk membuat alur pengayaan AI: sumber data, set keterampilan, indeks, dan pengindeks.

Keterampilan bawaan diperkenalkan, bersama dengan definisi set keterampilan yang menunjukkan mekanisme perangkaian keterampilan yang dirangkai bersama-sama melalui input dan output. Anda juga mempelajari bahwa outputFieldMappings dalam definisi pengindeks diperlukan untuk merutekan nilai yang diperkaya dari pipeline ke dalam indeks yang dapat dicari pada layanan Pencarian Azure AI.

Akhirnya, Anda sudah belajar cara menguji hasil dan mengatur ulang sistem untuk iterasi lebih lanjut. Anda sudah belajar bahwa memasukkan kueri terhadap indeks menyajikan output yang dibuat oleh alur pengindeksan yang diperkaya.

Membersihkan sumber daya

Saat Anda bekerja di langganan milik Anda sendiri, di akhir proyek, sebaiknya hapus sumber daya yang tidak lagi Anda butuhkan. Sumber daya yang dibiarkan tetap aktif dapat merugikan Anda secara finansial. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus seluruh kumpulan sumber daya.

Anda dapat menemukan dan mengelola sumber daya di portal Azure, menggunakan tautan Semua sumber daya atau Grup sumber daya di panel navigasi kiri.

Langkah selanjutnya

Sekarang setelah Anda terbiasa dengan semua objek dalam alur pengayaan AI, silahkan memeriksa lebih detail definisi kumpulan keterampilan dan keterampilan individu.