Tampilkan gambar yang disematkan dalam dokumen dalam pengambilan agentik (pratinjau)

Gunakan penyajian gambar (pratinjau) untuk menampilkan gambar yang disematkan dalam dokumen sumber Anda (seperti diagram, bagan, infografis, formulir yang dipindai, dan gambar produk) selama pengambilan agenik, sehingga model bahasa besar (LLM) Anda dapat beralasan melalui konteks visual bersama teks saat mensintesis jawaban.

Saat Anda mengaktifkan penyajian gambar, Pencarian Azure AI:

• Pada waktu pengindeksan, mengekstrak gambar dari dokumen yang didukung dan menyimpannya di penyimpanan aset Blob Azure yang disediakan pelanggan.

• Pada saat kueri dijalankan, mengambil gambar-gambar tersebut selama aksi pengambilan, mengodekannya dalam base64, dan menyisipkannya sebagai konten multimodal ke dalam prompt LLM yang menghasilkan jawaban sintesis.

Artikel ini menunjukkan kepada Anda cara mengaktifkan penyajian gambar di pangkalan pengetahuan, menggantinya per permintaan, memeriksa statistik penyajian gambar, dan merencanakan persyaratan siklus hidup akun penyimpanan.

Dukungan penggunaan

Prerequisites

• Layanan Pencarian Azure AI dengan pangkalan pengetahuan yang menentukan LLM. Pangkalan pengetahuan harus menggunakan sintesis jawaban.

• Sumber pengetahuan terindeks berbasis file yang dikonfigurasi dengan assetStore dalam ingestionParameters-nya. Jenis yang didukung:

  • sumber pengetahuan Blob (Azure Blob Storage atau Azure Data Lake Storage Gen2)
  • Sumber pengetahuan OneLake terindeks
  • Sumber pengetahuan SharePoint yang diindeks

  Untuk sumber pengetahuan blob yang menggunakan ekstraksi standar, selesaikan prasyarat sumber pengetahuan blob.

• Sumber pengetahuan tidak boleh mengonfigurasi ingestionPermissionOptions.

• Dokumen sumber yang berisi gambar yang dapat diekstrak, seperti file PNG, file JPEG, atau PDF dengan gambar yang disematkan.

• Sumber daya Microsoft Foundry di wilayah yang didukung oleh Azure Content Understanding di Foundry Tools, dengan penyematan Azure OpenAI dan penyebaran model obrolan multimodal. Gunakan titik akhir sumber daya dalam https://<resource-name>.services.ai.azure.com format .

• Izin untuk membuat atau memperbarui pangkalan pengetahuan dan sumber pengetahuan terkelola. Konfigurasikan autentikasi tanpa kunci dengan peran Kontributor Layanan Pencarian dan Kontributor Data Indeks Pencarian yang ditetapkan ke pengguna atau identitas otomatisasi yang melakukan operasi manajemen ini (disarankan). Atau, gunakan kunci API admin.

• Izin untuk memanggil aksi retrieve. Tetapkan peran Pembaca Data Indeks Pencarian ke identitas yang mengirim permintaan pengambilan (disarankan) atau gunakan kunci API kueri.

• Untuk panggilan keluar ke LLM selama sintesis jawaban, layanan pencarian harus memiliki identitas terkelola dengan izin Cognitive Services User pada sumber daya Microsoft Foundry yang meng-host LLM.

• Untuk akses penyimpanan aset, konfigurasikan identitas terkelola layanan pencarian seperti yang dijelaskan dalam Mengonfigurasi penyimpanan aset dan akses aplikasi.

• REST API 2026-08-01-preview atau paket pratinjau Azure SDK yang setara: .NET | Java | JavaScript | Python

Batasan dan pertimbangan

• Penyediaan gambar hanya tersedia melalui API retrieve dalam pengambilan berbasis agen. Kueri klasik /docs/search tidak menyediakan gambar yang disematkan dokumen ke sintesis jawaban hilir tanpa solusi atau konfigurasi kustom.

• Penayangan gambar hanya berfungsi dalam mode output sintesis jawaban. Mode extractiveData output melewati penyajian gambar.

• Penyajian gambar hanya berlaku untuk sumber pengetahuan terindeks berbasis file yang telah assetStore mengonfigurasi dan mengindeks potongan dengan nilai terisi image_path .

• Dalam basis pengetahuan campuran, hanya jenis sumber pengetahuan yang didukung (blob, OneLake terindeks, dan SharePoint terindeks) yang menyediakan gambar yang disematkan dalam dokumen untuk proses sintesis jawaban lanjutan. Jenis lain masih dapat berkontribusi terhadap landasan teks.

• Penyajian gambar tidak didukung untuk sumber pengetahuan yang menggunakan ingestionPermissionOptions untuk mengimpor izin tingkat dokumen, termasuk ACL, cakupan RBAC, atau label sensitivitas Microsoft Purview. Penyimpanan aset membuat penyimpanan pengetahuan yang mendasar, dan penyimpanan pengetahuan tidak mendukung pewarisan izin.

• Skema respons pengambilan tidak mendefinisikan bidang untuk jalur gambar individual di penyimpanan aset atau byte gambar yang dikirim ke model. Aktivitas imageServing melaporkan statistik agregat untuk gambar yang diambil dan dikirim ke model.

• Akses ke gambar dikontrol di tingkat akun penyimpanan, secara independen dari akses ke konten terindeks. Entitas apa pun yang memiliki akses baca ke akun penyimpanan aset dapat mengambil gambar-gambar tersebut.

• Jangan menyimpan rahasia (kunci akun, token, string koneksi) di dokumen sumber karena konten dapat dikembalikan sebagai data dasar.

• Penyajian gambar dapat meningkatkan latensi sintesis jawaban karena pengunduhan gambar dan pemrosesan token multimodal. Jalankan kueri perwakilan dengan sajian gambar diaktifkan dan dinonaktifkan dan bandingkan latensi respons dengan aktivitas yang dilaporkan imageServing .

• Pemahaman Konten dapat menghasilkan hasil gambar yang berbeda untuk file PDF dan DOCX. Jika ekstraksi dan verbalisasi gambar yang disematkan secara konsisten diperlukan, konversi dokumen sumber ke PDF atau uji setiap format sumber dengan konten representatif.

Cara kerja penyajian gambar

Penyajian gambar memiliki dua fase:

• Pengindeksan: Saat Anda mengonfigurasi ekstraksi konten standar dan penyimpanan aset pada sumber pengetahuan, keterampilan Pemahaman Konten yang dihasilkan secara semantik memotong dokumen, mempertahankan tabel sebagai Markdown, dan menggunakan LLM yang dikonfigurasi untuk menjelaskan gambar yang disematkan. Deskripsi gambar menjadi bagian dari Markdown yang diperkaya yang di-vektorisasi keterampilan penyematan. Skill ini juga mengekstrak gambar ke penyimpanan aset blob Anda dan menambahkan referensi image_path ke potongan yang tumpang tindih.

  Saat Anda mengonfigurasi penyimpanan aset, layanan pencarian juga menyediakan penyimpanan pengetahuan bersama sumber pengetahuan untuk mempertahankan artefak gambar yang diekstrak. Anda dapat memeriksa dan mengelola penyimpanan pengetahuan ini seperti yang lain.

• Pengambilan: Saat tindakan ambil berjalan dengan sajian gambar diaktifkan, layanan pencarian mengambil gambar yang cocok dari penyimpanan aset, mengodekannya dengan base64, dan menyertakannya sebagai konten multimodal dalam prompt sintesis jawaban.

Mengonfigurasi penyimpanan aset dan akses aplikasi

Penyajian gambar mencakup tiga batas kepercayaan. Pada waktu pengindeksan, layanan pencarian menulis artefak gambar ke penyimpanan aset Anda. Saat kueri dijalankan, layanan penelusuran membaca data dari penyimpanan aset untuk mengambil gambar. Aplikasi Anda juga membaca dari penyimpanan aset jika perlu menampilkan gambar di antarmuka pengguna. Konfigurasikan setiap jalur untuk mengikuti akses hak istimewa terkecil.

Cari akses layanan ke penyimpanan aset

• Gunakan Microsoft Entra ID dan identitas managed untuk layanan pencarian. Tetapkan identitas peran Kontributor Data Blob Penyimpanan di cakupan akun penyimpanan karena pengindeks menulis artefak gambar dan tindakan ambil membacanya. Saat kontainer sumber dan kontainer aset menggunakan akun yang sama, peran tersebut juga menyediakan akses baca ke blob sumber.

• Jangan aktifkan akses publik anonim pada kontainer penyimpanan aset.

Akses aplikasi ke referensi gambar

Indeks yang dihasilkan menyimpan image_path referensi ke gambar di penyimpanan aset. Skema respons pengambilan tidak menentukan bidang khusus untuk jalur gambar individual di penyimpanan aset atau byte gambar yang dikirim ke model. Opsional sourceData adalah data referensi terstruktur, dan image_path tidak diperlukan di dalamnya.

Untuk menampilkan gambar terindeks di aplikasi Anda:

1. Tetapkan peran Storage Blob Data Reader kepada identitas aplikasi Anda pada cakupan akun penyimpanan aset.

2. Tetapkan identitas aplikasi Anda peran Pembaca Data Indeks Pencarian sehingga dapat mengkueri indeks yang dihasilkan.

3. Dapatkan otorisasi image_path dari indeks yang dihasilkan melalui kueri atau titik akhir layanan yang dikontrol aplikasi.

4. Pastikan bahwa referensi mengarah ke akun penyimpanan dan kontainer aset yang diharapkan. Tolak jalur yang tidak tepercaya sebelum pencarian blob.

5. Ambil nama blob yang dihasilkan dari kontainer aset dengan menggunakan identitas aplikasi Anda.

Pemisahan ini memungkinkan Anda mengontrol siapa yang dapat melihat gambar sumber secara independen dari siapa yang dapat memanggil API ambil.

Mengonfigurasi penyimpanan aset pada sumber pengetahuan

Konfigurasikan assetStoreingestionParameters di sumber pengetahuan terindeks yang didukung. Penyimpanan aset adalah kontainer blob yang Anda miliki dan yang digunakan layanan pencarian untuk menulis artefak gambar ke dalamnya.

Untuk instruksi khusus sumber, lihat:

• Membuat sumber pengetahuan blob
• Buat sumber pengetahuan SharePoint terindeks
• Membuat sumber pengetahuan OneLake

Sumber pengetahuan blob minimal yang penayangan gambarnya diaktifkan terlihat seperti ini:

PUT https://{service-name}.search.windows.net/knowledgesources/my-blob-ks?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "azureBlobParameters": {
    "connectionString": "ResourceId=<storage-resource-id>",
    "containerName": "source-documents",
    "ingestionParameters": {
      "assetStore": {
        "connectionString": "ResourceId=<storage-resource-id>",
        "containerName": "image-assets"
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "https://{foundry-resource}.services.ai.azure.com",
          "deploymentId": "gpt-4o",
          "modelName": "gpt-4o"
        }
      },
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "https://{foundry-resource}.services.ai.azure.com",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large"
        }
      },
      "contentExtractionMode": "standard",
      "aiServices": {
        "uri": "https://{foundry-resource}.services.ai.azure.com"
      }
    }
  }
}

Hasil konfigurasi

Kombinasi assetStore, disableImageVerbalization, dan chatCompletionModel menentukan apa yang disimpan pengindeks dan apa yang dilihat model pada waktu kueri:

• Penyimpanan aset + verbalisasi (default):assetStore atur, disableImageVerbalization dibiarkan sebagai false, chatCompletionModel atur. Pengindeks mempertahankan gambar ke penyimpanan aset dan menyimpan deskripsi teks dalam indeks. Aktivitas pengambilan dapat melaporkan verbalizationUsed sebagai true.

• Penyimpanan aset saja:assetStore atur, disableImageVerbalization atur ke true, chatCompletionModel tidak diperlukan. Pengindeks mempertahankan gambar ke penyimpanan aset tetapi tidak menghasilkan deskripsi teks. Aktivitas pengambilan dapat melaporkan verbalizationUsed sebagai false.

• Tidak ada penyimpanan aset, kumpulan model:assetStore tidak disetel, chatCompletionModel disetel. Deskripsi teks saja, tidak ada artefak gambar. Penyajian gambar tidak berlaku.

• Tidak ada penyimpanan aset, tidak ada model: Tidak ada pemrosesan gambar.

Memverifikasi konfigurasi penyimpanan aset

Tunggu hingga penyerapan selesai sebelum melanjutkan:

• Periksa status pengindeks di portal Azure atau gunakan Dapatkan Status Pengindeks (REST API).

• Periksa apakah gugus terindeks memiliki bidang terisi image_path . Jika image_path kosong, periksa status pengindeks, konfigurasi penyimpanan aset sumber pengetahuan, konten dokumen sumber, dan konten kontainer aset.

• Periksa kontainer penyimpanan aset. Anda akan melihat blob gambar yang ditulis oleh pengindeks selama proses ingest.

Mengaktifkan penyajian gambar pada pangkalan pengetahuan

Atur enableImageServing ke true pada referensi sumber pengetahuan di dalam definisi pangkalan pengetahuan. Pengaturan ini menjadi default untuk setiap permintaan pengambilan yang menargetkan sumber pengetahuan.

Definisi basis pengetahuan juga menetapkan LLM yang digunakan untuk sintesis jawaban saat kueri. Pengaturan ini terpisah dari pengaturan chatCompletionModel apa pun yang Anda tetapkan pada ingestionParameters sumber pengetahuan, yang mengendalikan verbalisasi gambar selama pengindeksan.

Jika pangkalan pengetahuan Anda mereferensikan beberapa sumber pengetahuan, atur enableImageServing hanya pada jenis terindeks berbasis file yang didukung yang telah assetStore dikonfigurasi. Jenis sumber yang tidak didukung (seperti indeks pencarian, SharePoint jarak jauh, atau web) tetap memberikan kontribusi pada landasan tekstual, namun tidak menyediakan gambar yang disematkan dalam dokumen untuk proses sintesis jawaban lanjutan.

PUT https://{service-name}.search.windows.net/knowledgebases/my-kb?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "name": "my-kb",
  "knowledgeSources": [
    {
      "name": "my-blob-ks",
      "enableImageServing": true
    }
  ],
  "outputMode": "answerSynthesis",
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://{foundry-resource}.services.ai.azure.com",
        "deploymentId": "gpt-4o",
        "modelName": "gpt-4o"
      }
    }
  ]
}

Memverifikasi pengaktifan penyajian gambar

GET Kirim permintaan ke titik akhir pangkalan pengetahuan dan verifikasi bahwa referensi sumber pengetahuan mencakup "enableImageServing": true.

Mengambil dengan penyajian gambar

Panggil aksi pengambilan pada basis pengetahuan. Untuk mengesampingkan setelan bawaan basis pengetahuan untuk setiap permintaan, atur enableImageServing pada entri yang cocok di bawah knowledgeSourceParams.

POST https://{service-name}.search.windows.net/knowledgebases/my-kb/retrieve?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "retrievalReasoningEffort": { "kind": "medium" },
  "outputMode": "answerSynthesis",
  "includeActivity": true,
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "What's the wiring configuration shown in the installation guide?" }
      ]
    }
  ],
  "knowledgeSourceParams": [
    {
      "knowledgeSourceName": "my-blob-ks",
      "kind": "azureBlob",
      "enableImageServing": true
    }
  ]
}

Apa yang terjadi pada waktu pengambilan

Untuk referensi gambar yang terkait dengan konten yang cocok, layanan pencarian mengunduh gambar yang sesuai dari penyimpanan aset, mengodekannya dengan base64, dan meneruskannya sebagai konten multimodal ke model sintesis jawaban hilir. Periksa statistik agregat penayangan gambar di activity.imageServing. Untuk bentuk respons yang tepat, lihat dokumentasi referensi untuk Pengambilan Pengetahuan - Ambil (REST API).

Memverifikasi perilaku pengambilan

Respons pengambilan dapat memberikan sinyal penyajian gambar ini:

• Saat includeActivity bernilai true, larik activity melaporkan aktivitas imageServing untuk sumber pengetahuan saat layanan merekam operasi penyajian gambar.

• Nilai imagesSentToModel yang lebih besar dari 0 berarti layanan melaporkan bahwa layanan memasok gambar ke model sintesis jawaban hilir.

Aturan prioritas

Ketika definisi pangkalan pengetahuan dan permintaan pengambilan menentukan enableImageServing, nilai dalam permintaan pengambilan lebih diutamakan. Prioritas lengkapnya adalah:

1. Nilai dalam knowledgeSourceParams[].enableImageServing pada permintaan pengambilan (jika ditetapkan).
2. Nilai pada referensi sumber pengetahuan yang cocok dalam definisi pangkalan pengetahuan (jika ditetapkan).
3. false (nilai bawaan).

Tabel berikut ini meringkas sembilan kombinasi.

Memeriksa statistik penyajian gambar

Saat penyajian gambar berjalan, respons retrieve menyertakan bagian imageServing untuk setiap sumber pengetahuan di dalam array activity. Gunakan bagian ini untuk membandingkan gambar yang diambil dari penyimpanan aset dengan gambar yang dikirim ke model.

"activity": [
  {
    "type": "azureBlob",
    "knowledgeSourceName": "my-blob-ks",
    "imageServing": {
      "verbalizationUsed": true,
      "imagesRetrieved": 5,
      "imagesSentToModel": 4,
      "totalImageSizeBytes": 248361
    }
  }
]

Laporan bidang:

• verbalizationUsed: Statistik verbalisasi citra yang dilaporkan oleh layanan untuk aktivitas pengambilan.

• imagesRetrieved: Jumlah gambar yang diambil dari penyimpanan aset.

• imagesSentToModel: Jumlah gambar yang dikirim ke model hilir.

• totalImageSizeBytes: Ukuran total, dalam byte, dari gambar yang dikirim ke model.

Jika imagesRetrieved lebih besar dari imagesSentToModel, tidak setiap gambar yang diambil dikirim ke model.

Periksa verbalizationUsed dan imagesSentToModel secara terpisah. Respons dapat melaporkan baik verbalizationUsed sebagai true maupun satu atau beberapa gambar yang dikirim ke model.

Menguji penyajian gambar dari ujung ke ujung

Gunakan salah satu sampel berikut untuk menguji penyiapan lengkap:

• Sampel penyajian gambar C#
• Contoh Python untuk menyajikan gambar

Contoh-contoh ini membuat sumber pengetahuan blob dan basis pengetahuan, membandingkan permintaan pengambilan saat penayangan gambar dinonaktifkan dan diaktifkan, serta memeriksa statistik penayangan gambar. Mereka juga menggunakan kueri indeks wildcard yang independen untuk memilih image_path dan mengunduh aset itu. Contoh ini memilih satu referensi yang dipisahkan dengan titik koma, menghapus awalan proyeksi seperti 11.7: dari jalur relatif, atau mendekode URL pada jalur absolut dan menghapus segmen awal kontainer aset. Transformasi ini merupakan contoh perilaku, bukan jaminan dari API pengambilan. Aset yang dipilih bukan bukti bahwa gambar yang sama digunakan dalam respons pengambilan data tertentu.

Daftar periksa perbandingan A/B yang khas:

• Pilih pertanyaan yang hanya dapat dijawab dari diagram, bagan, atau gambar yang dipindai.

• Jalankan permintaan ambil dengan enableImageServing: false dan ambil jawabannya.

• Jalankan permintaan pengambilan yang sama dengan enableImageServing: true dan bandingkan jawaban, latensi, dan aktivitas yang dilaporkan.

• Perlakukan perbedaan jawaban sebagai sinyal A/B pengamatan, bukan bukti bahwa gambar menyebabkan perbedaan. Nilai imagesSentToModel yang lebih besar dari 0 berarti layanan melaporkan bahwa layanan tersebut memasok gambar ke model.

Membersihkan sumber daya

Hapus pangkalan pengetahuan sebelum Anda menghapus sumber pengetahuannya. Menghapus sumber daya Pencarian Azure AI ini tidak menghapus dokumen sumber atau blob gambar yang diproyeksikan di Azure Storage. Hapus blob tersebut secara terpisah hanya ketika tidak ada alur penyerapan atau pengambilan yang dipertahankan yang masih membutuhkannya.

Troubleshooting

Gunakan blok aktivitas imageServing dari Periksa statistik penyajian gambar sebagai langkah diagnostik pertama Anda. Tabel berikut ini mencantumkan pemeriksaan gejala umum tanpa mengasumsikkan satu penyebab.

Konten terkait

• Mengkueri pangkalan pengetahuan
• Gunakan sintesis jawaban untuk respons yang didukung kutipan
• Apa itu sumber pengetahuan?
• Konsep penyimpanan pengetahuan