자습서: 첫 번째 벡터 검색

벡터 인덱스과 함께 테이블을 생성합니다. 그러면 DescriptionVector 속성에 DescriptionIndex라는 벡터 인덱스가 있는 Products 테이블이 생성됩니다. 인덱스는 Titan Text Embeddings V2 출력과 일치하도록 1,024차원과 COSINE 거리 함수를 사용합니다. 벡터 인덱스 파티션 키가 정의되지 않았으므로 검색하는 데 SearchConditionExpression이 필요하지 않습니다.

aws dynamodb create-table \
    --table-name Products \
    --attribute-definitions AttributeName=ProductId,AttributeType=S \
    --key-schema AttributeName=ProductId,KeyType=HASH \
    --billing-mode PAY_PER_REQUEST \
    --vector-indexes \
        "[
            {
                \"IndexName\": \"DescriptionIndex\",
                \"VectorAttribute\": {\"AttributeName\": \"DescriptionVector\"},
                \"Projection\": {\"ProjectionType\": \"ALL\"},
                \"Dimensions\": 1024,
                \"DistanceFunction\": \"COSINE\"
            }
        ]"

이 예제에서는 모든 속성을 검색 결과에 사용할 수 있도록 ProjectionType에 ALL을 사용합니다. INCLUDE를 대신 사용하는 경우 프로젝션된 비 키 속성 예산이 공유됩니다. 벡터 속성이 하나의 속성으로 계산되고 각 INLINE_FILTER 검색 스키마 요소가 하나의 속성으로 계산됩니다. HASH 검색 스키마 요소는 제한에 포함되지 않습니다.

인덱스가 활성화될 때까지 대기합니다. IndexStatus가 ACTIVE로 될 때까지 이 작업을 실행합니다.

aws dynamodb describe-table \
    --table-name Products \
    --query 'Table.VectorIndexes[0].[IndexName,IndexStatus,Backfilling]'

이 자습서에서와 같이 CreateTable의 일부로 생성된 인덱스의 경우 Backfilling이 보고되지 않고 명령이 해당 인덱스에 대해 null을 반환합니다. 이 경우 IndexStatus만 단독으로 신호로 사용합니다.

Backfilling은 UpdateTable을 사용하여 기존 테이블에 추가하는 벡터 인덱스에 대해 보고됩니다. 이 경우 전체 검색 결과를 사용하기 전에 IndexStatus가 ACTIVE이고 Backfilling이 false가 될 때까지 대기합니다.

제품 카탈로그를 생성합니다. 다음 50개 제품을 products.tsv라는 탭으로 구분된 파일에 저장합니다. 각 줄에는 제품 ID, 이름, 단일 문장 설명이 들어 있습니다. 카탈로그에는 5개의 관련 제품으로 구성된 그룹이 10개 포함되어 있으므로 마지막 단계의 검색 결과를 쉽게 해석할 수 있습니다.

p01	Insulated Travel Mug	A vacuum insulated stainless steel mug that keeps hot drinks warm for up to twelve hours.
p02	Stovetop Espresso Maker	A compact aluminum pot that brews strong espresso style coffee directly on a gas or electric burner.
p03	Manual Burr Coffee Grinder	A hand cranked grinder with adjustable ceramic burrs for consistent coffee grounds.
p04	Pour Over Coffee Dripper	A ceramic cone that sits on a mug and brews a single cup of filter coffee.
p05	Electric Milk Frother	A handheld battery powered whisk that creates dense foam for lattes and cappuccinos.
p06	Lightweight Running Shoe	A breathable mesh road shoe with cushioned foam midsole for daily training runs.
p07	Trail Running Shoe	An aggressive lugged outsole shoe built for grip on loose gravel and muddy trails.
p08	Moisture Wicking Running Socks	Ankle height socks knitted from synthetic yarn that pulls sweat away from the skin.
p09	Reflective Running Vest	A lightweight vest with high visibility strips for running safely after dark.
p10	Hydration Waist Belt	An elastic belt that holds two small water flasks and a phone during long runs.
p11	Ergonomic Mesh Office Chair	An adjustable desk chair with breathable mesh back and lumbar support for long work sessions.
p12	Sit Stand Desk Converter	A height adjustable platform that raises a monitor and keyboard for standing work.
p13	Monitor Arm Mount	A clamp mounted articulating arm that lifts a display off the desk surface.
p14	Under Desk Footrest	An angled cushioned platform that supports the feet and improves seated posture.
p15	Wireless Split Keyboard	A two piece keyboard that separates for a natural shoulder width typing position.
p16	Noise Cancelling Headphones	Over ear wireless headphones that actively silence engine noise on long flights.
p17	Wireless Earbuds	Compact in ear buds with a charging case and multi hour battery for commuting.
p18	Portable Bluetooth Speaker	A water resistant rechargeable speaker sized to fit in a backpack side pocket.
p19	Studio Monitor Headphones	Wired closed back headphones with flat frequency response for audio mixing.
p20	Wired Lapel Microphone	A small clip on microphone for recording clear speech during interviews.
p21	Four Season Backpacking Tent	A double wall tent with an aluminum pole set rated for wind and heavy rain.
p22	Down Sleeping Bag	A mummy shaped bag filled with compressible down insulation for cold weather camping.
p23	Inflatable Sleeping Pad	A lightweight pad that inflates in a few breaths and packs down to bottle size.
p24	Canister Camping Stove	A screw on burner that boils water quickly using a compact fuel canister.
p25	Rechargeable Camp Lantern	A collapsible lantern with adjustable brightness and a built in battery.
p26	Cast Iron Skillet	A preseasoned heavy pan that holds heat evenly for searing and oven baking.
p27	Nonstick Frying Pan	A coated aluminum pan that releases eggs and fish without added oil.
p28	Stainless Steel Stock Pot	A tall wide pot for boiling pasta and simmering large batches of soup.
p29	Enameled Dutch Oven	A heavy lidded pot that moves from stovetop to oven for slow braising.
p30	Bamboo Cutting Board	A large reversible board with a juice groove around the edge.
p31	Padded Laptop Backpack	A water resistant pack with a suspended sleeve that protects a fifteen inch laptop.
p32	Slim Laptop Sleeve	A close fitting neoprene case that shields a notebook inside a larger bag.
p33	Rolling Carry On Suitcase	A hard shell four wheel case sized to fit most overhead cabin bins.
p34	Packing Cube Set	Zippered fabric cubes that compress clothing and organize a suitcase.
p35	Leather Messenger Bag	A single strap shoulder bag with a padded compartment and interior pockets.
p36	Daily Facial Moisturizer	A light lotion with humectants that hydrates skin without leaving residue.
p37	Mineral Sunscreen Lotion	A broad spectrum zinc based sunscreen formulated for sensitive facial skin.
p38	Gentle Foaming Cleanser	A low pH face wash that removes oil and sunscreen without stripping the skin.
p39	Vitamin C Serum	A brightening serum applied before moisturizer to even skin tone over time.
p40	Overnight Repair Cream	A rich night cream with ceramides that restores the skin barrier while sleeping.
p41	Stainless Steel Dog Bowl	A weighted nonslip bowl that resists tipping during enthusiastic feeding.
p42	Padded Dog Harness	An adjustable chest harness that distributes pull away from the neck on walks.
p43	Retractable Dog Leash	A spring loaded leash that extends and locks at several walking lengths.
p44	Interactive Cat Puzzle Feeder	A slow feed tray that makes a cat work for dry food and eat more slowly.
p45	Self Cleaning Litter Box	An enclosed box with a raking mechanism that sifts waste after each use.
p46	Bypass Pruning Shears	Sharp hardened blades that make clean cuts on green stems and small branches.
p47	Long Handled Garden Spade	A steel bladed spade with a wooden shaft for turning soil and digging beds.
p48	Adjustable Hose Spray Nozzle	A metal nozzle that shifts from a fine mist to a strong jet stream.
p49	Raised Garden Bed Kit	Interlocking cedar panels that assemble into an elevated planting box.
p50	Drip Irrigation Starter Kit	Tubing and emitters that deliver water slowly to the base of each plant.

세 필드 사이의 구분 기호는 리터럴 탭 문자여야 합니다. 브라우저에서 카탈로그를 복사하는 경우 계속하기 전에 탭이 유지되는지 확인합니다.

하나의 제품에 대한 임베딩을 생성합니다. 먼저 단일 임베딩 호출을 실행하여 Amazon Bedrock 모델 액세스 권한이 작동하는지 확인합니다. inputText 필드에는 임베드할 텍스트가 포함되어 있고, dimensions는 출력 크기를 설정하고(유효한 값은 256, 512 또는 1024), normalize는 코사인 유사성 검색에 권장되는 단위 길이 벡터를 생성합니다.

mkdir -p emb

aws bedrock-runtime invoke-model \
    --model-id amazon.titan-embed-text-v2:0 \
    --body '{"inputText":"A vacuum insulated stainless steel mug that keeps hot drinks warm for up to twelve hours.","dimensions":1024,"normalize":true}' \
    --cli-binary-format raw-in-base64-out \
    --content-type application/json \
    --accept application/json \
    emb/p01.json

--cli-binary-format raw-in-base64-out 플래그는 필수입니다. AWS CLI v2는 기본적으로 바이너리 파라미터에 대해 base64 인코딩을 사용하므로 이 플래그가 없으면 원시 JSON 본문이 올바르게 전송되지 않습니다. 응답은 emb/p01.json에 작성되며 1,024개의 부동 소수점 숫자로 구성된 embedding 배열을 포함합니다. 차원 수를 확인합니다.

jq '.embedding | length' emb/p01.json

출력은 1024입니다.

첫 번째 제품을 작성합니다. 임베딩을 DynamoDB 항목 형식으로 변환하고 기록합니다. 저장된 벡터 속성은 각 숫자를 N 유형으로 래핑하는 DynamoDB L(목록) 유형을 사용합니다.

jq '{"ProductId":{"S":"p01"},"Title":{"S":"Insulated Travel Mug"},"DescriptionVector":{"L":[.embedding[]|{"N":(.|tostring)}]}}' emb/p01.json > item-p01.json

aws dynamodb put-item --table-name Products --item file://item-p01.json

나머지 제품을 임베드합니다. 이 루프는 나머지 제품 각각에 대한 임베딩을 생성합니다. 이미 존재하는 모든 파일을 건너뛰므로 호출이 실패할 경우 루프를 안전하게 다시 실행할 수 있습니다.

while IFS=$'\t' read -r id title description; do
    [ -s "emb/$id.json" ] && continue
    body=$(jq -n --arg t "$description" '{inputText:$t,dimensions:1024,normalize:true}')
    aws bedrock-runtime invoke-model \
        --model-id amazon.titan-embed-text-v2:0 \
        --body "$body" \
        --cli-binary-format raw-in-base64-out \
        --content-type application/json \
        --accept application/json \
        "emb/$id.json" >/dev/null || echo "FAILED $id"
done < products.tsv

ls emb/*.json | wc -l

계속하려면 개수가 50이어야 합니다. 호출이 FAILED를 출력한 경우 루프를 다시 실행합니다. 루프는 누락된 파일만 다시 시도합니다.

나머지 제품을 로드합니다. 각각 25개의 항목으로 구성된 요청 페이로드를 빌드합니다. 이는 BatchWriteItem에서 허용하는 최대값입니다.

batch=0
count=0
echo -n '{"Products":[' > batch-0.json
while IFS=$'\t' read -r id title description; do
    if [ "$count" -eq 25 ]; then
        echo ']}' >> "batch-$batch.json"
        batch=$((batch+1)); count=0
        echo -n '{"Products":[' > "batch-$batch.json"
    fi
    [ "$count" -gt 0 ] && echo -n ',' >> "batch-$batch.json"
    jq -c --arg id "$id" --arg title "$title" \
        '{PutRequest:{Item:{ProductId:{S:$id},Title:{S:$title},
          DescriptionVector:{L:[.embedding[]|{"N":(.|tostring)}]}}}}' \
        "emb/$id.json" >> "batch-$batch.json"
    count=$((count+1))
done < <(tail -n +2 products.tsv)
echo ']}' >> "batch-$batch.json"

루프는 파이프가 아닌 리디렉션에서 읽습니다. 파이프된 while 루프는 일부 쉘의 하위 쉘에서 실행되어 batch 및 count 값을 무시하고 잘못된 배치 파일을 생성하기 때문입니다.

각 배치를 제출합니다. BatchWriteItem은 부분적으로 성공할 수 있으므로 UnprocessedItems에서 반환되는 모든 항목을 다시 제출합니다.

for f in batch-*.json; do
    cp "$f" pending.json
    for attempt in 1 2 3 4 5; do
        aws dynamodb batch-write-item \
            --request-items file://pending.json \
            --output json > resp.json
        left=$(jq '(.UnprocessedItems.Products // []) | length' resp.json)
        echo "$f attempt $attempt: unprocessed=$left"
        [ "$left" -eq 0 ] && break
        jq '.UnprocessedItems' resp.json > pending.json
        sleep 2
    done
done

50개 항목이 모두 있는지 확인합니다.

aws dynamodb scan --table-name Products --select COUNT --query 'Count'

쿼리 임베딩을 생성하고 검색합니다. 저장된 항목에 사용한 것과 동일한 모델 및 차원 수로 검색 구문을 임베딩합니다.

aws bedrock-runtime invoke-model \
    --model-id amazon.titan-embed-text-v2:0 \
    --body '{"inputText":"How can I make my desk more comfortable to work at","dimensions":1024,"normalize":true}' \
    --cli-binary-format raw-in-base64-out \
    --content-type application/json \
    --accept application/json \
    embedding-query.json

jq '[.embedding[]|{"N":(.|tostring)}]' embedding-query.json > query-vector.json

aws dynamodb search-vectors \
    --table-name Products \
    --index-name DescriptionIndex \
    --search-vector file://query-vector.json \
    --top-k 5 \
    --projection-expression "ProductId, Title" \
    --return-consumed-capacity TOTAL

쿼리 벡터와 저장된 벡터는 동일한 임베딩 모델에서 가져와야 하며 동일한 수의 차원을 가져야 합니다. 다른 모델 또는 차원 수를 사용하면 의미 없는 결과 또는 검증 오류가 발생합니다.

결과를 확인합니다. DynamoDB는 유사성을 기준으로 정렬된 결과를 반환합니다. 즉, 가장 유사한 항목을 먼저 표시합니다. 각 결과에는 프로젝션된 Item 속성과 Score가 포함됩니다.

{
    "SearchResults": [
        {
            "Item": {
                "ProductId": { "S": "p11" },
                "Title": { "S": "Ergonomic Mesh Office Chair" }
            },
            "Score": 0.6130197048187256
        },
        {
            "Item": {
                "ProductId": { "S": "p12" },
                "Title": { "S": "Sit Stand Desk Converter" }
            },
            "Score": 0.781868577003479
        },
        {
            "Item": {
                "ProductId": { "S": "p14" },
                "Title": { "S": "Under Desk Footrest" }
            },
            "Score": 0.816369354724884
        },
        {
            "Item": {
                "ProductId": { "S": "p13" },
                "Title": { "S": "Monitor Arm Mount" }
            },
            "Score": 0.8283305168151855
        },
        {
            "Item": {
                "ProductId": { "S": "p15" },
                "Title": { "S": "Wireless Split Keyboard" }
            },
            "Score": 0.8469693064689636
        }
    ],
    "ConsumedCapacity": {
        "VectorSearchRequestBytes": 31449.0
    }
}

점수는 임베딩 모델과 정확한 입력 텍스트에 따라 달라지므로 실제 값은 약간 다를 것입니다. 어떤 항목을 어떤 순서로 선택했는지가 중요합니다. 쿼리에 의자, 모니터 또는 키보드라는 단어가 포함되지 않았지만 검색 결과에는 카탈로그의 다른 45개 항목보다 5개의 책상 및 사무용 제품이 먼저 반환되었습니다. 커피, 캠핑 또는 반려동물 그룹의 항목은 표시되지 않습니다.

다른 쿼리를 시도하여 다른 그룹에서도 동일한 동작이 발생하는지 확인합니다. "Something to brew fresh coffee at home"를 사용하여 이전 단계를 반복하면 최상위 결과는 에스프레소 메이커, 커피 드리퍼, 우유 거품기입니다. "Keeping my dog safe on walks"를 사용하여 반복하면 리드줄과 하네스가 먼저 나오고, 그 다음에는 관련성이 떨어지는 항목이 나옵니다. 카탈로그에는 밀접하게 관련된 제품이 두 개만 포함되어 있기 때문입니다. 마지막 사례는 주목할 가치가 있습니다. 카탈로그에 일치하는 항목이 많지 않더라도 검색은 항상 요청한 항목 수를 반환합니다. 결과 수가 아닌 Score 값을 사용하여 일치 품질을 판단합니다.

점수를 판독하는 방법은 인덱스가 사용하는 거리 함수에 따라 달라집니다.

이 인덱스는 COSINE을 사용하므로 첫 번째 결과의 점수가 가장 낮습니다. 저장된 설명과 동일한 텍스트로 검색하면 점수가 0 또는 거의 0인 항목이 먼저 반환됩니다.