Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Napredna integracija v tvojo aplikacijo

Lekcija 21 od 25 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Kaj ostane po demonstraciji
  2. Avtentikacija vsake zahteve
  3. Vsak uporabnik dobi svoje pogovore
  4. Modelu posreduj kontekst svoje aplikacije
  5. Orodja na strani odjemalca
  6. Upravljaj ChatKit iz svoje aplikacije
  7. Opazuj, kaj se dogaja
  8. Pred odhodom v proizvodnjo
  9. Ključne ugotovitve

Lekcija na novo napisana 3. novembra 2026. Prejšnja različica se je zanašala na izmišljene lastnosti in dogodke (ChatProvider, način „stranske vrstice”, trajnost na ravni uporabniškega vmesnika). Zdaj sledi vodnikom za Python SDK openai-chatkit 1.6.5 (Priprava aplikacije za proizvodnjo, Posredovanje dodatnega konteksta aplikacije, Posodobitev odjemalca med odgovorom) in tipom @openai/chatkit-react 1.6.1: koda strežnika je bila izvedena lokalno, koda React pa preverjena s kompilacijo. Viri: Priprava aplikacije za proizvodnjo · Posredovanje dodatnega konteksta aplikacije modelu · Posodobitev odjemalca med odgovorom · Napredne integracije s ChatKit.

Kaj ostane po demonstraciji

Prejšnje štiri lekcije so ti dale delujočega pomočnika. Da bi ta zaživel v pravem izdelku, potrebuje vse tisto, kar loči demonstracijo od storitve: vedeti, kdo govori, vsakemu uporabniku prikazati le njegove pogovore, interakcijo z ostalim delom aplikacije in opazljivost. Ta lekcija obravnava te točke eno za drugo.

Avtentikacija vsake zahteve

SDK ne predpostavlja ničesar o tvoji avtentikaciji: omogoča ti, da preveriš uporabnika, nato pa njegovo identiteto posreduješ metodi server.process v kontekstu zahteve. Ta kontekst spremlja vsak klic: najdeš ga v respond, v action, v shrambi in v orodjih agenta.

Na strani vmesnika možnost api.fetch nadomesti funkcijo fetch, ki jo uporablja ChatKit. Tu dodaš sejni žeton svoje aplikacije:

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) => {
        // Ohrani glave, ki jih nastavi ChatKit, nato dodaj svoje
        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]" />;
}

Na strani strežnika odvisnost FastAPI preveri žeton in zgradi kontekst. Jezik vmesnika prispe v glavi Accept-Language, ki jo ChatKit pošlje z vsako zahtevo:

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)  # tvoja avtentikacija: seja, 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")

Vsak uporabnik dobi svoje pogovore

Avtentikacija ni dovolj: potrebuješ tudi avtorizacijo. Brez nadzora bi uporabnik, ki ugane ID niti, lahko prebral tuji pogovor. Pravo mesto za ta nadzor je shramba, skozi katero potekajo vsa branja. V tem primeru vsaka nit v svojih metapodatkih hrani ime lastnika, ki ga SDK nikoli ne posreduje vmesniku:

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")  # ne razkrij, da obstaja
        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

Blok try v končni točki ima tu smisel: brez njega bi neposredno branje tuje niti končalo s napako 500 namesto s 404; pri zahtevi s pretokom, kot je dodajanje sporočila, SDK prekine pretok, ne da bi karkoli poslal. V proizvodnji se to filtriranje zgodi neposredno v poizvedbi SQL (klavzula WHERE owner = … pravilno obravnava tudi paginacijo). Enako pravilo uporabi za priloge. Dokumentacija te tudi opominja, da se odločiš, kaj hraniš in kako dolgo: niti vsebujejo besedilo, datoteke in rezultate orodij, torej pogosto osebne podatke.

Modelu posreduj kontekst svoje aplikacije

Model ne ve ničesar o strani, ki jo uporabnik gleda, njegovi naročnini ali odprtem dokumentu. Dokumentacija predlaga tri načine, kako ga to naučiti:

  • Ob vsaki zahtevi, prek glav, dodanih v api.fetch (X-Page, X-Plan…), ki jih strežnik shrani v kontekst;
  • Po potrebi, prek orodja strežnika, ki prebere ctx.context.request_context in pridobi informacije;
  • V brskalniku, prek orodja na strani odjemalca, ko informacije obstajajo le tam (glej naslednji razdelek).

En previden ukrep, prevzet iz vodnika za proizvodnjo: nikoli ne gradi sistemskih navodil modela iz vrednosti, ki prihajajo od uporabnika, niti posredno (naslov niti, zadeva kartice). Ohrani jih fiksne in spremenljivi kontekst posreduj kot podatke.

Orodja na strani odjemalca

Nekatere informacije živijo le v brskalniku: izbor v urejevalniku, stanje platna, neshranjen osnutek. Orodje na strani odjemalca omogoča modelu, da jih zahteva sredi obrata: tvoj strežnik zaustavi agenta, ChatKit izvrši tvojo funkcijo v brskalniku, nato vrne rezultat strežniku, ki nadaljuje.

Na strani strežnika orodje le sproži zahtevo, agent pa se ob njem ustavi:

from agents import Agent, RunContextWrapper, StopAtTools, function_tool
from chatkit.agents import AgentContext, ClientToolCall


@function_tool(description_override="Prebere besedilo, ki ga je uporabnik izbral na strani.")
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="Pomagaj uporabniku izboljšati besedilo, ki ga izbere.",
    model="gpt-6.1-sol",
    tools=[read_selection],
    tool_use_behavior=StopAtTools(stop_at_tool_names=[read_selection.name]),
)

Na strani vmesnika onClientTool prejme zahtevo; ime se mora ujemati, vrnjeni objekt pa gre na strežnik:

const { control } = useChatKit({
  api: { url: '/chatkit', domainKey: 'local-dev' },
  onClientTool: async ({ name }) => {
    if (name === 'read_selection') {
      return { text: window.getSelection()?.toString() ?? '' };
    }
    return {};
  },
});

Na obrat se lahko izvrši le eno orodje na strani odjemalca. In ko ne pričakuješ odgovora, raje uporabi učinek: strežnik odda ClientEffectEvent(name="refresh_cart", data={...}), iz respond, action ali orodja prek ctx.context.stream(...), vmesnik pa ga prejme v onEffect brez prekinitve odgovora. Učinki niso zapisani v niti.

Upravljaj ChatKit iz svoje aplikacije

useChatKit vrne, poleg control, metode za ukazovanje vmesniku iz preostanka tvoje kode:

MetodaUčinek
sendUserMessage({ text })Pošlje sporočilo, kot da bi ga uporabnik vtipkal
setComposerValue({ text })Predizpolni vnosno polje brez pošiljanja
setThreadId(id)Odpre obstoječo nit ali novo nit z null
focusComposer()Postavi kazalec v vnosno polje
showHistory(), hideHistory()Odpre ali zapre zgodovino pogovorov
sendCustomAction(action)Pošlje dejanje strežniku (lekcija 20)
fetchUpdates()Ponovno naloži nit s strežnika

Gumb „Vprašaj pomočnika” na listu izdelka postane ena vrstica kode:

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]" />
    </>
  );
}

Možnost initialThread ob zagonu odpre določeno nit, na primer tisto, ki jo je uporabnik pustil odprto; z null (privzeta vrednost) ChatKit prikaže domači zaslon.

Opazuj, kaj se dogaja

ChatKit oddaja dogodke: pripravljenost (onReady), začetek in konec odgovora (onResponseStart, onResponseEnd), spremembo niti (onThreadChange), dnevnike (onLog) in napake (onError). V Reactu so to možnosti za useChatKit:

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 }),
});

Vodnik za proizvodnjo vztraja pri eni točki: ti dogodki lahko vsebujejo osebne podatke in besedilo sporočil. Ne pošiljaj celotne vsebine v svoje orodje za sledenje: izvleci uporabna polja (ime dogodka, ID niti, koda napake). Na strani strežnika beleži vsako zahtevo na /chatkit, klice shrambe in modela ter napake orodij, z ID-jem uporabnika in niti, da lahko povežeš obe strani.

Za počasna orodja uporabnika obveščaj: await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) prikaže takojšen napredek, ki ga nadomesti preostanek odgovora in nikoli ni zapisan v niti.

Pred odhodom v proizvodnjo

Seznam za preverjanje, prevzet iz uradnega vodnika:

  • Domena: vsako produkcijsko gostiteljsko ime je navedeno na strani Domain allowlist platforme OpenAI, njegov ključ pa je v domainKey;
  • Avtentikacija in avtorizacija: vsaka zahteva na /chatkit je avtenticirana, niti in priloge so filtrirane po uporabniku;
  • Skrivnosti: ključ API in notranja poverila so v spremenljivkah okolja ali upravitelju skrivnosti, nikoli v repozitoriju;
  • Vnosi: sporočila, datoteke, vsebine dejanj in rezultati orodij se obravnavajo kot nezaupanja vredni in se pred dostopom do tvojih sistemov validirajo;
  • Osebni podatki: obdobje hrambe je določeno in uveljavljeno v shrambi, šifriranje v mirovanju, v metapodatkih ni nepotrebnih podatkov;
  • Jezik: jezik v glavi Accept-Language usmerja odgovore agenta in sporočila tvojih orodij;
  • Sledenje: dogodki vmesnika in dnevniki strežnika so zbrani, brez občutljive vsebine.

Ključne ugotovitve

  • Identiteta uporabnika potuje prek api.fetch na strani vmesnika, nato prek konteksta server.process, ki jo razširi povsod
  • Avtorizacija se zgodi v shrambi: vsaka nit pripada uporabniku, nit drugega uporabnika pa je „ni mogoče najti”
  • Kontekst aplikacije prispe prek glav, orodij strežnika ali orodij na strani odjemalca (onClientTool + StopAtTools); učinki (onEffect) služijo, ko odgovor ni pričakovan
  • Metode iz useChatKit (sendUserMessage, setThreadId, setComposerValue…) upravljajo ChatKit iz preostanka aplikacije
  • Dogodki (onError, onLog…) hranijo tvoje sledenje, ne da bi vanj kopirali osebne podatke; seznam za proizvodnjo pokriva domene, pravice, skrivnosti, vnose in podatke