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

提示工程

運用提示工程策略改善生成結果。

透過 OpenAI API,你可以讓大型語言模型根據提示詞生成文字,就像使用 ChatGPT 一樣。模型幾乎能生成任何形式的文字回應,例如程式碼、數學方程式、結構化的 JSON 資料,或讀起來像人寫的文章。

以下是使用 Responses API 的範例。

根據簡單的提示詞生成文字
import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  input: "Write a one-sentence bedtime story about a unicorn.",
});

console.log(response.output_text);

回應的 output 屬性是一個陣列,內含模型生成的內容。這個範例只有一個輸出項目,如下所示:

[
  {
    "id": "msg_67b73f697ba4819183a15cc17d011509",
    "type": "message",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "Under the soft glow of the moon, Luna the unicorn danced through fields of twinkling stardust, leaving trails of dreams for every child asleep.",
        "annotations": []
      }
    ]
  }
]

回應中的 output 陣列通常包含多個項目! 其中可能包含工具呼叫、推理模型生成的推理 Token 相關資料,以及其他項目。請勿假設模型輸出的文字一定位於 output[0].content[0].text。

為了方便取得文字,部分官方 SDK 在模型回應中提供 output_text 屬性,將模型輸出的所有文字合併為單一字串。你可以透過這個屬性直接取得模型輸出的文字。

除了純文字,你也可以讓模型以 JSON 格式傳回結構化資料。這項功能稱為結構化輸出。

選擇模型

透過 API 生成內容時,一項重要的決定是要使用哪個模型。上述程式碼範例使用 model 參數指定模型。查看所有可用模型。選擇文字生成模型時,可以考量以下因素。

  • 推理模型 會在內部生成思路鏈來分析輸入的提示詞,擅長理解複雜任務及規劃多個步驟。相較於 GPT 模型,推理模型通常速度較慢,使用成本也較高。
  • GPT 模型速度快、成本效益高,能力也很強。如果指示中明確說明如何完成任務,效果會更好。
  • 大型與小型(mini 或 nano)模型在速度、成本和能力之間各有取捨。大型模型更擅長理解提示詞及解決各領域的問題,小型模型通常速度更快、成本更低。

如果不確定該選哪個模型,gpt-6-astra 是生成一般用途文字及反覆調整提示詞時的理想預設選擇。

提示工程

提示工程是為模型撰寫有效指示的過程,目的是讓模型穩定生成符合需求的內容。

即使輸入相同,模型生成的內容也可能不同,因此要寫出能產生預期結果的提示詞,既需要經驗,也講究方法。運用適當的技巧與最佳做法,可以持續取得良好的結果。

有些提示工程技巧適用於所有模型,例如使用訊息角色。但不同類型的模型(例如推理模型和 GPT 模型)可能需要不同的提示方式,才能得到最佳結果。即使是同一系列模型的不同快照,也可能產生不同的結果。因此,在建構較複雜的應用程式時,我們強烈建議採取以下做法:

  • 讓正式環境中的應用程式固定使用特定的模型快照(例如 gpt-4.1-2025-04-14),以確保行為一致。
  • 建立測試與評估套件,衡量模型對提示詞的反應,以便在調整提示詞、更換或升級模型版本時監控表現。

接下來介紹幾種可用來撰寫提示詞的工具與技巧。

訊息角色與指示的遵循方式

你可以透過 API 向模型提供不同權限層級的指示,做法是使用 instructions 參數或訊息角色。

instructions 參數可用來提供高層次指示,說明模型在生成回應時應採取的行為,包括語氣、目標及正確回應的範例。透過這個參數提供的指示,優先順序都高於 input 參數中的提示詞。

根據指示生成文字
import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "low" },
  instructions: "Talk like a pirate.",
  input: "Are semicolons optional in JavaScript?",
});

console.log(response.output_text);

上面的範例大致等同於在 input 陣列中傳入下列訊息:

使用不同角色的訊息生成文字
import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "low" },
  input: [
    {
      role: "developer",
      content: "Talk like a pirate.",
    },
    {
      role: "user",
      content: "Are semicolons optional in JavaScript?",
    },
  ],
});

console.log(response.output_text);

請注意,instructions 參數只適用於本次生成回應的請求。如果你在管理對話狀態時使用 previous_response_id 參數,先前各輪使用的 instructions 不會出現在本次請求的上下文中。

OpenAI 模型規格說明模型如何依據角色決定訊息的優先順序。

developer user assistant
developer 訊息包含開發者提供的指示,優先順序高於 user 訊息。 user 訊息包含終端使用者提供的指示,優先順序低於 developer 訊息。 模型生成的訊息使用 assistant 角色。

多輪對話可以包含數則上述類型的訊息,以及你和模型提供的其他類型內容。進一步瞭解如何管理對話狀態。

你可以把 developer 和 user 訊息的關係想成程式語言中函式與引數的關係。

  • developer 訊息提供系統規則與業務邏輯,就像函式定義。
  • user 訊息提供輸入與設定,就像傳給函式的引數。模型會將 developer 訊息中的指示套用到這些輸入與設定。

在程式碼中管理提示詞版本

請直接將正式環境使用的提示詞存放在應用程式碼中,無須另外建立可重複使用的提示詞物件。在程式碼中管理提示詞,就能透過具型別的輸入、程式碼審查、測試及既有的部署流程來調整模型行為。

OpenAI 正逐步棄用 API 中可重複使用的提示詞物件。自 2026 年 6 月 3 日起,OpenAI 將不再著重推廣建立提示詞物件的做法,v1/prompts 預計於 2026 年 11 月 30 日停止服務。最新時程請見棄用公告。

開始新的提示工程工作時,建議採取以下做法:

  • 將建構提示詞的程式碼集中在小型模組中,放在所支援功能的程式碼附近。
  • 使用具型別的函式引數或結構描述來定義動態值,例如客戶資料、檔案或任務選項。
  • 將產生的 instructions 和 input 直接傳給 Responses API。
  • 變更正式環境的提示詞前,先加入具代表性的測試資料、測試及評估檢查。
  • 透過部署系統推出提示詞變更。需要分階段發布時,可使用功能旗標或組態設定。

如果現有整合已透過提示詞 ID 或版本呼叫儲存的提示詞,請依照提示詞物件遷移指南,將該提示詞移至程式碼中。

使用 Markdown 與 XML 設定訊息格式

撰寫 developer 和 user 訊息時,可以搭配使用 Markdown 格式與 XML 標籤,幫助模型辨識提示詞和上下文資料中各部分的界線。

Markdown 標題和清單有助於區分提示詞的各個區段,讓模型理解內容的層級關係,也能讓開發者更容易閱讀提示詞。XML 標籤可以標示一段內容的起點與終點,例如一份供模型參考的文件。你也可以使用 XML 屬性為提示詞中的內容定義中繼資料,供指示引用。

開發者訊息通常依照以下順序安排各個區段,但最合適的內容與順序可能因模型而異:

  • 身分: 說明助理的用途、溝通風格及整體目標。
  • 指示: 說明模型該如何生成你想要的回應。模型應遵循哪些規則?該做哪些事?哪些事絕對不能做?你可以視使用情境在此加入多個小節,例如說明模型該如何呼叫自訂函式。
  • 範例: 提供可能的輸入範例,以及你希望模型針對各項輸入產生的輸出。
  • 上下文: 提供模型生成回應時可能需要的補充資訊,例如訓練資料未涵蓋的私人或專有資料,或其他你知道與任務特別相關的資料。不同的生成請求可能需要不同的上下文,因此這類內容通常最適合放在提示詞接近結尾處。

以下範例使用 Markdown 和 XML 標籤撰寫 developer 訊息,將內容分成不同區段,並附上相關範例。

用於生成程式碼的開發者訊息
# Identity

You are coding assistant that helps enforce the use of snake case
variables in JavaScript code, and writing code that will run in
Internet Explorer version 6.

# Instructions

* When defining variables, use snake case names (e.g. my_variable)
  instead of camel case names (e.g. myVariable).
* To support old browsers, declare variables using the older
  "var" keyword.
* Do not give responses with Markdown formatting, just return
  the code as requested.

# Examples

<user_query>
How do I declare a string variable for a first name?
</user_query>

<assistant_response>
var first_name = "Anna";
</assistant_response>

使用提示詞快取降低成本並縮短延遲

撰寫訊息時,盡量將預期會在 API 請求中重複使用的內容放在提示詞開頭,並且在傳給 Chat Completions 或 Responses 的 JSON 請求主體中,將承載這些內容的 API 參數放在前面。這樣就能充分利用提示詞快取來降低成本並縮短延遲。

少樣本學習

透過少樣本學習,你只需在提示詞中加入幾組輸入與輸出範例,就能引導大型語言模型執行新任務,無須微調模型。模型會自行從範例中掌握規律,並運用這些規律來回應提示詞。選擇範例時,請盡量涵蓋多種可能的輸入,並為每種輸入提供期望的輸出。

通常可以在 API 請求的 developer 訊息中提供範例。以下 developer 訊息透過範例示範如何判斷客服評論是正面還是負面。

# 身分

你是一位樂於助人的助理,負責將簡短的產品評論標記為 Positive、Negative 或 Neutral。

# 指示

* 回應時只能輸出一個單字,不要加上額外格式或說明。
* 根據產品評論表達的態度,從「Positive」、「Negative」和「Neutral」中選一個單字作答。

# 範例

<product_review id="example-1">
我超喜歡這款耳機,音質太棒了!
</product_review>

<assistant_response id="example-1">
Positive
</assistant_response>

<product_review id="example-2">
續航力還可以,不過耳墊摸起來很廉價。
</product_review>

<assistant_response id="example-2">
Neutral
</assistant_response>

<product_review id="example-3">
客服實在太糟了,我再也不會跟他們買東西了。
</product_review>

<assistant_response id="example-3">
Negative
</assistant_response>

加入相關的上下文資訊

在提示詞中補充上下文資訊,往往有助於模型生成回應。常見的原因包括:

  • 讓模型能使用專有資料,或其他未納入模型訓練資料集的資料。
  • 限定模型只能依據你認為最有幫助的一組資源來回應。

在生成請求中為模型補充相關上下文的技巧,有時稱為檢索增強生成(RAG)。補充上下文的方式很多,例如查詢向量資料庫並將傳回的文字加入提示詞,或使用 OpenAI 內建的檔案搜尋工具,根據上傳的文件生成內容。

依上下文視窗容量規劃輸入

模型在單次生成請求中能處理的上下文資料量有其上限。這個記憶容量限制稱為上下文視窗,以 Token 為單位計算。無論傳入的是文字還是圖片,都會分成這樣的資料單位。

各模型的上下文視窗大小不同,從十多萬個 Token 起,較新的 GPT-4.1 模型則可達一百萬個 Token。請參閱模型文件,查看各模型的上下文視窗大小。

為目前的模型撰寫提示詞

對於 gpt-6-astra 等 GPT 模型,在提示詞中給予精確指示,明確提供完成任務所需的邏輯與資料,有助於改善結果。想充分發揮最新模型的能力,可以先閱讀現行的提示詞指南。

GPT-6 Astra prompting guide

參考最新指引、實用範例與遷移注意事項,為最新模型撰寫有效的提示詞。

最新模型的提示詞最佳做法

如需完整的現行指引,請參閱最新模型的提示詞最佳做法。以下實務建議仍然適用。

為推理模型撰寫提示詞

為推理模型和 GPT 模型撰寫提示詞時,請考量兩者的差異。一般而言,只提供整體方向,推理模型就能在任務中取得較好的結果。GPT 模型則在收到精確的指示時表現更好。

你可以用以下比喻來理解推理模型與 GPT 模型的差異。

  • 推理模型就像資深同事。你可以交代要達成的目標,放心讓對方自行處理細節。
  • GPT 模型就像資歷較淺的同事。明確說明如何產出指定的成果,對方就能有最好的表現。

如需進一步瞭解使用推理模型的最佳做法,請參閱這份指南。

後續步驟

掌握文字輸入與輸出的基礎後,可以接著探索以下資源。

在 Playground 中撰寫提示詞

使用 Playground 開發並反覆調整提示詞。

使用結構化輸出生成 JSON 資料

確保模型輸出的 JSON 資料符合指定的 JSON 結構描述。

完整 API 參考文件

在 API 參考文件中查看文字生成的所有選項。

其他資源

如需更多靈感,請瀏覽 OpenAI Cookbook。其中收錄了程式碼範例,也提供以下第三方資源的連結: