取得批閱結果

outcome 判定、各評分法對應的批閱結果、penalties，以及版本歷史的讀取方式

批閱結果（Evaluation）是 AI 對單一題目作答所產生的評分與評語。批閱結果使用版本化管理。第一版由平台 AI 批閱產生，並可以透過人工覆核產生新版本。

讀取批閱結果

使用以下三種 API 端點讀取批閱結果。

方式	取得內容
`GET /submissions/{id}`	讀取提交，每筆作答內嵌最新版本
`GET /responses/{id}/evaluation`	單一作答的最新版本
`GET /responses/{id}/evaluation/history`	單一作答所有版本

若批閱尚在進行，或批閱任務失敗，/responses/{id}/evaluation* 端點將回應 404 ERR_NOT_FOUND 錯誤。

結果結構

{
  "id": "eval_8Sm4Tb",
  "response_id": "resp_5Kc3Yv",
  "version": 1,
  "method": "rubric_grading",
  "outcome": "graded",
  "score": { "earned": 7, "max": 10 },
  "dimensions": [
    {
      "key": "內容正確性",
      "score": { "earned": 3, "max": 6 },
      "feedback": "光反應說明正確，暗反應產物有誤。"
    },
    {
      "key": "完整性",
      "score": { "earned": 4, "max": 4 },
      "feedback": "涵蓋所有主要步驟。"
    }
  ],
  "feedback": "整體結構完整，建議補強暗反應的化學細節。",
  "review_suggested": false,
  "grader_revision": "grev_5a1d8c",
  "graded_by": "ai",
  "graded_at": "2026-03-02T09:33:15Z"
}

score.max 永遠等於被批閱題目版本的 scoring.max_score。

`outcome` 判定

每個由 AI 產生的批閱結果，都將帶有 outcome 參數，代表 AI 對作答本身的判定與批閱分類。

`outcome`	意義	`score.earned`	作答狀態
`graded`	依規則正常批閱	依實際評分	`completed`
`blank`	沒有可批閱的內容：空白，或僅有空白字元與標點	`0`	`completed`
`sensitive_content`	敏感或違反政策的內容，不就其內容批閱	`0`	`completed`

上述三者都是正常完成的批閱結果，不應將任何一者視為失敗，且所有批閱結果的分數均可正常讀取。該些分數可以照常被覆核。

填充題的逐格判定

填充題的每一格都帶有自己的 outcome（值域相同），整題的 outcome 則是各格的匯總：

條件	整題 `outcome`
任一格為 `sensitive_content`	`sensitive_content`
否則，每一格皆為 `blank`	`blank`
其餘情形	`graded`

評分方法與對應的批閱結果

一筆批閱結果中，最多只會出現一個細目欄位，欄位名稱取決於該題的批閱方式 method；rubric_grading 時再取決於該題所使用的評分標準採分析式或整體式評分。

`method`	評分標準採用	細目欄位	與總分的關係
`rubric_grading`	分析式（`dimensions`）	`dimensions`	`Σ earned = score.earned` 且 `Σ max = score.max`
`rubric_grading`	整體式（`criteria`）	`criteria`	無算術關係，總分由計分程式產生
`blank_grading`	逐格設定	`blanks`	`Σ earned = score.earned` 且 `Σ max = score.max`

客戶端可直接依收到的欄位處理。dimensions 與 blanks 可與總分互相核對，criteria 則不行。

dimensions[].key 與 criteria[].key 的值，即為評分標準中該向度或準則的名稱。

`dimensions` 分數的構成

dimensions 是構成總分的各個部分，每筆帶有 key、score: { earned, max }，以及選填的 feedback。

每個向度會對應到自己的一個級距，並取得該級距的分數價值，因此總分即為各向度得分的加總：score.earned = Σ earned，且 score.max = Σ max。

`criteria` 作答的歸因

criteria 是解釋總分的各條軸，每筆帶有 key、level，以及選填的 feedback。

level 為該準則所命中級距的 ratio，代表作答在該條軸上的落點，並非分數。各準則之間不可互相比較，也不參與任何加總。整體式評分的總分由本服務的計分程式產生，詳見整體式評分。

`penalties` 觸發了哪些計分規則

有些題型或本服務內建的評分標準程式中，另會對作答套用特定的硬性評分規則（例如：寫作未滿字數則扣分）。該些觸發規則將記錄於 penalties 參數中。

"penalties": [
  { "code": "no_paragraphing", "description": "全文未分段" },
  { "code": "off_topic", "description": "嚴重離題，總分設有上限" }
]

欄位	說明
`code`	該規則的機器可讀識別碼，可用於程式分支。代碼集合依題型而定，並以加法方式成長；無法辨識的代碼請忽略，改用 `description`。
`description`	人類可讀的說明，可直接顯示，不需要另外維護代碼對照表。

此些欄位不提供調整的幅度數值。實際的計分結果請以 score 為準。

penalties 屬於 AI 批閱的判斷結果，因此只出現在 version 1，覆核版本不會帶有此欄位。若覆核者認為某條規則不應觸發，請直接覆核並給出修正後的分數，於 reason 中說明理由。

`blanks` 逐格細目

填充題的結果帶有 blanks，題目宣告幾格即有幾筆，依題目中的順序排列。

{
  "method": "blank_grading",
  "outcome": "graded",
  "score": { "earned": 4, "max": 6 },
  "blanks": [
    {
      "key": "mockBlank1leeu4igarik",
      "score": { "earned": 2, "max": 2 },
      "outcome": "graded"
    },
    {
      "key": "mockBlank2r7fnq2xoahd",
      "score": { "earned": 0, "max": 2 },
      "outcome": "graded"
    },
    {
      "key": "mockBlank3ve1kzsp6mtb",
      "score": { "earned": 2, "max": 2 },
      "outcome": "graded",
      "feedback": "兩項產物皆正確。"
    }
  ]
}

key 即題目中的 blank_id。

每格分別採用的計分方式（完全比對或 AI 判定），結果中不會重複記載。該資訊由題目版本的 scoring.blanks[].method 決定。

人工檢閱建議提示

當批閱過程中，若學生作答存在一定的特殊性，批閱結果將帶 review_suggested 參數，並給定布林值為 true。代表系統建議該批閱結果可以進行人工檢閱。

就算系統建議可進行人工檢閱，該些批閱結果仍可正常使用，與其他所有未帶有建議的批閱結果相同。人工檢閱並非必要的動作，也不代表批閱結果存在錯誤或未完成。

建議提示由系統依照多重特徵及因素計算，計算的基準會隨 AI 模型、提示詞、系統結構等演進而變動。請直接使用該布林值建立工作佇列，不要反推任何數值門檻。

批閱結果版本歷史

請使用 GET /responses/{id}/evaluation/history 端點，讀取一份批閱結果的覆核歷史。此端點使用本服務 API 通用的分頁列表，依 version 由新到舊排列，data[0] 即為目前生效的最新版本。

{
  "data": [
    { "id": "eval_6Vq1Zr", "version": 2, "graded_by": "user_3Nb7Qh", "…": "…" },
    { "id": "eval_8Sm4Tb", "version": 1, "graded_by": "ai", "…": "…" }
  ],
  "pagination": { "has_more": false }
}

版本建立者參照

各批閱結果的版本中，均以 graded_by 參數註記該版本由誰產生。

值	執行者
`"ai"`	平台自動批閱產生的版本（僅會出現於所有作答的第一版批閱結果）
`user_…`	管理人員透過 Studio 工作階段覆核的版本
`ak_…`	持有 `evaluations:revise` 的 API 金鑰產生的覆核版本
`"norma_ops"`	平台維運人員提供客戶服務支援所作的修正版本

norma_ops 在一般情況下不會出現。 該種類僅適用於事前與貴組織溝通過的修正個案。