Comhtháthú casta i d'fheidhmchlár
Ar an leathanach seo
An ceacht athscríofa an 3 Samhain, 2026. Bhraitheann an leagan roimhe seo ar airíonna agus ar imeachtaí cumtha (
ChatProvider, mód “sidebar”, marthanacht bunaithe ar UI). Leanann sé treoracha Python SDKopenai-chatkit1.6.5 anois (Prepare your app for production, Pass extra app context, Update the client during a response) agus cineálacha@openai/chatkit-react1.6.1: rith an cód freastalaí go logánta, agus rinneadh an cód React a fhíorú trí thiomsú. Foinse: Prepare your app for production · Pass extra app context to your model · Update the client during a response · Advanced integrations with ChatKit.
Cad atá fágtha tar éis an taispeántais
Tugann na ceithre cheacht roimhe seo cúntóir oibre duit. Chun é a chur ar fáil i dtáirge fíor, teastaíonn uait na rudaí a dhealaíonn taispeántas ó sheirbhís: a fhios a bheith agat cé atá ag caint, gach úsáideoir a theorannú dá chomhráite féin, idirghníomhú le cuid eile an fheidhmchláir, agus bheith inbhraite. Pléann an ceacht seo na pointí sin ceann ar cheann.
Gach iarratas a fhíordheimhniú
Ní dhéanann an SDK aon toimhdí faoi d’fhíordheimhniú: ligeann sé duit an t-úsáideoir a fhíorú, agus ansin a aitheantas a chur ar server.process i comhthéacs iarratais. Leanann an comhthéacs seo gach glao: faigheann tú é in respond, in action, sa stór, agus in uirlisí an ghníomhaire.
Ar an taobh comhéadain, cuireann an rogha api.fetch in ionad an fheidhm fetch a úsáideann ChatKit. Seo áit a gcuireann tú do chomhartha seisiún feidhmchláir leis:
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) => {
// Keep headers set by ChatKit, then add ours
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]" />;
}
Ar an taobh freastalaí, fíoraíonn spleáchas FastAPI an comhartha agus tógann sé an comhthéacs. Tagann teanga an chomhéadain sa cheanntásc Accept-Language, a sheolann ChatKit le gach iarratas:
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) # your authentication: session, 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")
Gach úsáideoir ag fáil a chomhráite féin
Ní leor fíordheimhniú: teastaíonn údarú uait freisin. Gan rialú, d’fhéadfadh úsáideoir a thuarann ID snáithe comhrá duine eile a léamh. Is é an stór an t-áit cheart don rialú seo, trína n-imíonn gach léamh. Sa sampla seo, coinníonn gach snáithe ainm an úinéara ina mheiteashonraí, rud nach dtarchuireann an SDK riamh chuig an gcomhéadan:
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") # do not reveal that it exists
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
Tá ciall leis an mbloc try san ionphointe anseo: gan é, chríochnódh léamh díreach ar shnáithe úsáideora eile le hearráid 500 in ionad 404; d’iarratas sruthaithe, cosúil le teachtaireacht a chur leis, briseann an SDK an sruth gan aon rud a sheoladh. I dtáirgeadh, tarlaíonn an scagadh seo san iarratas SQL féin (déileálann WHERE owner = … le leathanú ceart freisin). Cuir an riail chéanna i bhfeidhm ar cheangaltáin. Cuimhníonn an doiciméadú ort freisin cinneadh a dhéanamh faoi cad a choinníonn tú agus ar feadh cé chomh fada: bíonn téacs, comhaid, agus torthaí uirlisí i snáitheanna, mar sin go minic sonraí pearsanta.
Comhthéacs d’fheidhmchláir a thabhairt don mhúnla
Níl a fhios ag an múnla faoin leathanach atá an t-úsáideoir a fheiceáil, faoina shíntiús, nó faoin doiciméad atá oscailte. Molann an doiciméadú trí bhealach chun é a mhúineadh:
- Ar gach iarratas, trí cheanntáisc a chuirtear leis in
api.fetch(X-Page,X-Plan…), a stórálann an freastalaí sa chomhthéacs; - Ar éileamh, trí uirlis freastalaí a léann
ctx.context.request_contextagus a fhaigheann an t-eolas; - Sa bhrabhsálaí, trí uirlis taobh cliant, nuair nach bhfuil an t-eolas ann ach ansin (féach an chéad chuid eile).
Réamhchúram amháin, tógtha ón treoir táirgeachta: ná tóg treoracha córais an mhúnla riamh as luachanna a thagann ón úsáideoir, fiú go hindíreach (teideal snáithe, ábhar ticéid). Coinnigh iad seasta, agus cuir an comhthéacs athraitheach ar fáil mar shonraí.
Uirlisí taobh cliant
Níl roinnt eolais le fáil ach sa bhrabhsálaí: roghnú in eagarthóir, stát canbháis, dréacht nach bhfuil sábháilte. Ligeann uirlis taobh cliant don mhúnla iad a iarraidh i lár an chas: stopann do fhreastalaí an gníomhaire, feidhmíonn ChatKit do fheidhm sa bhrabhsálaí, ansin filleann sé an toradh ar an bhfreastalaí, a thosaíonn arís.
Ar an taobh freastalaí, ní dhéanann an uirlis ach an t-iarratas, agus stopann an gníomhaire air:
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]),
)
Ar an taobh comhéadain, faigheann onClientTool an t-iarratas; caithfidh an t-ainm a bheith comhoiriúnach, agus téann an réad a filltear chuig an bhfreastalaí:
const { control } = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
onClientTool: async ({ name }) => {
if (name === 'read_selection') {
return { text: window.getSelection()?.toString() ?? '' };
}
return {};
},
});
Ní féidir ach uirlis amháin taobh cliant a fheidhmiú in aghaidh an chas. Agus nuair nach bhfuil freagra agat ag súil leis, roghnaigh éifeacht: eisíonn an freastalaí ClientEffectEvent(name="refresh_cart", data={...}), ó respond, action, nó uirlis trí ctx.context.stream(...), agus faigheann an comhéadan é in onEffect gan an freagra a bhriseadh. Ní dhéantar taifead ar éifeachtaí sa snáithe.
ChatKit a thiomáint ó d’fheidhmchlár
Filleann useChatKit, i dteannta le control, modhanna chun an comhéadan a ordú ó chuid eile do chóid:
| Modh | Éifeacht |
|---|---|
sendUserMessage({ text }) | Seolann teachtaireacht amhail is gur chlóscríobh an t-úsáideoir í |
setComposerValue({ text }) | Líonann an t-ionchur réamhghníomhach gan é a sheoladh |
setThreadId(id) | Osclaíonn snáithe atá ann cheana, nó snáithe nua le null |
focusComposer() | Cuireann an cúrsóir san achar ionchuir |
showHistory(), hideHistory() | Osclaíonn nó dúnann stair an chomhrá |
sendCustomAction(action) | Seolann gníomh chuig an bhfreastalaí (Ceacht 20) |
fetchUpdates() | Athlódálann an snáithe ón bhfreastalaí |
Déantar cnaipe “Cuir ceist ar an gcúntóir” ar bhileog táirge ina líne amháin cóid:
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]" />
</>
);
}
Osclaíonn an rogha initialThread snáithe sonrach ar mhountáil, mar shampla an ceann a d’fhág an t-úsáideoir oscailte; le null (an luach réamhshocraithe), taispeánann ChatKit an scáileán baile.
Breathnú ar an méid atá ar siúl
Eisíonn ChatKit imeachtaí: réidh (onReady), tús agus deireadh freagartha (onResponseStart, onResponseEnd), athrú snáithe (onThreadChange), logaí (onLog), agus earráidí (onError). I React, is roghanna iad seo do 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 }),
});
Cuireann an treoir táirgeachta béim ar phointe amháin: is féidir le na himeachtaí seo sonraí pearsanta agus téacs teachtaireachta a bheith iontu. Ná seol gach ábhar chuig d’uirlis rianaithe: eastósc na réimsí úsáideacha (ainm an imeachta, ID snáithe, cód earráide). Ar an taobh freastalaí, déan logáil ar gach iarratas chuig /chatkit, glaoite ar an stór agus ar an múnla, agus earráidí uirlisí, leis an úsáideoir agus ID an snáithe, ionas gur féidir leat an dá thaobh a chomhcheangal.
D’uirlisí mall, coinnigh an t-úsáideoir ar an eolas: taispeánann await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) dul chun cinn láithreach, a chuirtear in ionad ag an gcuid eile den fhreagra agus nach ndéantar taifead air riamh sa snáithe.
Sula dtéann tú go táirgeadh
An seicliosta, tógtha ón treoir oifigiúil:
- Fearainn: liostaítear gach óstainm táirgeachta ar an leathanach Domain allowlist de chuid ardán OpenAI, agus tá a eochair in
domainKey; - Fíordheimhniú agus údarú: déantar gach iarratas chuig
/chatkita fhíordheimhniú, scagtar snáitheanna agus ceangaltáin de réir úsáideora; - Rúin: tá an eochair API agus dintiúir inmheánacha in athróga timpeallachta nó i mbainisteoir rúin, riamh san stór;
- Ionchuir: déileáiltear le teachtaireachtaí, comhaid, lastais gníomhaíochta, agus torthaí uirlisí mar rud nach bhfuil muinín ann, agus bailíochtaithe sula sroicheann siad do chórais;
- Sonraí pearsanta: tréimhse coinneála cinnte agus curtha i bhfeidhm sa stór, criptiú ar scíth, gan sonraí nach gá sna meiteashonraí;
- Teanga: tiomáineann an teanga
Accept-Languagefreagraí an ghníomhaire agus do theachtaireachtaí uirlisí; - Rianú: bailítear imeachtaí comhéadain agus logaí freastalaí, gan ábhar íogair a bheith iontu.
Príomhphointí
- Téann aitheantas an úsáideora trí
api.fetchar an taobh comhéadain, ansin trí chomhthéacsserver.process, a scaipeann é gach áit - Tarlaíonn údarú sa stór: baineann gach snáithe le húsáideoir, agus tá snáithe úsáideora eile “gan aimsiú”
- Tagann comhthéacs an fheidhmchláir trí cheanntáisc, uirlisí freastalaí, nó uirlisí taobh cliant (
onClientTool+StopAtTools); freastalaíonn éifeachtaí (onEffect) nuair nach bhfuil freagra ag súil leis - Úsáideann modhanna ó
useChatKit(sendUserMessage,setThreadId,setComposerValue…) chun ChatKit a ordú ó chuid eile an fheidhmchláir - Cothaíonn imeachtaí (
onError,onLog…) do rianú, gan sonraí pearsanta a chóipeáil isteach ann; clúdaíonn an seicliosta táirgeachta fearainn, cearta, rúin, ionchuir, agus sonraí