استخدام نموذج التعلم الآلي من Azure الموزع كخدمة ويب

يؤدي توزيع نموذج التعلم الآلي من Azure كخدمة ويب إلى إنشاء نقطة نهاية واجهة برمجة تطبيقات REST. يمكنك إرسال البيانات إلى نقطة النهاية هذه وتلقي التنبؤ الذي تم إرجاعه بواسطة النموذج. في هذا المستند، تعرف على كيفية إنشاء عملاء لخدمة الويب باستخدام C# وGo وJava وPython.

يمكنك إنشاء خدمة ويب عند توزيع نموذج إلى بيئتك المحلية، أو مثيلات حاوية Azure، أو Azure Kubernetes Service، أو صفائف البوابة القابلة للبرمجة الميدانية (FPGA). يمكنك استرداد عنوان URI المستخدم للوصول إلى خدمة الويب باستخدام SDK لنظام التعلم الآلي من Azure. إذا تم تمكين المصادقة، يمكنك أيضا استخدام SDK للحصول على مفاتيح المصادقة أو الرموز المميزة.

يتمثل سير العمل العام لإنشاء عميل يستخدم خدمة ويب للتعلم الآلي في:

1. استخدم SDK للحصول على معلومات الاتصال.
2. تحديد نوع بيانات الطلب المستخدمة من قبل النموذج.
3. إنشاء تطبيق يستدعي خدمة الويب.

تلميح

يتم إنشاء الأمثلة في هذا المستند يدوياً دون استخدام مواصفات OpenAPI (Swagger). إذا قمت بتمكين مواصفات OpenAPI للتوزيع، يمكنك استخدام أدوات مثل swagger-codegen لإنشاء مكتبات العميل للخدمة لديك.

هام

تتطلب أوامر Azure CLI الواردة في هذه المقالة ملحق azure-cli-ml، أو الإصدار 1، التعلم الآلي من Microsoft Azure. سينتهي دعم ملحق الإصدار 1 في 30 سبتمبر 2025. ستتمكن من تثبيت ملحق v1 واستخدامه حتى ذلك التاريخ.

نوصي بالانتقال إلى ملحق ml أو الإصدار 2 قبل 30 سبتمبر 2025. لمزيد من المعلومات حول ملحق v2، راجع ملحق Azure ML CLI وPython SDK v2.

معلومات الاتصال

ملاحظة

استخدم SDK لنظام التعلم الآلي من Azure للحصول على معلومات خدمة الويب. يعد هذا هو Python SDK. يمكنك استخدام أي لغة لإنشاء عميل للخدمة.

توفر فئة azureml.core.Webservice المعلومات التي تحتاجها لإنشاء عميل. الخصائص Webservice التالية مفيدة لإنشاء تطبيق عميل:

• auth_enabled - إذا تم تمكين مصادقة المفتاح، True؛ وإلا، False.
• token_auth_enabled - إذا تم تمكين مصادقة الرمز المميز، True؛ وإلا، False.
• scoring_uri - عنوان واجهة برمجة تطبيقات REST.
• swagger_uri - عنوان مواصفات OpenAPI. يتوفر URI هذا إذا قمت بتمكين إنشاء المخطط التلقائي. لمزيد من المعلومات، راجع توزيع النموذج الحالي باستخدام التعلم الآلي من Azure.

هناك عدة طرق لاسترداد هذه المعلومات لخدمات الويب الموزعة:

Python SDK

ينطبق على:Python SDK azureml v1

• عند توزيع نموذج، يتم إرجاع عنصر Webservice بمعلومات حول الخدمة:

  service = Model.deploy(ws, "myservice", [model], inference_config, deployment_config)
  service.wait_for_deployment(show_output = True)
  print(service.scoring_uri)
  print(service.swagger_uri)
  

• يمكنك استخدام Webservice.list لاسترداد قائمة بخدمات الويب الموزعة للنماذج في مساحة العمل لديك. يمكنك إضافة عوامل تصفية لتضييق نطاق قائمة المعلومات التي تم إرجاعها. لمزيد من المعلومات حول ما يمكن تصفيته، راجع الوثائق المرجعية Webservice.list.

  services = Webservice.list(ws)
  print(services[0].scoring_uri)
  print(services[0].swagger_uri)
  

• إذا كنت تعرف اسم الخدمة الموزعة، يمكنك إنشاء مثيل جديد من Webservice، وتوفير مساحة العمل واسم الخدمة كمعلمات. يحتوي العنصر الجديد على معلومات حول الخدمة الموزعة.

  service = Webservice(workspace=ws, name='myservice')
  print(service.scoring_uri)
  print(service.swagger_uri)
  

Azure CLI

ينطبق على:ملحق Azure CLI ml v1

إذا كنت تعرف اسم الخدمة الموزعة، فاستخدم الأمر az ml service show:

az ml service show -n <service-name>

استوديو

من استوديو التعلم الآلي من Azure، حدد نقاط النهاية، ونقاط النهاية في الوقت الحقيقي، ثم اسم نقطة النهاية. في تفاصيل نقطة النهاية، يحتوي حقل نقطة نهاية REST على URI لتسجيل النقاط. يحتوي Swagger URI على عنوان URI لـ swagger.

يوضح الجدول التالي شكل معرفات URI هذه:

نوع URI	مثال
تسجيل URI	http://104.214.29.152:80/api/v1/service/<service-name>/score
Swagger URI	http://104.214.29.152/api/v1/service/<service-name>/swagger.json

تلميح

سيكون عنوان IP مختلفاً للتوزيع لديك. سيكون لكل نظام مجموعة AKS عنوان IP الخاص به الذي تتم مشاركته بواسطة عمليات التوزيع إلى نظام المجموعة هذا.

خدمة ويب آمنة

إذا قمت بتأمين خدمة الويب الموزعة باستخدام شهادة TLS/SSL، يمكنك استخدام HTTPS للاتصال بالخدمة باستخدام تسجيل النقاط أو swagger URI. يساعد HTTPS في تأمين الاتصالات بين العميل وخدمة الويب عن طريق تشفير الاتصالات بين الطرفين. التشفير يستخدم Transport Layer Security (TLS). لا يزال يشار إلى TLS أحياناً باسم طبقة مآخذ توصيل آمنة (SSL)، والتي كانت سلف لـ TLS.

هام

تدعم خدمات الويب التي تم توزيعها بواسطة التعلم الآلي من Azure الإصدار 1.2 من TLS فقط. عند إنشاء تطبيق عميل، تأكد من أنه يدعم هذا الإصدار.

لمزيد من المعلومات، راجع استخدام TLS لتأمين خدمة ويب من خلال التعلم الآلي من Azure.

مصادقة الخدمات

يوفر نظام التعلم الآلي من Azure طريقتين للتحكم في الوصول إلى خدمات الويب الخاصة بك.

طريقة التصديق	ACI	AKS
المفتاح	معطل بشكل افتراضي	مُمكّن بشكل افتراضي
الرمز المميز	غير متوفرة	معطل بشكل افتراضي

عند إرسال طلب إلى خدمة مؤمنة بمفتاح أو رمز مميز، استخدم عنوان التخويل لتمرير المفتاح أو الرمز المميز. يجب تنسيق المفتاح أو الرمز المميز كـ Bearer <key-or-token>، حيث يمثل <key-or-token> قيمة المفتاح أو الرمز المميز.

يتمثل الفرق الأساسي بين المفاتيح والرموز المميزة في أن المفاتيح ثابتة ويمكن إعادة إنشائها يدوياً، ويجب تحديث الرموز المميزة عند انتهاء الصلاحية. يتم دعم المصادقة المستندة إلى المفتاح لمثيل حاوية Azure وAzure Kubernetes Service التي وزعت خدمات الويب، ولا تتوفر المصادقة المستندة إلى الرمز المميز إلا لعمليات توزيع Azure Kubernetes Service. لمزيد من المعلومات حول تكوين المصادقة، راجع تكوين المصادقة للنماذج الموزعة كخدمات ويب.

المصادقة باستخدام المفاتيح

عند تمكين المصادقة للتوزيع، يمكنك إنشاء مفاتيح المصادقة تلقائياً.

• يتم تمكين المصادقة بشكل افتراضي عند التوزيع إلى Azure Kubernetes Service.
• يتم تعطيل المصادقة بشكل افتراضي عند التوزيع إلى Azure Container Instances.

للتحكم في المصادقة، استخدم المعلمة auth_enabled عند إنشاء توزيع أو تحديثه.

إذا تم تمكين المصادقة، يمكنك استخدام الأسلوب get_keys لاسترداد مفتاح مصادقة أساسي وثانوي:

primary, secondary = service.get_keys()
print(primary)

هام

إذا كنت بحاجة إلى إعادة إنشاء مفتاح، فاستخدم service.regen_key.

المصادقة مع الرموز المميزة

عند تمكين مصادقة الرمز المميز لخدمة ويب، يجب على المستخدم توفير الرمز المميز لنظام التعلم الآلي من Azure لخدمة الويب للوصول إليه.

• يتم تعطيل مصادقة الرمز المميز بشكل افتراضي عند التوزيع إلى Azure Kubernetes Service.
• مصادقة الرمز المميز غير مدعومة عند التوزيع إلى Azure Container Instances.

للتحكم في مصادقة الرمز المميز، استخدم المعلمة token_auth_enabled عند إنشاء توزيع أو تحديثه.

إذا تم تمكين مصادقة الرمز المميز، يمكنك استخدام الأسلوب get_token لاسترداد الرمز المميز للحامل ووقت انتهاء صلاحية الرموز المميزة:

token, refresh_by = service.get_token()
print(token)

إذا كان لديك ملحق Azure CLI ونظام التعلم الآلي من Azure، يمكنك استخدام الأمر التالي للحصول على رمز مميز:

ينطبق على:ملحق Azure CLI ml v1

az ml service get-access-token -n <service-name>

هام

تعد الطريقة الوحيدة حالياً لاسترداد الرمز المميز هي باستخدام SDK لنظام التعلم الآلي من Azure أو ملحق التعلم الآلي من Azure CLI.

ستحتاج إلى طلب رمز مميز جديد بعد وقت الرمز المميز refresh_by.

طلب البيانات

تتوقع واجهة برمجة تطبيقات REST أن يكون نص الطلب مستند JSON بالبنية التالية:

{
    "data":
        [
            <model-specific-data-structure>
        ]
}

هام

يجب أن تتطابق بنية البيانات مع ما يتوقعه البرنامج النصي لتسجيل النقاط والنموذج في الخدمة. قد يقوم البرنامج النصي لتسجيل النقاط بتعديل البيانات قبل تمريرها إلى النموذج.

بيانات ثنائية

للحصول على معلومات حول كيفية تمكين دعم البيانات الثنائية في خدمتك، راجع البيانات الثنائية.

تلميح

يحدث تمكين دعم البيانات الثنائية في ملف score.py المستخدم من قبل النموذج الموزع. من العميل، استخدم وظيفة HTTP للغة البرمجة لديك. على سبيل المثال، ترسل القصاصة البرمجية التالية محتويات ملف JPG إلى خدمة ويب:

import requests
# Load image data
data = open('example.jpg', 'rb').read()
# Post raw data to scoring URI
res = request.post(url='<scoring-uri>', data=data, headers={'Content-Type': 'application/> octet-stream'})

مشاركة الموارد عبر المنشأ (CORS)

للحصول على معلومات حول تمكين دعم CORS في خدمتك، راجع مشاركة الموارد عبر المنشأ.

استدعاء الخدمة (C#)

يوضح هذا المثال كيفية استخدام C# لاستدعاء خدمة الويب التي تم إنشاؤها من مثال تدريب داخل دفتر الملاحظات:

using System;
using System.Collections.Generic;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using Newtonsoft.Json;

namespace MLWebServiceClient
{
    // The data structure expected by the service
    internal class InputData
    {
        [JsonProperty("data")]
        // The service used by this example expects an array containing
        //   one or more arrays of doubles
        internal double[,] data;
    }
    class Program
    {
        static void Main(string[] args)
        {
            // Set the scoring URI and authentication key or token
            string scoringUri = "<your web service URI>";
            string authKey = "<your key or token>";

            // Set the data to be sent to the service.
            // In this case, we are sending two sets of data to be scored.
            InputData payload = new InputData();
            payload.data = new double[,] {
                {
                    0.0199132141783263,
                    0.0506801187398187,
                    0.104808689473925,
                    0.0700725447072635,
                    -0.0359677812752396,
                    -0.0266789028311707,
                    -0.0249926566315915,
                    -0.00259226199818282,
                    0.00371173823343597,
                    0.0403433716478807
                },
                {
                    -0.0127796318808497, 
                    -0.044641636506989, 
                    0.0606183944448076, 
                    0.0528581912385822, 
                    0.0479653430750293, 
                    0.0293746718291555, 
                    -0.0176293810234174, 
                    0.0343088588777263, 
                    0.0702112981933102, 
                    0.00720651632920303
                }
            };

            // Create the HTTP client
            HttpClient client = new HttpClient();
            // Set the auth header. Only needed if the web service requires authentication.
            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", authKey);

            // Make the request
            try {
                var request = new HttpRequestMessage(HttpMethod.Post, new Uri(scoringUri));
                request.Content = new StringContent(JsonConvert.SerializeObject(payload));
                request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
                var response = client.SendAsync(request).Result;
                // Display the response from the web service
                Console.WriteLine(response.Content.ReadAsStringAsync().Result);
            }
            catch (Exception e)
            {
                Console.Out.WriteLine(e.Message);
            }
        }
    }
}

النتائج التي تم إرجاعها مشابهة لمستند JSON التالي:

[217.67978776218715, 224.78937091757172]

استدعاء الخدمة (Go)

يوضح هذا المثال كيفية استخدام Go لاستدعاء خدمة الويب التي تم إنشاؤها من مثال تدريب داخل دفتر الملاحظات:

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

// Features for this model are an array of decimal values
type Features []float64

// The web service input can accept multiple sets of values for scoring
type InputData struct {
    Data []Features `json:"data",omitempty`
}

// Define some example data
var exampleData = []Features{
    []float64{
        0.0199132141783263, 
        0.0506801187398187, 
        0.104808689473925, 
        0.0700725447072635, 
        -0.0359677812752396, 
        -0.0266789028311707, 
        -0.0249926566315915, 
        -0.00259226199818282, 
        0.00371173823343597, 
        0.0403433716478807,
    },
    []float64{
        -0.0127796318808497, 
        -0.044641636506989, 
        0.0606183944448076, 
        0.0528581912385822, 
        0.0479653430750293, 
        0.0293746718291555, 
        -0.0176293810234174, 
        0.0343088588777263, 
        0.0702112981933102, 
        0.00720651632920303,
    },
}

// Set to the URI for your service
var serviceUri string = "<your web service URI>"
// Set to the authentication key or token (if any) for your service
var authKey string = "<your key or token>"

func main() {
    // Create the input data from example data
    jsonData := InputData{
        Data: exampleData,
    }
    // Create JSON from it and create the body for the HTTP request
    jsonValue, _ := json.Marshal(jsonData)
    body := bytes.NewBuffer(jsonValue)

    // Create the HTTP request
    client := &http.Client{}
    request, err := http.NewRequest("POST", serviceUri, body)
    request.Header.Add("Content-Type", "application/json")

    // These next two are only needed if using an authentication key
    bearer := fmt.Sprintf("Bearer %v", authKey)
    request.Header.Add("Authorization", bearer)

    // Send the request to the web service
    resp, err := client.Do(request)
    if err != nil {
        fmt.Println("Failure: ", err)
    }

    // Display the response received
    respBody, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(respBody))
}

النتائج التي تم إرجاعها مشابهة لمستند JSON التالي:

[217.67978776218715, 224.78937091757172]

استدعاء الخدمة (Java)

يوضح هذا المثال كيفية استخدام Java لاستدعاء خدمة الويب التي تم إنشاؤها من مثال تدريب داخل دفتر الملاحظات:

import java.io.IOException;
import org.apache.http.client.fluent.*;
import org.apache.http.entity.ContentType;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;

public class App {
    // Handle making the request
    public static void sendRequest(String data) {
        // Replace with the scoring_uri of your service
        String uri = "<your web service URI>";
        // If using authentication, replace with the auth key or token
        String key = "<your key or token>";
        try {
            // Create the request
            Content content = Request.Post(uri)
            .addHeader("Content-Type", "application/json")
            // Only needed if using authentication
            .addHeader("Authorization", "Bearer " + key)
            // Set the JSON data as the body
            .bodyString(data, ContentType.APPLICATION_JSON)
            // Make the request and display the response.
            .execute().returnContent();
            System.out.println(content);
        }
        catch (IOException e) {
            System.out.println(e);
        }
    }
    public static void main(String[] args) {
        // Create the data to send to the service
        JSONObject obj = new JSONObject();
        // In this case, it's an array of arrays
        JSONArray dataItems = new JSONArray();
        // Inner array has 10 elements
        JSONArray item1 = new JSONArray();
        item1.add(0.0199132141783263);
        item1.add(0.0506801187398187);
        item1.add(0.104808689473925);
        item1.add(0.0700725447072635);
        item1.add(-0.0359677812752396);
        item1.add(-0.0266789028311707);
        item1.add(-0.0249926566315915);
        item1.add(-0.00259226199818282);
        item1.add(0.00371173823343597);
        item1.add(0.0403433716478807);
        // Add the first set of data to be scored
        dataItems.add(item1);
        // Create and add the second set
        JSONArray item2 = new JSONArray();
        item2.add(-0.0127796318808497);
        item2.add(-0.044641636506989);
        item2.add(0.0606183944448076);
        item2.add(0.0528581912385822);
        item2.add(0.0479653430750293);
        item2.add(0.0293746718291555);
        item2.add(-0.0176293810234174);
        item2.add(0.0343088588777263);
        item2.add(0.0702112981933102);
        item2.add(0.00720651632920303);
        dataItems.add(item2);
        obj.put("data", dataItems);

        // Make the request using the JSON document string
        sendRequest(obj.toJSONString());
    }
}

النتائج التي تم إرجاعها مشابهة لمستند JSON التالي:

[217.67978776218715, 224.78937091757172]

استدعاء الخدمة (Python)

يوضح هذا المثال كيفية استخدام Python لاستدعاء خدمة الويب التي تم إنشاؤها من مثال تدريب داخل دفتر الملاحظات:

import requests
import json

# URL for the web service
scoring_uri = '<your web service URI>'
# If the service is authenticated, set the key or token
key = '<your key or token>'

# Two sets of data to score, so we get two results back
data = {"data":
        [
            [
                0.0199132141783263,
                0.0506801187398187,
                0.104808689473925,
                0.0700725447072635,
                -0.0359677812752396,
                -0.0266789028311707,
                -0.0249926566315915,
                -0.00259226199818282,
                0.00371173823343597,
                0.0403433716478807
            ],
            [
                -0.0127796318808497,
                -0.044641636506989,
                0.0606183944448076,
                0.0528581912385822,
                0.0479653430750293,
                0.0293746718291555,
                -0.0176293810234174,
                0.0343088588777263,
                0.0702112981933102,
                0.00720651632920303]
        ]
        }
# Convert to JSON string
input_data = json.dumps(data)

# Set the content type
headers = {'Content-Type': 'application/json'}
# If authentication is enabled, set the authorization header
headers['Authorization'] = f'Bearer {key}'

# Make the request and display the response
resp = requests.post(scoring_uri, input_data, headers=headers)
print(resp.text)

النتائج التي تم إرجاعها مشابهة لمستند JSON التالي:

[217.67978776218715, 224.78937091757172]

مخطط خدمة الويب (مواصفات OpenAPI)

إذا استخدمت إنشاء مخطط تلقائي مع التوزيع الخاص بك، يمكنك الحصول على عنوان مواصفات OpenAPI للخدمة باستخدام خاصية swagger_uri. (على سبيل المثال، print(service.swagger_uri).) استخدم طلب GET أو افتح URI في مستعرض لاسترداد المواصفات.

يعد مستند JSON التالي مثالاً على مخطط (مواصفات OpenAPI) تم إنشاؤه للتوزيع:

{
    "swagger": "2.0",
    "info": {
        "title": "myservice",
        "description": "API specification for Azure Machine Learning myservice",
        "version": "1.0"
    },
    "schemes": [
        "https"
    ],
    "consumes": [
        "application/json"
    ],
    "produces": [
        "application/json"
    ],
    "securityDefinitions": {
        "Bearer": {
            "type": "apiKey",
            "name": "Authorization",
            "in": "header",
            "description": "For example: Bearer abc123"
        }
    },
    "paths": {
        "/": {
            "get": {
                "operationId": "ServiceHealthCheck",
                "description": "Simple health check endpoint to ensure the service is up at any given point.",
                "responses": {
                    "200": {
                        "description": "If service is up and running, this response will be returned with the content 'Healthy'",
                        "schema": {
                            "type": "string"
                        },
                        "examples": {
                            "application/json": "Healthy"
                        }
                    },
                    "default": {
                        "description": "The service failed to execute due to an error.",
                        "schema": {
                            "$ref": "#/definitions/ErrorResponse"
                        }
                    }
                }
            }
        },
        "/score": {
            "post": {
                "operationId": "RunMLService",
                "description": "Run web service's model and get the prediction output",
                "security": [
                    {
                        "Bearer": []
                    }
                ],
                "parameters": [
                    {
                        "name": "serviceInputPayload",
                        "in": "body",
                        "description": "The input payload for executing the real-time machine learning service.",
                        "schema": {
                            "$ref": "#/definitions/ServiceInput"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The service processed the input correctly and provided a result prediction, if applicable.",
                        "schema": {
                            "$ref": "#/definitions/ServiceOutput"
                        }
                    },
                    "default": {
                        "description": "The service failed to execute due to an error.",
                        "schema": {
                            "$ref": "#/definitions/ErrorResponse"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "ServiceInput": {
            "type": "object",
            "properties": {
                "data": {
                    "type": "array",
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "integer",
                            "format": "int64"
                        }
                    }
                }
            },
            "example": {
                "data": [
                    [ 10, 9, 8, 7, 6, 5, 4, 3, 2, 1 ]
                ]
            }
        },
        "ServiceOutput": {
            "type": "array",
            "items": {
                "type": "number",
                "format": "double"
            },
            "example": [
                3726.995
            ]
        },
        "ErrorResponse": {
            "type": "object",
            "properties": {
                "status_code": {
                    "type": "integer",
                    "format": "int32"
                },
                "message": {
                    "type": "string"
                }
            }
        }
    }
}

لمزيد من المعلومات، راجع مواصفات OpenAPI.

للحصول على أداة مساعدة يمكنها إنشاء مكتبات العميل من المواصفات، راجع swagger-codegen.

تلميح

يمكنك استرداد مستند JSON للمخطط بعد توزيع الخدمة. استخدم خاصية swagger_uri من خدمة الويب الموزعة (على سبيل المثال، service.swagger_uri) للحصول على URI إلى ملف Swagger الخاص بخدمة الويب المحلية.

استهلاك الخدمة من Power BI

يدعم Power BI استهلاك خدمات الويب لنظام التعلم الآلي من Azure لإثراء البيانات في Power BI بالتنبؤات.

لإنشاء خدمة ويب مدعومة للاستهلاك في Power BI، يجب أن يدعم المخطط التنسيق المطلوب من قِبل Power BI. تعرف على كيفية إنشاء مخطط مدعوم من Power BI.

بمجرد توزيع خدمة الويب، يمكن استهلاكها من تدفقات بيانات Power BI. تعرف على كيفية استهلاك خدمة ويب نظام التعلم الآلي من Azure من Power BI.

الخطوات التالية

لعرض بنية مرجعية لتسجيل النقاط في الوقت الحقيقي لـ Python ونماذج التعلم العميق، انتقل إلى مركز تصميم Azure.