Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Interaktīvie logrīki

Nodarbība 19 no 25 Atjaunota 2026. gada 3. novembris Programmētājs
Šajā lapā
  1. Kas ir ChatKit logrīks?
  2. Konteineri un komponenti
  3. Logrīka projektēšana Logrīku veidotājā
  4. Ko satur veidne
  5. Logrīka attēlošana no respond
  6. Aģenta lēmuma pieņemšana
  7. Noklikšķināms saraksts
  8. Logrīka atjaunināšana attēlošanas laikā
  9. Kur palika Python klases?
  10. Kad lietot logrīku
  11. Galvenās atziņas

Nodarbība pārrakstīta 2026. gada 3. novembrī. Iepriekšējā versijā logrīki bija aprakstīti kā izstrādātāja rakstīti React komponenti, kas reģistrēti saskarnē, izmantojot neeksistējošu @openai/chatkit/react moduli. ChatKit vidē logrīks ir deklaratīvs apraksts, ko veido tavs serveris un ko ChatKit attēlo pats. Šī nodarbība balstās uz openai-chatkit Python SDK 1.6.5 versiju, kas veido logrīkus no .widget veidnēm: tās Card, Text, Badge… klases ir novecojušas. Piemēri tika izpildīti uz lokāla ChatKit servera. Avoti: ChatKit logrīki · Logrīki (Python SDK) · Interaktīvu atbilžu veidošana ar logrīkiem · Logrīku veidotājs.

Kas ir ChatKit logrīks?

Teksta atbilde pietiek skaidrojumiem. Taču, lai prezentētu pasūtījumu, salīdzinātu trīs plānus vai apstiprinātu tikšanos, teksts ātri pārvēršas par rindu sienu, ko lietotājam jāpārlasa. Logrīki aizstāj šo tekstu ar saskarni: kartiņu, sarakstu, veidlapu vai diagrammu, kas tiek attēlota tieši sarunas plūsmā.

Pieeja ir deklaratīva. Tavs serveris nenodrošina nedz HTML, nedz React komponenti: tas apraksta logrīku JSON formātā, izmantojot slēgtu komponentu un īpašību kopu, un nosūta to pavedienam kā pilnvērtīgu elementu (WidgetItem). ChatKit to uzzīmē ar saviem komponentiem, izmantojot iepriekšējā nodarbībā apskatītās tēmas krāsas. No tā izriet divas sekas:

  • Tu vari izmantot tikai tos komponentus un īpašības, ko ChatKit pazīst. Pretī tu saņem attēlojumu, kas ir konsekvents ar pārējo saskarni, un neviens patvaļīgs HTML vai JavaScript no servera nenonāk lapā.
  • Logrīks ir daļa no vēstures: nākamajos sarunas posmos tas tiek pārvērsts par ievadi modelim, kas tādējādi „redz”, ko tas parādīja lietotājam.

Konteineri un komponenti

Katram logrīkam ir sakne, ko izvēlas no trim konteineriem:

KonteinersLietojums
CardAtsevišķs saturs: kopsavilkums, apstiprinājums, veidlapa. Pieņem statusu un apstiprināšanas/atcelšanas pogas zem satura
ListViewOpciju kopa: restorāni, faili, pasūtījumi. Tā bērni ir ListViewItem, ar iebūvētu „skatīt vairāk” funkcionalitāti (limit)
BasicRezervēts vienību priekšskatījumiem, kas tiek parādīti, uzbraucot ar peli uz pieminējuma

Iekšpusē tu saliec kopā komponentus: tekstu (Title, Text, Caption, Markdown), etiķetes (Badge), izkārtojumu (Row, Col, Box, Spacer, Divider), multividi (Image, Icon), komandas (Button, Select, DatePicker, Checkbox, RadioGroup, Input, Textarea, ko Form var grupēt), diagrammas (Chart) un animācijas (Transition). Logrīku veidotāja komponentu lapa uzskaita katra īpašības, piedāvājot arī redaktoru to izmēģināšanai.

Logrīka projektēšana Logrīku veidotājā

Ieteicamais darbplūsma sākas ChatKit Studio Logrīku veidotājā. Tu tur projektē izkārtojumu, aizpildi datu paneli ar paraugvērtībām, lai novērtētu attēlojumu, un pēc tam eksportē .widget failu. Tas ir JSON fails, kas apvieno veidni, sagaidāmo datu shēmu (jsonSchema) un parauga datus. Versiju kontroli veic kopā ar servera kodu, piemēram, mapē widgets/.

Servera pusē WidgetTemplate ielādē failu, bet build aizpilda to ar reāliem datiem:

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

Relatīvais ceļš tiek atrisināts no Python faila, kas izsauc from_file, nevis no palaišanas direktorija. build pieņem vārdnīcu vai Pydantic modeli.

Ko satur veidne

Veidne ir Jinja modelis, kas ģenerē logrīka JSON. Pasūtījuma kartiņas veidne izskatās šādi:

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

Tu reti rakstīsi veidni ar roku, jo Logrīku veidotājs to ģenerē. Taču tās lasīšana ietaupīs laiku, kad radīsies pirmā problēma. Trīs piezīmes:

  • Filtrs tojson pārvērš katru vērtību derīgā JSON (citētā virkne, boolean kā true vai false) un atbrīvojas no speciālajām zīmēm: apostrofs vai pēdiņas produkta nosaukumā nesabojās JSON.
  • Jinja darbojas stingrā režīmā: trūkstoši dati liek build izgāzties, nevis ģenerēt pus tukšu logrīku.
  • build nepārbauda datus pret jsonSchema. Šī shēma dokumentē datus; ja tie nāk no rīka vai datubāzes, validē tos iepriekš, piemēram, ar Pydantic modeli.

Konstruktors WidgetTemplate(...) pieņem to pašu saturu kā jau nolasīts .widget fails: tas ir ērti testiem vai veidnei, ko ģenerē tavs kods.

Logrīka attēlošana no respond

Lai nosūtītu logrīku pavedienam, stream_widget ģenerē atbilstošos ChatKit notikumus. Tu tos nodod tālāk no savas respond metodes:

from chatkit.server import stream_widget

# Tavā ChatKitServer klasē
async def respond(self, thread, input_user_message, context):
    card = order_template.build(await get_order_data("C-42"))  # tavi dati
    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 ir teksts, kas tiek kopēts starpliktuvē, kad lietotājs noklikšķina uz kopēšanas pogas zem atbildes. Serveris pats saglabā logrīku veikalā (store), tāpat kā jebkuru raidītu elementu.

Aģenta lēmuma pieņemšana

Visbiežāk ne tavs kods izlemj parādīt kartiņu, bet gan aģents, kad saruna to prasa. Piešķir tam rīku, kas raida logrīku, izmantojot AgentContext.stream_widget: stream_agent_response, ko apskatījām 17. nodarbībā, nodod to saskarnei tieši atbildes vidū.

from agents import RunContextWrapper, function_tool
from chatkit.agents import AgentContext


@function_tool(description_override="Displays order details as a card.")
async def show_order(ctx: RunContextWrapper[AgentContext], number: str) -> str:
    data = await get_order_data(number)  # tava datu piekļuve
    await ctx.context.stream_widget(order_template.build(data))
    return f"The card for order {number} is displayed."

Pievieno rīku aģenta tools sarakstam. Virkne, ko atgriež rīks, kalpo modelim, kas tādējādi zina, ka kartiņa ir ekrānā, un var to komentēt, nevis atkārtot.

Noklikšķināms saraksts

Lai piedāvātu izvēli, ListView prezentē noklikšķināmas rindas. Katrs ListViewItem var nest darbību, kas tiek aktivizēta, noklikšķinot, lietotājam neko nerakstot; nākamajā nodarbībā parādīsim, kā to apstrādāt servera pusē.

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

Pārsniedzot limit, ChatKit parāda saiti „skatīt vairāk”.

Logrīka atjaunināšana attēlošanas laikā

Logrīks var evolucionēt lietotāja acu priekšā, piemēram, lai parādītu melnrakstu, ko modelis raksta. Padod stream_widget asinhronu ģeneratoru, kas ražo secīgus logrīka stāvokļus: ChatKit aprēķina atšķirības un nosūta tikai to, kas mainījies.

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})
    # Beigu stāvoklis, kad teksts ir pabeigts
    yield draft_template.build({"text": text, "in_progress": False})

Tikai Text un Markdown komponenti ar id rāda savus atjauninājumus straumē, vārdu pa vārdam; pārējiem ChatKit aizstāj modificēto logrīka daļu.

Kur palika Python klases?

Tu sastapsi, pat OpenAI rokasgrāmatās, logrīkus, kas veidoti ar klasēm: Card(children=[Text(value="…")]). Tās joprojām darbojas, taču openai-chatkit 1.6.5 SDK tās atzīmējis kā novecojušas par labu WidgetTemplate: to lietošana izraisa brīdinājumu, kas norāda uz .widget failiem. Jaunam projektam sāc no veidnēm. Esošam projektam migrē savu tempu: brīdinājums neko nebloķē, taču novecojusi klase var pazust nākamajā versijā.

Kad lietot logrīku

Dokumentācija min tipiskus lietojumus:

  • strukturētas ievades vākšana ar veidlapu vai bagātīga rezultāta (tabula, kartiņa, diagramma) prezentēšana, ko teksts attēlo slikti;
  • izvēles piedāvāšana starp vairākām opcijām;
  • logrīka kombinēšana ar darbībām, lai validētu atlasi, apstiprinātu soli vai uzsāktu apstrādi servera pusē;
  • īsa skaidrojoša teksta papildināšana ar interaktīvu komandu.

Turpretī neliec tos visur. Logrīks, kas vārds vārdā atkārto to, ko saka teksts, nedod nekādu pievienoto vērtību, un saruna, kas piesātināta ar kartiņām, kļūst tikpat grūti lasāma kā teksta siena.

Galvenās atziņas

  • ChatKit logrīks ir deklaratīvs apraksts (JSON), ko veido tavs serveris, nevis React komponente: ChatKit to attēlo pats
  • Trīs konteineri: Card (atsevišķs saturs), ListView (opciju saraksts), Basic (vienību priekšskatījumi)
  • Projektē Logrīku veidotājā, eksportē .widget failu, ielādē ar WidgetTemplate.from_file(...) un aizpildi ar build(data); klases Card, Text… ir novecojušas
  • Raidi ar stream_widget no respond vai no aģenta rīka ar ctx.context.stream_widget
  • Asinhrons ģenerators atjaunina logrīku tiešraidē; tikai Text un Markdown ar id straumē vārdu pa vārdam