Dskr.dev

Как правильно установить node.js окружение?

Mon, 18 Sep 2023 00:00:00 GMT

Установка Node.JS

Существует несколько способов установки Node.JS и сложно понять какой из них лучше. В этой статье мы сравним разные способы (прямая установка, системные пакетные менеджеры, nvm, n, nodenv, volta, fnm). TLDR: я предпочитаю использовать fnm

Самый простой вариант установить Node.JS это пойти на nodejs.org и скачать установщик. Но это не лучшая идея. Вариант чуть получше, воспользоваться системным пакетным менеджером(brew, apt, dnf). В обоих случаях нельзя быстро сменить версию Node.JS. Часто актуальный проект требует свежую LTS версию, легаси проект работает под предыдущим LTS, а так же хочется попробовать новые фишки из Current версии.

Самое популярное решение это Node Version Manager nvm. Но, во-первых, он невероятно медленный. Каждое открытие консоли с установленным nvm будет занимать до нескольких секунд. Во-вторых, он не поддерживает fish и windows. В-третьих, глобально установленные пакеты прийдётся ставить каждый раз заново, либо нужно прописывать их в специальном файле. n и nodenv имеют примерно те же проблемы.

Следующее решение это Volta. Написано на Rust, а значит должно быть быстрым. Поддерживает fish и даже windows. Глобально установленные библиотеки работают даже после смены версии. Но не поддерживается .nvmrc/.node-version файлы, хотя на замену тут предлагается писать версию ноды в package.json. Ещё из недостатков, поддержка pnpm находится в экспериментальном режиме.

И наконец Fast Node Manager fnm. Написан также на Rust. Работает быстро и поддерживает всё что надо. Устанавливается fnm одной командой:

curl -fsSL https://fnm.vercel.app/install | bash

Далее можно установить версию Node.JS которая будет использоваться по умолчанию:

fnm default 18

Теперь можно добавить в проект файл .node-version с указанием версии Node.JS, которая будет использоваться в этом проекте.

echo 18.17.0 > .node-version

При открытии консоли в папке с проектом, fnm автоматически включит нужную версию Node.JS.

Есть небольшой недостаток, если в проекте указана версия Node.JS которая не установлена, автоматически она не установится, но при открытии консоли отобразится ошибка. Для установки нужной версии нужно будет ввести целых две команды

fnm install
fnm use

Установка pnpm/yarn

Node.JS, начиная с версии 16.13, получил поддержку Corepack. Эта утилита позволяет использовать любой поддерживаемый пакетный менеджер без ручной установки. Всё что нужно сделать, это включить corepack:

corepack enable

После чего при первом использовании pnpm/yarn они автоматически установятся и будут работать.

Photo lib share - фото галерея своими руками

Mon, 12 Jun 2023 00:00:00 GMT

Идея написать свою фото галерею появилась у меня пару лет назад. И даже начал что-то писать, но довольно быстро забил. С тех времён у меня была почти готовая библиотека для создания красивого лэйаута. Photo flex layout - это имплементация Google Photo Flex Layout. Выпустил версию 1.0.0, подробнее про неё писал в Telegram канале.

В планах написать два модуля:

Photo lib - приложение для хранение и организации фоточек. Ставится он должен в идеале на NAS. Пока он не написан, использую synology photos. Но единственный его плюс, это неплохая синхронизация через мобильное приложение, в остальном одни минусы. Нет возможности посмотреть все фото наа карте, raw и jpeg не объединяются в одно фото, нет архива, нельзя поставить условие and при фильтрации по тегам. И это первое что пришло в голову
Photo lib share - галерея для шеринга фоточек и альбомов. Ставится он должен куда-нибудь на публичный сервер, чтоб можно было смотреть на фоточки даже если Photo lib не доступен. Начать я решил именно с этого модуля.

В данный момент готов MVP. Посмотреть на работу можно на dskr.photos. Исходники на GitHub.

Нулевая версия

Начал с того что взял старый код, выкинул всё что было не нужно, обновил зависимости и заставил это всё хоть как-то работать. Превью подготавливал с помощью sharp, mozjpeg, 80%, 1000 пикселей по длиной стороне. Превью генерировались во время индексации, что не очень удобно. Между беком и фронтом, просто http, на сервере koa. Метадата хранится в nedb. Эту версию так никуда и не выложил.

Первая версия

Добавил docker compose для нормального деплоя. Пришлось изучить как правильно писать докерфайлы. Долго матерился.

Базу поменял на postgres, взял orm prisma. До этого обычно использовал sequelize, это был первый опыт работы с призмой. В целом понравилось, из косяков, при кодогенерации нужно задавать валидную переменную окружения с строкой подключения к базе, что не очень хорошо ложится на логику использования докера. Описал одну единственную таблицу с нужными и не очень полями.

Sharp поменял на imgproxy. Но это оказалось плохое решение. В целом imgproxy клёвый, но он явно сделан не для этого. Из косяков, imgproxy не умеет в кеширование, всё что он делает, это выставляет правильные заголовки кеширования. Для решения этой проблемы пришлось настроит кеширующий nginx. Но проблему первого открытия это всё равно не решило, большие фоточки конвертировались медленно. Превью запрашивал под необходимый размер, но чтоб работало кеширование, округлял до 25 в большую сторону.

Lightbox быстро написал сам, получилось плохо не удобно и не красиво.

Сделал нормальный монорепозиторий. Для управления взял turborepo. Сразу вынес отдельно будущий общий код Photo lib и Photo lib share.

Задеплоил, собрал фидбек. Ожидаемо всё было плохо с lightbox. Так же загружались оригиналы в lightbox, что тоже не оч хорошая идея.

Вторая версия

Поменял схему базы. Теперь у меня есть Image с основной информацией вроде времени создания и exif. File с ссылкой на оригинальное фото. Thumbnail с ссылкой на всевозможные превью.

Выкинул imgproxy, вернул sharp. Теперь генерю webp и avif. Качество пока выставил 80 для webp и 65 для avif. Хотел добавить ещё heif и jxl, но для них нужно руками собирать плюсовую либу. Генерирую два размера, полноразмерную превью для показал в lightbox и 720px по длинной стороне для галереи. Так как avif генерируются медленно, использую очередь и отдельный поток для генерации. Для очереди пока что взял bullmq. Если никакой превью ещё не сгенерировано, то загружаю оригинальную фотку.

Выкинул самописный lightbox и взял photoswipe. Выбрал его в первую очередь из-за красивой анимации открытия фотки. Photoswipe написан без фреимворков, но его можно подключить например к реакту. Из косяков, у меня не подтягиваются типы. Так же взял framer-motion для красивой анимации появления фоток в галерее. Не уверен что это хорошее решение, но пока решил оставить так.

Взял tRPC вместо koa. Хотел попробовать Garph, но он пока что очень сырой, писал про это в Telegram канале. tRPC достаточно стабильный и удобный. Но мне не нравится что фронтенд проект импортирует бэкенд проект. Как минимум это замедляет билд. В идеале хотелось бы иметь возможность вынести схему отдельно, но пока не понял как это сделать удобно.

Добавил telegram бота для администрирования и загрузки фоток. Для этого взял grammY. Пока что бот умеет только загружать фотки, и запускать принудительную переиндексацию. Из ограничений, нельзя загружать фото больше 20мб, это можно обойти если самому хостить bot api, но пока что мне не хочется с этим разбираться.

Добавил Reproxy для простенькой реверспрокси. Nginx я настраивать не умею, а caddy кажется overkill для таких задач. Хотел чтоб всё красиво работало через лейблы, но почему-то не смог завести на маке docker sock. Но, меня и статичный конфиг устраивает.

ToDo

Планирую заменить bullmq на rabbitmq. Bullmq всем хорош, но он работает только с нодой и в экспериментальном режиме питоном. А хочется иметь больший выбор платформ.

Хочется попробовать перенести генерацию превью на rust. Это должно быть быстрее. Надеюсь что там не будет проблем с поддержкой модных форматов. Но я совсем не знаю раст, и это не тот язык который можно освоить за выходные.

Надо бы добавить альбомы. Но пока что не придумал как они должны выглядеть. Так же под это дело прийдётся дорабатывать бота.

Ну и уже можно начинать думать о работе над Photo lib. Там у меня куда больше планов.

Шесть лет разработки Telegram-бота: от токенайзера до LLM, RAG и векторных баз

Thu, 30 Jul 2026 00:00:00 GMT

Ио — это LLM-бот для Telegram-чатов. Он умеет отвечать на сообщения пользователей, распознавать изображения и голосовые сообщения, учитывать текущий тред, историю переписки и информацию о пользователе. Сейчас бот живёт в нескольких десятках чатов.

Расскажу, как я пилил его несколько лет, пытался научить помнить пользователей, разбирался с RAG и векторными базами и в итоге получил систему, которая действительно работает.

Как появилась идея?

Много лет назад существовало околокосмическое комьюнити Alpha Centauri. У него был оффтоп-чат, а в нём жил чат-бот. Никаких LLM тогда ещё не существовало, бот работал на регулярках, умел искать погоду, банить пользователей, запоминать информацию и прочие приколюхи. Чат вместе с ботом канул в Лету, а люди разбежались по другим чатам. И через какое-то время мне захотелось написать похожего бота.

Прототип из эпохи до LLM

Первая версия была написана летом 2020 года. В те времена только вышла GPT-3, в русский язык она не умела, да и до чатов не добралась, поэтому пришлось изобретать велосипеды. Я не знал регулярки, поэтому решил разбить текст на токены, выделить среди них смысловые и запустить нужную функцию.

Токенайзер работал так: удалял из текста ссылки, разбивал его по знакам препинания на предложения, затем предложения — на слова, переводил их в нижний регистр и применял стеммер.

Например, слова «расскажи» и «рассказать» превращаются в основу «расска», а «погода» и «погоду» — в «погод». Таким образом, список искомых команд не разрастался до десятков вариантов написания одного и того же. В русском языке есть всякие склонения, падежи и прочие усложнения, поэтому работало это не идеально.

Местами всё равно приходилось писать несколько вариантов:

switch (nextWorld) {
  case PorterStemmerRu.stem('мин'):
  case PorterStemmerRu.stem('минут'): {
    return number * 60;
  }
  case PorterStemmerRu.stem('час'): {
    return number * 60 * 60;
  }
  case PorterStemmerRu.stem('дня'):
  case PorterStemmerRu.stem('дней'):
  case PorterStemmerRu.stem('день'): {
    return number * 60 * 60 * 24;
  }
}

Среди первых функций были прогноз погоды, возможность банить пользователей, распознавание войсов и перевод текстов.

С погодой тоже были сложности. Пользователь мог писать имя города в разных вариантах, поэтому, чтобы определить город, я пользовался сервисом DaData. Сам прогноз брал и до сих пор беру из OpenWeather. Источник не лучший, зато бесплатный.

Ну а для перевода и распознавания войсов использовал сервисы Яндекса. Кружки тоже хотелось распознавать, поэтому пришлось затащить FFmpeg для извлечения аудио из видео.

В таком виде бот был заброшен на долгие три года. Мне, конечно же, хотелось затащить побольше фичей, но, во-первых, мешала прокрастинация, а во-вторых — сложность. Сделать что-то полезное и интересное на базе примитивного токенайзера было сложно.

Первые попытки с LLM

Сначала я попробовал написать отдельного бота. В тот момент удобного способа вызывать функции через LLM ещё не было. Получился примитивный бот на базе GPT-3.5 Turbo. Контекст хранился в оперативной памяти, поэтому после перезапуска ничего не сохранялось. Работал он только внутри треда.

С полученным опытом я пошёл переписывать Ио. LLM вызывалась, если пользователь обращался к боту, но ни одна из обычных команд не срабатывала.

В таком виде бот прожил до 2024 года. После этого я добавил нормальную работу с контекстом. Все сообщения хранились в базе данных. Каждое сообщение ссылается на реплай, таким образом строится дерево диалога. Такой подход позволял, например, получить другой ответ на тот же запрос: достаточно было ответить на нужное сообщение в истории, и бот продолжал диалог именно с этой точки, не затрагивая остальные ветки переписки.

В это же время я перешёл на GPT-4o mini и добавил Tool Calling, чтобы модель сама выбирала и вызывала нужные функции. Соответственно, все предыдущие костыли с токенайзером больше были не нужны и были выброшены. Заодно была выпилена функция банов пользователей, так как к тому моменту её никто уже не использовал.

Также я добавил поддержку изображений. Сначала бот просто передавал ссылку на картинку в каждый запрос к модели, но это оказалось слишком дорого. Поэтому обработку изображений я вынес в отдельный этап: когда пользователь отправляет фото, бот сразу прогоняет его через модель, получает текстовое описание и сохраняет его в базу. Позже, если картинка попадает в контекст диалога, используется уже готовое описание. В таком виде эта функция работает до сих пор.

Поскольку бота можно было свободно добавлять в любые чаты, обработка изображений сначала работала только в доверенных. Даже с этим ограничением бот съедал на моделях около $10–20 в месяц.

Учим бота запоминать информацию

Первая версия памяти

В 2025 году я начитался про RAG (Retrieval-Augmented Generation, метод работы с большим количеством данных), но был ещё не готов разбираться с векторными базами и прочими сложностями. Поэтому решил пойти самым простым путём. Добавил в базу поле metaInfo с JSON, в котором хранилась собранная информация о пользователе. Раз в 10 сообщений обновлял это поле таким запросом:

А дальше в каждый запрос добавлял эту информацию с такими приписками:

Память заработала, теперь Ио знала что-то о пользователе.

<details> <summary>Скрытый текст</summary>

</details>

Но память работала не идеально. У одной девушки было гендерно-нейтральное имя, и Ио ни в какую не хотела запоминать, что она девушка. Я переписал метаинформацию и добавил фактам веса. Теперь модель оценивала важность каждого факта, а я увеличивал вес, если он повторялся. Но и это не помогло. Информация о гендере пользователя, по мнению модели, оказалась совсем не важной) В итоге проблема решилась простым ручным редактированием базы.

Эта же пользовательница очень сильно старалась заставить Ио начать писать что-нибудь неприличное. Это вылилось в то, что Ио начала отвечать неадекватно вообще на все её сообщения.

Пришлось добавить возможность очистить память.

Теперь всё-таки векторы

В таком виде бот просуществовал до 2026 года. К этому времени из-за развития агентов порог входа в подобные эксперименты сильно снизился, и мне наконец захотелось попробовать векторные базы. В моём представлении RAG строился просто: взять все сообщения, положить их в векторную базу, а при новом запросе найти похожие и добавить их в контекст. Всё — модель знает историю пользователя и учитывает её в ответах. Как же сильно я ошибался.

Очень быстро выяснилось, что поиск похожих сообщений почти бесполезен. Большинство найденных сообщений были просто кусками старых диалогов без какой-либо долгосрочной ценности. Модели гораздо полезнее знать устойчивые факты о пользователе, чем перечитывать его переписку. Поэтому я продолжил использовать два подхода: векторный поиск по сообщениям и отдельное извлечение фактов.

После этого я переписал сбор фактов. Теперь модель извлекает факт и оценивает его важность. Затем векторный поиск находит среди сохранённых фактов похожие, а модель решает, нужно ли увеличить вес существующего факта, обновить его или сохранить новый.

Такая сложность нужна потому, что один и тот же факт модель каждый раз может формулировать немного по-разному. Заодно появилась возможность актуализировать информацию, если она противоречит старым данным. При новом запросе факты пользователя ранжируются по дате и важности, после чего в контекст попадает топ-10.

Мелкие полезные фичи

Суммаризация войсов. Если войс длинный, бот делает саммари, а оригинальный текст прячет под спойлер. Также прогоняю расшифровку через LLM, чтобы расставить знаки препинания и убрать повторы.

Guest Mode. Возможность призвать бота в любой чат и пообщаться с ним там. Это похоже на inline mode, только диалог не ограничивается одним запросом.

Поиск по Википедии. Позволяет модели хоть иногда не косячить в фактах.

Явная память. Возможность напрямую попросить бота что-нибудь запомнить. Это решило проблему, когда для исправления фактов приходилось руками лезть в базу.

Монетизация

Недавно запилил монетизацию. В бесплатной версии есть дневные лимиты на сообщения, распознавание картинок и войсов. Ограничение на сообщения мягкое: после достижения лимита бот переходит на более дешёвую модель. Можно купить подписку на неделю, месяц, три месяца или год. В зависимости от срока увеличивается ежедневный лимит. В качестве бонуса немного увеличиваются лимиты всем участникам чата, один из пользователей которого оформил подписку.

<details> <summary>Скрытый текст</summary>

</details>

Технологический стек

Изначально стек был таким: Node.js, TypeScript, Telegraf.js, OpenAI.

Позже с Telegraf.js я перешёл на grammY. У него удобный API, хорошая типизация, быстрая поддержка новых версий Telegram Bot API и много полезных расширений.

В качестве векторной базы изначально взял Qdrant. Для моих масштабов это оказалось оверкилом: незачем поддерживать отдельную БД, когда всё спокойно помещается в PostgreSQL. Поэтому недавно я перешёл на расширение pgvector.

Для работы с LLM сначала перешёл на LangChain, но он оказался слишком сложным. Поэтому в итоге мигрировал на AI SDK от Vercel.

В качестве провайдера сначала использовал OpenAI, затем перешёл на OpenRouter, а потом на RouterAI из-за проблем с оплатой.

Промпты и трейсы запросов храню в Langfuse. Для моих задач это оказалось не лучшим решением, потому что промпт у меня динамически изменяется, а возможностей шаблонов не хватает. В итоге сейчас статическая часть хранится в Langfuse, а динамическая подставляется одним куском. Трейсинг я почти не использую: пока не возникало задач, для которых хотелось бы регулярно туда смотреть.

Основная модель сейчас — Gemini 3.6 Flash, бюджетная — Gemini 2.5 Flash Lite. Для работы с фактами, суммаризации и распознавания картинок использую Nex-N2-mini.

Векторы изначально генерировал через OpenRouter, но с переходом на RouterAI генерация эмбеддингов стала занимать слишком много времени — от 10 до 60 секунд. Бот векторизует текущее сообщение при каждом запросе, чтобы найти подходящий контекст, что создаёт ощущение, что бот тормозит. Поэтому я поднял text-embeddings-inference с multilingual-e5-small. Качество пока не сравнивал, зато эмбеддинги генерируются быстро даже на небольшом сервере.

Отдельная история — инфраструктура. Сначала всё работало через Docker Compose, но при каждом деплое нужно было руками заходить на сервер, стягивать изменения и пересобирать бота. Это, конечно, можно было автоматизировать, но мне было лень. Поэтому потом бот переехал в Coolify. Там появились автоматическая сборка, развёртывание и бэкапы. Но сборка сильно нагружала сервер и могла вообще положить его на пару минут. Плюс возникали проблемы с обновлением базы данных.

Поэтому решил перелезть на k3s. Теперь GitHub Actions собирает образ бота, после чего он деплоится в k3s. Бэкапы отправляются в S3-хранилище на домашнем NAS. В планах дома поднять ещё один k3s и развернуть там мониторинг, чтобы было красиво. Тем более что с агентами это делать стало очень просто и быстро (хотя есть риск, что очередной агент когда-нибудь снесёт мне и базу, и бэкапы).

Планы

Настроить нормальный мониторинг. Починить баги, сейчас в Guest mode не сохраняется контекст например. Реализовать веб-поиск, ибо сейчас есть только поиск по Википедии. Доработать инфраструктуру: сейчас бот во время деплоя несколько минут недоступен.

Ио до сих пор остаётся для меня большим полигоном для экспериментов. Многие новые идеи из мира LLM и инфраструктуры я сначала пробую именно на нём. Пока проект продолжает приносить удовольствие — значит, всё было не зря. Попробовать бота можно в Telegram. Исходники лежат на GitHub.

TypeScript - номинальная типизация примитивных типов

Thu, 10 Feb 2022 00:00:00 GMT

Координаты

В моих задачах мне приходится много работать с библиотеками, использующими координаты. Разные библиотеки могут сохранять/передавать значения координат в разном виде. Например, это может быть объект с двумя полями или массив с двумя значениями. С массивом возникают некоторые сложности. В какой последовательности — и почему именно в такой — должны идти долгота и широта? Каждый автор библиотеки решает эту проблему по-своему, а нам страдать.

Было бы классно, написать что-то такое:

type Lat = number;
type Lng = number;

type LatLng = [Lat, Lng];
type LngLat = [Lng, Lat];

Но это не сработает, потому что в typescript используется структурная типизация, и оба типа работают как [number, number]. К счастью, номинальную типизацию можно эмулировать. Для этого к number нужно добавить уникальный признак:

type Lat = number & { __type: 'Lat' };
type Lng = number & { __type: 'Lng' };

Теперь типы Lat и Lng не будут равны друг другу, что нам и нужно было. Такой подход называется brand/opaque type. И чтобы было удобнее, можно написать алиас.

type Brand<T, U> = T & { __type: U };

Или взять готовую реализацию из библиотеки с утилитарными типами, например из utility-types или type-fest.

Тогда использование будет выглядеть как-то так:

type Lat = Brand<number, 'Lat'>;
type Lng = Brand<number, 'Lng'>;

type LatLng = [Lat, Lng];

const lat = 59.57 as Lat;
const lng = 30.19 as Lng;

const fn = (coords: LatLng) => {...};

fn([lat, lng]) // Всё ок

fn([lng, lat]) // Ошибка

Email

Кажется, что с адресом электронной почты можно поступить так же:

type Email = Brand<string, 'Email'>;

Но на самом в typescript 4.1 появились литеральные типы, и они позволяют творить магию. Например можно написать так:

type Email = `${string}@${string}.${string}`;

Таким образом, можно проверить что тут не случайная строка, а строка в особом формате, немного похожем на email.

const notEmail: Email = 'example'; // Ошибка

const email: Email = 'mail@example.com'; // Всё ок

Но тут нужно быть осторожным, ибо одно неверное движение — и всё сломается.

// Ошибки нет, хотя строка не правильного формата
const notEmail = 'example' as Email;

Валюты и немного дженериков

Представим, что приложение работает с разными валютами. И хочется на уровне типов запретить складывать доллары с рублями без конвертации.

type Rub = Brand<number, 'Rub'>;
type Usd = Brand<number, 'Usd'>;
type Eur = Brand<number, 'Eur'>;

Здесь полностью запретить сложение разных валют не выйдет, но если всегда для сложения валют использовать функцию — всё будет работать.

const sumRub = (a: Rub, b: Rub): Rub => {...};

В таком случае, нам для каждой валюты придётся писать свои функции.

Но можно использовать дженерики:

const sum = <T extends>(a: T, b: T): T => ...;

const aRub = 300 as Rub;
const bRub = 600 as Rub;
const cUsd = 30 as Usd;

sum(aRub, bRub) // Всё ок

sum(aRub, cUsd) // Ошибка

А теперь используя brand type и литеральные типы, напишем функцию для конвертации любой валюты в usd.

const toUsd = <Value extends Brand<number, B>, B extends string>(value: Value, currency: Brand<number, `${Value['__type']}ToUsd`>): Usd => {};

type RubToUsdCurrency = Brand<number, 'RubToUsd'>; 

const rubToUsdCurrency = 30 as RubToUsdCurrency;

toUsd(rub, rubToUsd); // Всё ок
toUsd(eur, rubToUsd); // Ошибка

Немного маги. Первый аргумент в дженерике - любой brand type. Второй аргумент - уникальная строка из brand type. Такое усложнение нужно, чтобы можно было вытащить эту уникальную строку. Тип currency можно было бы задать как Brand<number, `${B}ToUsd`>, но тогда при неправильном вызове функции typescript будет ругаться на первый аргумент. Если же написать Brand<number, `${Value['__type']}ToUsd`>, то ошибка будет во втором аргументе, что логичнее.