如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

決策

將文字和圖片轉換為應用程式可直接使用的決策,速度是 Responses API 的 10 倍。

Decisions API 現已正式推出。請參閱公開測試以來的新增功能。

Decisions API 可評估文字、圖片和 JSON,並傳回具有明確型別的答案,速度約為 Responses API 的 10 倍。你可以取得條件成立的機率、從固定選項中選出的值,或依評分規準算出的分數。應用程式可根據這些答案為內容分類、分派請求,以及安排工作的優先順序。

撰寫程式碼前,可以先在 Playground 試用 Decisions API,測試不同的問題和輸入。

將請求傳送至 POST /v1/decisions,並使用目前唯一支援的模型 gpt-6-luna。

新增功能

自公開測試開始以來,Decisions API 新增了以下功能:

決策的運作方式

每個請求包含三個部分:

欄位 用途
model 用來評估請求的模型。目前僅支援 gpt-6-luna。
input 各問題共用的佐證資料,可以是文字字串,也可以是依序列出訊息、工具呼叫和工具輸出的陣列。
questions 要評估的問題,包括各問題的類型、指示,以及允許的選項或評分等級。

回應包含一個 answers 陣列。為每個問題指定唯一的 name,API 會在回應中傳回相同的名稱,方便你辨識對應的答案。

選擇問題類型

類型 用途 主要結果
predicate 檢查條件是否成立,例如是否有可見損傷,或某段文字是否相關。 probability:條件成立的估計機率,介於 0 到 1 之間。
choice 選擇一個選項,例如部門或內容類別。 choice:你提供的其中一個值。
score 依照有順序的等級評估輸入,例如問題的嚴重程度。 score:以各等級的機率為權重,計算等級索引的加權平均值。

choice 和 score 都會傳回各個離散選項的機率。對於沒有先後順序的類別(例如部門),請使用 choice。對於有順序的等級(例如嚴重程度),請使用 score。它會依機率對各等級的數值索引取加權平均,因此分數可能落在兩個等級之間。

如果應用程式需要上述任一類型的答案,請使用 Decisions。如果需要產生符合自訂 JSON 結構描述的物件,例如包含擷取欄位或文字說明的物件,請搭配 Responses API 使用結構化輸出。如果需要模型提出工具呼叫請求並指定引數,請使用函式呼叫。

評估對話

在 input 中傳入對話記錄,讓模型根據上下文評估請求。請依序列出訊息,以及任何函式或自訂工具的呼叫與輸出。使用 call_id 將每個工具輸出與對應的呼叫配對。

支援的內容取決於訊息角色或項目類型:

輸入項目 支援的內容
使用者訊息 文字、圖片和 JSON
開發人員或系統訊息 僅限輸入文字。系統訊息會視為開發人員訊息。
助理訊息 輸出文字或拒絕回覆
函式或自訂工具的輸出 與對應工具呼叫相關聯的文字和圖片

工具呼叫及其輸出可作為回答問題的依據。Decisions 會傳回具有明確型別的答案,再由應用程式執行答案所指定的動作。目前不支援檔案、音訊和項目參照。如需查看可接受的輸入欄位,請參閱建立決策的 API 參考文件。

評估 JSON 資料

使用 input_json 內容區塊即可直接傳入結構化佐證資料,無須先轉換成字串。將 JSON 物件或陣列放入 data,與其他文字或圖片區塊一起放在使用者訊息中。在訊息內容中,input_json 僅適用於 user 角色。

例如,將下列 JSON 請求主體傳送至 POST /v1/decisions,即可對照訂單記錄評估客服工單:

{
  "model": "gpt-6-luna",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "Evaluate the ticket using the order evidence."
        },
        {
          "type": "input_json",
          "data": {
            "ticket": { "body": "Please refund the duplicate charge." },
            "order": { "charges": [49, 49] }
          }
        }
      ]
    }
  ],
  "questions": [
    {
      "type": "predicate",
      "name": "duplicate_charge",
      "instructions": "Does the ticket describe a duplicate charge supported by the order?"
    }
  ]
}

role 或 image_url 等 JSON 鍵出現在 data 中時,都只是一般資料,不會建立訊息或擷取圖片。答案仍採用所選的問題類型,JSON 輸入不會改變回應格式。

檢查圖片中是否有可見損傷

使用 predicate 問題檢查產品照片中是否有可見損傷。這個請求同時提供圖片和指示,要求模型查看是否有裂痕、破口或凹痕。

檢查圖片中是否有可見損傷
IMAGE_BASE64="$(base64 < product.png | tr -d '\r\n')"

curl https://api.openai.com/v1/decisions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "model": "gpt-6-luna",
  "input": [{
    "role": "user",
    "content": [
      {"type": "input_text", "text": "Inspect the product in this photo."},
      {"type": "input_image", "image_url": "data:image/png;base64,$IMAGE_BASE64"}
    ]
  }],
  "questions": [{
    "type": "predicate",
    "name": "visible_damage",
    "instructions": "Does the product have visible damage, such as a crack, tear, or dent? Ignore shadows and damage to the packaging."
  }]
}
JSON

以下是回應範例節錄:

{
  "answers": [
    {
      "type": "predicate",
      "name": "visible_damage",
      "probability": 0.92
    }
  ]
}

probability 是模型估計條件成立的機率。你可以自行設定門檻,根據這個機率標記需要審查的照片。

請使用內嵌的 base64 資料 URL 或可公開存取的 HTTP 或 HTTPS URL 提供圖片。此端點不支援 file_id 輸入。在使用者訊息中結合 input_text 和 input_image 區塊,即可讓模型依照指示或其他上下文評估圖片。

在問題指示中加入圖片

將所有問題共用的佐證資料放在 input 中。如要為每個問題提供不同的圖片,請將其 instructions 設為由 input_text 和 input_image 區塊組成的非空陣列。條件判斷、選擇和評分問題都支援這種用法。純文字指示仍可使用字串。

例如,將下列 JSON 請求主體傳送至 POST /v1/decisions,即可將待比對圖片與共用的參考圖片比對。請將兩個範例圖片 URL 換成可公開存取的圖片 URL,或使用 base64 圖片資料 URL:

{
  "model": "gpt-6-luna",
  "input": [
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "The shared image is reference image A."
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/reference.jpg"
        }
      ]
    }
  ],
  "questions": [
    {
      "type": "predicate",
      "name": "candidate_matches_reference",
      "instructions": [
        {
          "type": "input_text",
          "text": "Is candidate image B a derivative or variant of reference image A, including recompression or resizing?"
        },
        {
          "type": "input_image",
          "image_url": "https://example.com/candidate.jpg"
        }
      ]
    }
  ]
}

在問題指示中加入圖片時,請注意:

  • 每新增一張待比對圖片,就新增一個問題。每個問題都會將自己的圖片與同一張共用參考圖片比對。
  • 直接在 instructions 中提供內容區塊,無須包成訊息或指定 role。
  • 問題中的圖片與 input 中的圖片合併計算,共用每個請求的圖片限額。

從固定選項中擇一

choice 問題會從你提供的選項中選出一個值。請為每個選項指定不同的值,並說明各選項適用的情況。

模型會讀取每個選項的 value。如果你提供了 description,模型也會讀取其內容。這兩個欄位都是提示詞的一部分,因此即使說明維持不變,修改 value 也可能改變結果。

設定字串型別的 value 時,請優先使用 "billing" 和 "technical" 這類能表達選項意義的標籤,避免使用 UUID 這類看不出含義的識別碼。

選項說明應簡潔明瞭,如下列範例所示。

以下請求會判斷客訴應分派給哪個部門:

分派客訴
curl https://api.openai.com/v1/decisions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": "I was charged twice for my order.",
    "questions": [{
      "type": "choice",
      "name": "department",
      "instructions": "Which department should handle this complaint?",
      "choices": [
        {"value": "billing", "description": "Payments, invoices, and refunds."},
        {"value": "technical", "description": "Problems using the product."},
        {"value": "shipping", "description": "Delivery and tracking."},
        {"value": "other", "description": "Requests outside these categories."}
      ]
    }]
  }'

以下是回應範例節錄:

{
  "answers": [
    {
      "type": "choice",
      "name": "department",
      "choice": "billing",
      "probabilities": [
        { "value": "billing", "probability": 0.95 },
        { "value": "technical", "probability": 0.02 },
        { "value": "shipping", "probability": 0.01 },
        { "value": "other", "probability": 0.02 }
      ],
      "confidence": 0.93
    }
  ]
}

答案的 choice 欄位包含你提供的其中一個值,在此例中為 "billing"。答案也包含各選項的 probabilities 陣列和 confidence 欄位。如需設定門檻的指引,請參閱解讀答案。

如果類別無法涵蓋所有可能的輸入,請加入 "other" 之類的備用選項。應用程式可以將這類結果送至一般審查佇列。

依評分規準評分

score 問題會依照 2 到 10 個有順序的 levels 評估輸入。請定義每個等級的判定標準,並由低到高排列。

依嚴重程度為問題評分
curl https://api.openai.com/v1/decisions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": "Export fails in Safari but works in Chrome.",
    "questions": [{
      "type": "score",
      "name": "severity",
      "instructions": "How severe is this issue?",
      "levels": [
        {"label": "Cosmetic", "description": "Appearance only; no lost functionality."},
        {"label": "Workaround available", "description": "A task fails, but another way works."},
        {"label": "Fully blocked", "description": "A task fails with no workaround."}
      ]
    }]
  }'

以下是回應範例節錄:

{
  "answers": [
    {
      "type": "score",
      "name": "severity",
      "score": 1.1,
      "probabilities": [
        { "value": 0, "label": "Cosmetic", "probability": 0.1 },
        { "value": 1, "label": "Workaround available", "probability": 0.7 },
        { "value": 2, "label": "Fully blocked", "probability": 0.2 }
      ],
      "confidence": 0.55
    }
  ]
}

等級索引從 0 開始。在此例中,0 表示只影響外觀,1 表示有替代做法,2 表示完全無法繼續。傳回的 score 是依機率計算的加權平均值,因此可能落在兩個等級之間。在此例中,各等級的機率分別為 0.1、0.7 和 0.2,算出的分數為 1.1。

答案也包含 confidence 和各等級的 probabilities。分數反映各等級的整體機率分布。如需選出單一類別,請使用 choice。

一次提出多個問題

每個請求可包含 1 到 400 個問題。將彼此獨立的問題放在同一個 questions 陣列中,即可針對共用輸入進行評估。例如,對於一張產品照片,可以在同一個請求中檢查是否有損傷,並判斷產品類別。每個問題都可以使用不同的類型。

如果決策取決於先前的答案,請分別傳送請求。例如,先檢查是否有損傷,再根據結果決定是否需要詢問維修類別。

請根據可觀察的條件撰寫問題。將不同的判斷事項拆成不同問題,讓各選項的意義明確區隔,並為相鄰的評分等級訂定不同的判定標準。

解讀答案

條件判斷問題會傳回條件成立的估計機率。選擇和評分問題的答案則包含機率分布,以及獨立的 confidence 欄位。

使用應用程式中已標註的範例,為分派、篩選或審查設定門檻。選擇門檻時,請考量偽陽性和偽陰性的代價。

透過提示詞快取重複使用共用輸入

透過提示詞快取,多次傳送請求時,只要共用 input 的前綴相符,就能重複使用該前綴,並享有快取讀取優惠費率。例如,可以將參考文件或圖片保留在 input 中,每次請求只更換問題。questions 中的內容(包括問題專屬的圖片)不在可重複使用的前綴範圍內。

預設情況下,Decisions 會在共用 input 的結尾設定隱含的快取中斷點。既有請求無須修改請求主體即可使用快取。可重複使用的前綴必須至少包含 1,024 個 Token,問題內容不計入此門檻。請確保各請求的前綴完全相同,以便重複使用。

使用 prompt_cache_key 即可依呼叫端提供的鍵劃分快取的重複使用範圍。如需自行指定快取邊界,請將 prompt_cache_breakpoint: {"mode": "explicit"} 加入共用 input 中的文字或圖片內容區塊。將 prompt_cache_options.mode 設為 "explicit",即可只使用已標記的邊界。在明確指定邊界的模式下,如果請求中沒有標記任何邊界,就不會使用提示詞快取。問題指示不支援快取中斷點。

查看 usage.input_tokens_details.cached_tokens 可取得從快取讀取的 Token 數量,查看 usage.input_tokens_details.cache_write_tokens 則可取得寫入快取的 Token 數量。這兩項數量均已計入 usage.input_tokens,請勿重複加總。如需瞭解快取概念,請參閱提示詞快取指南。如需查看請求支援的控制選項,請參閱 Decisions 參考文件。

監控用量

使用 GET /v1/organization/usage/decisions 取得組織的 Decisions Token 用量和請求數。請使用具有 api.usage.read 權限的管理員 API 金鑰進行驗證。

選擇時間範圍和每個統計區間的長度,再依專案、API 金鑰或模型篩選結果或將結果分組。num_model_requests 欄位統計的是請求數,即使一個請求包含多個問題,也只計算一次。如需瞭解篩選和分頁方式,請參閱 Decisions 用量參考文件。

定價與適用範圍

使用 gpt-6-luna 時,未快取輸入的費率為每 100 萬個 Token 0.10 美元。命中提示詞快取的輸入適用優惠費率,寫入快取則會收費。快取讀取與寫入的費率均與 gpt-6-luna 的標準提示詞快取費率相同。輸出 Token 不收費。

區域處理附加費與長上下文輸入的費率倍數均適用。上述費率適用於 /v1/decisions。其他使用 gpt-6-luna 的請求則依相應的模型與處理層級費率計費。

符合資格的客戶可在 Decisions API 使用零資料保留(ZDR),也可將此 API 用於受 HIPAA 規範的情境。所有支援的 API 區域均提供資料駐留。美國和歐洲(歐洲經濟區及瑞士)支援區域處理。如需瞭解資格要求、必要協議和限制,請參閱資料控制。

加入語音控制

將語音連接至 Decisions,即可根據口頭請求選擇動作,或在使用者或 GPT-Live 說話時即時做出反應。