本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Per-request 元数据标记
请求元数据允许您将键值标签附加到终端节点上的单个 Amazon Bedrock 推理调用。[`bedrock-runtime`](endpoints.md)标签与请求一起记录在[模型调用日志](model-invocation-logging.md)中。然后，您可以将使用情况归因于团队、应用程序、环境、实验或每次调用不同的任何其他维度。无需提前创建或配置资源，每个呼叫可以携带一组不同的标签。
以下 [`bedrock-runtime`](endpoints.md)API 支持请求元数据：
+ [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)
+ [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)
+ [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html)
+ [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)
**注意**
[`bedrock-mantle`](endpoints.md)终端节点不支持请求元数据。有关作为 AWS 成本分配标签直接流入 Cost Explorer 和 “ AWS 成本和使用情况报告” 的归因[应用程序推理配置文件](cost-mgmt-application-inference-profiles.md)，请参阅[Projects](cost-mgmt-projects.md)、或[Workspaces](cost-mgmt-workspaces.md)。
## 请求元数据的工作原理
根据您调用的 API，您可以以不同的方式向请求附加元数据：
+ **InvokeModel 和 InvokeModelWithResponseStream** — 在请求上设置 `X-Amzn-Bedrock-Request-Metadata` HTTP 标头。该值是一个 JSON 对象，其键和值是您选择的字符串。
+ **Converse** and ConverseStream — 在请求正文中设置`requestMetadata`字段。有关更多信息，请参阅 [requestMetadata](conversation-inference.md#converse-request-metadata)。
只有在进行调用的位置启用了日志记录时，请求元数据才会记录 AWS 区域 在模型调用日志中。有关设置说明，请参阅[使用 CloudWatch 日志和 Amazon S3 监控模型调用](model-invocation-logging.md)。
以下示例显示了一个 InvokeModel 请求，该请求使用团队名称、环境和测试用例标识符标记呼叫：
```
POST /model/anthropic.claude-3-haiku-20240307-v1:0/invoke HTTP/1.1
Content-Type: application/json
X-Amzn-Bedrock-Request-Metadata: {"team": "orchestrator", "environment": "preview-test", "test_case": "invoke_model_sync"}
{
"anthropic_version": "bedrock-2023-05-31",
"max_tokens": 50,
"messages": [{"role": "user", "content": "Say hello in one word."}]
}
```
以下版本支持相同的标题 InvokeModelWithResponseStream：
```
POST /model/anthropic.claude-3-haiku-20240307-v1:0/invoke-with-response-stream HTTP/1.1
Content-Type: application/json
X-Amzn-Bedrock-Request-Metadata: {"team": "orchestrator", "environment": "preview-test", "test_case": "invoke_model_stream"}
{
"anthropic_version": "bedrock-2023-05-31",
"max_tokens": 50,
"messages": [{"role": "user", "content": "Say hello in one word."}]
}
```
**重要**
使用 AWS 签名版本 4 (Sigv4) 签署请求时，请包含`X-Amzn-Bedrock-Request-Metadata`在列表中。`SignedHeaders`在签名列表中省略标头的请求会被拒绝。`InvalidSignatureException` AWS 将请求元数据作为参数公开的 SDK 会自动处理此问题。
以下示例使用适用于 Python 的 AWS 软件开发工具包 (Boto3) 在 Converse 调用中设置请求元数据。SDK 将元数据包含在 SigV4-signed 标题中。
```
import boto3
client = boto3.client("bedrock-runtime")
response = client.converse(
modelId="us.anthropic.claude-opus-4-8", # or an inference profile ARN
messages=[{"role": "user", "content": [{"text": "Summarize this ticket."}]}],
requestMetadata={
"user": "alice@example.com",
"team": "growth",
"feature": "summarizer",
"environment": "prod",
},
)
```
## 限制
请求元数据有以下限制，这些限制适用于`X-Amzn-Bedrock-Request-Metadata`标头 (InvokeModel, InvokeModelWithResponseStream) 和`requestMetadata`正文字段（Converse， ConverseStream）：
+ 每个请求最多 16 个元数据条目。
+ 密钥：最多 256 个字符。
+ 值：最多 256 个字符。
+ 允许的字符：一组受限制的字母数字和标点字符。
超过这些限制的请求会被拒绝，并出现验证错误。
## 请求元数据的显示位置
请求元数据显示在您的 Amazon Bedrock 模型调用日志的顶级`requestMetadata`字段下。以下缩写的日志条目显示了 InvokeModel 呼叫的字段：
```
{
"schemaType": "ModelInvocationLog",
"schemaVersion": "1.0",
"timestamp": "2024-01-15T12:00:00Z",
"accountId": "123456789012",
"region": "us-east-1",
"requestId": "abcd1234-5678-efgh-ijkl-mnopqrstuvwx",
"operation": "InvokeModel",
"modelId": "anthropic.claude-3-haiku-20240307-v1:0",
"requestMetadata": {
"team": "orchestrator",
"environment": "preview-test",
"test_case": "invoke_model_sync"
},
"input": { "...": "..." },
"output": { "...": "..." }
}
```
您可以在 Amazon Logs Insights、Amazon S3 查询工具（例如 Amazon Athena）或任何其他读取调用 CloudWatch 日志的系统中按元数据字段筛选和汇总日志。
## 从日志中获取成本
请求元数据和令牌计数会写入您的模型调用日志，而不是账单。有两种方法可以将其转化为成本。
根据代币数量计算
每条日志记录都包含请求的输入、输出、缓存读取和缓存写入令牌计数。将这些值乘以 A [mazon Bedrock 定价](https://aws.amazon.com/bedrock/pricing/)中的每代币费率，然后按任意元数据标签进行分组。这种方法是按提示进行的，几乎是实时的，但它只是一种估计。你维护价目表。除非您对其进行建模，否则它不会反映折扣、承诺、批量定价、免费套餐或预配置吞吐量。
以下 CloudWatch Logs Insights 查询将调用日志传送到 Logs 时每个用户和模型的总令牌： CloudWatch
```
fields requestMetadata.user as user, modelId,
input.inputTokenCount as inTokens,
output.outputTokenCount as outTokens
| stats sum(inTokens) as totalInput,
sum(outTokens) as totalOutput,
count() as calls
by user, modelId
| sort totalInput desc
```
对于传送到 Amazon S3 的日志，以下 Amazon Athena 查询按团队估算成本。将每个代币的费率替换为 [Amazon Bedrock 定价](https://aws.amazon.com/bedrock/pricing/)中的当前费率，并调整表格和列引用以匹配您的 AWS Glue 表格定义。
```
SELECT requestMetadata.team AS team,
modelId,
SUM(input.inputTokenCount) AS input_tokens,
SUM(output.outputTokenCount) AS output_tokens,
SUM(input.inputTokenCount) * 0.000015 AS est_input_cost,
SUM(output.outputTokenCount) * 0.000075 AS est_output_cost
FROM bedrock_invocation_logs
GROUP BY requestMetadata.team, modelId
ORDER BY est_input_cost DESC;
```
根据 CUR 进行调节
将您的调用日志加入 AWS 成本和使用情况报告，获取准确的发票总额。经典 CUR 和 CUR 2.0 都没有在其行项目中包含每个请求的标识符。两者都按使用类型汇总一小时或一天内的成本。将此路径视为模型和使用类型颗粒的对账，日志在下面提供每个请求的详细信息。
**注意**
请求元数据和 IAM 会话标签是不同的机制。请求元数据是为每个呼叫设置的，并且因请求而异。它会落在你的调用日志中。IAM 会话标签按会话绑定，并且仅作为汇总账单数据显示在 Cost Expl AWS orer 和 CUR 中。对于按用户、按提示归因，请在 ARN 中使用请求元数据或每用户身份，而不是会话标签。
## 注意事项
+ 只有在调用中启用模型调用日志时，才会记录请求元数据值。 AWS 区域如果未配置日志记录，则请求仍会成功，但不会保留元数据。
+ 请求元数据不会作为 AWS 成本分配标签提供，也不会显示在 Cost Explorer 或 CUR 中 AWS 。要按元数据维度分析成本，请在开启成本和使用情况报告的情况下加入调用日志。`requestId`或者，直接从日志记录中汇总代币数量，然后乘以 A [mazon Bedro](https://aws.amazon.com/bedrock/pricing/) ck 定价中的每个代币费率。对于原生流向 Cost Explorer 和 CUR 的归因，请使用[应用程序推理配置文件](cost-mgmt-application-inference-profiles.md)[Projects](cost-mgmt-projects.md)、或。[Workspaces](cost-mgmt-workspaces.md)
+ 为易于聚合的分析选择稳定`team``environment`、低基数的密钥，例如`feature`、、或`experiment`。只有在需要跟踪单个呼叫时，才使用更高的基数值，例如会话或跟踪标识符。
+ 避免在请求元数据中放置个人身份信息 (PII)、凭证或其他敏感数据。值存储在您的模型调用日志和任何读取这些日志的系统中。
+ 请求元数据由每次通话提供，Amazon Bedrock 不强制执行。省略它的请求仍然会成功，并且没有服务端策略可以要求它。要保证覆盖整个组织，请在共享客户端或 LLM 网关中设置请求元数据。对于始终存在且不带每次通话代码的归因，请使用[IAM 主要归因](cost-mgmt-iam-principal-tracking.md)。它会自动捕获来电者身份。
+ 请求元数据可与其他 Amazon Bedrock 使用情况跟踪方法配合使用。您可以使用在同一[IAM 主要归因](cost-mgmt-iam-principal-tracking.md)工作负载上按身份归[应用程序推理配置文件](cost-mgmt-application-inference-profiles.md)因和资源级成本分配标签。