Belge Yönetim Bilgileri toplu iş analizi

Toplu analiz API'si, bir zaman uyumsuz istek kullanarak birden çok belgeyi toplu olarak işlemenizi sağlar. Belgeleri tek tek göndermek ve birden çok istek kimliği izlemek zorunda kalmak yerine, faturalar, bir dizi ödünç verme belgesi veya bir grup özel belge gibi bir belge koleksiyonunu aynı anda analiz edebilirsiniz. Toplu iş API'si, Azure blob depolamadan belgeleri okumayı ve sonuçları blob depolamaya yazmayı destekler.

• Toplu analizden yararlanmak için hem kaynak belgeleriniz hem de işlenen çıkışlarınız için belirli kapsayıcılara sahip bir Azure Blob depolama hesabına ihtiyacınız vardır.
• İşlem tamamlandıktan sonra toplu işlem sonucu, durumuyla işlenen , skippedveya failedgibi succeededtek tek tüm belgeleri listeler.
• Batch API önizleme sürümü kullandıkça öde fiyatlandırması aracılığıyla kullanılabilir.

Toplu iş analizi kılavuzu

• Tek bir toplu çözüm isteği (atlanan belgeler dahil) başına işlenen belge sayısı üst sınırı 10.000'dir.

• İşlem sonuçları tamamlandıktan sonra 24 saat boyunca saklanır. Belgeler ve sonuçlar sağlanan depolama hesabında yer alır, ancak işlem durumu artık tamamlandıktan 24 saat sonra kullanılamaz.

Başlamaya hazır mısınız?

Önkoşullar

• Etkin bir Azure aboneliğine ihtiyacınız vardır. Azure aboneliğiniz yoksa ücretsiz olarak bir abonelik oluşturabilirsiniz.

• Azure aboneliğinize sahip olduktan sonra Azure portalında Bir Belge Zekası örneği. Hizmeti denemek için ücretsiz fiyatlandırma katmanını (F0) kullanabilirsiniz.

• Kaynağınız dağıtıldıktan sonra Kaynağa git'i seçin ve anahtarınızı ve uç noktanızı alın.

  • Uygulamanızı Belge Yönetim Bilgileri hizmetine bağlamak için kaynaktan anahtara ve uç noktaya ihtiyacınız vardır. Anahtarınızı ve uç noktanızı hızlı başlangıcın ilerleyen bölümlerinde koda yapıştırırsınız. Bu değerleri Azure portal Anahtarları ve Uç Nokta sayfasında bulabilirsiniz.

• bir Azure Blob Depolama hesabı. kaynak ve sonuç dosyalarınız için Azure Blob Depolama hesabınızda kapsayıcılar oluşturacaksınız:

  • Kaynak kapsayıcı. Bu kapsayıcı, dosyalarınızı analiz için karşıya yüklediğiniz yerdir (gerekli).
  • Sonuç kapsayıcısı. Bu kapsayıcı, işlenen dosyalarınızın depolandığı yerdir (isteğe bağlı).

Kaynak ve işlenmiş belgeler için aynı Azure Blob Depolama kapsayıcısını belirleyebilirsiniz. Ancak yanlışlıkla verilerin üzerine yazma olasılığını en aza indirmek için ayrı kapsayıcılar seçmenizi öneririz.

Depolama kapsayıcısı yetkilendirmesi

Belge kaynağınıza erişimi yetkilendirmek için aşağıdaki seçeneklerden birini belirleyebilirsiniz.

✔️ Yönetilen Kimlik. Yönetilen kimlik, Azure tarafından yönetilen bir kaynak için Microsoft Entra kimliği ve belirli izinler oluşturan bir hizmet sorumlusudur. Yönetilen kimlikler, kimlik bilgilerini kodunuz içine eklemek zorunda kalmadan Belge Yönetim Bilgileri uygulamanızı çalıştırmanıza olanak tanır. Yönetilen kimlikler, depolama verilerine erişim vermenin ve paylaşılan erişim imzası belirteçlerini (SAS) kaynak ve sonuç URL'lerinizle ekleme gereksinimini değiştirmenin daha güvenli bir yoludur.

Daha fazla bilgi edinmek için bkz. Belge Zekası için yönetilen kimlikler.

✔️ Paylaşılan Erişim İmzası (SAS). Paylaşılan erişim imzası, Belge Yönetim Bilgileri hizmetinize belirli bir süre için kısıtlanmış erişim sağlayan bir URL'dir. Bu yöntemi kullanmak için kaynak ve sonuç kapsayıcılarınız için Paylaşılan Erişim İmzası (SAS) belirteçleri oluşturmanız gerekir. Kaynak ve sonuç kapsayıcıları, sorgu dizesi olarak eklenmiş bir Paylaşılan Erişim İmzası (SAS) belirteci içermelidir. Belirteç kapsayıcınıza veya belirli bloblara atanabilir.

• Kaynak kapsayıcınızın veya blobunuzun okuma, yazma, listeleme ve silme erişimi belirlemesi gerekir.
• Sonuç kapsayıcınız veya blobunuz yazma, listeleme, silme erişimini belirlemelidir.

Daha fazla bilgi edinmek için bkz. SAS belirteçleri oluşturma.

Toplu iş analizi API'sini çağırma

• veya azureBlobFileListSource nesneleri içinde ayarlanan kaynak belgeniz için Azure Blob Depolama kapsayıcı URL'sini azureBlobSource belirtin.

Giriş dosyalarını belirtme

Toplu iş API'si, işlenecek dosyaları belirtmek için iki seçeneği destekler. Bir kapsayıcı veya klasördeki tüm dosyaların işlenmesi gerekiyorsa ve dosya sayısı tek bir toplu iş isteği için 10000 sınırından azsa kapsayıcıyı azureBlobSource kullanın.

Kapsayıcıda veya klasörde işlenecek belirli dosyalarınız varsa veya işlenecek dosya sayısı tek bir toplu işlem için maksimum sınırı aşmışsa kullanın azureBlobFileListSource. Veri kümesini birden çok toplu işleme bölün ve kapsayıcının kök klasöründe JSONL biçiminde işlenecek dosyaların listesini içeren bir dosya ekleyin. Dosya listesi biçimine örnek olarak.

{"file": "Adatum Corporation.pdf"}
{"file": "Best For You Organics Company.pdf"}

Sonuçların konumunu belirtin

kullanarak resultContainerUrltoplu analiz sonuçlarınız için Azure Blob Depolama kapsayıcı URL'sini belirtin. Yanlışlıkla üzerine yazılmasını önlemek için, kaynak ve işlenmiş belgeler için ayrı kapsayıcılar kullanmanızı öneririz.

Aynı dosya adlarının overwriteExisting üzerine yazılmasını istemiyorsanız boole özelliğini false olarak ayarlayın. Bu ayar faturalamayı etkilemez ve yalnızca giriş dosyası işlendikten sonra sonuçların üzerine yazılmasını engeller.

toplu iş API'sinin resultPrefix bu çalıştırmasının sonuçlarını ad alanına ayarlayın.

• Hem giriş hem de çıkış için aynı kapsayıcıyı kullanmayı planlıyorsanız, ve resultPrefix değerini girişinizle azureBlobSourceeşleşecek şekilde ayarlayınresultContainerUrl.
• Aynı kapsayıcıyı kullanırken, çözümleme sonuç dosyalarıyla overwriteExisting dosyaların üzerine yazıp yazmayacağınıza karar vermek için alanını ekleyebilirsiniz.

POST isteğini derleme ve çalıştırma

POST isteğini çalıştırmadan önce {your-source-container-SAS-URL} ve {your-result-container-SAS-URL} değerlerini Azure Blob depolama kapsayıcı örneklerinizdeki değerlerle değiştirin.

Aşağıdaki örnekte, özelliğin azureBlobSource isteğe nasıl ekleneceği gösterilmektedir:

Yalnızca birine azureBlobSource veya azureBlobFileListSourceizin verin.

POST /documentModels/{modelId}:analyzeBatch

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "prefix": "trainingDocs/"
  },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "layoutresult/",
  "overwriteExisting": true
}

Aşağıdaki örnekte, özelliğin azureBlobFileListSource isteğe nasıl ekleneceği gösterilmektedir:

POST /documentModels/{modelId}:analyzeBatch

{
   "azureBlobFileListSource": {
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
      "fileList": "myFileList.jsonl"
    },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "customresult/",
  "overwriteExisting": true
}

Başarılı yanıt

202 Accepted
Operation-Location: /documentModels/{modelId}/analyzeBatchResults/{resultId}

Toplu analiz API'si sonuçlarını alma

Batch API işlemi yürütüldükten sonra, işlemi kullanarakGET toplu analiz sonuçlarını alabilirsiniz. Bu işlem işlem durumu bilgilerini, işlem tamamlanma yüzdesini ve işlem oluşturma ve güncelleştirme tarihini/saatini getirir.

GET /documentModels/{modelId}/analyzeBatchResults/{resultId}
200 OK

{
  "status": "running",      // notStarted, running, completed, failed
  "percentCompleted": 67,   // Estimated based on the number of processed documents
  "createdDateTime": "2021-09-24T13:00:46Z",
  "lastUpdatedDateTime": "2021-09-24T13:00:49Z"
...
}

Durum iletilerini yorumlama

Bir kümenin her belgesi için , failedveya skippedgibi succeededbir durum atanır. Her belge için, sonuçları doğrulamak için sağlanan iki URL vardır: sourceUrlbaşarılı giriş belgenizin kaynak blob depolama kapsayıcısı olan ve resultUrlile kaynak dosya .ocr.jsonveresultPrefix için göreli yolu oluşturmak üzere ve birleştirilerek resultContainerUrl oluşturulur.

• Durum notStarted veya running. Toplu analiz işlemi başlatılmaz veya tamamlanmamıştır. Tüm belgeler için işlem tamamlanana kadar bekleyin.

• Durum completed. Toplu analiz işlemi tamamlandı.

• Durum failed. Toplu işlem başarısız oldu. Bu yanıt genellikle istekle ilgili genel sorunlar varsa oluşur. Tek tek dosyalardaki hatalar, tüm dosyalar başarısız olsa bile toplu rapor yanıtında döndürülür. Örneğin, toplu iş raporu yanıtı aracılığıyla kısmi sonuçlara erişebilmeniz için depolama hataları toplu işlemi bir bütün olarak durdurmaz.

Yalnızca durumu olan succeeded dosyaların yanıtta özelliği resultUrl oluşturulur. Bu, model eğitiminin ile biten .ocr.json dosya adlarını algılamasını ve bunları eğitim için kullanılabilecek tek dosyalar olarak tanımlamasını sağlar.

Durum yanıtı örneği succeeded :

[
  "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
      {
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
          "code": "InvalidArgument",
          "message": "Invalid argument.",
          "innererror": {
            "code": "InvalidSasToken",
            "message": "The shared access signature (SAS) is invalid: {details}"
                   }
               }
          }
      ]
   }
]
...

Durum yanıtı örneği failed :

• Bu hata yalnızca genel toplu iş isteğinde hatalar varsa döndürülür.
• Toplu analiz işlemi başlatıldıktan sonra, tek tek belge işlemi durumu, tüm dosyaların durumu olsa bile genel toplu işin durumunu failedetkilemez.

[
    "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
            "code": "InvalidArgument",
            "message": "Invalid argument.",
            "innererror": {
              "code": "InvalidSasToken",
              "message": "The shared access signature (SAS) is invalid: {details}"
                }
            }
        ]
    }
]
...

Durum yanıtı örneği skipped :

[
    "result": {
    "succeededCount": 3,
    "failedCount": 0,
    "skippedCount": 2,
    "details": [
        ...
        "sourceUrl": "https://myStorageAccount.blob.core.windows.net/myContainer/trainingDocs/file4.jpg",
        "status": "skipped",
        "error": {
            "code": "OutputExists",
            "message": "Analysis skipped because result file {path} already exists."
             }
        ]
    }
]
...

Toplu çözümleme sonuçları, içindeki dosyasını içindeki çıkış dosyasıyla resultUrl resultContainerUrlkarşılaştırarak hangi dosyaların başarılı bir şekilde analiz edilecegini belirlemenize ve çözümleme sonuçlarını doğrulamanıza yardımcı olur.

Sonraki adımlar

GitHub'da kod örneklerini görüntüleyin.