使用 CloudWatch Logs 監控 Amazon Q in Connect - Amazon Connect
所需的 IAM 許可Enable logging (啟用日誌記錄)支援的日誌類型檢查 CloudWatch Logs 配額使用互動式處理常式記錄 CloudWatch Events偵錯助理日誌的常見查詢範例

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 CloudWatch Logs 監控 Amazon Q in Connect

若要了解 Amazon Q in Connect 提供給客服人員的即時建議，以及它透過自然語言理解偵測到的客戶意圖，您可以查詢 CloudWatch Logs。CloudWatch Logs 可讓您了解整個聯絡旅程：對話、觸發條件、意圖、建議。您也可以使用此資訊進行偵錯，或在聯絡他們尋求協助 支援 時將其提供給 。

本主題說明如何啟用 Amazon Q in Connect 的記錄。

所需的 IAM 許可

啟用 Amazon Q in Connect 助理的記錄之前，請檢查您是否具有下列 AWS Identity and Access Management 許可。登入 Amazon Connect 主控台的使用者帳戶需要它們：

  • wisdom:AllowVendedLogDeliveryForResource：允許為助理資源交付日誌時需要。

若要檢視具有特定記錄目的地所有必要許可的範例 IAM 角色，請參閱需要額外許可 【V2】 的 記錄。該主題包含不同記錄目的地的範例，例如傳送至 CloudWatch Logs 的日誌和傳送至 Amazon S3 的日誌。範例示範如何允許更新特定記錄目的地資源。

啟用 Amazon Q in Connect 的記錄

若要啟用 Amazon Q in Connect 的記錄，您可以使用 CloudWatch API。完成下列步驟。

  1. 取得 Amazon Q in Connect 助理的 ARN （也稱為其網域)。建立助理後，您可以從 Amazon Connect 主控台或呼叫 GetAssistant API 取得其 ARN。ARN 遵循此格式：

    arn:aws:wisdom:your-region:your-account-id:assistant/assistant-id

  2. 呼叫 PutDeliverySource：使用此 CloudWatch API 為助理建立交付來源。將助理的 ARN 做為 傳遞resourceArn。針對 logType，指定 EVENT_LOGS從您的助理收集日誌。

    {
    "logType": "EVENT_LOGS",
    "name": "your-assistant-delivery-source",
    "resourceArn": "arn:aws:wisdom:your-region:your-account-id:assistant/assistant_id
}

  3. 呼叫 PutDeliveryDestination：使用此 CloudWatch API 來設定日誌的存放位置。您可以選擇 CloudWatch Logs、Amazon S3 或 Amazon Data Firehose 作為儲存日誌的目的地。您必須指定要存放日誌的其中一個目的地選項的 ARN。您可以選擇日誌outputFormat的 做為下列其中一項：json、plain、w3c、raw、parquet。

    下列範例示範如何設定日誌以存放在 Amazon CloudWatch Logs 群組和 JSON 格式。

    {
    "deliveryDestinationConfiguration": {
        "destinationResourceArn": "arn:aws:logs:your-region:your-account-id:log-group:your-log-group-name:*"
    },
    "name": "string",
    "outputFormat": "json",
    "tags": {
        "key": "value"
    }
}

  4. 呼叫 CreateDelivery：使用此 CloudWatch API 將交付來源連結至您在先前步驟中建立的交付目的地。此 API 操作會將交付來源與最終目的地建立關聯。

    {
    "deliveryDestinationArn": "string",
    "deliverySourceName": "string",
    "tags": {
        "string": "string"
    }
}

支援的日誌類型

Amazon Q in Connect 支援下列日誌類型：

  • EVENT_LOGS：在通話和聊天期間追蹤 Amazon Q in Connect 助理事件的日誌。

檢查 CloudWatch Logs 配額

我們建議您檢查 Amazon CloudWatch Logs 端點和配額，以查看是否有任何配額可用於進行 CloudWatch Logs 交付相關 API 呼叫。配額設定您可以呼叫 API 或建立資源的次數上限。超過限制會導致ServiceQuotaExceededException錯誤。

使用互動式處理常式記錄 CloudWatch Events

事件類型定義

下表說明每個事件類型。請注意，不同的事件類型包含不同的欄位。如需每個欄位的詳細資訊，請參閱欄位定義一節。

EventType 定義
TRANSCRIPT_CREATE_SESSION 建立新的 Amazon Q in Connect 工作階段時記錄。這會標記對話的開頭。
TRANSCRIPT_INTENT_TRIGGERING_REFERENCE 在對話中偵測到特定客戶意圖時記錄，這可能會觸發自動回應或工作流程。
TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION 調用大型語言模型 (LLM) 以產生回應或處理對話內容時記錄。記錄 LLM 的輸入和輸出。
TRANSCRIPT_QUERY_ASSISTANT 在手動搜尋或直接查詢 Amazon Q in Connect 時記錄
TRANSCRIPT_RECOMMENDATION 當系統向客服人員或客戶提供建議時記錄，其中可能包括知識文章、產生的回應或建議的動作。
TRANSCRIPT_RESULT_FEEDBACK 當提供有關搜尋或查詢結果實用性或相關性的意見回饋時記錄。
TRANSCRIPT_SELF_SERVICE_MESSAGE 當客戶與 Amazon Q in Connect 的自助式元件互動時記錄
TRANSCRIPT_SESSION_POLLED 當系統偵測到客服人員已連線至工作階段時記錄 （在進行 GetRecommendations API 呼叫時輪詢工作階段）
TRANSCRIPT_TRIGGER_DETECTION_MODEL_INVOCATION 在叫用觸發偵測模型時記錄，以判斷對話是否有意圖
TRANSCRIPT_UTTERANCE 當對話中的任何參與者傳送訊息時記錄，記錄實際的對話內容。

欄位定義

下表說明每個欄位。

欄位 定義
ai_agent_id Amazon Q in Connect AI 代理程式資源的唯一識別符。
assistant_id Amazon Q in Connect 助理資源的唯一識別符。
完成 LLM 傳回或為訊息產生的原始完成文字。
connect_user_arn 存取工作階段之 Connect 使用者的 Amazon Resource Name (ARN)。
event_timestamp 事件發生時取消ix 時間戳記 （以毫秒為單位）。
event_type 事件類型，指出系統中發生的動作或程序。
generation_id 特定 AI 產生的回應的唯一識別符。
意圖 意圖文字或描述。
intent_clicked 布林值指出建議是否由點選的意圖觸發。
intent_id 偵測到意圖的唯一識別符。
issue_probability 在對話中偵測到問題的數值機率 (0.0–1.0) （大於 0.5 的機率將調用意圖產生）
is_recommendation_useful 布林值指出使用者是否認為結果有幫助。
is_valid_trigger 布林值指出偵測模型分析是否產生有效的觸發。
model_id 用來叫用 LLM 的 AI 模型識別符。
parsed_response 語言模型回應的處理/剖析版本，通常採用結構化格式。
提示 用來叫用 LLM 的輸入提示。
prompt_type 用於處理訊息或查詢的 Amazon Q in Connect 提示類型。
建議 提供給使用者的實際建議文字內容
recommendation_id 建議的唯一識別符。
response 處理後為使用者產生的最終回應文字。
session_event_id 工作階段中特定事件的唯一識別符。
session_event_ids 工作階段事件識別符的清單。
session_id Amazon Q in Connect 工作階段的唯一識別符。
session_message_id 工作階段中自助式訊息的唯一識別符。
session_name 工作階段的名稱。
表達用語 對話中交換的實際訊息文字。

助理日誌的範例

以下是每個事件類型的不同事件日誌範例。如需每個事件類型的詳細說明，請參閱事件類型定義一節。

CreateSession


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173612,
    "event_type": "TRANSCRIPT_CREATE_SESSION",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
    "session_name": "nabbccdd-9999-4b23-aaee-112233445566"
}

IntentTriggeringReference


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173623,
    "event_type": "TRANSCRIPT_INTENT_TRIGGERING_REFERENCE",
    "intent": "To learn about how to autoscale DynamoDB.",
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}

LargeLanguageModelInvocation

查詢重新格式化


{
    "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "completion": "<query>The customer is asking for information on how to autoscale DynamoDB.</query>",
    "event_timestamp": 1729530173645,
    "event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
    "generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5"
    "model_id": "us.amazon.nova-lite-v1:0",
    "parsed_response": "The customer is asking for information on how to autoscale DynamoDB.",
    "prompt": "{\"anthropic_version\":\"bedrock-2023-05-31\",\"max_tokens\":1024,\"system\":\"You are a...\"}",
    "prompt_type": "BEDROCK_KB_QUERY_REFORMULATION",
    "session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}

意圖偵測


{
    "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "completion": "no</malice>\n  - Step 2. <specific>yes</specific>\n  - Step 3. <intent>To learn how to autoscale DynamoDB.</intent>",
    "event_timestamp": 1729530173645,
    "event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
    "generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5"
    "model_id": "us.amazon.nova-lite-v1:0",
    "parsed_response": "To learn how to autoscale DynamoDB.",
    "prompt": "{\"anthropic_version\":\"bedrock-2023-05-31\",\"max_tokens\":1024,\"system\":\"You are a...\"}",
    "prompt_type": "GENERATIVE_INTENT_DETECTION",
    "session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}

意圖答案產生


{
    "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "completion": "{\"citations\":[{\"citation\":{\"generatedResponsePart\":{\"textResponsePart\":{\"span\":{\"end\":1065,\"start\":0},\"text\":\"\\nDynamoDB auto s\"}}}}]}",
    "event_timestamp": 1729530173645,
    "event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
    "generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
    "model_id": "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
    "parsed_response": "DynamoDB auto scaling works by creating CloudWatch alarms that monitor your table's activity. When the...",
    "prompt": "{\"input\":{\"text\":\"The customer is seeking information on how to autoscale DynamoDB. Key utterance: \\\"How can \"}}",
    "prompt_type": "BEDROCK_KB_GENERATIVE_ANSWER",
    "session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}

手動搜尋產生


{
    "ai_agent_id": "ai112233-7a85-4b3c-8def-0123456789ab",
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "completion": "no</malice>\n  - Step 2. <specific>yes</specific>\n  - Step 3. <intent>To learn how to autoscale DynamoDB.</intent>",
    "event_timestamp": 1729530173645,
    "event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
    "generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
    "model_id": "us.anthropic.claude-3-7-sonnet-20250219-v1:0",
    "parsed_response": "DynamoDB auto scaling works by creating CloudWatch alarms that monitor...",
    "prompt": "{\"anthropic_version\":\"bedrock-2023-05-31\",\"max_tokens\":1024,\"system\":\"You are a...\"}",
    "prompt_type": "BEDROCK_KB_GENERATIVE_ANSWER",
    "session_id": "******************-*****************"
}

QueryAssistant


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173667,
    "event_type": "TRANSCRIPT_QUERY_ASSISTANT",
    "recommendation_id": "r0001112-3f4e-4fa5-9111-aabbccddeeff",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}

建議


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173656,
    "event_type": "TRANSCRIPT_RECOMMENDATION",
    "intent_clicked": 1,
    "intent_id": "i78bc90-1234-4dce-8012-f0e1d2c3b4a5",
    "recommendation_id": "r0001112-3f4e-4fa5-9111-aabbccddeeff",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}

ResultFeedback


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173667,
    "event_type": "TRANSCRIPT_RESULT_FEEDBACK",
    "generation_id": "gabc1234-9def-47ff-bb88-abcdefabcdef",
    "is_recommendation_useful": 1,
    "recommendation_id": "r0001112-3f4e-4fa5-9111-aabbccddeeff"
}

SelfServiceMessage


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "completion": "{\"citations\":[{\"generatedResponsePart\":{\"textResponsePart\":{\"span\":{\"end\":276,\"start\":0},\"text\":\"To autoscale Amazon DynamoDB...\"}}]}",
    "event_timestamp": 1729530173678,
    "event_type": "TRANSCRIPT_SELF_SERVICE_MESSAGE",
    "model_id": "us.amazon.nova-pro-v1:0",
    "parsed_response": "To autoscale Amazon DynamoDB, follow these steps:...",
    "prompt": "{\"input\":{\"text\":\"how to autoscale dynamodb\"},\"retrieveAndGenerateConfiguration\":...}",
    "prompt_type": "SELF_SERVICE_ANSWER_GENERATION",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
    "session_message_id": "mdee1234-5678-4eab-9333-ffeebb998877",
    "utterance": "[Customer] How can I autoscale DyanmoDB?"
}

TranscriptSessionPolled


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "connect_user_arn": "arn:aws:connect:us-east-1:204585150770:instance/seaa9988-2233-4f44-8899-abcabcabcabc/agent/agbbccdd-9999-4b23-aaee-112233445566",
    "event_timestamp": 1729530173623,
    "event_type": "TRANSCRIPT_SESSION_POLLED",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
    "session_name": "nabbccdd-9999-4b23-aaee-112233445566"
}

TriggerDetectionModelInvocation


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173634,
    "event_type": "TRANSCRIPT_TRIGGER_DETECTION_MODEL_INVOCATION",
    "is_valid_trigger": 1,
    "issue_probability": "0.87",
    "session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
    "session_event_ids": ["seaa9988-2233-4f44-8899-abcabcabcabc"],
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa"
}

表達用語


{
    "assistant_id": "a1c2d3e4-5b67-4a89-9abc-def012345678",
    "event_timestamp": 1729530173623,
    "event_type": "TRANSCRIPT_UTTERANCE",
    "session_event_id": "seaa9988-2233-4f44-8899-abcabcabcabc",
    "session_id": "s9f8e7d6-1234-4cde-9abc-ffeeddccbbaa",
    "utterance": "[Customer] My laptop won't connect to WiFi after the recent update"
}

偵錯助理日誌的常見查詢範例

您可以使用查詢與日誌互動。例如，您可以使用 查詢工作階段中的所有事件SESSION_NAME。

以下是兩個常見的查詢，用於傳回針對特定工作階段產生的所有日誌。

  • filter session_name = "SessionName"

  • filter session_id = "SessionId"