提示詞手動優化
此 API 用於根據使用者提供的優化意圖,產生一個針對指定 Prompt 的自訂優化版本。
透過提供:
-
current_issue:目前這個 Prompt 在使用上遇到的問題(如太冗長、不夠明確、回答風格錯誤等) -
desired_behavior:期望模型在優化後的輸出行為(如更精簡、更正式、更適合摘要等)
系統會在保留原始 Prompt 語言與主結構的前提下,依這些指示補充限制與指令,並將結果儲存為一筆新的 Prompt;原始 Prompt 不會被修改。
所有參數皆以 query string 傳遞,含中文或空白時請先做 URL encode(以下範例使用 curl -G --data-urlencode)。
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
{
"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,欄位同「提示詞物件」章節內容。新 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 無法使用或模型服務呼叫失敗,會回傳非錯誤代碼格式的回應。兩者格式見「例外狀況處理」章節。