استهلاك نموذج Azure التعلم الآلي تم نشره كخدمة ويب
يؤدي نشر نموذج Azure التعلم الآلي كخدمة ويب إلى إنشاء نقطة نهاية واجهة برمجة تطبيقات REST. يمكنك إرسال البيانات إلى نقطة النهاية هذه وتلقي التنبؤ الذي تم إرجاعه بواسطة النموذج. في هذا المستند، تعرف على كيفية إنشاء عملاء لخدمة الويب باستخدام C# وGo وJava وPython.
يمكنك إنشاء خدمة ويب عند نشر نموذج إلى البيئة المحلية أو مثيلات حاوية Azure أو خدمة Azure Kubernetes أو صفائف البوابات القابلة للبرمجة الميدانية (FPGA). يمكنك استرداد عنوان URI المستخدم للوصول إلى خدمة الويب باستخدام Azure التعلم الآلي SDK. إذا تم تمكين المصادقة، يمكنك أيضا استخدام SDK للحصول على مفاتيح المصادقة أو الرموز المميزة.
سير العمل العام لإنشاء عميل يستخدم خدمة ويب للتعلم الآلي هو:
- استخدم SDK للحصول على معلومات الاتصال.
- تحديد نوع بيانات الطلب المستخدمة من قبل النموذج.
- إنشاء تطبيق يستدعي خدمة الويب.
تلميح
يتم إنشاء الأمثلة الواردة في هذا المستند يدويا دون استخدام مواصفات OpenAPI (Swagger). إذا قمت بتمكين مواصفات OpenAPI للنشر، فيمكنك استخدام أدوات مثل swagger-codegen لإنشاء مكتبات عملاء لخدمتك.
معلومات الاتصال
ملاحظة
استخدم Azure التعلم الآلي SDK للحصول على معلومات خدمة الويب. هذا هو بايثون SDK. يمكنك استخدام أي لغة لإنشاء عميل للخدمة.
توفر فئة azureml.core.Webservice المعلومات التي تحتاجها لإنشاء عميل. الخصائص التالية Webservice مفيدة لإنشاء تطبيق عميل:
auth_enabled- إذا تم تمكين مصادقة المفتاح ،Trueوإلا ،False.token_auth_enabled- إذا تم تمكين مصادقة الرمز المميز ،True؛ خلاف ذلك ،False.scoring_uri- عنوان واجهة برمجة تطبيقات REST.swagger_uri- عنوان مواصفات OpenAPI. يتوفر عنوان URI هذا إذا قمت بتمكين إنشاء المخطط التلقائي. لمزيد من المعلومات، راجع نشر النماذج باستخدام Azure التعلم الآلي.
هناك عدة طرق لاسترداد هذه المعلومات لخدمات الويب المنشورة:
عند نشر نموذج،
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)
يوضح الجدول التالي كيف تبدو عناوين 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 للاتصال بالخدمة باستخدام عنوان URI الخاص بالتسجيل أو التباهي بالتسجيل. يساعد HTTPS على تأمين الاتصالات بين العميل وخدمة الويب عن طريق تشفير الاتصالات بين الاثنين. يستخدم التشفير أمان طبقة النقل (TLS). لا يزال يشار إلى TLS في بعض الأحيان باسم طبقة المقابس الآمنة (SSL) ، والتي كانت سلف TLS.
هام
خدمات الويب التي تم نشرها بواسطة Azure التعلم الآلي تدعم فقط TLS الإصدار 1.2. عند إنشاء تطبيق عميل، تأكد من أنه يدعم هذا الإصدار.
لمزيد من المعلومات، راجع استخدام طبقة النقل الآمنة لتأمين خدمة ويب من خلال Azure التعلم الآلي.
المصادقة على الخدمات
يوفر Azure التعلم الآلي طريقتين للتحكم في الوصول إلى خدمات الويب الخاصة بك.
| أسلوب المصادقة | ACI | AKS |
|---|---|---|
| المفتاح | معطل افتراضيا | مُمكّن بشكل افتراضي |
| الرمز المميز | غير متوفرة | معطل افتراضيا |
عند إرسال طلب إلى خدمة مؤمنة بمفتاح أو رمز مميز، استخدم رأس التفويض لتمرير المفتاح أو الرمز المميز. يجب تنسيق المفتاح أو الرمز المميز على النحو التالي: Bearer <key-or-token>، أين <key-or-token> توجد قيمة المفتاح أو الرمز المميز.
الفرق الأساسي بين المفاتيح والرموز المميزة هو أن المفاتيح ثابتة ويمكن إعادة تجديدها يدويا ، ويجب تحديث الرموز المميزة عند انتهاء الصلاحية. يتم دعم المصادقة المستندة إلى المفتاح لمثيل حاوية Azure وAzure Kubernetes Service المنشورة على الويب، ولا يتوفر المصادقة المستندة إلى الرمز المميز إلا لعمليات نشر Azure Kubernetes Service. لمزيد من المعلومات حول تكوين المصادقة، راجع تكوين المصادقة للنماذج التي تم نشرها كخدمات ويب.
المصادقة باستخدام المفاتيح
عند تمكين المصادقة لعملية نشر، يمكنك إنشاء مفاتيح مصادقة تلقائيا.
- يتم تمكين المصادقة بشكل افتراضي عند النشر في Azure Kubernetes Service.
- يتم تعطيل المصادقة بشكل افتراضي عند النشر في مثيلات حاوية Azure.
للتحكم في المصادقة، استخدم المعلمة auth_enabled عند إنشاء عملية نشر أو تحديثها.
إذا تم تمكين المصادقة، يمكنك استخدام الطريقة get_keys لاسترداد مفتاح مصادقة أساسي وثانوي:
primary, secondary = service.get_keys()
print(primary)
هام
إذا كنت بحاجة إلى إعادة إنشاء مفتاح، فاستخدم service.regen_key.
المصادقة باستخدام الرموز المميزة
عند تمكين مصادقة الرمز المميز لخدمة ويب، يجب على المستخدم توفير رمز Azure التعلم الآلي JWT المميز لخدمة الويب للوصول إليه.
- يتم تعطيل مصادقة الرمز المميز بشكل افتراضي عند النشر في Azure Kubernetes Service.
- لا يتم دعم مصادقة الرمز المميز عند النشر إلى مثيلات حاوية Azure.
للتحكم في مصادقة الرمز المميز، استخدم المعلمة token_auth_enabled عند إنشاء عملية نشر أو تحديثها.
إذا تم تمكين مصادقة الرمز المميز ، فيمكنك استخدام get_token الطريقة لاسترداد رمز مميز لحامله ووقت انتهاء صلاحية الرموز المميزة:
token, refresh_by = service.get_token()
print(token)
إذا كان لديك Azure CLI وملحق التعلم الآلي، فيمكنك استخدام الأمر التالي للحصول على رمز مميز:
APPLY TO: Azure CLI ml extension
ع1
v2 (معاينة)
az ml service get-access-token -n <service-name>
هام
حاليا الطريقة الوحيدة لاسترداد الرمز المميز هي باستخدام Azure التعلم الآلي SDK أو ملحق التعلم الآلي 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)
يوضح هذا المثال كيفية استخدام الانتقال للاتصال بخدمة الويب التي تم إنشاؤها من مثال " التدريب داخل دفتر الملاحظات" :
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 للاتصال بخدمة الويب التي تم إنشاؤها من مثال " التدريب داخل دفتر الملاحظات" :
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 للاتصال بخدمة الويب التي تم إنشاؤها من مثال " التدريب داخل دفتر الملاحظات" :
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.