Share via

Azure AI Dili için yerel belge desteği (önizleme)

  • Makale

Önemli

  • Yerel belge desteği, geçitli bir önizlemedir. Yerel belge destek özelliğine erişim istemek için Dil Hizmeti önizlemelerine erişim için uygula formunu doldurun ve gönderin.

  • Azure AI Language genel önizleme sürümleri, etkin geliştirme aşamasında olan özelliklere erken erişim sağlar.

  • Genel Kullanılabilirlik (GA) öncesinde kullanıcı geri bildirimlerine göre özellikler, yaklaşımlar ve süreçler değişebilir.

Azure AI Language, metin tabanlı verilere Doğal Dil İşleme (NLP) özellikleri uygulayan bulut tabanlı bir hizmettir. Yerel belge destek özelliği, verilerinizi göndermek için bir HTTP POST istek gövdesi ve durum sonuçlarını almak için HTTP GET isteği sorgu dizesi kullanarak API isteklerini zaman uyumsuz olarak göndermenizi sağlar. İşlenen belgeleriniz Azure Blob Depolama hedef kapsayıcınızda bulunur.

Yerel belge, Microsoft Word (docx) veya taşınabilir belge dosyası (pdf) gibi özgün belgeyi oluşturmak için kullanılan dosya biçimini ifade eder. Yerel belge desteği, Azure AI Dili kaynak özelliklerini kullanmadan önce metin ön işleme gereksinimini ortadan kaldırır. Şu anda aşağıdaki özellikler için yerel belge desteği sağlanıyor:

  • Kişisel Bilgiler (PII). PII algılama özelliği yapılandırılmamış metindeki hassas bilgileri tanımlayabilir, kategorilere ayırabilir ve yeniden düzenleyebilir. API yerel PiiEntityRecognition belge işlemeyi destekler.

  • Belge özetleme. Belge özetleme, belgeler için ayıklayıcı (salient cümle ayıklama) veya soyut (bağlamsal sözcük ayıklama) özetler oluşturmak için doğal dil işlemeyi kullanır. ExtractiveSummarization Hem hem de AbstractiveSummarization API'ler yerel belge işlemeyi destekler.

Desteklenen belge biçimleri

Uygulamalar yerel belge oluşturmak, kaydetmek veya açmak için yerel dosya biçimlerini kullanır. Şu anda PII ve Belge özetleme özellikleri aşağıdaki yerel belge biçimlerini destekler:

Dosya türü Dosya uzantısı Açıklama
Metin .txt Biçimlendirilmemiş bir metin belgesi.
Adobe PDF .pdf Taşınabilir bir belge dosyası biçimlendirilmiş belge.
Microsoft Word .docx Microsoft Word belge dosyası.

Giriş yönergeleri

Desteklenen dosya biçimleri

Tür destek ve sınırlamalar
Pdf Tam olarak taranan PDF'ler desteklenmez.
Resimler içindeki metin Eklenmiş metin içeren dijital görüntüler desteklenmez.
Dijital tablolar Taranan belgelerdeki tablolar desteklenmez.

Belge Boyutu

Öznitelik Giriş sınırı
İstek başına toplam belge sayısı ≤ 20
İstek başına toplam içerik boyutu ≤ 1 MB

HTTP isteğine yerel belgeler ekleme

Haydi başlayalım:

  • Bu projede REST API çağrıları yapmak için cURL komut satırı aracını kullanacağız.

    Not

    cURL paketi çoğu Windows 10 ve Windows 11'e ve çoğu macOS ve Linux dağıtımına önceden yüklenmiştir. Paket sürümünü şu komutlarla de kontrol edebilirsiniz: Windows: curl.exe -V macOS curl -V Linux: curl --version

  • cURL yüklü değilse, platformunuzun yükleme bağlantıları şunlardır:

  • Etkin bir Azure hesabı. Hesabınız yoksa ücretsiz bir hesap oluşturabilirsiniz.

  • bir Azure Blob Depolama hesabı. Ayrıca kaynak ve hedef dosyalarınız için Azure Blob Depolama hesabınızda kapsayıcılar oluşturmanız gerekir:

    • Kaynak kapsayıcı. Bu kapsayıcı, analiz için yerel dosyalarınızı karşıya yüklediğiniz yerdir (gerekli).
    • Hedef kapsayıcı. Bu kapsayıcı, analiz edilen dosyalarınızın depolandığı yerdir (gereklidir).

  • Tek hizmetli dil kaynağı (çok hizmetli bir Azure AI hizmetleri kaynağı değil):

    Dil kaynağı projesi ve örnek ayrıntıları alanlarını aşağıdaki gibi tamamlayın:

    1. Abonelik. Kullanılabilir Azure aboneliklerinizden birini seçin.

    2. Kaynak Grubu. Yeni bir kaynak grubu oluşturabilir veya kaynağınızı aynı yaşam döngüsünü, izinleri ve ilkeleri paylaşan önceden var olan bir kaynak grubuna ekleyebilirsiniz.

    3. Kaynak Bölgesi. İşletmeniz veya uygulamanız belirli bir bölge gerektirmediği sürece Genel'i seçin. Kimlik doğrulaması için sistem tarafından atanan yönetilen kimlik (RBAC) kullanmayı planlıyorsanız Batı ABD gibi bir coğrafi bölge seçin.

    4. Adı. Kaynağınız için seçtiğiniz adı girin. Seçtiğiniz ad Azure içinde benzersiz olmalıdır.

    5. Fiyatlandırma katmanı. Hizmeti denemek ve daha sonra üretim için ücretli bir katmana yükseltmek için ücretsiz fiyatlandırma katmanını (Free F0) kullanabilirsiniz.

    6. Gözden geçir + Oluştur’u seçin.

    7. Hizmet koşullarını gözden geçirin ve kaynağınızı dağıtmak için Oluştur'u seçin.

    8. Kaynağınız başarıyla dağıtıldıktan sonra Kaynağa git'i seçin.

Anahtarınızı ve dil hizmet uç noktanızı alma

Dil hizmetine yönelik istekler, erişimin kimliğini doğrulamak için salt okunur bir anahtar ve özel uç nokta gerektirir.

  1. Yeni bir kaynak oluşturduysanız, dağıtıldıktan sonra Kaynağa git'i seçin. Mevcut bir dil hizmeti kaynağınız varsa doğrudan kaynak sayfanıza gidin.

  2. Sol rayda, Kaynak Yönetimi'nin altında Anahtarlar ve Uç Nokta'yı seçin.

  3. Dil hizmetinde isteğinizin kimliğini doğrulamak için ve key kodunuzu language service instance endpoint kopyalayıp kod örneklerine yapıştırabilirsiniz. API çağrısı yapmak için yalnızca bir anahtar gerekir.

Azure Blob Depolama kapsayıcıları oluşturma

kaynak ve hedef dosyalar için Azure Blob Depolama hesabınızda kapsayıcılaroluşturun.

  • Kaynak kapsayıcı. Bu kapsayıcı, analiz için yerel dosyalarınızı karşıya yüklediğiniz yerdir (gerekli).
  • Hedef kapsayıcı. Bu kapsayıcı, analiz edilen dosyalarınızın depolandığı yerdir (gereklidir).

Kimlik Doğrulaması

Dil kaynağınızın blob oluşturabilmesi, okuyabilmesi veya silebilmesi için depolama hesabınıza erişim izni verilmesi gerekir. Depolama verilerinize erişim vermek için kullanabileceğiniz iki birincil yöntem vardır:

Bu proje için source location , sorgu dizesi olarak eklenen Paylaşılan Erişim İmzası (SAS) belirteçleriyle ve target location URL'lerine erişimin kimliğini doğrularız. Her belirteç belirli bir bloba (dosya) atanır.

Screenshot of a storage url with SAS token appended.

  • Kaynak kapsayıcınızın veya blobunuzun okuma ve liste erişimi belirlemesi gerekir.
  • Hedef kapsayıcınızın veya blobunuzun yazma ve liste erişimi belirlemesi gerekir.

İpucu

Tek bir dosyayı (blob) işlediğimizden, SAS erişimini blob düzeyinde temsilci olarak atamanızı öneririz.

İstek üst bilgileri ve parametreleri

parametre Açıklama
-X POST <endpoint> API'ye erişmek için Dil kaynak uç noktanızı belirtir.
--header Content-Type: application/json JSON verilerini göndermek için içerik türü.
--header "Ocp-Apim-Subscription-Key:<key> API'ye erişmek için Dil kaynak anahtarını belirtir.
-data İsteğinizle birlikte geçirmek istediğiniz verileri içeren JSON dosyası.

Aşağıdaki cURL komutları bir BASH kabuğundan yürütülür. Bu komutları kendi kaynak adınız, kaynak anahtarınız ve JSON değerlerinizle düzenleyin. veya Document Summarization kod örneği projesini Personally Identifiable Information (PII) seçerek yerel belgeleri analiz etmeyi deneyin:

PII Örnek belgesi

Bu hızlı başlangıçta, kaynak kapsayıcınıza yüklenmiş bir kaynak belge gerekir. Bu proje için Microsoft Word örnek belgemizi veya Adobe PDF'mizi indirebilirsiniz. Kaynak dil İngilizcedir.

POST isteğini oluşturma

  1. Tercih ettiğiniz düzenleyiciyi veya IDE'yi kullanarak uygulamanız için adlı native-documentyeni bir dizin oluşturun.

  2. Yerel belge dizininizde pii-detection.json adlı yeni bir json dosyası oluşturun.

  3. Aşağıdaki Kişisel Bilgiler (PII) isteği örneğini kopyalayıp dosyanıza pii-detection.json yapıştırın. ve {your-target-container-SAS-URL} değerini Azure portal Depolama hesap kapsayıcıları örneğinizdeki değerlerle değiştirin{your-source-container-SAS-URL}:

İstek örneği

{
    "displayName": "Extracting Location & US Region",
    "analysisInput": {
        "documents": [
            {
                "language": "en-US",
                "id": "Output-excel-file",
                "source": {
                    "location": "{your-source-blob-with-SAS-URL}"
                },
                "target": {
                    "location": "{your-target-container-with-SAS-URL}"
                }
            } 
        ]
    },
    "tasks": [
        {
            "kind": "PiiEntityRecognition",
            "parameters":{
                "excludePiiCategories" : ["PersonType", "Category2", "Category3"],
                "redactionPolicy": "UseRedactionCharacterWithRefId" 
            }
        }
    ]
}

  • Kaynak location değer, kaynak kapsayıcı SAS URL'si değil, kaynak belgenin (blob) SAS URL'sidir.

  • Olası redactionPolicy değerler (varsayılan) veya UseEntityTypeNameşeklindedir UseRedactionCharacterWithRefId . Daha fazla bilgi için bkz. PiiTask Parametreleri.

POST isteğini çalıştırma

  1. POST isteğinin ön yapısı aşağıdadır:

       POST {your-language-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview

  2. POST isteğini çalıştırmadan önce ve {your-key} değerini Azure portal Dil hizmeti örneğinizdeki değerlerle değiştirin{your-language-resource-endpoint}.

    Önemli

    İşiniz bittiğinde anahtarı kodunuzdan kaldırmayı unutmayın ve asla herkese açık olarak göndermeyin. Üretim için Azure Key Vault gibi kimlik bilgilerinizi depolamanın ve bunlara erişmenin güvenli bir yolunu kullanın. Daha fazla bilgi için bkz . Azure AI hizmetleri güvenliği.

    PowerShell

       cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

    komut istemi / terminal

       curl -v -X POST "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

  3. Aşağıda örnek bir yanıt verilmişti:

    HTTP/1.1 202 Accepted
Content-Length: 0
operation-location: https://{your-language-resource-endpoint}/language/analyze-documents/jobs/f1cc29ff-9738-42ea-afa5-98d2d3cabf94?api-version=2023-11-15-preview
apim-request-id: e7d6fa0c-0efd-416a-8b1e-1cd9287f5f81
x-ms-region: West US 2
Date: Thu, 25 Jan 2024 15:12:32 GMT

POST yanıtı (jobId)

Salt okunur operation-location üst bilgisi içeren bir 202 (Başarılı) yanıtı alırsınız. Bu üst bilginin değeri, zaman uyumsuz işlemin durumunu almak ve GET isteği kullanarak sonuçları almak için sorgulanabilen bir jobId içerir:

Screenshot showing the operation-location value in the POST response.

Sonuçları analiz etme (GET isteği)

  1. Başarılı POST isteğinizden sonra, işlenen verileri görüntülemek için POST isteğinde döndürülen işlem konumu üst bilgisini yokleyin.

  2. GET isteğinin ön yapısı aşağıdadır:

      GET {your-language-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview

  3. Komutu çalıştırmadan önce şu değişiklikleri yapın:

    • {jobId} öğesini POST yanıtından Operation-Location üst bilgisi ile değiştirin.

    • {your-language-resource-endpoint} ve {your-key} değerlerini Azure portalındaki Dil hizmeti örneğinizdeki değerlerle değiştirin.

İstek alma

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" -i -X GET --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

    curl -v -X GET "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

Yanıtı inceleme

JSON çıkışıyla 200 (Başarılı) yanıt alırsınız. Durum alanı, işlemin sonucunu gösterir. İşlem tamamlanmazsa, durum değeri "çalışıyor" veya "notStarted" olur ve API'yi el ile veya betik aracılığıyla yeniden çağırmanız gerekir. Aramalar arasında bir saniyelik veya daha fazla bir aralık öneririz.

Örnek yanıt

{
  "jobId": "f1cc29ff-9738-42ea-afa5-98d2d3cabf94",
  "lastUpdatedDateTime": "2024-01-24T13:17:58Z",
  "createdDateTime": "2024-01-24T13:17:47Z",
  "expirationDateTime": "2024-01-25T13:17:47Z",
  "status": "succeeded",
  "errors": [],
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "PiiEntityRecognitionLROResults",
        "lastUpdateDateTime": "2024-01-24T13:17:58.33934Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "doc_0",
              "source": {
                "kind": "AzureBlob",
                "location": "https://myaccount.blob.core.windows.net/sample-input/input.pdf"
              },
              "targets": [
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.result.json"
                },
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.docx"
                }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2023-09-01"
        }
      }
    ]
  }
}

Başarıyla tamamlandıktan sonra:

  • Çözümlenen belgeler hedef kapsayıcınızda bulunabilir.
  • Başarılı POST yöntemi, hizmetin toplu iş isteğini oluşturduğunu belirten bir 202 Accepted yanıt kodu döndürür.
  • POST isteği, sonraki GET isteklerinde kullanılan bir değer sağlayan yanıt üst bilgilerini Operation-Location de döndürdü.

Kaynakları temizleme

Azure AI hizmetleri aboneliğini temizlemek ve kaldırmak istiyorsanız, kaynağı veya kaynak grubunu silebilirsiniz. Kaynak grubunun silinmesi, kaynak grubuyla ilişkili diğer tüm kaynakları da siler.

Sonraki adımlar

PII algılamaya genel bakışBelge Özetleme'ye genel bakış