# 教程：S3 Vectors 入门
在本教程中，将使用 Amazon S3 控制台在 AWS 区域中创建 S3 向量存储桶和向量索引。接下来，可以使用 Amazon Bedrock 嵌入模型来生成数据的向量嵌入，并将其存储在向量索引中以执行语义搜索。
开始之前，如果您还没有 AWS 账户，请先注册一个。有关设置账户的更多信息，请参阅 [Amazon S3 入门](GetStartedWithS3.md)。
**Topics**
+ [步骤 1：使用控制台创建向量存储桶](#s3-vectors-create-bucket-tutorial)
+ [步骤 2：使用控制台在向量存储桶中创建向量索引](#s3-vectors-create-index-tutorial)
+ [步骤 3：使用适用于 Python 的 SDK（Boto3）将向量插入到向量索引中](#s3-vectors-insert-vectors-tutorial)
+ [步骤 4：使用适用于 Python 的 SDK（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 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/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. 在**创建向量索引**页面上，在**向量索引名称**字段中输入名称。在本教程中，我们使用 {{movies}} 作为向量索引名称。
向量索引名称必须为 3 到 63 个字符，并且在该向量存储桶中是唯一的。有效字符为小写字母（a-z）、数字（0-9）、连字符（-）和点（.）。
创建索引后，无法更改向量索引名称。
1. 在**维度**下，指定一个介于 1 和 4096 之间的数值，该数值确定向量嵌入模型生成的每个向量中将有多少个数字。嵌入模型是专门的机器学习（ML）模型，用于将数据（如文本或图像）转换为数值向量。嵌入模型通常会产生 500-2000 个维度之间的输出，每个维度都是一个浮点数。在本教程中，我们将使用来自 Amazon Bedrock 的 Titan 文本 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 账单与成本管理来帮助跟踪和整理向量索引成本。输入 **Key (键)** 和 **Value (值)**。要添加另一个标签，请选择 **Add Tag (添加标签)**。您可以为一个向量索引输入最多 50 个标签。有关更多信息，请参阅 [将标签与 S3 向量存储桶结合使用](s3-vectors-tags.md)。
1. 选择**创建向量索引**。
验证新的向量索引是否出现在存储桶中。
## 步骤 3：使用适用于 Python 的 SDK（Boto3）将向量插入到向量索引中
要插入、列出和查询向量，请使用 AWS SDK、AWS CLI 或 Amazon S3 REST API。
此步骤是要使用 [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)。
以下示例代码通过适用于 Python (Boto3) 的 AWS SDK，使用来自 Amazon Bedrock 的 Titan 文本嵌入 V2 模型生成 1024 维向量嵌入，并使用 `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：使用适用于 Python 的 SDK（Boto3）查询向量索引中的向量
将向量嵌入存储在向量索引中后，可以使用 [QueryVectors](https://docs.aws.amazon.com/AmazonS3/latest/API/API_S3VectorBuckets_QueryVectors.html) API 操作来执行相似性搜索。
必须首先使用在[步骤 3：使用适用于 Python 的 SDK（Boto3）将向量插入到向量索引中](#s3-vectors-insert-vectors-tutorial)中插入时所用的相同嵌入模型来生成查询向量嵌入。在本教程中，通过适用于 Python 的 SDK（Boto3）使用来自 Amazon Bedrock 的 Titan 文本嵌入 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. 在 [https://console.aws.amazon.com/bedrock/](https://console.aws.amazon.com/bedrock/) 上，使用[具有 Amazon Bedrock 权限的 IAM 角色](https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html)登录到 AWS 管理控制台，然后打开 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 User Guide》**中的 [Prerequisites for using a vector store you created for a knowledge base](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-setup.html)。
1. 对于**其它配置**：默认情况下，向量存储桶使用具有 Amazon S3 托管式密钥的服务器端加密（SSE-S3）。对于使用 AWS Key Management Service 密钥的服务器端加密（SSE-KMS），您可以选择使用自己的 KMS 密钥来增强对加密设置的控制。
1. 选择**下一步**来查看知识库详细信息，然后选择**创建知识库**。
**注意**
创建知识库所用的时间取决于您的特定配置。完成创建知识库后，知识库的状态将发生变化，来指明知识库已就绪或可用。知识库准备就绪并可供使用后，您可以首次同步数据来源，或者在您希望内容保持最新时同步数据来源。要同步数据来源，请在控制台中选择知识库，然后在数据来源概述部分中选择**同步**。
## （可选）将 S3 Vectors 与 Amazon OpenSearch 集成
[Amazon OpenSearch Service](https://aws.amazon.com/opensearch-service/) 是一项完全托管式服务，可简化 OpenSearch 在 AWS 云中的部署、扩展和运营。S3 Vectors 和 OpenSearch 之间有两种集成。一种是将向量数据从 S3 Vectors 导出到 OpenSearch 无服务器，以获得高性能的搜索功能。另一种使用 S3 Vectors 作为 OpenSearch 中经济高效的存储引擎，同时保持对 OpenSearch 功能的访问权限。
有关更多信息，请参阅 [将 S3 Vectors 与 OpenSearch Service 结合使用](s3-vectors-opensearch.md)。