Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Täiustatud integreerimine rakendusse

Õppetund 21 / 25 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Mis jääb pärast demo-versiooni
  2. Autendi iga päringut
  3. Iga kasutaja saab oma vestlused
  4. Anna mudelile oma rakenduse kontekst
  5. Kliendipoolsed tööriistad
  6. Juhi ChatKiti oma rakendusest
  7. Jälgi, mis toimub
  8. Enne tootmisse minekut
  9. Peamised punktid

Õ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 SDK openai-chatkit 1.6.5 juhiseid (Valmista oma rakendus tootmiseks ette, Edasta täiendavat rakenduse konteksti, Uuenda klienti vastuse ajal) ja @openai/chatkit-react 1.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.fetch kaudu (X-Page, X-Plan…), mille server salvestab konteksti;
  • Vajadusel, serveri tööriista kaudu, mis loeb ctx.context.request_context ja 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:

MeetodMõ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 /chatkit on 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-Language suunab 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.fetch kaudu, seejärel server.process konteksti 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