トレーニング
認定資格
Microsoft Certified: Azure AI Engineer Associate - Certifications
Azure AI サービス、Azure AI 検索、Azure Open AI を使用して Azure AI ソリューションを設計して実装します。
このブラウザーはサポートされなくなりました。
Microsoft Edge にアップグレードすると、最新の機能、セキュリティ更新プログラム、およびテクニカル サポートを利用できます。
この例では、Web API カスタム スキルを作成する方法について説明します。 このスキルでは、場所、著名人、組織を受け入れ、それらの説明を返します。 この例では、Azure Functionsを使用して、カスタム スキル インターフェイスを実装できるように Bing Entity Search API をラップします。
カスタム スキルで実装する必要がある入出力インターフェイスがよくわからない場合は、カスタム スキル インターフェイスに関する記事を参照してください。
Azure portal から Bing 検索 リソースを作成します。 この例では、Free レベルを使用して十分です。
Visual Studio 以降をインストールします。
この例では Azure 関数を使用して Web API をホストしていますが、必須ではありません。 コグニティブ スキルのインターフェイス要件を満たしていれば、どのような方法を使用してもかまいません。 ただし、Azure Functions を使用すると、カスタム スキルを簡単に作成できます。
Visual Studio で、[ファイル] メニューから [新規]>[プロジェクト] の順に選択します。
テンプレートとして [Azure Functions] を選択し、[次へ] を選択します。 プロジェクトの名前を入力し、[作成] を選択します。 関数アプリ名は、C# 名前空間として有効である必要があります。そのため、アンダースコア、ハイフン、その他の英数字以外の文字は使用しないでください。
長期的なサポートを持つフレームワークを選択します。
プロジェクトに追加する関数の種類として [HTTP トリガー] を選択します。
権限レベルとして [機能] を選択します。
[作成] を選択して、関数プロジェクトと、HTTP でトリガーされる関数を作成します。
Visual Studio は、選択した関数型の定型コードを含むプロジェクトを作成します。 メソッドの FunctionName 属性は、Functions の名前を設定します HttpTrigger 属性は、Functions が HTTP 要求によってトリガーされることを指定します。
Function1.cs のコンテンツを次のコードに置き換えます。
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;
namespace SampleSkills
{
/// <summary>
/// Sample custom skill that wraps the Bing entity search API to connect it with a
/// AI enrichment pipeline.
/// </summary>
public static class BingEntitySearch
{
#region Credentials
// IMPORTANT: Make sure to enter your credential and to verify the API endpoint matches yours.
static readonly string bingApiEndpoint = "https://api.bing.microsoft.com/v7.0/entities";
static readonly string key = "<enter your api key here>";
#endregion
#region Class used to deserialize the request
private class InputRecord
{
public class InputRecordData
{
public string Name { get; set; }
}
public string RecordId { get; set; }
public InputRecordData Data { get; set; }
}
private class WebApiRequest
{
public List<InputRecord> Values { get; set; }
}
#endregion
#region Classes used to serialize the response
private class OutputRecord
{
public class OutputRecordData
{
public string Name { get; set; } = "";
public string Description { get; set; } = "";
public string Source { get; set; } = "";
public string SourceUrl { get; set; } = "";
public string LicenseAttribution { get; set; } = "";
public string LicenseUrl { get; set; } = "";
}
public class OutputRecordMessage
{
public string Message { get; set; }
}
public string RecordId { get; set; }
public OutputRecordData Data { get; set; }
public List<OutputRecordMessage> Errors { get; set; }
public List<OutputRecordMessage> Warnings { get; set; }
}
private class WebApiResponse
{
public List<OutputRecord> Values { get; set; }
}
#endregion
#region Classes used to interact with the Bing API
private class BingResponse
{
public BingEntities Entities { get; set; }
}
private class BingEntities
{
public BingEntity[] Value { get; set; }
}
private class BingEntity
{
public class EntityPresentationinfo
{
public string[] EntityTypeHints { get; set; }
}
public class License
{
public string Url { get; set; }
}
public class ContractualRule
{
public string _type { get; set; }
public License License { get; set; }
public string LicenseNotice { get; set; }
public string Text { get; set; }
public string Url { get; set; }
}
public ContractualRule[] ContractualRules { get; set; }
public string Description { get; set; }
public string Name { get; set; }
public EntityPresentationinfo EntityPresentationInfo { get; set; }
}
#endregion
#region The Azure Function definition
[FunctionName("EntitySearch")]
public static async Task<IActionResult> Run(
[HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] HttpRequest req,
ILogger log)
{
log.LogInformation("Entity Search function: C# HTTP trigger function processed a request.");
var response = new WebApiResponse
{
Values = new List<OutputRecord>()
};
string requestBody = new StreamReader(req.Body).ReadToEnd();
var data = JsonConvert.DeserializeObject<WebApiRequest>(requestBody);
// Do some schema validation
if (data == null)
{
return new BadRequestObjectResult("The request schema does not match expected schema.");
}
if (data.Values == null)
{
return new BadRequestObjectResult("The request schema does not match expected schema. Could not find values array.");
}
// Calculate the response for each value.
foreach (var record in data.Values)
{
if (record == null || record.RecordId == null) continue;
OutputRecord responseRecord = new OutputRecord
{
RecordId = record.RecordId
};
try
{
responseRecord.Data = GetEntityMetadata(record.Data.Name).Result;
}
catch (Exception e)
{
// Something bad happened, log the issue.
var error = new OutputRecord.OutputRecordMessage
{
Message = e.Message
};
responseRecord.Errors = new List<OutputRecord.OutputRecordMessage>
{
error
};
}
finally
{
response.Values.Add(responseRecord);
}
}
return (ActionResult)new OkObjectResult(response);
}
#endregion
#region Methods to call the Bing API
/// <summary>
/// Gets metadata for a particular entity based on its name using Bing Entity Search
/// </summary>
/// <param name="entityName">The name of the entity to extract data for.</param>
/// <returns>Asynchronous task that returns entity data. </returns>
private async static Task<OutputRecord.OutputRecordData> GetEntityMetadata(string entityName)
{
var uri = bingApiEndpoint + "?q=" + entityName + "&mkt=en-us&count=10&offset=0&safesearch=Moderate";
var result = new OutputRecord.OutputRecordData();
using (var client = new HttpClient())
using (var request = new HttpRequestMessage {
Method = HttpMethod.Get,
RequestUri = new Uri(uri)
})
{
request.Headers.Add("Ocp-Apim-Subscription-Key", key);
HttpResponseMessage response = await client.SendAsync(request);
string responseBody = await response?.Content?.ReadAsStringAsync();
BingResponse bingResult = JsonConvert.DeserializeObject<BingResponse>(responseBody);
if (bingResult != null)
{
// In addition to the list of entities that could match the name, for simplicity let's return information
// for the top match as additional metadata at the root object.
return AddTopEntityMetadata(bingResult.Entities?.Value);
}
}
return result;
}
private static OutputRecord.OutputRecordData AddTopEntityMetadata(BingEntity[] entities)
{
if (entities != null)
{
foreach (BingEntity entity in entities.Where(
entity => entity?.EntityPresentationInfo?.EntityTypeHints != null
&& (entity.EntityPresentationInfo.EntityTypeHints[0] == "Person"
|| entity.EntityPresentationInfo.EntityTypeHints[0] == "Organization"
|| entity.EntityPresentationInfo.EntityTypeHints[0] == "Location")
&& !String.IsNullOrEmpty(entity.Description)))
{
var rootObject = new OutputRecord.OutputRecordData
{
Description = entity.Description,
Name = entity.Name
};
if (entity.ContractualRules != null)
{
foreach (var rule in entity.ContractualRules)
{
switch (rule._type)
{
case "ContractualRules/LicenseAttribution":
rootObject.LicenseAttribution = rule.LicenseNotice;
rootObject.LicenseUrl = rule.License.Url;
break;
case "ContractualRules/LinkAttribution":
rootObject.Source = rule.Text;
rootObject.SourceUrl = rule.Url;
break;
}
}
}
return rootObject;
}
}
return new OutputRecord.OutputRecordData();
}
#endregion
}
}
Bing Entity Search API にサインアップしたときに取得したキーに基づいて、key
定数の独自の key 値を確実に入力します。
F5 キーを押して、プログラムを実行し、関数の動作をテストします。 ここでは、次の Functions を使用して、2 つのエンティティを検索します。 REST クライアントを使用して、次のような呼び出しを発行します。
POST https://localhost:7071/api/EntitySearch
{
"values": [
{
"recordId": "e1",
"data":
{
"name": "Pablo Picasso"
}
},
{
"recordId": "e2",
"data":
{
"name": "Microsoft"
}
}
]
}
次の例のような応答が表示されます。
{
"values": [
{
"recordId": "e1",
"data": {
"name": "Pablo Picasso",
"description": "Pablo Ruiz Picasso was a Spanish painter [...]",
"source": "Wikipedia",
"sourceUrl": "http://en.wikipedia.org/wiki/Pablo_Picasso",
"licenseAttribution": "Text under CC-BY-SA license",
"licenseUrl": "http://creativecommons.org/licenses/by-sa/3.0/"
},
"errors": null,
"warnings": null
},
"..."
]
}
関数の動作に満足したら、発行できます。
ソリューション エクスプローラーで、プロジェクトを右クリックし、 [発行] を選択します。 [新規作成]>[発行] の順に選択します。
まだ Visual Studio を Azure アカウントに接続していない場合は、[アカウントの追加] を選択します。
画面の指示に従います。 使用するアプリ サービス、Azure サブスクリプション、リソース グループ、ホスティング プラン、ストレージ アカウントに対して一意の名前を指定するように求められます。 リソース グループ、ホスティング プラン、ストレージ アカウントをまだ作成していない場合は新しく作成できます。 終わったら、[作成] を選択します。
デプロイが完了したら、サイトの URL を書き留めておきます。 これが Azure における関数アプリのアドレスになります。
Azure portal でリソース グループに移動し、発行した EntitySearch
Functions を探します。 [管理] セクションに [ホスト キー] が表示されます。 "既定" のホスト キーの [コピー] アイコンを選択します。
既定のホスト キーが用意できたので、次のように関数をテストします。
POST https://[your-entity-search-app-name].azurewebsites.net/api/EntitySearch?code=[enter default host key here]
{
"values": [
{
"recordId": "e1",
"data":
{
"name": "Pablo Picasso"
}
},
{
"recordId": "e2",
"data":
{
"name": "Microsoft"
}
}
]
}
この例では、以前にローカル環境で Functions を実行したときと同じ結果が得られるはずです。
新しいカスタム スキルが作成できたので、スキルセットに追加できます。 次の例では、スキルを呼び出して、ドキュメント内の組織に説明を追加する方法を示しています (これは場所および人の操作にも拡張できる可能性があります)。 [your-entity-search-app-name]
をご自分のアプリの名前に置き換えます。
{
"skills": [
"[... your existing skills remain here]",
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "Our new Bing entity search custom skill",
"uri": "https://[your-entity-search-app-name].azurewebsites.net/api/EntitySearch?code=[enter default host key here]",
"context": "/document/merged_content/organizations/*",
"inputs": [
{
"name": "name",
"source": "/document/merged_content/organizations/*"
}
],
"outputs": [
{
"name": "description",
"targetName": "description"
}
]
}
]
}
ここでは、組み込みのエンティティ認識スキルがスキルセットに存在すること、および組織のリストでエンリッチされたドキュメントがあることを想定しています。 参考のため、必要なデータを生成するために十分なエンティティ抽出スキルの構成を示します。
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"name": "#1",
"description": "Organization name extraction",
"context": "/document/merged_content",
"categories": [ "Organization" ],
"defaultLanguageCode": "en",
"inputs": [
{
"name": "text",
"source": "/document/merged_content"
},
{
"name": "languageCode",
"source": "/document/language"
}
],
"outputs": [
{
"name": "organizations",
"targetName": "organizations"
}
]
},
お疲れさまでした。 最初のカスタム スキルが作成されました。 これで同じパターンに従って、独自のカスタム機能を追加できます。 詳細については、以下のリンクをクリックしてください。
トレーニング
認定資格
Microsoft Certified: Azure AI Engineer Associate - Certifications
Azure AI サービス、Azure AI 検索、Azure Open AI を使用して Azure AI ソリューションを設計して実装します。
ドキュメント
カスタム スキルの拡張と管理 - Azure AI Search
カスタム スキルを効率的にスケールアウトしてスループットを最大限に高めるためのツールと手法について説明します。 カスタム スキルは、Azure AI Search で AI エンリッチされたインデックス作成パイプラインに追加できるカスタム AI モデルまたはロジックを呼び出します。
カスタム スキル インターフェイス - Azure AI Search
スキルセットで互換性のある入力と出力を定義する Web インターフェイスを使用して、Azure AI Search の AI エンリッチメント パイプラインとカスタム スキルを統合します。
スキルセット内のカスタム Web API スキル - Azure AI Search
Web API を呼び出すことによって、Azure AI Search スキルセットの機能を拡張します。 カスタム Web API スキルを使用してカスタム コードを統合します。