Interaktiivsed vidinad
Sellel lehel
Tund kirjutati ümber 3. novembril 2026. Eelmine versioon kirjeldas vidinaid arendaja kirjutatud ja liidesesse registreeritud Reacti komponentidena, kasutades olematut moodulit
@openai/chatkit/react. ChatKitis on vidin deklaratiiivne kirjeldus, mille koostab sinu server ja mille ChatKit ise renderdab. See tund järgibopenai-chatkitPythoni SDK versiooni 1.6.5, mis loob vidinaid.widgetmallidest: selleCard,Text,Badge… klassid on iganenud. Näited käivitati kohalikus ChatKiti serveris. Allikad: ChatKiti vidinad · Vidinad (Pythoni SDK) · Interaktiivsete vastuste loomine vidinatega · Vidinate koostaja.
Mis on ChatKiti vidin?
Tekstivastus sobib selgitusteks. Kuid tellimuse esitamiseks, kolme paketi võrdlemiseks või kohtumise kinnitamiseks muutub tekst kiiresti realeaks, mida kasutaja peab uuesti läbi lugema. Vidinad asendavad selle teksti liidesega: kaardi, loendi, vormi või diagrammiga, mis kuvatakse vestlusvoos.
Lähenemine on deklaratiiivne. Sinu server ei edasta ei HTML-i ega Reacti komponenti: see kirjeldab vidinat JSON-formaadis, kasutades suletud hulka komponente ja omadusi, ning saadab selle lõimesse täieõigusliku elemendina (WidgetItem). ChatKit joonistab selle oma komponentidega, kasutades eelmises tunnis käsitletud teemavärve. Sellest tulenevad kaks järeldust:
- Saad kasutada ainult komponente ja omadusi, mida ChatKit tunneb. Tasuks jääb renderdus ülejäänud liidesega kooskõlaliseks ning serverilt ei jõua lehele suvalist HTML-i ega JavaScripti.
- Vidin on ajaloo osa: järgnevates voorudes teisendatakse see mudeli sisendiks, mistõttu mudel „näeb“, mida ta kasutajale näitas.
Konteinerid ja komponendid
Igal vidinal on juurelement, mis valitakse kolme konteineri seast:
| Konteiner | Kasutus |
|---|---|
Card | Iseseisev sisu: kokkuvõte, kinnitus, vorm. Võtab vastu oleku ning kinnituse/tühistamise nupud sisu all |
ListView | Valikute hulk: restoranid, failid, tellimused. Selle lapsed on ListViewItem-id, sisseehitatud „vaata rohkem“ funktsionaalsusega (limit) |
Basic | Reserveeritud üksuste eelvaadetele, mis kuvatakse mainimisel hõljumisel |
Seespool koostad komponendid: tekst (Title, Text, Caption, Markdown), sildid (Badge), paigutus (Row, Col, Box, Spacer, Divider), meedia (Image, Icon), käsud (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, mida Form saab rühmitada), diagrammid (Chart) ja animatsioonid (Transition). Vidinate koostaja komponentide leht loetleb ühe omadused koos redaktoriga nende proovimiseks.
Vidina kujundamine Vidinate koostajas
Soovitatav töövoog algab ChatKit Studio Vidinate koostajast. Kujundad seal paigutuse, täidad andmepaneeli näidisväärtustega, et hinnata renderdust, ja seejärel ekspordid .widget faili. See on JSON-fail, mis ühendab malli, oodatavate andmete skeemi (jsonSchema) ja näidisandmed. Versioonihalda seda koos oma serverikoodiga, näiteks kaustas widgets/.
Serveripoolselt laadib WidgetTemplate faili ja build täidab selle tegelike andmetega:
from chatkit.widgets import WidgetTemplate
order_template = WidgetTemplate.from_file("widgets/order.widget")
card = order_template.build({
"number": "C-42",
"status": "Shipped",
"color": "success",
"items": [{"name": "Keyboard", "price": "$49.90"}, {"name": "Mouse", "price": "$10.00"}],
"total": "$59.90",
})
Suhteline tee lahendatakse Pythoni failist, mis kutsub from_file, mitte käivituskataloogist. build aktsepteerib sõnastikku või Pydanticu mudelit.
Mida mall sisaldab
Mall on Jinja mudel, mis toodab vidina JSON-i. Tellimuse kaardi mall näeb välja selline:
ORDER_TEMPLATE = """
{
"type": "Card",
"children": [
{"type": "Row", "justify": "between", "align": "center", "children": [
{"type": "Title", "value": {{ ("Order " ~ number) | tojson }}, "size": "sm"},
{"type": "Badge", "label": {{ status | tojson }}, "color": {{ color | tojson }}}
]},
{"type": "Divider"},
{"type": "Col", "gap": 2, "children": [
{%- for item in items %}
{"type": "Row", "justify": "between", "children": [
{"type": "Text", "value": {{ item.name | tojson }}},
{"type": "Text", "value": {{ item.price | tojson }}}
]}{% if not loop.last %},{% endif %}
{%- endfor %}
]},
{"type": "Divider"},
{"type": "Row", "justify": "between", "children": [
{"type": "Text", "value": "Total", "weight": "semibold"},
{"type": "Text", "value": {{ total | tojson }}, "weight": "semibold"}
]}
]
}
"""
order_template = WidgetTemplate({"version": "1.0", "name": "order", "template": ORDER_TEMPLATE})
Sa kirjutad malle harva käsitsi, kuna Vidinate koostaja genereerib need. Kuid ühe lugemine säästab aega, kui tekib esimene probleem. Kolm märkust:
- Filter
tojsonteisendab iga väärtuse kehtivaks JSON-iks (jutumärkides string, tõeväärtus kuitruevõifalse) ja ekraanib erimärgid: tootenimes olev ülakoma või jutumärk ei riku JSON-i. - Jinja töötab ranges režiimis: puuduvad andmed põhjustavad
buildebaõnnestumise, mitte pooltühja vidina loomise. buildei valideeri andmeidjsonSchemavastu. See skeem dokumenteerib andmeid; kui need pärinevad tööriistast või andmebaasist, valideeri need eelnevalt, näiteks Pydanticu mudeliga.
Konstruktor WidgetTemplate(...) võtab sama sisu juba loetud .widget failist: see on kasulik testide jaoks või koodi poolt genereeritud malli puhul.
Vidina kuvamine respond kaudu
Vidina lõimesse saatmiseks toodab stream_widget vastavad ChatKiti sündmused. Edastad need oma respond meetodist:
from chatkit.server import stream_widget
# Sinu ChatKitServer klassis
async def respond(self, thread, input_user_message, context):
card = order_template.build(await get_order_data("C-42")) # sinu andmed
async for event in stream_widget(
thread,
card,
copy_text="Order C-42: shipped, $59.90",
generate_id=lambda item_type: self.store.generate_item_id(item_type, thread, context),
):
yield event
copy_text on tekst, mis kopeeritakse lõikelauale, kui kasutaja klõpsab vastuse all olevat kopeerimisnuppu. Server salvestab vidina ise poodi nagu iga edastatava elemendi.
Otsuse langetamine agendi poolt
Enamasti ei otsusta kaardi kuvamist sinu kood, vaid agent, kui vestlus seda nõuab. Anna talle tööriist, mis edastab vidina funktsiooniga AgentContext.stream_widget: stream_agent_response, mida nähti tunnis 17, edastab selle liidesesse vastuse keskele.
from agents import RunContextWrapper, function_tool
from chatkit.agents import AgentContext
@function_tool(description_override="Kuvab tellimuse üksikasjad kaardina.")
async def show_order(ctx: RunContextWrapper[AgentContext], number: str) -> str:
data = await get_order_data(number) # sinu andmete juurdepääs
await ctx.context.stream_widget(order_template.build(data))
return f"Tellimuse {number} kaart on kuvatud."
Lisa tööriist agendi tools loendisse. Tööriista tagastatud string teenib mudelit, mis teab seega, et kaart on ekraanil, ja saab seda kommenteerida, selle asemel et seda korrata.
Klõpsatav loend
Valiku pakkumiseks esitab ListView klõpsatavad read. Iga ListViewItem võib kanda tegevust, mis käivitub klõpsamisel ilma, et kasutaja peaks midagi trükkima; järgmine tund näitab, kuidas seda serveripoolselt käsitleda.
LIST_TEMPLATE = """
{
"type": "ListView",
"limit": 5,
"children": [
{%- for o in orders %}
{
"type": "ListViewItem",
"key": {{ o.number | tojson }},
"onClickAction": {"type": "order.open", "payload": {"number": {{ o.number | tojson }}}},
"children": [
{"type": "Col", "children": [
{"type": "Text", "value": {{ ("Order " ~ o.number) | tojson }},
{"type": "Caption", "value": {{ o.date | tojson }}}
]}
]
}{% if not loop.last %},{% endif %}
{%- endfor %}
]
}
"""
order_list_template = WidgetTemplate({"version": "1.0", "name": "order_list", "template": LIST_TEMPLATE})
list_widget = order_list_template.build({"orders": [{"number": "C-42", "date": "November 2"}, {"number": "C-41", "date": "October 28"}]})
Piirangust limit kaugemale kuvab ChatKit lingi „vaata rohkem“.
Vidina uuendamine kuvamise ajal
Vidin võib kasutaja silme all muutuda, näiteks mustandi kuvamiseks, mida mudel parajasti kirjutab. Anna stream_widget-ile asünkroonne generaator, mis toodab vidina järjestikuseid olekuid: ChatKit arvutab erinevused ja saadab ainult muutunud osa.
from collections.abc import AsyncGenerator
from chatkit.widgets import DynamicWidgetRoot, WidgetTemplate
draft_template = WidgetTemplate({
"version": "1.0",
"name": "draft",
"template": """{"type": "Card", "children": [
{"type": "Title", "value": "Draft"},
{"type": "Text", "id": "body", "value": {{ text | tojson }}, "streaming": {{ in_progress | tojson }}}
]}""",
})
async def streaming_draft(chunks: AsyncGenerator[str, None]) -> AsyncGenerator[DynamicWidgetRoot, None]:
text = ""
async for chunk in chunks:
text += chunk
yield draft_template.build({"text": text, "in_progress": True})
# Lõppolek, kui tekst on valmis
yield draft_template.build({"text": text, "in_progress": False})
Ainult Text ja Markdown komponendid, millel on id, kuvavad oma uuendusi voona, sõna haaval; teiste puhul asendab ChatKit vidina muudetud osa.
Mis saab Pythoni klassidest?
Kohtad isegi OpenAI juhendites vidinaid, mis on ehitatud klassidega: Card(children=[Text(value="…")]). Need toimivad endiselt, kuid openai-chatkit 1.6.5 SDK kuulutab need iganenuks WidgetTemplate kasuks: nende kasutamine tekitab hoiatuse, viidates .widget failidele. Uue projekti puhul alusta mallidest. Olemasoleva projekti puhul vii üle oma tempos: hoiatus ei blokeeri midagi, kuid iganenud klass võib tulevases versioonis kaduda.
Millal vidinat kasutada
Dokumentatsioon toob välja tüüpilised kasutusjuhud:
- struktureeritud sisu kogumine vormiga või rikka tulemuse (tabel, kaart, diagramm) esitamine, mida tekst halvasti edasi annab;
- valiku pakkumine mitme variandi vahel;
- vidina kombineerimine tegevustega, et valideerida valik, kinnitada samm või käivitada serveripoolne töötlemine;
- lühikese selgitava teksti kõrvale interaktiivse käsuga kaasamine.
Vastupidiselt ära paiguta neid igale poole. Vidin, mis kordab sõna-sõnalt seda, mida tekst ütleb, ei lisa midagi, ja kaartidega küllastunud vestlus muutub sama raskesti loetavaks kui tekstisein.
Peamised punktid
- ChatKiti vidin on sinu serveri loodud deklaratiiivne kirjeldus (JSON), mitte Reacti komponent: ChatKit renderdab selle ise
- Kolm konteinerit:
Card(iseseisev sisu),ListView(valikute loend),Basic(üksuste eelvaated) - Kujunda Vidinate koostajas, ekspordi
.widgetfail, laadi seeWidgetTemplate.from_file(...)-ga ja täidabuild(data)-ga; klassidCard,Text… on iganenud - Edasta
stream_widget-garespond-ist või agendi tööriistastctx.context.stream_widgetkaudu - Asünkroonne generaator uuendab vidinat reaalajas; ainult
TextjaMarkdownkoosid-ga voogavad sõna haaval