Azure Content Understanding becerisiyle içeriği öbekleme ve vektörleştirme

Bu makalede, Azure Content Understanding becerisini kullanarak şunları yapmayı öğreneceksiniz:

Azure Content Understanding becerisi, belge başına bir veya daha fazla öbek döndürür. Her öbek Markdown biçimli içerik, konum meta verileri (sayfa numaraları ve sınırlayıcı çokgenler) ve ayıklanan görüntülere isteğe bağlı başvurular içerir. olarak chunkingProperties.methodayarladığınızda semantic öbekler, sabit karakter aralıkları yerine paragraf ve başlık sınırlarını izler. modelName ve modelDeployment ayarladığınızda, beceri ekli görüntülerin açıklamalarını oluşturmak için Azure OpenAI sohbet tamamlama dağıtımını çağırır. Beceri daha sonra bu açıklamaları öbek içeriğiyle birleştirir.

Bu makalede, açıklama amacıyla örnek sağlık planı PDF'leri kullanılmaktadır. Dosyaları Content Understanding'in desteklediği biçimde kullanıma sunan desteklenen herhangi bir veri kaynağında aynı işlem hattını çalıştırabilirsiniz.

Prerequisites

• Herhangi bir desteklenen bölgede bir Azure Yapay Zeka Arama hizmeti. Arama hizmetinin kendisi bu senaryo için bölge kısıtlaması taşımaz.

• Azure Content Understanding becerisi tarafından desteklenen bir bölgedeki Microsoft Foundry kaynağı. Görüntü açıklaması ve parçalama, Foundry kaynağının bulunduğu bölgede işlenir.

• Faturalama için beceri kümesine bağlı bir Microsoft Foundry kaynağı. Azure Content Understanding becerisi, Azure Content Understanding fiyatlandırması üzerinden ücretlendirilir.

• (İsteğe bağlı) Görüntü açıklamaları oluşturmak için kullanılan, aynı Foundry kaynağındaki bir sohbet tamamlama modelinin (gpt-4.1 gibi) Azure OpenAI dağıtımı. Yalnızca yapay zeka tabanlı görüntü açıklamaları istiyorsanız gereklidir.

• Öbekleri vektörleştirmek için text-embedding-3-small tarafından kullanılan bir ekleme modelinin ( gibi) Azure OpenAI dağıtımı.

• Dizine eklemek istediğiniz dosyaları içeren bir Azure Blob Depolama kapsayıcısı. Bu makalede, dizin oluşturucu ayarıyla allowSkillsetToReadFileData bir blob veri kaynağı kullanılır (dosya içeriğini Content Understanding becerisine geçirmek için kullanılır).

Genel bakış

Makale, bire çok dizin oluşturma işlem hattı oluşturur. Her kaynak belge birden çok arama belgesi (öbek başına bir tane) oluşturur:

1. Dizin oluşturucu Azure Blob Depolama’daki her dosyayı okur ve ikili içeriği /document/file_data aracılığıyla beceri kümesine iletir.

2. Azure Content Understanding becerisi, text_sections oluşturmak için anlamsal öbekleme (önizleme) kullanır. modelName ve modelDeployment ayarlandığında, ayrıca gömülü görüntüler için yapay zeka tarafından oluşturulan açıklamalar (önizleme) üretir ve bunları her parçanın Markdown içeriğine satır içi olarak ekler.

3. Azure OpenAI Ekleme becerisi öbek başına bir kez çalışır ve öbek içeriği için bir vektör oluşturur.

4. Dizin projeksiyonu hedef dizine öbek başına bir arama belgesi yazar, içeriği, sayfa meta verilerini, görüntü başvurularını ve vektöri alanlara eşler.

5. (İsteğe bağlı) Bir bilgi deposu, istemci uygulamalarının ayıklanan görüntüleri URL aracılığıyla alabilmesi için bunları Azure Blob Depolama’a normalized_images yansıtır.

Veri dosyalarını hazırlama

Azure Content Understanding becerisi her belgenin ikili içeriğini işler, bu nedenle kaynak dosyalar becerinin desteklediği bir biçimde olmalıdır. Geçerli liste için bkz. Content Understanding hizmet sınırları. Yaygın olarak desteklenen biçimler PDF, DOCX, XLSX, PPTX ve birçok görüntü biçimidir.

Dosyalarınızı desteklenen veri kaynağına yükleyin. Azure portalını, REST API'lerini veya Azure SDK kullanarak veri kaynağını oluşturabilirsiniz.

Aşağıdaki en düşük istek, bu kılavuz boyunca kullanılan veri kaynağını oluşturur.

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

Birden çoğa indeksleme için indeks oluşturma

Her arama belgesi, Content Understanding becerisi tarafından üretilen bir parçaya karşılık gelir. Dizin gereksinimleri:

• Bir anahtar alanı (chunk_id).
• Öbeklerin hangi kaynak belgedenparent_id () geldiğini tanımlayan üst alan.
• Öbek içeriğini, sayfa meta verilerini ve görüntü başvurularını depolayan alanlar.
• Öbek ekleme için bir vektör alanı.

Aşağıdaki dizin tanımı, sonraki bölümde oluşturduğunuz beceri kümesiyle eşleşir.

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

Anlamsal öbekleme (önizleme) ve vektörleştirme için beceri kümesini tanımlayın

Hedef dizin hazır olduğunda, onu besleyen öbekleri, vektörleri ve projeksiyon eşlemelerini üreten beceri kümesini tanımlayın.

Beceri kümesinin iki becerisi vardır:

• Azure Content Understanding becerisi her belgeyi parçalara ayırır. chunkingProperties.method ayarını semantic olarak ayarlamak, yeteneğin paragraf ve başlık sınırlarına uymasını sağlar. modelName ve modelDeployment ayarlarının yapılması, becerinin vektörleştirmeden önce öbek içeriğine doğrudan eklediği yapay zeka tarafından oluşturulan görüntü açıklamalarını (önizleme) etkinleştirir. Desteklenen sohbet tamamlama modellerinin listesi ve diğer parametre ayrıntıları için bkz . Beceri parametreleri.

• Azure OpenAI Ekleme becerisi her öbeğin içeriği için bir vektör oluşturur.

Beceri kümesi, her öbeği ayrı bir arama belgesine eşlemek için indexProjections kullanır. Daha fazla bilgi için Dizin projeksiyonu tanımlama bölümüne bakın.

İsteği göndermeden önce <subdomain> yerine Azure OpenAI alt etki alanınızı, <Azure OpenAI api key> yerine gömme kaynağı anahtarını ve <Foundry resource key> yerine beceri kümesine bağlı Foundry kaynağının anahtarını yazın.

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

Content Understanding becerisi için tam parametre başvurusu, desteklenen değerler ve doğrulama kuralları için bkz. Azure Content Understanding becerisi.

Dizin oluşturucuyu yapılandırma ve çalıştırma

Veri kaynağınızdan okuyan, beceri kümesini çağıran ve öbekleri dizine dönüştüren bir dizin oluşturucu oluşturun ve çalıştırın. allowSkillsetToReadFileData değerini true olarak ayarlayın; böylece Content Understanding becerisi dosya içeriğini alır ve parsingMode değerini default olarak ayarlayın.

Bu senaryoda ihtiyacınız outputFieldMappings yoktur. indexProjections Beceri kümesindeki blok zaten her öbeği hedef dizin alanlarına eşler.

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

Dizin oluşturucu çalıştırıldığında Content Understanding becerisi semantik öbekleme (önizleme) kullanır, isteğe bağlı olarak yapay zeka tabanlı görüntü açıklamaları (önizleme) oluşturur ve öbek başına dizine bir arama belgesi yazar.

Dizin oluşturucu durumunu kontrol et

Sorgulamadan önce dizin oluşturucu çalıştırmasının tamamladığını onaylayın:

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

lastResult.status öğesinin success olduğunu doğrulayın. transientFailure itemsProcessed değerinden 0yüksekse, çalıştırma kısmi bir başarıdır ve yine de doldurulan öbekleri sorgulayabilirsiniz. Daha fazla bilgi için bkz. Dizin oluşturucu durumunu izleme.

Sonuçları doğrulama

Öbeklerin beklenen içeriği içerdiğini ve vektör aramasının beklendiği gibi çalıştığını doğrulamak için dizini sorgular. Arama Gezgini'ni veya HTTP istekleri gönderen herhangi bir aracı kullanın.

Aşağıdaki istek, hem öbeklenmiş metnin hem de gömmelerin doldurulduğunu doğrulamak için bir karma sorgu ( chunk üzerinde anahtar sözcük araması ve text_vector karşı vektör sorgusu) çalıştırır.

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

Başarılı bir yanıt aşağıdakine benzer (kısalık için kırpılır):

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

Yanıt şunları içerir:

• chunk: Her öbek için Markdown içeriği. modelDeployment ve modelName öğelerini yapılandırdığınızda, yapay zeka tarafından oluşturulan görüntü açıklamaları (önizleme) Markdown içinde satır içi olarak görünür.
• page_number_from ve page_number_to: Öbeği oluşturan sayfa aralığı.
• image_path: Öbekle ayıklanan görüntünün yolu veya bir öbek birden çok görüntüye yayıldığında yolların noktalı virgülle ayrılmış bir listesidir. Tam şekil, bilgi deposu dosya projeksiyonunun yapılandırılıp yapılandırılmadığına bağlıdır. Dosya projeksiyonu olmadan yol, örnekte (figures/3 ) gösterilen kısa formdur. Dosya projeksiyonu ile yol, bilgi deposundaki görüntünün göreli yoludur. Bu görüntüleri istemci uygulamalarının kullanımına sunmak için bkz: (İsteğe bağlı) Geri alma için proje görüntüleri.

(İsteğe bağlı) Geri alma için proje görselleri

image_path Dizinde depolanan değerler, doğrudan alınabilir URL'ler değil, becerinin zenginleştirme ağacının işaretçileridir. Görüntüleri almak için, normalized_images öğesini bir bilgi deposu kullanarak Azure Blob Depolama’a aktarın ve ardından her öbek için bir blob URL’si elde edin.

Bu adım isteğe bağlıdır. Yalnızca istemci uygulamanızın ayıklanan görüntüleri görüntülemesi veya indirmesi gerekiyorsa ekleyin.

Önceki bölümdeki beceri kümesi yüküne aşağıdaki özelliği ekleyin. Beceri kümesi isteği, api-version=2026-08-01-preview kullanır.

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

Dizin oluşturucu çalıştırıldıktan sonra kapsayıcıdaki extracted-images her blob bir normalized_images öğeye karşılık gelir. Blob URL'si, https://<storage-account>.blob.core.windows.net/<container>/<imagePath> biçimindedir; burada <imagePath>, image_path alanında depolanan değerle eşleşir.

Ek projeksiyon türleri (tables ve objects) ile kimlik doğrulama seçenekleri dahil olmak üzere şemanın tamamı için bkz. Azure Yapay Zeka Arama'te Knowledge Store "projeksiyonlar".

Kaynakları temizle

İşiniz bittiğinde, Content Understanding ve Azure OpenAI ücretlerinin işlemeye devam etmesini önlemek için dizin oluşturucuyu, beceri kümesini ve dizini silin. Azure Blob Depolama ve Foundry kaynağındaki kaynak dosyaları siz silene kadar kalır.

Troubleshooting

Dizin oluşturucu başarısız olursa veya beklenmeyen sonuçlar döndürüyorsa aşağıdaki yaygın nedenleri denetleyin.

Beceri kümesi doğrulaması 400 ile başarısız oluyor

Parametre birleşimleri çakıştığında beceri bir 400 Skill validation failed hata döndürür. Yaygın nedenler:

• modelName, modelDeployment olmadan ayarlanır veya tam tersi. İkisi de birlikte ayarlanmalıdır.
• method, semantic (önizleme) sürümüdür ve overlapLength, 0 değerinden büyüktür. overlapLength öğesini 0 olarak ayarlayın veya bunu atlayın.
• method ve unit desteklenen bir çift değildir. fixedSize ile characters veya semantic ile tokens kullanın.

Foundry kaynağında yetkilendirme başarısız oluyor

Beceri, Dökümhane kaynağını çağırırken 401 veya 403 döndürürse şunları doğrulayın:

• Beceri kümesindeki cognitiveServices blok, doğru Foundry kaynağını gösterir.
• Arama hizmeti tarafından kullanılan kimlik, Foundry kaynağında gerekli role sahiptir. Yönetilen kimlik kurulumları için bkz. Azure Yapay Zeka Arama'da bir beceri kümesine faturalanabilir kaynak ekleme.

text_sections boş

Dizine alınan belgelerin öbekleri yoksa şunları doğrulayın:

• Dosya biçimi desteklenir. Liste için bkz . Desteklenen dosya biçimleri.
• Foundry kaynağı desteklenen bölgelerden birindedir.
• Dizin oluşturmadan önce parola korumalı PDF'lerin kilidi açılır.

Resim açıklamaları (önizleme) eksik

Öbekler satır içi görüntü açıklamaları içermiyorsa şunları doğrulayın:

• Hem modelName hem de modelDeployment, beceri kümesinde ayarlanmıştır.
• modelName içindeki sohbet tamamlama modeli, beceri kümesinin başvurduğu aynı Foundry kaynağına dağıtılmıştır.
• Dağıtımınız, belge hacminiz için yeterli TPM veya RPM kotasına sahiptir.

Dizin oluşturucu büyük belgelerde zaman aşımına uğruyor

Content Understanding, belge başına bir işleme zaman aşımı uygular. Büyük PDF'ler başarısız olursa:

• Dizin oluşturmadan önce kaynak belgeyi daha küçük dosyalara bölün.
• Her belgenin bağımsız olarak işlenmesi için batchSize değerini 1 düşürün.

Azure Content Understanding becerisinin tam veri sınırları için bkz. Data sınırları.

İlgili içerik

• Azure İçerik Anlama Yeteneği
• Azure OpenAI Ekleme becerisi
• Azure Yapay Zeka Arama'te çok modlu arama
• Üst-alt dizin oluşturma için dizin projeksiyonu tanımlama
• RAG ve vektör araması için büyük belgeleri parçalara ayır