> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/api-reference/ping-gu-he-ce-shi-ji.md).
# 評估與測試集
評估與測試集端點對應後台 AgentOps 的「測試集」與「自動化測試」，讓您從自己的系統批次測試 Agent。完整流程是：
1. **建立測試集**：用 `POST /api/v1/dataset/` 建立空白測試集，或用 `POST /api/v1/dataset/upload/` 上傳 CSV／Excel 一次建好。
2. **加入測試案例**：單輪問答用 `/api/v1/test-case/`（逐筆建立、上傳檔案或從知識庫檔案生成），多輪對話情境用 `/api/v1/multi-turn-test-case/`。從知識庫檔案生成在背景執行，回應 `202` 與 `jobId`，再用 [查詢測試案例生成任務進度](#test-case-generation-jobs-retrieve) 追蹤。
3. **執行評估**：用 `POST /api/v1/evaluations/evaluate/`（單輪）或 `POST /api/v1/evaluations/multi-turn-evaluate/`（多輪）指定測試集與 Agent，回應 `202` 與 `evaluationId`。
4. **讀取結果與匯出**：輪詢 `GET /api/v1/evaluations/{id}/`，`status` 變成 `completed`、`partial_completed` 或 `failed` 即結束；單輪的逐題結果在 `details`，多輪的逐對話結果在 `multi-turn-results`。已完成的單輪評估可以用 `export` 匯出 Excel 報表，再從 `export-status` 取得下載網址。
**所需權限**：API Key 以建立它的成員身分呼叫。`/dataset/`、`/test-case/`、`/multi-turn-test-case/` 的列表與所有寫入操作需要角色具備「測試集權限」，`/evaluations/` 的列表與所有寫入操作需要「自動化測試權限」（[角色權限](https://docs.maiagent.ai/org/roles/role-permission)中的 AgentOps 權限；擁有者一律具備），權限不足回 `403`。擁有者以外的成員只看得到、也只能評估自己角色可使用的 Agent。
**Credit**：從知識庫檔案生成測試案例，依實際生成的題數扣計價項目 `agentops_test_gen`；執行評估在結束時依完成的測試案例數扣 `agentops_test_run` 與 `agentops_deepeval`，評分用的評估模型呼叫另依該模型的用量計費。送出生成或評估前，系統會先檢查組織 Credit 與額度，不足回 `402`。手動建立、上傳檔案與讀取結果不扣 Credit；各項單價見 [列出計價項目](/api/api-reference/credit.md#credit-items-list)。
功能與後台操作見使用者手冊[測試集管理](https://docs.maiagent.ai/build/agent-ops/test-datasets)與[自動評估與 Agent 監控](https://docs.maiagent.ai/build/agent-ops/evaluations)。
### 列出測試集
GET `/api/v1/dataset/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------- | -- | ------- | ------------------------------------------------------------------------ |
| `isActive` | ❌ | boolean | 只列出啟用（true）或停用（false）的資料集 |
| `ordering` | ❌ | string | 排序欄位：created\_at 或 updated\_at，前面加 - 為由新到舊（例：-updated\_at）；未指定時依建立時間由新到舊 |
| `page` | ❌ | integer | 頁碼，從 1 開始；超過最後一頁回 404 |
| `pageSize` | ❌ | integer | 每頁筆數，預設 20、上限 100（超過以 100 計） |
| `query` | ❌ | string | 關鍵字，比對資料集名稱、描述或 ID（部分符合） |
| `search` | ❌ | string | 關鍵字，比對資料集名稱或描述（部分符合、不分大小寫；以空白分隔多個關鍵字時須全部符合） |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/dataset/?isActive=true&ordering=example&page=1&pageSize=1&query=example&search=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/dataset/?isActive=true&ordering=example&page=1&pageSize=1&query=example&search=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/?isActive=true&ordering=example&page=1&pageSize=1&query=example&search=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/dataset/?isActive=true&ordering=example&page=1&pageSize=1&query=example&search=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"name": string
"description"?: string // 非必填
"organization":
{
"id": string (uuid)
"name": string
}
"createdBy":
{
"id": string (uuid)
"name": string
}
"isActive"?: boolean // 非必填
"singleTurnTestCaseCount": integer
"multiTurnTestCaseCount": integer
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"isActive": false,
"singleTurnTestCaseCount": 456,
"multiTurnTestCaseCount": 456,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
]
}
```
***
### 建立空白測試集
POST `/api/v1/dataset/`
{% hint style="info" %}
測試集名稱在組織內不可重複，重複時回 `400`。
{% endhint %}
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ----------- | ------ | -- | -- |
| name | string | 是 | |
| description | string | 否 | |
**請求結構範例**
```typescript
{
"name": string
"description"?: string // 非必填
}
```
**請求範例值**
```json
{
"name": "範例名稱",
"description": "範例字串"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/dataset/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "範例名稱",
"description": "範例字串"
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": "範例名稱",
"description": "範例字串"
};
axios.post("https://api.maiagent.ai/api/v1/dataset/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": "範例名稱",
"description": "範例字串"
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/dataset/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => '範例名稱',
'description' => '範例字串'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"description"?: string // 非必填
"organization":
{
"id": string (uuid)
"name": string
}
"createdBy":
{
"id": string (uuid)
"name": string
}
"isActive"?: boolean // 非必填
"singleTurnTestCaseCount": integer
"multiTurnTestCaseCount": integer
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"isActive": false,
"singleTurnTestCaseCount": 456,
"multiTurnTestCaseCount": 456,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 上傳 CSV 或 Excel 建立測試集
POST `/api/v1/dataset/upload/`
{% hint style="info" %}
以 `multipart/form-data` 上傳：`file` 與 `name` 必填，`description` 選填。檔案格式同 [上傳 CSV 或 Excel 加入測試案例](#test-case-upload-create)；測試集名稱在組織內不可重複。
{% endhint %}
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/dataset/upload/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-F "file=@example_file.csv" \
-F "name=範例字串" \
-F "description=範例字串"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
const FormData = require('form-data');
// 建立FormData對象
const formData = new FormData();
// 請用實際檔案替換
formData.append('file', /* 實際檔案物件 */, 'example_file.csv');
formData.append('name', '範例字串');
formData.append('description', '範例字串');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
...formData.getHeaders()
}
};
axios.post("https://api.maiagent.ai/api/v1/dataset/upload/", formData, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/upload/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
# 建立檔案和表單資料
files = {
'file': ('example_file.csv', open('example_file.csv', 'rb'), 'text/csv'),
'name': (None, '範例字串'),
'description': (None, '範例字串')
}
response = requests.post(url, files=files, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/dataset/upload/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
],
'multipart' => [
[
'name' => 'file',
'contents' => fopen('example_file.csv', 'r'),
'filename' => 'example_file.csv'
],
[
'name' => 'name',
'contents' => '範例字串'
],
[
'name' => 'description',
'contents' => '範例字串'
]
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"description"?: string // 非必填
"organization":
{
"id": string (uuid)
"name": string
}
"createdBy":
{
"id": string (uuid)
"name": string
}
"isActive"?: boolean // 非必填
"singleTurnTestCaseCount": integer
"multiTurnTestCaseCount": integer
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"isActive": false,
"singleTurnTestCaseCount": 456,
"multiTurnTestCaseCount": 456,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 從知識庫檔案生成測試集
POST `/api/v1/dataset/generate-from-file/`
{% hint style="info" %}
以單一知識庫檔案（`knowledgeBaseFileId`）建立新測試集並生成單輪測試案例，`numTestCases` 為 1～50（預設 10）。生成在背景執行，實際回應是 `202` 與 `taskId`，不含測試集 ID，也沒有進度可查；完成後新測試集會出現在列表中。需要追蹤進度時，請先建立空白測試集，再用 [從知識庫檔案生成單輪測試案例](#test-case-generate-from-file-create)。**Credit**：送出前檢查組織 Credit，不足回 `402`；依實際生成的題數扣 `agentops_test_gen`。
{% endhint %}
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------------- | ------------- | -- | -- |
| name | string | 是 | |
| description | string | 否 | |
| chatbotFileId | string (uuid) | 否 | |
| knowledgeBaseFileId | string (uuid) | 否 | |
| numTestCases | integer | 否 | |
**請求結構範例**
```typescript
{
"name": string
"description"?: string // 非必填
"chatbotFileId"?: string (uuid) // 非必填
"knowledgeBaseFileId"?: string (uuid) // 非必填
"numTestCases"?: integer // 非必填
}
```
**請求範例值**
```json
{
"name": "範例名稱",
"description": "範例字串",
"chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/dataset/generate-from-file/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "範例名稱",
"description": "範例字串",
"chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": "範例名稱",
"description": "範例字串",
"chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
};
axios.post("https://api.maiagent.ai/api/v1/dataset/generate-from-file/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/generate-from-file/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": "範例名稱",
"description": "範例字串",
"chatbotFileId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/dataset/generate-from-file/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => '範例名稱',
'description' => '範例字串',
'chatbotFileId' => '550e8400-e29b-41d4-a716-446655440000',
'knowledgeBaseFileId' => '550e8400-e29b-41d4-a716-446655440000',
'numTestCases' => 123
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 202**
**回應結構範例**
```typescript
{
"status": string (enum: accepted) // * `accepted` - 固定為 accepted，表示已受理並排入背景執行
"message": string // 受理說明
"taskId": string // 背景任務 ID
}
```
**回應範例值**
```json
{
"status": "accepted",
"message": "回應字串",
"taskId": "回應字串"
}
```
***
### 列出可生成測試案例的知識庫檔案
GET `/api/v1/dataset/knowledge-base-files/`
{% hint style="info" %}
依知識庫分組，只列出處理完成、類型為 txt、docx、pdf、md、markdown、mdx 的檔案。`pageSize` 是每個知識庫最多回傳的檔案數（預設 5，上限 100），`search` 依檔名篩選。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------- | -- | ------- | -------------------------- |
| `pageSize` | ❌ | integer | 每個知識庫最多回傳的檔案數（預設 5，上限 100） |
| `search` | ❌ | string | 依檔名篩選（部分符合，不分大小寫） |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/dataset/knowledge-base-files/?pageSize=1&search=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/dataset/knowledge-base-files/?pageSize=1&search=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/knowledge-base-files/?pageSize=1&search=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/dataset/knowledge-base-files/?pageSize=1&search=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"knowledgeBases": [ // 有可用檔案的知識庫，依名稱排序；沒有可用檔案的知識庫不列出
{
"id": string (uuid)
"name": string
"files":
{
"count": integer // 此知識庫符合條件的檔案總數
"results": [ // 最新的 page_size 個檔案
{
"id": string (uuid)
"filename": string
"fileType": string
"size": integer // File size in bytes
"knowledgeBase":
{
"id": string (uuid)
"name": string
}
}
]
}
}
]
}
```
**回應範例值**
```json
{
"knowledgeBases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"files": {
"count": 456,
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"filename": "回應字串",
"fileType": "回應字串",
"size": 456,
"knowledgeBase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
}
}
]
}
}
]
}
```
***
### 取得特定測試集
GET `/api/v1/dataset/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ------ |
| `id` | ✅ | string | 資料集 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"description"?: string // 非必填
"organization":
{
"id": string (uuid)
"name": string
}
"createdBy":
{
"id": string (uuid)
"name": string
}
"isActive"?: boolean // 非必填
"singleTurnTestCaseCount": integer
"multiTurnTestCaseCount": integer
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"isActive": false,
"singleTurnTestCaseCount": 456,
"multiTurnTestCaseCount": 456,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 取得測試集與單輪測試案例
GET `/api/v1/dataset/{id}/details/`
{% hint style="info" %}
回應在測試集欄位之外另含 `testCases` 陣列，只包含單輪測試案例；多輪測試案例請用 `GET /api/v1/multi-turn-test-case/?datasetId={id}`。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ------ |
| `id` | ✅ | string | 資料集 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/details/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/details/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/details/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/details/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"description"?: string // 非必填
"organization":
{
"id": string (uuid)
"name": string
}
"createdBy":
{
"id": string (uuid)
"name": string
}
"isActive"?: boolean // 非必填
"singleTurnTestCaseCount": integer
"multiTurnTestCaseCount": integer
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"testCases": [ // 此測試集的全部單輪測試案例，依建立時間由舊到新；沒有測試案例時為空陣列
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"question": string
"groundTruth"?: string // 非必填
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
"creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (非必填)
"sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (非必填)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"isActive": false,
"singleTurnTestCaseCount": 456,
"multiTurnTestCaseCount": 456,
"createdAt": "回應字串",
"updatedAt": "回應字串",
"testCases": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"question": "回應字串",
"groundTruth": "回應字串",
"status": "active",
"creationMethod": "manual",
"sourceFile": "回應字串",
"flaky": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
]
}
```
***
### 更新測試集
PUT `/api/v1/dataset/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ------ |
| `id` | ✅ | string | 資料集 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ----------- | ------- | -- | -- |
| name | string | 是 | |
| description | string | 否 | |
| isActive | boolean | 否 | |
**請求結構範例**
```typescript
{
"name": string
"description"?: string // 非必填
"isActive"?: boolean // 非必填
}
```
**請求範例值**
```json
{
"name": "範例名稱",
"description": "範例字串",
"isActive": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "範例名稱",
"description": "範例字串",
"isActive": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": "範例名稱",
"description": "範例字串",
"isActive": true
};
axios.put("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": "範例名稱",
"description": "範例字串",
"isActive": True
}
response = requests.put(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => '範例名稱',
'description' => '範例字串',
'isActive' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"description"?: string // 非必填
"organization":
{
"id": string (uuid)
"name": string
}
"createdBy":
{
"id": string (uuid)
"name": string
}
"isActive"?: boolean // 非必填
"singleTurnTestCaseCount": integer
"multiTurnTestCaseCount": integer
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"isActive": false,
"singleTurnTestCaseCount": 456,
"multiTurnTestCaseCount": 456,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 部分更新測試集
PATCH `/api/v1/dataset/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ------ |
| `id` | ✅ | string | 資料集 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ----------- | ------- | -- | -- |
| name | string | 否 | |
| description | string | 否 | |
| isActive | boolean | 否 | |
**請求結構範例**
```typescript
{
"name"?: string // 非必填
"description"?: string // 非必填
"isActive"?: boolean // 非必填
}
```
**請求範例值**
```json
{
"name": "範例名稱",
"description": "範例字串",
"isActive": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "範例名稱",
"description": "範例字串",
"isActive": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": "範例名稱",
"description": "範例字串",
"isActive": true
};
axios.patch("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": "範例名稱",
"description": "範例字串",
"isActive": True
}
response = requests.patch(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => '範例名稱',
'description' => '範例字串',
'isActive' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"description"?: string // 非必填
"organization":
{
"id": string (uuid)
"name": string
}
"createdBy":
{
"id": string (uuid)
"name": string
}
"isActive"?: boolean // 非必填
"singleTurnTestCaseCount": integer
"multiTurnTestCaseCount": integer
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"createdBy": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"isActive": false,
"singleTurnTestCaseCount": 456,
"multiTurnTestCaseCount": 456,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 刪除測試集
DELETE `/api/v1/dataset/{id}/`
{% hint style="info" %}
刪除後無法復原，會一併刪除測試集內的所有測試案例，以及用這個測試集執行過的評估與結果。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ------ |
| `id` | ✅ | string | 資料集 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/dataset/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 列出單輪測試案例
GET `/api/v1/test-case/`
{% hint style="info" %}
用 `datasetId` 篩選單一測試集，也可依 `status`、`creationMethod`（`manual`、`file`、`generate`）篩選。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ------------------------------------------------------------------------------------------- |
| `creationMethod` | ❌ | string | 只列出以此方式建立的測試案例。可用值： \`manual\`: Manual ; \`file\`: File import ; \`generate\`: Generated; |
| `datasetId` | ❌ | string | 只列出此資料集的測試案例 |
| `ordering` | ❌ | string | 排序欄位：created\_at 或 updated\_at，前面加 - 為由新到舊（例：-updated\_at）；未指定時依建立時間由新到舊 |
| `page` | ❌ | integer | 頁碼，從 1 開始；超過最後一頁回 404 |
| `pageSize` | ❌ | integer | 每頁筆數，預設 20、上限 100（超過以 100 計） |
| `query` | ❌ | string | 關鍵字，比對問題、標準答案或 ID（部分符合） |
| `search` | ❌ | string | 關鍵字，比對問題或標準答案（部分符合、不分大小寫；以空白分隔多個關鍵字時須全部符合） |
| `status` | ❌ | string | 只列出此狀態的測試案例。可用值： \`active\`: Active ; \`inactive\`: Inactive ; \`pending\`: Pending Review; |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/test-case/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/test-case/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/test-case/?creationMethod=file&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&query=example&search=example&status=active", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"question": string
"groundTruth"?: string // 非必填
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
"creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (非必填)
"sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (非必填)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"question": "回應字串",
"groundTruth": "回應字串",
"status": "active",
"creationMethod": "manual",
"sourceFile": "回應字串",
"flaky": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
]
}
```
***
### 建立單輪測試案例
POST `/api/v1/test-case/`
{% hint style="info" %}
`datasetId`、`question`、`groundTruth` 必填。`status` 預設 `active`；評估只會執行 `active` 的測試案例。
{% endhint %}
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ----------- | ------------- | -- | -- |
| datasetId | string (uuid) | 是 | |
| question | string | 是 | |
| groundTruth | string | 是 | |
| status | string | 否 | |
| flaky | boolean | 否 | |
**請求結構範例**
```typescript
{
"datasetId": string (uuid)
"question": string
"groundTruth": string
"status"?: string // 非必填
"flaky"?: boolean // 非必填
}
```
**請求範例值**
```json
{
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"question": "範例字串",
"groundTruth": "範例字串",
"status": "範例字串",
"flaky": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/test-case/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"question": "範例字串",
"groundTruth": "範例字串",
"status": "範例字串",
"flaky": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"question": "範例字串",
"groundTruth": "範例字串",
"status": "範例字串",
"flaky": true
};
axios.post("https://api.maiagent.ai/api/v1/test-case/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"question": "範例字串",
"groundTruth": "範例字串",
"status": "範例字串",
"flaky": True
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/test-case/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'datasetId' => '550e8400-e29b-41d4-a716-446655440000',
'question' => '範例字串',
'groundTruth' => '範例字串',
'status' => '範例字串',
'flaky' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"question": string
"groundTruth"?: string // 非必填
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
"creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (非必填)
"sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (非必填)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"question": "回應字串",
"groundTruth": "回應字串",
"status": "active",
"creationMethod": "manual",
"sourceFile": "回應字串",
"flaky": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 上傳 CSV 或 Excel 加入測試案例
POST `/api/v1/test-case/upload/`
{% hint style="info" %}
以 `multipart/form-data` 上傳，`file` 與 `dataset_id` 都必填。檔案為 `.csv`、`.xlsx` 或 `.xls`，標題列須有 `question` 與 `ground_truth` 兩欄，每一列新增一筆單輪測試案例；CSV 請用 UTF-8 編碼。回應是新增測試案例的陣列。
{% endhint %}
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/test-case/upload/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-F "file=@example_file.csv" \
-F "dataset_id=550e8400-e29b-41d4-a716-446655440000"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
const FormData = require('form-data');
// 建立FormData對象
const formData = new FormData();
// 請用實際檔案替換
formData.append('file', /* 實際檔案物件 */, 'example_file.csv');
formData.append('dataset_id', '550e8400-e29b-41d4-a716-446655440000');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
...formData.getHeaders()
}
};
axios.post("https://api.maiagent.ai/api/v1/test-case/upload/", formData, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/upload/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
# 建立檔案和表單資料
files = {
'file': ('example_file.csv', open('example_file.csv', 'rb'), 'text/csv'),
'dataset_id': (None, '550e8400-e29b-41d4-a716-446655440000')
}
response = requests.post(url, files=files, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/test-case/upload/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
],
'multipart' => [
[
'name' => 'file',
'contents' => fopen('example_file.csv', 'r'),
'filename' => 'example_file.csv'
],
[
'name' => 'dataset_id',
'contents' => '550e8400-e29b-41d4-a716-446655440000'
]
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
[
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"question": string
"groundTruth"?: string // 非必填
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
"creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (非必填)
"sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (非必填)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
```
**回應範例值**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"question": "回應字串",
"groundTruth": "回應字串",
"status": "active",
"creationMethod": "manual",
"sourceFile": "回應字串",
"flaky": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
]
```
***
### 從知識庫檔案生成單輪測試案例
POST `/api/v1/test-case/generate-from-file/`
{% hint style="info" %}
用 `knowledgeBaseIds`（展開為知識庫內處理完成、類型支援的所有檔案）或 `knowledgeBaseFileIds` 指定來源，兩者可合用；支援 txt、docx、pdf、md、markdown、mdx。`numTestCases` 是這次要生成的總題數（預設 10），檔案數或題數超過平台上限時回 `400`，訊息會寫出上限。生成在背景執行，回應 `202` 與 `jobId`；同一個測試集已有生成任務在進行時，回傳該任務的 `jobId`，不會重複建立。**Credit**：送出前檢查組織 Credit，不足回 `402`；依實際生成的題數扣 `agentops_test_gen`。
{% endhint %}
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| -------------------- | -------------- | -- | ---------------------------------------------------------------------- |
| chatbotFileIds | array\[string] | 否 | List of KnowledgeBaseFile IDs to generate test cases from (deprecated) |
| knowledgeBaseFileIds | array\[string] | 否 | List of KnowledgeBaseFile IDs to generate test cases from |
| knowledgeBaseIds | array\[string] | 否 | List of KnowledgeBase IDs to generate test cases from all their files |
| datasetId | string (uuid) | 是 | |
| numTestCases | integer | 否 | |
**請求結構範例**
```typescript
{
"chatbotFileIds"?: [ // List of KnowledgeBaseFile IDs to generate test cases from (deprecated) (非必填)
string (uuid)
]
"knowledgeBaseFileIds"?: [ // List of KnowledgeBaseFile IDs to generate test cases from (非必填)
string (uuid)
]
"knowledgeBaseIds"?: [ // List of KnowledgeBase IDs to generate test cases from all their files (非必填)
string (uuid)
]
"datasetId": string (uuid)
"numTestCases"?: integer // 非必填
}
```
**請求範例值**
```json
{
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/test-case/generate-from-file/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
};
axios.post("https://api.maiagent.ai/api/v1/test-case/generate-from-file/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/generate-from-file/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"chatbotFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"knowledgeBaseIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"numTestCases": 123
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/test-case/generate-from-file/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'chatbotFileIds' => [
'550e8400-e29b-41d4-a716-446655440000'
],
'knowledgeBaseFileIds' => [
'550e8400-e29b-41d4-a716-446655440000'
],
'knowledgeBaseIds' => [
'550e8400-e29b-41d4-a716-446655440000'
],
'datasetId' => '550e8400-e29b-41d4-a716-446655440000',
'numTestCases' => 123
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 202**
**回應結構範例**
```typescript
{
"status": string (enum: accepted) // * `accepted` - 固定為 accepted，表示已受理並排入背景執行
"message": string // 受理說明
"jobId": string (uuid) // 生成任務 ID，可用 GET /api/v1/test-case/generation-jobs/{jobId}/ 查詢進度；同一測試集已有進行中的生成任務時，回傳的是該任務
"taskId": string // 背景任務 ID
}
```
**回應範例值**
```json
{
"status": "accepted",
"message": "回應字串",
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"taskId": "回應字串"
}
```
***
### 列出測試案例生成任務
GET `/api/v1/test-case/generation-jobs/`
{% hint style="info" %}
列出組織的單輪與多輪生成任務，新到舊排序，可用 `datasetId` 與 `status` 篩選。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------- | ----------------------------------------------------------------- |
| `datasetId` | ❌ | string | 只列出此資料集的生成任務 |
| `page` | ❌ | integer | 頁碼，從 1 開始；超過最後一頁回 404 |
| `pageSize` | ❌ | integer | 每頁筆數，預設 20、上限 100（超過以 100 計） |
| `status` | ❌ | string | 依狀態過濾：pending / running / completed / partial\_completed / failed |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/test-case/generation-jobs/?datasetId=example&page=1&pageSize=1&status=example" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/test-case/generation-jobs/?datasetId=example&page=1&pageSize=1&status=example", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/generation-jobs/?datasetId=example&page=1&pageSize=1&status=example"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/test-case/generation-jobs/?datasetId=example&page=1&pageSize=1&status=example", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"status"?: string (enum: pending, running, completed, partial_completed, failed) // * `pending` - Pending
* `running` - Generating
* `completed` - Completed
* `partial_completed` - Partially completed
* `failed` - Generation failed (非必填)
"jobType"?: // Single-turn Q&A test data or multi-turn conversation test data
* `single_turn` - Single turn
* `multi_turn` - Multi turn (非必填)
{
}
"requestedNumTestCases"?: integer // 非必填
"totalFiles"?: integer // 非必填
"processedFiles"?: integer // 非必填
"generatedCount"?: integer // 非必填
"progressPercentage": number (double)
"errorMessage"?: string // Error message recorded when the whole batch fails (非必填)
"fileResults"?: object // Result for each file, such as [{'file_id', 'filename', 'status', 'generated', 'error'}] (非必填)
"startedAt"?: string (timestamp) // 非必填
"completedAt"?: string (timestamp) // 非必填
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"status": "pending",
"jobType": {},
"requestedNumTestCases": 456,
"totalFiles": 456,
"processedFiles": 456,
"generatedCount": 456,
"progressPercentage": 456,
"errorMessage": "回應字串",
"fileResults": null,
"startedAt": "回應字串",
"completedAt": "回應字串",
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
]
}
```
***
### 查詢測試案例生成任務進度
GET `/api/v1/test-case/generation-jobs/{jobId}/`
{% hint style="info" %}
`status` 為 `pending`、`running`、`completed`、`partial_completed` 或 `failed`；`generatedCount` 是已生成的題數，`fileResults` 列出每個檔案的結果與失敗原因。單輪與多輪的生成任務都用這個端點查詢，以 `jobType` 區分。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ------- | -- | ------ | -------------------------------- |
| `jobId` | ✅ | string | 生成任務 ID，即「從知識庫檔案生成測試案例」回應的 jobId |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/test-case/generation-jobs/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/test-case/generation-jobs/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/generation-jobs/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/test-case/generation-jobs/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"status"?: string (enum: pending, running, completed, partial_completed, failed) // * `pending` - Pending
* `running` - Generating
* `completed` - Completed
* `partial_completed` - Partially completed
* `failed` - Generation failed (非必填)
"jobType"?: // Single-turn Q&A test data or multi-turn conversation test data
* `single_turn` - Single turn
* `multi_turn` - Multi turn (非必填)
{
}
"requestedNumTestCases"?: integer // 非必填
"totalFiles"?: integer // 非必填
"processedFiles"?: integer // 非必填
"generatedCount"?: integer // 非必填
"progressPercentage": number (double)
"errorMessage"?: string // Error message recorded when the whole batch fails (非必填)
"fileResults"?: object // Result for each file, such as [{'file_id', 'filename', 'status', 'generated', 'error'}] (非必填)
"startedAt"?: string (timestamp) // 非必填
"completedAt"?: string (timestamp) // 非必填
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"status": "pending",
"jobType": {},
"requestedNumTestCases": 456,
"totalFiles": 456,
"processedFiles": 456,
"generatedCount": 456,
"progressPercentage": 456,
"errorMessage": "回應字串",
"fileResults": null,
"startedAt": "回應字串",
"completedAt": "回應字串",
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 更新單輪測試案例
PUT `/api/v1/test-case/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ------- |
| `id` | ✅ | string | 測試案例 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ----------- | ---------------------------------------- | -- | --------------------------------------------------------------------------------------- |
| question | string | 是 | |
| groundTruth | string | 否 | |
| status | string (enum: active, inactive, pending) | 否 | `active`: Active ; `inactive`: Inactive ; `pending`: Pending Review; |
| flaky | boolean | 否 | Flaky test cases still run and keep their results, but are excluded from the pass rate. |
**請求結構範例**
```typescript
{
"question": string
"groundTruth"?: string // 非必填
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
}
```
**請求範例值**
```json
{
"question": "範例字串",
"groundTruth": "範例字串",
"status": "active",
"flaky": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "範例字串",
"groundTruth": "範例字串",
"status": "active",
"flaky": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"question": "範例字串",
"groundTruth": "範例字串",
"status": "active",
"flaky": true
};
axios.put("https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"question": "範例字串",
"groundTruth": "範例字串",
"status": "active",
"flaky": True
}
response = requests.put(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'question' => '範例字串',
'groundTruth' => '範例字串',
'status' => 'active',
'flaky' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"question": string
"groundTruth"?: string // 非必填
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
"creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (非必填)
"sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (非必填)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"question": "回應字串",
"groundTruth": "回應字串",
"status": "active",
"creationMethod": "manual",
"sourceFile": "回應字串",
"flaky": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 部分更新單輪測試案例
PATCH `/api/v1/test-case/{id}/`
{% hint style="info" %}
想暫時不測某一題時，把 `status` 改成 `inactive`，評估會略過它，過往的評估結果也會保留。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ------- |
| `id` | ✅ | string | 測試案例 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ----------- | ---------------------------------------- | -- | --------------------------------------------------------------------------------------- |
| question | string | 否 | |
| groundTruth | string | 否 | |
| status | string (enum: active, inactive, pending) | 否 | `active`: Active ; `inactive`: Inactive ; `pending`: Pending Review; |
| flaky | boolean | 否 | Flaky test cases still run and keep their results, but are excluded from the pass rate. |
**請求結構範例**
```typescript
{
"question"?: string // 非必填
"groundTruth"?: string // 非必填
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
}
```
**請求範例值**
```json
{
"question": "範例字串",
"groundTruth": "範例字串",
"status": "active",
"flaky": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"question": "範例字串",
"groundTruth": "範例字串",
"status": "active",
"flaky": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"question": "範例字串",
"groundTruth": "範例字串",
"status": "active",
"flaky": true
};
axios.patch("https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"question": "範例字串",
"groundTruth": "範例字串",
"status": "active",
"flaky": True
}
response = requests.patch(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'question' => '範例字串',
'groundTruth' => '範例字串',
'status' => 'active',
'flaky' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"question": string
"groundTruth"?: string // 非必填
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
"creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (非必填)
"sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (非必填)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"question": "回應字串",
"groundTruth": "回應字串",
"status": "active",
"creationMethod": "manual",
"sourceFile": "回應字串",
"flaky": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 刪除單輪測試案例
DELETE `/api/v1/test-case/{id}/`
{% hint style="info" %}
會一併刪除這筆測試案例在過往評估中的逐題結果；只想暫停測試請改用 `status`。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ------- |
| `id` | ✅ | string | 測試案例 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/test-case/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 批次刪除單輪測試案例
POST `/api/v1/test-case/bulk-delete/`
{% hint style="info" %}
以 `testCaseIds` 傳入要刪除的測試案例 ID 陣列，成功回 `204`。刪除的影響同 [刪除單輪測試案例](#test-case-destroy)。
{% endhint %}
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| --------------- | -------------- | -- | -------------- |
| test\_case\_ids | array\[string] | 是 | 要刪除的測試案例 ID 列表 |
**請求結構範例**
```typescript
{
"test_case_ids": [ // 要刪除的測試案例 ID 列表
string (uuid)
]
}
```
**請求範例值**
```json
{
"test_case_ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/test-case/bulk-delete/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"test_case_ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"test_case_ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
};
axios.post("https://api.maiagent.ai/api/v1/test-case/bulk-delete/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/test-case/bulk-delete/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"test_case_ids": [
"550e8400-e29b-41d4-a716-446655440000"
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/test-case/bulk-delete/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'test_case_ids' => [
'550e8400-e29b-41d4-a716-446655440000'
]
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 列出多輪測試案例
GET `/api/v1/multi-turn-test-case/`
{% hint style="info" %}
用 `datasetId` 篩選單一測試集。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ----------- | -- | ------- | ------------------------------------------------------------------------ |
| `dataset` | ❌ | string | 同 datasetId，只列出此資料集的多輪對話測試案例 |
| `datasetId` | ❌ | string | 只列出此資料集的多輪對話測試案例 |
| `ordering` | ❌ | string | 排序欄位：created\_at 或 updated\_at，前面加 - 為由新到舊（例：-updated\_at）；未指定時依建立時間由新到舊 |
| `page` | ❌ | integer | 頁碼，從 1 開始；超過最後一頁回 404 |
| `pageSize` | ❌ | integer | 每頁筆數，預設 20、上限 100（超過以 100 計） |
| `search` | ❌ | string | 關鍵字，比對情境（scenario）或預期結果（expected\_outcome）（部分符合、不分大小寫；以空白分隔多個關鍵字時須全部符合） |
| `status` | ❌ | string | 只列出此狀態的多輪對話測試案例。可用值： \`active\`: Active ; \`inactive\`: Inactive; |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/multi-turn-test-case/?dataset=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&search=example&status=active" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/multi-turn-test-case/?dataset=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&search=example&status=active", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/?dataset=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&search=example&status=active"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/multi-turn-test-case/?dataset=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&ordering=example&page=1&pageSize=1&search=example&status=active", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"scenario": string // Task scenario the simulated user should accomplish
"expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
"userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (非必填)
"status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (非必填)
"creationMethod":
{
}
"sourceFile": string // Name of the knowledge base file this multi-turn test case was generated from
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"scenario": "回應字串",
"expectedOutcome": "回應字串",
"userDescription": "回應字串",
"status": "active",
"creationMethod": {},
"sourceFile": "回應字串",
"flaky": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
]
}
```
***
### 建立多輪測試案例
POST `/api/v1/multi-turn-test-case/`
{% hint style="info" %}
`datasetId`、`scenario`（模擬使用者要完成的任務情境）、`expectedOutcome`（對話成功時應達成的結果，也是模擬對話的結束條件）必填；`userDescription` 選填，描述模擬使用者的語氣、背景與專業程度。
{% endhint %}
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| --------------- | ------------- | -- | -- |
| datasetId | string (uuid) | 是 | |
| scenario | string | 是 | |
| expectedOutcome | string | 是 | |
| userDescription | string | 否 | |
| status | object | 否 | |
| flaky | boolean | 否 | |
**請求結構範例**
```typescript
{
"datasetId": string (uuid)
"scenario": string
"expectedOutcome": string
"userDescription"?: string // 非必填
"status"?: // 非必填
{
}
"flaky"?: boolean // 非必填
}
```
**請求範例值**
```json
{
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"scenario": "範例字串",
"expectedOutcome": "範例字串",
"userDescription": "範例字串",
"status": {},
"flaky": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/multi-turn-test-case/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"scenario": "範例字串",
"expectedOutcome": "範例字串",
"userDescription": "範例字串",
"status": {},
"flaky": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"scenario": "範例字串",
"expectedOutcome": "範例字串",
"userDescription": "範例字串",
"status": {},
"flaky": true
};
axios.post("https://api.maiagent.ai/api/v1/multi-turn-test-case/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"scenario": "範例字串",
"expectedOutcome": "範例字串",
"userDescription": "範例字串",
"status": {},
"flaky": True
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/multi-turn-test-case/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'datasetId' => '550e8400-e29b-41d4-a716-446655440000',
'scenario' => '範例字串',
'expectedOutcome' => '範例字串',
'userDescription' => '範例字串',
'status' => new \stdClass(),
'flaky' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"scenario": string // Task scenario the simulated user should accomplish
"expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
"userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (非必填)
"status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (非必填)
"creationMethod":
{
}
"sourceFile": string // Name of the knowledge base file this multi-turn test case was generated from
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"scenario": "回應字串",
"expectedOutcome": "回應字串",
"userDescription": "回應字串",
"status": "active",
"creationMethod": {},
"sourceFile": "回應字串",
"flaky": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 從知識庫檔案生成多輪測試案例
POST `/api/v1/multi-turn-test-case/generate-from-file/`
{% hint style="info" %}
用 `knowledgeBaseFileIds` 指定來源檔案，`numTestCases` 預設 5、最多 20。生成在背景執行，回應 `202` 與 `jobId`，用 [查詢測試案例生成任務進度](#test-case-generation-jobs-retrieve) 追蹤。**Credit**：同單輪生成，依實際生成的題數扣 `agentops_test_gen`。
{% endhint %}
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| -------------------- | -------------- | -- | -------------------------------------------------------------------- |
| datasetId | string (uuid) | 是 | |
| knowledgeBaseFileIds | array\[string] | 是 | List of KnowledgeBaseFile IDs to generate multi-turn test cases from |
| numTestCases | integer | 否 | |
**請求結構範例**
```typescript
{
"datasetId": string (uuid)
"knowledgeBaseFileIds": [ // List of KnowledgeBaseFile IDs to generate multi-turn test cases from
string (uuid)
]
"numTestCases"?: integer // 非必填
}
```
**請求範例值**
```json
{
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"numTestCases": 123
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/multi-turn-test-case/generate-from-file/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"numTestCases": 123
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"numTestCases": 123
};
axios.post("https://api.maiagent.ai/api/v1/multi-turn-test-case/generate-from-file/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/generate-from-file/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"datasetId": "550e8400-e29b-41d4-a716-446655440000",
"knowledgeBaseFileIds": [
"550e8400-e29b-41d4-a716-446655440000"
],
"numTestCases": 123
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/multi-turn-test-case/generate-from-file/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'datasetId' => '550e8400-e29b-41d4-a716-446655440000',
'knowledgeBaseFileIds' => [
'550e8400-e29b-41d4-a716-446655440000'
],
'numTestCases' => 123
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 202**
**回應結構範例**
```typescript
{
"status": string (enum: accepted) // * `accepted` - 固定為 accepted，表示已受理並排入背景執行
"message": string // 受理說明
"jobId": string (uuid) // 生成任務 ID，可用 GET /api/v1/test-case/generation-jobs/{jobId}/ 查詢進度；同一測試集已有進行中的生成任務時，回傳的是該任務
"taskId": string // 背景任務 ID
}
```
**回應範例值**
```json
{
"status": "accepted",
"message": "回應字串",
"jobId": "550e8400-e29b-41d4-a716-446655440000",
"taskId": "回應字串"
}
```
***
### 取得特定多輪測試案例
GET `/api/v1/multi-turn-test-case/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ----------- |
| `id` | ✅ | string | 多輪對話測試案例 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"scenario": string // Task scenario the simulated user should accomplish
"expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
"userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (非必填)
"status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (非必填)
"creationMethod":
{
}
"sourceFile": string // Name of the knowledge base file this multi-turn test case was generated from
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"scenario": "回應字串",
"expectedOutcome": "回應字串",
"userDescription": "回應字串",
"status": "active",
"creationMethod": {},
"sourceFile": "回應字串",
"flaky": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 更新多輪測試案例
PUT `/api/v1/multi-turn-test-case/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ----------- |
| `id` | ✅ | string | 多輪對話測試案例 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| --------------- | ------------------------------- | -- | ------------------------------------------------------------------------------------------ |
| scenario | string | 是 | Task scenario the simulated user should accomplish |
| expectedOutcome | string | 是 | Outcome a successful conversation should reach, also used as the simulation stop condition |
| userDescription | string | 否 | Persona of the simulated user, such as tone, background and level of expertise |
| status | string (enum: active, inactive) | 否 | `active`: Active ; `inactive`: Inactive; |
| flaky | boolean | 否 | Flaky test cases still run and keep their results, but are excluded from the pass rate. |
**請求結構範例**
```typescript
{
"scenario": string // Task scenario the simulated user should accomplish
"expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
"userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (非必填)
"status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (非必填)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
}
```
**請求範例值**
```json
{
"scenario": "範例字串",
"expectedOutcome": "範例字串",
"userDescription": "範例字串",
"status": "active",
"flaky": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"scenario": "範例字串",
"expectedOutcome": "範例字串",
"userDescription": "範例字串",
"status": "active",
"flaky": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"scenario": "範例字串",
"expectedOutcome": "範例字串",
"userDescription": "範例字串",
"status": "active",
"flaky": true
};
axios.put("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"scenario": "範例字串",
"expectedOutcome": "範例字串",
"userDescription": "範例字串",
"status": "active",
"flaky": True
}
response = requests.put(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
put("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'scenario' => '範例字串',
'expectedOutcome' => '範例字串',
'userDescription' => '範例字串',
'status' => 'active',
'flaky' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"scenario": string // Task scenario the simulated user should accomplish
"expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
"userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (非必填)
"status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (非必填)
"creationMethod":
{
}
"sourceFile": string // Name of the knowledge base file this multi-turn test case was generated from
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"scenario": "回應字串",
"expectedOutcome": "回應字串",
"userDescription": "回應字串",
"status": "active",
"creationMethod": {},
"sourceFile": "回應字串",
"flaky": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 部分更新多輪測試案例
PATCH `/api/v1/multi-turn-test-case/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ----------- |
| `id` | ✅ | string | 多輪對話測試案例 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| --------------- | ------------------------------- | -- | ------------------------------------------------------------------------------------------ |
| scenario | string | 否 | Task scenario the simulated user should accomplish |
| expectedOutcome | string | 否 | Outcome a successful conversation should reach, also used as the simulation stop condition |
| userDescription | string | 否 | Persona of the simulated user, such as tone, background and level of expertise |
| status | string (enum: active, inactive) | 否 | `active`: Active ; `inactive`: Inactive; |
| flaky | boolean | 否 | Flaky test cases still run and keep their results, but are excluded from the pass rate. |
**請求結構範例**
```typescript
{
"scenario"?: string // Task scenario the simulated user should accomplish (非必填)
"expectedOutcome"?: string // Outcome a successful conversation should reach, also used as the simulation stop condition (非必填)
"userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (非必填)
"status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (非必填)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
}
```
**請求範例值**
```json
{
"scenario": "範例字串",
"expectedOutcome": "範例字串",
"userDescription": "範例字串",
"status": "active",
"flaky": true
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"scenario": "範例字串",
"expectedOutcome": "範例字串",
"userDescription": "範例字串",
"status": "active",
"flaky": true
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"scenario": "範例字串",
"expectedOutcome": "範例字串",
"userDescription": "範例字串",
"status": "active",
"flaky": true
};
axios.patch("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"scenario": "範例字串",
"expectedOutcome": "範例字串",
"userDescription": "範例字串",
"status": "active",
"flaky": True
}
response = requests.patch(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'scenario' => '範例字串',
'expectedOutcome' => '範例字串',
'userDescription' => '範例字串',
'status' => 'active',
'flaky' => true
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"scenario": string // Task scenario the simulated user should accomplish
"expectedOutcome": string // Outcome a successful conversation should reach, also used as the simulation stop condition
"userDescription"?: string // Persona of the simulated user, such as tone, background and level of expertise (非必填)
"status"?: string (enum: active, inactive) // * `active` - Active
* `inactive` - Inactive (非必填)
"creationMethod":
{
}
"sourceFile": string // Name of the knowledge base file this multi-turn test case was generated from
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"scenario": "回應字串",
"expectedOutcome": "回應字串",
"userDescription": "回應字串",
"status": "active",
"creationMethod": {},
"sourceFile": "回應字串",
"flaky": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
```
***
### 刪除多輪測試案例
DELETE `/api/v1/multi-turn-test-case/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ----------- |
| `id` | ✅ | string | 多輪對話測試案例 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/multi-turn-test-case/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
### 列出可用的評估模型
GET `/api/v1/evaluations/evaluation-llms/`
{% hint style="info" %}
`isDefault` 為 `true` 的模型，是執行評估時沒有指定 `evaluationLlmId` 所使用的預設評估模型。
{% endhint %}
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/evaluation-llms/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/evaluations/evaluation-llms/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/evaluation-llms/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/evaluations/evaluation-llms/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
[
{
"id": string (uuid)
"name": string
"value": string
"provider": string
"isDefault": boolean
}
]
```
**回應範例值**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"value": "回應字串",
"provider": "回應字串",
"isDefault": false
}
]
```
***
### 執行單輪評估
POST `/api/v1/evaluations/evaluate/`
{% hint style="info" %}
`datasetId` 與 `chatbotId` 必填；`evaluationLlmId` 省略時使用預設評估模型。`metricConfig` 以布林值開關內建指標，`customMetrics` 最多 10 個自訂指標。只評估狀態為 `active` 的測試案例。評估在背景執行，回應 `202` 與 `evaluationId`。**Credit**：送出前檢查組織 Credit，不足回 `402`；評估結束時依完成的測試案例數扣 `agentops_test_run` 與 `agentops_deepeval`，評估模型的呼叫另計。
{% endhint %}
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| --------------- | ------------------------------------- | -- | -- |
| datasetId | string (uuid) | 是 | |
| chatbotId | string (uuid) | 是 | |
| evaluationLlmId | string (uuid) | 否 | |
| name | string | 否 | |
| description | string | 否 | |
| metricConfig | object | 否 | |
| customMetrics | array\[DatasetEvaluationCustomMetric] | 否 | |
**請求結構範例**
```typescript
{
"datasetId": string (uuid)
"chatbotId": string (uuid)
"evaluationLlmId"?: string (uuid) // 非必填
"name"?: string // 非必填
"description"?: string // 非必填
"metricConfig"?: object // 非必填
"customMetrics"?: [ // 非必填
{
"name": string
"criteria"?: string // 非必填
"evaluationSteps"?: [ // 非必填
string
]
"threshold"?: number (double) // 非必填
}
]
}
```
**請求範例值**
```json
{
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"evaluation_llm_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Evaluation Name",
"description": "Evaluation Description",
"metric_config": {
"ground_truth": true,
"task_completion": false,
"tool_correctness": false,
"guardrail": true,
"summarize": false,
"hallucination": true
},
"custom_metrics": [
{
"name": "Support Tone",
"criteria": "The answer should be polite, empathetic, and professional in tone.",
"threshold": 0.6
}
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/evaluations/evaluate/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"evaluation_llm_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Evaluation Name",
"description": "Evaluation Description",
"metric_config": {
"ground_truth": true,
"task_completion": false,
"tool_correctness": false,
"guardrail": true,
"summarize": false,
"hallucination": true
},
"custom_metrics": [
{
"name": "Support Tone",
"criteria": "The answer should be polite, empathetic, and professional in tone.",
"threshold": 0.6
}
]
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"evaluation_llm_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Evaluation Name",
"description": "Evaluation Description",
"metric_config": {
"ground_truth": true,
"task_completion": false,
"tool_correctness": false,
"guardrail": true,
"summarize": false,
"hallucination": true
},
"custom_metrics": [
{
"name": "Support Tone",
"criteria": "The answer should be polite, empathetic, and professional in tone.",
"threshold": 0.6
}
]
};
axios.post("https://api.maiagent.ai/api/v1/evaluations/evaluate/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/evaluate/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"evaluation_llm_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Evaluation Name",
"description": "Evaluation Description",
"metric_config": {
"ground_truth": True,
"task_completion": False,
"tool_correctness": False,
"guardrail": True,
"summarize": False,
"hallucination": True
},
"custom_metrics": [
{
"name": "Support Tone",
"criteria": "The answer should be polite, empathetic, and professional in tone.",
"threshold": 0.6
}
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/evaluations/evaluate/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'dataset_id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
'chatbot_id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
'evaluation_llm_id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
'name' => 'Evaluation Name',
'description' => 'Evaluation Description',
'metric_config' => [
'ground_truth' => true,
'task_completion' => false,
'tool_correctness' => false,
'guardrail' => true,
'summarize' => false,
'hallucination' => true
],
'custom_metrics' => [
[
'name' => 'Support Tone',
'criteria' => 'The answer should be polite, empathetic, and professional in tone.',
'threshold' => 0.6
]
]
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 202**
**回應結構範例**
```typescript
{
"status": string (enum: accepted) // * `accepted` - 固定為 accepted，表示已受理並排入背景執行
"message": string // 受理說明
"evaluationId": string (uuid) // 評估 ID，可用 GET /api/v1/evaluations/{id}/ 輪詢 status 直到結束
}
```
**回應範例值**
```json
{
"status": "accepted",
"message": "回應字串",
"evaluationId": "550e8400-e29b-41d4-a716-446655440000"
}
```
***
### 執行多輪評估
POST `/api/v1/evaluations/multi-turn-evaluate/`
{% hint style="info" %}
以測試集內的多輪測試案例模擬使用者與 Agent 對話後評分。`maxTurns` 是模擬使用者最多發話的輪數（2～10，預設 6），`language` 是模擬使用者的語言（`Traditional Chinese`、`Simplified Chinese`、`English`、`Japanese`、`Korean`，預設 `Traditional Chinese`）。測試集沒有任何 `active` 的多輪測試案例時回 `400`。回應與 Credit 同 [執行單輪評估](#evaluations-evaluate-create)。
{% endhint %}
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ------------------------ | ----------------------------- | -- | -- |
| datasetId | string (uuid) | 是 | |
| chatbotId | string (uuid) | 是 | |
| evaluationLlmId | string (uuid) | 否 | |
| name | string | 否 | |
| description | string | 否 | |
| maxTurns | integer | 否 | |
| minTurns | integer | 否 | |
| turnFaithfulness | boolean | 否 | |
| turnRelevancy | boolean | 否 | |
| conversationCompleteness | boolean | 否 | |
| language | object | 否 | |
| customMetrics | array\[MultiTurnCustomMetric] | 否 | |
**請求結構範例**
```typescript
{
"datasetId": string (uuid)
"chatbotId": string (uuid)
"evaluationLlmId"?: string (uuid) // 非必填
"name"?: string // 非必填
"description"?: string // 非必填
"maxTurns"?: integer // 非必填
"minTurns"?: integer // 非必填
"turnFaithfulness"?: boolean // 非必填
"turnRelevancy"?: boolean // 非必填
"conversationCompleteness"?: boolean // 非必填
"language"?: // 非必填
{
}
"customMetrics"?: [ // 非必填
{
"name": string
"criteria"?: string // 非必填
"evaluationSteps"?: [ // 非必填
string
]
"threshold"?: number (double) // 非必填
}
]
}
```
**請求範例值**
```json
{
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"max_turns": 6,
"min_turns": 2,
"custom_metrics": [
{
"name": "Identity Check",
"criteria": "The assistant confirms the user identity before sharing account details.",
"threshold": 0.6
}
]
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/evaluations/multi-turn-evaluate/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"max_turns": 6,
"min_turns": 2,
"custom_metrics": [
{
"name": "Identity Check",
"criteria": "The assistant confirms the user identity before sharing account details.",
"threshold": 0.6
}
]
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"max_turns": 6,
"min_turns": 2,
"custom_metrics": [
{
"name": "Identity Check",
"criteria": "The assistant confirms the user identity before sharing account details.",
"threshold": 0.6
}
]
};
axios.post("https://api.maiagent.ai/api/v1/evaluations/multi-turn-evaluate/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/multi-turn-evaluate/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"dataset_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"chatbot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"max_turns": 6,
"min_turns": 2,
"custom_metrics": [
{
"name": "Identity Check",
"criteria": "The assistant confirms the user identity before sharing account details.",
"threshold": 0.6
}
]
}
response = requests.post(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/evaluations/multi-turn-evaluate/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'dataset_id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
'chatbot_id' => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
'max_turns' => 6,
'min_turns' => 2,
'custom_metrics' => [
[
'name' => 'Identity Check',
'criteria' => 'The assistant confirms the user identity before sharing account details.',
'threshold' => 0.6
]
]
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 202**
**回應結構範例**
```typescript
{
"status": string (enum: accepted) // * `accepted` - 固定為 accepted，表示已受理並排入背景執行
"message": string // 受理說明
"evaluationId": string (uuid) // 評估 ID，可用 GET /api/v1/evaluations/{id}/ 輪詢 status 直到結束
}
```
**回應範例值**
```json
{
"status": "accepted",
"message": "回應字串",
"evaluationId": "550e8400-e29b-41d4-a716-446655440000"
}
```
***
### 列出評估
GET `/api/v1/evaluations/`
{% hint style="info" %}
可用 `datasetId`、`chatbotId`、`status` 篩選。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------------- | -- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chatbotId` | ❌ | string | 只列出評估此 AI 助理的評估 |
| `datasetId` | ❌ | string | 只列出使用此資料集的評估 |
| `excludeBuiltIn` | ❌ | string | true 時排除官方內建 Agent（由 Agent 市集租用而建立的鎖定實例）的資料，只留組織自建助理；「複製為自建」產生的副本屬自建。不帶或 false 時與未加此條件相同。 |
| `ordering` | ❌ | string | 排序欄位：created\_at 或 updated\_at，前面加 - 為由新到舊（例：-updated\_at）；未指定時依建立時間由新到舊 |
| `page` | ❌ | integer | 頁碼，從 1 開始；超過最後一頁回 404 |
| `pageSize` | ❌ | integer | 每頁筆數，預設 20、上限 100（超過以 100 計） |
| `query` | ❌ | string | 關鍵字，比對評估名稱、描述或 ID（部分符合） |
| `search` | ❌ | string | 關鍵字，比對評估名稱、資料集名稱或 AI 助理名稱（部分符合、不分大小寫；以空白分隔多個關鍵字時須全部符合） |
| `status` | ❌ | string | 只列出此狀態的評估。可用值： \`pending\`: Pending evaluation ; \`running\`: Evaluating ; \`stopping\`: Stopping ; \`completed\`: Completed ; \`partial\_completed\`: Partially completed ; \`failed\`: Evaluation failed; |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&excludeBuiltIn=example&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/evaluations/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&excludeBuiltIn=example&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&excludeBuiltIn=example&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/evaluations/?chatbotId=550e8400-e29b-41d4-a716-446655440000&datasetId=550e8400-e29b-41d4-a716-446655440000&excludeBuiltIn=example&ordering=example&page=1&pageSize=1&query=example&search=example&status=completed", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"name": string
"description": string
"chatbot":
{
"id": string (uuid)
"name": string
}
"dataset":
{
"id": string (uuid)
"name": string
}
"organization":
{
"id": string (uuid)
"name": string
}
"evaluationLlm":
{
"id": string (uuid)
"name": string
}
"status":
{
}
"startedAt": string (timestamp)
"completedAt": string (timestamp)
"totalTestCases": integer
"completedTestCases": integer
"passedTestCases": integer // Number of test cases that passed
"metricScores": object // Detailed score per evaluation metric, such as ground_truth, task_completion and tool_correctness
"evaluationConfig": object
"progressPercentage": number (double)
"overallScore": number (double)
"passRate": number (double)
"averageExecutionTimeMs": integer
"totalExecutionTimeMs": integer
"chatbotConfig": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"insights":
{
"summary": string
"metricStats"?: object // 非必填
"recommendations"?: object // 非必填
}
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"evaluationLlm": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"status": {},
"startedAt": "回應字串",
"completedAt": "回應字串",
"totalTestCases": 456,
"completedTestCases": 456,
"passedTestCases": 456,
"metricScores": null,
"evaluationConfig": null,
"progressPercentage": 456,
"overallScore": 456,
"passRate": 456,
"averageExecutionTimeMs": 456,
"totalExecutionTimeMs": 456,
"chatbotConfig": "回應字串",
"createdAt": "回應字串",
"updatedAt": "回應字串",
"insights": {
"summary": "回應字串",
"metricStats": null,
"recommendations": null
}
}
]
}
```
***
### 取得評估結果
GET `/api/v1/evaluations/{id}/`
{% hint style="info" %}
`status` 為 `pending`、`running`、`stopping`、`completed`、`partial_completed` 或 `failed`；執行中看 `progressPercentage`，結束後看 `passRate`、`overallScore` 與各指標的 `metricScores`。沒有任何測試案例完成時結束為 `failed`。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ----- |
| `id` | ✅ | string | 評估 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"description": string
"chatbot":
{
"id": string (uuid)
"name": string
}
"dataset":
{
"id": string (uuid)
"name": string
}
"organization":
{
"id": string (uuid)
"name": string
}
"evaluationLlm":
{
"id": string (uuid)
"name": string
}
"status":
{
}
"startedAt": string (timestamp)
"completedAt": string (timestamp)
"totalTestCases": integer
"completedTestCases": integer
"passedTestCases": integer // Number of test cases that passed
"metricScores": object // Detailed score per evaluation metric, such as ground_truth, task_completion and tool_correctness
"evaluationConfig": object
"progressPercentage": number (double)
"overallScore": number (double)
"passRate": number (double)
"averageExecutionTimeMs": integer
"totalExecutionTimeMs": integer
"chatbotConfig": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"insights":
{
"summary": string
"metricStats"?: object // 非必填
"recommendations"?: object // 非必填
}
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"evaluationLlm": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"status": {},
"startedAt": "回應字串",
"completedAt": "回應字串",
"totalTestCases": 456,
"completedTestCases": 456,
"passedTestCases": 456,
"metricScores": null,
"evaluationConfig": null,
"progressPercentage": 456,
"overallScore": 456,
"passRate": 456,
"averageExecutionTimeMs": 456,
"totalExecutionTimeMs": 456,
"chatbotConfig": "回應字串",
"createdAt": "回應字串",
"updatedAt": "回應字串",
"insights": {
"summary": "回應字串",
"metricStats": null,
"recommendations": null
}
}
```
***
### 取得單輪評估的逐題結果
GET `/api/v1/evaluations/{id}/details/`
{% hint style="info" %}
只適用單輪評估，多輪評估回 `400`。回應是所有測試案例結果的陣列，不分頁。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ----- |
| `id` | ✅ | string | 評估 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/details/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/details/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/details/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/details/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
[
{
"id": string (uuid)
"datasetEvaluation":
{
"id": string (uuid)
"name": string
}
"testCase":
{
"id": string (uuid)
"dataset":
{
"id": string (uuid)
"name": string
}
"question": string
"groundTruth"?: string // 非必填
"status"?: string (enum: active, inactive, pending) // * `active` - Active
* `inactive` - Inactive
* `pending` - Pending Review (非必填)
"creationMethod"?: string (enum: manual, file, generate) // * `manual` - Manual
* `file` - File import
* `generate` - Generated (非必填)
"sourceFile"?: string // Name of the CSV, Excel or knowledge base file this test case came from (非必填)
"flaky"?: boolean // Flaky test cases still run and keep their results, but are excluded from the pass rate. (非必填)
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
"status":
{
}
"chatbotResponse": string
"context": [ // Enrich each context item with is_deleted status for referenced knowledge base files.
object
]
"metricScores": object
"executionTimeMs": integer
"executionTimeSeconds": number (double)
"passed": boolean
"errorMessage": string // Error message recorded when the evaluation fails
"startedAt": string (timestamp)
"completedAt": string (timestamp)
"retryCount": integer // Number of times this test case has been retried
"lastAttemptAt": string (timestamp) // Time of the last evaluation attempt
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
}
]
```
**回應範例值**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"datasetEvaluation": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"testCase": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"question": "回應字串",
"groundTruth": "回應字串",
"status": "active",
"creationMethod": "manual",
"sourceFile": "回應字串",
"flaky": false,
"createdAt": "回應字串",
"updatedAt": "回應字串"
},
"status": {},
"chatbotResponse": "回應字串",
"context": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應範例名稱",
"description": "回應範例描述"
}
],
"metricScores": null,
"executionTimeMs": 456,
"executionTimeSeconds": 456,
"passed": false,
"errorMessage": "回應字串",
"startedAt": "回應字串",
"completedAt": "回應字串",
"retryCount": 456,
"lastAttemptAt": "回應字串",
"createdAt": "回應字串",
"updatedAt": "回應字串"
}
]
```
***
### 取得多輪評估的逐對話結果
GET `/api/v1/evaluations/{id}/multi-turn-results/`
{% hint style="info" %}
只適用多輪評估，單輪評估回 `400`。回應分頁。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---------- | -- | ------- | ---------------------------- |
| `id` | ✅ | string | 評估 ID |
| `page` | ❌ | integer | 頁碼，從 1 開始；超過最後一頁回 404 |
| `pageSize` | ❌ | integer | 每頁筆數，預設 20、上限 100（超過以 100 計） |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/multi-turn-results/?page=1&pageSize=1" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/multi-turn-results/?page=1&pageSize=1", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/multi-turn-results/?page=1&pageSize=1"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/multi-turn-results/?page=1&pageSize=1", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"count": integer
"next"?: string (uri) // 非必填
"previous"?: string (uri) // 非必填
"results": [
{
"id": string (uuid)
"multiTurnTestCase": string (uuid)
"scenario": string
"expectedOutcome": string
"flaky": boolean
"status":
{
}
"turns": object // The whole simulated conversation; each turn is {role, content, retrieval_context}
"metricScores": object
"passed": boolean
"errorMessage": string
"startedAt": string (timestamp)
"completedAt": string (timestamp)
"createdAt": string (timestamp)
}
]
}
```
**回應範例值**
```json
{
"count": 123,
"next": "http://api.example.org/accounts/?page=4",
"previous": "http://api.example.org/accounts/?page=2",
"results": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"multiTurnTestCase": "550e8400-e29b-41d4-a716-446655440000",
"scenario": "回應字串",
"expectedOutcome": "回應字串",
"flaky": false,
"status": {},
"turns": null,
"metricScores": null,
"passed": false,
"errorMessage": "回應字串",
"startedAt": "回應字串",
"completedAt": "回應字串",
"createdAt": "回應字串"
}
]
}
```
***
### 取消執行中的評估
POST `/api/v1/evaluations/{id}/cancel/`
{% hint style="info" %}
只能取消 `status` 為 `running` 的評估，否則回 `400`。取消後 `status` 先變成 `stopping`，停止後結束為 `partial_completed`，保留已算好的分數，已完成的測試案例照常扣 Credit；之後可以用 [繼續未完成的評估](#evaluations-resume-create) 補跑。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ----- |
| `id` | ✅ | string | 評估 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/cancel/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/cancel/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/cancel/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.post(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/cancel/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"description": string
"chatbot":
{
"id": string (uuid)
"name": string
}
"dataset":
{
"id": string (uuid)
"name": string
}
"organization":
{
"id": string (uuid)
"name": string
}
"evaluationLlm":
{
"id": string (uuid)
"name": string
}
"status":
{
}
"startedAt": string (timestamp)
"completedAt": string (timestamp)
"totalTestCases": integer
"completedTestCases": integer
"passedTestCases": integer // Number of test cases that passed
"metricScores": object // Detailed score per evaluation metric, such as ground_truth, task_completion and tool_correctness
"evaluationConfig": object
"progressPercentage": number (double)
"overallScore": number (double)
"passRate": number (double)
"averageExecutionTimeMs": integer
"totalExecutionTimeMs": integer
"chatbotConfig": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"insights":
{
"summary": string
"metricStats"?: object // 非必填
"recommendations"?: object // 非必填
}
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"evaluationLlm": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"status": {},
"startedAt": "回應字串",
"completedAt": "回應字串",
"totalTestCases": 456,
"completedTestCases": 456,
"passedTestCases": 456,
"metricScores": null,
"evaluationConfig": null,
"progressPercentage": 456,
"overallScore": 456,
"passRate": 456,
"averageExecutionTimeMs": 456,
"totalExecutionTimeMs": 456,
"chatbotConfig": "回應字串",
"createdAt": "回應字串",
"updatedAt": "回應字串",
"insights": {
"summary": "回應字串",
"metricStats": null,
"recommendations": null
}
}
```
***
### 繼續未完成的評估
POST `/api/v1/evaluations/{id}/resume/`
{% hint style="info" %}
只能繼續 `status` 為 `partial_completed` 的評估，否則回 `400`。重跑失敗與尚未執行的測試案例並保留已完成的結果，回應 `202`；只對先前未計費的完成案例扣 Credit。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ----- |
| `id` | ✅ | string | 評估 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/resume/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/resume/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/resume/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.post(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/resume/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 202**
**回應結構範例**
```typescript
{
"status": string (enum: accepted) // * `accepted` - 固定為 accepted，表示已受理並排入背景執行
"message": string // 受理說明
"taskId": string // 背景任務 ID
}
```
**回應範例值**
```json
{
"status": "accepted",
"message": "回應字串",
"taskId": "回應字串"
}
```
***
### 匯出評估報表
POST `/api/v1/evaluations/{id}/export/`
{% hint style="info" %}
只能匯出 `status` 為 `completed` 的單輪評估；多輪評估目前不支援匯出，回 `400`。報表在背景產生 Excel 檔，回應 `201` 與匯出紀錄，再用 [查詢最新匯出狀態](#evaluations-export-status-retrieve) 取得下載網址。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ----- |
| `id` | ✅ | string | 評估 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.post(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
post("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 201**
**回應結構範例**
```typescript
{
"id": string (uuid)
"userEmail": string (email)
"datasetEvaluationId": string (uuid)
"datasetEvaluationName": string
"status":
{
}
"statusDisplay": string
"fileUrl": string // 返回檔案 URL
"fileSize": integer // File size in bytes
"errorMessage": string
"processingDurationSeconds": number (double) // 計算處理時長（秒）
"createdAt": string (timestamp)
"startedAt": string (timestamp)
"completedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"userEmail": "response@example.com",
"datasetEvaluationId": "550e8400-e29b-41d4-a716-446655440000",
"datasetEvaluationName": "回應字串",
"status": {},
"statusDisplay": "回應字串",
"fileUrl": "回應字串",
"fileSize": 456,
"errorMessage": "回應字串",
"processingDurationSeconds": 456,
"createdAt": "回應字串",
"startedAt": "回應字串",
"completedAt": "回應字串"
}
```
***
### 查詢最新匯出狀態
GET `/api/v1/evaluations/{id}/export-status/`
{% hint style="info" %}
回傳這筆評估最近一次的匯出紀錄：`status` 為 `pending`、`processing`、`completed` 或 `failed`，`completed` 時從 `fileUrl` 下載。這筆評估沒有匯出紀錄時回 `404`。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ----- |
| `id` | ✅ | string | 評估 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export-status/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export-status/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export-status/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/export-status/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"userEmail": string (email)
"datasetEvaluationId": string (uuid)
"datasetEvaluationName": string
"status":
{
}
"statusDisplay": string
"fileUrl": string // 返回檔案 URL
"fileSize": integer // File size in bytes
"errorMessage": string
"processingDurationSeconds": number (double) // 計算處理時長（秒）
"createdAt": string (timestamp)
"startedAt": string (timestamp)
"completedAt": string (timestamp)
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"userEmail": "response@example.com",
"datasetEvaluationId": "550e8400-e29b-41d4-a716-446655440000",
"datasetEvaluationName": "回應字串",
"status": {},
"statusDisplay": "回應字串",
"fileUrl": "回應字串",
"fileSize": 456,
"errorMessage": "回應字串",
"processingDurationSeconds": 456,
"createdAt": "回應字串",
"startedAt": "回應字串",
"completedAt": "回應字串"
}
```
***
### 列出匯出紀錄
GET `/api/v1/evaluations/{id}/exports/`
{% hint style="info" %}
回應是這筆評估所有匯出紀錄的陣列，新到舊排序，不分頁。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ----- |
| `id` | ✅ | string | 評估 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/exports/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
axios.get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/exports/", config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/exports/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.get(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
get("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/exports/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
[
{
"id": string (uuid)
"userEmail": string (email)
"datasetEvaluationId": string (uuid)
"datasetEvaluationName": string
"status":
{
}
"statusDisplay": string
"fileUrl": string // 返回檔案 URL
"fileSize": integer // File size in bytes
"processingDurationSeconds": number (double) // 計算處理時長（秒）
"createdAt": string (timestamp)
"startedAt": string (timestamp)
"completedAt": string (timestamp)
}
]
```
**回應範例值**
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"userEmail": "response@example.com",
"datasetEvaluationId": "550e8400-e29b-41d4-a716-446655440000",
"datasetEvaluationName": "回應字串",
"status": {},
"statusDisplay": "回應字串",
"fileUrl": "回應字串",
"fileSize": 456,
"processingDurationSeconds": 456,
"createdAt": "回應字串",
"startedAt": "回應字串",
"completedAt": "回應字串"
}
]
```
***
### 編輯評估名稱與描述
PATCH `/api/v1/evaluations/{id}/`
{% hint style="info" %}
只接受 `name` 與 `description`，其他欄位會被忽略；任何狀態都可以編輯。
{% endhint %}
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ----- |
| `id` | ✅ | string | 評估 ID |
#### 請求內容
**請求參數**
| 欄位 | 類型 | 必填 | 說明 |
| ----------- | ------ | -- | -- |
| name | string | 否 | |
| description | string | 否 | |
**請求結構範例**
```typescript
{
"name"?: string // 非必填
"description"?: string // 非必填
}
```
**請求範例值**
```json
{
"name": "範例名稱",
"description": "範例字串"
}
```
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "範例名稱",
"description": "範例字串"
}'
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY',
'Content-Type': 'application/json'
}
};
// 請求內容 (payload)
const data = {
"name": "範例名稱",
"description": "範例字串"
};
axios.patch("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY",
"Content-Type": "application/json"
}
# 請求內容 (payload)
data = {
"name": "範例名稱",
"description": "範例字串"
}
response = requests.patch(url, json=data, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
patch("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY',
'Content-Type' => 'application/json'
],
'json' => [
'name' => '範例名稱',
'description' => '範例字串'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
**狀態碼: 200**
**回應結構範例**
```typescript
{
"id": string (uuid)
"name": string
"description": string
"chatbot":
{
"id": string (uuid)
"name": string
}
"dataset":
{
"id": string (uuid)
"name": string
}
"organization":
{
"id": string (uuid)
"name": string
}
"evaluationLlm":
{
"id": string (uuid)
"name": string
}
"status":
{
}
"startedAt": string (timestamp)
"completedAt": string (timestamp)
"totalTestCases": integer
"completedTestCases": integer
"passedTestCases": integer // Number of test cases that passed
"metricScores": object // Detailed score per evaluation metric, such as ground_truth, task_completion and tool_correctness
"evaluationConfig": object
"progressPercentage": number (double)
"overallScore": number (double)
"passRate": number (double)
"averageExecutionTimeMs": integer
"totalExecutionTimeMs": integer
"chatbotConfig": string
"createdAt": string (timestamp)
"updatedAt": string (timestamp)
"insights":
{
"summary": string
"metricStats"?: object // 非必填
"recommendations"?: object // 非必填
}
}
```
**回應範例值**
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串",
"description": "回應字串",
"chatbot": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"dataset": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"organization": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"evaluationLlm": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "回應字串"
},
"status": {},
"startedAt": "回應字串",
"completedAt": "回應字串",
"totalTestCases": 456,
"completedTestCases": 456,
"passedTestCases": 456,
"metricScores": null,
"evaluationConfig": null,
"progressPercentage": 456,
"overallScore": 456,
"passRate": 456,
"averageExecutionTimeMs": 456,
"totalExecutionTimeMs": 456,
"chatbotConfig": "回應字串",
"createdAt": "回應字串",
"updatedAt": "回應字串",
"insights": {
"summary": "回應字串",
"metricStats": null,
"recommendations": null
}
}
```
***
### 刪除評估
DELETE `/api/v1/evaluations/{id}/`
#### 參數
| 參數名稱 | 必填 | 類型 | 說明 |
| ---- | -- | ------ | ----- |
| `id` | ✅ | string | 評估 ID |
#### 程式碼範例
{% tabs %}
{% tab title="Shell/Bash" %}
```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/" \
-H "Authorization: Api-Key YOUR_API_KEY"
# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```
{% endtab %}
{% tab title="JavaScript" %}
```javascript
const axios = require('axios');
// 設定請求標頭
const config = {
headers: {
'Authorization': 'Api-Key YOUR_API_KEY'
}
};
// 請求內容 (payload)
const data = null;
axios.delete("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/", data, config)
.then(response => {
console.log('成功取得回應:');
console.log(response.data);
})
.catch(error => {
console.error('請求發生錯誤:');
console.error(error.response?.data || error.message);
});
```
{% endtab %}
{% tab title="Python" %}
```python
import requests
url = "https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/"
headers = {
"Authorization": "Api-Key YOUR_API_KEY"
}
response = requests.delete(url, headers=headers)
try:
print("成功取得回應:")
print(response.json())
except Exception as e:
print("請求發生錯誤:", e)
```
{% endtab %}
{% tab title="PHP" %}
```php
delete("https://api.maiagent.ai/api/v1/evaluations/550e8400-e29b-41d4-a716-446655440000/", [
'headers' => [
'Authorization' => 'Api-Key YOUR_API_KEY'
]
]);
$data = json_decode($response->getBody(), true);
echo "成功取得回應:\n";
print_r($data);
} catch (Exception $e) {
echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```
{% endtab %}
{% endtabs %}
#### 回應內容
| 狀態碼 | 說明 |
| --- | ---------------- |
| 204 | No response body |
***
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.maiagent.ai/api/api-reference/ping-gu-he-ce-shi-ji.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.