Это руководство объясняет, как создавать, настраивать и интегрировать пользовательские инструменты ИИ в плагине Discourse AI, позволяя администраторам расширять возможности бота с помощью определенных пользователем функций JavaScript.
Требуемый уровень доступа пользователя: Администратор
Инструменты — это программируемые функции, которые могут использоваться ботом ИИ для выполнения конкретных задач или получения информации, выходящей за рамки простых текстовых ответов. Эти инструменты представляют собой скрипты или интеграции, позволяющие боту взаимодействовать с внешними API, манипулировать данными или выполнять дополнительные функции для расширения своих возможностей.
Краткое содержание
В этой документации рассматриваются следующие темы:
- Создание нового пользовательского инструмента ИИ
- Настройка параметров и скриптов инструмента
- Доступные API для скриптов инструментов
- Интеграция пользовательских инструментов с персонажами ИИ
- Тестирование и устранение неполадок пользовательских инструментов
Создание нового пользовательского инструмента ИИ
Чтобы создать новый инструмент ИИ:
- Перейдите в Панель администратора > Плагины > Discourse AI > Инструменты
- Нажмите «Новый инструмент» (вы можете использовать существующие предустановки, чтобы ознакомиться с возможностями)
- Заполните следующие поля:
- Имя: Название инструмента, отображаемое для LLM
- Описание: Описание инструмента, отображаемое для LLM
- Краткое описание: Краткое описание того, что делает инструмент для помощи пользователям (отображается в деталях)
- Параметры: Определите входные данные, необходимые вашему инструменту, как они будут представлены LLM
- Скрипт: Код JavaScript, обеспечивающий работу вашего инструмента
- Нажмите «Сохранить»
Настройка скриптов инструментов
Доступные API
Ваши скрипты инструментов имеют доступ к следующим API:
-
HTTP-запросы:
http.get(url, options) http.post(url, options) http.put(url, options) http.patch(url, options) http.delete(url, options)Используйте их для взаимодействия со внешними сервисами. Вы можете использовать
optionsдля указания заголовков и тела HTTP-запроса:http.get(url, { headers: { "Authorization": "Bearer key" } }) http.post(url, { headers: { "Content-Type": "application/json" }, body: { key: "value" } }) http.patch(url, { headers: { "Authorization": "Bearer key" }, body: "some body" }) http.delete(url, { headers: { "Authorization": "Bearer key" } }) http.put(url, { headers: { "Authorization": "Bearer key" }, body: "some body" })Все методы HTTP возвращают объект
{ status: number, body: string }. -
Интеграция с LLM (языковой моделью):
llm.truncate(text, length)Обрезает текст до указанной длины в токенах на основе токенизатора настроенной LLM.
llm.generate(prompt, options)Генерирует текст с использованием настроенной LLM. Промпт может быть простой строкой или структурированным объектом, например
{ messages: [{ type: "system", content: "..." }, { type: "user", content: "..." }] }. Опции включаютjson: trueдля запроса и автоматического парсинга вывода в формате JSON, а такжеtemperature,top_p,max_tokensиstop_sequences. -
Интеграция пользовательских загрузок (RAG)
index.search(query, { filenames: ["file.pdf"], limit: 10 })Ищет фрагменты документов RAG, индексированных и прикрепленных к этому инструменту. Возвращает
Array<{ fragment: string, metadata: string | null }>, отсортированный по релевантности. Ограничение по умолчанию — 10, максимум — 200.index.getFile(filename)Извлекает полное содержимое загруженного файла RAG по его точному имени файла. Возвращает полный текст или
null, если файл не найден. -
Поддержка загрузок
upload.create(filename, base_64_content)Создает новую загрузку. Возвращает
{ id: number, url: string, short_url: string }.upload.getUrl(shortUrl)По короткому URL (например,
upload://12345) возвращает полный URL, совместимый с CDN.upload.getBase64(uploadIdOrShortUrl, maxPixels)Получает содержимое существующей загрузки в кодировке base64. Принимает ID загрузки (число) или короткий URL (строку). Необязательный параметр
maxPixelsдля автоматического изменения размера изображения (по умолчанию: 10 000 000). -
Контроль цепочки выполнения
chain.setCustomRaw(raw)Устанавливает окончательное необработанное содержимое поста бота и останавливает цепочку выполнения инструмента. Полезно для инструментов, которые напрямую генерируют полный ответ (например, инструменты генерации изображений).
-
Управление секретами
secrets.get(alias)Возвращает значение учетных данных, связанное с указанным псевдонимом. Псевдонимы определяются в конфигурации контрактов секретов инструмента и привязываются к секретам ИИ в панели администратора. Выбрасывает ошибку, если псевдоним не объявлен, не привязан или отсутствуют учетные данные.
const apiKey = secrets.get("my_api_key"); -
Интеграция с Discourse
Инструменты могут напрямую взаимодействовать с данными Discourse:
discourse.baseUrl // Базовый URL сайта discourse.search(params) // Выполнить поиск в Discourse discourse.getPost(post_id) // Получить детали поста (включая необработанное содержимое) discourse.getTopic(topic_id) // Получить детали темы (теги, категория и т. д.) discourse.getUser(id_or_username) // Получить детали пользователя discourse.createTopic(params) // Создать новую тему discourse.createPost(params) // Создать новый пост/ответ discourse.editPost(post_id, raw, options) // Изменить содержимое поста discourse.editTopic(topic_id, updates, options) // Изменить свойства темы (теги, категория, видимость) discourse.createChatMessage(params) // Отправить сообщение в чате discourse.createStagedUser(params) // Создать подготовленного пользователя discourse.getAgent(name) // Получить другого агента ИИ (с методом respondTo) discourse.updateAgent(name, updates) // Обновить конфигурацию агента ИИ discourse.getCustomField(type, id, key) // Читать пользовательское поле в посте/теме/пользователе discourse.setCustomField(type, id, key, value) // Устанавливать пользовательское поле в посте/теме/пользователе -
Объект контекста
Объект
contextпредоставляет информацию о том, где выполняется инструмент:- Контекст разговора бота:
context.post_id,context.topic_id,context.private_message,context.participants,context.username,context.user_id - Контекст чата:
context.message_id,context.channel_id,context.username - Контекст автоматизации:
context.post_id,context.topic_id,context.username,context.user_id,context.feature_name,context.feature_context - Общие свойства:
context.site_url,context.site_title,context.site_description
- Контекст разговора бота:
Обязательные функции
Ваш скрипт должен реализовывать:
invoke(params): Основная функция, которая выполняется при вызове инструмента
Он также может опционально реализовывать:
details(): Возвращает строку (может включать базовый HTML), описывающую выполнение инструмента, отображаемую в интерфейсе чатаcustomSystemMessage(): Вызывается во время сборки промпта (не во время вызова инструмента). Возвращает строку, добавляемую к системному промпту, илиnull/undefinedдля пропуска. Имеет доступ к объектамcontext,discourseиindex.
Пример скрипта:
function invoke(params) {
let result = http.get("https://api.example.com/data?query=" + params.query);
return JSON.parse(result.body);
}
function details() {
return "Получены данные из Example API";
}
Ограничения и безопасность
- Тайм-аут выполнения: Тайм-аут по умолчанию составляет 2000 мс времени обработки скрипта. Таймер приостанавливается во время внешних HTTP-запросов (
http.*) и вызовов LLM (llm.generate), поэтому учитывается только время обработки самого скрипта. - Память: Максимальный лимит кучи V8 — 10 МБ
- HTTP-запросы: Максимум 20 запросов за одно выполнение инструмента
- Песочница: Скрипты выполняются в ограниченной среде JavaScript V8 (через MiniRacer). Нет доступа к глобальным объектам браузера, файловой системе хоста или серверным библиотекам. Сетевые запросы проксируются через бэкенд Discourse.
Тестирование вашего инструмента
Вам следует тестировать любой созданный инструмент, чтобы убедиться, что результаты, предоставляемые LLM, соответствуют вашим ожиданиям.
Интеграция инструментов с персонажами ИИ
Чтобы добавить свой пользовательский инструмент к персонажу ИИ:
- Перейдите в Панель администратора > Плагины > Discourse AI > Персонажи
- Отредактируйте существующий персонаж или создайте новый
- В разделе «Инструменты» вы увидите свои пользовательские инструменты в списке наряду со встроенными
- Выберите свой пользовательский инструмент, чтобы добавить его к персонажу
Пользовательские инструменты в действии
Как только вы предоставите свой пользовательский инструмент LLM, он сможет использовать его для улучшения разговора.
Устранение неполадок
Если ваш инструмент работает не так, как ожидалось:
- Используйте интерфейс Тестирования, чтобы убедиться, что он ведет себя ожидаемым образом для ваших входных данных.
- Убедитесь, что ваша группа включена в
ai_bot_debugging_allowed_groups. Участники этой группы имеют полный доступ к транскриптам бота; вы можете просмотреть логи ИИ там. - Если происходит что-то неожиданное, перейдите на
https://SITENAME/logs, чтобы проверить наличие ошибок.