使用 Amazon Bedrock Request Metadata 增强您的模型调用追踪与成本分析能力
内容提要
Amazon Bedrock 推出 Request Metadata 功能，调用模型时可附加最多 16 个键值对元数据，不影响模型输出，但会记录到 CloudWatch 或 S3 日志，用于业务分析、日志过滤、追踪 ID 和成本分账。Converse 与 InvokeModel 系列 API 均已支持。文章介绍通过 CLI 和 SDK 添加元数据的方法，并演示如何用 CloudWatch Logs Insights 和 Athena 查询日志、按部门或项目统计 Token 消耗与估算成本，最后给出元数据命名统一、避免敏感信息等最佳实践。
延伸解读
元数据键名大小写：查询前必须统一的细节
文章多次强调键名大小写敏感：CloudWatch Logs Insights 中 requestMetadata.Project 与 requestMetadata.project 被视为不同字段；Athena 的 OpenX JsonSerDe 默认将 JSON 键名转为小写，因此查询时需使用 requestMetadata['department']，写成大写将返回空值；Python 脚本中字典键同样区分大小写。若团队未统一命名规范，后续按部门或项目聚合时可能漏掉部分调用记录，导致成本统计不完整。
模型标识格式不一，聚合前需统一处理
日志中 modelId 的记录方式因 API 而异：使用推理配置文件时，Converse 类请求记录为配置文件 ID，InvokeModel 类请求记录为完整 ARN。若直接按 modelId 聚合，同一模型可能被拆成多行。文章给出的查询示例使用 parse 或 regexp_replace 将 ARN 统一为 ID，本地脚本也用正则去除 ARN 前缀。做成本分账前应先完成这一步，否则按模型统计的 Token 与费用会失真。
日志投递延迟与字段缺失对实时分析的影响
文章指出调用日志投递存在几分钟延迟，刚发出的请求可能无法立即查询到，因此不适合做秒级实时监控。此外，cacheReadInputTokenCount、cacheWriteInputTokenCount 并非每条日志都有，统计时需做空值处理，示例查询用 COALESCE 归零。若忽略这两点，可能误判近期调用量或低估缓存相关成本。
Athena 建表需绕开 data/ 目录中的大载荷文件
Bedrock 会将超大请求/响应正文及图片等原始文件存放在日志目录的 data/ 子目录，格式与调用日志不同。Athena 会递归读取表 LOCATION 下所有文件，若将 input、output 定义为嵌套结构，查询会因 data/ 文件报 BAD_DATA 错误。文章建议将 input、output 定义为字符串，查询时用 json_extract_scalar 提取 Token 数，并用 schemaType 过滤调用日志，同时按天分区控制扫描成本。
Q&A
Amazon Bedrock Request Metadata 是什么？它会影响模型输出吗？
Request Metadata 是 Amazon Bedrock 的一项新功能，允许用户在调用模型时附加键值对形式的元数据。这些元数据不会影响模型的输出结果，但会被记录在 Amazon CloudWatch 或 Amazon S3 中，用于业务分析、日志过滤、调用跟踪和成本分账等场景。
哪些 Bedrock API 支持 Request Metadata？使用 InvokeModel 需要升级 SDK 吗？
最初仅支持 Converse 及 ConverseStream API。自 2026 年 5 月起，InvokeModel 及 InvokeModelWithResponseStream API 也已支持。如果之前使用 InvokeModel 系列 API，无需切换到 Converse API，只需将 SDK 升级到较新版本即可（Python SDK 需要 boto3/botocore 1.43.12 及以上版本）。
Request Metadata 的键值对有什么格式和数量限制？
每个请求最多可以添加 16 个键值对。键和值均为字符串类型，键长度 1～256 个字符，值长度 0～256 个字符。键和值仅支持英文字母、数字、空白字符以及 : _ @ $ # = / + , - . 这些符号，不支持中文等非 ASCII 字符。
如何通过 AWS CLI 为 Bedrock 请求添加 Request Metadata？
在 AWS CLI 中，可以通过 --request-metadata 参数添加元数据，支持键值对格式（如 "ProjectName=AI,Department=IT"）或 JSON 格式（如 '{"ProjectName": "AI", "Department": "IT"}'）。Converse 和 InvokeModel 命令均支持该参数，InvokeModel 需使用较新版本的 AWS CLI v2。
使用 Request Metadata 后，如何按部门或项目统计 Token 消耗和估算成本？
可以将 Bedrock 调用日志投递到 CloudWatch 或 S3，然后使用 CloudWatch Logs Insights 或 Amazon Athena 进行查询。在查询中通过 requestMetadata 字段（如 requestMetadata.Project 或 requestMetadata['department']）分组，结合日志中的 inputTokenCount、outputTokenCount 等字段，并关联模型单价，即可统计各维度 Token 消耗和估算成本。
使用 Request Metadata 有哪些最佳实践需要注意？
最佳实践包括：制定统一的元数据命名标准，尤其统一键名大小写；仅使用英文字符，中文需转换为英文代码；控制键值对数量和长度（最多 16 对，键值不超过 256 字符）；避免包含敏感信息；使用有意义的键名和值；定期审查元数据使用情况。成本分析方面还需统一模型标识、建立成本模型、定期更新价格并设置成本预警。
