打造專屬ChatGPT：OpenAI Chat Completion API參數解析(20241111更新)

POST https://api.openai.com/v1/chat/completions

client = OpenAI()

completion = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"},
    ],
)

print(completion.usage)

B. 請求參數

1. REST API的參數

messages = [
    {
        "role": "system", 
        "content": "你是品牌形象大師"
    },
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "這個Logo好嗎"},
            {"type": "text", "text": "你可以給我一些建議嗎"},
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://i0.wp.com/www.alfred.wiki/wp-content/uploads/2024/11/cropped-Logo_info_2400x900_transparent.png?resize=1024%2C307&ssl=1"
                },
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": f"data:{image_mime_type};base64,{base64_image}"
                },
            },
        ],
    },
    {
        "role": "assistant", 
        "content": "這個Logo設計有一些優點和改進的建議：..."
    },
]

{
    "type" :"json_schema",
    "json_schema" {
        "name": Required，a-zA-Z0-9_-，最大長度64
        "description": 協助模型了解該如何使用這個結構
        "schema": JSON Schema物件
        "strict": boolean or null，是否嚴格遵循定義。設為True時，只支持部分JSON Schema。預設為False
    }
}

{
    "type": "function",
    "function" : {
        "name": string，Required，function(tool)的名稱,
        "description": string，Optional，描述function(tool)的用途，讓模型知道使用時機
        "parameters": object，Optional，描述function需要的參數，使用JSON Schema物件。{
            "type": "object",
            "properties": {
                "參數名稱": {
                    "type": "參數類型",
                    "description": "參數說明"
                }
            }
        },
        "strict": "boolean or null，Optional，Defaults to false，控制是否嚴格遵守papameters的設定(只支援部分的JSON Schema)"
    }
}

{
    "type": "function",
    "function" : {
        "name": string，Required，function(tool)的名稱
    }
}

# a ChatCompletion request
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "What's 1+1? Answer in one word."}],
        temperature=0,
        stream=True,  # this time, we set stream=True
    )

    for chunk in response:
        print(content=chunk.choices[0].delta.content)
        print("****************")

{
    "type": "content",
    "content": string or array
}

2. OpenAI Python SDK封裝的其他參數

a. 額外參數

如果有額外的參數要在API傳遞，依據不同的位置使用不同的名稱，

• extra_query：查詢字串
• extra_body：請求Body
• extra_headers：請求Header

資料皆為key-value對應，Python中使用dict資料類型。

b. timeout

預設情況(httpx.Timeout(timeout=600.0, connect=5.0))下，請求在10分鐘後會超時。透過timeout選項進行調整，接受浮點數(秒)或httpx.Timeout物件。

# Configure the default for all requests
client = OpenAI(
    timeout=20.0,
)

# More granular control:
client = OpenAI(
    timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0)
)

# Override per-request:
client.with_options(timeout=5.0).chat.completions.create(
    messages=[{"role": "user", "content": "Hello"}],
    model="gpt-4o"
)

# Override the client-level default timeout for this request, in seconds
client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello"}],
    model="gpt-4o",
    timeout=5
)

某些錯誤在預設情況下會自動重試兩次，並採用短暫的指數退避策略。連線錯誤(例如，由於網絡連接問題)、408 Request Timeout, 409 Conflict, 429 Rate Limit, and >=500 Internal errors皆會被預設重試。改寫方式：

# Configure the default for all requests:
client = OpenAI(max_retries=0) # default is 2

# Or, configure per-request:
client.with_options(max_retries=5).chat.completions.create(
    messages=[{"role": "user", "content": "Hello"}],
    model="gpt-3.5-turbo",
)

C. The chat completion object

一般請求下，Chat Completion API回傳的物件結構：

1. id，string，唯一值，請求的ID。
2. choices，array，回答的內容，根據不同請求參數n，array中會有n個元素，每個元素都是一個物件，結構如下：
   • finish_reason，string，模型停止生成標記的原因：
     • stop：當模型到達自然停止點或遇到指定的停止序列時。
     • length：達到請求中指定的最大token數。
     • content_filter：自訂義的內容過濾器。
     • tool_calls：模型調用了工具。
   • index，integer，choices的索引值，與請求參數n對應。
   • message，object，模型回傳的訊息，結構如下：
     • content：string or null，訊息內容。
     • refusal：string or null，拒絕的訊息，請求時設定參數response_format使用json_schema相關時才會出現。
     • tool_calls，array，此次請求中模型回應所需的Tool們，並以object表示，給個object格式如下：
       • id：string，這次呼叫的ID。
       • type：string，這裡只會是function。
       • function，object：
         • name：Tool(function)的名稱，與傳入參數Tools中的name相同。
         • arguments：string，通常是json字串，代表呼叫Tool所需的參數。請注意，模型並不總是生成有效的JSON，並且可能會臆測出您函數結構中未定義的參數。在呼叫函數之前，請在您的代碼中驗證這些引數。
     • role：訊息角色，這裡通常會是Assistant message。
   • logprobs：object or null，啟用參數logprobs時，模型提供的相關資訊，跟著message中的content或refusal的每一個token的log probability。結構如下：
     • content：array or null。
     • refusal：array or null。
3. created，integer，Unix時間戳記，請求建立的時間。
4. model，string，本次使用的模型。
5. service_tier，string or null，請求API時如果有帶入相關資訊，回傳結果上才會出現，該參數請參考官方說明。
6. system_fingerprint，string，系統的指紋，有助於確認輸出變化是否是OpenAI模型後端更新導致，當設定更改時，即使使用相同的seed，結果也可能不同。
7. object，string，物件名稱，使用Chat Completion API時，值會是chat.completion。
8. usage，object，此次請求的用量，結構如下：
   • completion_tokens：integer，生成回覆的token數量。
   • prompt_tokens：integer，問題的token數量。
   • total_tokens：integer，completion_tokens+prompt_tokens的總額。
   • completion_tokens_details：object，結構如下，
     • reasoning_tokens：integer，用於推理的token。
     • accepted_prediction_tokens：integer，使用參數prediction時，預測的token有出現在結果的數量。
     • rejected_prediction_tokens：integer，使用參數prediction時，預測的token未出現在結果的數量。但就像推理token一樣，這些token在計算總完成token數時仍會被包含在內，用於計費、輸出和上下文窗口限制。
     • audio_tokens：integer，音訊使用的token。
   • prompt_tokens_details：object，結構如下，
     • audio_tokens：integer，音訊使用的token。
     • cached_tokens：integer，快取使用的token。

D. The chat completion chunk object

Stream請求下，Chat Completion API回傳每個Chunk的結構：

1. id：string，唯一值，請求的ID，同個請求不同Chunk的ID相同。
2. choices：array，回答的內容，根據不同請求參數n，array中會有n個元素。設定stream_options: {"include_usage": true}時，最後一則訊息choices為空，此時usage為此次請求的總API用量。每個元素都是一個物件，結構如下，
   • finish_reason：string，模型停止生成標記的原因，有以下幾種可能，
     • stop：當模型到達自然停止點或遇到指定的停止序列時。
     • length：達到請求中指定的最大token數。
     • content_filter：自訂義的內容過濾器。
     • tool_calls：模型調用了工具。
   • index：integer，choices的索引值，與請求參數n對應。
   • delta：object，模型回傳的訊息，結構如下，
     • content：string or null，訊息內容。
     • refusal：string or null，拒絕的訊息，請求時設定參數response_format使用json_schema時才會出現。
     • tool_calls：array，此次請求中模型回應所需的Tool們，並以object表示，給個object格式如下，
       • id：string，這次呼叫的ID。
       • type：string，這裡只會是function。
       • function：object
         • name：Tool(function)的名稱，與傳入參數Tools中的name相同。
         • arguments：string，通常是json字串，代表呼叫Tool所需的參數。請注意，模型並不總是生成有效的JSON，並且可能會臆測出您函數結構中未定義的參數。在呼叫函數之前，請在您的代碼中驗證這些引數。
     • role：訊息角色，這裡通常會是Assistant message。
   • logprobs：object or null，啟用參數logprobs時，模型提供的相關資訊，跟著message中的content或refusal的每一個token的log probability。結構如下：
     • content：array or null。
     • refusal：array or null。
3. created：integer，Unix時間戳記，請求建立的時間。
4. model：string，本次使用的模型。
5. service_tier：string or null，請求API時如果有帶入相關資訊，回傳結果上才會出現，該參數請參考官方說明。
6. system_fingerprint：string，系統的指紋，有助於確認輸出變化是否是OpenAI模型後端更新導致，當設定更改時，即使使用相同的seed，結果也可能不同。
7. object：string，物件名稱，使用Chat Completion API時，值會是chat.completion.chunk。
8. usage：object，此次請求的用量，設定stream_options: {"include_usage": true}時才會出現，此時choices為null。結構如下，
   • completion_tokens：integer，生成回覆的token數量。
   • prompt_tokens：integer，問題的token數量。
   • total_tokens：integer，completion_tokens+prompt_tokens的總額。

E. 總結

文章中，探討了如何使用OpenAI的Python SDK來操作Chat completions API，特別關注gpt-4o模型所需的參數以及回傳物件的結構，並針對不太容易理解的參數進行重新分組和白話文解釋，希望能讓OpenAI虛無縹緲的說明稍微具象化。

從模型輸入參數中，衍生出了兩個主題：

1. 〖打造專屬ChatGPT：利用LLM進行結構化輸出(Structured Outputs)〗：在這部分，將記錄如何設計並生成結構化的文本輸出，讓我們可以輕易的利用LLM強大的語言能力，直接從對話中(非結構化資料)萃取出特定關鍵資訊(結構化資料)。

2. 〖打造專屬ChatGPT：透過OpenAI Tool Calling深度整合資源〗：這個主題關注如何通過OpenAI的Tool Calls(前身為function calls)，將模型與外部資源深度整合。將記錄如何利用這些工具來擴展模型的能力，從而獲取更豐富和專業化的服務。

OpenAI Chat completions API的參數眾多，希望這樣的整理，能夠更有效率的查詢所需資料。