Integrācija jūsu lietotnē: padziļināti
Šajā lapā
Nodarbība pārrakstīta 2026. gada 3. novembrī. Iepriekšējā versija balstījās uz izgudrotām īpašībām un notikumiem (
ChatProvider, „sānjoslas” režīms, lietotāja saskarnē balstīta saglabāšana). Tagad tā seko Python SDKopenai-chatkit1.6.5 rokasgrāmatām (Sagatavo savu lietotni ražošanai, Nodec papildu lietotnes kontekstu, Atjaunini klientu atbildes laikā) un@openai/chatkit-react1.6.1 tipiem: servera kods ir izpildīts lokāli, bet React kods verificēts, kompilējot. Avoti: Sagatavo savu lietotni ražošanai · Nodec modelim papildu lietotnes kontekstu · Atjaunini klientu atbildes laikā · Padziļināta integrācija ar ChatKit.
Kas paliek pēc demonstrācijas
Iepriekšējās četras nodarbības nodrošina tevi ar funkcionējošu asistentu. Lai tas darbotos reālā produktā, tam ir nepieciešams tas, kas atšķir demonstrāciju no servisa: zināt, kurš runā, rādīt katram lietotājam tikai viņa sarunas, mijiedarboties ar pārējo lietotni un būt novērojamam. Šī nodarbība soli pa solim aplūko šos punktus.
Autentificē katru pieprasījumu
SDK neizdara nekādus pieņēmumus par tavu autentifikāciju: tas ļauj tev verificēt lietotāju un pēc tam nodot viņa identitāti funkcijai server.process pieprasījuma kontekstā. Šis konteksts pavada katru izsaukumu: tu to atrodi funkcijās respond, action, krātuvē (store) un aģenta rīkos.
Lietotāja saskarnes pusē opcija api.fetch aizstāj fetch funkciju, ko izmanto ChatKit. Tieši šeit tu pievieno savas lietotnes sesijas žetonu:
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) => {
// Saglabā ChatKit iestatītos galvenes, pēc tam pievieno savas
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]" />;
}
Servera pusē FastAPI atkarība verificē žetonu un veido kontekstu. Lietotāja saskarnes valoda nonāk Accept-Language galvenē, ko ChatKit nosūta ar katru pieprasījumu:
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) # tava autentifikācija: 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")
Katram lietotājam ir savas sarunas
Autentifikācija nav pietiekama: tev ir nepieciešama arī autorizācija. Bez kontroles lietotājs, kurš uzmin diega (thread) ID, varētu izlasīt kāda cita sarunu. Pareizā vieta šai kontrolei ir krātuve (store), caur kuru notiek visa lasīšana. Šajā piemērā katrs diegs savā metadatos glabā īpašnieka vārdu, ko SDK nekad nepārraida uz lietotāja saskarni:
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") # neatklāj, ka tas eksistē
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 bloks galapunktā šeit ir jēdzīgs: bez tā tieša cita lietotāja diega nolasīšana beigtos ar 500 kļūdu, nevis 404; straumēta pieprasījuma gadījumā, piemēram, pievienojot ziņojumu, SDK pārtrauc plūsmu, neko nesūtot. Ražošanas vidē šī filtrēšana notiek pašā SQL vaicājumā (kur WHERE owner = … arī pareizi apstrādā lapošanu). Piemēro to pašu noteikumu pielikumiem. Dokumentācija arī atgādina izlemt, ko tu glabā un cik ilgi: diegi satur tekstu, failus un rīku rezultātus, tāpēc bieži vien tie ir personas dati.
Nodec modelim savu lietotnes kontekstu
Modelis nezina neko par lapu, ko lietotājs skatās, viņa abonementu vai atvērto dokumentu. Dokumentācija piedāvā trīs veidus, kā to iemācīt:
- Ar katru pieprasījumu, izmantojot galvenes, kas pievienotas
api.fetch(X-Page,X-Plan…), ko serveris saglabā kontekstā; - Pēc pieprasījuma, izmantojot servera rīku, kas nolasa
ctx.context.request_contextun iegūst informāciju; - Pārlūkā, izmantojot klienta puses rīku, kad informācija eksistē tikai tur (skatīt nākamo sadaļu).
Viens piesardzības pasākums, kas ņemts no ražošanas rokasgrāmatas: nekad neveido modeļa sistēmas instrukcijas no vērtībām, kas nāk no lietotāja, pat netieši (diega nosaukums, biļetes tēma). Saglabā tās fiksētas un nodec mainīgo kontekstu kā datus.
Klienta puses rīki
Daļa informācijas eksistē tikai pārlūkā: atlase redaktorā, audekla stāvoklis, nesaglabāts melnraksts. Klienta puses rīks ļauj modelim pieprasīt tos sarunas vidū: tavs serveris aptur aģentu, ChatKit izpilda tavu funkciju pārlūkā, pēc tam atgriež rezultātu serverim, kas turpina darbu.
Servera pusē rīks tikai izsaka pieprasījumu, un aģents pie tā apstājas:
from agents import Agent, RunContextWrapper, StopAtTools, function_tool
from chatkit.agents import AgentContext, ClientToolCall
@function_tool(description_override="Nolasa tekstu, ko lietotājs ir atlasījis lapā.")
async def read_selection(ctx: RunContextWrapper[AgentContext]) -> None:
ctx.context.client_tool_call = ClientToolCall(name="read_selection", arguments={})
assistant = Agent[AgentContext](
name="Rakstīšanas asistents",
instructions="Palīdzi lietotājam uzlabot tekstu, ko viņš ir atlasis.",
model="gpt-6.1-sol",
tools=[read_selection],
tool_use_behavior=StopAtTools(stop_at_tool_names=[read_selection.name]),
)
Lietotāja saskarnes pusē onClientTool saņem pieprasījumu; nosaukumam ir jāsakrīt, un atgrieztais objekts nonāk serverī:
const { control } = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
onClientTool: async ({ name }) => {
if (name === 'read_selection') {
return { text: window.getSelection()?.toString() ?? '' };
}
return {};
},
});
Vienā sarunas solī var izpildīt tikai vienu klienta puses rīku. Un, kad tu negaidi atbildi, dod priekšroku efektam: serveris ģenerē ClientEffectEvent(name="refresh_cart", data={...}) no respond, action vai rīka, izmantojot ctx.context.stream(...), un lietotāja saskarne to saņem onEffect, nepārtraucot atbildi. Efekti netiek ierakstīti diegā.
Vadī ChatKit no savas lietotnes
useChatKit atgriež, papildus control, metodes, lai vadītu lietotāja saskarni no pārējā koda:
| Metode | Efekts |
|---|---|
sendUserMessage({ text }) | Nosūta ziņojumu tā, it kā lietotājs to būtu ierakstījis |
setComposerValue({ text }) | Aizpilda ievades lauku, nesūtot |
setThreadId(id) | Atver esošu diegu vai jaunu diegu ar null |
focusComposer() | Novieto kursoru ievades laukā |
showHistory(), hideHistory() | Atver vai aizver sarunu vēsturi |
sendCustomAction(action) | Nosūta darbību serverim (20. nodarbība) |
fetchUpdates() | Pārlādē diegu no servera |
Poga „Jautā asistentam” produkta lapā kļūst par vienu koda rindiņu:
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: `Vai produkts ${product} ir savietojams ar manu iekārtu?` })}>
Jautā asistentam
</button>
<ChatKit control={chatkit.control} className="h-[500px] w-[360px]" />
</>
);
}
Opcija initialThread montāžas laikā atver konkrētu diegu, piemēram, to, ko lietotājs atstāja atvērtu; ar null (noklusējuma vērtība) ChatKit parāda sākuma ekrānu.
Novēro notiekošo
ChatKit ģenerē notikumus: gatavību (onReady), atbildes sākumu un beigas (onResponseStart, onResponseEnd), diega maiņu (onThreadChange), žurnālus (onLog) un kļūdas (onError). React vidē tie ir useChatKit opcijas:
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 }),
});
Ražošanas rokasgrāmata uzstāj uz vienu punktu: šie notikumi var saturēt personas datus un ziņojumu tekstu. Nesūti visu saturu uz savu izsekošanas rīku: izgūst tikai noderīgos laukus (notikuma nosaukums, diega ID, kļūdas kods). Servera pusē žurnalizē katru pieprasījumu uz /chatkit, izsaukumus uz krātuvi un modeli, kā arī rīku kļūdas, norādot lietotāja un diega ID, lai varētu korelēt abas puses.
Lēniem rīkiem informē lietotāju: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Meklēju tavus pasūtījumus…")) parāda tūlītēju progresu, ko vēlāk aizstāj ar pārējo atbildi un kas nekad netiek ierakstīts diegā.
Pirms došanās ražošanā
Kontrolsaraksts, kas ņemts no oficiālās rokasgrāmatas:
- Domēni: katrs ražošanas resursdatora nosaukums ir uzskaitīts OpenAI platformas lapā Domain allowlist, un tā atslēga ir
domainKey; - Autentifikācija un autorizācija: katrs pieprasījums uz
/chatkitir autentificēts, diegi un pielikumi ir filtrēti pēc lietotāja; - Noslēpumi: API atslēga un iekšējie akreditācijas dati ir vides mainīgajos vai noslēpumu pārvaldniekā, nekad ne repozitorijā;
- Ievades: ziņojumi, faili, darbību slodzes un rīku rezultāti tiek uzskatīti par neuzticamiem un validēti, pirms tie sasniedz tavas sistēmas;
- Personas dati: glabāšanas periods ir izlemts un piemērots krātuvē, šifrēšana miera stāvoklī, nevajadzīgi dati metadatos;
- Valoda:
Accept-Languagevaloda virza aģenta atbildes un tavu rīku ziņojumus; - Izsekošana: lietotāja saskarnes notikumi un servera žurnāli tiek vākti, neiekļaujot sensitīvu saturu.
Galvenās atziņas
- Lietotāja identitāte tiek nodota caur
api.fetchlietotāja saskarnes pusē, pēc tam caurserver.processkontekstu, kas to izplata visur - Autorizācija notiek krātuvē: katrs diegs pieder lietotājam, un cita lietotāja diegs tiek uzskatīts par „neatrastu”
- Lietotnes konteksts nonāk caur galvenēm, servera rīkiem vai klienta puses rīkiem (
onClientTool+StopAtTools); efekti (onEffect) kalpo, kad nav gaidāma atbilde - Metodes no
useChatKit(sendUserMessage,setThreadId,setComposerValue…) vada ChatKit no pārējās lietotnes - Notikumi (
onError,onLog…) baro tavu izsekošanu, nekopējot tajā personas datus; ražošanas kontrolsaraksts aptver domēnus, tiesības, noslēpumus, ievades un datus