REST Resource: projects.locations.apps.evaluations

資源:評估

評估作業包含模擬及評估代理所需的所有資訊。

JSON 表示法
{
  "name": string,
  "displayName": string,
  "description": string,
  "tags": [
    string
  ],
  "evaluationDatasets": [
    string
  ],
  "createTime": string,
  "createdBy": string,
  "updateTime": string,
  "lastUpdatedBy": string,
  "evaluationRuns": [
    string
  ],
  "etag": string,
  "aggregatedMetrics": {
    object (AggregatedMetrics)
  },
  "lastCompletedResult": {
    object (EvaluationResult)
  },
  "invalid": boolean,
  "lastTenResults": [
    {
      object (EvaluationResult)
    }
  ],
  "evaluationMetricsThresholdOverride": {
    object (EvaluationMetricsThresholds)
  },
  "evaluationMetricsConfigOverride": {
    object (EvaluationMetricsConfig)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "golden": {
    object (Evaluation.Golden)
  },
  "scenario": {
    object (Evaluation.Scenario)
  }
  // End of mutually exclusive fields.
}
欄位
name

string

ID。這項評估的專屬 ID。格式:projects/{project}/locations/{location}/apps/{app}/evaluations/{evaluation}

displayName

string

這是必要旗標,使用者定義的評估顯示名稱。在應用程式中不得重複。

description

string

選用。使用者定義的評估說明。

tags[]

string

選用。使用者定義的標記,用於分類評估。

evaluationDatasets[]

string

僅供輸出。評估作業所屬的評估資料集清單。格式:projects/{project}/locations/{location}/apps/{app}/evaluationDatasets/{evaluationDataset}

createTime

string (Timestamp format)

僅供輸出。評估作業的建立時間戳記。

使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例:"2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

createdBy

string

僅供輸出。建立評估作業的使用者。

updateTime

string (Timestamp format)

僅供輸出。上次更新評估作業的時間戳記。

使用 RFC 3339,產生的輸出內容一律會經過 Z 正規化,並使用 0、3、6 或 9 個小數位數,也接受「Z」以外的偏移量。範例:"2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

lastUpdatedBy

string

僅供輸出。上次更新評估作業的使用者。

evaluationRuns[]

string

僅供輸出。與這項評估作業相關聯的 EvaluationRun。

etag

string

僅供輸出。Etag 可確保物件在讀取-修改-寫入作業期間未變更。如果 etag 為空白,更新作業會覆寫所有並行變更。

aggregatedMetrics

object (AggregatedMetrics)

僅供輸出。這項評估在所有執行作業中的匯總指標。

lastCompletedResult

object (EvaluationResult)

僅供輸出。這項評估的最新評估結果。

invalid

boolean

僅供輸出。評估是否無效。如果評估作業參照的工具、工具集或代理已刪除,就可能發生這種情況。

lastTenResults[]

object (EvaluationResult)

僅供輸出。這項評估作業最近 10 次的評估結果。只有在 ListEvaluationsRequest 或 GetEvaluationRequest 中將 include_last_ten_results 設為 true 時,系統才會填入這個欄位。

evaluationMetricsThresholdOverride

object (EvaluationMetricsThresholds)

選用。覆寫這項特定評估的指標門檻。

evaluationMetricsConfigOverride

object (EvaluationMetricsConfig)

選用。覆寫這項特定評估作業的指標設定。

評估作業的輸入內容。下列欄位互斥,回應中最多會設定下列其中一個欄位:
golden

object (Evaluation.Golden)

選用。要評估的黃金步驟。

scenario

object (Evaluation.Scenario)

選用。情境設定。

互斥欄位結束。

Evaluation.Golden

重播黃金對話所需的步驟。

JSON 表示法
{
  "turns": [
    {
      object (Evaluation.GoldenTurn)
    }
  ],
  "evaluationExpectations": [
    string
  ]
}
欄位
turns[]

object (Evaluation.GoldenTurn)

這是必要旗標,重播黃金對話所需的黃金回合。對話回合數上限為 100。

evaluationExpectations[]

string

選用。評估重播對話時的預期結果。格式:projects/{project}/locations/{location}/apps/{app}/evaluationExpectations/{evaluationExpectation}

Evaluation.GoldenTurn

黃金回合定義了黃金對話中的單一回合。

JSON 表示法
{
  "steps": [
    {
      object (Evaluation.Step)
    }
  ],
  "rootSpan": {
    object (Span)
  },
  "turnLevelMetricsThresholdsOverride": {
    object (EvaluationMetricsThresholds.GoldenEvaluationMetricsThresholds.TurnLevelMetricsThresholds)
  },
  "hallucinationMetricBehaviorOverride": enum (EvaluationMetricsThresholds.HallucinationMetricBehavior)
}
欄位
steps[]

object (Evaluation.Step)

這是必要旗標,重播黃金對話所需的步驟。

rootSpan

object (Span)

選用。處理及維護音訊資訊的黃金回合根時距。音訊的 URI 必須包含以 16Khz 取樣率儲存的音訊。

turnLevelMetricsThresholdsOverride

object (EvaluationMetricsThresholds.GoldenEvaluationMetricsThresholds.TurnLevelMetricsThresholds)

選用。覆寫回合層級指標門檻。

hallucinationMetricBehaviorOverride

enum (EvaluationMetricsThresholds.HallucinationMetricBehavior)

選用。覆寫回合層級幻覺指標行為。

Evaluation.Step

步驟定義了評估期間要執行的單一動作。

JSON 表示法
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "userInput": {
    object (SessionInput)
  },
  "agentTransfer": {
    object (AgentTransfer)
  },
  "expectation": {
    object (Evaluation.GoldenExpectation)
  }
  // End of mutually exclusive fields.
}
欄位
要執行的步驟。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位:
userInput

object (SessionInput)

選用。對話的使用者輸入內容。

agentTransfer

object (AgentTransfer)

選用。將對話轉接給其他服務專員。

expectation

object (Evaluation.GoldenExpectation)

選用。在目前的回合執行預期。

互斥欄位結束。

SessionInput

工作階段的輸入內容。

JSON 表示法
{
  "willContinue": boolean,
  "recordingControl": enum (SessionInput.RecordingControl),

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "text": string,
  "dtmf": string,
  "audio": string,
  "toolResponses": {
    object (ToolResponses)
  },
  "image": {
    object (Image)
  },
  "blob": {
    object (Blob)
  },
  "variables": {
    object
  },
  "event": {
    object (Event)
  }
  // End of mutually exclusive fields.
}
欄位
willContinue

boolean

選用。這個標記用於指出目前訊息是否為雙向串流工作階段中較大輸入內容的一部分。

如果設為 true,代理會延遲處理,直到收到 willContinue 為 false 的後續訊息,或系統偵測到音訊輸入中的端點。

注意:這個欄位不適用於音訊和 DTMF 輸入,因為系統一律會根據端點信號自動處理這些輸入。

recordingControl

enum (SessionInput.RecordingControl)

選用。是否要從現在起錄製及記錄對話。

如果是由應用程式 (而非代理) 決定可保留的內容,請使用這個選項。舉例來說,使用者必須先同意錄音,系統才能儲存通話相關內容。

這個值會持續有效,直到用戶端傳送不同的值為止,因此只有在答案變更時才需要傳送。一輪對話結束時,系統會根據當時生效的設定,決定該輪對話的音訊是否會傳送至錄音 bucket,以及轉錄稿是否會傳送至對話記錄、BigQuery 和 Cloud Logging。涵蓋代理和使用者雙方的對話內容。

在用戶端首次傳送此欄位之前完成的回合,會根據應用程式的記錄設定記錄,就像該欄位不存在一樣。

如果同一要求中有多個輸入內容設定了這個值,則以最後一個為準。

輸入內容的類型。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位:
text

string

選用。使用者的文字資料。

dtmf

string

選用。使用者輸入的 DTMF 數字。

audio

string (bytes format)

選用。使用者提供的音訊資料。

Base64 編碼字串。

toolResponses

object (ToolResponses)

選用。用戶端工具呼叫的執行結果。

image

object (Image)

選用。使用者提供的圖片資料。

blob

object (Blob)

選用。使用者提供的 Blob 資料。

variables

object (Struct format)

選用。工作階段的情境變數,依名稱排序。CES 代理只會使用在應用程式中宣告的變數。

無法辨識的變數仍會以額外工作階段參數的形式,傳送至 [Dialogflow 代理][Agent.RemoteDialogflowAgent]。

event

object (Event)

選用。事件輸入。

互斥欄位結束。

ToolResponses

用戶端要求的工具呼叫執行結果。

JSON 表示法
{
  "toolResponses": [
    {
      object (ToolResponse)
    }
  ]
}
欄位
toolResponses[]

object (ToolResponse)

選用。工具執行結果清單。

SessionInput.RecordingControl

應用程式做出的決定可能會記錄下來。

這個列舉可擴充,日後可能會新增值。

列舉
RECORDING_CONTROL_UNSPECIFIED 應用程式並未控制錄製功能。應用程式的記錄設定會決定,就像每個從未設定這個欄位的工作階段一樣。
RECORDING_ENABLED 從現在起,系統可能會錄音並記錄對話內容。
RECORDING_DISABLED 系統可能不會再錄製或記錄對話。

Evaluation.Scenario

情境設定

JSON 表示法
{
  "task": string,
  "userFacts": [
    {
      object (Evaluation.Scenario.UserFact)
    }
  ],
  "maxTurns": integer,
  "rubrics": [
    string
  ],
  "scenarioExpectations": [
    {
      object (Evaluation.ScenarioExpectation)
    }
  ],
  "variableOverrides": {
    object
  },
  "taskCompletionBehavior": enum (Evaluation.Scenario.TaskCompletionBehavior),
  "userGoalBehavior": enum (Evaluation.Scenario.UserGoalBehavior),
  "evaluationExpectations": [
    string
  ],
  "milestones": [
    {
      object (Evaluation.Scenario.Milestone)
    }
  ],
  "scenarioExecutionMode": enum (EvaluationSettings.ScenarioExecutionMode)
}
欄位
task

string

這是必要旗標,情境要指定的任務。

userFacts[]

object (Evaluation.Scenario.UserFact)

選用。情境要使用的使用者事實。

maxTurns

integer

選用。要模擬的回合數上限。最大值為 100。預設值為 100。

rubrics[]

string

這是必要旗標,情境的評分標準。

scenarioExpectations[]

object (Evaluation.ScenarioExpectation)

這是必要旗標,ScenarioExpectations:評估使用者模擬功能生成的對話。

variableOverrides

object (Struct format)

選用。變數/工作階段參數,做為工作階段的背景資訊,以變數名稱為索引鍵。這個結構體的成員會覆寫系統設定的所有預設值。

請注意,這與使用者事實不同,後者是指使用者已知的事實。變數是代理已知的參數,例如電話系統傳遞的 MDN (電話號碼)。

taskCompletionBehavior
(deprecated)

enum (Evaluation.Scenario.TaskCompletionBehavior)

選用。已淘汰,請改用 userGoalBehavior。

userGoalBehavior

enum (Evaluation.Scenario.UserGoalBehavior)

選用。使用者目標的預期行為。

evaluationExpectations[]

string

選用。評估模擬對話時,所依據的評估預期。格式:projects/{project}/locations/{location}/apps/{app}/evaluationExpectations/{evaluationExpectation}

milestones[]

object (Evaluation.Scenario.Milestone)

選用。這個情境的里程碑。

scenarioExecutionMode

enum (EvaluationSettings.ScenarioExecutionMode)

選用。情境評估的執行模式。

Evaluation.Scenario.TaskCompletionBehavior

使用者工作的預期行為。這項資訊可用來判斷情境是否成功。

列舉
TASK_COMPLETION_BEHAVIOR_UNSPECIFIED 未指定行為。預設為 TASK_SATISFIED。
TASK_SATISFIED 使用者工作應會順利完成。
TASK_REJECTED 使用者工作應遭拒。

Evaluation.Scenario.UserGoalBehavior

使用者目標的預期行為。這項資訊可用來判斷情境是否成功。

列舉
USER_GOAL_BEHAVIOR_UNSPECIFIED 未指定行為。預設為 USER_GOAL_SATISFIED。
USER_GOAL_SATISFIED 使用者目標應能順利完成。
USER_GOAL_REJECTED 應拒絕使用者目標。
USER_GOAL_IGNORED 忽略使用者目標狀態。

方法

create

建立評估作業。

delete

刪除評估作業。

export

匯出評估作業。

get

取得指定評估作業的詳細資料。

list

列出指定應用程式中的所有評估。

patch

更新評估作業。

uploadEvaluationAudio

上傳音訊,用於黃金標準評估。