指令碼開發 / 聯結器物件 `DFF.CONN` / LLM（相容 OpenAI）

LLM 聯結器操作物件用於透過聯結器中配置的 OpenAI 相容 Chat Completions API 發起文字對話。

本聯結器需要目標服務相容 OpenAI Chat Completions API

不同服務支援的模型和請求引數可能不同，具體以目標服務的文件為準。

1. 聯結器配置

建立 LLM 聯結器時，需要配置以下欄位：

欄位	必須 / 預設值	說明
`Base URL`	必須 / `https://api.openai.com/v1`	OpenAI 相容 API 的基礎地址
`API Key`	必須	用於訪問目標服務的 API Key
`Model`	必須	預設使用的模型 ID，必須是目標服務支援的 Chat Completions 模型 ID

填寫 Base URL 和 API Key 後，展開 Model 選擇框時，介面會嘗試透過目標服務的 /models 介面載入模型列表。如果未能載入，仍可以手工填寫目標服務支援的模型 ID。

訊息會發送到目標服務並可能產生費用

請確認聯結器指向的目標服務，不要在訊息中傳送 API Key、密碼或無關的敏感資料。

2. 獲取聯結器操作物件

DFF.CONN(...) 引數如下：

引數	型別	必須 / 預設值	說明
`connector_id`	str	必須	聯結器 ID
`model`	str	`None`	覆蓋聯結器配置中的預設模型
`timeout`	int/float	`60`	請求超時時間，單位為秒

示例
llm = DFF.CONN('llm_connector_id')

# 為當前操作物件覆蓋預設模型和請求超時時間
another_llm = DFF.CONN('llm_connector_id', model='another-model', timeout=30)

3. `.chat(...)`

呼叫 OpenAI 相容 Chat Completions API，方法簽名如下：

Python
llm.chat(messages, model=None, **kwargs)

引數如下：

引數	型別	必須 / 預設值	說明
`messages`	str/list[dict]	必須	對話訊息。傳入字串時會自動轉換為一條 `user` 訊息；傳入訊息列表時會原樣傳送
`model`	str	`None`	僅為本次呼叫覆蓋模型
`**kwargs`	任意	無	其他關鍵字引數會透傳給 OpenAI Python SDK 的 `client.chat.completions.create(...)`，是否可用取決於目標服務

本方法將 Chat Completions 的完整響應轉換為 dict 後返回。文本回復通常位於 choices[0].message.content。

有關 Chat Completions 請求引數和響應結構，請參考 OpenAI API / Create chat completion。

3.1 單輪對話

messages 可以直接傳入字串：

示例
llm = DFF.CONN('llm_connector_id')

response = llm.chat('什麼是 DataFlux Func？')
reply    = response['choices'][0]['message']['content']
print(reply)

字串會自動轉換為以下訊息列表後傳送：

Python
messages = [{
    'role'   : 'user',
    'content': '什麼是 DataFlux Func？',
}]

3.2 多輪對話

本聯結器不會儲存對話歷史。需要多輪對話時，應由指令碼儲存並在每次呼叫時傳入完整訊息列表：

示例
llm = DFF.CONN('llm_connector_id')

messages = [
    {
        'role'   : 'system',
        'content': '請簡短回答。',
    },
    {
        'role'   : 'user',
        'content': '什麼是 DataFlux Func？',
    },
]

response = llm.chat(messages, temperature=0)
reply    = response['choices'][0]['message']['content']

messages.append({
    'role'   : 'assistant',
    'content': reply,
})
messages.append({
    'role'   : 'user',
    'content': '它適合處理哪些任務？',
})

response = llm.chat(messages, temperature=0)

3.3 臨時覆蓋模型

模型按以下優先順序選擇：

.chat(...) 的 model 引數；
DFF.CONN(...) 的 model 引數；
聯結器配置中的 Model。

示例
llm = DFF.CONN('llm_connector_id', model='default-model-for-this-object')

# 本次呼叫使用 another-model
response = llm.chat('你好！', model='another-model')

4. 能力邊界和安全注意事項

本聯結器呼叫 Chat Completions API，不呼叫 Responses API。
本聯結器只支援非流式返回，不要傳入 stream=True。
本聯結器不會儲存對話歷史，也不會自動管理上下文長度。應根據模型上下文視窗、DataFlux Func 任務超時和呼叫方要求限制訊息歷史及輸出大小。
其他引數雖然可以透過 **kwargs 透傳，但本聯結器不負責管理工具呼叫、檔案、圖片、音訊等內容，也不自動執行模型返回的工具引數。
模型輸出屬於不可信資料。執行模型生成的程式碼、命令、SQL 或工具引數前，必須另行校驗並確認授權。

指令碼開發 / 聯結器物件 DFF.CONN / LLM（相容 OpenAI）