如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

ChatKit 高级集成

在自有基础设施上运行 ChatKit,按需定制聊天体验。

如果您需要完全掌控 ChatKit 的运行方式,例如自定义身份验证、满足数据驻留要求、在本地部署或定制智能体编排逻辑,可以在自有基础设施上运行 ChatKit。OpenAI 的高级自托管方案允许您使用自己的服务器并按需定制 ChatKit。

由 Agent Builder 托管的 ChatKit 工作流目前处于过渡期。开发新的 ChatKit 应用时,请使用 ChatKit SDK 和 Agents SDK,在您自己的服务器上实现智能体逻辑。请参阅 ChatKit 过渡指南 →

在自有基础设施上运行 ChatKit

ChatKit 高级集成主要包括两个步骤:搭建自己的 ChatKit 服务器,然后添加小组件来构建聊天界面。您将使用 OpenAI API 和自己的 ChatKit 服务器,构建由 OpenAI 模型驱动的自定义聊天应用。

由 OpenAI 托管的 ChatKit

设置 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 event

3. 对外提供端点

使用您选择的框架将 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 event

ChatKit 内置了多种小组件节点,包括卡片、列表、表单、文本和按钮等。请参阅 GitHub 上的小组件指南,了解所有组件及其属性,以及如何以流式方式更新组件。

您可以使用小组件构建器,在交互式界面中探索和创建小组件。

使用操作

通过操作,ChatKit 界面可以直接触发任务,无需发送用户消息。将 ActionConfig 附加到支持操作的小组件节点后,按钮、下拉选择框等控件便可以流式方式添加新的会话条目,或就地更新小组件。如果小组件位于 Form 中,ChatKit 会将收集到的表单值包含在操作载荷中。

在服务器端,请实现 action 方法,让 ChatKitServer 处理操作载荷,并根据需要以流式方式发送更多事件。您也可以在客户端处理操作:设置 handler="client",在 JavaScript 中响应操作,再将后续任务转发给服务器。

请参阅 GitHub 上的操作指南,了解如何串联操作、创建强类型载荷以及协调客户端与服务器端的处理函数。

资源

您可以使用以下资源和参考资料完成集成。

设计资源

事件参考

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 用于查找实体、处理点击和显示预览的回调函数。