Ajan tabanlı alma içinde belgeye gömülü görüntüleri ortaya çıkarma (önizleme)

Aracı destekli alma sırasında kaynak belgelerinize gömülü görüntüleri (diyagramlar, grafikler, infografikler, taranmış formlar ve ürün görüntüleri gibi) görüntülemek için görüntü sunma (önizleme) özelliğini kullanın; böylece büyük dil modeliniz (LLM), bir yanıt oluştururken metnin yanı sıra görsel bağlam üzerinde de akıl yürütebilir.

Görüntü sunmayı etkinleştirdiğinizde Azure Yapay Zeka Arama:

• Dizin oluşturma sırasında, desteklenen belgelerden görüntüleri ayıklar ve bunları müşteri tarafından sağlanan Azure Blob varlık deposunda depolar.

• Sorgu zamanında, alma eylemi sırasında bu görüntüleri getirir, base64 ile kodlar ve bunları sentezlenmiş yanıtı üreten LLM istemine çok modüllü içerik olarak ekler.

Bu makalede, bilgi bankasında görüntü sunumunu etkinleştirme, istek başına geçersiz kılma, görüntü sunma istatistiklerini inceleme ve depolama hesabı yaşam döngüsü gereksinimlerini planlama işlemleri gösterilmektedir.

Kullanım desteği

Prerequisites

• LLM içeren bir bilgi bankasına sahip bir Azure Yapay Zeka Arama hizmeti. Bilgi bankası yanıt sentezini kullanmalıdır.

• assetStore içinde bir ingestionParameters ile yapılandırılmış dosya tabanlı dizinlenmiş bilgi kaynağı. Desteklenen tür:

  • Blob bilgi kaynağı (Azure Blob Depolama veya Azure Data Lake Storage 2. Nesil)
  • Dizinlenmiş OneLake bilgi kaynağı
  • Dizinlenmiş SharePoint bilgi kaynağı

  Standart ayıklama kullanan blob bilgi kaynakları için blob bilgi kaynağı önkoşullarını tamamlayın.

• Bilgi kaynağı ingestionPermissionOptions yapılandırmamalıdır.

• PNG dosyaları, JPEG dosyaları veya eklenmiş resimler içeren PDF'ler gibi ayıklanabilir görüntüler içeren kaynak belgeler.

• Azure OpenAI gömme ve çok kipli sohbet modeli dağıtımları bulunan, Foundry Araçları'nda Azure Content Understanding tarafından desteklenen bir bölgedeki Microsoft Foundry kaynağı. Kaynak uç noktasını https://<resource-name>.services.ai.azure.com biçiminde kullanın.

• Bilgi bankası ve yönetilen bilgi kaynağını oluşturma veya güncelleştirme izni. Bu yönetim işlemlerini gerçekleştiren kullanıcı veya otomasyon kimliğine atanmış Arama Hizmeti Katkıda Bulunanı ve Arama Dizini Veri Katkıda Bulunanı rolleri ile anahtarsız kimlik doğrulamasını yapılandırın (önerilir). Alternatif olarak, bir yönetici API anahtarı kullanın.

• Alma eylemini çağırma izni. Alma istekleri gönderen kimliğe Arama Dizini Veri Okuyucusu rolünü atayın (önerilir) veya bir sorgu API'si anahtarı kullanın.

• Yanıt oluşturma sırasında LLM’ye yapılan dış çağrılar için, arama hizmetinin LLM’yi barındıran Microsoft Foundry kaynağında yönetilen kimliğe ve Cognitive Services User izinlerine sahip olması gerekir.

• Varlık deposu erişimi için, varlık deposu ve uygulama erişimini yapılandırma bölümünde açıklandığı gibi arama hizmeti yönetilen kimliğini yapılandırın.

• 2026-08-01-preview REST API veya eşdeğer bir Azure SDK önizleme paketi: .NET | Java | JavaScript | Python

Sınırlamalar ve Dikkat Edilecek Hususlar

• Görüntü sunumu, aracılı alımda yalnızca retrieve API aracılığıyla kullanılabilir. Klasik /docs/search sorgular, özel bir çözüm ya da yapılandırma olmadan belgeye gömülü görüntüleri sonraki yanıt oluşturma aşamasına iletmez.

• Görüntü sunma yalnızca yanıt sentezi çıkış modunda çalışır. extractiveData çıkış modu, görüntülerin sunulmasını atlar.

• Görüntü sunma yalnızca doldurulmuş assetStore değerlerle yapılandırılmış ve dizine alınmış öbeklere sahip image_path dosya tabanlı dizine alınmış bilgi kaynakları için geçerlidir.

• Karma bilgi tabanlarında yalnızca desteklenen bilgi kaynağı türleri (blob, dizinlenmiş OneLake ve dizinlenmiş SharePoint), belgelere gömülü görüntüleri sonraki yanıt oluşturma aşamalarına sağlar. Diğer türler de metin temellendirmesine katkıda bulunabilir.

• Belge düzeyindeki izinleri içeri aktarmak için ingestionPermissionOptions kullanan ve buna ACL'ler, RBAC kapsamları veya Microsoft Purview duyarlılık etiketleri de dahil olan bilgi kaynaklarında görüntü sunma desteklenmez. Varlık deposu temel alınan bir bilgi deposu oluşturur ve bilgi depoları izin devralmayı desteklemez.

• Alma yanıtı şeması, tek tek varlık deposu görüntü yolları veya modele gönderilen görüntü baytları için alanlar tanımlamaz. Etkinlik imageServing raporları, alınan ve modele gönderilen görüntülere ilişkin toplu istatistikleri sunar.

• Görüntülere erişim, dizine alınan içeriğe erişimden bağımsız olarak depolama hesabı düzeyinde denetlenmektedir. Varlık depolama hesabına okuma erişimi olan herhangi bir kimlik, ilgili görüntüleri alabilir.

• İçerik topraklama verileri olarak döndürülebildiğinden gizli dizileri (hesap anahtarları, belirteçler, bağlantı dizeleri) kaynak belgelerde depolamayın.

• Görüntü indirme ve çok modüllü belirteç işleme nedeniyle görüntü sunma yanıt sentezi gecikme süresini artırabilir. Görüntü sunma özelliği etkin ve devre dışı olan temsili sorgular çalıştırın ve yanıt gecikme süresini bildirilen imageServing etkinlikle karşılaştırın.

• Content Understanding, PDF ve DOCX dosyaları için farklı görüntü sonuçları üretebilir. Tutarlı ekli görüntü ayıklama ve sözlüleştirme gerekiyorsa, kaynak belgeleri PDF'ye dönüştürün veya temsili içerikle her kaynak biçimini test edin.

Görüntü sunma nasıl çalışır?

Görüntü sunmanın iki aşaması vardır:

• Dizin oluşturma: Standart içerik ayıklamayı ve bilgi kaynağında bir varlık depoyu yapılandırdığınızda, oluşturulan Content Understanding becerisi belgeyi anlamsal olarak öbekler, tabloları Markdown olarak korur ve yapılandırılmış LLM'yi ekli rakamları açıklamak için kullanır. Şekil açıklamaları, gömme becerisinin vektörleştirdiği zenginleştirilmiş Markdown'ın bir parçası hâline gelir. Beceri ayrıca blob varlık deponuza görüntüleri ayıklar ve çakışan öbeklere başvurular ekler image_path .

  Bir varlık deposunu yapılandırdığınızda, arama hizmeti ayıklanan görüntü yapıtlarını kalıcı hale getirmek için bilgi kaynağıyla birlikte bir bilgi deposu da sağlar. Bu bilgi depolarını diğer tüm bilgi depoları gibi inceleyebilir ve yönetebilirsiniz.

• Alma: Alma eylemi görüntü sunma özelliği etkin olarak çalıştırıldığında, arama hizmeti eşleşen görüntüleri varlık deposundan getirir, base64 ile kodlar ve bunları yanıt sentezi istemine çok modüllü içerik olarak ekler.

Varlık deposu ve uygulama erişimini yapılandırma

Görüntü sunumu üç güven sınırını kapsar. Dizinleme sırasında arama hizmeti, görüntü artifaktlarını varlık deponuza yazar. Sorgu sırasında arama hizmeti, görüntüleri almak üzere varlık deposunu okur. Uygulamanız, görüntüleri bir kullanıcı arayüzünde görüntülemesi gerekiyorsa varlık deposundan da okur. Her yolu en az ayrıcalıklı erişimi izleyecek şekilde yapılandırın.

Arama hizmetinin varlık deposuna erişimi

• Arama hizmeti için Microsoft Entra ID ve managed identity kullanın. Dizin oluşturucu görüntü yapıtları yazdığından ve alma eylemi bunları okuduğundan, kimliğe depolama hesabı kapsamında Depolama Blobu Veri Katkıda Bulunanı rolünü atayın. Kaynak ve varlık kapsayıcıları aynı hesabı paylaştığında, rol kaynak bloblarına okuma erişimi de sağlar.

• Varlık deposu kapsayıcısı üzerinde anonim genel erişimi etkinleştirmeyin.

Uygulamanın görüntü referanslarına erişimi

Oluşturulan dizin, varlık deposundaki görüntülere yönelik image_path başvuruları içerir. Alma yanıtı şeması, tek tek varlık deposu görüntü yolları veya modele gönderilen görüntü baytları için ayrılmış alanlar tanımlamaz. İsteğe bağlı sourceData , yapılandırılmış başvuru verileridir ve image_path içinde gerekli değildir.

Uygulamanızda dizine alınan bir görüntüyü görüntülemek için:

1. Uygulamanızın kimliğine, varlık depolama hesabı düzeyinde Depolama Blob Veri Okuyucusu rolünü atayın.

2. Oluşturulan dizini sorgulayabilmesi için uygulamanızın kimliğine Arama Dizini Veri Okuyucusu rolünü atayın.

3. Uygulama tarafından denetlenen bir sorgu veya hizmet uç noktası aracılığıyla oluşturulan dizinden yetkilendirilmiş image_path bir dizin elde edin.

4. Başvurunun beklenen depolama hesabına ve varlık kapsayıcısına çözümlendiğini doğrulayın. Blob aramasından önce güvenilir olmayan yolları reddedin.

5. Uygulamanızın kimliğini kullanarak varlık kapsayıcısından ortaya çıkan blob adını alın.

Bu ayrım, kaynak görüntüleri kimlerin alma API'sini çağıranın bağımsız olarak görüntüleyebileceğini denetlemenizi sağlar.

Bir bilgi kaynağında varlık deposunu yapılandırma

Desteklenen bir dizinlenmiş bilgi kaynağının assetStore içinde ingestionParameters yapılandırın. Varlık deposu, size ait olan ve arama hizmetinin görüntü artefaktlarını içine yazdığı bir blob kapsayıcısıdır.

Kaynağa özgü yönergeler için bkz:

• Blob bilgi kaynağı oluşturun
• Dizinlenmiş SharePoint bilgi kaynağı oluşturma
• OneLake bilgi kaynağı oluşturma

Görüntü sunma özelliği etkinleştirilmiş en düşük blob bilgi kaynağı şu şekilde görünür:

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

Yapılandırma sonuçları

, ve assetStoredisableImageVerbalization birleşimichatCompletionModel, dizin oluşturucunun neleri depolayıp modelin sorgu zamanında ne göreceğini belirler:

• Varlık deposu + seslendirme (varsayılan):assetStore ayarlandı, disableImageVerbalizationfalse olarak bırakıldı, chatCompletionModel ayarlandı. Dizin oluşturucu, görüntüleri varlık deposunda kalıcı hale getirmekte ve metin açıklamalarını dizinde depolar. Alma etkinliği, true öğesini verbalizationUsed olarak raporlayabilir.

• Yalnızca varlık deposu:assetStore ayarlayın, disableImageVerbalization olarak trueayarlayın, chatCompletionModel gerekli değildir. Dizin oluşturucu, görüntüleri varlık deposunda kalıcı hale getirmekle birlikte metin açıklamaları oluşturmaz. Alma etkinliği, false öğesini verbalizationUsed olarak raporlayabilir.

• Varlık deposu yok, model kümesi:assetStore ayarlanmadı, chatCompletionModel ayarlandı. Yalnızca metin açıklamaları, görüntü yapıtları yok. Görüntü sunumu uygulanmaz.

• Varlık deposu yok, model yok: Görüntü işleme yok.

Varlık deposu yapılandırmasını doğrulama

Devam etmeden önce alımın tamamlanmasını bekleyin:

• Azure portalında dizin oluşturucu durumunu denetleyin veya Get Indexer Status (REST API) kullanın.

• Dizine alınmış öbeklerin doldurulmuş image_path bir alana sahip olup olmadığını denetleyin. image_path boşsa, dizin oluşturucu durumunu, bilgi kaynağı asset store yapılandırmasını, kaynak belge içeriğini ve varlık kapsayıcısı içeriğini denetleyin.

• Varlık deposu kapsayıcısını inceleyin. Dizin oluşturucunun içeri aktarma sırasında yazdığı görüntü bloblarını görmelisiniz.

Bilgi bankasında görüntü sunumlarını etkinleştirme

Bilgi tabanı tanımı içindeki bilgi kaynağı referansında enableImageServing değerini true olarak ayarlayın. Bu ayar, bilgi kaynağını hedefleyen her alma isteği için varsayılan ayar olur.

Bilgi bankası tanımı, sorgu zamanında yanıt sentezi için kullanılan LLM'yi de belirtir. Bu ayar, dizin oluşturma sırasında görüntü sözelleştirmeyi yönlendiren bilgi kaynağının chatCompletionModelüzerinde ayarladığınız herhangi bir ingestionParameters ayardan bağımsızdır.

Bilgi tabanınız birden fazla bilgi kaynağına başvuruyorsa, enableImageServing yapılandırılmış desteklenen dosya tabanlı dizinlenmiş türlerde yalnızca assetStore ayarlayın. Desteklenmeyen türler (arama dizini, uzak SharePoint veya web gibi) yine de metin temellendirmesine katkıda bulunur, ancak sonraki yanıt sentezi aşamalarına belgelere gömülü görüntüler sağlamaz.

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

Görüntü sunum etkinleştirmesini doğrulama

Bilgi tabanı uç noktasına bir GET isteği gönderin ve bilgi kaynağı referansının "enableImageServing": true içerdiğini doğrulayın.

Görüntü sunma ile alma

Bilgi tabanında getirme eylemini çağırın. Bilgi tabanı varsayılanını her istek için geçersiz kılmak üzere, enableImageServing altındaki eşleşen girdide knowledgeSourceParams değerini ayarlayın.

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

Alma zamanında ne olur?

Eşleşen içerikle ilişkili görüntü başvuruları için, arama hizmeti ilgili görüntüleri varlık deposundan indirir, base64 ile kodlar ve bunları aşağı akış yanıt sentezi modeline çok modüllü içerik olarak geçirir. içindeki activity.imageServingtoplam görüntü sunma istatistiklerini inceleyin. Tam yanıt şekli için Bilgi Alma - Alma (REST API) başvuru belgelerine bakın.

Geri getirme davranışını doğrulama

Bir alma yanıtı, resim sunumuna ilişkin şu sinyalleri sağlayabilir:

• includeActivity, true olduğunda, hizmet görüntü sunma işlemlerini kaydettiğinde activity dizisi bir bilgi kaynağı için imageServing etkinliğini bildirir.

• imagesSentToModel değerinden 0 büyük bir değer, hizmetin aşağı akış yanıt sentezi modeline görüntü sağladığını bildirdiğini gösterir.

Öncelik kuralları

Hem bilgi bankası tanımı hem de alma isteği belirtildiğinde enableImageServing, alma isteğindeki değer önceliklidir. Tam öncelik:

1. Alma isteğindeki knowledgeSourceParams[].enableImageServing değeri (ayarlandıysa).
2. Bilgi bankası tanımındaki eşleşen bilgi kaynağı başvurusundaki değer (ayarlandıysa).
3. false (varsayılan).

Aşağıdaki tablo, dokuz kombinasyonu özetlemektedir.

Görüntü sunma istatistiklerini inceleme

Görüntü sunma çalıştırıldığında, retrieve yanıtı, imageServing dizisi içindeki her bilgi kaynağı için bir activity bölümü içerir. Varlık deposundan alınan görüntüleri modele gönderilen görüntülerle karşılaştırmak için bu bölümü kullanın.

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

Alan raporu:

• verbalizationUsed: Alma etkinliği için hizmet tarafından bildirilen görüntü sözelleştirme istatistiği.

• imagesRetrieved: Varlık deposundan alınan görüntü sayısı.

• imagesSentToModel: Aşağı akış modeline gönderilen görüntü sayısı.

• totalImageSizeBytes: Modele gönderilen görüntülerin bayt cinsinden toplam boyutu.

değerinden imagesSentToModelbüyükseimagesRetrieved, alınan her görüntü modele gönderilmez.

verbalizationUsed ve imagesSentToModel öğelerini bağımsız olarak inceleyin. Bir yanıt, hem true öğesini verbalizationUsed olarak hem de modele gönderilen bir veya daha fazla görüntüyü bildirebilir.

Test görüntüsü sunumunu uçtan uca test edin

Tam kurulumu test etmek için aşağıdaki örneklerden birini kullanın:

• C# görüntü sunma örneği
• Python görüntü sunma örneği

Örnekler bir blob bilgi kaynağı ve bilgi tabanı oluşturur, görüntü sunma devre dışıyken ve etkinken getirme isteklerini karşılaştırır ve görüntü sunma istatistiklerini inceler. Ayrıca, bir image_path varlığını seçmek ve bu varlığı indirmek için bağımsız bir joker karakterli dizin sorgusu da kullanırlar. Örnekler, noktalı virgülle ayrılmış bir referans seçer, göreli bir yoldan 11.7: gibi bir projeksiyon ön ekini kaldırır ya da mutlak bir yolun URL kodlamasını çözüp başındaki asset-container segmentini kaldırır. Bu dönüştürmeler örnek davranıştır, alma API'sinin garantisi değildir. Seçilen varlık, aynı görüntünün belirli bir geri getirme yanıtına katkıda bulunduğunun kanıtı değildir.

Tipik bir A/B karşılaştırma denetim listesi:

• Yalnızca diyagramdan, grafikten veya taranmış görüntüden yanıtlanacak bir soru seçin.

• ile enableImageServing: false alma isteğini çalıştırın ve yanıtı yakalayın.

• Ile aynı alma isteğini enableImageServing: true çalıştırın ve yanıtları, gecikme süresini ve bildirilen etkinliği karşılaştırın.

• Yanıt farklılıklarını, görüntülerin bu farklılıklara neden olduğunun kanıtı olarak değil, gözlemsel A/B sinyalleri olarak değerlendirin. 0 değerinden büyük bir imagesSentToModel değeri, hizmetin modele görüntü sağladığını bildirdiği anlamına gelir.

Kaynakları temizle

Bilgi kaynağını silmeden önce bilgi bankasını silin. Bu Azure Yapay Zeka Arama kaynakların silinmesi, Azure Depolama kaynak belgeleri veya yansıtılan görüntü bloblarını silmez. Bu blobları yalnızca, artık hiçbir korunan alım veya alma işlem hattı bunlara ihtiyaç duymadığında ayrı ayrı silin.

Troubleshooting

imageServing İlk tanılamanız olarak görüntü sunum istatistiklerini incele'nin etkinlik bloğunu kullanın. Aşağıdaki tablo, tek bir neden varsaymadan yaygın belirtilere yönelik kontrolleri listeler.

İlgili içerik

• Bilgi bankasını sorgulama
• Alıntı destekli yanıtlar için yanıt sentezi kullanma
• Bilgi kaynağı nedir?
• Bilgi deposu kavramları