本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 向量 每個向量都包含一個索引鍵，可唯一識別向量索引中的每個向量。此外，您可以將中繼資料 (例如年份、作者、類型、位置) 以鍵值對形式連接到每個向量。 向量資料操作包括插入、列示、查詢和刪除向量。若要產生非結構化資料的新向量嵌入，您可以使用 Amazon Bedrock 的 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) API 操作，以指定您要使用的嵌入模型的模型 ID。此外，開放原始碼 Amazon S3 Vectors Embed CLI 工具提供從命令列產生嵌入和執行語義搜尋的簡化方法。如需有關此開放原始碼工具使用 Amazon Bedrock 基礎模型自動產生向量嵌入，以及在 S3 Vectors 索引中自動產生語義搜尋操作的詳細資訊，請參閱 [使用 `s3vectors-embed-cli` 建立向量嵌入和執行語義搜尋](s3-vectors-cli.md)。 ## 向量概念 **向量索引鍵**：每個向量都由索引中的唯一向量索引鍵識別。向量索引鍵的長度上限為 1,024 個字元，而且在向量索引中必須是唯一。索引鍵區分大小寫，可包含任何 UTF-8 字元。 **向量維度**：維度是向量中的值數目。較大的維度需要更多的儲存空間。索引中的所有向量都必須具有相同數量的維度，而這些維度會在您建立索引時指定。維度必須是介於 1 到 4096 之間的整數。 **中繼資料**：您可以將中繼資料連接至向量做為鍵值對，以提供其他前後關聯內容，並在查詢期間啟用篩選功能。中繼資料包含可篩選和不可篩選的中繼資料索引鍵。可篩選中繼資料用於查詢篩選條件。不可篩選的中繼資料索引鍵會在向量索引建立期間指定，並提供其他前後關聯內容，但無法用於篩選。中繼資料支援字串、數字和布林值類型。如需可篩選和不可篩選中繼資料的詳細資訊，請參閱 [中繼資料篩選](s3-vectors-metadata-filtering.md)。如需中繼資料限制 (包括每個向量的大小限制，和每個向量的最大中繼資料索引鍵) 的詳細資訊，請參閱[限制與局限](s3-vectors-limitations.md)。 **Topics** + [ ## 向量概念 ](#s3-vectors-concepts) + [ # 將向量插入向量索引 ](s3-vectors-index-create.md) + [ # 列示向量 ](s3-vectors-list.md) + [ # 查詢向量 ](s3-vectors-query.md) + [ # 從向量索引刪除向量 ](s3-vectors-delete.md) + [ # 中繼資料篩選 ](s3-vectors-metadata-filtering.md) # 將向量插入向量索引 您可以使用 [PutVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_PutVectors.html) API 操作將向量新增至向量索引。每個向量都包含一個索引鍵，可唯一識別向量索引中的每個向量。如果您放置的向量具有已存在於索引中之索引鍵，該向量會完全覆寫現有的向量，導致無法再搜尋先前的向量。若要最大化寫入輸送量並最佳化成本，建議您大量插入向量，直到 的批次大小上限為止`PutVectors`。不過，對於需要使用較小批次的工作負載 - 例如即時，傳入向量資料必須立即變成可搜尋 - 您可以透過使用較多的並行`PutVectors`請求來達到更高的寫入輸送量，最高可達每秒允許的請求上限。如需 批次大小上限的詳細資訊`PutVectors`，也就是每個 `PutVectors` API 呼叫的向量限制，以及每秒的請求和向量上限，請參閱 [限制](s3-vectors-limitations.md)。此外，您可以將中繼資料 (例如年份、作者、類型、位置) 以鍵值對形式連接到每個向量。根據預設，連接至向量的所有中繼資料索引鍵都是可篩選的，並且可以當作相似度查詢中的篩選條件。只有在向量索引建立期間指定為不可篩選的中繼資料索引鍵，才會排除在篩選範圍外。S3 向量索引支援中繼資料的字串、數字、布林值和清單類型。如需有關每個向量的總中繼資料大小限制，和每個向量的可篩選中繼資料大小限制的詳細資訊，請參閱 [限制](s3-vectors-limitations.md)。如果中繼資料大小超過這些限制，`PutVectors` API 操作會傳回 `400 Bad Request` 錯誤。 使用 `PutVectors` API 操作將向量資料加入至向量索引之前，您需要將原始資料轉換為向量嵌入，這是做為浮點數陣列的內容數字表示法。向量嵌入會擷取內容的語義，一旦透過 `PutVectors` 操作儲存在向量索引中，就會啟用相似性搜尋。您可以根據您的資料類型和使用案例，使用各種方法來產生向量嵌入。這些方法包括使用機器學習架構、專業嵌入程式庫，或 Amazon Bedrock 等的 AWS 服務。例如，若使用的是 Amazon Bedrock，您可以利用 [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) API 操作和偏好的嵌入模型來產生嵌入。 此外，Amazon Bedrock 知識庫提供全託管端對端 RAG 工作流程，其中 Amazon Bedrock 會自動從 S3 資料來源擷取資料、將內容轉換為文字區塊、產生嵌入，然後將其儲存在向量索引中。接著您可以查詢知識庫，並根據從來源資料擷取的區塊產生回應。 此外，開放原始碼 Amazon S3 Vectors Embed CLI 工具會提供產生嵌入，並從命令列執行語義搜尋的簡化方法。如需有關此開放原始碼工具使用 Amazon Bedrock 基礎模型自動產生向量嵌入，以及在 S3 Vectors 索引中自動產生語義搜尋操作的詳細資訊，請參閱 [使用 `s3vectors-embed-cli` 建立向量嵌入和執行語義搜尋](s3-vectors-cli.md)。 **注意** 將向量資料插入向量索引時，您必須提供向量資料來當作 `float32` (32 位元浮點) 值。如果您將更精確的值傳遞至 AWS SDK，S3 Vectors 會在儲存值之前將值轉換為 32 位元浮點，而 [GetVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_GetVectors.html)、[ListVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_ListVectors.html) 和 [QueryVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_QueryVectors.html) 操作會傳回`float32`值。 AWS SDKs可能會有不同的預設數值類型，因此請確保您的向量已正確格式化為`float32`值，無論您使用哪個 SDK。例如，在 Python 中，使用 `numpy.float32` 或明確轉換您的值。 ## 使用 AWS SDKs ------ #### [ SDK for Python ] ``` # 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"} } ] ) ``` ------ # 列示向量 您可以使用 [ListVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_ListVectors.html) API 操作列出向量索引中的向量。如需每一頁面可傳回之向量數上限的詳細資訊，請參閱 [限制](s3-vectors-limitations.md)。當結果遭到截斷時，回應會包含分頁字符。如需 `ListVectors` 的回應元素的詳細資訊，請參閱《Amazon S3 API 參考》**中的 [ListVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_ListVectors)。您也可以使用 `ListVectors` 從指定的向量索引匯出向量資料。`ListVectors` 非常一致。WRITE 操作之後，您可以立即列出反映所有變更的向量。 ## 使用 AWS CLI 若要列出向量，可使用下列範例命令。以您自己的資訊取代*使用者輸入預留位置*。 `segment-count` 和 `segment-index` 參數可讓您將列示操作分割為多個平行請求。當您指定 `segment-count` 值 (例如 `2`) 時，可以將索引分割成多個區段。`segment-index` 參數 (從 0 開始) 決定要列出的區段。此方法可啟用平行處理，藉以協助改善列出大型向量索引的效能。如需 `segment-count` 和 `segment-index` 的詳細資訊，請參閱《Amazon S3 API 參考》**中的 [ListVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_ListVectors)。 **列出索引中的所有向量** 範例請求： ``` aws s3vectors list-vectors \ --vector-bucket-name "amzn-s3-demo-vector-bucket" \ --index-name "idx" \ --segment-count 2 \ --segment-index 0 \ --return-data \ --return-metadata ``` 回應範例： ``` { "vectors": [ { "key": "vec3", "data": { "float32": [0.4000000059604645] }, "metadata": { "nonFilterableKey": "val4", "filterableKey": "val2" } } ] } ``` **列出具有分頁的向量** 範例請求： ``` aws s3vectors list-vectors \ --vector-bucket-name "amzn-s3-demo-vector-bucket" \ --index-name "idx" \ --segment-count 2 \ --segment-index 0 \ --return-data \ --return-metadata \ --next-token "zWfh7e57H2jBfBtRRmC7OfMwl209G9dg3j2qM6kM4t0rps6ClYzJykgMOil9eGqU5nhf_gTq53IfoUdTnsg" ``` 回應範例： ``` { "vectors": [ { "key": "vec1", "data": { "float32": [0.5] }, "metadata": { "nonFilterableKey": "val2", "filterableKey": "val1" } } ] } ``` ## 使用 AWS SDKs ------ #### [ SDK for Python ] 範例：列出向量索引中的向量 ``` import boto3 # Create a S3 Vectors client in the AWS Region of your choice. s3vectors = boto3.client("s3vectors", region_name="us-west-2") #List vectors in your vector index response = s3vectors.list_vectors( vectorBucketName="media-embeddings", indexName="movies", maxResults = 600, returnData = True, returnMetadata = True ) vectors = response["vectors"] print(vectors) ``` 範例：平行列出向量索引中的所有向量 ``` import boto3 # Create a S3 Vectors client in the AWS Region of your choice. s3vectors = boto3.client("s3vectors", region_name="us-west-2") #List vectors in the 1st half of vectors in the index. response = s3vectors.list_vectors( vectorBucketName="media-embeddings", indexName="movies", segmentCount=2, segmentIndex=1, maxResults = 600, returnData = True, returnMetadata = True ) vectors = response["vectors"] #List vectors starting from the 2nd half of vectors in the index. # This can be ran in parallel with the first `list_vectors` call. response = s3vectors.list_vectors( vectorBucketName="media-embeddings", indexName="movies", segmentCount=2, segmentIndex=1, maxResults = 600, returnData = True, returnMetadata = True ) vectors = response["vectors"] print(vectors) ``` ------ # 查詢向量 您可以使用 [QueryVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_QueryVectors.html) API 操作執行相似度查詢，其中可指定查詢向量、要傳回的相關結果數目 (top K 最近鄰的)，以及索引 ARN。此外，您可以在查詢中使用中繼資料篩選條件，以僅搜尋符合篩選條件的向量。如果您請求對不可篩選的中繼資料欄位進行篩選，請求將傳回 `400 Bad Request` 錯誤。如需有關中繼資料篩選的詳細資訊，請參閱 [中繼資料篩選](s3-vectors-metadata-filtering.md)。 在回應中，依預設會傳回向量索引鍵。您可以選擇在回應中包含距離和中繼資料。 產生查詢向量時，您應該使用可用來產生儲存在向量索引中初始向量的相同向量嵌入模型。例如，若您在 Amazon Bedrock 中使用 Amazon Titan 文本嵌入 V2 模型來產生文件的向量嵌入，請使用相同的嵌入模型將問題轉換為查詢向量。此外，Amazon Bedrock 知識庫提供全託管端對端 RAG 工作流程，其中 Amazon Bedrock 會自動從 S3 資料來源擷取資料、將內容轉換為文字區塊、產生嵌入，然後將其儲存在向量索引中。接著您可以查詢知識庫，並根據從來源資料擷取的區塊產生回應。如需有關如何在主控台從 Amazon Bedrock 知識庫查詢向量的詳細資訊，請參閱 [(選用) 整合 S3 Vectors 與 Amazon Bedrock 知識庫](s3-vectors-getting-started.md#s3-vectors-bedrock-kb-tutorial)。 此外，開放原始碼 Amazon S3 Vectors Embed CLI 工具會提供從命令列執行語義搜尋的簡化方法。此開放原始碼工具透過使用 Amazon Bedrock 基礎模型處理向量嵌入產生，並根據 S3 向量索引執行語義搜尋操作，簡化查詢程序。如需有關使用此工具查詢向量資料的詳細資訊，請參閱 [使用 `s3vectors-embed-cli` 建立向量嵌入和執行語義搜尋](s3-vectors-cli.md)。 S3 Vectors 為冷查詢提供一秒的回應時間，利用 Amazon S3 彈性輸送量來有效搜尋數百萬個向量。這讓具有不常查詢的工作負載具有高成本效益。對於暖查詢，S3 Vectors 可以提供低至 100 毫秒的回應時間，使具有重複或頻繁查詢模式的工作負載受益。 為了執行向量嵌入的相似度查詢，數個因素可能會影響平均取回效能，包括向量嵌入模型、向量資料集的大小 (向量和維度的數量)，以及查詢的分佈。S3 Vectors 可為大多數資料集提供 90% 以上的平均取回率。平均取回率會測量查詢結果的品質。90% 的平均取回率表示回應包含 90% 的實際最接近向量 (基本事實)，這些向量儲存在相對於查詢向量的向量索引中。不過，由於實際效能可能會因您的特定使用案例而有所不同，建議您使用具代表性資料和查詢進行自己的測試，以驗證 S3 Vectors 是否符合您的取回要求。 ## 使用 AWS SDKs ------ #### [ SDK for Python ] ``` # 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)) ``` ------ # 從向量索引刪除向量 您可以使用 [DeleteVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_DeleteVectors.html) API 指定向量索引鍵，從向量索引中刪除特定向量。此操作有助於移除過時或不正確的資料，同時能保留其餘向量資料。 ## 使用 AWS CLI 若要刪除向量，請使用下列命令範例。以您自己的資訊取代*使用者輸入預留位置*。 ``` aws s3vectors delete-vectors \ --vector-bucket-name "amzn-s3-demo-vector-bucket" \ --index-name "idx" \ --keys '["vec2","vec3"]' ``` ## 使用 AWS SDKs ------ #### [ SDK for Python ] ``` import boto3 # Create a S3 Vectors client in the AWS Region of your choice. s3vectors = boto3.client("s3vectors", region_name="us-west-2") #Delete vectors in a vector index response = s3vectors.delete_vectors( vectorBucketName="media-embeddings", indexName="movies", keys=["Star Wars", "Finding Nemo"]) ``` ------ # 中繼資料篩選 中繼資料篩選功能可讓您根據連接至向量的特定屬性來篩選查詢結果。您可以搭配使用中繼資料篩選條件和查詢操作，以尋找同時符合相似性條件和特定中繼資料條件的向量。 S3 Vectors 支援兩種中繼資料類型：可篩選的中繼資料，和不可篩選的中繼資料。關鍵差異在於可篩選中繼資料可用於查詢篩選，但具有更嚴格的大小限制，而不可篩選的中繼資料無法用於篩選，但可以在其大小限制內存放大量資料。如需有關中繼資料限制，包括每個向量的大小限制和每個向量的中繼資料索引鍵上限的詳細資訊，請參閱 [限制](s3-vectors-limitations.md)。 S3 Vectors 會串聯執行向量搜索和篩選評估。S3 Vectors 會搜尋索引中的候選向量，尋找最 top K 相似向量，同時驗證每個候選向量是否符合中繼資料篩選條件。例如，若您搜尋相似的電影嵌入，並依 genre='mystery' 篩選，S3 Vectors 只會傳回相似電影嵌入，其中類型中繼資料符合 'mystery'。與在向量搜索後套用中繼資料篩選條件相反，此篩選方法更有可能找到相符的結果。注意：當向量索引包含極少相符結果時，具有篩選條件的查詢可能會傳回少於 top K 結果。 **Topics** + [ ## 可篩選的中繼資料 ](#s3-vectors-metadata-filtering-filterable) + [ ## 有效可篩選中繼資料的範例 ](#s3-vectors-metadata-filtering-examples) + [ ## 不可篩選的中繼資料 ](#s3-vectors-metadata-filtering-non-filterable) ## 可篩選的中繼資料 可篩選的中繼資料可讓您根據特定中繼資料值篩選查詢結果。根據預設，除非在向量索引建立期間明確指定為不可篩選，否則所有中繼資料欄位都可以在相似度查詢中進行篩選。S3 Vectors 支援字串、數字、布林值，以及具每個向量大小限制的中繼資料清單類型。中繼資料類型非常適合您要篩選的屬性，例如類別、時間戳記或狀態值。 如果中繼資料大小超過支援的限制，[PutVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_PutVectors.html) API 操作會傳回 `400 Bad Request` 錯誤。如需有關每個向量可篩選之中繼資料大小限制的詳細資訊，請參閱 [限制](s3-vectors-limitations.md)。 下列操作可與可篩選的中繼資料搭配使用。 | 運算子 | 有效的輸入類型 | Description | | --- | --- | --- | | \$1eq | 字串、數字、布林值 | 單一值的精確比對比較。與陣列中繼資料值比較時，如果輸入值符合陣列中的任何元素，則傳回 true。例如，`{"category": {"$eq": "documentary"}}` 會比對具有中繼資料 `"category": ["documentary", "romance"]` 的向量。 | | \$1ne | 字串、數字、布林值 | 非等於比較 | | \$1gt | Number | 大於比較 | | \$1gte | Number | 大於或等於比較 | | \$1lt | Number | 小於比較 | | \$1lte | Number | 小於或等於比較 | | \$1in | 基本項目的非空白陣列 | 符合陣列中的任何值 | | \$1nin | 基本項目的非空白陣列 | 未符合陣列中的任何值 | | \$1exists | Boolean | 檢查欄位是否存在 | | \$1and | 非空白的篩選條件陣列 | 多條件的邏輯 AND | | \$1or | 非空白的篩選條件陣列 | 多條件的邏輯 OR | ## 有效可篩選中繼資料的範例 **簡單相等** ``` {"genre": "documentary"} ``` 此篩選條件符合類型中繼資料索引鍵等於 "documentary" 的向量。當您未指定運算子時，S3 Vectors 會自動使用 \$1eq 運算子。 **明確相等** ``` // Example: Exact match {"genre": {"$eq": "documentary"}} ``` ``` // Example: Not equal to {"genre": {"$ne": "drama"}} ``` **數值比較** ``` {"year": {"$gt": 2019}} ``` ``` {"year": {"$gte": 2020}} ``` ``` {"year": {"$lt": 2020}} ``` ``` {"year": {"$lte": 2020}} ``` **陣列操作** ``` {"genre": {"$in": ["comedy", "documentary"]}} ``` ``` {"genre": {"$nin": ["comedy", "documentary"]}} ``` **存在檢查** ``` {"genre": {"$exists": true}} ``` `$exists` 篩選條件會比對具有 "genre" 中繼資料索引鍵的向量，無論該中繼資料索引鍵儲存的值為何。 **邏輯運算** ``` {"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]} ``` ``` {"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]} ``` **價格範圍 (相同欄位上的多個條件)** ``` {"price": {"$gte": 10, "$lte": 50}} ``` 如需如何使用中繼資料篩選功能查詢向量的詳細資訊，請參閱 [中繼資料篩選](s3-vectors.md#s3-vectors-filtering-metadata)。 ## 不可篩選的中繼資料 不可篩選的中繼資料無法用於查詢篩選，但可以儲存比可篩選的中繼資料更多的內容資料。它非常適合用於儲存大型文字區塊、詳細描述，或其他不需要可搜尋但可以使用查詢結果傳回的內容資訊。例如，您可以將完整文件文字、影像描述或詳細產品規格，儲存為不可篩選的中繼資料。 在向量索引建立期間，必須明確設定不可篩選的中繼資料索引鍵。中繼資料索引鍵在索引建立期間指定為不可篩選後，就無法在之後變更為可篩選。您可以為每個向量索引將多個中繼資料索引鍵設定為不可篩選，其中每個中繼資料索引鍵名稱限制為 63 個字元。如需有關每個向量索引允許的不可篩選中繼資料索引鍵數目上限的詳細資訊，請參閱 [限制](s3-vectors-limitations.md)。 雖然您無法篩選不可篩選的中繼資料，但您可以使用 `return-metadata` 參數將其與查詢結果一起擷取。對於某些使用案例，您可以使用不可篩選的中繼資料，如下所示。 + 使用不可篩選的中繼資料為您的應用程式提供內容，無需剖析單獨的資料來源。 + 儲存會超過可篩選中繼資料大小限制的較大文字區塊。 + 使用 [ListVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_ListVectors.html) API 操作將其包含在向量匯出中。 如需設定不可篩選的中繼資料的詳細資訊，請參閱 [在向量儲存貯體中建立向量索引](s3-vectors-create-index.md)。