ИИ-помощник сайта

This page has not been translated into English yet. The Russian original is below.

Сайт может отвечать посетителям на вопросы по собственной базе знаний. Для этого нужны две вещи: каталог assistant/ в проекте и элемент `Assistant` на странице.

Помощник — возможность REEEL-сайта: вопрос уходит на адрес самого сайта, и отвечает сервер, который раздаёт сайт. У экспортированного в статику сайта и в превью редактора отвечать некому.

Каталог assistant/

assistant/
  assistant.json            темы, лимиты, следующие шаги, запасной путь
  prompt.md                 кто такой помощник, словами владельца
  knowledge/<язык>/**.md    по чему он отвечает

Сайт этот каталог не раздаёт : с адреса сайта наружу идут только data/** и страницы.

Но тайником он от этого не становится. assistant/ — такие же файлы проекта, как остальные: они синхронизируются на платформу, и её адрес выдачи содержимого ( /content/{projectId}/… ) отдаёт любой синхронизированный файл тому, кто знает идентификатор проекта и прошёл выдачу доступа, — а она рассчитана на установленные приложения, не на проверку личности. Секретов сюда не кладите : ни в prompt.md , ни в assistant.json , ни в каталог.

Обязательна только база. Каталог с одним knowledge/ — рабочий помощник.

База знаний

Обычные markdown-файлы.

• По каталогу на язык ( knowledge/ru/ , knowledge/en/ ): посетителю отвечают по базе языка, на котором он спросил; если такой базы нет — по базе языка сайта по умолчанию.
• Файлы прямо в knowledge/ : одна база на всех.

Помощник отвечает только тем, что написано в базе . Каждое утверждение опирается на дословную цитату из прочитанного раздела; чего в базе нет, того он не скажет.

Документ и страница

Документ считается страницей по своему же пути:

Под утверждением стоит ссылка на эту страницу и на заголовок раздела. Если такой страницы на сайте нет, источник называется без ссылки. Другую страницу документу назначает links .

Те же файлы могут быть страницами: страница, которая рисует текст через `Markdown src:` из assistant/knowledge/ , — одновременно и страница, и запись в базе.

Markdown src:$"assistant/knowledge/${strings.effectiveLocale}/project/domains.md"

assistant.json

Все поля необязательны.

{
  "topics": "Тарифы, оплата и публикация Acme.",
  "limits": {
    "questionChars": 400,
    "claims": 5,
    "perVisitorPerDay": 30,
    "offTopicBeforePause": 3,
    "pauseMinutes": 30
  },
  "actions": [
    {
      "id": "support",
      "title": { "ru": "Написать в поддержку", "en": "Write to support" },
      "url": "/help",
      "when": "документация не решает вопрос посетителя"
    }
  ],
  "fallback": {
    "text": { "ru": "Спросите нас напрямую.", "en": "Ask us directly." },
    "action": "support"
  },
  "messages": { "paused": { "ru": "На сегодня всё — позвоните нам." } },
  "links": { "pricing.md": "tiers" },
  "transcripts": true
}

Текст можно задать одной строкой на все языки или объектом по языкам.

Лимиты владелец только ужесточает. Потолки платформы — предел; число больше потолка читается как потолок.

Следующие шаги

Помощник не только отвечает, но и подводит к действию: записаться, скачать, написать в поддержку. when — единственное, что читает модель; она называет id , а подпись и адрес посетителю показываются из этого файла . Ссылок модель не пишет, и шага, которого нет в списке, предложить не может.

Сценарии и каталог: карточки в ответе

Часть ответов лучше показать, чем пересказать: тариф, услугу, товар, раздел сайта. Для этого у помощника есть сценарии — в assistant.json :

"scenarios": [
  { "id": "tiers", "when": "посетитель выбирает тариф", "catalog": "tiers" }
]

и каталог записей рядом с базой знаний — assistant/catalog/tiers.json :

[
  {
    "id": "studio",
    "about": "для команд от пяти человек, с общим доступом",
    "title": { "ru": "Студия", "en": "Studio" },
    "text": { "ru": "Для команд от пяти человек.", "en": "For teams of five or more." },
    "price": 4900,
    "image": "data/images/studio.png",
    "url": "/tier#studio"
  }
]

Как это работает:

• Модель видит список: сценарий, его when и по строке на запись — идентификатор и about . Больше ничего: ни цен, ни картинок, ни адресов.
• В ответе она называет идентификаторы записей. Сервер сверяет их со списком и подставляет поля из каталога на языке посетителя. Идентификатор, которого в каталоге нет, отбрасывается.
• В одном ответе не больше шести карточек. Карточки могут идти вместе с утверждениями или сами по себе.
• Список записей уходит модели перед каждым вопросом, поэтому каталог держите небольшим: до 12 сценариев, до 60 записей в каждом.
• Картинки кладите в data/** : каталог assistant/ наружу не раздаётся.
• Сценарий с ошибкой (нет файла каталога, файл не разбирается, вид text ) пропускается, а помощник продолжает работать без него.

Как нарисовать карточку на странице — в описании элемента `Assistant` .

prompt.md

Инструкция владельца: кто такой помощник и как он говорит. Секретов сюда не кладите — модель можно уговорить пересказать сказанное ей.

Что помощник делает сам

• Отвечает только по темам сайта. Вопрос не по теме получает мягкий отказ; после нескольких таких посетитель ставится на паузу, и ему предлагают fallback .
• Требует согласия. Без него вопрос не уходит со страницы.
• Проверяет незнакомца. После первого вопроса — невидимая проверка «я не бот»; посетителя, который её прошёл, больше не спрашивают.
• Помнит посетителя по cookie , которую сам выставляет. Скрипт страницы её не видит, чужой сайт предъявить не может.

Включение

Каталог assistant/ — заявка, а не разрешение: помощник появляется у сайта, когда платформа включила его для проекта.

Разговоры

Если владелец не запретил ( transcripts: false ), вопросы и ответы сохраняются для улучшения базы: видно, о чём спрашивают и чего в базе не хватает. Об этом посетителю нужно сказать рядом с полем вопроса и в политике сайта.