本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 功能儲存範例筆記本簡介
<a name="feature-store-introduction-notebook"></a>

**重要**  
允許 Amazon SageMaker Studio 或 Amazon SageMaker Studio Classic 建立 Amazon SageMaker 資源的自訂 IAM 政策也必須授與許可，才能將標籤新增至這些資源。需要將標籤新增至資源的許可，因為 Studio 和 Studio Classic 會自動標記它們建立的任何資源。如果 IAM 政策允許 Studio 和 Studio Classic 建立資源，但不允許標記，則在嘗試建立資源時可能會發生 "AccessDenied" 錯誤。如需詳細資訊，請參閱[提供標記 SageMaker AI 資源的許可](security_iam_id-based-policy-examples.md#grant-tagging-permissions)。  
提供許可來建立 SageMaker 資源的 [AWS Amazon SageMaker AI 的 受管政策](security-iam-awsmanpol.md) 已包含建立這些資源時新增標籤的許可。

此頁面上的範例程式碼是指[特徵商店簡介](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-featurestore/feature_store_introduction.html)範例筆記本。建議您在 Studio Classic、筆記本執行個體或 JupyterLab 中執行此筆記本，因為本指南中的程式碼是概念性的，而且若複製，無法完全運作。

使用下列項目複製 [aws/amazon-sagemaker-examples](https://github.com/aws/amazon-sagemaker-examples) GitHub 儲存庫，其中包含範例筆記本：
+ **針對 Studio Classic**

  啟動 Studio Classic。如果 Studio 或 Studio Classic 已啟用做為您的預設體驗，則您可以開啟 Studio Classic。如需如何開啟 Studio Classic 的指示，請參閱[使用 Amazon SageMaker AI 主控台啟動 Amazon SageMaker Studio Classic](studio-launch.md#studio-launch-console)。

  遵循 [複製 Amazon SageMaker Studio Classic 中的 Git 儲存庫](studio-tasks-git.md) 中的步驟，將 [aws/amazon-sagemaker-examples](https://github.com/aws/amazon-sagemaker-examples) GitHub 儲存庫複製到 Studio Classic。
+ **針對 Amazon SageMaker 筆記本執行個體**

  遵循[存取筆記本執行個體](howitworks-access-ws.md)中的指示啟動 SageMaker 筆記本執行個體。

現在您有 SageMaker AI 範例筆記本，請導覽至 `amazon-sagemaker-examples/sagemaker-featurestore` 目錄並開啟 [Feature Store 簡介](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-featurestore/feature_store_introduction.html)範例筆記本。

## 步驟 1：設定 SageMaker AI 工作階段
<a name="feature-store-setup"></a>

若要開始使用 Feature Store，請建立 SageMaker AI 工作階段。然後，設定您要用於功能的 Amazon Simple Storage Service (Amazon S3) 儲存貯體。Amazon S3 儲存貯體是您的離線儲存。下列程式碼會使用 SageMaker AI 預設儲存貯體，並將自訂字首新增至其中。

**注意**  
您用來執行筆記本的角色必須附加下列受管的政策：`AmazonS3FullAccess` 和 `AmazonSageMakerFeatureStoreAccess`。如需將政策新增至 IAM 角色的相關資訊，請參閱 [將政策新增至您的 IAM 角色](feature-store-adding-policies.md)。

```
# SageMaker Python SDK version 2.x is required
import sagemaker
import sys
```

```
import boto3
import pandas as pd
import numpy as np
import io
from sagemaker.session import Session
from sagemaker import get_execution_role

prefix = 'sagemaker-featurestore-introduction'
role = get_execution_role()

sagemaker_session = sagemaker.Session()
region = sagemaker_session.boto_region_name
s3_bucket_name = sagemaker_session.default_bucket()
```

## 步驟 2：檢查資料
<a name="feature-store-load-datasets"></a>

在此筆記本範例中，我們會從託管完整筆記本的 [Github 儲存庫](https://github.com/aws/amazon-sagemaker-examples/tree/master/sagemaker-featurestore/data)中擷取合成資料。

```
customer_data = pd.read_csv("data/feature_store_introduction_customer.csv")
orders_data = pd.read_csv("data/feature_store_introduction_orders.csv")

print(customer_data.head())
print(orders_data.head())
```

下圖說明了資料在 Feature Store 擷取它之前所經歷的步驟。在本筆記本中，我們說明了您擁有來自多個來源的資料，並想要將其獨立存放在 Feature Store 中的使用案例。我們的範例會考量來自資料倉儲 (客戶資料) 的資料，以及來自即時串流服務 (訂單資料) 的資料。

![\[在 Feature Store 中為此範例筆記本進行特徵群組建立和資料擷取。\]](http://docs.aws.amazon.com/zh_tw/sagemaker/latest/dg/images/feature-store/feature-store-intro-diagram.png)


## 步驟 3：建立特徵群組
<a name="feature-store-set-up-feature-groups-introduction"></a>

我們首先通過為客戶資料和訂單資料建立功能組名稱開始。在此之後，我們建立了兩個特徵群組，一個用於 `customer_data` 和另一個用於 `orders_data`。

```
import time
from time import strftime, gmtime
customers_feature_group_name = 'customers-feature-group-' + strftime('%d-%H-%M-%S', gmtime())
orders_feature_group_name = 'orders-feature-group-' + strftime('%d-%H-%M-%S', gmtime())
```

具現化 `customers_data` 和 `orders_data` 的 `FeatureGroup` 物件。

```
from sagemaker.feature_store.feature_group import FeatureGroup

customers_feature_group = FeatureGroup(
    name=customers_feature_group_name, sagemaker_session=sagemaker_session
)
orders_feature_group = FeatureGroup(
    name=orders_feature_group_name, sagemaker_session=sagemaker_session
)
```

```
import time
current_time_sec = int(round(time.time()))
record_identifier_feature_name = "customer_id"
```

附加 `EventTime` 功能到您的資料影格。此參數為必要參數，且為每個資料點設定時間戳記。

```
customer_data["EventTime"] = pd.Series([current_time_sec]*len(customer_data), dtype="float64")
orders_data["EventTime"] = pd.Series([current_time_sec]*len(orders_data), dtype="float64")
```

將特徵定義載入至您的特徵群組：

```
customers_feature_group.load_feature_definitions(data_frame=customer_data)
orders_feature_group.load_feature_definitions(data_frame=orders_data)
```

以下呼叫 `create` 以分別建立兩個特徵群組，即 `customers_feature_group` 和 `orders_feature_group`。

```
customers_feature_group.create(
    s3_uri=f"s3://{s3_bucket_name}/{prefix}",
    record_identifier_name=record_identifier_feature_name,
    event_time_feature_name="EventTime",
    role_arn=role,
    enable_online_store=True
)

orders_feature_group.create(
    s3_uri=f"s3://{s3_bucket_name}/{prefix}",
    record_identifier_name=record_identifier_feature_name,
    event_time_feature_name="EventTime",
    role_arn=role,
    enable_online_store=True
)
```

為了確認您的特徵群組已建立，我們使用 `DescribeFeatureGroup` 和 `ListFeatureGroups` API 來顯示它：

```
customers_feature_group.describe()
```

```
orders_feature_group.describe()
```

```
sagemaker_session.boto_session.client('sagemaker', region_name=region).list_feature_groups() # We use the boto client to list FeatureGroups
```

## 步驟 4：將資料擷取至功能群組
<a name="feature-store-set-up-record-identifier-event-time"></a>

建立特徵群組後，我們可以將資料放入其中。如果您使用的是 SageMaker AI 適用於 Python (Boto3) 的 AWS SDK，請使用 `ingest` API 呼叫。如果您使用的是 SDK for Python (Boto3)，請使用 `PutRecord` API。擷取這兩個選項的資料需要不到 1 分鐘的時間。此範例使用 SageMaker AI SDK for Python (Boto3)，因此其會使用 `ingest` API 呼叫。

```
def check_feature_group_status(feature_group):
    status = feature_group.describe().get("FeatureGroupStatus")
    while status == "Creating":
        print("Waiting for Feature Group to be Created")
        time.sleep(5)
        status = feature_group.describe().get("FeatureGroupStatus")
    print(f"FeatureGroup {feature_group.name} successfully created.")

check_feature_group_status(customers_feature_group)
check_feature_group_status(orders_feature_group)
```

```
customers_feature_group.ingest(
    data_frame=customer_data, max_workers=3, wait=True
)
```

```
orders_feature_group.ingest(
    data_frame=orders_data, max_workers=3, wait=True
)
```

使用任意的客戶記錄 ID，573291 我們用 `get_record` 來檢查資料是否已被擷取到特徵群組。

```
customer_id = 573291
sample_record = sagemaker_session.boto_session.client('sagemaker-featurestore-runtime', region_name=region).get_record(FeatureGroupName=customers_feature_group_name, RecordIdentifierValueAsString=str(customer_id))
```

```
print(sample_record)
```

以下示範如何使用 `batch_get_record` 來取得批次記錄。

```
all_records = sagemaker_session.boto_session.client(
    "sagemaker-featurestore-runtime", region_name=region
).batch_get_record(
    Identifiers=[
        {
            "FeatureGroupName": customers_feature_group_name,
            "RecordIdentifiersValueAsString": ["573291", "109382", "828400", "124013"],
        },
        {
            "FeatureGroupName": orders_feature_group_name,
            "RecordIdentifiersValueAsString": ["573291", "109382", "828400", "124013"],
        },
    ]
)
```

```
print(all_records)
```

## 步驟 5：清除
<a name="feature-store-load-feature-definitions"></a>

我們在此處移除所建立的特徵群組。

```
customers_feature_group.delete()
orders_feature_group.delete()
```

## 步驟 6：後續步驟
<a name="feature-store-setup-create-feature-group"></a>

在此範例筆記本中，您了解如何開始使用 Feature Store、建立特徵群組，以及將資料擷取到其中。

如需如何將 Feature Store 用於詐騙偵測使用案例的進階範例，請參閱[使用 Feature Store 進行詐騙偵測](https://sagemaker-examples.readthedocs.io/en/latest/sagemaker-featurestore/sagemaker_featurestore_fraud_detection_python_sdk.html)。

## 步驟 7：適用於程式設計人員的程式碼範例
<a name="feature-store-working-with-feature-groups"></a>

在這本筆記本中，我們使用了各種不同的 API 調用。其中大多數都可以透過 SageMaker Python SDK 存取，但是有些只存在於 Boto3 內。您可以直接在 Feature Store 物件上調用 SageMaker Python SDK API 呼叫，而若要調用存在於 Boto3 中的 API 呼叫，您必須先透過 Boto3 和 SageMaker AI 工作階段存取 Boto3 用戶端：例如，`sagemaker_session.boto_session.client()`。

以下是此筆記本的 API 呼叫清單。這些呼叫存在於 SDK for Python 內，也存在於 Boto3 中，供您參考：

 **SDK for Python (Boto3) API 呼叫** 

```
describe()
ingest()
delete()
create()
load_feature_definitions()
```

 **Boto3 API 調用** 

```
list_feature_groups()
get_record()
```