Memotong dan mem-vektorisasi konten dengan keterampilan Pemahaman Konten Azure

Dalam artikel ini, Anda mempelajari cara menggunakan keterampilan Azure Content Understanding untuk:

Keahlian Azure Content Understanding mengembalikan satu atau beberapa bagian per dokumen. Setiap potongan berisi konten berformat Markdown, metadata lokasi (nomor halaman dan poligon pembatas), dan referensi opsional untuk gambar yang diekstrak. Saat Anda mengatur chunkingProperties.method ke semantic, potongan mengikuti batas paragraf dan judul alih-alih rentang karakter tetap. Saat Anda mengatur modelName dan modelDeployment, keterampilan ini memanggil penyebaran penyelesaian obrolan OpenAI Azure untuk menghasilkan deskripsi gambar yang disematkan. Kemampuan tersebut kemudian menggabungkan deskripsi itu menjadi konten potongan.

Artikel ini menggunakan PDF contoh rencana kesehatan sebagai ilustrasi. Anda dapat menjalankan alur yang sama terhadap sumber data yang didukung yang mengekspos file dalam format yang didukung Content Understanding.

Prerequisites

• Layanan Pencarian Azure AI di wilayah yang didukung. Layanan pencarian itu sendiri tidak dibatasi wilayah untuk skenario ini.

• Sumber daya Microsoft Foundry di wilayah yang didukung oleh keterampilan Azure Content Understanding. Deskripsi gambar dan segmentasi diproses di wilayah sumber daya Foundry.

• Sumber daya Microsoft Foundry dilampirkan ke skillset untuk penagihan. Keahlian Azure Content Understanding ditagihkan sesuai harga Azure Content Understanding.

• (Opsional) Penyebaran Azure OpenAI dari model penyelesaian percakapan (seperti gpt-4.1) dalam sumber daya Foundry yang sama, yang digunakan untuk menghasilkan deskripsi gambar. Diperlukan hanya jika Anda menginginkan deskripsi gambar berbasis AI.

• Penyebaran Azure OpenAI dari model penyematan (seperti text-embedding-3-small), digunakan oleh Azure keterampilan OpenAI Embedding untuk mem-vektorisasi gugus.

• Kontainer Azure Blob Storage dengan file yang ingin Anda indeks. Artikel ini menggunakan sumber data blob dengan pengaturan pengindeks allowSkillsetToReadFileData (yang digunakan untuk meneruskan konten file ke skill Content Understanding).

Overview

Artikel ini membangun alur pengindeksan satu-ke-banyak. Setiap dokumen sumber menghasilkan beberapa dokumen pencarian (satu per gugus):

1. Pengindeks membaca setiap file dari Azure Blob Storage dan meneruskan konten biner ke kumpulan keterampilan melalui /document/file_data.

2. Kemampuan Azure Content Understanding menggunakan pemenggalan semantik (pratinjau) untuk menghasilkan text_sections. Ketika modelName dan modelDeployment diatur, deskripsi gambar yang disematkan yang dibuat oleh AI (pratinjau) juga dihasilkan dan disisipkan langsung ke dalam Markdown setiap bagian.

3. Skill Azure OpenAI Embedding dijalankan sekali untuk setiap potongan dan menghasilkan vektor untuk konten potongan tersebut.

4. Proyeksi indeks menulis satu dokumen pencarian per gugus ke dalam indeks target, konten pemetaan, metadata halaman, referensi gambar, dan vektor ke bidang.

5. (Opsional) Sebuah penyimpanan pengetahuan memproyeksikan normalized_images ke Azure Blob Storage sehingga aplikasi klien dapat mengambil gambar yang diekstrak melalui URL.

Siapkan file data

Keterampilan Azure Content Understanding memproses konten biner dari setiap dokumen, sehingga file sumber harus dalam format yang didukung keterampilan. Untuk daftar saat ini, lihat batas layanan Pemahaman Konten. Format umum yang didukung termasuk PDF, DOCX, XLSX, PPTX, dan banyak format gambar.

Unggah file Anda ke sumber data yang didukung. Anda dapat menggunakan portal Azure, REST API, atau Azure SDK untuk buat sumber data.

Permintaan minimal berikut membuat sumber data yang digunakan di seluruh panduan ini.

POST {endpoint}/datasources?api-version=2026-08-01-preview

{
  "name": "my_blob_datasource",
  "type": "azureblob",
  "credentials": {
    "connectionString": "<your-blob-connection-string>"
  },
  "container": {
    "name": "my-container"
  }
}

Membuat indeks untuk pengindeksan satu ke banyak

Setiap dokumen penelusuran sesuai dengan satu bagian yang dihasilkan oleh keterampilan Pemahaman Konten. Indeks membutuhkan:

• Bidang kunci (chunk_id).
• Kolom induk yang mengidentifikasi dokumen sumber asal chunk tersebut (parent_id).
• Bidang yang menyimpan konten gugus, metadata halaman, dan referensi gambar.
• Bidang vektor untuk penyematan gugus.

Definisi indeks berikut cocok dengan set keterampilan yang Anda buat di bagian berikutnya.

{
  "name": "my_content_understanding_index",
  "fields": [
    {
      "name": "chunk_id",
      "type": "Edm.String",
      "key": true,
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": true,
      "facetable": false,
      "analyzer": "keyword"
    },
    {
      "name": "parent_id",
      "type": "Edm.String",
      "searchable": false,
      "filterable": true,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "title",
      "type": "Edm.String",
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "chunk",
      "type": "Edm.String",
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "page_number_from",
      "type": "Edm.Int32",
      "searchable": false,
      "filterable": true,
      "retrievable": true,
      "stored": true,
      "sortable": true,
      "facetable": false
    },
    {
      "name": "page_number_to",
      "type": "Edm.Int32",
      "searchable": false,
      "filterable": true,
      "retrievable": true,
      "stored": true,
      "sortable": true,
      "facetable": false
    },
    {
      "name": "image_path",
      "type": "Edm.String",
      "searchable": false,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "text_vector",
      "type": "Collection(Edm.Single)",
      "searchable": true,
      "retrievable": true,
      "stored": false,
      "dimensions": 1536,
      "vectorSearchProfile": "profile"
    }
  ],
  "vectorSearch": {
    "profiles": [
      {
        "name": "profile",
        "algorithm": "algorithm"
      }
    ],
    "algorithms": [
      {
        "name": "algorithm",
        "kind": "hnsw"
      }
    ]
  }
}

Tentukan set keterampilan untuk pemotongan semantik (pratinjau) dan vektorisasi

Setelah indeks target tersedia, tentukan kumpulan keterampilan yang menghasilkan segmen, vektor, dan pemetaan proyeksi yang memasok data ke indeks tersebut.

Skillset memiliki dua keterampilan:

• Keahlian Azure Content Understanding membagi setiap dokumen menjadi beberapa bagian. Mengatur chunkingProperties.method ke semantic membuat keterampilan mematuhi batas paragraf dan judul. Menetapkan modelName dan modelDeployment mengaktifkan deskripsi gambar yang dihasilkan AI (pratinjau), yang disisipkan oleh keterampilan langsung ke dalam konten potongan sebelum vektorisasi. Untuk daftar model penyelesaian obrolan yang didukung dan detail parameter lainnya, lihat Parameter keterampilan.

• Keahlian Azure OpenAI Embedding menghasilkan vektor untuk konten setiap potongan.

Skillset menggunakan indexProjections untuk memetakan setiap potongan ke dalam dokumen pencarian terpisah. Untuk informasi selengkapnya, lihat Menentukan proyeksi indeks.

Sebelum Anda mengirim permintaan, ganti <subdomain> dengan subdomain OpenAI Azure Anda, <Azure OpenAI api key> dengan kunci sumber daya penyematan, dan <Foundry resource key> dengan kunci untuk sumber daya Foundry yang melekat pada skillset.

POST {endpoint}/skillsets?api-version=2026-08-01-preview

{
  "name": "my_content_understanding_skillset",
  "description": "Semantic chunking, image descriptions, and vectorization with the Azure Content Understanding skill",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Util.ContentUnderstandingSkill",
      "name": "my_content_understanding_skill",
      "context": "/document",
      "modelName": "gpt-4.1",
      "modelDeployment": "my-gpt-4-1-deployment",
      "chunkingProperties": {
        "method": "semantic",
        "unit": "tokens",
        "maximumLength": 500
      },
      "extractionOptions": ["images", "locationMetadata"],
      "inputs": [
        {
          "name": "file_data",
          "source": "/document/file_data"
        }
      ],
      "outputs": [
        {
          "name": "text_sections",
          "targetName": "text_sections"
        },
        {
          "name": "normalized_images",
          "targetName": "normalized_images"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
      "name": "my_azure_openai_embedding_skill",
      "context": "/document/text_sections/*",
      "inputs": [
        {
          "name": "text",
          "source": "/document/text_sections/*/content"
        }
      ],
      "outputs": [
        {
          "name": "embedding",
          "targetName": "text_vector"
        }
      ],
      "resourceUri": "https://<subdomain>.openai.azure.com",
      "deploymentId": "text-embedding-3-small",
      "modelName": "text-embedding-3-small",
      "apiKey": "<Azure OpenAI api key>"
    }
  ],
  "cognitiveServices": {
    "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
    "key": "<Foundry resource key>"
  },
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "my_content_understanding_index",
        "parentKeyFieldName": "parent_id",
        "sourceContext": "/document/text_sections/*",
        "mappings": [
          {
            "name": "chunk",
            "source": "/document/text_sections/*/content"
          },
          {
            "name": "text_vector",
            "source": "/document/text_sections/*/text_vector"
          },
          {
            "name": "page_number_from",
            "source": "/document/text_sections/*/locationMetadata/pageNumberFrom"
          },
          {
            "name": "page_number_to",
            "source": "/document/text_sections/*/locationMetadata/pageNumberTo"
          },
          {
            "name": "image_path",
            "source": "/document/text_sections/*/imagePath"
          },
          {
            "name": "title",
            "source": "/document/metadata_storage_name"
          }
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

Untuk referensi parameter lengkap, nilai yang didukung, dan aturan validasi untuk keterampilan Pemahaman Konten, lihat keterampilan pemahaman konten Azure.

Mengonfigurasi dan menjalankan pengindeks

Buat dan jalankan pengindeks yang membaca data dari sumber data Anda, memanggil kumpulan keterampilan, dan memasukkan potongan data ke dalam indeks. Atur allowSkillsetToReadFileData ke true agar keterampilan Content Understanding menerima konten file, dan diatur parsingMode ke default.

Anda tidak perlu outputFieldMappings dalam skenario ini. Blok indexProjections dalam kumpulan keterampilan tersebut sudah memetakan setiap potongan ke bidang indeks target.

POST {endpoint}/indexers?api-version=2026-08-01-preview

{
  "name": "my_content_understanding_indexer",
  "dataSourceName": "my_blob_datasource",
  "targetIndexName": "my_content_understanding_index",
  "skillsetName": "my_content_understanding_skillset",
  "parameters": {
    "batchSize": 1,
    "configuration": {
      "dataToExtract": "contentAndMetadata",
      "parsingMode": "default",
      "allowSkillsetToReadFileData": true
    }
  },
  "fieldMappings": [],
  "outputFieldMappings": []
}

Saat pengindeks berjalan, keterampilan Pemahaman Konten menggunakan penggugusan semantik (pratinjau), secara opsional menghasilkan deskripsi gambar berbasis AI (pratinjau), dan menulis satu dokumen pencarian per gugus ke indeks.

Periksa status pengindeks

Sebelum Anda melakukan kueri, pastikan proses pengindeksan telah selesai:

GET {endpoint}/indexers/my_content_understanding_indexer/status?api-version=2026-08-01-preview

Verifikasi bahwa lastResult.status adalah success. Jika nilainya transientFailure dengan itemsProcessed lebih tinggi daripada 0, proses tersebut berhasil sebagian, dan Anda masih dapat menjalankan kueri pada bagian-bagian yang telah terisi. Untuk informasi selengkapnya, lihat Memantau status pengindeks.

Memverifikasi hasil

Kueri indeks untuk memverifikasi bahwa gugus berisi konten yang diharapkan dan pencarian vektor berfungsi seperti yang diharapkan. Gunakan Search Explorer atau alat apa pun yang mengirim permintaan HTTP.

Permintaan berikut menjalankan kueri hibrid (pencarian kata kunci pada chunk dan kueri vektor terhadap text_vector) untuk mengonfirmasi bahwa teks yang telah dibagi menjadi beberapa chunk dan sematan sudah terisi.

POST /indexes/my_content_understanding_index/docs/search?api-version=2026-08-01-preview
{
  "search": "copay for in-network providers",
  "count": true,
  "searchMode": "all",
  "vectorQueries": [
    {
      "kind": "text",
      "text": "copay for in-network providers",
      "fields": "text_vector"
    }
  ],
  "select": "chunk, title, page_number_from, page_number_to, image_path"
}

Respons yang berhasil tampak seperti berikut ini (dipersingkat agar ringkas):

{
  "@odata.count": 2,
  "value": [
    {
      "@search.score": 0.0317,
      "chunk": "## Cost sharing\n\nFor in-network providers, the copay is $20 per visit...\n\n![Chart: Copay comparison across plans](figures/3)",
      "title": "Northwind_Standard_Benefits_Details.pdf",
      "page_number_from": 4,
      "page_number_to": 4,
      "image_path": "figures/3"
    },
    {
      "@search.score": 0.0289,
      "chunk": "### Out-of-network providers\n\nWhen you visit a provider that isn't in the Northwind network, the copay is $40 per visit...",
      "title": "Northwind_Standard_Benefits_Details.pdf",
      "page_number_from": 5,
      "page_number_to": 6,
      "image_path": null
    }
  ]
}

Responsnya meliputi:

• chunk: Konten Markdown dari setiap gugus. Saat Anda mengonfigurasi modelName dan modelDeployment, deskripsi gambar yang dihasilkan AI (pratinjau) muncul sebaris dalam Markdown.
• page_number_from dan page_number_to: Rentang halaman yang menghasilkan potongan tersebut.
• image_path: Jalur ke gambar yang diekstrak dengan gugus atau, ketika gugus mencakup beberapa gambar, daftar jalur yang dipisahkan titik koma. Bentuk yang tepat tergantung pada apakah proyeksi file penyimpanan pengetahuan dikonfigurasi. Tanpa proyeksi file, jalur adalah bentuk pendek yang ditunjukkan dalam contoh (figures/3). Dengan proyeksi file, jalurnya adalah jalur relatif gambar di penyimpanan pengetahuan. Agar gambar-gambar ini tersedia bagi aplikasi klien, lihat (Opsional) Gambar proyek untuk diambil kembali.

(Opsional) Gambar proyek untuk pengambilan kembali

Nilai image_path yang disimpan dalam indeks adalah penunjuk ke pohon pengayaan keterampilan, bukan URL yang dapat diambil secara langsung. Untuk mengambil gambar, proyeksikan normalized_images ke Azure Blob Storage dengan menggunakan knowledge store, lalu hasilkan URL blob untuk setiap potongan.

Langkah ini bersifat opsional. Tambahkan hanya jika aplikasi klien Anda perlu menampilkan atau mengunduh gambar yang diekstrak.

Tambahkan properti berikut ke payload skillset dari bagian sebelumnya. Permintaan keterampilan menggunakan api-version=2026-08-01-preview.

"knowledgeStore": {
  "storageConnectionString": "<your-azure-storage-connection-string>",
  "projections": [
    {
      "files": [
        {
          "storageContainer": "extracted-images",
          "source": "/document/normalized_images/*"
        }
      ],
      "tables": [],
      "objects": []
    }
  ]
}

Setelah pengindeks berjalan, setiap blob dalam extracted-images kontainer sesuai dengan satu normalized_images elemen. URL blob memiliki formulir https://<storage-account>.blob.core.windows.net/<container>/<imagePath>, di mana <imagePath> cocok dengan nilai yang disimpan di image_path bidang .

Untuk skema lengkap, termasuk jenis proyeksi tambahan (tables dan objects) dan opsi autentikasi, lihat "proyeksi" penyimpanan Knowledge di Pencarian Azure AI.

Membersihkan sumber daya

Setelah selesai, hapus pengindeks, kumpulan keterampilan, dan indeks agar tidak lagi dikenakan biaya Content Understanding dan Azure OpenAI. File sumber di Azure Blob Storage dan sumber daya Foundry itu sendiri tetap ada sampai Anda menghapusnya.

Troubleshooting

Jika pengindeks gagal atau mengembalikan hasil yang tidak terduga, periksa penyebab umum berikut.

Validasi kumpulan keterampilan gagal dengan kode 400

Skill mengembalikan error 400 Skill validation failed ketika kombinasi parameter saling bertentangan. Penyebab umum:

• modelName diatur tanpa modelDeployment, atau sebaliknya. Keduanya harus diatur bersama-sama.
• method adalah semantic (pratinjau) dan overlapLength lebih besar dari 0. Atur overlapLength ke 0 atau hilangkan.
• method dan unit bukan pasangan yang didukung. Gunakan fixedSize dengan characters atau semantic dengan tokens.

Otorisasi pada sumber daya Foundry gagal

Jika keterampilan mengembalikan 401 atau 403 saat memanggil sumber daya Foundry, verifikasi bahwa:

• Blok cognitiveServices dalam skillset mengarah ke sumber daya Foundry yang benar.
• Identitas yang digunakan oleh layanan pencarian memiliki peran yang diperlukan pada sumber daya Foundry. Untuk konfigurasi identitas terkelola, lihat Melampirkan sumber daya yang dapat ditagih ke skillset di Pencarian Azure AI.

text_sections kosong

Jika dokumen yang diindeks tidak memiliki potongan, pastikan bahwa:

• Format file didukung. Untuk daftar, lihat Format file yang didukung.
• Sumber daya Foundry berada di wilayah yang didukung.
• PDF yang dilindungi kata sandi tidak terkunci sebelum pengindeksan.

Deskripsi gambar (pratinjau) tidak ada

Jika potongan tidak menyertakan deskripsi gambar inline, pastikan bahwa:

• modelName dan modelDeployment ditetapkan dalam kumpulan keterampilan.
• Model penyelesaian chat di modelName diterapkan dalam sumber daya Foundry yang sama yang dirujuk oleh skillset.
• Deployment memiliki kuota TPM atau RPM yang mencukupi untuk volume dokumen Anda.

Waktu pengindeks habis pada dokumen besar

Pemahaman Konten memberlakukan batas waktu pemrosesan per dokumen. Jika PDF besar gagal:

• Pisahkan dokumen sumber menjadi file yang lebih kecil sebelum mengindeks.
• Kurangi batchSize menjadi 1 agar setiap dokumen diproses secara independen.

Untuk batas data lengkap untuk keterampilan Azure Content Understanding, lihat Batas data.

Konten terkait

• Kemampuan Pemahaman Konten Azure
• Keterampilan Penyematan Azure OpenAI
• Pencarian multimodal di Pencarian Azure AI
• Menentukan proyeksi indeks untuk pengindeksan induk-turunan
• Membagi dokumen besar untuk RAG dan pencarian vektor