本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Neptune ML 中的 Gremlin 推論查詢
如 [Neptune ML 功能](machine-learning.md#machine-learning-capabilities) 中所述，Neptune ML 支援可以執行下列各種推論任務的訓練模型：
+ **節點分類** – 預測頂點屬性的類別特徵。
+ **節點迴歸** – 預測頂點的數值屬性。
+ **邊緣分類** – 預測邊緣屬性的類別特徵。
+ **邊緣迴歸** – 預測邊緣的數值屬性。
+ **連結預測** – 鑑於來源節點和傳出邊緣預測目的地節點，或鑑於目的地節點和傳入邊緣指定來源節點。
我們可以透過使用 [GroupLens Research](https://grouplens.org/datasets/movielens/) 所提供的 [MovieLens 100k 資料集](https://grouplens.org/datasets/movielens/100k/)的範例來說明這些不同的任務。此資料集由電影、使用者和使用者對電影的評分組成，我們從中建立了一個屬性圖，如下所示：
![\[使用 MovieLens 100k 資料集的範例影片屬性圖\]](http://docs.aws.amazon.com/zh_tw/neptune/latest/userguide/images/movie_property_graph_example.png)
**節點分類**：在上述資料集中，`Genre` 是由邊緣 `included_in` 連線至頂點類型 `Movie` 的頂點類型。但是，如果我們調整資料集，使 `Genre` 成為頂點類型 `Movie` 的[類別](https://en.wikipedia.org/wiki/Categorical_variable)特徵，則為新增至我們知識圖譜的新電影推斷 `Genre` 的問題可以使用節點分類模型來解決。
**節點迴歸**：如果我們考慮頂點類型 `Rating`，它具有 `timestamp` 和 `score` 等屬性，則為 `Rating` 推斷數值 `Score` 的問題可以使用節點迴歸模型來解決。
**邊緣分類**：同樣地，對於 `Rated` 邊緣，如果我們有一個屬性 `Scale` 可以具有 `Love`、`Like`、`Dislike`、`Neutral`、`Hate` 其中一個值，則為新電影/評分的 `Rated` 邊緣推斷 `Scale` 的問題可以使用邊緣分類模型來解決。
**邊緣迴歸**：同樣地，對於相同的 `Rated` 邊緣，如果我們有一個屬性 `Score` 保留評分的數值，則這可以從邊緣迴歸模型推斷出來。
**連結預測**：尋找最有可能對給定電影評分的前十名使用者，或尋找給定使用者最有可能評分的前十部電影之類的問題屬於連結預測。
**注意**
對於 Neptune ML 使用案例，我們有一組非常豐富的筆記本，旨在讓您實際了解每個使用案例。當您使用 Neptune [ML CloudFormation 範本建立 Neptune](machine-learning-quick-start.md) ML 叢集時，您可以建立這些筆記本和 Neptune 叢集。這些筆記本也可以在 [github](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/notebooks/04-Machine-Learning) 上取得。
**Topics**
+ [Gremlin 推論查詢中使用的 Neptune ML 述詞](machine-learning-gremlin-inference-query-predicates.md)
+ [Neptune ML 中的 Gremlin 節點分類查詢](machine-learning-gremlin-vertex-classification-queries.md)
+ [Neptune ML 中的 Gremlin 節點迴歸查詢](machine-learning-gremlin-vertex-regression-queries.md)
+ [Neptune ML 中的 Gremlin 邊緣分類查詢](machine-learning-gremlin-edge-classification-queries.md)
+ [Neptune ML 中的 Gremlin 邊緣迴歸查詢](machine-learning-gremlin-edge-regression.md)
+ [在 Neptune ML 中使用連結預測模型進行 Gremlin 連結預測查詢](machine-learning-gremlin-link-prediction-queries.md)
+ [Neptune ML Gremlin 推論查詢的例外狀況清單](machine-learning-gremlin-exceptions.md)
# Gremlin 推論查詢中使用的 Neptune ML 述詞
## `Neptune#ml.deterministic`
這個述詞是針對歸納推論查詢的選項，也就是，針對包含 [`Neptune#ml.inductiveInference`](#machine-learning-gremlin-inference-neptune-ml-inductiveInference) 述詞的查詢。
使用歸納推斷時，Neptune 引擎會建立適當的子圖來評估訓練後的 GNN 模型，而這個子圖的需求取決於最終模型的參數。尤其，`num-layer` 參數會決定來自目標節點或邊緣的周遊躍點數目，而 `fanouts` 參數則會指定要在每個躍點上取樣的鄰近項目數 (請參閱 [HPO 參數](machine-learning-customizing-hyperparams.md))。
根據預設，歸納推論查詢會在非確定性模式下執行，其中 Neptune 會隨機建置鄰域。在進行預測時，這種正常的隨機鄰近項目抽樣有時會導致不同的預測。
當您在歸納推論查詢中包含 `Neptune#ml.deterministic` 時，Neptune 引擎會嘗試以確定性的方式對鄰近項目進行取樣，以便相同查詢的多次調用，每次都會傳回相同的結果。不過，不能保證結果是完全確定的，因為對分散式系統的基礎圖形和成品的變更仍然可能會引起波動。
您可以在查詢中包含 `Neptune#ml.deterministic` 述詞，如下所示：
```
.with("Neptune#ml.deterministic")
```
如果包含 `Neptune#ml.deterministic` 述詞的查詢中未同時包含 `Neptune#ml.inductiveInference`，則只需將其忽略即可。
## `Neptune#ml.disableInductiveInferenceMetadataCache`
這個述詞是針對歸納推論查詢的選項，也就是，針對包含 [`Neptune#ml.inductiveInference`](#machine-learning-gremlin-inference-neptune-ml-inductiveInference) 述詞的查詢。
對於歸納推論查詢，Neptune 會使用儲存在 Amazon S3 中的中繼資料檔案，以在建立鄰域時決定躍點數和扇出數。Neptune 通常會快取此模型中繼資料，以避免重複從 Amazon S3 擷取檔案。可在查詢中包含 `Neptune#ml.disableInductiveInferenceMetadataCache` 述詞來停用快取。雖然 Neptune 直接從 Amazon S3 擷取中繼資料可能較慢，但當 SageMaker AI 端點在重新訓練或轉換後更新且快取過時時，此功能非常有用。
您可以在查詢中包含 `Neptune#ml.disableInductiveInferenceMetadataCache` 述詞，如下所示：
```
.with("Neptune#ml.disableInductiveInferenceMetadataCache")
```
以下是查詢範例在 Jupyter 筆記本中的可能樣子：
```
%%gremlin
g.with("Neptune#ml.endpoint", "ep1")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.with("Neptune#ml.disableInductiveInferenceMetadataCache")
.V('101').properties("rating")
.with("Neptune#ml.regression")
.with("Neptune#ml.inductiveInference")
```
## `Neptune#ml.endpoint`
`Neptune#ml.endpoint` 述詞會在 `with()` 步驟中用來指定推論端點 (如有必要)：
```
.with("Neptune#ml.endpoint", "the model's SageMaker AI inference endpoint")
```
您可以透過端點 `id` 或其 URL 來識別端點。例如：
```
.with( "Neptune#ml.endpoint", "node-classification-movie-lens-endpoint" )
```
或者：
```
.with( "Neptune#ml.endpoint", "https://runtime.sagemaker.us-east-1.amazonaws.com/endpoints/node-classification-movie-lens-endpoint/invocations" )
```
**注意**
如果您將 Neptune 資料庫叢集參數群組中的 [`neptune_ml_endpoint` 參數](machine-learning-cluster-setup.md#machine-learning-set-inference-endpoint-cluster-parameter)設定為端點 `id` 或 URL，則不需要在每個查詢中包含 `Neptune#ml.endpoint` 述詞。
## `Neptune#ml.iamRoleArn`
`Neptune#ml.iamRoleArn` 會視需要在`with()`步驟中使用，以指定 SageMaker AI 執行 IAM 角色的 ARN：
```
.with("Neptune#ml.iamRoleArn", "the ARN for the SageMaker AI execution IAM role")
```
如需如何建立 SageMaker AI 執行 IAM 角色的資訊，請參閱 [建立自訂 NeptuneSageMakerIAMRole 角色](machine-learning-manual-setup.md#ml-manual-setup-sm-role)。
**注意**
如果您在 Neptune 資料庫叢集參數群組中[將 `neptune_ml_iam_role` 參數](machine-learning-cluster-setup.md#machine-learning-enabling-create-param-group)設定為 SageMaker AI 執行 IAM 角色的 ARN，則不需要在每個查詢中包含`Neptune#ml.iamRoleArn`述詞。
## Neptune\$1ml.inductiveInference
預設會在 Gremlin 中啟用直推式推論。若要進行[即時直推式推論](machine-learning-overview-evolving-data.md#inductive-vs-transductive-inference)查詢，請包含如下 `Neptune#ml.inductiveInference` 述詞：
```
.with("Neptune#ml.inductiveInference")
```
如果您的圖形是動態的，歸納推論通常是最佳選擇，但是如果您的圖形是靜態的，則直推式推論更快、更有效率。
## `Neptune#ml.limit`
`Neptune#ml.limit` 述詞可以選擇性地限制每個實體傳回的結果數量：
```
.with( "Neptune#ml.limit", 2 )
```
根據預設，限制為 1，但可以設定的數量上限為 100。
## `Neptune#ml.threshold`
`Neptune#ml.threshold` 述詞可以選擇性地建立結果分數的截止閾值：
```
.with( "Neptune#ml.threshold", 0.5D )
```
這可讓您捨棄分數低於指定閾值的所有結果。
## `Neptune#ml.classification`
`Neptune#ml.classification` 述詞會連接到 `properties()` 步驟，以確定需要從節點分類模型的 SageMaker AI 端點擷取屬性：
```
.properties( "property key of the node classification model" ).with( "Neptune#ml.classification" )
```
## `Neptune#ml.regression`
`Neptune#ml.regression` 述詞會連接到 `properties()` 步驟，以確定需要從節點迴歸模型的 SageMaker AI 端點擷取屬性：
```
.properties( "property key of the node regression model" ).with( "Neptune#ml.regression" )
```
## `Neptune#ml.prediction`
`Neptune#ml.prediction` 述詞會附加到 `in()` 和 `out()` 步驟，以確定這是連結預測查詢：
```
.in("edge label of the link prediction model").with("Neptune#ml.prediction").hasLabel("target node label")
```
## `Neptune#ml.score`
`Neptune#ml.score` 述詞用於 Gemlin 節點或邊緣分類查詢中，以擷取機器學習可信度分數。`Neptune#ml.score` 述詞應該與 `properties()` 步驟中的查詢述詞一起傳遞，以取得節點或邊緣分類查詢的 ML 可信度分數。
您可以在節點分類區段中找到包含[其他節點分類範例](machine-learning-gremlin-vertex-classification-queries.md#machine-learning-gremlin-node-class-other-queries)的[節點分類範例，以及邊緣](machine-learning-gremlin-edge-classification-queries.md)分類範例。
# Neptune ML 中的 Gremlin 節點分類查詢
對於 Neptune ML 中的 Gremlin 節點分類：
+ 模型根據頂點的一個屬性進行訓練。這個屬性的唯一值集被稱為節點類別集，或者簡稱為類別。
+ 頂點屬性的節點類別屬性值可從節點分類模型中推斷出來。這在此屬性尚未附加至頂點時很有用。
+ 為了從節點分類模型中擷取一個或多個類別，您需要使用 `with()` 步驟搭配述詞 `Neptune#ml.classification` 來設定 `properties()` 步驟。如果輸出格式是頂點屬性，則輸出格式與您所期望的格式相似。
**注意**
節點分類僅會使用字串屬性值。這表示不支援數值屬性值 (例如 `0` 或 `1`)，儘管字串等同於 `"0"` 和 `"1"`。同樣地，布林屬性值 `true` 和 `false` 不起作用，但 `"true"` 和 `"false"` 可以。
以下是範例節點分類查詢：
```
g.with( "Neptune#ml.endpoint","node-classification-movie-lens-endpoint" )
.with( "Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role" )
.with( "Neptune#ml.limit", 2 )
.with( "Neptune#ml.threshold", 0.5D )
.V( "movie_1", "movie_2", "movie_3" )
.properties("genre").with("Neptune#ml.classification")
```
此查詢的輸出如下所示：
```
==>vp[genre->Action]
==>vp[genre->Crime]
==>vp[genre->Comedy]
```
在上述查詢中，`V()` 和 `properties()` 步驟的使用方式如下：
`V()` 步驟包含您要從節點分類模型中擷取其類別的頂點集：
```
.V( "movie_1", "movie_2", "movie_3" )
```
`properties()` 步驟包含模型訓練時根據的索引鍵，而且具有 `.with("Neptune#ml.classification")` 指示這是節點分類 ML 推論查詢。
`properties().with("Neptune#ml.classification")` 步驟中目前不支援多個內容索引鍵。例如，下列查詢會導致例外狀況：
```
g.with("Neptune#ml.endpoint", "node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V( "movie_1", "movie_2", "movie_3" )
.properties("genre", "other_label").with("Neptune#ml.classification")
```
如需特定錯誤訊息，請參閱 [Neptune ML 例外狀況清單](machine-learning-gremlin-exceptions.md)。
`properties().with("Neptune#ml.classification")` 步驟可與下列任一步驟搭配使用：
+ `value()`
+ `value().is()`
+ `hasValue()`
+ `has(value,"")`
+ `key()`
+ `key().is()`
+ `hasKey()`
+ `has(key,"")`
+ `path()`
## 其他節點分類查詢
如果推論端點和對應的 IAM 角色都已儲存在您的資料庫叢集參數群組中，則節點分類查詢可以簡單的如下所示：
```
g.V("movie_1", "movie_2", "movie_3").properties("genre").with("Neptune#ml.classification")
```
您可以使用 `union()` 步驟，在查詢中混合頂點屬性和類別：
```
g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V( "movie_1", "movie_2", "movie_3" )
.union(
properties("genre").with("Neptune#ml.classification"),
properties("genre")
)
```
您也可以建立無限制的查詢，如下所示：
```
g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V()
.properties("genre").with("Neptune#ml.classification")
```
您可以使用 `select()` 步驟搭配 `as()` 步驟來擷取節點類別以及頂點：
```
g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V( "movie_1", "movie_2", "movie_3" ).as("vertex")
.properties("genre").with("Neptune#ml.classification").as("properties")
.select("vertex","properties")
```
您也可以根據節點類別篩選，如下列範例所示：
```
g.with("Neptune#ml.endpoint", "node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V( "movie_1", "movie_2", "movie_3" )
.properties("genre").with("Neptune#ml.classification")
.has(value, "Horror")
g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V( "movie_1", "movie_2", "movie_3" )
.properties("genre").with("Neptune#ml.classification")
.has(value, P.eq("Action"))
g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V( "movie_1", "movie_2", "movie_3" )
.properties("genre").with("Neptune#ml.classification")
.has(value, P.within("Action", "Horror"))
```
您可以使用 `Neptune#ml.score` 述詞，取得節點分類可信度分數：
```
g.with("Neptune#ml.endpoint","node-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V( "movie_1", "movie_2", "movie_3" )
.properties("genre", "Neptune#ml.score").with("Neptune#ml.classification")
```
回應看起來像這樣：
```
==>vp[genre->Action]
==>vp[Neptune#ml.score->0.01234567]
==>vp[genre->Crime]
==>vp[Neptune#ml.score->0.543210]
==>vp[genre->Comedy]
==>vp[Neptune#ml.score->0.10101]
```
## 在節點分類查詢中使用歸納推論
假設您要在 Jupyter 筆記本中將新節點新增至現有圖形，如下所示：
```
%%gremlin
g.addV('label1').property(id,'101').as('newV')
.V('1').as('oldV1')
.V('2').as('oldV2')
.addE('eLabel1').from('newV').to('oldV1')
.addE('eLabel2').from('oldV2').to('newV')
```
您接著可以使用歸納推論查詢，取得反映了新節點的類型和可信度分數：
```
%%gremlin
g.with("Neptune#ml.endpoint", "nc-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.V('101').properties("genre", "Neptune#ml.score")
.with("Neptune#ml.classification")
.with("Neptune#ml.inductiveInference")
```
不過，如果您執行了多次查詢，則可能會得到有些不同的結果：
```
# First time
==>vp[genre->Action]
==>vp[Neptune#ml.score->0.12345678]
# Second time
==>vp[genre->Action]
==>vp[Neptune#ml.score->0.21365921]
```
你可以使相同的查詢具有確定性：
```
%%gremlin
g.with("Neptune#ml.endpoint", "nc-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.V('101').properties("genre", "Neptune#ml.score")
.with("Neptune#ml.classification")
.with("Neptune#ml.inductiveInference")
.with("Neptune#ml.deterministic")
```
在這種情況下，每次結果將大致相同：
```
# First time
==>vp[genre->Action]
==>vp[Neptune#ml.score->0.12345678]
# Second time
==>vp[genre->Action]
==>vp[Neptune#ml.score->0.12345678]
```
# Neptune ML 中的 Gremlin 節點迴歸查詢
節點迴歸類似於節點分類，不同之處在於從每個節點的迴歸模型推斷出的值是數值。您可以使用與節點分類相同的 Gremlin 查詢進行節點迴歸，但以下差異除外：
+ 同樣，在 Neptune ML 中，節點指的是頂點。
+ `properties()` 步驟接受形式 `properties().with("Neptune#ml.regression")` 而不是 `properties().with("Neptune#ml.classification")`。
+ `"Neptune#ml.limit`" 和 `"Neptune#ml.threshold"` 述詞不適用。
+ 根據值進行篩選時，您必須指定一個數值。
以下是範例頂點分類查詢：
```
g.with("Neptune#ml.endpoint","node-regression-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::0123456789:role/sagemaker-role")
.V("movie_1","movie_2","movie_3")
.properties("revenue").with("Neptune#ml.regression")
```
您可以根據使用迴歸模型推斷出的值進行篩選，如下列範例所示：
```
g.with("Neptune#ml.endpoint","node-regression-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("movie_1","movie_2","movie_3")
.properties("revenue").with("Neptune#ml.regression")
.value().is(P.gte(1600000))
g.with("Neptune#ml.endpoint","node-regression-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("movie_1","movie_2","movie_3")
.properties("revenue").with("Neptune#ml.regression")
.hasValue(P.lte(1600000D))
```
## 在節點迴歸查詢中使用歸納推論
假設您要在 Jupyter 筆記本中將新節點新增至現有圖形，如下所示：
```
%%gremlin
g.addV('label1').property(id,'101').as('newV')
.V('1').as('oldV1')
.V('2').as('oldV2')
.addE('eLabel1').from('newV').to('oldV1')
.addE('eLabel2').from('oldV2').to('newV')
```
然後，您可以使用歸納推論查詢，來取得考慮到新節點的評分：
```
%%gremlin
g.with("Neptune#ml.endpoint", "nr-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.V('101').properties("rating")
.with("Neptune#ml.regression")
.with("Neptune#ml.inductiveInference")
```
因為查詢不具確定性，所以如果根據鄰域多次執行該查詢，其可能會傳回有些不同的結果：
```
# First time
==>vp[rating->9.1]
# Second time
==>vp[rating->8.9]
```
如果需要更一致的結果，您可以使查詢具有確定性：
```
%%gremlin
g.with("Neptune#ml.endpoint", "nc-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.V('101').properties("rating")
.with("Neptune#ml.regression")
.with("Neptune#ml.inductiveInference")
.with("Neptune#ml.deterministic")
```
現在每次結果都會大致相同：
```
# First time
==>vp[rating->9.1]
# Second time
==>vp[rating->9.1]
```
# Neptune ML 中的 Gremlin 邊緣分類查詢
對於 Neptune ML 中的 Gremlin 邊緣分類：
+ 模型根據邊緣的一個屬性進行訓練。這個屬性的唯一值集被稱為類別集。
+ 邊緣的類別屬性值可從邊緣分類模型推斷出來，這在此屬性尚未附加至邊緣時很有用。
+ 為了從邊緣分類模型中擷取一個或多個類別，您需要使用 `with()` 步驟搭配述詞 `"Neptune#ml.classification"` 來設定 `properties()` 步驟。如果輸出格式是邊緣邊緣屬性，則輸出格式與您所期望的格式相似。
**注意**
邊緣分類僅會使用字串屬性值。這表示不支援數值屬性值 (例如 `0` 或 `1`)，儘管字串等同於 `"0"` 和 `"1"`。同樣地，布林屬性值 `true` 和 `false` 不起作用，但 `"true"` 和 `"false"` 可以。
以下是邊緣分類查詢的範例，其會使用 `Neptune#ml.score` 述詞請求可信度分數：
```
g.with("Neptune#ml.endpoint","edge-classification-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.E("relationship_1","relationship_2","relationship_3")
.properties("knows_by", "Neptune#ml.score").with("Neptune#ml.classification")
```
回應看起來像這樣：
```
==>p[knows_by->"Family"]
==>p[Neptune#ml.score->0.01234567]
==>p[knows_by->"Friends"]
==>p[Neptune#ml.score->0.543210]
==>p[knows_by->"Colleagues"]
==>p[Neptune#ml.score->0.10101]
```
## Gremlin 邊緣分類查詢的語法
對於簡單圖形，其中 `User` 是前端和尾端節點，且 `Relationship` 是連線它們的邊緣，範例邊緣分類查詢如下：
```
g.with("Neptune#ml.endpoint","edge-classification-social-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.E("relationship_1","relationship_2","relationship_3")
.properties("knows_by").with("Neptune#ml.classification")
```
此查詢的輸出如下所示：
```
==>p[knows_by->"Family"]
==>p[knows_by->"Friends"]
==>p[knows_by->"Colleagues"]
```
在上述查詢中，`E()` 和 `properties()` 步驟的使用方式如下：
+ `E()` 步驟包含您要從邊緣分類模型中擷取其類別的邊緣集：
```
.E("relationship_1","relationship_2","relationship_3")
```
+ `properties()` 步驟包含模型訓練時根據的索引鍵，而且具有 `.with("Neptune#ml.classification")` 指示這是邊緣分類 ML 推論查詢。
`properties().with("Neptune#ml.classification")` 步驟中目前不支援多個內容索引鍵。例如，下列查詢會導致擲出例外狀況：
```
g.with("Neptune#ml.endpoint","edge-classification-social-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.E("relationship_1","relationship_2","relationship_3")
.properties("knows_by", "other_label").with("Neptune#ml.classification")
```
如需特定錯誤訊息，請參閱 [Neptune ML Gremlin 推論查詢的例外狀況清單](machine-learning-gremlin-exceptions.md)。
`properties().with("Neptune#ml.classification")` 步驟可與下列任一步驟搭配使用：
+ `value()`
+ `value().is()`
+ `hasValue()`
+ `has(value,"")`
+ `key()`
+ `key().is()`
+ `hasKey()`
+ `has(key,"")`
+ `path()`
## 在邊緣分類查詢中使用歸納推論
假設您要在 Jupyter 筆記本中將新邊緣新增至現有圖形，如下所示：
```
%%gremlin
g.V('1').as('fromV')
.V('2').as('toV')
.addE('eLabel1').from('fromV').to('toV').property(id, 'e101')
```
然後，您可以使用歸納推論查詢，來取得考慮到新邊緣的範圍：
```
%%gremlin
g.with("Neptune#ml.endpoint", "ec-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.E('e101').properties("scale", "Neptune#ml.score")
.with("Neptune#ml.classification")
.with("Neptune#ml.inductiveInference")
```
因為查詢不具確定性，所以如果根據隨機鄰域多次執行該查詢，結果將會有些不同：
```
# First time
==>vp[scale->Like]
==>vp[Neptune#ml.score->0.12345678]
# Second time
==>vp[scale->Like]
==>vp[Neptune#ml.score->0.21365921]
```
如果需要更一致的結果，您可以使查詢具有確定性：
```
%%gremlin
g.with("Neptune#ml.endpoint", "ec-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.E('e101').properties("scale", "Neptune#ml.score")
.with("Neptune#ml.classification")
.with("Neptune#ml.inductiveInference")
.with("Neptune#ml.deterministic")
```
現在，每次執行查詢時，結果都會或多或少相同：
```
# First time
==>vp[scale->Like]
==>vp[Neptune#ml.score->0.12345678]
# Second time
==>vp[scale->Like]
==>vp[Neptune#ml.score->0.12345678]
```
# Neptune ML 中的 Gremlin 邊緣迴歸查詢
邊緣迴歸類似於邊緣分類，不同之處在於從 ML 模型推斷出的值是數值。對於邊緣迴歸，Neptune ML 支援與分類相同的查詢。
需要注意的要點如下：
+ 您必須使用 ML 述詞 `"Neptune#ml.regression"`，針對此使用案例設定 `properties()` 步驟。
+ `"Neptune#ml.limit"` 和 `"Neptune#ml.threshold"` 述詞不適用於此使用案例。
+ 如需根據值進行過濾，您需要將該值指定為數值。
## Gremlin 邊緣迴歸查詢的語法
對於簡單圖形，其中 `User` 是前端節點、`Movie` 是尾端節點，以及 `Rated` 是連接它們的邊緣，以下是一個範例邊緣迴歸查詢，其會尋找邊緣 `Rated` 的數值評分值，在這裡稱為分數：
```
g.with("Neptune#ml.endpoint","edge-regression-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.E("rating_1","rating_2","rating_3")
.properties("score").with("Neptune#ml.regression")
```
您也可以根據從 ML 迴歸模型推斷出的值進行篩選。對於由 `"rating_1"`、`"rating_2"` 和 `"rating_3"` 所識別的現有 `Rated` 邊緣 (從 `User` 到 `Movie`)，其中這些評分不存在邊緣屬性 `Score`，您可以使用如下查詢來推斷邊緣的 `Score`，其中它大於或等於 9：
```
g.with("Neptune#ml.endpoint","edge-regression-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.E("rating_1","rating_2","rating_3")
.properties("score").with("Neptune#ml.regression")
.value().is(P.gte(9))
```
## 在邊緣迴歸查詢中使用歸納推論
假設您要在 Jupyter 筆記本中將新邊緣新增至現有圖形，如下所示：
```
%%gremlin
g.V('1').as('fromV')
.V('2').as('toV')
.addE('eLabel1').from('fromV').to('toV').property(id, 'e101')
```
然後，您可以使用歸納推論查詢，來取得考慮到新邊緣的分數：
```
%%gremlin
g.with("Neptune#ml.endpoint", "er-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.E('e101').properties("score")
.with("Neptune#ml.regression")
.with("Neptune#ml.inductiveInference")
```
因為查詢不具確定性，所以如果根據隨機鄰域多次執行該查詢，結果將會有些不同：
```
# First time
==>ep[score->96]
# Second time
==>ep[score->91]
```
如果需要更一致的結果，您可以使查詢具有確定性：
```
%%gremlin
g.with("Neptune#ml.endpoint", "er-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.E('e101').properties("score")
.with("Neptune#ml.regression")
.with("Neptune#ml.inductiveInference")
.with("Neptune#ml.deterministic")
```
現在，每次執行查詢時，結果都會或多或少相同：
```
# First time
==>ep[score->96]
# Second time
==>ep[score->96]
```
# 在 Neptune ML 中使用連結預測模型進行 Gremlin 連結預測查詢
連結預測模型可以解決如下問題：
+ **前端節點預測**：鑑於頂點和邊緣類型，該頂點可能從哪些頂點連結？
+ **尾端節點預測**：鑑於頂點和邊緣標籤，該頂點可能連結至哪些頂點？
**注意**
Neptune ML 中尚未支援邊緣預測。
對於下面範例，考慮其中頂點 `User` 和 `Movie` 是由邊緣 `Rated` 連結的簡單圖形。
以下是範例前端節點預測查詢，用來預測最有可能評分電影 (`"movie_1"`、`"movie_2"` 和 `"movie_3"`) 的前五名使用者：
```
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.with("Neptune#ml.limit", 5)
.V("movie_1", "movie_2", "movie_3")
.in("rated").with("Neptune#ml.prediction").hasLabel("user")
```
以下是用於尾端節點預測的類似查詢，用來預測使用者 `"user_1"` 可能評分的前五名電影：
```
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("user_1")
.out("rated").with("Neptune#ml.prediction").hasLabel("movie")
```
邊緣標籤和預測的頂點標籤都是必要的。如果省略其中一個，則會擲出例外狀況。例如，以下查詢沒有預測的頂點標籤，其會擲回例外狀況：
```
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("user_1")
.out("rated").with("Neptune#ml.prediction")
```
同樣地，沒有邊緣標籤的下列查詢也會擲回例外狀況：
```
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("user_1")
.out().with("Neptune#ml.prediction").hasLabel("movie")
```
如需這些例外狀況傳回的特定錯誤訊息，請參閱 [Neptune ML 例外狀況清單](machine-learning-gremlin-exceptions.md)。
## 其他連結預測查詢
您可以使用 `select()` 步驟搭配 `as(`) 步驟，以同時輸出預測的頂點與輸入頂點：
```
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("movie_1").as("source")
.in("rated").with("Neptune#ml.prediction").hasLabel("user").as("target")
.select("source","target")
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("user_1").as("source")
.out("rated").with("Neptune#ml.prediction").hasLabel("movie").as("target")
.select("source","target")
```
您可以進行無限制查詢，如下所示：
```
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("user_1")
.out("rated").with("Neptune#ml.prediction").hasLabel("movie")
g.with("Neptune#ml.endpoint","node-prediction-movie-lens-endpoint")
.with("Neptune#ml.iamRoleArn","arn:aws:iam::0123456789:role/sagemaker-role")
.V("movie_1")
.in("rated").with("Neptune#ml.prediction").hasLabel("user")
```
## 在連結預測查詢中使用歸納推論
假設您要在 Jupyter 筆記本中將新節點新增至現有圖形，如下所示：
```
%%gremlin
g.addV('label1').property(id,'101').as('newV1')
.addV('label2').property(id,'102').as('newV2')
.V('1').as('oldV1')
.V('2').as('oldV2')
.addE('eLabel1').from('newV1').to('oldV1')
.addE('eLabel2').from('oldV2').to('newV2')
```
然後，您可以使用歸納推論查詢來預測前端節點，同時考慮到新節點：
```
%%gremlin
g.with("Neptune#ml.endpoint", "lp-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.V('101').out("eLabel1")
.with("Neptune#ml.prediction")
.with("Neptune#ml.inductiveInference")
.hasLabel("label2")
```
結果：
```
==>V[2]
```
同樣地，您可以使用歸納推論查詢來預測尾端節點，同時考慮到新節點：
```
%%gremlin
g.with("Neptune#ml.endpoint", "lp-ep")
.with("Neptune#ml.iamRoleArn", "arn:aws:iam::123456789012:role/NeptuneMLRole")
.V('102').in("eLabel2")
.with("Neptune#ml.prediction")
.with("Neptune#ml.inductiveInference")
.hasLabel("label1")
```
結果：
```
==>V[1]
```
# Neptune ML Gremlin 推論查詢的例外狀況清單
這是執行 Neptune ML Gremlin 推論查詢時可能發生的例外狀況完整清單。這些例外狀況涵蓋一系列問題，從指定 IAM 角色或端點的問題，到每個查詢的 ML 推論查詢數量不受支援的 Gremlin 步驟和限制。每個項目都包含描述問題的詳細訊息。
+ **`BadRequestException`** – 無法載入所提供角色的憑證。
*訊息*：`Unable to load credentials for role: the specified IAM Role ARN.`
+ **`BadRequestException`** – 指定的 IAM 角色無權叫用 SageMaker AI 端點。
*訊息*：`User: the specified IAM Role ARN is not authorized to perform: sagemaker:InvokeEndpoint on resource: the specified endpoint.`
+ **`BadRequestException`** – 指定的端點不存在。
*訊息*：`Endpoint the specified endpoint not found.`
+ **`InternalFailureException`** – 無法從 Amazon S3 擷取 Neptune ML 即時歸納推論中繼資料。
*訊息*：`Unable to fetch Neptune ML - Real-Time Inductive Inference metadata from S3. Check the permissions of the S3 bucket or if the Neptune instance can connect to S3.`
+ **`InternalFailureException`** – Neptune ML 無法在 Amazon S3 中找到用於即時歸納推論的中繼資料檔案。
*訊息*：`Neptune ML cannot find the metadata file for Real-Time Inductive Inference in S3.`
+ **`InvalidParameterException`** – 指定的端點在語法上無效。
*訊息*：`Invalid endpoint provided for external service query.`
+ **`InvalidParameterException`** – 指定的 SageMaker 執行 IAM 角色 ARN 在語法上無效。
*訊息*：`Invalid IAM role ARN provided for external service query.`
+ **`InvalidParameterException`** – 在查詢的 `properties()` 步驟中指定多個屬性索引鍵。
*訊息*：`ML inference queries are currently supported for one property key.`
+ **`InvalidParameterException`** – 在查詢中指定多個邊緣標籤。
*訊息*：`ML inference are currently supported only with one edge label.`
+ **`InvalidParameterException`** – 在查詢中指定多個頂點標籤限制條件。
*訊息*：`ML inference are currently supported only with one vertex label constraint.`
+ **`InvalidParameterException`** – `Neptune#ml.classification` 和 `Neptune#ml.regression` 述詞都存在於相同的查詢中。
*訊息*：`Both regression and classification ML predicates cannot be specified in the query.`
+ **`InvalidParameterException`** – 已在連結預測查詢的 `in()` 或 `out()` 步驟中指定多個邊緣標籤。
*訊息*：`ML inference are currently supported only with one edge label.`
+ **`InvalidParameterException`** – 已使用 Neptune\$1ml.score 指定多個屬性索引鍵。
*訊息*：`Neptune ML inference queries are currently supported for one property key and one Neptune#ml.score property key.`
+ **`MissingParameterException`** – 未在查詢中指定端點，或未將其指定為資料庫叢集參數。
*訊息*：`No endpoint provided for external service query.`
+ **``MissingParameterException** – 未在查詢中指定 SageMaker AI 執行 IAM 角色，或將其指定為資料庫叢集參數。
*訊息*：`No IAM role ARN provided for external service query.`
+ **`MissingParameterException`** – 查詢中的 `properties()` 步驟遺失內容索引鍵。
*訊息*：`Property key needs to be specified using properties() step for ML inference queries.`
+ **`MissingParameterException`** – 未在連結預測查詢的 `in()` 或 `out()` 步驟中指定任何邊緣標籤。
*訊息*：`Edge label needs to be specified while using in() or out() step for ML inference queries.`
+ **`MissingParameterException`** – 未使用 Neptune\$1ml.score 指定屬性索引鍵。
*訊息*：`Property key needs to be specified along with Neptune#ml.score property key while using the properties() step for Neptune ML inference queries.`
+ **`UnsupportedOperationException`** – `both()` 步驟用於連結預測查詢中。
*訊息*：`ML inference queries are currently not supported with both() step.`
+ **`UnsupportedOperationException`** – 未在 `has()` 步驟以及連結預測查詢中的 `in()` 或 `out()` 步驟中指定預測的頂點標籤。
*訊息*：`Predicted vertex label needs to be specified using has() step for ML inference queries.`
+ **`UnsupportedOperationException`** – 未最佳化的步驟目前不支援 Gremlin ML 歸納推論查詢。
*訊息*：`Neptune ML - Real-Time Inductive Inference queries are currently not supported with Gremlin steps which are not optimized for Neptune. Check the Neptune User Guide for a list of Neptune-optimized steps.`
+ **`UnsupportedOperationException`** – `repeat` 步驟內目前不支援 Neptune ML 推論查詢。
*訊息*：`Neptune ML inference queries are currently not supported inside a repeat step.`
+ **`UnsupportedOperationException`** – 每個 Grinlin 查詢目前不支援多個 Neptune ML 推論查詢。
*訊息*：`Neptune ML inference queries are currently supported only with one ML inference query per gremlin query.`