如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

ChatKit

使用 ChatKit 建立並自訂可嵌入的對話介面。

ChatKit 是打造智慧體對話體驗的最佳方式。無論你要開發內部知識庫助理、協助新人到職的人資助理、研究夥伴、購物或排程助理、疑難排解機器人、財務規劃顧問或客服智慧體,ChatKit 都提供可自訂的嵌入式對話介面,替你處理使用者體驗的各項細節。

ChatKit 提供可嵌入的介面小工具和可自訂的提示詞,並支援工具呼叫、檔案附件和思路鏈視覺化,讓你建立智慧體時無須從頭開發對話介面。

概覽

ChatKit 有兩種整合方式:

  • 整合自有伺服器。在自己的基礎架構上執行 ChatKit。使用 ChatKit Python SDK 連接任何智慧體服務,包括使用 Agents SDK 建立的服務,再以小工具建構前端。
  • 沿用 Agent Builder 代管的工作流程。如果你已將 ChatKit 與 Agent Builder 工作流程整合,可以在 Agent Builder 過渡期間繼續使用該代管工作流程。

OpenAI 正逐步棄用 Agent Builder。現有使用者可在過渡期間繼續使用 Agent Builder,該產品預定於 2026 年 11 月 30 日停止服務。ChatKit 仍可使用。如果你要開發新專案或規劃遷移,請使用 ChatKit 進階整合連接你在伺服器端實作的智慧體,並參閱從 Agent Builder 遷移,瞭解過渡期間的做法。

開始使用 ChatKit

將 ChatKit 嵌入前端

只有在現有的 ChatKit 實作已使用 Agent Builder 工作流程時,才採用這種方式。如果你要開發新的 ChatKit 應用程式,或要在 Agent Builder 停止服務前遷移,請使用進階整合,將 ChatKit 連接到你在伺服器端實作的智慧體。

將 ChatKit 與現有的代管工作流程整合分為三個步驟。先趁 Agent Builder 仍可使用時開啟現有的工作流程,再設定 ChatKit,最後新增功能,打造你的對話體驗。


由 OpenAI 代管的
ChatKit

1. 使用現有的代管工作流程

在 Agent Builder 中開啟現有的工作流程,即可取得工作流程 ID。如需規劃遷移,請參閱從 Agent Builder 遷移。

嵌入前端的對話介面會連接到你選取的工作流程。

2. 在產品中設定 ChatKit

設定 ChatKit 時,你需要建立 ChatKit 工作階段和伺服器端點、傳入工作流程 ID、交換用戶端密鑰,並新增指令碼,將 ChatKit 嵌入網站。

重要安全事項: 建立 ChatKit 工作階段時,必須傳入 user 參數,而且每位終端使用者的參數值都應不同。伺服器必須驗證應用程式使用者的身分,並透過此參數傳入該使用者的唯一識別碼。

  1. 在伺服器上產生用戶端權杖。

    下列範例會啟動一項服務,透過 OpenAI API 建立 ChatKit 工作階段,並傳回該工作階段的用戶端密鑰:

    # Replace the illustrative IDs and URLs below with your own resource values.
    import hmac
    import json
    import os
    from typing import Annotated
    
    import requests
    from fastapi import Depends, FastAPI, HTTPException
    from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
    from pydantic import BaseModel
    
    
    api_key = os.environ["OPENAI_API_KEY"]
    workflow_id = "wf_123"
    authenticated_users: dict[str, str] = json.loads(
        os.environ["CHATKIT_AUTHENTICATED_USERS"]
    )
    bearer_auth = HTTPBearer(auto_error=False)
    
    
    def get_authenticated_user_id(
        credentials: Annotated[
            HTTPAuthorizationCredentials | None,
            Depends(bearer_auth),
        ],
    ) -> str:
        if credentials is not None:
            for token, user_id in authenticated_users.items():
                if hmac.compare_digest(credentials.credentials, token):
                    return user_id
        raise HTTPException(status_code=401, detail="Invalid authentication token")
    
    
    class ChatKitSession(BaseModel):
        client_secret: str
    
    
    app = FastAPI()
    
    
    @app.post("/api/chatkit/session")
    def create_chatkit_session(
        user_id: Annotated[str, Depends(get_authenticated_user_id)],
    ):
        response = requests.post(
            "https://api.openai.com/v1/chatkit/sessions",
            headers={
                "Authorization": f"Bearer {api_key}",
                "Content-Type": "application/json",
                "OpenAI-Beta": "chatkit_beta=v1",
            },
            json={
                "workflow": {"id": workflow_id},
                "user": user_id,
            },
            timeout=30,
        )
        response.raise_for_status()
        session = ChatKitSession.model_validate(response.json())
        return {"client_secret": session.client_secret}

    如果使用 Ruby,請執行 gem install webrick 安裝 WEBrick。

    啟動服務前,請將 wf_123 替換為你的工作流程 ID,並設定 OPENAI_API_KEY 和 CHATKIT_AUTHENTICATED_USERS。後者的值是一份 JSON 對照表,將應用程式的 Bearer 權杖對應到固定的使用者 ID。在正式環境中,請改用應用程式的身分驗證或工作階段查詢機制,取代存放在環境變數中的對照表。

  2. 在伺服器端程式碼中,將工作流程 ID 和密鑰傳入工作階段端點。

    ChatKit 前端會以用戶端密鑰作為憑證,開啟或更新對話工作階段。取得密鑰後,請立即交給 ChatKit 用戶端程式庫,不要儲存。

    請參閱 GitHub 上的 chatkit-js 程式碼庫。

    如果使用 Go,請執行 go get github.com/openai/openai-go/v3@v3.70.0。如果使用 Java,請新增 Maven 相依套件 com.openai:openai-java:4.75.1。

    建立 ChatKit 工作階段權杖
    export default async function getChatKitSessionToken(deviceId: string) {
      const apiKey = process.env.OPENAI_API_KEY;
      if (!apiKey) {
        throw new Error("OPENAI_API_KEY is required");
      }
    
      const response = await fetch("https://api.openai.com/v1/chatkit/sessions", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "OpenAI-Beta": "chatkit_beta=v1",
          Authorization: `Bearer ${apiKey}`,
        },
        body: JSON.stringify({
          workflow: { id: "wf_68df4b13b3588190a09d19288d4610ec0df388c3983f58d1" },
          user: deviceId,
        }),
      });
    
      if (!response.ok) {
        throw new Error(
          `Failed to create a ChatKit session: ${response.status} ${await response.text()}`
        );
      }
    
      const { client_secret } = await response.json();
    
      if (!client_secret) {
        throw new Error("ChatKit session response did not include client_secret");
      }
    
      return client_secret;
    }
  3. 在專案目錄中安裝 ChatKit 的 React 繫結套件:

    npm install @openai/chatkit-react
  4. 將 ChatKit JS 指令碼加入網頁。將下列程式碼片段放入網頁的 <head> 或其他載入指令碼的位置,瀏覽器就會擷取並執行 ChatKit。

    index.html
    <script
    src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"
    async
    ></script>
  5. 在使用者介面中呈現 ChatKit。請將一個函式傳給 React MyChat 元件,此函式名為 getAppAuthToken,會傳回目前使用者的 Bearer 權杖。如果使用 TypeScript 分頁中的範例,請確保程式碼片段可在其作用域內存取同一個函式。這段程式碼會將憑證傳送到你的伺服器、取得用戶端密鑰,並掛載已連接到你所選工作流程的即時對話小工具。

    你的前端程式碼
    import { ChatKit, useChatKit } from '@openai/chatkit-react';
    
       export function MyChat({ getAppAuthToken }) {
         const { control } = useChatKit({
           api: {
             async getClientSecret(existing) {
               if (existing) {
                 // implement session refresh
                }
    
               const appAuthToken = await getAppAuthToken();
               const res = await fetch('/api/chatkit/session', {
                 method: 'POST',
                 headers: {
                   'Authorization': 'Bearer ' + appAuthToken,
                   'Content-Type': 'application/json',
                 },
               });
               const { client_secret } = await res.json();
               return client_secret;
             },
           },
         });
    
         return <ChatKit control={control} className="h-[600px] w-[320px]" />;
       }

3. 開發並持續改進

請參閱自訂佈景主題、小工具和動作文件,進一步瞭解 ChatKit 的運作方式。你也可以利用下列資源測試對話、反覆調整提示詞,以及新增小工具和工具。

開發你的 ChatKit 應用程式

GitHub 上的 ChatKit 文件

瞭解如何處理身分驗證、套用佈景主題及自訂介面等。

ChatKit Python SDK

新增伺服器端儲存、存取控制、工具及其他後端功能。

ChatKit JS SDK

瀏覽 ChatKit JS 程式碼庫。

探索 ChatKit 使用者介面

chatkit.world

試用 ChatKit 的互動示範。

小工具建構器

瀏覽可用的小工具。

ChatKit Playground

透過互動示範動手練習。

查看可執行的範例

GitHub 上的範例

查看可執行的 ChatKit 範例,從中獲得靈感。

入門應用程式的程式碼庫

複製程式碼庫,即可從功能完整且可直接執行的範本開始開發。

後續步驟

當 ChatKit 實作符合你的需求後,可以進一步瞭解如何透過評估來最佳化實作。如果你要開發新的 ChatKit 應用程式,或將現有的 ChatKit 應用程式遷出 Agent Builder 代管的工作流程,請參閱進階整合文件。