龍騰 AI 非選批閱平台 開發者文件中心
API 參考

評分標準 Rubric

評分標準定義 AI 如何給分。可作為獨立資源共用，也可直接內嵌於單一題目。

列出評分標準

GET
/rubrics

回傳摘要，每個標準一筆，取最新版本，只含識別與標籤而不含評分本體； 要看 levels / dimensions 請以 id 取單一標準。

認證方式

bearerAuth questions:read
認證Bearer <token>

Authorization: Bearer sk_live_…

每個請求都帶一個 bearer 憑證。端點一律以 scope 授權； 缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。

位置: header

Scope: questions:read

查詢參數

name?string

以不分大小寫的子字串比對標籤。此處刻意偏離一般的完全比對， 因為它是給人用的題庫搜尋：?name=作文 會回傳所有名稱含「作文」的標準。

status?string
Default"active"
owner?string

篩選標準的維護者：organization 是貴組織自建的標準，platform 是 內建預設評分標準。 未指定時兩者並列。

Value in

  • "organization"
  • "platform"
sort?string

排序欄位，前綴 - 為遞減、+ 或無前綴為遞增，以逗號分隔可指定多個欄位 （例如 -created_at,status）。無法辨識的欄位名會得到 400 ERR_VALIDATION_FAILED， 不會被忽略。

預設為 -created_at，即最新建立的排在最前面。 游標分頁的頁面邊界取決於排序， 因此順序是有定義的而非未指定。

批閱結果版本歷史與覆核清單另有各自的預設（分別為 -version 與 -graded_at），

Default"-created_at"
limit?integer

每頁筆數，最大 100。

Rangevalue <= 100
Default20
cursor?string

前一頁回應中的 next_cursor。游標是不透明權杖，請勿解析或自行組合。 持續翻頁直到 has_more 為 false。

回應內容

application/json

curl -X GET "https://example.com/rubrics"
{  "data": [    {      "id": "string",      "name": "string",      "version": 0,      "status": "active",      "owner": "organization",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "pagination": {    "has_more": true,    "next_cursor": "string"  }}

建立評分標準

POST
/rubrics

建立 version 1 的獨立評分標準。

name 是必填：它是題庫搜尋 ?name= 比對的標籤，沒有名字的標準只能靠不透明 id 找到。 接著是標準本體：dimensions 或 criteria（兩者擇一）。

建立的一律是組織自有的標準（owner: "organization"）；id、version、status、 owner、created_at 由伺服器指派，帶入即拒絕。

認證方式

bearerAuth questions:manage
認證Bearer <token>

Authorization: Bearer sk_live_…

每個請求都帶一個 bearer 憑證。端點一律以 scope 授權； 缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。

位置: header

Scope: questions:manage

標頭參數

Idempotency-Key?string

建議帶上。同一把金鑰配同樣的內容重送時，會重播原本儲存的回應 （連同原本的 2xx 狀態碼），不會重複建立。金鑰保留 24 小時。

請求內容

application/json

TypeScript 型別定義

在 TypeScript 中使用 request body 型別。

評分標準的本體。它宣告 dimensions 與 criteria 其中之一， 而選了哪一個就決定了批閱結果的形狀，沒有旗標需要另外設定， 也因此消費端不必先讀到標準才知道手上的細目該怎麼解讀。

宣告意義與總分的關係
dimensions分解：各項構成總分Σ earned = score.earned，無條件成立
criteria歸因：各項解釋總分沒有算術關係；結果中的 level 不帶 max

criteria 標準的總分由平台端的計分程式產生，其方法不屬於本合約； 該程式套用的規則（扣分、封頂、打折）會以批閱結果的 penalties 呈現。

級距用 score 還是 ratio，決定這份標準能不能跨滿分重複使用。 ratio 級距不帶絕對數值，因此同一套標準可以服務任何滿分的題目； score 級距自帶數值，因此只適用於滿分等於其加總的題目。 同一份標準內不得混用兩種形式。

引擎不會在級距之間給分。 引擎產生的數值恰好是命中級距的值， 所以客戶端可以只用它反推級距，批閱結果因此不帶任何指名級距的欄位。 （人工覆核不受此限。）

回應內容

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/rubrics" \  -H "Content-Type: application/json" \  -d '{    "name": "簡答題全／半／零通用標準",    "dimensions": [      {        "name": "整體",        "weight": 1,        "levels": [          {            "ratio": 1,            "description": "完整答出題目要求的所有要點。"          },          {            "ratio": 0.5,            "description": "答出部分要點，或要點正確但不完整。"          },          {            "ratio": 0,            "description": "答案錯誤、離題或空白。"          }        ]      }    ]  }'
{  "data": {    "id": "string",    "version": 0,    "status": "active",    "owner": "organization",    "created_at": "2019-08-24T14:15:22Z",    "name": "string",    "dimensions": [      {        "name": "string",        "description": "string",        "weight": 0,        "levels": [          {            "score": 0,            "ratio": 0,            "description": "string",            "examples": [              "string"            ],            "metadata": {}          }        ]      }    ],    "criteria": [      {        "name": "string",        "description": "string",        "levels": [          {            "ratio": 0,            "description": "string",            "examples": [              "string"            ],            "metadata": {}          }        ]      }    ],    "metadata": {}  }}

取得評分標準

GET
/rubrics/{rubric_id}

已封存的標準一樣正常回傳：封存管的是可發現性，不是可解析性， 所以現有題目釘選的 "rub_x:2" 在任何狀態下都解析得到。

認證方式

bearerAuth questions:read
認證Bearer <token>

Authorization: Bearer sk_live_…

每個請求都帶一個 bearer 憑證。端點一律以 scope 授權； 缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。

位置: header

Scope: questions:read

路徑參數

rubric_id*string

查詢參數

version?integer

指定版本；省略時取最新版本。

回應內容

application/json

application/json

curl -X GET "https://example.com/rubrics/rub_fhz"
{  "data": {    "id": "string",    "version": 0,    "status": "active",    "owner": "organization",    "created_at": "2019-08-24T14:15:22Z",    "name": "string",    "dimensions": [      {        "name": "string",        "description": "string",        "weight": 0,        "levels": [          {            "score": 0,            "ratio": 0,            "description": "string",            "examples": [              "string"            ],            "metadata": {}          }        ]      }    ],    "criteria": [      {        "name": "string",        "description": "string",        "levels": [          {            "ratio": 0,            "description": "string",            "examples": [              "string"            ],            "metadata": {}          }        ]      }    ],    "metadata": {}  }}

更新評分標準（產生新版本）

PATCH
/rubrics/{rubric_id}

建立新版本並回傳。與題目相同，送出的每個欄位都是整個取代，不做合併： 送出 levels 會取代整組級距，未送出的欄位由前一版沿用。新版本必須滿足建立時的每一條規則。

現有題目完全不受影響：題目的 scoring.rubric_ref 在題目寫入時就解析為明確版本， "rub_fhz:1" 會永遠以 version 1 批閱；只有之後才寫入的題目能採用新版本。

認證方式

bearerAuth questions:manage
認證Bearer <token>

Authorization: Bearer sk_live_…

每個請求都帶一個 bearer 憑證。端點一律以 scope 授權； 缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。

位置: header

Scope: questions:manage

路徑參數

rubric_id*string

請求內容

application/json

TypeScript 型別定義

在 TypeScript 中使用 request body 型別。

評分標準的本體。它宣告 dimensions 與 criteria 其中之一， 而選了哪一個就決定了批閱結果的形狀，沒有旗標需要另外設定， 也因此消費端不必先讀到標準才知道手上的細目該怎麼解讀。

宣告意義與總分的關係
dimensions分解：各項構成總分Σ earned = score.earned，無條件成立
criteria歸因：各項解釋總分沒有算術關係；結果中的 level 不帶 max

criteria 標準的總分由平台端的計分程式產生，其方法不屬於本合約； 該程式套用的規則（扣分、封頂、打折）會以批閱結果的 penalties 呈現。

級距用 score 還是 ratio，決定這份標準能不能跨滿分重複使用。 ratio 級距不帶絕對數值，因此同一套標準可以服務任何滿分的題目； score 級距自帶數值，因此只適用於滿分等於其加總的題目。 同一份標準內不得混用兩種形式。

引擎不會在級距之間給分。 引擎產生的數值恰好是命中級距的值， 所以客戶端可以只用它反推級距，批閱結果因此不帶任何指名級距的欄位。 （人工覆核不受此限。）

回應內容

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/rubrics/rub_fhz" \  -H "Content-Type: application/json" \  -d '{}'
{  "data": {    "id": "string",    "version": 0,    "status": "active",    "owner": "organization",    "created_at": "2019-08-24T14:15:22Z",    "name": "string",    "dimensions": [      {        "name": "string",        "description": "string",        "weight": 0,        "levels": [          {            "score": 0,            "ratio": 0,            "description": "string",            "examples": [              "string"            ],            "metadata": {}          }        ]      }    ],    "criteria": [      {        "name": "string",        "description": "string",        "levels": [          {            "ratio": 0,            "description": "string",            "examples": [              "string"            ],            "metadata": {}          }        ]      }    ],    "metadata": {}  }}

封存評分標準

POST
/rubrics/{rubric_id}/archive

與題目封存完全一致：標準離開預設列表、不能再被新題目採用， 而每個已釘選的 "rub_x:2" 照常解析，批閱結果不變。不會產生新版本。

退役一套標準前，先用 GET /questions?rubric_ref=rub_x 查出所有釘選它的題目。

認證方式

bearerAuth questions:manage
認證Bearer <token>

Authorization: Bearer sk_live_…

每個請求都帶一個 bearer 憑證。端點一律以 scope 授權； 缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。

位置: header

Scope: questions:manage

路徑參數

rubric_id*string

回應內容

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/rubrics/rub_fhz/archive"
{  "data": {    "id": "string",    "version": 0,    "status": "active",    "owner": "organization",    "created_at": "2019-08-24T14:15:22Z",    "name": "string",    "dimensions": [      {        "name": "string",        "description": "string",        "weight": 0,        "levels": [          {            "score": 0,            "ratio": 0,            "description": "string",            "examples": [              "string"            ],            "metadata": {}          }        ]      }    ],    "criteria": [      {        "name": "string",        "description": "string",        "levels": [          {            "ratio": 0,            "description": "string",            "examples": [              "string"            ],            "metadata": {}          }        ]      }    ],    "metadata": {}  }}

取消封存評分標準

POST
/rubrics/{rubric_id}/unarchive

認證方式

bearerAuth questions:manage
認證Bearer <token>

Authorization: Bearer sk_live_…

每個請求都帶一個 bearer 憑證。端點一律以 scope 授權； 缺少必要 scope 會得到 403 ERR_INVALID_SCOPE，details 為 {required, available}。

位置: header

Scope: questions:manage

路徑參數

rubric_id*string

回應內容

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/rubrics/rub_fhz/unarchive"
{  "data": {    "id": "string",    "version": 0,    "status": "active",    "owner": "organization",    "created_at": "2019-08-24T14:15:22Z",    "name": "string",    "dimensions": [      {        "name": "string",        "description": "string",        "weight": 0,        "levels": [          {            "score": 0,            "ratio": 0,            "description": "string",            "examples": [              "string"            ],            "metadata": {}          }        ]      }    ],    "criteria": [      {        "name": "string",        "description": "string",        "levels": [          {            "ratio": 0,            "description": "string",            "examples": [              "string"            ],            "metadata": {}          }        ]      }    ],    "metadata": {}  }}

題目 Question

題目是組織自有的題庫資源，逐版本不可變：每次更新都產生新版本，考試則釘選特定版本。

學生名冊 Roster

學生名冊把提交上的不透明學生識別碼對應到可讀的姓名，供覆核介面顯示。