Node SDK

ChatBotKit Node SDK е комплект за разработка на софтуер, който позволява на разработчиците да създават интерфейси и чатботове с изкуствен интелект за разговори. Той предоставя набор от инструменти, библиотеки и API, които помагат на разработчиците да създават чатботове за различни платформи.

SDKs

ChatBotKit SDK за Node е съставен от няколко отделни пакета. Всеки пакет предоставя специфични функции за целевата платформа:

Инсталация

To install ChatBotKit Node SDK, simply run the following command in your terminal:

npm install @chatbotkit/sdk

Additional SDKs for your platform of choice can be installed in a similar way:

npm install @chatbotkit/next @chatbotkit/react

Употреба

ChatBotKit Node SDK поддържа както CommonJS, така и модулите в готов вид. Можете да импортирате SDK в кода си по следния начин:

const { ChatBotKit } = require('@chatbotkit/sdk')

...или ако предпочитате стила на модула, можете да направите това:

import { ChatBotKit } from '@chatbotkit/sdk'

Документацията за TypeScript е налична и на адрес https://chatbotkit.github.io/node-sdk/.

Съвместимост

Сайтът Node SDK е съвместим с всички среди на JavaScript, включително: AWS Lambda, Vercel Serverless, Vercel Edge, Cloudflare Workers, браузър и много други.

Инстанциране

SDK се състои от няколко клиентски библиотеки. Клиентите са обекти от класове, които съдържат всички налични методи за взаимодействие с определена категория методи на API в ChatBotKit. Методите могат да бъдат импортирани и използвани самостоятелно. Поради това се поддържат напълно както обектно ориентирани, така и функционални подходи за програмиране.

Импортиране на върха ChatBotKit ви дава достъп до всички функционалности. Например:

// access all clients

import { ChatBotKit } from '@chatbotkit/sdk'

Отделни клиентски класове могат да бъдат импортирани по следния начин:

// access only the conversation client

import { ConversationClient } from '@chatbotkit/sdk/conversation/index.js'

Преди да започнете да използвате клиент, трябва да създадете инстанция на класа. Този принцип се прилага за всички клиенти на SDK.

import { ConversationClient } from '@chatbotkit/sdk/conversation/index.js'

const client = new ConversationClient({
  // options
})

Достъпът до отделните методи е толкова лесен, колкото да импортирате базовия клиент и желаната версия на метода. Например:

import { Client } from '@chatbotkit/sdk/client.js'
import { conversationList } from '@chatbotkit/sdk/conversation/v1.js'

const client = new Client({
  // options
})

await conversationList(client)

Удостоверяване

Всички клиенти трябва да бъдат инстанцирани с тайна.

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

Тайната може да бъде API токен, който ви дава достъп до всички методи на API, или ограничен сесиен токен, който ви дава достъп само до няколко метода за разговори. Последната се използва за сигурен достъп до разговорите, свързани с отделните ви потребители.

В допълнение към тайната можете също така да подадете runAsUserId ако трябва да задействате заявката не от името на акаунт на дете в конфигурация на акаунт родител-дете (вж. Партньорски API). Следващият пример демонстрира как да конфигурирате SDK:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here',
  runAsUserId: '...the child user id here'
})

Страница

Всички методи за списъци поддържат страниране с курсор. Резултатите са винаги в обратен хронологичен ред, което означава, че най-новите елементи са винаги най-отгоре. За да получите следващата страница, курсорът трябва да посочи идентификатора на последния елемент. Например:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

// get first page

const page1 = await client.conversation.list()

// get the second page

const page2 = await client.conversation.list({ cursor: page1.items.at(-1).id })

Можете също така да използвате стрийминг за достъп до всички елементи, без ръчно да странирате резултатите. Тази мощна функция е разгледана в следващия раздел.

Стрийминг

Streaming is a powerful feature which allows you to access large quantities of ChatBotKit data without manually paginating the results. Streaming is also useful to tap into ChatBotKit events when interacting with your ChatBotKit bots and integrations. Streaming simplifies tremendously all types of access patterns.

Всички методи за списъци поддържат по подразбиране поточно предаване, което означава, че можем лесно да прелистваме всички елементи и да имаме достъп до всички резултати без ръчно прелистване. Например:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

// access all conversations via the .stream() AsyncGenerator

for await (const { type, data } of client.conversation.list().stream()) {
  if (type === 'item') {
	  console.log('conversation', data)
  }
}

По подобен начин можем да получим достъп до различни събития, когато извършваме операции по завършване и други видове операции, например:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const messages = [
  {
    type: 'user',
    text: 'Hello!'
  }
]

// access all conversations via the .stream() AsyncGenerator

for await (const { type, data } of client.conversation.complete(null, { messages }).stream()) {
  if (type === 'token') {
    console.log('token', data)
  }
}

Забележете, че методът stream дава обекти, съставени от параметри за тип и данни. Типът съответства на типа на събитието, а данните представляват свързаната с него информация. Методи като conversation.complete дават различни типове събития, а не само обикновени токени.

Изключения

Всички методи могат да хвърлят изключения. Всички изключения имат стандартен подпис за грешка. Например:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

try {
  const page = await client.conversation.list()
} catch (e) {
  console.log('message', e.message)
  console.log('code', e.code)
}

Всяко изключение съдържа следните свойства:

Общите типове кодове включват:

Всички изключения на API дават и съответния код на състоянието.

Реакция

ChatBotKit React SDK предлага цялостен набор от функции и възможности, включително:

• userConversationManager: React Hook за управление на потока от разговори. Обслужва цялата тежка работа по изпращане и получаване на съобщения, както и индикатори за мислене и писане.
• AutoTextarea: Компонент на React, който автоматично променя размера на текстовото поле, за да се побере в съдържанието. Полезен за интерфейси за чат, които позволяват на потребителите да въвеждат съобщения.
• ChatInput: Компонент на React, който предоставя интерфейс за въвеждане на чат. Полезен за интерфейси за чат, които позволяват на потребителите да въвеждат съобщения. Той автоматично обработва модификатори като ctrl, cmd и shift.
• ChatMessages: Компонент на React, който предоставя интерфейс за чат съобщения. Полезен за интерфейси за чат за показване на съобщения.

Следваща

The ChatBotKit SDK for Next.js is crafted to integrate chatbot functionalities seamlessly into Next.js applications, specifically optimized for Next.js Edge runtime environments.

В момента SDK включва следните помощни програми:

• поток: Тази функция може да се използва за поточно предаване на всеки поточно предаван отговор на ChatBotKit към клиента. Тя автоматично ще кодира отговора като JSONL и е напълно съвместима с @chatbotkit/react useConversationManager кука.

Примери

В следващия раздел ще разгледаме различни типични случаи на използване, като ще ви предоставим практически идеи за разбиране. За тези, които търсят по-сложни сценарии, в официалното хранилище на Node SDK Examples (примери) има богат набор от разширени примери. Този ресурс е предназначен да обогати допълнително вашите знания и умения.

Завършване на разговора

Можете да завършите следващото съобщение в даден разговор, като предоставите пълната история на разговора до момента. Например, за да получите следващото съобщение в разговора, можете да направите следното:

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const messages = [
  {
    type: 'user',
    text: 'Hello!'
  }
]

const { text } = await client.conversation.complete({ model: 'gpt-4', messages })

console.log('bot:', text)

Обърнете внимание, че целият метод подлежи на 30-секунден таймаут. Поради тази причина препоръчваме вместо това да използвате API за поточно предаване.

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const messages = [
  {
    type: 'user',
    text: 'Hello!'
  }
]

// access all conversations via the .stream() AsyncGenerator

for await (const { type, data } of client.conversation.complete(null, { model: 'gpt-4', messages }).stream()) {
  if (type === 'result') {
    console.log('bot:', data)
  }
}

Примерът по-горе не съхранява разговора ви. Следващият пример демонстрира как да направите това.

Създаване и завършване на разговори

За да съхраним разговор, първо трябва да го създадем.

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const conversation = await client.conversation.create({
  backstory: '...your backstroy here',
  model: 'gpt-4'
})

След това можем да взаимодействаме с разговора, подобно на предишния пример.

for await (const { type, data } of conversation.complete(null, { text: 'Hello!' }).stream()) {
  if (type === 'result') {
    console.log('bot:', data)
  }
}

Забележете, че вместо да изпращаме пълната история на разговора, изпращаме само съобщението на потребителя с параметъра текст.

Можете също така да го разделите на две стъпки. Това е особено полезно, когато имате асинхронен процес, при който съобщението се улавя на едно място, но се завършва в завършена в друга част на кода. Например:

await conversation.send({ text: 'Hello!' })

Можем да получим съобщението на бота по следния начин:

const { text } = await conversation.receive()

Имайте предвид, че методът за получаване също поддържа поточно предаване.

Сесии за разговори

To enable secure client-side interaction, we need to create a session and initialise the SDK client-side. We are still using the same code-base server-side and client-side without swapping our mental model. Here is an example.

// server

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const conversation = await client.conversation.create({
  backstory: '...your backstroy here',
  model: 'gpt-4'
})

const { token } = await client.conversation.session.create(conversation.id)

// pass the token to the client

На клиента можем да използваме токена за сигурно взаимодействие с API.

// client

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: token // is the token passed from the server
})

await conversation.send({ text: 'Hello!' })

const { text } = await conversation.receive()

Имайте предвид, че сесиите изтичат. Предоставяме времето на изтичане на сървъра в параметъра expiresAt respond. Трябва да следите това време или да обработвате изключения (кодNOT_AUTHORIZED ). Също така имайте предвид, че токените за сесии са ограничени само до текущия разговор. С други думи, потребителят може да взаимодейства само с чатбота, но не и с друг метод в API.

Създаване на набори от данни и записи

A common use-case is to create and import Datasets and Dataset Records. This is a very easy process.

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const dataset = await client.dataset.create({
  name: '...the dataset name',
  description: '...the dataset description',
})

await client.dataset.record.create(dataset.id, {
  text: '...the record text'
})

Търсене на набори от данни

Searching the dataset is part of the conversational flow so typically you do not need to do that when interacting with your conversational AI bot. However, this method is also available in case it is needed. This is how to use it.

import { ChatBotKit } from '@chatbotkit/sdk'

const client = new ChatBotKit({
  secret: '...your secret here'
})

const { records } = await client.dataset.search('...dataset id', '...my search')

// do something wihth the found records

Заключение

С това приключва документацията за ChatBotKit Node SDK. За повече информация как да използвате SDK, моля, обърнете се към официалното хранилище на адрес https://github.com/chatbotkit/node-sdk.