Azure AI Dili için yerel belge desteği (önizleme)
Ö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 deAbstractiveSummarization
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'ler | 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
macOScurl -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:
Abonelik. Kullanılabilir Azure aboneliklerinizden birini seçin.
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.
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.
Adı. Kaynağınız için seçtiğiniz adı girin. Seçtiğiniz ad Azure içinde benzersiz olmalıdır.
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.Gözden geçir + Oluştur’u seçin.
Hizmet koşullarını gözden geçirin ve kaynağınızı dağıtmak için Oluştur'u seçin.
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.
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.
Sol rayda, Kaynak Yönetimi'nin altında Anahtarlar ve Uç Nokta'yı seçin.
Dil hizmetinde isteğinizin kimliğini doğrulamak için ve
key
kodunuzulanguage 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ılar oluş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:
Paylaşılan erişim imzası (SAS) belirteçleri. Kullanıcı temsilcisi SAS belirteçlerinin güvenliği Microsoft Entra kimlik bilgileriyle sağlanır. SAS belirteçleri, Azure depolama hesabınızdaki kaynaklara güvenli ve temsilci erişimi sağlar.
Yönetilen kimlik rol tabanlı erişim denetimi (RBAC). Azure kaynakları için yönetilen kimlikler, Microsoft Entra kimliği ve Azure yönetilen kaynakları için belirli izinler oluşturan hizmet sorumlularıdı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.
- 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
Tercih ettiğiniz düzenleyiciyi veya IDE'yi kullanarak uygulamanız için adlı
native-document
yeni bir dizin oluşturun.Yerel belge dizininizde pii-detection.json adlı yeni bir json dosyası oluşturun.
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ğerlerini Azure portal Depolama hesabı 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) veyaUseEntityTypeName
şeklindedirUseRedactionCharacterWithRefId
. Daha fazla bilgi için bkz. PiiTask Parametreleri.
POST isteğini çalıştırma
POST isteğinin ön yapısı aşağıdadır:
POST {your-language-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview
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"
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:
Sonuçları analiz etme (GET isteği)
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.
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
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
Geri Bildirim
https://aka.ms/ContentUserFeedback.
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz.Gönderin ve geri bildirimi görüntüleyin