本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 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 会自动处理此问题。
## 限制
请求元数据有以下限制，这些限制适用于`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 日志的系统中按元数据字段筛选和汇总日志。
## 注意事项
+ 只有在调用中启用模型调用日志时，才会记录请求元数据值。 AWS 区域如果未配置日志记录，则请求仍会成功，但不会保留元数据。
+ 请求元数据不会作为 AWS 成本分配标签提供，也不会显示在 Cost Explorer 或 CUR 中 AWS 。要按元数据维度分析成本，请在开启成本和使用报告的情况下加入调用日志`requestId`，或者直接从日志记录中汇总令牌数量，然后乘以 A [ma](https://aws.amazon.com/bedrock/pricing/) zon Bedrock 定价中的每个令牌费率。对于原生流向 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 使用情况跟踪方法配合使用。在同一[IAM 主体归因](cost-mgmt-iam-principal-tracking.md)工作负载上，您可以使用按身份归[应用程序推理配置文件](cost-mgmt-application-inference-profiles.md)因和资源级成本分配标签。