Täiustatud integreerimine rakendusse
Sellel lehel
Õppetund kirjutati ümber 3. novembril 2026. Eelmine versioon tugines väljamõeldud omadustele ja sündmustele (
ChatProvider, „külgriba“ režiim, kasutajaliidese-põhine püsivus). Nüüd järgib see Pythoni SDKopenai-chatkit1.6.5 juhiseid (Valmista oma rakendus tootmiseks ette, Edasta täiendavat rakenduse konteksti, Uuenda klienti vastuse ajal) ja@openai/chatkit-react1.6.1 tüüpe: serverikood on lokaalselt käivitatud ja Reacti kood on kompileerimisega kontrollitud. Allikad: Valmista oma rakendus tootmiseks ette · Edasta mudelile täiendavat rakenduse konteksti · Uuenda klienti vastuse ajal · Täiustatud integratsioonid ChatKitiga.
Mis jääb pärast demo-versiooni
Eelmised neli õppetundi andsid sulle toimiva assistendi. Et see reaalses tootes elaks, vajab see kõike, mis eristab demo-versiooni teenusest: teadmine, kes räägib, iga kasutaja jaoks ainult tema vestluste näitamine, suhtlemine ülejäänud rakendusega ja jälgitavus. See õppetund käsitleb neid punkte ükshaaval.
Autendi iga päringut
SDK ei tee eeldusi sinu autentimise kohta: see võimaldab sul kasutaja üle kontrollida ja seejärel edastada tema identiteedi funktsioonile server.process päringu kontekstis. See kontekst saadab kaasa iga väljakutse: leiad selle kohast respond, action, salvestusruumist (store) ja agendi tööriistadest.
Kasutajaliidese poolel asendab valik api.fetch ChatKiti kasutatava funktsiooni fetch. Siia lisad oma rakenduse seansitokeni:
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) => {
// Säilita ChatKiti määratud päised, seejärel lisa omad
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]" />;
}
Serveri poolel kontrollib FastAPI sõltuvus tokenit ja loob konteksti. Kasutajaliidese keel saabub päises Accept-Language, mille ChatKit saadab iga päringuga:
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) # sinu autentimine: seanss, 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")
Iga kasutaja saab oma vestlused
Autentimisest ei piisa: vajad ka autoriseerimist. Ilma kontrollita võiks kasutaja, kes arvab ära lõime ID, lugeda kellegi teise vestlust. Õige koht selleks kontrolliks on salvestusruum (store), mille kaudu kõik lugemised läbivad. Selles näites hoiab iga lõim oma omaniku nime metaandmetes, mida SDK kunagi kasutajaliidesesse ei edasta:
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") # ära paljasta, et see eksisteerib
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
Lõpp-punkti try plokk on siin mõttekas: ilma selleta lõpeks teise kasutaja lõime otsene lugemine veaga 500, mitte 404; voogedastusega päringu korral, nagu sõnumi lisamine, katkestab SDK voo ilma midagi saatmata. Tootmises toimub see filtreerimine otse SQL-päringus (kus WHERE owner = … käsitleb õigesti ka leheküljestamist). Rakenda sama reeglit manuste kohta. Dokumentatsioon tuletab meelde, et pead otsustama, mida sa säilitad ja kui kaua: lõimed sisaldavad teksti, faile ja tööriistade tulemusi, seega sageli isikuandmeid.
Anna mudelile oma rakenduse kontekst
Mudel ei tea midagi lehest, mida kasutaja vaatleb, tema tellimusest ega avatud dokumendist. Dokumentatsioon pakub kolm viisi, kuidas seda õpetada:
- Iga päringu korral, lisades päiseid
api.fetchkaudu (X-Page,X-Plan…), mille server salvestab konteksti; - Vajadusel, serveri tööriista kaudu, mis loeb
ctx.context.request_contextja toob info kätte; - Brauseris, kliendipoolse tööriista kaudu, kui info eksisteerib ainult seal (vaata järgmist lõiku).
Üks ettevaatusabinõu, mis on võetud tootmisjuhendist: ära kunagi ehita mudeli süsteemijuhiseid väärtustest, mis tulevad kasutajalt, isegi kaudselt (lõime pealkiri, piletiteema). Hoia need fikseerituna ja edasta muutuv kontekst andmetena.
Kliendipoolsed tööriistad
Mõni info eksisteerib ainult brauseris: valik redaktoris, lõuendi olek, salvestamata mustand. Kliendipoolne tööriist võimaldab mudelil neid keset vooru küsida: sinu server peatab agendi, ChatKit käivitab sinu funktsiooni brauseris ja tagastab tulemuse serverile, mis jätkab tööd.
Serveri poolel teeb tööriist ainult päringu ja agent peatub sellel:
from agents import Agent, RunContextWrapper, StopAtTools, function_tool
from chatkit.agents import AgentContext, ClientToolCall
@function_tool(description_override="Loeb teksti, mille kasutaja on lehel valinud.")
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="Aita kasutajal parandada teksti, mille ta valib.",
model="gpt-6.1-sol",
tools=[read_selection],
tool_use_behavior=StopAtTools(stop_at_tool_names=[read_selection.name]),
)
Kasutajaliidese poolel saab onClientTool päringu; nimi peab klappima ja tagastatud objekt läheb serverisse:
const { control } = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
onClientTool: async ({ name }) => {
if (name === 'read_selection') {
return { text: window.getSelection()?.toString() ?? '' };
}
return {};
},
});
Ühe vooru jooksul saab täita ainult ühte kliendipoolset tööriista. Ja kui sa ei oota vastust, eelista efekti: server edastab ClientEffectEvent(name="refresh_cart", data={...}) kohast respond, action või tööriistast ctx.context.stream(...) kaudu ning kasutajaliides saab selle kätte onEffect kaudu, katkestamata vastust. Efekte ei salvestata lõimesse.
Juhi ChatKiti oma rakendusest
useChatKit tagastab lisaks control-ile meetodid, millega juhtida kasutajaliidest ülejäänud koodist:
| Meetod | Mõju |
|---|---|
sendUserMessage({ text }) | Saadab sõnumi, justkui oleks kasutaja selle tippinud |
setComposerValue({ text }) | Täidab sisendvälja eelnevalt, saatmata |
setThreadId(id) | Avab olemasoleva lõime või uue lõime väärtusega null |
focusComposer() | Paigutab kursori sisendväljale |
showHistory(), hideHistory() | Avab või sulgeb vestluste ajaloo |
sendCustomAction(action) | Saadab tegevuse serverisse (õppetund 20) |
fetchUpdates() | Laadib lõime serverist uuesti |
„Küsi assistendilt“ nupp tootelehel muutub üheks koodireaks:
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?` })}>
Küsi assistendilt
</button>
<ChatKit control={chatkit.control} className="h-[500px] w-[360px]" />
</>
);
}
Valik initialThread avab käivitamisel kindla lõime, näiteks selle, mille kasutaja lahti jättis; väärtusega null (vaikimisi väärtus) kuvab ChatKit avalehe.
Jälgi, mis toimub
ChatKit edastab sündmusi: valmisolek (onReady), vastuse algus ja lõpp (onResponseStart, onResponseEnd), lõime vahetus (onThreadChange), logid (onLog) ja vead (onError). Reactis on need useChatKit valikud:
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 }),
});
Tootmisjuhend rõhutab üht punkti: need sündmused võivad sisaldada isikuandmeid ja sõnumite teksti. Ära saada kogu sisu oma jälgimistööriista: eralda kasulikud väljad (sündmuse nimi, lõime ID, veakood). Serveri poolel logi iga päring /chatkit aadressile, väljakutsed salvestusruumi ja mudelile ning tööriistade vead koos kasutaja ja lõime ID-ga, et saaksid mõlemat poolt korreleerida.
Aeglaste tööriistade puhul hoia kasutajat kursis: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) kuvab kohese edenemise, mille asendab ülejäänud vastus ja mida kunagi lõimesse ei salvestata.
Enne tootmisse minekut
Kontrollnimekiri ametlikust juhendist:
- Domeenid: iga tootmise hostinimi on loetletud OpenAI platvormi lehel Domain allowlist ja selle võti on
domainKey-s; - Autentimine ja autoriseerimine: iga päring
/chatkiton autenditud, lõimed ja manused on filtreeritud kasutaja järgi; - Saladused: API võti ja sisemised mandaadid on keskkonnamuutujates või saladuste halduris, mitte kunagi repositooriumis;
- Sisendid: sõnumeid, faile, tegevuste kasulikke andmeid ja tööriistade tulemusi käsitletakse usaldamatuna ja valideeritakse enne süsteemidesse jõudmist;
- Isikuandmed: säilitusaeg on otsustatud ja rakendatud salvestusruumis, krüpteerimine puhkeolekus, metaandmetes pole ebavajalikke andmeid;
- Keel: keel päises
Accept-Languagesuunab agendi vastuseid ja sinu tööriistade sõnumeid; - Jälgimine: kasutajaliidese sündmused ja serveri logid kogutakse ilma tundliku sisuta.
Peamised punktid
- Kasutaja identiteet liigib kasutajaliidese poolel
api.fetchkaudu, seejärelserver.processkonteksti kaudu, mis levitab seda kõikjale - Autoriseerimine toimub salvestusruumis: iga lõim kuulub kasutajale ja teise kasutaja lõim on „ei leitud“
- Rakenduse kontekst saabub päiste, serveri tööriistade või kliendipoolsete tööriistade kaudu (
onClientTool+StopAtTools); efektid (onEffect) teenindavad juhtumeid, kui vastust ei oodata - Meetodid
useChatKit-ist (sendUserMessage,setThreadId,setComposerValue…) juhivad ChatKiti rakenduse ülejäänud osast - Sündmused (
onError,onLog…) toidavad sinu jälgimist, kopeerimata sinna isikuandmeid; tootmise kontrollnimekiri hõlmab domeene, õigusi, saladusi, sisendeid ja andmeid