# 提示詞手動優化

此 API 用於根據使用者提供的優化意圖，產生一個針對指定 Prompt 的自訂優化版本。  
透過提供：

- `current_issue`：目前這個 Prompt 在使用上遇到的問題（如太冗長、不夠明確、回答風格錯誤等）

- `desired_behavior`：期望模型在優化後的輸出行為（如更精簡、更正式、更適合摘要等）

系統會在保留原始 Prompt 語言與主結構的前提下，依這些指示補充限制與指令，並將結果**儲存為一筆新的 Prompt**；原始 Prompt 不會被修改。  
所有參數皆以 query string 傳遞，含中文或空白時請先做 URL encode（以下範例使用 `curl -G --data-urlencode`）。

```bash
curl -X 'POST' -G \
  'http://127.0.0.1:8000/v1/prompts/{prompt_id}/optimize/instruct' \
  --data-urlencode 'current_issue=回答太冗長' \
  --data-urlencode 'desired_behavior=以一句話回答' \
  --data-urlencode 'model={model}' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $PRIVAI_API_KEY"
```

#### Request Headers

| Key | Value |
| --- | --- |
| Request Method | POST |
| accept | application/json |
| Authorization | `Bearer $PRIVAI_API_KEY` |

#### Path Parameters

| Field | Type | Note | Required |
| --- | --- | --- | --- |
| prompt_id | string (uuid) | 要優化的原始提示詞唯一鍵 | true |

#### Query Parameters

| Field | Type | Note | Required |
| --- | --- | --- | --- |
| current_issue | string | 目前這個 Prompt 遇到的問題 | true |
| desired_behavior | string | 期望模型優化後的輸出行為 | true |
| model | string | 用來優化 Prompt 的模型名稱，可由「取得所有模型」API 查詢；省略則使用系統預設模型 | false |

#### Response Headers

| Key | Value |
| --- | --- |
| Status Code | 200 |

#### Response Body

```json
{
  "id": "6afecc03-ef73-4aa9-8ea6-88098047f3a2",
  "value": "Antibiotics are a type of medication used to treat bacterial infections. ... Explain the above in one sentence. Answer with a single concise sentence only:",
  "name": "Derived from Antibiotics Explanation",
  "metadata": {
    "tag": [
      "medication",
      "antibiotics"
    ],
    "derived_from": "dae76e24-ca4b-414f-92be-21abe36a70f7"
  },
  "created_at": "2025-06-09T07:33:47.632198Z"
}
```

**Field Explanation**  
回傳新建立的 Prompt，欄位同「[提示詞物件](https://privstation-docs.apmic.ai/latest/privai-400/提示詞物件.md)」章節內容。新 Prompt 的欄位規則如下：

| Field | Detail |
| --- | --- |
| id | 系統自動產生的新 UUID（與原始 Prompt 不同） |
| value | 模型依 `current_issue` 與 `desired_behavior` 調整後的 Prompt 內容 |
| name | `Derived from ` 加上原始 Prompt 的 `name`，例如 `Derived from Antibiotics Explanation` |
| metadata | 複製原始 Prompt 的 `metadata`，並加入 `derived_from` 欄位 |

在優化提示詞時，系統會自動於新產生的 Prompt 的 `metadata` 中加入一筆 `derived_from` 欄位，記錄來源的 `prompt_id`，方便後續追蹤來源關係與管理版本差異。

#### 可能的錯誤

| Error Code | HTTP Status | 情境 |
| --- | --- | --- |
| `AUTH_001`、`AUTH_002`、`AUTH_003` | 401 / 403 | 缺少 Authorization header、API Key 無效或已過期，見 「錯誤代碼說明-身份驗證類」 |
| `PROMPT_001` | 404 | 原始 Prompt 不存在，或不屬於目前的 API Key，見 「錯誤代碼說明-提示詞管理類」 |

缺少 `current_issue` 或 `desired_behavior` 時，會回傳 422 參數驗證錯誤。若指定的 `model` 無法使用或模型服務呼叫失敗，會回傳非錯誤代碼格式的回應。兩者格式見「例外狀況處理」章節。
