🪣
S3 Vectors+Knowledge BaseでFilterable metadataのサイズについて怒られた【S3 Vectors】

2025/08/02に公開
 はじめにどうも、bunbookです。普段はAWSのAI系サービスをメインに扱っています。Xも良ければフォローしてください。↓
https://x.com/mtbambooygo
前回の記事↓
https://zenn.dev/mtaerohand/articles/d67e98cddd2cae

 結論急いでいる人用。
Knowledge Base+S3 VectorでデータのSync時に発生するFilterable metadata must have at most 2048 bytesのエラーは、S3 Vector BucketをKnowledge Base作成フローのQuick create a new vector store - Recommendedから作れば基本的に解消される。
また、既存のVectorバケットを利用する場合は、Index作成時にAMAZON_BEDROCK_TEXTをNon-filterable metadataに設定する。

 やったこと最近S3 Vectorsが登場したので自分もKnowledge Baseのベクターストアに試してみたのですが、Knowledge Baseのparsingやchunkingの設定はデフォルトのまま、自前で作成したS3 Vector Bucketを使用したら、ごく一般的なPDFの取り込みが頻繁に（私のデータでは19/20）失敗しました。
エラーは以下。
Encountered error: Invalid record for key '#vector-key': Filterable metadata must have at most 2048 bytes (Service: S3Vectors, Status Code: 400, Request ID: #request-id) (SDK Attempt Count: 1). Call to Amazon S3 Vectors did not succeed.
Filterable metadataを2KB以下にしろ、と言われています。おそらくS3 Vectorsでベクターデータにひっついているメタデータであり、Knowledge Baseが自動で生成したものが許可されているサイズをオーバーしているよう。
特段変わった設定はしていないしデータも普通のPDFなので、Previewとはいえリリースされたサービスでここまで頻繁に失敗するのは変な気がします。
今回はこの問題の根本原因を探りつつ、Knowledge BaseでS3 Vectorsをベクターストアにした場合のメタデータ構造とS3 Vectorsの制約について調査しました。

 Filterable metadata
https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors.html
公式ドキュメントによれば、S3 Vectorsはメタデータによる検索結果のフィルタリングに対応しており、メタデータは項目ごとに
Filterable metadata:
Filterable metadata allows you to filter query results based on specific metadata values.

Non-filterable metadata:
Non-filterable metadata can't be used in query filters but can store larger amounts of contextual data than filterable metadata.

に分かれています。すべての項目はデフォルトでfilterableであり、non-filterableとするにはS3 Vector Bucketのインデックス作成時に明示的に項目名を設定する必要があります。
また、公式ドキュメントのLimitations and restrictionsのページを読むと、メタデータに関して以下の制約があります。

Total metadata per vector: Up to 40 KB (filterable + non-filterable)
Total metadata keys per vector: Up to 10
Filterable metadata per vector: Up to 2 KB
Non-filterable metadata keys per vector index: Up to 10

https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-limitations.html
今回はFilterable metadata per vector: Up to 2 KBに引っかかっていると思われます。

 メタデータを見てみる取り込みに失敗したドキュメントは見られませんが、いくつかは成功しているのでメタデータを取得してみます。
マネコンからは見られないのでAWS CLIから取得します。
> aws s3vectors list-vectors --vector-bucket-name s3-vector-bucket-mt --index-name s3-vector-index-mt --return-metadata

{
    "vectors": [
        {
            "key": "91293f67-0c6b-4fa6-b886-26d2a6b7e99b",
            "metadata": {
                "x-amz-bedrock-kb-data-source-id": "YK35GCMH1R",
                "AMAZON_BEDROCK_METADATA": "{\"text\":null,\"author\":\"USAID/Global Health\",\"createDate\":\"2005-03-21T21:09:00Z\",\"modifiedDate\":\"2005-03-21T21:10:33Z\",\"source\":{\"sourceLocation\":\"s3://sample-s3-data-mt/2ED27NR7CISW7J4PHXXBZ6OFPVDFHMFB.pdf\",\"sourceType\":null},\"descriptionText\":\"List of global health country contacts for the Africa Region\",\"pageNumber\":null,\"pageSizes\":null,\"graphDocument\":{\"entities\":[]},\"parentText\":null,\"relatedContents\":null,\"sourceDocumentId\":\"3iZM3cb0ujHBZuHVqse+Rn9KS9S3LwGv7OcxDfY0vAKocKl9EJ8TCSWzrHt53BQi\",\"additionalMetadata\":null}",
                "x-amz-bedrock-kb-source-uri": "s3://sample-s3-data-mt/2ED27NR7CISW7J4PHXXBZ6OFPVDFHMFB.pdf",
                "AMAZON_BEDROCK_TEXT": "AFR Bureau Desk Officer     Priority     South Africa Celeste Carr (202-712-4802) Julie Wallace (202-712-0428)     Shanti Conly, Julie Wallace     Julie Wallace Hope Sukin GH Senior Staff     Lorie Dobbins, AFR/SA     PEPFAR TB     Sudan Willa Pressman (202- 712-0187) Trent Ruebush (202- 712-5734)     Lisa Maniscalco Willa Pressman     Hope Sukin, Mary Harvey     Richard Greene     Ami Helson AFR/EA     Tanzania Willa Pressman (202-712-0187) Mark Austin (202-712-1001) Tanvi Pandit (202-712-4943)     Katherine Kripke, Peter Salama     Willa Pressman     Subhi Mehdi Scott Radloff Krista Desgranges AFR/EA     PEPFAR Malaria PRH     Uganda Krista Stewart (202-712-0808) Laura Harley (202-712-5024)     Neen Alrutz, Krista Stewart     Patricia Mengech     Ishrat Husain Roxana Rogers     Krista Desgranges AFR/EA     PEPFAR TB Malaria PRH MCH     WARP Alan Bornbusch (202-712- 4691) Nancy McCharen (202-712-1894)     Janean Martin Nancy",
                "x-amz-bedrock-kb-document-page-number": 4.0
            }
        },
...
バケットに入っているベクターデータのメタデータ一覧が返ってきます。
見ると、以下の項目があります。
"x-amz-bedrock-kb-data-source-id": Knowledge Baseで設定するデータソースに払い出されるID
"AMAZON_BEDROCK_METADATA": 作成・更新日時やデータソースの情報などメタデータ的な情報が入っている
"x-amz-bedrock-kb-source-uri": チャンクの元ファイルとなるPDFのURI
"AMAZON_BEDROCK_TEXT": チャンクのテキスト
"x-amz-bedrock-kb-document-page-number": チャンクが元ファイルで所属するページ
項目ごとにfilterable、non-filterableの情報を取得するオプションは無かったのですが、特にnon-filterableの設定はしていないので全項目filterableな前提で考えます（※判定する方法はありますし実際filterableなのですが、それは後でやります）。
これらを連結した文字列が2KBを越えているとエラーが発生します。試しに2つのメタデータの文字数を計ると1818文字、1976文字でした。
UTF-8ならアルファベット1文字=1Bなので、2KB=2048Bの上限に結構近いです。これは明らかにエラーの原因っぽいです。
PDFをS3 Vector Bucketに取り込むには、分割されたすべてのチャンクの埋め込みのメタデータがこの2KBのチェックをパスする必要があるため、大半のファイルが取り込みに失敗したことも納得できます。
メタデータで一番大きいのはAMAZON_BEDROCK_TEXTに入っている、埋め込みの原文となるチャンクテキストです。ここをどうにかする必要があります。
自分は最初、Knowledge Baseのチャンク戦略を変更して、100トークンの固定長チャンキングを試してみました。英文だと1トークンは3~5文字程度なので大分メタデータのサイズを抑えることができます。実際、この対処でPDFは無事全て取り込むことができました。
しかし、そもそもS3 Vectors+Bedrock Knowledge Baseの利用に短い固定長チャンクを前提として要求されるというのは違和感を覚えます。世のやってみた記事も自分のような対応はしていません。処理は上手くいったとはいえ筋の悪い方法をとっている可能性が高いと思い、改めて調査しました。

 Non-filterable metadataを適切に設定せよhttps://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-vectors-best-practices.html
公式ドキュメントのS3 Vectors best practicesというページに

Configuring non-filterable metadata fields for vector indexes

という項目がありました。
When creating a vector index, configure metadata fields that don't require filtering as non-filterable metadata keys. For example, store text chunks for vector embeddings as non-filterable metadata fields when you need them only for reference. For more information, see Non-filterable metadata.
チャンクテキストとかnon-filterableでいいんじゃない？ と書いています。
つまり、Knowledge Baseで使用するS3 Vector BucketのIndex作成時にAMAZON_BEDROCK_TEXTをnon-filterableに設定するのが良さそうです。確かに2KB制限はfilterable metadataのみ対象なので、この設定でファイル取り込み時のエラーは消えそうです。
ただ、この設定も世のKnowledge Base+S3 Vectorsやってみた記事には基本的に記載なし。
改めてそれらの記事と自分の方法と見比べてみると、自分はあらかじめ作ったS3 Vector Bucketを利用しているのに対し、記事ではKnowledge Base作成フローのVector Storeの項目でQuick create a new vector store - Recommendedを選択していることが分かりました。
そして、この方法では自分のような2KB制限のエラーが起きることなく正常にファイルを取り込めています。
となると、「Knowledge BaseでS3 Vector Bucketを自動作成する場合は、べスプラに従いインデックス作成時にAMAZON_BEDROCK_TEXTを自動でnon-filterable metadataに設定するのではないか」という仮説を立てられます。
実際に確かめてみました。

 自動作成されたS3 Vector BucketのAMAZON_BEDROCK_TEXTはnon-filterable？Amazon S3 Vectors Embed CLIというツールを使い、自前作成と自動作成のS3 Vector BucketにAMAZON_BEDROCK_TEXTのフィルタリングを含んだクエリを投げてレスポンスを観察してみます。
https://github.com/awslabs/s3vectors-embed-cli
> s3vectors-embed query --vector-bucket-name your-vector-bucket-name --index-name your-index-name --model-id amazon.titan-embed-text-v2:0  --query-input "hoge(何でもいい)" --filter '{"AMAZON_BEDROCK_TEXT": {"$exists": true}}'

# 自前作成バケット
{
  "results": [
    {
      "key": "504e685e-80b2-4d5b-9517-eb09e2417281",
      "metadata": {
        "AMAZON_BEDROCK_TEXT": "Wallace (202-712-0428) Jason Wright (202-712-5146)     Janean Martin Julie Wallace Hope Sukin GH Senior Staff     Lorie Dobbins AFR/SA     -­     Rwanda Rose McCullough (202-712-4763)     Nancy Lowenthal, Megan Gerson     Nancy McCharen     Hope Sukin Margaret Neuse     Olutokunbo L. Cole AFR/EA     PEPFAR     Nancy McCharen (202-712-1894) Julia Byington (202-712-0540)     Senegal Frances Davidson (202-712-0982) Julie Wallace     Janean Martin Julie Wallace John Paul Clark     GH Senior Staff     Harry Proctor AFR/WA     Malaria PRH MCH     (202-712-0428)     Sierra Leone Sandra Jordan (202-712-1161) Susan Youll     Janean Martin Celeste Gregory     Mary Harvey GH Senior Staff     Lydia Hall AFR/WA     (202-712-1444)--     --     Country Country Coordinator     GH HIV/AIDS Point Person     GH/RCS Rep     AFR/SD Rep     GH Senior Advisor     AFR Bureau Desk Officer     Priority     South Africa Celeste Carr (202-712-4802) Julie Wallace (202-712-0428)     Shanti Conly, Julie Wallace     Julie Wallace Hope Sukin GH Senior Staff     Lorie",
        "AMAZON_BEDROCK_METADATA": "{\"text\":null,\"author\":\"USAID/Global Health\",\"createDate\":\"2005-03-21T21:09:00Z\",\"modifiedDate\":\"2005-03-21T21:10:33Z\",\"source\":{\"sourceLocation\":\"s3://sample-s3-data-mt/2ED27NR7CISW7J4PHXXBZ6OFPVDFHMFB.pdf\",\"sourceType\":null},\"descriptionText\":\"List of global health country contacts for the Africa Region\",\"pageNumber\":null,\"pageSizes\":null,\"graphDocument\":{\"entities\":[]},\"parentText\":null,\"relatedContents\":null,\"sourceDocumentId\":\"3iZM3cb0ujHBZuHVqse+Rn9KS9S3LwGv7OcxDfY0vAKocKl9EJ8TCSWzrHt53BQi\",\"additionalMetadata\":null}",
        "x-amz-bedrock-kb-source-uri": "s3://sample-s3-data-mt/2ED27NR7CISW7J4PHXXBZ6OFPVDFHMFB.pdf",
        "x-amz-bedrock-kb-document-page-number": 3.0,
        "x-amz-bedrock-kb-data-source-id": "YK35GCMH1R"
      }
    },
...

# 自動作成バケット
Error: S3 Vectors query_vectors failed: An error occurred (ValidationException) when calling the QueryVectors operation: Invalid use of non-filterable metadata in filter
Error: S3 Vectors query_vectors failed: An error occurred (ValidationException) when calling the QueryVectors operation: Invalid use of non-filterable metadata in filter
私がnon-filterable metadataの設定を行わず自前で作ったS3 Vector Bucketへのクエリは検索結果が返ってきている一方で、Knowledge Baseにより自動作成された方はnon-filterable metadataを使うなと怒られています。
AMAZON_BEDROCK_TEXTがちゃんと自動でnon-filterableに設定されているようです。

 まとめ今回の問題の原因は、私が自前で用意したS3 Vector BucketでAMAZON_BEDROCK_TEXTがfilterableであり、取り込み時にfilterable metadataの2KB制限に引っかかったことにあります。
私のように自分で作成するなら、インデックス作成時にAMAZON_BEDROCK_TEXTをnon-filterableに設定するなどしてfilterable metadataのサイズを減らす必要があります。また、Knowledge Baseに作成してもらうなら自動でnon-filterableの設定をしてくれるので、自分で何かする必要はありません。
S3 Vectors+Knowledge BaseでFilterable metadataのサイズについて怒られた【S3 Vectors】

はじめに

結論

やったこと

`Filterable metadata`

メタデータを見てみる

Non-filterable metadataを適切に設定せよ

自動作成されたS3 Vector Bucketの`AMAZON_BEDROCK_TEXT`はnon-filterable？

まとめ

Discussion
