환각 현상이 있는 API 호출 없이, S3 Vectors를 사용하여 Bedrock RAG 지식 기반(knowledge base)을 프로비저닝하기.

만약 AI 코딩 에이전트에게 AWS 설정을 요청해 본 적이 있다면, 에이전트가 자신만만하게 존재하지 않는 파라미터를 만들어내거나, 더 이상 사용되지 않는(deprecated) 서비스를 호출하거나, 학습 데이터에 없었던 서비스에 대해 10분 동안 재시도하며 시간을 허비하는 모습을 본 적이 있을 것입니다. 가장 뼈아픈 실패 유형은 바로 '조용한 실패'입니다. 에이전트는 자신이 성공했다고 생각하고, 당신은 한 시간 뒤에야 그 사실을 알게 됩니다.

저는 Amazon S3 Vectors를 기반으로 하는 Amazon Bedrock Knowledge Base를 사용하여 LangGraph 지원 봇의 검색 레이어(retrieval layer)를 구축하는 과정에서 이러한 실수를 두 번 겪었습니다. 제가 깊은 AWS 전문 지식 덕분에 이 두 가지를 잡아냈다고 말하고 싶지만, 사실은 Agent Toolkit for AWS가 제가 읽지 않았던 문서를 읽어주었기 때문에 잡아낼 수 있었습니다. 두 실수 모두 그대로 방치했다면 배포되었을 것이고, 둘 다 실패했을 것입니다.

30초 설정

목표: 마크다운(markdown) 제품 문서 폴더를 의미 기반으로 쿼리할 수 있게 만들어, 에이전트가 추측하는 대신 실제 문서를 바탕으로 "이 제품이 염색 모발에 안전한가요?"와 같은 질문에 답할 수 있도록 하는 것입니다. 에이전트에게 무언가를 지어내게 하는 대신, 검색할 수 있는 도서관을 제공하는 것이라고 생각하면 됩니다. 이것이 RAG의 검색(retrieval) 단계이며, 나중에 LangGraph 에이전트가 도구(tool)로 호출하게 될 토대입니다.

하나의 관리형 서비스로 묶인 네 가지 구성 요소:

• 소스 버킷 (Source bucket): 문서를 담고 있는 S3 버킷.
• 임베딩 (Embeddings): Amazon Titan Text Embeddings V2 (1024차원 벡터).
• 벡터 스토어 (Vector store): Amazon S3 Vectors. OpenSearch Serverless 대신 이를 선택한 이유는 항상 켜져 있는 컴퓨팅 자원이 없기 때문입니다. 이는 유휴 상태로 머무는 데모 환경에서 몇 센트와 예상치 못한 월간 비용 사이의 차이를 만듭니다.
• 지식 기반 (Knowledge Base): Amazon Bedrock Knowledge Bases는 이 모든 것을 하나로 묶어 retrieve 호출로 쿼리할 수 있는 하나의 단위로 만들어 줍니다.

함께 따라 해보려면 AWS 계정, 로컬에 자격 증명이 구성된 비루트(non-root) IAM ID, uv 설치, 그리고 에이전트에 툴킷(toolkit)이 설치되어 있어야 합니다. Kiro, Claude Code, Cursor, Codex를 사용하는 가장 빠른 방법은 AWS CLI 설치 프로그램인 aws configure agent-toolkit을 사용하는 것입니다. Kiro에서는 대신 AWS MCP Server를 .kiro/settings/mcp.json에 추가하고(mcp-proxy-for-aws 버전을 고정), npx skills add aws/agent-toolkit-for-aws/skills를 실행할 수 있습니다. 이 툴킷은 사용자가 이미 사용 중인 에이전트에 연결되어 필요할 때마다 작업별 _스킬(skills)_을 로드합니다. 저는 지식 기반(Knowledge Base) 구축을 위한 검증된 최신 절차를 포함하고 있는 amazon-bedrock 스킬을 사용했습니다. 여기서

ValidationException: 지정된 인덱스를 찾을 수 없습니다 (S3Vectors 404)

S3 Vectors 문서에 명시된 실제 요구 사항은 다음과 같습니다: 사용자가 직접 인덱스를 생성해야 하며, Bedrock이 청크 텍스트(chunk text)와 메타데이터(metadata)를 저장하는 데 사용하는 두 개의 **필터링 불가능한 메타데이터 키 (non-filterable metadata keys)**를 반드시 선언해야 합니다. 이를 누락하면 나중에 원인과 거리가 먼 모호한 오류와 함께 데이터 주입 (ingestion) 단계에서 실패하게 됩니다. 올바른 명령어는 다음과 같습니다:

aws s3vectors create-index \
  --vector-bucket-name <VECTOR_BUCKET> \
  --index-name <INDEX_NAME> \
...

이 사례는 왜 최신 문서가 중요한지를 가장 잘 보여줍니다. S3 Vectors는 2025년에 출시되었기 때문에, 이 요구 사항은 대부분의 모델 학습 데이터에 포함되어 있지 않습니다. 툴킷 (toolkit)이 없는 에이전트라면 인덱스를 생성하고 성공했다고 생각하겠지만, 데이터 주입 시점에 벽에 부딪힐 것이며, 결국 잘못된 설정으로 인덱스를 다시 생성하느라 오후 시간을 허비하게 될 것입니다. 여기서 차원 (dimension, 1024)과 거리 측정 방식 (distance metric) 또한 임의로 정할 수 있는 것이 아닙니다. 이는 Titan 임베딩 모델 (embedding model)과 일치해야 하며, 에이전트가 추측에 의존할 때 흔히 실수하는 리소스 간 제약 조건 (cross-resource constraint) 중 하나입니다.

나머지는 순조롭게 진행되었고, 정상 작동합니다

앞선 두 가지 문제를 해결하자, 검증된 절차에 따라 깔끔하게 실행되었습니다: IAM 서비스 역할 (service role) 생성 (다른 고객이 해당 역할을 속여 자신의 리소스에 접근하지 못하도록 bedrock.amazonaws.com에 confused-deputy 조건을 부여하고, Titan 호출, 버킷 읽기, 벡터 인덱스 사용을 위한 최소 권한 (least-privilege) 부여), 지식 기반 (Knowledge Base) 생성, 고정 크기 청킹 (fixed-size chunking, 300 토큰, 20% 중첩)을 적용한 S3 데이터 소스 연결, 그리고 데이터 주입 (ingestion) 실행. 결과: 10/10개 문서 인덱싱 완료, 실패 제로.

그 증거는 검색 쿼리 (retrieval query)입니다:

aws bedrock-agent-runtime retrieve \
  --knowledge-base-id <KB_ID> \
  --retrieval-query '{"text":"Is the Curl Cream safe for color-treated hair?"}' \
...

가장 유사도가 높은 결과가 **0.86 유사도 (similarity)**로 반환되었으며, 정답이 포함된 정확한 제품 문서가 검색되었습니다. 라이브러리가 제대로 채워졌습니다.

이를 통해 얻은 것, 그리고 다르게 했을 점

이를 통해 얻은 것, 그리고 다르게 했을 점

demo와 툴킷을 제외하고 살펴보니 두 가지 변화가 있었습니다. 첫째, 에이전트에게 검증된 설정 순서(setup order)를 미리 제공받았고 (시행착오 과정 없음), 둘째, 몇 달 전에 학습된 모델로는 알 수 없는 두 가지 실수를 잡아냈습니다. 이는 AWS가 유지 관리하는 최신 문서를 확인하고 절차를 배포하기 때문입니다. AWS에 따르면 개발자들은 이를 사용하면서 반복 횟수와 오류가 줄어든다고 보고하며, 이번 빌드에서 이 두 가지 발견만으로 저의 오후 시간을 아낄 수 있었습니다.

두 가지 솔직한 미흡점(gap)이 있습니다. 첫째, 툴킷 자체 규칙은 직접적인 CLI 명령어 사용보다 Infrastructure-as-Code를 권장하는데, 저는 이를 따르지 않았습니다. CLI 호출을 실행하고 해체(teardown)를 위해 태그가 지정된 매니페스트에 기록했습니다. 작동은 하지만, 독자가 복제할 수 있는 재현 가능한 아티팩트는 CDK나 CloudFormation이 될 것입니다. 둘째, IAM 역할의 신뢰 정책(trust policy) 범위를 특정 KB ID 대신 knowledge-base/*로 설정했습니다. 이 aws:SourceArn을 더 엄격하게 제한하는 것이 이것이 단순한 데모가 되기 전에 당연히 거쳐야 할 강화 조치입니다.

다음 단계는 무엇인가요 (What's next)

여기는 검색(retrieval) 기반일 뿐, 전체 애플리케이션은 아닙니다. 구체적인 두 가지 다음 단계가 있으며, 이 중 어느 것을 선택할 수 있습니다:

1. 루프를 닫기 (Close the loop). LangGraph 에이전트를 연결하여 이 Knowledge Base를 도구(tool)로 호출하게 만듭니다. 이렇게 하면 정보를 검색하고 근거 기반 답변을 생성하는 것이 가능해집니다. 이때 'RAG 지식 기반'은 'RAG 애플리케이션'으로 발전합니다.
2. 재현 가능하게 만들기 (Make it reproducible). 임시적인 CLI 프로비저닝을 CDK나 CloudFormation으로 변환하여, 툴킷 자체 규칙이 권장하는 방식대로 전체 스택이 하나의 명령어로 구축되고 해체되도록 합니다.

만약 한 가지를 가져가야 한다면: 이 툴킷의 진정한 가치는 단순히 명령어를 입력해 주는 것이 아니라, AI 에이전트가 놓치기 쉬운 것들(심지어 몇 시간 후에야 발견하는 방식)에 대해 최신 문서를 기반으로 더 나은 결정을 내리게 한다는 점입니다.