chat.use құқығы бар кілт: API кілтін жасау бетін қараңыз. Платформа балансындағы ақша: Платформа балансы және шығын бетін қараңыз. Және 1С қосылған компания, өйткені ЖИ-бухгалтер соның деректері бойынша жауап береді. 1С-ті қалай қосу керегі 1С қосу бөлімінде сипатталған.
Төмендегі мысалдардың бәрі екі орта айнымалысын қолданады. Кілт x-api-key тақырыбында беріледі. Оның орнына Authorization: Bearer tg_… жіберуге болады.
Кілтті тексеру және id-ді білу
workspace.id өрісінде жатыр және ws_ деп басталады. blocked_reason өрісі ЖИ-бухгалтерге сұраулардың қазір неге өтпейтінін көрсетеді, мысалы баланс бос болғандықтан. Онда null тұрса, бәрі дұрыс.
Екінші сұрау кілттің компанияларын қайтарады. Компанияның id-і data[].id ішінде жатыр және co_ деп басталады. Бұл id-лер қалған сұраулардың мекенжайларына қойылады.
connected өрісі мен қосылымды соңғы тексерудің нәтижесі бар.
Сұрақтың бағасын шамалау
Бұл сұрау тегін: модель жауап бермейді, баланстан ештеңе алынбайды.input_tokens, max_output_tokens, input_cost_tiyn және max_cost_tiyn. Сомалар тиынмен көрсетілген, 1 ₸ = 100 тиын. Бұл — модельді бір рет шақырудың бағалауы. Сұраққа жауап беру үшін ЖИ-бухгалтер әдетте модельді бірнеше рет шақырады, сондықтан нақты баға тек іс жүзінде белгілі болады.
Сұрақ қою
"stream": false болғанда жауап ЖИ-бухгалтер жұмысын аяқтаған соң бір JSON түрінде келеді. Бұл уақыт алуы мүмкін, сондықтан клиентіңізде күту уақытын қормен қойыңыз. Жауаптың негізгі өрістері:
answer— жауап мәтіні, Markdown түрінде.dialog_id— чаттың id-і, ол келесі сұраққа керек.proposals— ЖИ-бухгалтер жауап барысында 1С үшін дайындаған құжаттар.usage— токендер мен жауаптың бағасы,cost_tiynтиынмен.stop_reason— жауап немен аяқталды,end_turn«жауап дайын» дегенді білдіреді.
mode өрісі мұны шектейді: ask тек жауап беруді, document құжат дайындауды білдіреді.
Компания 1С-ке қосылмаған болса, сұрау 409 қайтарады. Платформа балансы бос болса, platform_balance_exhausted кодымен 402 келеді. Қалған бас тартулар Қателер мен шектеулер бетінде талданған.
Жауапты ағынмен алу
"stream": false бермесеңіз, жауап Server-Sent Events пішіміндегі оқиғалар ағынымен келеді. Осылай мәтінді пайда болуына қарай көрсетуге болады.
type өрісі бар JSON денесі болады. Бастау үшін үш түрі жеткілікті. text оқиғасы жауаптың кезекті бөлігін delta өрісінде әкеледі. error оқиғасы қате туралы хабарлайды, одан кейін ағын үзілмейді. done оқиғасы ең соңында келеді: онда answer өрісінде толық қорытынды жауап, cost_tiyn ішінде баға және stop_reason бар. Оқиғалардың қалған түрлері API анықтамасында сипатталған.
Чаттың id-і мен жауаптың нөмірі X-Dialog-Id және X-Turn-No тақырыптарында келеді. Байланыстың үзілуі жауапты тоқтатпайды: ЖИ-бухгалтер жұмысын соңына дейін жеткізеді. Оқиғаларды соңына дейін оқу үшін GET /v1/companies/{co}/chat/{id}/events мекенжайын Last-Event-ID тақырыбымен ашыңыз, сонда бұрын алынған оқиғалар қайталанбайды.
Чатты жалғастыру
Келесі сұрақ алдыңғыларын ескеруі үшін өткен жауаптағыdialog_id мәнін жіберіңіз.
turn_in_progress кодымен 409 алады. Чат жабық болса немесе ол енді жоқ болса, dialog_closed кодымен 409 немесе 410 келеді. Екі жағдайда да жаңа чат бастаңыз: сұрақты dialog_id өрісінсіз жіберіңіз.
Сұрауды ақша екі рет алынбайтындай қайталау
Желі сұрау кеткеннен кейін, бірақ жауап келгенге дейін үзіліп кетуі мүмкін. Қайталау екінші ақылы сұраққа айналмауы үшінIdempotency-Key тақырыбын кез келген өз бірегей мәніңізбен беріңіз, мысалы UUID.
Сол қайталау кілтімен және сол денемен жасалған қайталау ештеңені екінші рет орындамайды. Ол бұрынғы жауапты Idempotent-Replayed: true тақырыбымен қайтарады. Бірінші сұрау әлі орындалып жатса, idempotency_in_progress кодымен 409 келеді: күте тұрып, қайталаңыз. Сол қайталау кілті басқа денемен жіберілсе, idempotency_key_reused кодымен 422 келеді. Жаңа әрекетке жаңа мән керек.
Тек сәтті жауап есте сақталады, бас тартудан кейін қайталау жаңадан орындалады. Мән бір тәулік сақталады.
Әрі қарай
- Оқиғаларды алу (вебхуктар): дайын құжаттар мен жауаптардың аяқталғаны туралы сауалсыз біліп отыру.
- Қателер мен шектеулер: бас тартуларды қалай талдау керек және сұраулар жиілігіне қалай тірелмеу керек.
- Платформа балансы және шығын: сұрау қанша тұрды және оны қайдан көруге болады.