本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 教學課程：開始使用 S3 Vectors
在本教學課程中，您會在 Amazon S3 主控台 AWS 區域 的 中建立 S3 向量儲存貯體和向量索引。 Amazon S3 接著，您使用 Amazon Bedrock 嵌入模型產生資料的向量嵌入，並將其儲存在向量索引中，以執行語義搜尋。
若要開始使用，如果您還沒有帳戶，請註冊 AWS 帳戶。如需有關使用帳戶進行設定的詳細資訊，請參閱 [Amazon S3 入門](GetStartedWithS3.md)。
**Topics**
+ [步驟 1：使用主控台建立向量儲存貯體](#s3-vectors-create-bucket-tutorial)
+ [步驟 2：使用主控台在向量儲存貯體中建立向量索引](#s3-vectors-create-index-tutorial)
+ [步驟 3：使用 SDK for Python (Boto3) 將向量插入向量索引](#s3-vectors-insert-vectors-tutorial)
+ [步驟 4. 使用 SDK for Python (Boto3) 查詢向量索引中的向量](#s3-vectors-query-vectors-tutorial)
+ [(選用) 使用 S3 Vectors Embed CLI 自動建立向量嵌入](#s3-vectors-embed-CLI-tutorial)
+ [(選用) 整合 S3 Vectors 與 Amazon Bedrock 知識庫](#s3-vectors-bedrock-kb-tutorial)
+ [(選用) 整合 S3 Vectors 與 Amazon OpenSearch](#s3-vectors-opensearch-tutorial)
## 步驟 1：使用主控台建立向量儲存貯體
S3 向量儲存貯體是一種 Amazon S3 儲存貯體，專門用於儲存和查詢向量。您可以使用專用的 API 操作來寫入和查詢向量資料。您可以使用存取控制機制來控制向量資料的存取，例如 IAM 身分型政策和資源型政策。
在此步驟中，您使用 Amazon S3 主控台建立第一個向量儲存貯體。如需建立向量儲存貯體的其他方式，請參閱 [建立向量儲存貯體](s3-vectors-buckets-create.md)。
### 建立向量儲存貯體
1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 的 Amazon S3 主控台。
1. 在左側導覽窗格中，選擇**向量儲存貯體**。
1. 在**向量儲存貯體**頁面上，選擇**建立向量儲存貯體**。
1. 在**建立向量儲存貯體**頁面上，在**向量儲存貯體名稱**欄位輸入名稱。在本教學課程中，我們使用 {{media-embeddings}} 做為向量儲存貯體名稱。向量儲存貯體名稱必須介於 3 到 63 個字元之間，且在 AWS 區域中是唯一的。有效字元為小寫字母(a-z)、數字 (0-9) 和連字號 (-)。
**注意**
建立儲存貯體後，就無法變更向量儲存貯體。
1. 在**加密**下，選擇**指定加密類型**。您可以選擇將加密類型指定為**具有 AWS Key Management Service 金鑰的伺服器端加密 (SSE-KMS)** 或**具有 Amazon S3 受管金鑰 (SSE-S3) 的預設伺服器端加密**。在本教學課程中，我們選擇**使用 Amazon S3 受管金鑰 (SSE-S3) 的伺服器端加密**。如需有關設定向量儲存貯體的加密組態的詳細資訊，請參閱 [S3 Vectors 中的資料保護和加密](s3-vectors-data-encryption.md)。
**注意**
建立向量儲存貯體後，就無法變更加密類型。
1. 在**標籤 （選用）** 下，您可以將標籤新增為鍵值對，以協助組織和指定向量儲存貯體的許可。輸入 **Key (索引鍵)** 和 **Value (數值)**。若要新增其他標籤，選擇 **Add Tag (新增標籤)**。您可以為向量儲存貯體輸入最多 50 個標籤。如需詳細資訊，請參閱[搭配 S3 向量儲存貯體使用標籤](s3-vectors-tags.md)。
1. 選擇**建立向量儲存貯體**。
## 步驟 2：使用主控台在向量儲存貯體中建立向量索引
**注意**
請仔細選擇向量索引組態參數。建立向量索引後，便無法更新向量索引名稱、維度、距離指標，或無法篩選的中繼資料索引鍵。若要變更這些值，則必須建立新的向量索引。
在此步驟中，您可在向量儲存貯體中建立向量索引。向量索引用於儲存和查詢向量嵌入。如需向量索引的詳細資訊，請參閱 [向量索引](s3-vectors-indexes.md)。
### 建立向量索引
1. 在 Amazon S3 主控台上的**向量儲存貯體**清單中，導覽至新建立的向量儲存貯體。
1. 選擇**建立向量索引**。
1. 在**建立向量索引**頁面上，在**向量索引名稱**欄位中輸入名稱。在本教學課程中，我們使用{{電影}}做為向量索引名稱。
向量索引名稱必須介於 3 到 63 個字元之間，而且在此向量儲存貯體中是唯一的。有效字元為小寫字母 (a-z)、數字 (0-9)、連字號 (-) 和點 (.)。
在建立索引後，就無法變更向量索引名稱。
1. 在**維度**下，指定介於 1 到 4096 之間的數值，以確定向量嵌入模型所產生的每個向量中有多少數字。嵌入模型是專用機器學習 (ML) 模型，可將資料 (例如文字或影像) 轉換為數值向量。嵌入模型通常會產生介於 500-2000 個維度的輸出，每個維度都是浮點數。在本教學課程中，我們會使用來自 Amazon Bedrock 的 Titan Text v2 嵌入模型。此嵌入模型使用 1024 維向量做為預設值，因此我們會將向量索引的維度設定為 `1024`。
建立索引後，就無法變更維度值。根據您的嵌入模型建議，小心指定維度值。
1. 在**距離指標**下，選擇**餘弦** (測量角度相似度) 或**歐幾里得 **(測量直線距離) 做為距離指標，以定義在查詢期間計算向量之間的相似度。在本教學課程中，我們選擇**餘弦**。
建立索引後，就無法變更距離指標。根據您的嵌入模型建議，仔細選擇距離指標。
1. **在其他設定 (選用)** 下，您可以指定不可篩選的中繼資料索引鍵，一起儲存補充資訊與向量嵌入。
**注意**
當您在索引建立之後插入向量資料時，可以將可篩選的中繼資料以鍵值對形式連接到每個向量。根據預設，連接至向量的所有中繼資料索引鍵都是可篩選的，並且可以當作相似度查詢中的篩選條件。只有在向量索引建立期間指定為不可篩選的中繼資料索引鍵，才會排除在篩選範圍外。
每個不可篩選的中繼資料索引鍵必須介於 1 到 63 個字元之間，且在向量索引中是唯一的。這些索引鍵適用於儲存您在相似度查詢期間不需要篩選的參考資訊。例如，在使用文字嵌入時，您可能會想要保留原始文字區塊以供參考。在本教學課程中，我們會新增名為 `source_text` 的不可篩選中繼資料索引鍵，以儲存要為其建立向量嵌入的文字資料。
建立索引後，就無法更新不可篩選的中繼資料索引鍵。仔細規劃中繼資料結構。
1. 在**加密**下，選擇**指定加密類型**。您可以選擇使用儲存貯體層級加密設定或覆寫向量索引的加密設定。如果您覆寫儲存貯體層級設定，您可以選擇將向量索引的加密類型指定為**使用 AWS Key Management Service 金鑰 (SSE-KMS) 的伺服器端加密**，或使用 **Amazon S3 受管金鑰 (SSE-S3) 的伺服器端加密**。在本教學課程中，我們選擇**使用儲存貯體設定進行加密**。如需設定向量儲存貯體和索引加密組態的詳細資訊，請參閱 [S3 Vectors 中的資料保護和加密](s3-vectors-data-encryption.md)。
1. 在**標籤 （選用）** 下，您可以將標籤新增為鍵值對，以協助使用 AWS Billing and Cost Management 追蹤和組織向量索引成本。輸入 **Key (索引鍵)** 和 **Value (數值)**。若要新增其他標籤，選擇 **Add Tag (新增標籤)**。您可以為向量索引輸入最多 50 個標籤。如需詳細資訊，請參閱[搭配 S3 向量儲存貯體使用標籤](s3-vectors-tags.md)。
1. 選擇**建立向量索引**。
確認您的新向量索引出現在儲存貯體內。
## 步驟 3：使用 SDK for Python (Boto3) 將向量插入向量索引
若要插入、列出和查詢向量，請使用 AWS SDKs或 Amazon S3 REST API。 AWS CLI
此步驟使用 [PutVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_PutVectors.html) API 操作將向量嵌入項目插入向量索引。
您必須先使用選擇的嵌入模型來產生向量嵌入。如果您使用 Amazon Bedrock，請使用 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) API 操作來指定您偏好的嵌入模型，藉以產生嵌入。或者，若要使用單一命令產生和插入向量嵌入，請參閱 [(選用) 使用 S3 Vectors Embed CLI 自動建立向量嵌入](#s3-vectors-embed-CLI-tutorial)。
下列範例程式碼使用 從 Amazon Bedrock 產生具有 Titan Text Embeddings V2 模型的 1024 維向量內嵌 適用於 Python (Boto3) 的 AWS SDK，並使用 `PutVectors` API 將其存放在向量索引中。除了每個向量之外，我們還會連接鍵值對以當作可篩選的中繼資料。此外，我們使用名為 {{source\_text}} 的不可篩選中繼資料索引鍵，保留衍生每個向量的原始文字。若要最大化請求輸送量，並最佳化速度和效率，建議您分批插入和刪除向量。如需詳細資訊，請參閱[S3 Vectors 最佳實務](s3-vectors-best-practices.md)。
```
# Populate a vector index with embeddings from Amazon Titan Text Embeddings V2.
import boto3
import json
# Create Bedrock Runtime and S3 Vectors clients in the AWS Region of your choice.
bedrock = boto3.client("bedrock-runtime", region_name="us-west-2")
s3vectors = boto3.client("s3vectors", region_name="us-west-2")
# Texts to convert to embeddings.
texts = [
"Star Wars: A farm boy joins rebels to fight an evil empire in space",
"Jurassic Park: Scientists create dinosaurs in a theme park that goes wrong",
"Finding Nemo: A father fish searches the ocean to find his lost son"
]
# Generate vector embeddings.
embeddings = []
for text in texts:
response = bedrock.invoke_model(
modelId="amazon.titan-embed-text-v2:0",
body=json.dumps({"inputText": text})
)
# Extract embedding from response.
response_body = json.loads(response["body"].read())
embeddings.append(response_body["embedding"])
# Write embeddings into vector index with metadata.
s3vectors.put_vectors(
vectorBucketName="media-embeddings",
indexName="movies",
vectors=[
{
"key": "Star Wars",
"data": {"float32": embeddings[0]},
"metadata": {"source_text": texts[0], "genre":"scifi"}
},
{
"key": "Jurassic Park",
"data": {"float32": embeddings[1]},
"metadata": {"source_text": texts[1], "genre":"scifi"}
},
{
"key": "Finding Nemo",
"data": {"float32": embeddings[2]},
"metadata": {"source_text": texts[2], "genre":"family"}
}
]
)
```
## 步驟 4. 使用 SDK for Python (Boto3) 查詢向量索引中的向量
在向量索引中儲存向量嵌入之後，您可以使用 [QueryVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_QueryVectors.html) API 操作執行相似性搜尋。
您必須先使用在 [步驟 3：使用 SDK for Python (Boto3) 將向量插入向量索引](#s3-vectors-insert-vectors-tutorial) 中插入時使用的相同嵌入模型，產生查詢向量嵌入。在本教學課程中，透過 SDK for Python (Boto3)，從 Amazon Bedrock 使用 Titan Text Embeddings V2 模型。
您可以執行相似性搜尋，以傳回最接近的相符向量。在相似性搜尋中，您可以選擇透過使用中繼資料索引鍵，根據特定條件縮小結果範圍的方式進行篩選，如此可同時保持語義相關性。
```
# Query a vector index with an embedding from Amazon Titan Text Embeddings V2.
import boto3
import json
# Create Bedrock Runtime and S3 Vectors clients in the AWS Region of your choice.
bedrock = boto3.client("bedrock-runtime", region_name="us-west-2")
s3vectors = boto3.client("s3vectors", region_name="us-west-2")
# Query text to convert to an embedding.
input_text = "adventures in space"
# Generate the vector embedding.
response = bedrock.invoke_model(
modelId="amazon.titan-embed-text-v2:0",
body=json.dumps({"inputText": input_text})
)
# Extract embedding from response.
model_response = json.loads(response["body"].read())
embedding = model_response["embedding"]
# Query vector index.
response = s3vectors.query_vectors(
vectorBucketName="media-embeddings",
indexName="movies",
queryVector={"float32": embedding},
topK=3,
returnDistance=True,
returnMetadata=True
)
print(json.dumps(response["vectors"], indent=2))
# Query vector index with a metadata filter.
response = s3vectors.query_vectors(
vectorBucketName="media-embeddings",
indexName="movies",
queryVector={"float32": embedding},
topK=3,
filter={"genre": "scifi"},
returnDistance=True,
returnMetadata=True
)
print(json.dumps(response["vectors"], indent=2))
```
## (選用) 使用 S3 Vectors Embed CLI 自動建立向量嵌入
Amazon S3 Vectors Embed CLI 是一種獨立的命令列工具，可簡化在 S3 Vectors 中使用向量嵌入的程序。您可以透過單一命令，使用 Amazon Bedrock 為資料建立向量嵌入，並將其儲存在 S3 向量索引中以進行查詢。該工具支援以下命令：
+ `s3vectors-embed put`：產生文字、檔案內容或 S3 物件的向量嵌入，並將其以向量形式儲存在 S3 向量索引中。
+ `s3vectors-embed query`：嵌入查詢輸入，並在 S3 向量索引中搜尋相似的向量。
如需有關命令和用量的詳細資訊，請參閱 [Amazon S3 Vectors Embed CLI GitHub 儲存庫](https://github.com/awslabs/s3vectors-embed-cli)。
## (選用) 整合 S3 Vectors 與 Amazon Bedrock 知識庫
Amazon Bedrock 知識庫與 S3 Vectors 整合，以提高向量資料集的成本效益，並達到長期儲存之目的。
### 先決條件
遵循[先決條件](https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started-console.html)，確保您擁有建立 Amazon Bedrock 知識庫的必要權限。
+ 適用於 S3 Vectors 和 Amazon Bedrock 服務的 IAM 許可。如需 S3 Vectors 的 IAM 許可的詳細資訊，請參閱 [S3 Vectors 中的身分和存取管理](s3-vectors-access-management.md)。
+ 為擷取至知識庫而準備的來源文件。
+ 了解您的嵌入模型要求。
### 在主控台使用 S3 Vectors 建立 Amazon Bedrock 知識庫
Amazon Bedrock 知識庫提供全託管的端對端 RAG 工作流程。當您使用 S3 Vectors 建立知識庫時，Amazon Bedrock 會自動從 S3 資料來源擷取資料、將內容轉換為文字區塊、產生嵌入，並將其儲存在向量索引中。接著您可以查詢知識庫，並根據從來源資料擷取的區塊產生回應。
**在主控台使用 S3 Vectors 建立 Amazon Bedrock 知識庫**
1. AWS 管理主控台 使用[具有 Amazon Bedrock 許可的 IAM 角色](https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html)登入 ，然後開啟位於 https：//[https://console.aws.amazon.com/bedrock/](https://console.aws.amazon.com/bedrock/) 的 Amazon Bedrock 主控台。
1. 在左側導覽窗格中，選擇**知識庫**。
1. 在**知識庫**區段中，選擇**建立**。在下拉式清單中，選擇**知識庫 (使用向量存放區)**。
1. 在本教學課程中，為**知識庫名稱**、**知識庫描述**和 **IAM 許可**保留預設值。
1. 針對**選擇資料來源類型**，選擇要連接知識庫的資料來源。在本教學課程中，選擇 **Amazon S3**。
1. (選用) 提供任何**標籤**或**應用程式日誌**。
1. 選擇**下一步**。
1. 在**設定資料來源**頁面上，為**資料來源名稱**、**資料來源位置**、**剖析策略**和**區塊策略**保留在本教學課程中的預設設定。
1. 在 **S3 URI** 中，輸入包含來源檔案的 S3 一般用途儲存貯體，或選擇**瀏覽 S3**，並選擇 S3 一般用途儲存貯體。
1. 針對加密的 S3 資料，選取**為 S3 資料新增客戶自管 KMS 金鑰**，並指定您的客戶自管 KMS 金鑰。
1. 選擇**下一步**以繼續至下一個步驟，指定**嵌入模型**和**向量儲存**選項。
1. 在**嵌入模型**區段中，選擇**選取模型**，然後選擇可與 S3 Vectors 搭配使用的相容嵌入模型。您必須使用浮點嵌入。不支援二進位類型。
1. (選用) 展開**其他組態**區段，查看下列組態選項 (並非所有模型都支援所有組態)：
+ **嵌入類型** – 是否要將資料轉換為浮點 (float32) 向量嵌入 (更精確，但較昂貴) 或二進位向量嵌入 (較不精確，但成本較低)。若要與 S3 Vectors 整合，您必須選擇**浮點向量嵌入**。
+ **向量維度** – 選擇嵌入模型建議的維度大小。
1. 在**向量儲存**區段中，選擇建議的方法即**快速建立新的向量儲存**，以自動設定新的向量儲存貯體，或者如果可行，選擇**使用現有向量存放區**來使用現有的向量儲存貯體。如需有關使用現有向量存放區流程的資訊，請參閱《Amazon Bedrock 使用者指南》**中的[使用您為知識庫建立之向量存放區的先決條件](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-setup.html)。
1. 關於**其他組態** – 根據預設，您的向量儲存貯體會搭配使用伺服器端加密和 Amazon S3 受管金鑰 (SSE-S3)。您可以選擇使用自己的 KMS 金鑰與 AWS Key Management Service 金鑰 (SSE-KMS) 進行伺服器端加密，以增強對加密設定的控制。
1. 選擇**下一步**以檢閱知識庫詳細資訊，然後選擇**建立知識庫**。
**注意**
建立知識庫所需的時間，取決於您的特定組態。建立好知識庫後，知識庫的狀態會變更為就緒或可用。一旦知識庫準備就緒且可用，請於首次同步資料來源，或可隨時同步您的內容，以保持其最新狀態。若要同步資料來源，請在主控台選擇您的知識庫，然後在資料來源概觀區段選擇**同步**。
## (選用) 整合 S3 Vectors 與 Amazon OpenSearch
[Amazon OpenSearch Service](https://aws.amazon.com/opensearch-service/) 是一項全受管服務，可簡化 AWS 雲端中 OpenSearch 的部署、擴展和操作。S3 Vectors 和 OpenSearch 之間有兩種整合。一個是將向量資料從 S3 Vectors 匯出到 OpenSearch Serverless，以取得高效能搜尋功能。另一個使用 S3 Vectors 做為 OpenSearch 中經濟實惠的儲存引擎，同時可保持對 OpenSearch 功能的存取。
如需詳細資訊，請參閱[搭配 OpenSearch Service 使用 S3 Vectors](s3-vectors-opensearch.md)。