Словарь, который можно поднять рядом со своим приложением
Vocab Bloom Hub — self-hosted английский словарь: 300 000 записей со значениями, примерами, формами и переводами на русский, испанский, французский, немецкий, португальский, китайский и арабский за публичным read-only API, с SDK, админкой и опубликованным датасетом. Установка одной командой, MIT для кода, CC BY 4.0 для данных.
Установка одной командой
Достаточно compose-файла и шаблона переменных: образы скачиваются из GitHub Container Registry, Postgres поднимается рядом, словарь загружается сам при первом старте.
mkdir vocab-bloom-hub && cd vocab-bloom-hub
curl -fsSLO https://raw.githubusercontent.com/Fristail27/vocab-bloom-hub/main/docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/Fristail27/vocab-bloom-hub/main/.env.example -o .env
# edit .env: ADMIN_PASSWORD, POSTGRES_PASSWORD
docker compose up -d
curl -s localhost:3010/api/ready # {"status":"ok"} once the dictionary is in
Что внутри
Публичный API
Версионированный, только чтение, без логина: поиск с допуском опечаток, слово со значениями, формами, переводами, синонимами и антонимами, пакетный поиск, списки с курсорной пагинацией, случайное слово — каждый ответ в одном конверте, с ETag-кэшем.
SDK
Типизированные клиенты для Node.js / TypeScript и Python, сгенерированные из одного OpenAPI-документа: метод на эндпоинт, обход по курсору, типизированные ошибки, ETag-кэш, опциональные повторы запросов, DataFrame для ноутбуков.
Админка
Редактирование слов, значений, переводов, синонимов и антонимов в браузере, статистика, импорт и экспорт всего словаря как датасета.
Датасет
Словарь опубликован на HuggingFace под CC BY 4.0 и сам загружается в пустой инстанс; экспорт переносит его между окружениями, в том числе офлайн.
Для эксплуатации
Health и readiness probes, graceful shutdown, миграции на старте, метрики Prometheus, структурированные JSON-логи с request id — то, что нужно сервису, который запускает кто-то другой.
Поиск
Точный, префиксный, нечёткий и по переводам — на индексах Postgres: горячие запросы отвечают за миллисекунды на полном словаре.
Два SDK, один контракт
Оба клиента генерируются из закоммиченного OpenAPI-документа публичного API и не расходятся с сервером.
Node.js / TypeScript
import { VocabBloomClient } from '@vocab-bloom-hub/client';
const client = new VocabBloomClient({ baseUrl: 'https://your-instance.example/api' });
const { data } = await client.search({ search: 'runing', limit: 5 }); // typo tolerant
const run = await client.word('run'); // every part of speech, forms, meanings, translations
for await (const word of client.iterateWords({ part_of_speech: ['verb'], word_level: ['b1'] })) {
console.log(word.word);
}
Python
from vocab_bloom_hub import VocabBloomClient
client = VocabBloomClient("https://your-instance.example/api")
hits = client.search("runing", limit=5) # typo tolerant
run = client.word("run") # forms, meanings, translations
for word in client.iter_words(part_of_speech=["verb"], word_level=["b1"]):
print(word.word)
df = client.words_dataframe(part_of_speech=["noun"]) # pip install "vocab-bloom-hub[pandas]"
Данные и лицензия
Код — MIT. Данные словаря — те, что отдаёт API, экспортируются в датасеты и опубликованы на HuggingFace, — CC BY 4.0: свободно использовать и изменять, в том числе коммерчески, с указанием авторства. Они в основном сгенерированы LLM и не проверены людьми; прочитайте, что это значит, прежде чем на них полагаться.