تحليل المحتوى
نصيحة
راجع علامة التبويب النص والصور لمزيد من التفاصيل!
لتحليل محتويات الملف، يمكنك استخدام واجهة برمجة تطبيقات Azure Content Understanding لإرساله إلى نقطة النهاية. يمكنك تحديد المحتوى كرابط (لملف مستضاف في موقع يمكن الوصول إليه عبر الإنترنت) أو رفع بيانات الملفات الثنائية مباشرة (على سبيل المثال، مستند .pdf، صورة .png، ملف صوتي .mp3، أو ملف فيديو .mp4). يتضمن طلب التحليل المحلل الذي سيتم استخدامه.
التحليل هو عملية غير متزامنة. بعد تقديم الطلب، تحصل على معرف عملية يمكنك استخدامه للتحقق من الحالة واسترجاع النتائج عند اكتمال العملية.
على سبيل المثال، افترض أنك تريد استخدام محلل بطاقة العمل الذي تمت مناقشته مسبقا لاستخراج الاسم وعنوان البريد الإلكتروني من صورة بطاقة العمل الممسوحة ضوئيا التالية:
استخدام Python SDK
يوفر دليل تطوير البرمجيات لفهم المحتوى (azure-ai-contentunderstanding) في بايثون فئة ContentUnderstandingClient تبسط التفاعل مع الخدمة. تتولى مجموعة تطوير البرمجيات (SDK) عمليات المصادقة، وتسق الطلبات، والاستطلاع التلقائي للعمليات غير المتزامنة.
يستخدم كود بايثون التالي مجموعة تطوير البرمجيات لتقديم بطاقة عمل للتحليل واسترجاع النتائج:
from azure.ai.contentunderstanding import ContentUnderstandingClient
from azure.ai.contentunderstanding.models import AnalysisInput
from azure.core.credentials import AzureKeyCredential
# Authenticate the client
endpoint = "<YOUR_ENDPOINT>"
credential = AzureKeyCredential("<YOUR_API_KEY>")
client = ContentUnderstandingClient(endpoint=endpoint, credential=credential)
# Analyze the business card using the custom analyzer
analyzer_name = "business_card_analyser"
poller = client.begin_analyze(
analyzer_id=analyzer_name,
inputs=[AnalysisInput(url="https://host.com/business-card.png")]
)
# Wait for the operation to complete and get the results
result = poller.result()
# Extract field values from the results
content = result.contents[0]
if content.fields:
for field_name, field_data in content.fields.items():
if field_data.type == "string":
print(f"{field_name}: {field_data.value}")
نصيحة
تعيد طريقة SDK begin_analyze كائن استطلاع. استدعاء .result() جهاز الاستشعار يتعامل تلقائيا مع الاستطلاع حتى تكتمل العملية، لذلك لا تحتاج إلى كتابة حلقة الاستطلاع الخاصة بك.
استخدام واجهة برمجة تطبيقات REST
يمكنك أيضا تقديم طلبات التحليل مباشرة باستخدام واجهة برمجة تطبيقات REST. يقوم تطبيق العميل الخاص بك بإرسال استدعاءات HTTP إلى نقطة نهاية فهم المحتوى لمورد Microsoft Foundry الخاص بك، مع تمرير مفتاح API في الرأس.
الكود التالي في بايثون يقدم طلب تحليل باستخدام عنوان URL، ثم يقوم باستطلاع الخدمة حتى تكتمل العملية ويتم إرجاع النتائج.
import json
import requests
## Use a POST request to submit the file URL to the analyzer
analyzer_name = "business_card_analyser"
headers = {
"Ocp-Apim-Subscription-Key": "<YOUR_API_KEY>",
"Content-Type": "application/json"}
url = f"{<YOUR_ENDPOINT>}/contentunderstanding/analyzers/{analyzer_name}:analyze?api-version=2025-11-01"
request_body = {
"inputs": [
{
"url": "https://host.com/business-card.png"
}
]
}
response = requests.post(url, headers=headers, json=request_body)
# Get the response and extract the ID assigned to the analysis operation
response_json = response.json()
id_value = response_json.get("id")
# Use a GET request to check the status of the analysis operation
result_url = f"{<YOUR_ENDPOINT>}/contentunderstanding/analyzerResults/{id_value}?api-version=2025-11-01"
result_response = requests.get(result_url, headers=headers)
# Keep polling until the analysis is complete
status = result_response.json().get("status")
while status == "Running":
result_response = requests.get(result_url, headers=headers)
status = result_response.json().get("status")
# Get the analysis results
if status == "Succeeded":
result_json = result_response.json()
ملحوظة
يمكنك تحديد عنوان URL لموقع ملف المحتوى كما هو موضح هنا. لتقديم بيانات الملفات الثنائية مباشرة، استخدم العملية analyzeBinary بدلا من ذلك.
معالجة نتائج التحليل
تعتمد النتائج على:
- نوع المحتوى الذي تم تصميم المحلل لتحليله (على سبيل المثال، المستند أو الفيديو أو الصورة أو الصوت).
- مخطط المحلل.
- محتويات الملف الذي تم تحليله.
على سبيل المثال، تحتوي الاستجابة من محلل بطاقات العمل المستندة إلى المستند عند تحليل بطاقة العمل الموضحة سابقا على:
- الحقول المستخرجة
- تخطيط التعرف البصري على الحروف (OCR) للمستند، بما في ذلك مواقع أسطر النص والكلمات الفردية والفقرات في كل صفحة.
استخدام Python SDK
عند استخدام SDK، يوفر الكائن AnalysisResult وصولا نوعيا إلى النتائج. تحتوي الخاصية contents على قائمة بكائنات المحتوى، كل منها يحتوي على حقول وعلامات تحذيرية وبيانات وصفية. يوضح الكود التالي كيفية استخراج قيم حقول السلاسل النصية:
# (continued from previous SDK code example)
content = result.contents[0]
if content.fields:
for field_name, field_data in content.fields.items():
if field_data.type == "string":
print(f"{field_name}: {field_data.value}")
استخدام واجهة برمجة تطبيقات REST
عند استخدام واجهة برمجة تطبيقات REST، يكون الرد عبارة عن حمولة JSON يجب على تطبيقك تحليلها. فيما يلي استجابة JSON الكاملة لتحليل بطاقة العمل:
{
"id": "00000000-0000-0000-0000-a00000000000",
"status": "Succeeded",
"result": {
"analyzerId": "biz_card_analyser_2",
"apiVersion": "2025-11-01",
"createdAt": "2025-05-16T03:51:46Z",
"warnings": [],
"contents": [
{
"markdown": "John Smith\nEmail: john@contoso.com\n",
"fields": {
"ContactName": {
"type": "string",
"valueString": "John Smith",
"spans": [
{
"offset": 0,
"length": 10
}
],
"confidence": 0.994,
"source": "D(1,69,234,333,234,333,283,69,283)"
},
"EmailAddress": {
"type": "string",
"valueString": "john@contoso.com",
"spans": [
{
"offset": 18,
"length": 16
}
],
"confidence": 0.998,
"source": "D(1,179,309,458,309,458,341,179,341)"
}
},
"kind": "document",
"startPageNumber": 1,
"endPageNumber": 1,
"unit": "pixel",
"pages": [
{
"pageNumber": 1,
"angle": 0.03410444,
"width": 1000,
"height": 620,
"spans": [
{
"offset": 0,
"length": 35
}
],
"words": [
{
"content": "John",
"span": {
"offset": 0,
"length": 4
},
"confidence": 0.992,
"source": "D(1,69,234,181,234,180,283,69,283)"
},
{
"content": "Smith",
"span": {
"offset": 5,
"length": 5
},
"confidence": 0.998,
"source": "D(1,200,234,333,234,333,282,200,283)"
},
{
"content": "Email:",
"span": {
"offset": 11,
"length": 6
},
"confidence": 0.995,
"source": "D(1,75,310,165,309,165,340,75,340)"
},
{
"content": "john@contoso.com",
"span": {
"offset": 18,
"length": 16
},
"confidence": 0.977,
"source": "D(1,179,309,458,311,458,340,179,341)"
}
],
"lines": [
{
"content": "John Smith",
"source": "D(1,69,234,333,233,333,282,69,282)",
"span": {
"offset": 0,
"length": 10
}
},
{
"content": "Email: john@contoso.com",
"source": "D(1,75,309,458,309,458,340,75,340)",
"span": {
"offset": 11,
"length": 23
}
}
]
}
],
"paragraphs": [
{
"content": "John Smith Email: john@contoso.com",
"source": "D(1,69,233,458,233,458,340,69,340)",
"span": {
"offset": 0,
"length": 34
}
}
],
"sections": [
{
"span": {
"offset": 0,
"length": 34
},
"elements": [
"/paragraphs/0"
]
}
]
}
]
}
}
يجب أن يقوم التطبيق الخاص بك عادة بتحليل JSON لاسترداد قيم الحقول. على سبيل المثال، الكود التالي في بايثون يستخرج جميع قيم السلاسل النصية :
# (continued from previous code example)
# Iterate through the fields and extract the names and type-specific values
contents = result_json["result"]["contents"]
for content in contents:
if "fields" in content:
fields = content["fields"]
for field_name, field_data in fields.items():
if field_data['type'] == "string":
print(f"{field_name}: {field_data['valueString']}")
يظهر الإخراج من هذه التعليمة البرمجية هنا:
ContactName: John Smith
EmailAddress: john@contoso.com