腳本開發 / 連接器對象 `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）