_OpenSource Web4 agent & app starter kit_

# Поиск по смыслу, посчитанный на вашем компьютере

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

[Подключить элемент](#connect)
[Как устроено](#hood)

## Как текст становится вектором

#### Ваш элемент

Присылает свои тексты: строку дневника, вопрос, описание навыка. До 256 за один вызов.

#### Embeddings

Проверяет ключ узла и передаёт тексты модели, по одной пачке за раз.

#### Модель

Читает до 128 токенов каждого текста на любом из примерно 50 языков.

#### 384 числа

Каждый текст возвращается вектором, и тексты с одинаковым смыслом оказываются рядом.

Векторы хранят элемент vectors, граф знаний и глубокая память и находят текст по смыслу, какими бы словами и на каком бы языке ни был задан вопрос.

## Включён, засыпает только при нехватке памяти

Элемент запускается вместе с узлом. Когда свободной памяти меньше 0,5 ГБ, узел может его усыпить; первый вызов или запись календаря будят его за секунды, а при 1 ГБ свободной памяти он возвращается сам.

## Один смысл — одно место

Каждая полоска — одно из 384 чисел. «Привет» и «Hello» — одно приветствие на двух языках, поэтому их векторы почти совпадают. «Fix a leaking kitchen faucet» значит другое и с приветствием почти ничего общего не имеет. Число рядом со строкой — её косинус с первой строкой: 1 — тот же смысл, 0 — ничего общего.

- Привет
- Hello
- Fix a leaking kitchen faucet

Это векторы из собственной проверки элемента, посчитанные на Mac с Intel. Linux, Windows и Apple silicon дают те же числа.

## Что меняется для вас

| Без него | С элементом embeddings |
| --- | --- |
| Для поиска по смыслу нужен ключ OpenAI и счёт за каждый текст | Ни ключа, ни счёта: модель работает на вашем компьютере |
| Каждый сохранённый текст уходит во внешний сервис | Тексты не покидают компьютер |
| Модель за чужим API может смениться без предупреждения | Файл модели закреплён контрольной суммой и меняется только по решению владельца |
| Векторы, посчитанные в другом месте, могут не совпасть с вашими | Один и тот же текст даёт один и тот же вектор на Linux, Windows и macOS — проверено |
| Каждый элемент считает векторы по-своему | Одна модель и одна дверь на весь узел |

## Рядом с моделью OpenAI

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

|  | Embeddings узла | OpenAI text-embedding-3-small |
| --- | --- | --- |
| Где считается | На вашем компьютере | На серверах OpenAI, через интернет |
| Ключ и счёт | Не нужны | Ключ OpenAI; около 62 500 страниц на доллар |
| Куда уходят тексты | Никуда | В OpenAI |
| Размер вектора | 384 числа | 1536 чисел |
| Сколько текста читает | 128 токенов | 8192 токена |

Цифры OpenAI — из её руководства по эмбеддингам, developers.openai.com/api/docs/guides/embeddings.

## Подключите свой элемент

Любой элемент узла зовёт дверь на этом компьютере с ключом узла. Он присылает до 256 текстов и получает по одному нормированному вектору на каждый, в том же порядке.

```
curl -s "$EMBEDDINGS_URL/api/embed" \
  -H "X-Node-Key: $SETTINGS_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"texts":["Привет","Hello"]}'

{ "model": "paraphrase-multilingual-MiniLM-L12-v2", "dims": 384,
  "vectors": [[0.0356, 0.0416, …], [0.0312, …]] }
```

`GET /api/embed-status` называет модель, её размер и готова ли она. Вызывающий узнаёт размер здесь и никогда не подставляет его сам.

## Что под капотом

| Часть | Что это |
| --- | --- |
| Модель | `paraphrase-multilingual-MiniLM-L12-v2` от sentence-transformers: 384 числа, около 50 языков, 128 токенов каждого текста, усреднение по токенам, нормированные векторы |
| Среда | `onnxruntime-node` 1.21.0 через `@huggingface/transformers` 3.8.1, внутри собственного процесса элемента, без Python |
| Файл | 235 МБ, скачивается один раз из релиза самого элемента на GitHub и сверяется по sha256 перед каждой загрузкой |
| Память | Около 0.8 ГБ после загрузки, до 1.0 ГБ, пока считаются 100 текстов |
| Скорость | Короткий текст — за 6–25 мс, 100 длинных — примерно за 8 секунд на ноутбуке Intel 2016 года |
| Смена модели | Пришлось бы пересчитать каждый сохранённый вектор узла, поэтому решает только владелец |

## Свой строитель в комплекте

Каждый элемент узла приходит со своим агентом Claude Code и может получить свой Telegram-бот. Нужно что-то поменять в этом элементе — напишите его боту с телефона, и агент обновит логику или дизайн.

Агент работает только в папке своего элемента и не читает весь узел, поэтому каждая правка стоит меньше токенов. Платит за неё ваша подписка Claude Code.

- Бот элемента подключается в ядре, на его странице «Telegram».
- Агент возвращает коммит; вы смотрите его в «Предпросмотре» и принимаете или отклоняете.
- За компьютером терминал агента — в ядре, в разделе «Сборка» этого элемента.

## Открытый код

Сделано Fractera для протокола [Lagrix](https://lagrix.dev) и для любого web2-проекта, которому нужен поиск по смыслу без внешнего сервиса. Код открыт по лицензии MIT: [Fractera/fractera-embeddings-starter](https://github.com/Fractera/fractera-embeddings-starter). Модель — [paraphrase-multilingual-MiniLM-L12-v2](https://huggingface.co/sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2), авторы Nils Reimers и Iryna Gurevych, в ONNX-версии Qdrant, Apache-2.0.

## Вопросы и ответы

**Уходит ли что-то с моего компьютера?**
Нет. Тексты, модель и векторы остаются на компьютере; ни ключ, ни интернет не нужны.

**Когда модель OpenAI лучше?**
Для длинных текстов одним куском: она читает до 8192 токенов, эта модель — 128. Для коротких текстов узла, строки дневника или вопроса, локальной модели хватает.

**Одинаковы ли векторы на разных компьютерах?**
Да. Один и тот же текст даёт один и тот же вектор на Linux, Windows и macOS; элемент проверяет это сам.