如果你需要完整的控制權,例如自訂身分驗證、符合資料駐留要求、在地端部署,或自訂智慧體的編排方式,可以在自己的基礎設施上執行 ChatKit。OpenAI 提供進階自架方案,讓你在自己的伺服器上執行並自訂 ChatKit。
由 Agent Builder 代管的 ChatKit 工作流程目前處於過渡期。開發新的 ChatKit 應用程式時,請使用 ChatKit SDK 和 Agents SDK,在自己的伺服器端實作智慧體, 並以此為基礎建構應用程式。請參閱 ChatKit 過渡期指南 →
在自己的基礎設施上執行 ChatKit
整合 ChatKit 的進階做法是架設自己的 ChatKit 伺服器,再加入小工具來建構對話介面。你會搭配使用 OpenAI API 和自己的 ChatKit 伺服器,打造由 OpenAI 模型驅動的自訂對話體驗。

設定 ChatKit 伺服器
請參閱 GitHub 上的伺服器指南,瞭解如何處理傳入的請求、執行工具,並以串流方式將結果傳回用戶端。以下程式碼片段示範主要元件的用法。
1. 安裝伺服器套件
pip install openai-chatkit
2. 實作伺服器類別
ChatKitServer 負責管理對話流程。覆寫 respond,讓伺服器每次收到使用者訊息或用戶端工具的輸出時,都能以串流方式傳送事件。你可以透過 stream_agent_response 等輔助函式,將伺服器連接到 Agents SDK。
class MyChatKitServer(ChatKitServer[RequestContext]):
async def respond(
self,
thread: ThreadMetadata,
input: UserMessageItem | ClientToolCallOutputItem | None,
context: RequestContext,
) -> AsyncIterator[Event]:
items_page = await self.store.load_thread_items(
thread.id,
after=None,
limit=20,
order="desc",
context=context,
)
input_items = await simple_to_agent_input(list(reversed(items_page.data)))
agent_context = AgentContext(
thread=thread,
store=self.store,
request_context=context,
)
result = Runner.run_streamed(
assistant_agent,
input_items,
context=agent_context,
)
async for event in stream_agent_response(agent_context, result):
yield event3. 開放端點
使用你選用的框架,將 HTTP 請求轉送至伺服器執行個體。以下以 FastAPI 為例:
from fastapi import FastAPI, Request, Response
from fastapi.responses import StreamingResponse
app = FastAPI()
data_store = MemoryStore()
server = MyChatKitServer(data_store)
@app.post("/chatkit")
async def chatkit_endpoint(request: Request):
result = await server.process(await request.body(), {})
if isinstance(result, StreamingResult):
return StreamingResponse(result, media_type="text/event-stream")
return Response(content=result.json, media_type="application/json")4. 實作資料儲存介面
實作 chatkit.store.Store,將對話串、訊息和檔案持久儲存在你選用的資料庫中。在本機開發時,可以使用將資料存放在記憶體中的 Store 實作。在正式環境中,請使用持久性儲存空間,並考慮將資料模型儲存為 JSON blob。這樣一來,即使程式庫更新時變更結構描述,也不必遷移資料。
5. 實作檔案儲存介面
如果應用程式支援上傳檔案,請提供 FileStore 實作。ChatKit 支援直接上傳(用戶端以 POST 請求將檔案傳送至你的端點),也支援兩階段上傳(用戶端先請求取得已簽署的 URL,再將檔案上傳至雲端儲存空間)。請提供檔案預覽,讓對話中能直接顯示縮圖,並在移除對話串時處理檔案刪除作業。
6. 從伺服器觸發用戶端工具
你必須在用戶端選項和智慧體中都註冊用戶端工具。在 Agents SDK 工具中使用 ctx.context.client_tool_call,即可將用戶端工具呼叫加入佇列。
@function_tool(description_override="Add an item to the user's todo list.")
async def add_to_todo_list(ctx: RunContextWrapper[AgentContext], item: str) -> None:
ctx.context.client_tool_call = ClientToolCall(
name="add_to_todo_list",
arguments={"item": item},
)
assistant_agent = Agent[AgentContext](
model="gpt-6-astra",
name="Assistant",
instructions="You are a helpful assistant",
tools=[add_to_todo_list],
tool_use_behavior=StopAtTools(stop_at_tool_names=[add_to_todo_list.name]),
)7. 使用對話串的中繼資料與狀態
使用 thread.metadata 儲存伺服器端狀態,例如上一次 Responses API 執行作業的 ID 或自訂標籤。用戶端無法存取這些中繼資料,但每次呼叫 respond 時都能在伺服器端取得。
8. 取得工具狀態更新
執行時間較長的工具可以使用 ProgressUpdateEvent,以串流方式將進度傳送至使用者介面。ChatKit 會以下一則助理訊息或小工具輸出取代進度事件。
9. 使用伺服器上下文
將自訂上下文物件傳入 server.process(body, context),即可執行權限控管,或將使用者身分傳遞至資料儲存與檔案儲存介面的實作。
在對話中加入互動式小工具
智慧體可以透過小工具,直接在對話中呈現卡片、表單、文字區塊、清單和其他版面配置,提供豐富的使用者介面。輔助函式 stream_widget 可以立即顯示小工具,也可以在收到更新時以串流方式傳送更新內容。
async def respond(
self,
thread: ThreadMetadata,
input: UserMessageItem | ClientToolCallOutputItem | None,
context: RequestContext,
) -> AsyncIterator[Event]:
widget = Card(
children=[
Text(
id="description",
value="Generated summary",
)
]
)
async for event in stream_widget(
thread,
widget,
generate_id=lambda item_type: self.store.generate_item_id(
item_type, thread, context
),
):
yield eventChatKit 內建多種小工具節點,包括卡片、清單、表單、文字和按鈕等。請參閱 GitHub 上的小工具指南,查看所有元件、屬性及串流使用說明。
使用 Widget Builder 即可在互動式介面中探索及建立小工具。
使用動作
透過動作,ChatKit 介面可以在使用者未傳送訊息的情況下觸發作業。將 ActionConfig 加入任何支援動作的小工具節點,就能透過按鈕、選取控制項等,以串流方式傳送新的對話串項目,或就地更新小工具。如果小工具位於 Form 內,ChatKit 會將收集到的表單欄位值納入動作承載資料。
在伺服器端實作 action 方法時,請將它定義在 ChatKitServer 上,用來處理承載資料,並視需要以串流方式傳送其他事件。你也可以設定 handler="client",在用戶端先以 JavaScript 處理動作,再將後續作業轉交給伺服器。
請參閱 GitHub 上的動作指南,瞭解如何串接動作、建立強型別的承載資料,以及協調用戶端與伺服器端的處理常式。
資源
你可以運用以下資源與參考資料完成整合。
設計資源
- 下載 OpenAI Sans Variable。
- 建立檔案副本,並依產品需求自訂元件。
事件參考
ChatKit 會透過 Web 元件發出 CustomEvent 執行個體。你可以監聽生命週期事件,並從 event.detail 讀取承載資料:
chatkit.addEventListener("chatkit.error", (event) => {
console.error(event.detail.error);
});
chatkit.addEventListener("chatkit.response.start", () => {
console.log("Response started");
});
chatkit.addEventListener("chatkit.response.end", () => {
console.log("Response ended");
});
chatkit.addEventListener("chatkit.thread.change", (event) => {
console.log("Active thread:", event.detail.threadId);
});
chatkit.addEventListener("chatkit.log", (event) => {
console.log(event.detail.name, event.detail.data);
});選項參考
| 選項 | 型別 | 說明 | 預設值 |
|---|---|---|---|
apiURL |
string |
實作 ChatKit 伺服器通訊協定的端點。 | 必填 |
fetch |
typeof fetch |
覆寫 fetch 呼叫,以自訂請求標頭或身分驗證方式。 | window.fetch |
theme |
"light" | "dark" |
使用者介面主題。 | "light" |
initialThread |
string | null |
指定元件掛載時要開啟的對話串。設為 null 時會顯示新對話串畫面。 |
null |
clientTools |
Record<string, Function> |
提供給模型呼叫、由用戶端執行的工具。 | |
header |
object | boolean |
設定頁首,或設為 false 以隱藏頁首。 |
true |
newThreadView |
object |
自訂問候語和對話開場提示詞。 | |
messages |
object |
設定訊息功能,例如意見回饋和註解。 | |
composer |
object |
控制附件、實體標籤和預留位置文字。 | |
entities |
object |
用於查詢實體、處理點擊及顯示預覽的回呼函式。 |