ChatKit: Pregled in namestitev
Na tej strani
Lekcija na novo napisana 3. novembra 2026. Prejšnja različica je opisovala API, ki ne obstaja več: objekt
new ChatKit({ apiKey, agentId }), komponentiChatProviderinChatWindow, komponentoMessageInput, modul@openai/chatkit/reactter skriptcdn.openai.com/chatkit/…. Ta lekcija zdaj sledi uradnim vodnikom za OpenAI ChatKit, Python SDKopenai-chatkit1.6.5 in@openai/chatkit-react1.6.1. Primer strežnika smo zagnali lokalno, da smo preverili vsak korak. Opomba: Agent Builder se izklopi 30. novembra 2026; ChatKit ostane na voljo. Viri: ChatKit · Napredne integracije s ChatKit · Hitri začetek za Python SDK · Uradna začetna aplikacija.
Zakaj ChatKit
Zgradil si agenta z Agents SDK. Teče v tvojem terminalu in nihče drug ga ne more uporabljati. Da bi ga dal v roke svojim uporabnikom, potrebuješ vmesnik za pogovor – gradnja dobrega uporabniškega vmesnika za klepet od nič pa je draga. Obdelati moraš drsenje, pretakanje sporočil, nadaljevanje pogovora, priloge, prikaz klicev orodij in obravnavo napak v omrežju.
ChatKit je odgovor OpenAI: komponenta za pogovor, ki jo vgradiš v svoj izdelek in ki poskrbi za celotno uporabniško izkušnjo. Dokumentacija poudarja interaktivne gradnike, predloge za začetek, prikaz klicev orodij, priloge in vizualizacijo razmišljanja agenta. Ti obdržiš nadzor nad tistim, kar je pomembno: agentom, svojimi podatki in svojimi pravili.
Dva načina napajanja
ChatKit je le vmesnik. Potrebuje strežnik, ki prejme sporočila, zažene agenta in vrne odgovor nazaj v toku. OpenAI opisuje dva pristopa:
| Pot | Kako deluje | Za koga je |
|---|---|---|
| Tvoj lastni strežnik ChatKit (napredna integracija) | Tvoj Python strežnik z uporabo SDK openai-chatkit prejme zahteve iz uporabniškega vmesnika in zažene agenta po tvoji izbiri, na primer agenta Agents SDK | Vsak nov projekt: to je pot, ki jo OpenAI priporoča |
| Potek dela v gostovanem Agent Builderju | OpenAI izvaja potek dela, zasnovan v Agent Builderju; tvoj strežnik le ustvarja seje | Obstoječe integracije v prehodnem obdobju: Agent Builder se izklopi 30. novembra 2026 |
Ta tečaj sledi prvi poti – edini, ki ima prihodnost. Drugo povzamemo na koncu lekcije za tiste, ki morajo do izklopa vzdrževati obstoječo integracijo.
Arhitektura iz treh delov
Integracija ChatKit se zreducira na tri elemente. Razlikovanje med njimi prepreči večino napak začetnikov:
- ChatKit.js, sama komponenta: spletna komponenta
<openai-chatkit>, ki prikaže pogovor v iframeu. Naloži se z OpenAI-jevega CDN-ja (https://cdn.platform.openai.com/deployments/chatkit/chatkit.js), ne iz npm: paket npm@openai/chatkitvsebuje le njegove definicije tipov. - Povezave za React,
@openai/chatkit-react, ki izpostavljata komponentoChatKitin hookuseChatKit. To je opcijsko: brez Reacta spletno komponento nadzoruješ neposredno. - Tvoj strežnik ChatKit, ena sama končna točka HTTP, običajno
/chatkit, ki prejme vse zahteve iz vmesnika. InstancaChatKitServerjih usmerja, se zanaša na shrambo (store) za trajno shranjevanje niti pogovora in zažene tvojega agenta.
Ključ API za OpenAI nikoli ne zapusti strežnika: vmesnik komunicira le s tvojo končno točko /chatkit.
Namestitev
Na strani vmesnika namesti povezave za React in naloži skript ChatKit na svojo stran:
npm install @openai/chatkit-react
<!-- V <head> svoje strani -->
<script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
Na strani strežnika namesti Python SDK za ChatKit (Python 3.10 ali novejši), ki vključuje Agents SDK, ter spletni strežnik:
pip install openai-chatkit fastapi uvicorn
Minimalni strežnik
Spodnji strežnik sledi uradnemu hitremu začetku. ChatKitServer zahteva le eno metodo, respond, ki se pokliče za vsako uporabniško sporočilo. Ponovno naloži zadnje elemente niti, jih pretvori v vhod za agenta z simple_to_agent_input, zažene agenta v načinu pretoka in ta pretok prevede v dogodke ChatKit z 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 # shramba v pomnilniku iz začetne aplikacije
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]:
# Zadnjih 30 elementov niti, obnovljenih v kronološkem vrstnem redu
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")
Zaženi ga z OPENAI_API_KEY v svojem okolju: uvicorn main:app --port 8000.
Shramba (store) zasluži dve besedi. ChatKit sam ne shrani ničesar: niti, sporočila, gradnike in klice orodij trajno shrani razred, ki deduje od chatkit.store.Store in implementira približno ducat metod (load_thread, save_thread, load_thread_items, add_thread_item…). Za začetek ponovno uporabi datoteko memory_store.py iz uradne začetne aplikacije: vse ohrani v pomnilniku, dokler proces teče. V proizvodnji jo zamenjaj z bazo podatkov. Dokumentacija priporoča shranjevanje objektov kot JSON, da posodobitve SDK ne bodo vsiljevale selitev sheme.
Vmesnik React
Na strani vmesnika useChatKit prejme konfiguracijo in vrne objekt control, ki ga posreduješ komponenti ChatKit:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function Assistant() {
const { control } = useChatKit({
api: {
url: '/chatkit',
// V razvojnem okolju je dovolj nadomestna vrednost; v proizvodnji
// uporabi svoj ključ domene (glej spodaj)
domainKey: 'local-dev',
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Vmesnik in /chatkit streži z istega izvora: v razvojnem okolju to opravi proxy tvojega orodja za gradnjo (začetna aplikacija konfigurira Viteov proxy za preusmeritev /chatkit na vrata 8000). Če strežnik deluje na drugem izvoru, ga izrecno dovoli, na primer s CORSMiddleware v FastAPI.
Brez Reacta
Spletno mesto WordPress, aplikacija Rails ali statična stran lahko integrirata istega asistenta: spletna komponenta deluje neposredno, ko se skript CDN naloži.
<!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>
Vsaka možnost, ki jo boš videl v naslednjih lekcijah, ima v obeh primerih enako obliko: objekt, posredovan funkciji useChatKit v Reactu ali metodi setOptions na spletni komponenti.
Varnost od prvega dne
Tri pravila, povzeta po vodniku za proizvodnjo ChatKit, veljajo že od faze prototipa:
- Ključ API ostane na strežniku. Ne sme se pojaviti v kodi vmesnika ali v tvojem repozitoriju: preberi ga iz spremenljivke okolja ali upravitelja skrivnosti.
- Avtenticiraj vsako zahtevo za
/chatkit. SDK tega ne obravnava: tvoja aplikacija mora preveriti sejo ali žeton uporabnika, nato pa njegovo identiteto posredovati funkcijiserver.processv kontekstu (lekcija 21). Brez tega lahko kdorkoli zažene tvojega agenta na tvoje stroške. - Registriraj svoje domene. Preden greš v produkcijo, na strani Seznam dovoljenih domen na platformi OpenAI deklariraj vsako gostiteljsko ime, ki bo prikazovalo ChatKit, in kopiraj generirani ključ v
domainKey. Ob nalaganju iframe ChatKit preveri ta ključ pri OpenAI in zavrne prikaz, če manjka ali se ne ujema.
Če že imaš potek dela v Agent Builderju
Obstoječe integracije, povezane z gostovanim potekom dela, delujejo do izklopa Agent Builderja. Njihovo načelo je drugačno: tvoj strežnik ustvari sejo ChatKit s klicem POST https://api.openai.com/v1/chatkit/sessions, z glavo OpenAI-Beta: chatkit_beta=v1, ID-jem poteka dela in identifikatorjem user, ki je edinstven za vsakega avtenticiranega uporabnika. Nato vrne pridobljeni client_secret vmesniku. Na strani vmesnika možnost api nato namesto URL-ja prevzame funkcijo getClientSecret.
Ne začni novega projekta s tem modelom. Za obstoječo integracijo izvozi potek dela v kodo Agents SDK in preklopi na svoj lastni strežnik ChatKit pred 30. novembrom 2026, tako da slediš vodniku Selitev iz Agent Builderja.
Ključne ugotovitve
- ChatKit je vmesnik za pogovor, pripravljen za integracijo; tvoj strežnik poganja agenta
- Za vsak nov projekt: tvoj lastni strežnik ChatKit (
pip install openai-chatkit) z metodorespondin končno točko/chatkit; gostovani Agent Builder se izklopi 30. novembra 2026 - Vmesnik se naloži z OpenAI-jevega CDN-ja; v Reactu uporabi
useChatKitin<ChatKit control={control} />iz@openai/chatkit-react - Shramba trajno hrani niti pogovora: v pomnilniku za testiranje, v bazi podatkov za proizvodnjo
- Ključ API samo na strani strežnika, avtenticirana
/chatkit, registrirane domene za pridobitevdomainKey