
This add-on is operated by Salesforce
Build smarter apps with image recognition and natural language processing
Einstein Vision および Language
この記事の英語版に更新があります。ご覧の翻訳には含まれていない変更点があるかもしれません。
最終更新日 2022年10月06日(木)
This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.
Table of Contents
Einstein Vision および Einstein Language API は Salesforce Einstein テクノロジスイートの一部であり、これらを使用してアプリを AI 対応にすることができます。Einstein Vision API を使用すると、事前にトレーニングされた分類子を利用したり、さまざまな特殊な画像認識ユースケースを解決するように独自のカスタム分類子をトレーニングしたりできます。Einstein Language API を使用すると、強力な自然言語処理機能を利用してテキストを分析し、そのテキストの背後にある感情または意図を推論できます。
アドオンのプロビジョニング
アプリの Einstein Platform Services アドオンは、CLI を使用してプロビジョニングできます。
$ heroku addons:create einstein-vision:starter --app coral-brook-39111
Creating einstein-vision:starter on ⬢ coral-brook-39111... free
選択可能なすべてのプランのリストはここから見つけることができます。
Einstein Platform Services の認証
アドオンをインストールすると、次の環境設定が使用可能になります。
EINSTEIN_VISION_ACCOUNT_ID
- アカウント ID。EINSTEIN_VISION_PRIVATE_KEY
- PEM 形式の RSA キー。EINSTEIN_VISION_URL
- Einstein Vision および Einstein Language API エンドポイント。
これらの変数の値は、heroku config:get
コマンドを使用して表示できます。
$ heroku config:get EINSTEIN_VISION_ACCOUNT_ID
heroku@famj5Uu91v6ByMC85f1aCfqJg1484200000000
$ heroku config:get EINSTEIN_VISION_PRIVATE_KEY
-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAze8Dh6o66ThPZz7 ...
...
-----END RSA PRIVATE KEY-----
$ heroku config:get EINSTEIN_VISION_URL
https://api.einstein.ai/
認証フロー
Einstein Platform Services API は、OAuth 2.0 認証を使用します。各 API 呼び出しでは、有効な OAuth アクセストークンを渡す必要があります。
アプリでは、OAuth アクセストークンの署名された JWT (JSON Web トークン) を交換するコードを追加する必要があります。すばやく開始するには、このトークン生成ページを使用して、コードなしで一時的なトークンを生成できます。
トークンを取得する手順
トークンを取得するためにコードで従う高レベルの手順を次に示します。コードの詳細は、使用している言語によって異なります。
- 秘密鍵を使用して JWT に署名してアサーションを作成します。
- JWT アサーションを
/v2/oauth2/token
API に送信することによってアクセストークンをリクエストします。 - そのアクセストークンを
Authorization
リクエストヘッダーで使用して API 呼び出しを行います。
JWT ペイロードの例:
{
"sub": "$EINSTEIN_VISION_ACCOUNT_ID",
"aud": "https://api.einstein.ai/v2/oauth2/token",
"exp": $EXPIRY_UNIX_TIME_IN_SECONDS
}
exp
: UNIX 時間での有効期限。この値は、現在の UNIX 時間 (秒数) とトークンを有効にする秒数の合計です。JWT ペイロードでは、トークンが有効になってからトークンが期限切れになるまでの時間を設定します。現在のトークンが期限切れになったら、新しいトークンを生成する必要があります。
JWT ライブラリ、カスタムコード、またはこのトークン生成ページのいずれかを使用して、RSA 秘密鍵の環境設定 EINSTEIN_VISION_PRIVATE_KEY
を使用して JWT ペイロードに署名して JWT アサーションを生成します。
アクセストークンの交換のための JWT の例
OAuth トークン生成リソース https://api.einstein.ai/v2/oauth2/token
を使用して、JWT アサーションを使用して JWT トークンを生成します。
$ curl -H "Content-type: application/x-www-form-urlencoded" \
-X POST https://api.einstein.ai/v2/oauth2/token \
-d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=eyJhOiJSU ..."
{
"access_token": "4f4c5a29a284920dcd43700dcc56c0ff2e2e2cb5",
"token_type": "Bearer",
"expires_in": 900
}
詳細は、OAuth トークンの API ドキュメントを参照してください。
各 API 呼び出しを認証するには、API リクエストヘッダーでトークンを設定する必要があります。Authorization: Bearer <TOKEN>
のヘッダー値を使用してください。
API 呼び出しの例
この cURL コマンドは、すべてのデータセットの一覧を返します。
$ curl -X GET \
-H "Authorization: Bearer 4f4c5a29a284920dcd43700dcc56c0ff2e2e2cb5" \
https://api.einstein.ai/v2/vision/datasets
{
"object": "list",
"data": [
{
"id": 24,
"name": "Beach and Mountain",
"createdAt": "2016-09-09T22:39:22.000+0000",
"updatedAt": "2016-09-09T22:39:22.000+0000",
"labelSummary": {
"labels": [
{
"id": 37,
"datasetId": 24,
"name": "beach",
"numExamples": 49
},
{
"id": 36,
"datasetId": 24,
"name": "mountain",
"numExamples": 50
}
]
},
"totalExamples": 99,
"totalLabels": 2,
"available": true,
"statusMsg": "SUCCEEDED",
"type": "image",
"object": "dataset"
},
{
"id": 25,
"name": "Brain Scans",
"createdAt": "2016-08-24T21:35:27.000+0000",
"updatedAt": "2016-08-24T21:35:27.000+0000",
"totalExamples": 0,
"totalLabels": 0,
"available": true,
"statusMsg": "SUCCEEDED",
"type": "image",
"object": "dataset"
}
]
}
Ruby でトークンを生成する
Ruby アプリケーションでトークンを生成するには、Gemfile
に jwt
および rest-client
gem を含めます。
gem 'jwt'
gem 'rest-client', '~> 1.8'
bundle install
を実行して、すべての依存関係をダウンロードして解決します。
トークンを生成する
require 'jwt'
require 'rest-client'
require 'json'
ps_endpoint = ENV['EINSTEIN_VISION_URL']
subject = ENV['EINSTEIN_VISION_ACCOUNT_ID']
private_key = String.new(ENV['EINSTEIN_VISION_PRIVATE_KEY'])
private_key.gsub!('\n', "\n")
expiry = Time.now.to_i + (60 * 15)
# Read the private key string as Ruby RSA private key
rsa_private = OpenSSL::PKey::RSA.new(private_key)
# Build the JWT payload
payload = {
:sub => subject,
:aud => "https://api.einstein.ai/v2/oauth2/token",
:exp => expiry
}
# Sign the JWT payload
assertion = JWT.encode payload, rsa_private, 'RS256'
puts assertion
# Call the OAuth endpoint to generate a token
response = RestClient.post(ps_endpoint + 'v2/oauth2/token', {
grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
assertion: assertion
})
token_json = JSON.parse(response)
puts "\nGenerated access token:\n"
puts JSON.pretty_generate(token_json)
access_token = token_json["access_token"]
ここにあるサンプルの Ruby アプリを参照してください。
Java でトークンを生成する
Java アプリケーションでトークンを生成するには、pom.xml
に次の依存関係を追加します。
<dependency>
<groupId>org.bitbucket.b_c</groupId>
<artifactId>jose4j</artifactId>
<version>0.5.4</version>
</dependency>
<dependency>
<groupId>commons-codec</groupId>
<artifactId>commons-codec</artifactId>
<version>1.9</version>
</dependency>
<dependency>
<groupId>org.glassfish.jersey.core</groupId>
<artifactId>jersey-client</artifactId>
<version>2.25</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.8.5</version>
</dependency>
mvn install
を実行して、すべての依存関係をダウンロードして解決します。
トークンを生成する
EINSTEIN_VISION_PRIVATE_KEY
環境設定の値を java PrivateKey
オブジェクトに読み取ります。
/**
* Extracts private key from EINSTEIN_VISION_PRIVATE_KEY contents
*/
private static PrivateKey getPrivateKey() {
String privateKeyBase64 = System.getenv("EINSTEIN_VISION_PRIVATE_KEY");
String privKeyPEM = privateKeyBase64.replace("-----BEGIN RSA PRIVATE KEY-----\n", "");
privKeyPEM = privKeyPEM.replace("\n-----END RSA PRIVATE KEY-----", "");
// Base64 decode the data
byte[] encoded = Base64.decodeBase64(privKeyPEM);
try {
DerInputStream derReader = new DerInputStream(encoded);
DerValue[] seq = derReader.getSequence(0);
if (seq.length < 9) {
throw new GeneralSecurityException("Could not read private key");
}
// skip version seq[0];
BigInteger modulus = seq[1].getBigInteger();
BigInteger publicExp = seq[2].getBigInteger();
BigInteger privateExp = seq[3].getBigInteger();
BigInteger primeP = seq[4].getBigInteger();
BigInteger primeQ = seq[5].getBigInteger();
BigInteger expP = seq[6].getBigInteger();
BigInteger expQ = seq[7].getBigInteger();
BigInteger crtCoeff = seq[8].getBigInteger();
RSAPrivateCrtKeySpec keySpec = new RSAPrivateCrtKeySpec(modulus, publicExp,
privateExp, primeP, primeQ, expP, expQ, crtCoeff);
KeyFactory factory = KeyFactory.getInstance("RSA");
return factory.generatePrivate(keySpec);
} catch (IOException | GeneralSecurityException e) {
// Handle failures
}
return null;
}
PrivateKey
を使用して JWT アサーションを生成します。
/**
* Generate JWT assertion
*/
public static String generateJWTAssertion(float expiryInSeconds) {
String email = System.getenv("EINSTEIN_VISION_ACCOUNT_ID");
PrivateKey privateKey = getPrivateKey();
final JwtClaims claims = new JwtClaims();
claims.setSubject(email);
claims.setAudience("https://api.einstein.ai/v2/oauth2/token");
claims.setExpirationTimeMinutesInTheFuture(expiryInSeconds / 60);
claims.setIssuedAtToNow();
// Generate the payload
final JsonWebSignature jws = new JsonWebSignature();
jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.RSA_USING_SHA256);
jws.setPayload(claims.toJson());
jws.setKeyIdHeaderValue(UUID.randomUUID().toString());
// Sign using the private key
jws.setKey(privateKey);
try {
return jws.getCompactSerialization();
} catch (JoseException e) {
return null;
}
}
OAuth エンドポイントを呼び出してトークンを生成します。
/**
* Obtain an access token
*/
public static void main(String args[]) {
String assertion = generateJWTAssertion(60 * 15);
Form form = new Form();
form.param("assertion", assertion);
form.param("grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer");
Entity<Form> entity = Entity.form(form);
String endpoint = System.getenv("EINSTEIN_VISION_URL");
Response response = client.target(endpoint + "v2/oauth2/token")
.request()
.post(entity);
try {
ObjectMapper mapper = new ObjectMapper();
JsonNode responseJson = mapper.readValue(response.readEntity(InputStream.class), JsonNode.class);
System.out.println(responseJson);
} finally {
response.close();
}
}
ここにあるサンプルの Java アプリを参照してください。
Node.js でトークンを生成する
Node.js アプリケーションでトークンを生成するには、package.json
に jsonwebtoken
を含めます。
"dependencies": {
"jsonwebtoken": "^7.1.9",
"request": "^2.78.0"
}
トークンを生成する
var jwt = require('jsonwebtoken');
var request = require('request');
var url = process.env.EINSTEIN_VISION_URL
var private_key = process.env.EINSTEIN_VISION_PRIVATE_KEY
var account_id = process.env.EINSTEIN_VISION_ACCOUNT_ID
var reqUrl = `${url}v2/oauth2/token`;
// JWT payload
var rsa_payload = {
"sub":account_id,
"aud":reqUrl
}
var rsa_options = {
header:{
"alg":"RS256",
"typ":"JWT"
},
expiresIn: '1h'
}
// Sign the JWT payload
var assertion = jwt.sign(
rsa_payload,
private_key,
rsa_options
);
var options = {
url: reqUrl,
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
'accept': 'application/json'
},
body:`grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=${encodeURIComponent(assertion)}`
}
// Make the OAuth call to generate a token
request.post(options, function(error, response, body) {
var data = JSON.parse(body);
console.log(data["access_token"]);
});
サンプルコード
次のコードサンプルを参照して、サービスの起動と実行に役立ててください。
- Node.js
- Heroku にデプロイできる Web アプリ
- 画像をアップロードし、予測を戻してもらう
GeneralImageClassifier
モデルを使用する
- Java
- Python
- Ruby
カスタムモデルを共有する
カスタムのトレーニングされたモデルを含むアドオンを各アプリにアタッチすることによって、そのアドオンを複数のアプリ間で共有します。
# First, fetch the `einstein-vision` add-on identifier from the original app.
$ heroku addons --app $APP_NAME
# Then, attach that add-on to another app.
$ heroku addons:attach $ADD_ON_IDENTIFIER --app $OTHER_APP_NAME
# Finally, configure the custom model ID on the other app.
# (This may take a different form for a different app; we recommend using the `CUSTOM_MODEL_ID` env var.)
$ heroku config:set CUSTOM_MODEL_ID=$MODEL_ID --app $OTHER_APP_NAME
Einstein Vision および Language のアドオンが作成された場合は、そのアドオンによって新しい Einstein Platform Services アカウントが取得されます。カスタムモデルが作成されると、それらはそのアカウントにスコープ指定されます。これらのモデルを共有するには、そのアドオンを複数のアプリにアタッチできます。
プラン間の移行
新しいプランに移行するには、heroku addons:upgrade
コマンドを使用します。
プランを変更する場合は、関連付けられている速度制限に注意してください。
$ heroku addons:upgrade einstein-vision:basic
Changing einstein-vision-curved-87707 on coral-brook-39111 from ... done
アドオンの削除
Einstein Vision および Language のアドオンは、CLI を使用して削除できます。
これにより、関連付けられているデータセットとモデルがすべて破棄され、元に戻すことはできません。
$ heroku addons:destroy einstein-vision
Destroying einstein-vision-transparent-56474 on ⬢ coral-brook-39111... done
サポート
Einstein Vision および Language のアドオンの使用中に何らかの問題が発生した場合やサポートが必要な場合は、Heroku サポートチャネルを使用してください。
追加リソース
Einstein Platform Services API のドキュメントは、ここ にあります。
Einstein.ai API サービス利用規約
Einstein.ai サービスの利用者による使用は、サービス利用規約 http://www.sfdcstatic.com/assets/pdf/misc/salesforce_MSA.pdf (“MSA”) と、ここで参照により MSA に組み込まれている次の補足条項に従います。 ここで定義されていない大文字の用語は、MSA でそれらに与えられている意味を持つものとします。
補足条項: “Einstein.ai API” は、https://api.einstein.ai でアクセス可能な API エンドポイントを意味します。 “Einstein.ai サービス” は、Einstein Vision および Language サービス、または Einstein.ai API 経由で利用者によってアクセスされるその他のすべての関連付けられたオンラインサービス用の Einstein.ai API を意味します。 “予測” は、予測の生成という目的を持つサービスへの API 呼び出しを意味します。 “ベータサービス” は、ベータ、パイロット、制限されたリリース、開発者プレビュー、非本番、評価として、または同様の説明によって明確に指定されている、追加料金なしでオプションで試すために顧客に対して使用可能にできる SFDC サービスまたは機能を意味します。
利用者は、SFDC が Einstein.ai サービスに送信された利用者のデータに、Einstein.ai サービスおよび SFDC の現在と将来のその他のすべての同様の、または関連する機能、製品やサービスの開発および改善の目的でアクセスできることを確認します。
利用者は、Einstein.ai サービスに送信されたすべての画像、テキスト、音声やその他のデータの利用者の収集、使用、処理、および保持において適用されるすべての法律および規制に従い、かつ利用者が Einstein.ai サービスに送信したすべての画像、テキスト、音声やその他のデータを使用、処理、および保持するために必要なすべての同意を得ており、すべての通知を提供している (該当する場合は、プライバシーポリシーでの明確な開示によるものを含む) ことをここで表明および保証するものとします。
機密の個人データを Einstein.ai サービスに送信してはなりません。これには、政府が発行した ID 番号を含むか、または公開する画像、テキスト、音声などのデータ、財務情報 (クレジットまたはデビットカード番号、関連するセキュリティコードまたはパスワード、銀行口座番号など)、人種または民族的出自、政治的な信念、宗教的または哲学的な信条、労働組合への加入状況、健康または性生活に関する情報、個人の物理的または精神的な健康に関連した情報、および健康管理の備えまたは支払いに関連した情報が含まれます。 さらに、利用者は Einstein.ai サービスを使用して、顔紋や指紋、または眼、手、顔面形状のスキャンなどのバイオメトリック識別子を作成または分析してはならず、また利用者は、誰かの人種または民族的出自、政治的な信念、宗教的または哲学的な信条、労働組合への加入状況、年齢、性別、性生活、性的指向、有罪判決、身体傷害、健康状態、または病状の分析、プロファイリング、または対象設定の目的に Einstein.ai サービスを使用してはなりません。
追加条項: Einstein Vision および Language の有料ユーザーの場合のみ、Einstein.ai サービスの利用者による使用には暦月あたり 2,000 の予測が含まれるという条項も適用されます。利用者は、上記の制限が本質的に契約である (つまり、サービスにおいて技術的な事項として制限されない) ことを理解し、そのため利用者は、サービスの利用者による使用を厳密にレビューして上記で規定された制限に従うことに同意します。SFDC は、サービスの利用者による使用をサービスを通していつでもレビューできます。未使用の予測は各暦月の最後に失われ、以降の暦月に持ち越されることはありません。各暦月の開始と終了は UTC 時間に従います。
Einstein Vision および Language の無料ユーザーの場合のみ、Einstein.ai サービスの利用者による使用には暦月あたり 2,000 の無料予測が含まれるという条項も適用されます。SFDC は、データベースのサイズ、利用者がトレーニングできるモデルの数、および Einstein.ai API への利用者の一般的なアクセスを制限する権利を留保します。未使用の予測は各暦月の最後に失われ、以降の暦月に持ち越されることはありません。各暦月の開始と終了は UTC 時間に従います。
当社は、これらの Einstein.ai API サービス利用規約をいつでも更新できます。当社は、これらの条項への変更の通知をこのページにポストします。 当社はまた、たとえばサービス通知や、Salesforce または Heroku アカウントに関連付けられたメールアドレスへのメール経由で資料のリビジョンを通知することもできます。 Einstein.ai サービスの利用者の継続的な使用は、更新された条項に利用者が同意することを意味します。更新された条項に同意しない場合は、Einstein.ai API の使用を停止する必要があります。
2017 年 6 月 28 日から有効