Pažangi integracija į tavo programą
Šiame puslapyje
Pamoka perrašyta 2026 m. lapkričio 3 d. Ankstesnė versija rėmėsi išgalvotomis savybėmis ir įvykiais (
ChatProvider, „šoninės juostos“ režimas, naudotojo sąsajos pagrindu veikiantis išsaugojimas). Dabar ji atitinka Python SDKopenai-chatkit1.6.5 gaires (Prepare your app for production, Pass extra app context, Update the client during a response) ir@openai/chatkit-react1.6.1 tipus: serverio kodas buvo paleistas lokaliai, o React kodas patikrintas kompiliuojant. Šaltiniai: Prepare your app for production · Pass extra app context to your model · Update the client during a response · Advanced integrations with ChatKit.
Kas liko po demonstracinės versijos
Pirmosios keturios pamokos suteikė tau veikiantį asistentą. Kad jis veiktų realiame produkte, jam reikia to, kas skiria demonstraciją nuo paslaugos: žinoti, kas kalba, rodyti kiekvienam naudotojui tik jo pokalbius, sąveikauti su likusia programos dalimi ir būti stebimu. Šioje pamokoje nagrinėjami šie punktai po vieną.
Autentifikuo kiekvieną užklausą
SDK nedaro jokių prielaidų apie tavo autentifikavimą: jis leidžia tau patikrinti naudotoją, o tada perduoti jo tapatybę į server.process per užklausos kontekstą. Šis kontekstas lydi kiekvieną kvietimą: jį rasi respond, action, saugykloje (store) ir agento įrankiuose.
Sąsajos pusėje parinktis api.fetch pakeičia ChatKit naudojamą fetch funkciją. Čia pridėsi savo programos sesijos žetoną:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function ConnectedAssistant({ obtainToken }: { obtainToken: () => Promise<string> }) {
const { control } = useChatKit({
api: {
url: '/chatkit',
domainKey: 'local-dev',
fetch: async (input, init) => {
// Išsaugok ChatKit nustatytas antraštes, tada pridėk savąsias
const headers = new Headers(init?.headers);
headers.set('Authorization', `Bearer ${await obtainToken()}`);
return fetch(input, { ...init, headers });
},
},
});
return <ChatKit control={control} className="h-[600px] w-[360px]" />;
}
Serverio pusėje FastAPI priklausomybė patikrina žetoną ir sukuria kontekstą. Sąsajos kalba atkeliauja Accept-Language antraštėje, kurią ChatKit siunčia su kiekviena užklausa:
from dataclasses import dataclass
from chatkit.server import StreamingResult
from chatkit.store import NotFoundError
from fastapi import Depends, FastAPI, HTTPException, Request
from fastapi.responses import Response, StreamingResponse
@dataclass
class RequestContext:
user_id: str
locale: str
async def current_user(request: Request) -> str:
token = request.headers.get("authorization", "").removeprefix("Bearer ")
user_id = await verify_token(token) # tavo autentifikavimas: sesija, JWT...
if not user_id:
raise HTTPException(status_code=401, detail="Unauthenticated")
return user_id
app = FastAPI()
@app.post("/chatkit")
async def chatkit_endpoint(request: Request, user_id: str = Depends(current_user)) -> Response:
context = RequestContext(user_id=user_id, locale=request.headers.get("accept-language", "fr"))
try:
result = await server.process(await request.body(), context)
except NotFoundError:
raise HTTPException(status_code=404, detail="Not found")
if isinstance(result, StreamingResult):
return StreamingResponse(result, media_type="text/event-stream")
return Response(content=result.json, media_type="application/json")
Kiekvienas naudotojas gauna savo pokalbius
Autentifikavimo nepakanka: tau taip pat reikia autorizacijos. Be kontrolės, naudotojas, atspėjęs gijos ID, galėtų perskaityti kito asmens pokalbį. Tinkama vieta šiai kontrolei yra saugykla (store), per kurią eina visi skaitymai. Šiame pavyzdyje kiekviena gija savo metaduomenyse saugo savininko vardą, kurio SDK niekada neperduoda į sąsają:
from chatkit.store import NotFoundError
from chatkit.types import Page, ThreadMetadata
from memory_store import MemoryStore
class UserStore(MemoryStore):
async def save_thread(self, thread: ThreadMetadata, context: RequestContext) -> None:
thread.metadata.setdefault("owner", context.user_id)
await super().save_thread(thread, context)
async def load_thread(self, thread_id: str, context: RequestContext) -> ThreadMetadata:
thread = await super().load_thread(thread_id, context)
if thread.metadata.get("owner") != context.user_id:
raise NotFoundError(f"Thread {thread_id} not found") # neatskleisk, kad ji egzistuoja
return thread
async def load_threads(self, limit, after, order, context: RequestContext) -> Page[ThreadMetadata]:
page = await super().load_threads(limit, after, order, context)
page.data = [t for t in page.data if t.metadata.get("owner") == context.user_id]
return page
try blokas galiniame taške čia turi prasmę: be jo, tiesioginis kito naudotojo gijos skaitymas baigtųsi 500 klaida vietoj 404; srautinės užklausos atveju, pavyzdžiui, pridėjus žinutę, SDK nutraukia srautą nieko neišsiųsdamas. Gamyboje šis filtravimas vyksta pačioje SQL užklausoje (WHERE owner = … taip pat teisingai tvarko puslapiavimą). Taikyk tą pačią taisyklę priedams. Dokumentacija taip pat primena nuspręsti, ką saugai ir kiek laiko: gijose yra tekstas, failai ir įrankių rezultatai, todėl dažnai – asmens duomenys.
Suteik modeliui savo programos kontekstą
Modelis nieko nežino apie puslapį, kurį naudotojas žiūri, jo prenumeratą ar atidarytą dokumentą. Dokumentacija siūlo tris būdus jį to išmokyti:
- Kiekvienos užklausos metu, per antraštes, pridėtas
api.fetch(X-Page,X-Plan…), kurias serveris išsaugo kontekste; - Pagal poreikį, per serverio įrankį, kuris skaito
ctx.context.request_contextir gauna informaciją; - Naršyklėje, per kliento pusės įrankį, kai informacija egzistuoja tik ten (žr. kitą skyrių).
Viena atsargumo priemonė, paimta iš gamybos gairių: niekada nekurd modelio sistemos instrukcijų iš reikšmių, kurios ateina iš naudotojo, net ir netiesiogiai (gijos pavadinimas, bilieto tema). Laikyk jas fiksuotas, o kintamą kontekstą perduok kaip duomenis.
Kliento pusės įrankiai
Kai kuri informacija egzistuoja tik naršyklėje: pasirinkimas redaktoriuje, drobės būsena, neišsaugotas juodraštis. Kliento pusės įrankis leidžia modeliui jų paprašyti pokalbio eigoje: tavo serveris sustabdo agentą, ChatKit įvykdo tavo funkciją naršyklėje, tada grąžina rezultatą serveriui, kuris tęsia darbą.
Serverio pusėje įrankis tik pateikia užklausą, o agentas ties ja sustoja:
from agents import Agent, RunContextWrapper, StopAtTools, function_tool
from chatkit.agents import AgentContext, ClientToolCall
@function_tool(description_override="Reads the text the user has selected on the page.")
async def read_selection(ctx: RunContextWrapper[AgentContext]) -> None:
ctx.context.client_tool_call = ClientToolCall(name="read_selection", arguments={})
assistant = Agent[AgentContext](
name="Writing Assistant",
instructions="Help the user improve the text they select.",
model="gpt-6.1-sol",
tools=[read_selection],
tool_use_behavior=StopAtTools(stop_at_tool_names=[read_selection.name]),
)
Sąsajos pusėje onClientTool gauna užklausą; pavadinimas turi sutapti, o grąžintas objektas keliauja į serverį:
const { control } = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
onClientTool: async ({ name }) => {
if (name === 'read_selection') {
return { text: window.getSelection()?.toString() ?? '' };
}
return {};
},
});
Vienu pokalbio ėjimu gali būti vykdomas tik vienas kliento pusės įrankis. O kai nelauki atsakymo, geriau rinktis efektą: serveris išleidžia ClientEffectEvent(name="refresh_cart", data={...}) iš respond, action arba įrankio per ctx.context.stream(...), o sąsaja jį gauna onEffect nutraukdama atsakymo. Efektai nėra įrašomi į giją.
Valdyk ChatKit iš savo programos
useChatKit grąžina, be control, metodus, leidžiančius valdyti sąsają iš likusios tavo kodo dalies:
| Metodas | Poveikis |
|---|---|
sendUserMessage({ text }) | Siunčia žinutę taip, lyg naudotojas ją būtų įvedęs |
setComposerValue({ text }) | Iš anksto užpildo įvesties sritį nesiųsdamas |
setThreadId(id) | Atidaro esamą giją arba naują giją su null |
focusComposer() | Pastato žymeklį įvesties srityje |
showHistory(), hideHistory() | Atidaro arba užveria pokalbių istoriją |
sendCustomAction(action) | Siunčia veiksmą serveriui (20 pamoka) |
fetchUpdates() | Iš naujo įkelia giją iš serverio |
Mygtukas „Klausti asistento“ produkto lape tampa viena kodo eilute:
import { ChatKit, useChatKit } from '@openai/chatkit-react';
export function ProductSheet({ product }: { product: string }) {
const chatkit = useChatKit({ api: { url: '/chatkit', domainKey: 'local-dev' } });
return (
<>
<button onClick={() => chatkit.sendUserMessage({ text: `Is the ${product} product compatible with my equipment?` })}>
Ask the assistant
</button>
<ChatKit control={chatkit.control} className="h-[500px] w-[360px]" />
</>
);
}
Parinktis initialThread paleidimo metu atidaro konkrečią giją, pavyzdžiui, tą, kurią naudotojas paliko atidarytą; su null (numatytoji reikšmė) ChatKit rodo pagrindinį ekraną.
Stebėk, kas vyksta
ChatKit skleidžia įvykius: paruoštumas (onReady), atsakymo pradžia ir pabaiga (onResponseStart, onResponseEnd), gijos keitimas (onThreadChange), žurnalai (onLog) ir klaidos (onError). React’e tai yra useChatKit parinktys:
const { control } = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
onThreadChange: ({ threadId }) => rememberLastThread(threadId),
onError: ({ error }) => sendTelemetry({ name: 'chatkit.error', message: error.message }),
onLog: ({ name }) => sendTelemetry({ name: name }),
});
Gamybos gairėse pabrėžiamas vienas dalykas: šiuose įvykiuose gali būti asmens duomenų ir žinučių teksto. Nesiųsk viso turinio į savo stebėjimo įrankį: ištrauk tik naudingus laukus (įvykio pavadinimą, gijos ID, klaidos kodą). Serverio pusėje registruok kiekvieną užklausą į /chatkit, kvietimus į saugyklą ir modelį bei įrankių klaidas, nurodydamas naudotojo ir gijos ID, kad galėtum susieti abi puses.
Lėtiems įrankiams informuok naudotoją: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) rodo momentinę pažangą, kurią vėliau pakeičia likusi atsakymo dalis ir kuri niekada neįrašoma į giją.
Prieš einant į gamybą
Kontrolinis sąrašas, paimtas iš oficialių gairių:
- Domenai: kiekvienas gamybos prieglobos vardas yra įtrauktas į OpenAI platformos puslapį Domain allowlist, o jo raktas yra
domainKey; - Autentifikavimas ir autorizacija: kiekviena užklausa į
/chatkityra autentifuojama, gijos ir priedai filtruojami pagal naudotoją; - Paslaptys: API raktas ir vidiniai prisijungimo duomenys yra aplinkos kintamuosiuose arba paslapčių valdytojuje, niekada ne saugykloje;
- Įvestys: žinutės, failai, veiksmų naudingieji krūviai ir įrankių rezultatai traktuojami kaip nepatikimi ir patikrinami prieš pasiekiant tavo sistemas;
- Asmens duomenys: saugojimo laikotarpis nuspręstas ir taikomas saugykloje, šifravimas ramybės būsenoje, jokių nereikalingų duomenų metaduomenyse;
- Kalba:
Accept-Languagekalba valdo agento atsakymus ir tavo įrankių žinutes; - Stebėjimas: renkami sąsajos įvykiai ir serverio žurnalai, be jautraus turinio.
Svarbiausi punktai
- Naudotojo tapatybė perduodama per
api.fetchsąsajos pusėje, tada perserver.processkontekstą, kuris ją paskleidžia visur - Autorizacija vyksta saugykloje: kiekviena gija priklauso naudotojui, o kito naudotojo gija yra „nerasta“
- Programos kontekstas atkeliauja per antraštes, serverio įrankius arba kliento pusės įrankius (
onClientTool+StopAtTools); efektai (onEffect) naudojami, kai atsakymo nesitikima - Metodai iš
useChatKit(sendUserMessage,setThreadId,setComposerValue…) valdo ChatKit iš likusios programos dalies - Įvykiai (
onError,onLog…) maitina tavo stebėjimą, nekopijuojant į jį asmens duomenų; gamybos kontrolinis sąrašas apima domenus, teises, paslaptis, įvestis ir duomenis