本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 每個請求中繼資料標記
請求中繼資料可讓您將金鑰值標籤連接到[`bedrock-runtime`](endpoints.md)端點上的個別 Amazon Bedrock 推論呼叫。標籤會與請求一起記錄在[模型調用日誌](model-invocation-logging.md)中。然後，您可以將用量歸因於團隊、應用程式、環境、實驗或任何其他因呼叫而異的維度。沒有資源可事先建立或設定 - 每個呼叫都可以攜帶不同的標籤集。
下列 [`bedrock-runtime`](endpoints.md) APIs 支援請求中繼資料：
+ [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)、 [專案](cost-mgmt-projects.md)或 [工作區](cost-mgmt-workspaces.md)。
## 請求中繼資料的運作方式
視您呼叫的 API 而定，您會以不同的方式將中繼資料連接至請求：
+ **InvokeModel 和 InvokeModelWithResponseStream** – 在請求上設定 `X-Amzn-Bedrock-Request-Metadata` HTTP 標頭。此值是 JSON 物件，其索引鍵和值是您選擇的字串。
+ **Converse 和 ConverseStream** – 在請求內文中設定 `requestMetadata` 欄位。如需詳細資訊，請參閱[requestMetadata](conversation-inference.md#converse-request-metadata)。
只有在進行呼叫的 中啟用記錄時 AWS 區域 ，請求中繼資料才會記錄在模型調用日誌中。如需設定說明，請參閱 [使用 CloudWatch Logs 和 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 Signature 第 4 版 (SigV4) 簽署請求時，`X-Amzn-Bedrock-Request-Metadata`請將 包含在`SignedHeaders`清單中。從已簽章清單中省略 標頭的請求會遭到拒絕，而 `InvalidSignatureException`. AWS SDKs 會將請求中繼資料公開為 參數，以自動處理此問題。
下列範例會在 Converse 呼叫上使用適用於 Python (Boto3) 的 AWS SDK 設定請求中繼資料。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 個字元。
+ 允許字元：一組受限的英數字元和標點符號字元。
超過這些限制的請求會因驗證錯誤而遭到拒絕。
## 請求中繼資料的顯示位置
請求中繼資料會顯示在最上層`requestMetadata`欄位下的 Amazon Bedrock 模型調用日誌中。下列縮寫日誌項目顯示 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 CloudWatch Logs Insights、Amazon S3 查詢工具，例如 Amazon Athena 或任何其他讀取調用日誌的系統中的中繼資料欄位來篩選和彙總日誌。
## 從日誌取得成本
請求中繼資料和字符計數會寫入您的模型調用日誌，而不是您的帳單。有兩種方式可將它們轉換為成本。
從字符計數運算
每個日誌記錄都會攜帶請求的輸入、輸出、快取讀取和快取寫入字符計數。將這些值乘以 [Amazon Bedrock 定價](https://aws.amazon.com/bedrock/pricing/)中的每個金鑰費率，並將群組乘以任何中繼資料標籤。此方法按提示且近乎即時，但這是預估值。您可以維護 費率卡。除非您建立模型，否則不會反映折扣、承諾、批次定價、免費方案或佈建輸送量。
將調用日誌交付至 CloudWatch Logs 時，下列 CloudWatch Logs Insights 查詢會針對每個使用者和模型總計權杖：
```
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 在其明細項目上都不包含每個請求識別符。在一小時或一天內，依用量類型彙總成本。將此路徑視為模型和用量類型 grain 的對帳，日誌在下方提供每個請求的詳細資訊。
**注意**
請求中繼資料和 IAM 工作階段標籤是不同的機制。每個呼叫都會設定請求中繼資料，每個請求也會有所不同。它會落在您的調用日誌中。IAM 工作階段標籤每個工作階段繫結，且僅以 AWS Cost Explorer 和 CUR 中的彙總帳單資料顯示。對於每個使用者、每個提示屬性，請在 ARN 中使用請求中繼資料或每個使用者身分，而不是工作階段標籤。
## 考量事項
+ 只有在呼叫的 中啟用模型調用記錄時，才會記錄請求中繼資料值 AWS 區域。如果未設定記錄，請求仍會成功，但中繼資料不會保留。
+ 請求中繼資料不會交付為 AWS 成本分配標籤，也不會出現在 AWS Cost Explorer 或 CUR 中。若要依中繼資料維度分析成本，請將您的調用日誌與 上的成本和用量報告聯結`requestId`。或者，彙總字符會直接從日誌記錄中計數，並乘以 [Amazon Bedrock 定價](https://aws.amazon.com/bedrock/pricing/)中的每個字符費率。對於原生流向 Cost Explorer 和 CUR 的屬性，請使用 [應用程式推論設定檔](cost-mgmt-application-inference-profiles.md)、 [專案](cost-mgmt-projects.md)或 [工作區](cost-mgmt-workspaces.md)。
+ 選擇穩定、低基數索引鍵，例如 `team`、`feature`、 `environment`或 `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)資源層級成本分配標籤。