튜토리얼: S3 Vectors 시작하기

이 튜토리얼에서는 Amazon S3 콘솔의 AWS 리전에 S3 벡터 버킷과 벡터 인덱스를 만들고, Amazon Bedrock 임베딩 모델로 데이터의 벡터 임베딩을 생성해 벡터 인덱스에 저장한 뒤 시맨틱 검색을 수행해요.

출처: Tutorial: Getting started with S3 Vectors

본문

이 튜토리얼에서는 Amazon S3 콘솔의 AWS 리전에 S3 벡터 버킷과 벡터 인덱스를 만들어요. 그다음 Amazon Bedrock 임베딩 모델로 여러분의 데이터 벡터 임베딩을 생성해 벡터 인덱스에 저장하고, 시맨틱 검색을 수행해요.

시작하려면 아직 AWS 계정이 없다면 계정을 가입하세요. 계정 설정에 대한 자세한 내용은 Getting started with Amazon S3을 참고해 주세요.

1단계: 콘솔로 벡터 버킷 만들기
2단계: 콘솔로 벡터 버킷에 벡터 인덱스 만들기
3단계: SDK for Python(Boto3)으로 벡터 인덱스에 벡터 삽입하기
4단계: SDK for Python(Boto3)으로 벡터 인덱스에서 벡터 질의하기
(선택) S3 Vectors Embed CLI로 벡터 임베딩 생성 자동화하기
(선택) S3 Vectors를 Amazon Bedrock Knowledge Bases와 통합하기
(선택) S3 Vectors를 Amazon OpenSearch와 통합하기

1단계: 콘솔로 벡터 버킷 만들기

S3 벡터 버킷은 벡터를 저장하고 질의하도록 목적 특화된 Amazon S3 버킷의 한 종류예요. 전용 API 작업으로 벡터 데이터를 쓰고 질의해요. IAM 아이덴티티 기반 정책과 리소스 기반 정책 같은 접근 제어 메커니즘으로 벡터 데이터에 대한 접근을 제어할 수 있어요.

이 단계에서는 Amazon S3 콘솔로 첫 번째 벡터 버킷을 만들어요. 벡터 버킷을 만드는 다른 방법은 Creating a vector bucket을 참고해 주세요.

벡터 버킷을 만들려면

AWS Management Console에 로그인하고 Amazon S3 콘솔(https://console.aws.amazon.com/s3/)을 엽니다.
왼쪽 탐색 창에서 Vector buckets를 선택합니다.
Vector buckets 페이지에서 Create vector bucket을 선택합니다.
Create vector bucket 페이지의 Vector bucket name 필드에 이름을 입력합니다. 이 튜토리얼에서는 media-embeddings를 벡터 버킷 이름으로 사용해요. 벡터 버킷 이름은 3자에서 63자 사이여야 하며 AWS 리전 안에서 고유해야 합니다. 유효한 문자는 소문자(a-z), 숫자(0-9), 하이픈(-)입니다. 참고: 벡터 버킷 이름은 버킷을 만든 뒤에는 변경할 수 없어요.
Encryption 아래에서 Specify encryption type을 선택합니다. 암호화 유형을 AWS Key Management Service 키를 사용한 서버 측 암호화(SSE-KMS) 또는 기본값인 Amazon S3 관리형 키를 사용한 서버 측 암호화(SSE-S3)로 지정할 수 있어요. 이 튜토리얼에서는 **Server-side encryption with Amazon S3 managed keys (SSE-S3)**를 선택해요. 벡터 버킷의 암호화 구성 설정에 대한 자세한 내용은 Data protection and encryption in S3 Vectors를 참고해 주세요. 참고: 암호화 유형은 벡터 버킷을 만든 뒤에는 변경할 수 없어요.
Tags (Optional) 아래에서 벡터 버킷을 정리하고 권한을 지정하는 데 도움을 주는 태그를 키-값 쌍으로 추가할 수 있어요. Key와 Value를 입력합니다. 태그를 더 추가하려면 Add Tag를 선택합니다. 벡터 버킷에는 최대 50개의 태그를 입력할 수 있어요. 자세한 내용은 Using tags with S3 vector buckets을 참고해 주세요.
Create vector bucket을 선택합니다.

2단계: 콘솔로 벡터 버킷에 벡터 인덱스 만들기

벡터 인덱스 구성 파라미터는 신중하게 선택하세요. 벡터 인덱스를 만든 뒤에는 인덱스 이름, 차원, 거리 메트릭, 비필터 가능 메타데이터 키를 업데이트할 수 없어요. 이 값들 중 하나라도 바꾸려면 새 벡터 인덱스를 만들어야 해요.

이 단계에서는 벡터 버킷에 벡터 인덱스를 만들어요. 벡터 인덱스는 벡터 임베딩을 저장하고 질의하는 데 사용돼요. 벡터 인덱스에 대한 자세한 내용은 Vector indexes을 참고해 주세요.

벡터 인덱스를 만들려면

Amazon S3 콘솔의 Vector buckets 목록에서 방금 만든 벡터 버킷으로 이동합니다.
Create vector index를 선택합니다.
Create vector index 페이지의 Vector index name 필드에 이름을 입력합니다. 이 튜토리얼에서는 movies를 벡터 인덱스 이름으로 사용해요. 벡터 인덱스 이름은 3자에서 63자 사이여야 하며 이 벡터 버킷 안에서 고유해야 합니다. 유효한 문자는 소문자(a-z), 숫자(0-9), 하이픈(-), 점(.)입니다. 벡터 인덱스 이름은 인덱스 생성 후 변경할 수 없어요.
Dimension 아래에서 벡터 임베딩 모델이 생성하는 각 벡터에 들어갈 숫자 개수를 결정하는 1에서 4096 사이의 값을 지정합니다. 임베딩 모델은 데이터(예: 텍스트, 이미지)를 숫자 벡터로 변환하는 특수 기계 학습(ML) 모델이에요. 임베딩 모델은 보통 각 차원이 부동소수점 숫자인 500에서 2000 차원 사이의 출력을 생성해요. 이 튜토리얼에서는 Amazon Bedrock의 Titan Text v2 임베딩 모델을 사용할게요. 이 임베딩 모델은 기본적으로 1024차원 벡터를 사용하므로 벡터 인덱스의 dimension을 1024로 설정할게요. dimension 값은 인덱스 생성 후 변경할 수 없어요. 임베딩 모델의 권장 사항에 따라 dimension 값을 신중하게 지정하세요.
Distance metric 아래에서 벡터 사이의 유사도를 계산하는 방법을 정의하는 거리 메트릭으로 Cosine(각도 유사도 측정) 또는 Euclidean(직선 거리 측정) 중 하나를 선택합니다. 이 튜토리얼에서는 Cosine을 선택해요. 거리 메트릭은 인덱스 생성 후 변경할 수 없어요. 임베딩 모델의 권장 사항에 따라 거리 메트릭을 신중하게 선택하세요.
Additional settings (optional) 아래에서 벡터 임베딩과 함께 보조 정보를 저장하기 위해 비필터 가능 메타데이터 키를 지정할 수 있어요. 참고: 인덱스를 만든 뒤 벡터 데이터를 삽입할 때 각 벡터에 필터 가능 메타데이터를 키-값 쌍으로 붙일 수 있어요. 기본적으로 벡터에 붙는 모든 메타데이터 키는 필터 가능하며 유사도 질의에서 필터로 쓸 수 있어요. 벡터 인덱스 생성 중에 비필터 가능으로 지정된 메타데이터 키만 필터링에서 제외돼요. 각 비필터 가능 메타데이터 키는 1자에서 63자 사이여야 하며 벡터 인덱스 안에서 고유해야 합니다. 이 키들은 유사도 질의 중 필터링할 필요가 없는 참조 정보를 저장하는 데 유용해요. 예를 들어 텍스트 임베딩 작업을 할 때 참조용으로 원본 텍스트 청크를 보존하고 싶을 수 있어요. 이 튜토리얼에서는 벡터 임베딩을 만들 텍스트 데이터를 저장하기 위해 source_text라는 비필터 가능 메타데이터 키를 추가해요. 비필터 가능 메타데이터 키는 인덱스 생성 후 업데이트할 수 없어요. 메타데이터 구조를 신중히 계획하세요.
Encryption 아래에서 Specify encryption type을 선택합니다. 버킷 수준 암호화 설정을 사용하거나 벡터 인덱스의 암호화 설정을 덮어쓸 수 있어요. 버킷 수준 설정을 덮어쓰는 경우 벡터 인덱스의 암호화 유형을 AWS Key Management Service 키를 사용한 서버 측 암호화(SSE-KMS) 또는 Amazon S3 관리형 키를 사용한 서버 측 암호화(SSE-S3)로 지정할 수 있습니다. 이 튜토리얼에서는 Use bucket settings for encryption을 선택해요. 벡터 버킷과 인덱스의 암호화 구성 설정에 대한 자세한 내용은 Data protection and encryption in S3 Vectors를 참고해 주세요.
Tags (Optional) 아래에서 AWS Billing and Cost Management로 벡터 인덱스 비용을 추적·정리하는 데 쓸 태그를 키-값 쌍으로 추가할 수 있어요. Key와 Value를 입력합니다. 태그를 더 추가하려면 Add Tag를 선택합니다. 벡터 인덱스에는 최대 50개의 태그를 입력할 수 있어요. 자세한 내용은 Using tags with S3 vector buckets을 참고해 주세요.
Create vector index를 선택합니다.

새 벡터 인덱스가 버킷 안에 나타나는지 확인해 주세요.

3단계: SDK for Python(Boto3)으로 벡터 인덱스에 벡터 삽입하기

벡터를 삽입·나열·질의하려면 AWS SDK, AWS CLI, 또는 Amazon S3 REST API를 사용해요.

이 단계에서는 PutVectors API 작업으로 벡터 인덱스에 벡터 임베딩을 삽입해요.

먼저 원하는 임베딩 모델로 벡터 임베딩을 생성해야 해요. Amazon Bedrock을 사용한다면 InvokeModel API 작업으로 원하는 임베딩 모델을 지정해 임베딩을 생성해요. 또는 단일 명령으로 벡터 임베딩을 생성하고 삽입하려면 (선택) S3 Vectors Embed CLI로 벡터 임베딩 생성 자동화하기를 참고해 주세요.

다음 예시 코드는 AWS SDK for Python(Boto3)로 Amazon Bedrock의 Titan Text Embeddings V2 모델로 1024차원 벡터 임베딩을 생성하고, PutVectors API로 여러분의 벡터 인덱스에 저장해요. 각 벡터와 함께 필터 가능 메타데이터로 키-값 쌍을 붙여요. 또한 source_text라는 비필터 가능 메타데이터 키로 각 벡터가 유래된 원본 텍스트를 보존해요. 요청 처리량을 최대화하고 속도·효율성을 최적화하려면 벡터를 일괄(batch)로 삽입·삭제하는 것을 권장해요. 자세한 내용은 S3 Vectors best practices를 참고해 주세요.

# 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 API 작업으로 유사도 검색을 수행할 수 있어요.

먼저 3단계(벡터 인덱스에 벡터 삽입)에서 삽입할 때 사용한 것과 동일한 임베딩 모델로 질의 벡터 임베딩을 생성해야 해요. 이 튜토리얼에서는 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에서 벡터 임베딩 작업을 단순화하는 독립형(standalone) 커맨드라인 도구예요. 단일 명령으로 Amazon Bedrock을 사용해 데이터의 벡터 임베딩을 만들고 S3 벡터 인덱스에 저장·질의할 수 있어요. 이 도구는 다음 명령을 지원해요.

s3vectors-embed put: 텍스트, 파일 내용, 또는 S3 객체의 벡터 임베딩을 생성하고 S3 벡터 인덱스에 벡터로 저장합니다.
s3vectors-embed query: 질의 입력을 임베딩하고 S3 벡터 인덱스에서 유사한 벡터를 검색합니다.

명령과 사용법에 대한 자세한 내용은 Amazon S3 Vectors Embed CLI GitHub 리포지토리를 참고해 주세요.

(선택) S3 Vectors를 Amazon Bedrock Knowledge Bases와 통합하기

Amazon Bedrock Knowledge Bases는 S3 Vectors와 통합해 벡터 데이터셋을 비용 효율적으로 장기 저장해요.

사전 요구 사항 (Prerequisites)

Amazon Bedrock 지식 베이스를 만드는 데 필요한 권한이 있는지 사전 요구 사항을 따르세요.

S3 Vectors와 Amazon Bedrock 서비스 양쪽에 적절한 IAM 권한. S3 Vectors의 IAM 권한에 대한 자세한 내용은 Identity and Access management in S3 Vectors를 참고해 주세요.
지식 베이스에 수집할 소스 문서를 준비해 두세요.
임베딩 모델 요구 사항을 이해하고 있어야 해요.

콘솔에서 S3 Vectors로 Amazon Bedrock 지식 베이스 만들기

Amazon Bedrock Knowledge Bases는 완전 관리형 엔드투엔드 RAG 워크플로를 제공해요. S3 Vectors로 지식 베이스를 만들면 Amazon Bedrock이 S3 데이터 소스에서 데이터를 자동으로 가져오고, 콘텐츠를 텍스트 블록으로 변환하고, 임베딩을 생성하고, 벡터 인덱스에 저장해요. 그런 다음 지식 베이스를 질의하고 소스 데이터에서 검색된 청크를 기반으로 응답을 생성할 수 있어요.

Amazon Bedrock 권한이 있는 IAM 역할로 AWS Management Console에 로그인하고 Amazon Bedrock 콘솔(https://console.aws.amazon.com/bedrock/)을 엽니다.
왼쪽 탐색 창에서 Knowledge Bases를 선택합니다.
Knowledge Bases 섹션에서 Create를 선택합니다. 드롭다운 목록에서 Knowledge Base with vector store를 선택합니다.
이 튜토리얼에서는 Knowledge Base name, Knowledge Base description, IAM permissions을 기본값으로 유지합니다.
Choose a data source type에서 지식 베이스를 연결할 데이터 소스를 선택합니다. 이 튜토리얼에서는 Amazon S3를 선택합니다.
(선택) Tags 또는 Application logs를 제공합니다.
Next를 선택합니다.
Configure data source 페이지에서 이 튜토리얼에서는 Data source name, Data source location, Parsing strategy, Chunking strategy를 기본 설정으로 유지합니다.
S3 URI에서 소스 파일이 들어 있는 S3 일반 용도 버킷을 입력하거나, Browse S3를 선택해 S3 일반 용도 버킷을 선택합니다.
암호화된 S3 데이터의 경우 Add customer-managed KMS key for S3 data를 선택하고 고객 관리형 KMS 키를 지정합니다.
Next를 선택해 Embeddings 모델과 Vector store 옵션을 지정하는 다음 단계로 진행합니다.
Embeddings model 섹션에서 Select model을 선택하고 S3 Vectors와 호환되는 임베딩 모델을 선택합니다. 부동소수점(float) 임베딩을 사용해야 합니다. 이진(binary) 유형은 지원되지 않아요.
(선택) Additional configurations 섹션을 펼쳐 다음 구성 옵션을 확인합니다(모든 모델이 모든 구성을 지원하지는 않아요).
- Embeddings type – 데이터를 부동소수점(float32) 벡터 임베딩(더 정밀하지만 비용이 더 높음)이나 이진 벡터 임베딩(덜 정밀하지만 비용이 더 낮음)으로 변환할지 여부. S3 Vectors와 통합하려면 Floating-point vector embeddings를 선택해야 합니다.
- Vector dimensions – 임베딩 모델이 권장하는 차원 크기를 선택합니다.
Vector store 섹션에서 권장 방식인 Quick create a new vector store를 선택해 새 벡터 버킷을 자동 설정하거나, Use an existing vector store를 선택해 사용 가능한 기존 벡터 버킷을 사용합니다. 기존 벡터 스토어 흐름 사용에 대한 정보는 Amazon Bedrock User Guide의 Prerequisites for using a vector store you created for a knowledge base를 참고해 주세요.
Additional configurations – 기본적으로 벡터 버킷은 Amazon S3 관리형 키를 사용한 서버 측 암호화(SSE-S3)를 사용해요. 암호화 설정을 더 잘 제어하려면 AWS Key Management Service 키를 사용한 서버 측 암호화(SSE-KMS)로 여러분의 KMS 키를 사용하도록 선택할 수 있어요.
Next를 선택해 Knowledge Base 세부 정보를 검토한 뒤 Create Knowledge Base를 선택합니다.

지식 베이스를 만드는 데 걸리는 시간은 특정 구성에 따라 달라져요. 지식 베이스 생성이 완료되면 지식 베이스 상태가 ready 또는 available로 바뀌어요. 지식 베이스가 ready·available 상태가 되면, 처음으로 또는 콘텐츠를 최신으로 유지하려고 할 때마다 데이터 소스를 동기화하세요. 데이터 소스를 동기화하려면 콘솔에서 지식 베이스를 선택하고 데이터 소스 개요 섹션에서 Sync를 선택합니다.

(선택) S3 Vectors를 Amazon OpenSearch와 통합하기

Amazon OpenSearch Service는 AWS 클라우드에서 OpenSearch의 배포·확장·운영을 단순화하는 완전 관리형 서비스예요. S3 Vectors와 OpenSearch 사이에는 두 가지 통합이 있어요. 하나는 고성능 검색을 위해 S3 Vectors에서 OpenSearch Serverless로 벡터 데이터를 내보내는 것이고, 다른 하나는 OpenSearch 기능에 계속 접근하면서 S3 Vectors를 OpenSearch 안의 비용 효율적인 스토리지 엔진으로 사용하는 것이에요.

자세한 내용은 Using S3 Vectors with OpenSearch Service를 참고해 주세요.

튜토리얼: S3 Vectors 시작하기