Локальна LLM для перекладу та зіставлення в abrest

Цей посібник описує налаштування локального LLM-сервера для функцій перекладу при імпорті та зіставлення товарів на основі векторних представлень (embeddings).

Вимоги до обладнання

Складова	Мінімум	Рекомендовано
Оперативна пам'ять	8 ГБ	16+ ГБ
Процесор	4 ядра	8+ ядер
Відеокарта	не потрібна	NVIDIA з 8+ ГБ відеопам'яті
Диск	10 ГБ вільно	20+ ГБ вільно

Обчислення лише на процесорі працює і для векторних представлень, і для генерації тексту. Відеокарта суттєво прискорює генерацію тексту (переклад і підтвердження зіставлення).

Встановлення Ollama

Ollama — рекомендований LLM-сервер. Він надає API, сумісний з OpenAI, і самостійно керує завантаженням моделей.

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Перевірка встановлення
ollama --version

Типово Ollama працює як служба systemd на порту 11434.

Завантаження потрібних моделей

Abrest використовує дві моделі: генеративну — для перекладу та підтвердження зіставлення, і модель векторних представлень — для пошуку за схожістю.

# Генеративна модель (переклад + підтвердження зіставлення)
ollama pull qwen3:8b

# Модель векторних представлень (схожість векторів)
ollama pull nomic-embed-text

Інші сумісні моделі:

Призначення	Модель	Розмір	Примітки
Переклад	`qwen3:8b`	~5 ГБ	Добра підтримка багатьох мов
Переклад	`gemma3:12b`	~8 ГБ	Сильна багатомовність, потребує більше пам'яті
Переклад	`llama3.1:8b`	~5 ГБ	Добра універсальна модель
Вектори	`nomic-embed-text`	~275 МБ	768 вимірів, багатомовна
Вектори	`mxbai-embed-large`	~670 МБ	1024 виміри
Вектори	`all-minilm`	~45 МБ	384 виміри, найшвидша

Перевірка API

Перевірка генерації тексту:

curl -s http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3:8b",
    "messages": [
      {"role": "system", "content": "Translate the product name from uk to en. Return only the translation."},
      {"role": "user", "content": "Молоко пастеризоване 2.5%"}
    ],
    "temperature": 0.1
  }'

У відповіді очікується "content": "Pasteurized milk 2.5%" (або подібне).

Перевірка векторних представлень:

curl -s http://localhost:11434/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nomic-embed-text",
    "input": "Laptop HP ProBook 450"
  }'

У відповіді очікується масив "data" з масивом чисел "embedding".

Налаштування abrest

Додайте або оновіть секцію translation: у файлі abrest.yaml:

translation:
  enabled: true
  api_url: 'http://localhost:11434/v1'
  model: 'qwen3:8b'
  embedding_model: 'nomic-embed-text'
  match_threshold: 0.80
  timeout: 30

Ключ	Типове значення	Опис
`enabled`	`false`	`true` вмикає переклад і векторні представлення
`provider`	`openai_compatible`	Різновид API для генерації
`api_url`	`http://localhost:11434/v1`	Базова адреса API, сумісного з OpenAI
`api_key`	(порожньо)	Надсилається як bearer-токен; для локальної Ollama залиште порожнім
`model`	`qwen3:8b`	Назва моделі для перекладу та підтвердження зіставлення
`embedding_provider`	(як `provider`)	Різновид API для векторних представлень
`embedding_api_url`	(як `api_url`)	Задавайте, лише якщо вектори обчислює окремий сервер
`embedding_api_key`	(як `api_key`)	Обліковий ключ для окремого сервера векторів
`embedding_model`	`nomic-embed-text`	Назва моделі для обчислення векторів
`match_threshold`	`0.80`	Поріг косинусної схожості для кандидатів зіставлення (0.0-1.0)
`timeout`	`30`	Тайм-аут HTTP-запиту в секундах

Чотири запасні значення embedding_* означають, що для однієї локальної Ollama додаткові ключі не потрібні: задавайте їх, лише якщо генерація і вектори працюють на різних серверах.

Після зміни конфігурації перезапустіть abrest.

Початкове наповнення векторів

Після першого вмикання перекладу для наявних товарів у R_TOVAR треба обчислити вектори. Це разова операція:

curl -s -X POST http://localhost:4603/api/tools/embeddings/rebuild \
  -H "X-API-KEY: your-api-key"

Відповідь:

{"processed": 12345, "failed": 2}

Операція виконується синхронно і для великих каталогів може тривати кілька хвилин (~15 мс на товар з nomic-embed-text). Для товарів, імпортованих після цього, вектори обчислюються автоматично під час імпорту.

Усунення несправностей

«Translation is not enabled» Перевірте, що в секції translation: файлу abrest.yaml встановлено enabled: true, і перезапустіть abrest.

Переклад повертає порожні рядки - Перевірте, що Ollama працює: systemctl status ollama - Переконайтеся, що модель завантажена: ollama list - Пошукайте в журналі abrest попередження «LLM API call failed» - Перевірте API вручну через curl (див. вище)

Перебудова векторів показує багато помилок - Товари з порожньою назвою пропускаються (це очікувано) - Перевірте, скільки пам'яті споживає Ollama — модель векторів має бути завантажена - Збільште timeout, якщо сервер відповідає повільно

Імпорт із увімкненим перекладом працює повільно - Кожен товар потребує 1-2 звернень до LLM (вектор + можливе підтвердження зіставлення) - Розгляньте відеокарту для генерації тексту або меншу та швидшу модель - Обчислення векторів швидке (~15 мс на товар) навіть на процесорі - Уже перекладені чи зіставлені товари пропускаються (операція ідемпотентна)

Зміна моделі векторних представлень При переході на іншу модель наявні вектори стають несумісними. Запустіть перебудову, щоб обчислити всі вектори новою моделлю. Старі вектори перезаписуються автоматично.