Ενσωμάτωση προχωρημένου επιπέδου στην εφαρμογή σας
Σε αυτήν τη σελίδα
Μάθημα ξαναγραμμένο στις 3 Νοεμβρίου 2026. Η προηγούμενη έκδοση βασιζόταν σε εφευρεμένες ιδιότητες και συμβάντα (
ChatProvider, λειτουργία “sidebar”, επιμονή βάσει UI). Ακολουθεί πλέον τους οδηγούς του Python SDKopenai-chatkit1.6.5 (Προετοιμάστε την εφαρμογή σας για παραγωγή, Περάστε επιπλέον πλαίσιο εφαρμογής, Ενημερώστε τον πελάτη κατά τη διάρκεια απόκρισης) και τους τύπους του@openai/chatkit-react1.6.1: ο κώδικας διακομιστή εκτελέστηκε τοπικά και ο κώδικας React επαληθεύτηκε μέσω μεταγλώττισης. Πηγές: Προετοιμάστε την εφαρμογή σας για παραγωγή · Περάστε επιπλέον πλαίσιο εφαρμογής στο μοντέλο σας · Ενημερώστε τον πελάτη κατά τη διάρκεια απόκρισης · Προχωρημένες ενσωματώσεις με το ChatKit.
Τι απομένει μετά την επίδειξη
Τα προηγούμενα τέσσερα μαθήματα σας παρέχουν έναν λειτουργικό βοηθό. Για να ζήσει μέσα σε ένα πραγματικό προϊόν, χρειάζεται ό,τι χωρίζει μια επίδειξη από μια υπηρεσία: να γνωρίζει ποιος μιλάει, να εμφανίζει σε κάθε χρήστη μόνο τις δικές του συνομιλίες, να αλληλεπιδρά με την υπόλοιπη εφαρμογή και να είναι παρατηρήσιμος. Αυτό το μάθημα καλύπτει αυτά τα σημεία ένα προς ένα.
Πιστοποιήστε κάθε αίτημα
Το SDK δεν κάνει καμία υπόθεση σχετικά με την πιστοποίησή σας: σας επιτρέπει να επαληθεύετε τον χρήστη και στη συνέχεια να περνάτε την ταυτότητά του στο server.process μέσα σε ένα πλαίσιο αιτήματος. Αυτό το πλαίσιο ακολουθεί κάθε κλήση: το βρίσκετε στο respond, στο action, στο store και στα εργαλεία του πράκτορα.
Στην πλευρά της διεπαφής, η επιλογή api.fetch αντικαθιστά τη συνάρτηση fetch που χρησιμοποιεί το ChatKit. Εδώ προσθέτετε το διακριτικό συνεδρίας της εφαρμογής σας:
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) => {
// Διατηρήστε τις κεφαλίδες που ορίζει το ChatKit και μετά προσθέστε τις δικές μας
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]" />;
}
Στην πλευρά του διακομιστή, μια εξάρτηση FastAPI επαληθεύει το διακριτικό και δημιουργεί το πλαίσιο. Η γλώσσα της διεπαφής φτάνει στην κεφαλίδα Accept-Language, την οποία το ChatKit στέλνει με κάθε αίτημα:
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) # η πιστοποίησή σας: συνεδρία, 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")
Κάθε χρήστης έχει τις δικές του συνομιλίες
Η πιστοποίηση δεν αρκεί: χρειάζεστε επίσης εξουσιοδότηση. Χωρίς έλεγχο, ένας χρήστης που μαντεύει ένα ID νήματος θα μπορούσε να διαβάσει τη συνομιλία κάποιου άλλου. Το σωστό σημείο για αυτόν τον έλεγχο είναι το store, μέσω του οποίου περνούν όλες οι αναγνώσεις. Σε αυτό το παράδειγμα, κάθε νήμα διατηρεί το όνομα του ιδιοκτήτη του στα μεταδεδομένα του, τα οποία το SDK δεν μεταδίδει ποτέ στη διεπαφή:
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") # μην αποκαλύπτετε ότι υπάρχει
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 στο σημείο τελείωσης έχει νόημα εδώ: χωρίς αυτό, η άμεση ανάγνωση ενός νήματος άλλου χρήστη θα κατέληγε σε σφάλμα 500 αντί για 404· για ένα streamed αίτημα, όπως η προσθήκη μηνύματος, το SDK διακόπτει τη ροή χωρίς να στείλει τίποτα. Στην παραγωγή, αυτό το φιλτράρισμα συμβαίνει στο ίδιο το ερώτημα SQL (ένα WHERE owner = … χειρίζεται επίσης σωστά τη σελιδοποίηση). Εφαρμόστε τον ίδιο κανόνα στα συνημμένα. Η τεκμηρίωση σας υπενθυμίζει επίσης να αποφασίσετε τι κρατάτε και για πόσο χρονικό διάστημα: τα νήματα περιέχουν κείμενο, αρχεία και αποτελέσματα εργαλείων, άρα συχνά προσωπικά δεδομένα.
Δώστε στο μοντέλο το πλαίσιο της εφαρμογής σας
Το μοντέλο δεν γνωρίζει τίποτα για τη σελίδα που βλέπει ο χρήστης, τη συνδρομή του ή το ανοιχτό έγγραφο. Η τεκμηρίωση προτείνει τρεις τρόπους για να το διδάξετε:
- Σε κάθε αίτημα, μέσω κεφαλίδων που προστίθενται στο
api.fetch(X-Page,X-Plan…), τις οποίες ο διακομιστής αποθηκεύει στο πλαίσιο· - Κατόπιν ζήτησης, μέσω ενός εργαλείου διακομιστή που διαβάζει το
ctx.context.request_contextκαι ανακτά τις πληροφορίες· - Στον browser, μέσω ενός εργαλείου πλευράς πελάτη, όταν οι πληροφορίες υπάρχουν μόνο εκεί (δείτε την επόμενη ενότητα).
Μια προφύλαξη, παρμένη από τον οδηγό παραγωγής: μην κατασκευάζετε ποτέ τις οδηγίες συστήματος του μοντέλου από τιμές που προέρχονται από τον χρήστη, έστω και έμμεσα (τίτλος νήματος, θέμα ticket). Κρατήστε τες σταθερές και περάστε το μεταβλητό πλαίσιο ως δεδομένα.
Εργαλεία πλευράς πελάτη
Ορισμένες πληροφορίες ζουν μόνο στον browser: επιλογή σε έναν επεξεργαστή, κατάσταση καμβά, ένα μη αποθηκευμένο πρόχειρο. Ένα εργαλείο πλευράς πελάτη επιτρέπει στο μοντέλο να τις ζητήσει στη μέση μιας στροφής: ο διακομιστής σας παύει τον πράκτορα, το ChatKit εκτελεί τη συνάρτησή σας στον browser και στη συνέχεια επιστρέφει το αποτέλεσμα στον διακομιστή, ο οποίος συνεχίζει.
Στην πλευρά του διακομιστή, το εργαλείο κάνει μόνο το αίτημα και ο πράκτορας σταματά σε αυτό:
from agents import Agent, RunContextWrapper, StopAtTools, function_tool
from chatkit.agents import AgentContext, ClientToolCall
@function_tool(description_override="Διαβάζει το κείμενο που έχει επιλέξει ο χρήστης στη σελίδα.")
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="Βοηθήστε τον χρήστη να βελτιώσει το κείμενο που επιλέγει.",
model="gpt-6.1-sol",
tools=[read_selection],
tool_use_behavior=StopAtTools(stop_at_tool_names=[read_selection.name]),
)
Στην πλευρά της διεπαφής, το onClientTool λαμβάνει το αίτημα· το όνομα πρέπει να ταιριάζει και το αντικείμενο που επιστρέφεται πηγαίνει στον διακομιστή:
const { control } = useChatKit({
api: { url: '/chatkit', domainKey: 'local-dev' },
onClientTool: async ({ name }) => {
if (name === 'read_selection') {
return { text: window.getSelection()?.toString() ?? '' };
}
return {};
},
});
Μόνο ένα εργαλείο πλευράς πελάτη μπορεί να εκτελεστεί ανά στροφή. Και όταν δεν αναμένετε απόκριση, προτιμήστε ένα effect: ο διακομιστής εκπέμπει ένα ClientEffectEvent(name="refresh_cart", data={...}), από το respond, το action ή ένα εργαλείο μέσω ctx.context.stream(...), και η διεπαφή το λαμβάνει στο onEffect χωρίς να διακόπτει την απόκριση. Τα effects δεν καταγράφονται στο νήμα.
Οδηγήστε το ChatKit από την εφαρμογή σας
Το useChatKit επιστρέφει, εκτός από το control, μεθόδους για να δίνετε εντολές στη διεπαφή από τον υπόλοιπο κώδικά σας:
| Μέθοδος | Επίδραση |
|---|---|
sendUserMessage({ text }) | Στέλνει ένα μήνυμα σαν να το πληκτρολόγησε ο χρήστης |
setComposerValue({ text }) | Προσυμπληρώνει την περιοχή εισαγωγής χωρίς αποστολή |
setThreadId(id) | Ανοίγει ένα υπάρχον νήμα ή ένα νέο νήμα με null |
focusComposer() | Τοποθετεί τον κέρσορα στην περιοχή εισαγωγής |
showHistory(), hideHistory() | Ανοίγει ή κλείνει το ιστορικό συνομιλίας |
sendCustomAction(action) | Στέλνει μια ενέργεια στον διακομιστή (Μάθημα 20) |
fetchUpdates() | Επαναφορτώνει το νήμα από τον διακομιστή |
Ένα κουμπί “Ρωτήστε τον βοηθό” σε ένα φύλλο προϊόντος γίνεται μία γραμμή κώδικα:
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]" />
</>
);
}
Η επιλογή initialThread ανοίγει ένα συγκεκριμένο νήμα κατά την τοποθέτηση, για παράδειγμα αυτό που άφησε ανοιχτό ο χρήστης· με null (την προεπιλεγμένη τιμή), το ChatKit εμφανίζει την αρχική οθόνη.
Παρατηρήστε τι συμβαίνει
Το ChatKit εκπέμπει συμβάντα: έτοιμο (onReady), έναρξη και λήξη απόκρισης (onResponseStart, onResponseEnd), αλλαγή νήματος (onThreadChange), αρχεία καταγραφής (onLog) και σφάλματα (onError). Στο React, αυτές είναι επιλογές για το 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 }),
});
Ο οδηγός παραγωγής επιμένει σε ένα σημείο: αυτά τα συμβάντα μπορεί να περιέχουν προσωπικά δεδομένα και κείμενο μηνυμάτων. Μην στέλνετε όλο το περιεχόμενο στο εργαλείο παρακολούθησής σας: εξάγετε χρήσιμα πεδία (όνομα συμβάντος, ID νήματος, κωδικός σφάλματος). Στην πλευρά του διακομιστή, καταγράψτε κάθε αίτημα στο /chatkit, κλήσεις στο store και στο μοντέλο, καθώς και σφάλματα εργαλείων, με το ID χρήστη και το ID νήματος, ώστε να μπορείτε να συσχετίσετε και τις δύο πλευρές.
Για αργά εργαλεία, κρατήστε τον χρήστη ενημερωμένο: το await ctx.context.stream(ProgressUpdateEvent(icon="search", text="Searching your orders…")) εμφανίζει άμεση πρόοδο, η οποία αντικαθίσταται από την υπόλοιπη απόκριση και δεν καταγράφεται ποτέ στο νήμα.
Πριν πάτε σε παραγωγή
Η λίστα ελέγχου, παρμένη από τον επίσημο οδηγό:
- Τομείς: κάθε όνομα host παραγωγής αναγράφεται στη σελίδα Domain allowlist της πλατφόρμας OpenAI και το κλειδί του βρίσκεται στο
domainKey· - Πιστοποίηση και εξουσιοδότηση: κάθε αίτημα στο
/chatkitείναι πιστοποιημένο, τα νήματα και τα συνημμένα φιλτράρονται ανά χρήστη· - Μυστικά: το κλειδί API και τα εσωτερικά διαπιστευτήρια βρίσκονται σε μεταβλητές περιβάλλοντος ή σε διαχειριστή μυστικών, ποτέ στο αποθετήριο·
- Είσοδοι: μηνύματα, αρχεία, φορτία ενεργειών και αποτελέσματα εργαλείων αντιμετωπίζονται ως μη έμπιστα και επικυρώνονται πριν φτάσουν στα συστήματά σας·
- Προσωπικά δεδομένα: περίοδος διατήρησης αποφασισμένη και εφαρμοσμένη στο store, κρυπτογράφηση σε κατάσταση ηρεμίας, χωρίς περιττά δεδομένα στα μεταδεδομένα·
- Γλώσσα: η γλώσσα
Accept-Languageκαθοδηγεί τις αποκρίσεις του πράκτορα και τα μηνύματα των εργαλείων σας· - Παρακολούθηση: συμβάντα διεπαφής και αρχεία καταγραφής διακομιστή συλλέγονται, χωρίς ευαίσθητο περιεχόμενο.
Βασικά σημεία
- Η ταυτότητα του χρήστη περνά μέσω του
api.fetchστην πλευρά της διεπαφής και στη συνέχεια μέσω του πλαισίου τουserver.process, το οποίο την διαχέει παντού - Η εξουσιοδότηση συμβαίνει στο store: κάθε νήμα ανήκει σε έναν χρήστη και το νήμα άλλου χρήστη εμφανίζεται ως “δεν βρέθηκε”
- Το πλαίσιο εφαρμογής φτάνει μέσω κεφαλίδων, εργαλείων διακομιστή ή εργαλείων πλευράς πελάτη (
onClientTool+StopAtTools)· τα effects (onEffect) εξυπηρετούν όταν δεν αναμένεται απόκριση - Οι μέθοδοι από το
useChatKit(sendUserMessage,setThreadId,setComposerValue…) δίνουν εντολές στο ChatKit από την υπόλοιπη εφαρμογή - Τα συμβάντα (
onError,onLog…) τροφοδοτούν την παρακολούθησή σας, χωρίς να αντιγράφουν προσωπικά δεδομένα σε αυτήν· η λίστα ελέγχου παραγωγής καλύπτει τομείς, δικαιώματα, μυστικά, εισόδους και δεδομένα