ChatKit: Ülevaade ja paigaldamine
Sellel lehel
Õppetund kirjutati ümber 3. novembril 2026. Eelmine versioon kirjeldas API-t, mida enam ei eksisteeri: objekti
new ChatKit({ apiKey, agentId }), komponenteChatProvider,ChatWindowjaMessageInput, moodulit@openai/chatkit/reactning skripticdn.openai.com/chatkit/…. See õppetund järgib nüüd ametlikke OpenAI ChatKiti juhendeid, Pythoni SDK-dopenai-chatkit1.6.5 ja@openai/chatkit-react1.6.1. Käivitasime näiteserveri lokaalselt, et iga sammu kontrollida. Märkus: Agent Builder suletakse 30. novembril 2026; ChatKit jääb kasutatavaks. Allikad: ChatKit · Täiustatud integratsioonid ChatKitiga · Pythoni SDK kiirjuhend · Ametlik algusprojekt.
Miks ChatKit
Oled loonud agendi Agents SDK-ga. See töötab sinu terminalis ja keegi teine ei saa seda kasutada. Et viia see kasutajateni, vajad vestlusliidest – hea vestluskasutajaliidese nullist ehitamine on aga kallis. Pead tegelema kerimise, sõnumite voogedastuse, vestluse taastamise, manuste, tööriistakutsete kuvamise ja võrguvigade käsitlemisega.
ChatKit on OpenAI vastus: vestluskomponent, mille saad oma tootesse põimida ja mis haldab kogu kasutajakogemust. Dokumentatsioon toob eselle interaktiivsed vidinad, algussoovitused, tööriistakutsete kuvamise, manused ja agendi arutluskäigu visualiseerimise. Sina säilitad kontrolli selle üle, mis loeb: agent, sinu andmed ja sinu reeglid.
Kaks viisi selle käivitamiseks
ChatKit on vaid liides. See vajab serverit, mis võtab vastu sõnumeid, käivitab agendi ja edastab vastuse voona tagasi. OpenAI kirjeldab kahte lähenemist:
| Tee | Kuidas see töötab | Kellele see on mõeldud |
|---|---|---|
| Sinu enda ChatKiti server (täiustatud integratsioon) | Sinu Pythoni server, kasutades SDK-d openai-chatkit, võtab liideselt vastu päringuid ja käivitab sinu valitud agendi, näiteks Agents SDK agendi | Iga uus projekt: see on tee, mida OpenAI soovitab |
| Majutatud Agent Builderi töövoog | OpenAI käitab Agent Builderis loodud töövoogu; sinu server loob vaid seansse | Olemasolevad integratsioonid üleminekuperioodil: Agent Builder suletakse 30. novembril 2026 |
See kursus järgib esimest teed – ainukest, millel on tulevikku. Võtame teise kokku õppetunni lõpus nende jaoks, kes peavad olemasolevat integratsiooni hooldama kuni sulgemiseni.
Kolmeosaline arhitektuur
ChatKiti integratsioon taandub kolmele elemendile. Nende eristamine hoiab ära enamiku algajate vigadest:
- ChatKit.js, komponent ise: veebikomponent
<openai-chatkit>, mis kuvab vestlust iframe’is. See laaditakse OpenAI CDN-ist (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), mitte npm-ist: npm-i pakett@openai/chatkitsisaldab ainult selle tüübimääratlusi. - Reacti sidemed,
@openai/chatkit-react, mis teevad kättesaadavaks komponendiChatKitja konksuuseChatKit. Need on valikulised: ilma Reactita juhite veebikomponenti otse. - Sinu ChatKiti server, üks HTTP-lõpp-punkt, tavapäraselt
/chatkit, mis võtab vastu kõik liideselt tulevad päringud.ChatKitServeri eksemplar suunab need, kasutab salvestust (store) vestlusteemade püsimajäämiseks ja käivitab sinu agendi.
OpenAI API võti ei lahku kunagi serverit: liides suhtleb ainult sinu lõpp-punktiga /chatkit.
Paigaldamine
Liidese poolel paigalda Reacti sidemed ja laadi ChatKiti skript oma lehele:
npm install @openai/chatkit-react
<!-- Lehe <head>-osas -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
Serveri poolel paigalda ChatKiti Pythoni SDK (Python 3.10 või uuem), mis toob kaasa Agents SDK, koos veebiserveriga:
pip install openai-chatkit fastapi uvicorn
Minimaalne server
Allpool olev server järgib ametlikku kiirjuhendit. ChatKitServer nõuab ainult ühte meetodit, respond, mida kutsutakse iga kasutaja sõnumi jaoks. See laadib viimased teema üksused, teisendab need agendi sisendiks funktsiooniga simple_to_agent_input, käivitab agendi voorežiimis ja tõlgib selle voo ChatKiti sündmusteks funktsiooniga stream_agent_response:
# main.py
from typing import Any, AsyncIterator
from agents import Agent, Runner
from chatkit.agents import AgentContext, simple_to_agent_input, stream_agent_response
from chatkit.server import ChatKitServer, StreamingResult
from chatkit.types import ThreadMetadata, ThreadStreamEvent, UserMessageItem
from fastapi import FastAPI, Request
from fastapi.responses import Response, StreamingResponse
from memory_store import MemoryStore # mälus salvestus algusprojektist
assistant = Agent[AgentContext[dict[str, Any]]](
name="Product Assistant",
instructions="You help product users. Respond in English, briefly.",
model="gpt-6.1-sol",
)
class MyChatKitServer(ChatKitServer[dict[str, Any]]):
async def respond(
self,
thread: ThreadMetadata,
input_user_message: UserMessageItem | None,
context: dict[str, Any],
) -> AsyncIterator[ThreadStreamEvent]:
# Viimased 30 teema üksust, taastatud kronoloogilises järjekorras
page = await self.store.load_thread_items(
thread.id, after=None, limit=30, order="desc", context=context
)
agent_input = await simple_to_agent_input(list(reversed(page.data)))
agent_context = AgentContext(thread=thread, store=self.store, request_context=context)
result = Runner.run_streamed(assistant, agent_input, context=agent_context)
async for event in stream_agent_response(agent_context, result):
yield event
app = FastAPI()
server = MyChatKitServer(MemoryStore())
@app.post("/chatkit")
async def chatkit_endpoint(request: Request) -> Response:
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")
Käivita see keskkonnamuutujaga OPENAI_API_KEY: uvicorn main:app --port 8000.
Salvestus (store) väärib kahte sõna. ChatKit ei salvesta ise midagi: teemad, sõnumid, vidinad ja tööriistakutsed salvestab klass, mis pärineb chatkit.store.Store-ist ja rakendab umbes tosinat meetodit (load_thread, save_thread, load_thread_items, add_thread_item…). Alustamiseks kasuta uuesti ametlikust algusprojektist faili memory_store.py: see hoiab kõike mälus seni, kuni protsess töötab. Tootmises asenda see andmebaasiga. Dokumentatsioon soovitab objekte salvestada JSON-ina, et SDK värskendused ei sunniks sind skeemi migratsioone tegema.
Reacti liides
Liidese poolel saab useChatKit konfiguratsiooni ja tagastab objekti control, mille annad komponendile ChatKit:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// Arenduses piisab kohahoidja väärtusest; tootmises
// kasuta oma domeenivõtit (vt allpool)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Serveeri liides ja /chatkit samalt päritolult: arenduses haldab seda sinu ehitustööriista proksi (algusprojekt konfigureerib Vite’i proksi suunama /chatkit pordile 8000). Kui server asub teisel päritolul, luba see sõnaselgelt, näiteks FastAPI CORSMiddleware-iga.
Ilma Reactita
WordPressi sait, Railsi rakendus või staatiline leht saavad integreerida sama assistendi: veebikomponent töötab otse, kui CDN-i skript on laaditud.
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
</head>
<body>
<div id="chat-root" style="height: 600px"></div>
<script>
const chatkit = document.createElement('openai-chatkit');
chatkit.setOptions({
api: { url: '/chatkit', domainKey: 'local-dev' },
});
document.getElementById('chat-root').append(chatkit);
</script>
</body>
</html>
Igal valikul, mida näed järgmistes õppetundides, on mõlemal juhul sama kuju: objekt, mis antakse Reactis useChatKit-ile või veebikomponendil setOptions-ile.
Turvalisus esimesest päevast
Kolm reeglit, mis on tuletatud ChatKiti tootmisjuhendist, kehtivad juba prototüübi staadiumist:
- API võti jääb serverisse. See ei tohi ilmuda liidesekoodi ega sinu hoidlasse: loe see keskkonnamuutujast või saladuste haldurist.
- Autendi iga päring lõpp-punkti
/chatkit. SDK seda ei haldi: sinu rakendus peab kontrollima kasutaja seanssi või tokenit ja edastama seejärel tema identiteediserver.process-ile kontekstis (õppetund 21). Ilma selleta saab igaüks käivitada sinu agenti sinu kulul. - Registreeri oma domeenid. Enne live’i minekut deklareeri iga hostinimi, mis kuvab ChatKiti, OpenAI platvormi lehel Domeenide lubatud loend ja kopeeri genereeritud võti
domainKey-sse. Laadimisel kontrollib ChatKiti iframe seda võtit OpenAI-ga ja keeldub kuvamast, kui see puudub või ei klapi.
Kui sul on juba Agent Builderi töövoog
Olemasolevad integratsioonid, mis on seotud majutatud töövooga, töötavad kuni Agent Builderi sulgemiseni. Nende printsiip erineb: sinu server loob ChatKiti seansi, kutudes POST https://api.openai.com/v1/chatkit/sessions, päise OpenAI-Beta: chatkit_beta=v1, töövoog ID ja iga autenditud kasutaja jaoks unikaalse user identifikaatoriga. Seejärel tagastab saadud client_secret liidesesse. Liidese poolel võtab api valik siis vastu funktsiooni getClientSecret URL-i asemel.
Ära alusta uut projekti selle mudeli põhjal. Olemasoleva integratsiooni puhul ekspordi töövoog Agents SDK koodiks ja lülitu oma ChatKiti serverile enne 30. novembrit 2026, järgides juhendit Migreeru Agent Builderist.
Peamised punktid
- ChatKit on valmis integreeritav vestlusliides; sinu server käivitab agendi
- Iga uue projekti jaoks: sinu enda ChatKiti server (
pip install openai-chatkit), meetodigarespondja lõpp-punktiga/chatkit; majutatud Agent Builder suletakse 30. novembril 2026 - Liides laaditakse OpenAI CDN-ist; Reactis kasuta
useChatKitja<ChatKit control={control} />paketist@openai/chatkit-react - Salvestus (store) hoiab vestlusteemasid: testimiseks mälus, tootmises andmebaasis
- API võti ainult serveripoolselt, autenditud
/chatkit, registreeritud domeeniddomainKeysaamiseks