如果您需要完全掌控 ChatKit 的运行方式,例如自定义身份验证、满足数据驻留要求、在本地部署或定制智能体编排逻辑,可以在自有基础设施上运行 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 数据块,这样即使库更新时调整了数据模式,也无需迁移数据。
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.2-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 上的小组件指南,了解所有组件及其属性,以及如何以流式方式更新组件。
您可以使用小组件构建器,在交互式界面中探索和创建小组件。
使用操作
通过操作,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 |
用于查找实体、处理点击和显示预览的回调函数。 |