Чат-бот підтримки для українського магазину вітамінів 🇺🇦

Інтелектуальний чат-бот для консультацій клієнтів українського інтернет-магазину вітамінів та біологічно активних добавок (БАДів), побудований на основі OpenAI GPT-4o-mini та векторного пошуку Pinecone.

Особливості

✅ Відповіді виключно українською мовою - навіть на запити іншими мовами ✅ Векторний пошук товарів через Pinecone з метаданими ✅ Мінімум 3 товари у кожній відповіді ✅ Обов'язкове включення товарів Biotus або My Nutri Week ✅ Валідація релевантності запитів через GPT ✅ Історія розмови (до 6 останніх повідомлень) ✅ Фільтрація за доступністю (status=true, quantity>0) ✅ RESTful API з Express.js

Технології

Node.js + TypeScript
Express.js - веб-сервер
Pinecone - векторна база даних (index: vitamins-catalog-v2, dimensions: 1536)
OpenAI - GPT-4o-mini для діалогів, text-embedding-3-small для embeddings

Структура проекту

vitamin-support-bot/
├── src/
│   ├── config/
│   │   ├── pinecone.ts         # Підключення до Pinecone
│   │   └── openai.ts           # Підключення до OpenAI
│   ├── types/
│   │   └── product.ts          # TypeScript інтерфейси
│   ├── services/
│   │   ├── vectorSearch.ts     # Пошук товарів у Pinecone
│   │   └── chatbot.ts          # Логіка чат-бота
│   ├── utils/
│   │   ├── prompts.ts          # Системні промпти українською
│   │   └── validation.ts       # Валідація та утиліти
│   └── index.ts                # Express сервер
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
└── README.md

Швидкий старт

1. Встановлення залежностей

npm install

2. Налаштування змінних середовища

Створіть файл .env на основі .env.example:

cp .env.example .env

Заповніть змінні:

# Pinecone Configuration
PINECONE_API_KEY=your_pinecone_api_key_here
PINECONE_INDEX_NAME=vitamins-catalog-v2

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here

# Server Configuration
PORT=3000
NODE_ENV=development

# Application Configuration
MAX_PRODUCTS_PER_RESPONSE=10
MIN_PRODUCTS_PER_RESPONSE=3
SIMILARITY_THRESHOLD=0.7
MAX_CONVERSATION_HISTORY=6

3. Запуск сервера

Режим розробки (з автоматичним перезапуском):

npm run dev

Production режим:

npm run build
npm start

API Endpoints

`GET /`

Інформація про API

Відповідь:

{
  "message": "Вітаємо в API чат-бота підтримки магазину вітамінів! 🌟",
  "version": "1.0.0",
  "endpoints": { ... }
}

`GET /health`

Перевірка стану сервісу

Відповідь:

{
  "status": "healthy",
  "services": {
    "pinecone": "ok",
    "openai": "ok"
  },
  "environment": {
    "nodeEnv": "development",
    "port": 3000
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

`POST /chat`

Відправити повідомлення боту

Запит:

{
  "message": "Які вітаміни для імунітету?",
  "sessionId": "опціонально-uuid"
}

Відповідь:

{
  "success": true,
  "data": {
    "response": "Вітаю! Для підтримки імунітету рекомендую наступні товари...",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "productsFound": 5,
    "relevanceCheck": {
      "isRelevant": true,
      "reason": "Питання про вітаміни для імунітету"
    }
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Приклади запитів:

# Новий діалог (без sessionId)
curl -X POST http://localhost:3000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Привіт! Які вітаміни для енергії?"
  }'

# Продовження діалогу (з sessionId)
curl -X POST http://localhost:3000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "А що для дітей?",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000"
  }'

`DELETE /chat/:sessionId`

Видалити сесію розмови

Приклад:

curl -X DELETE http://localhost:3000/chat/550e8400-e29b-41d4-a716-446655440000

Відповідь:

{
  "success": true,
  "message": "Сесію успішно видалено",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

`GET /stats`

Отримати статистику сесій (для адміністрування)

Відповідь:

{
  "success": true,
  "data": {
    "totalSessions": 5,
    "sessions": [
      {
        "sessionId": "550e8400-e29b-41d4-a716-446655440000",
        "messageCount": 8,
        "createdAt": "2025-01-15T10:00:00.000Z",
        "lastUpdatedAt": "2025-01-15T10:30:00.000Z"
      }
    ]
  },
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Структура метаданих товарів у Pinecone

Кожен товар у Pinecone індексі має наступні метадані:

{
  id: string;              // Унікальний ID
  product_id: string;      // ID продукту
  name: string;            // Назва товару
  brand: string;           // Бренд
  sku: string;             // SKU код
  price: number;           // Ціна в грн
  description: string;     // Опис товару
  categories: string;      // Категорії
  form: string;            // Форма випуску (капсули, таблетки, порошок)
  package: string;         // Упаковка
  flavor: string;          // Смак
  age: string;             // Вікова категорія
  active: boolean;         // Чи активний товар
  quantity: number;        // Кількість на складі
  status: boolean;         // Статус доступності
}

Логіка роботи бота

1. Валідація релевантності

Перед обробкою запиту бот перевіряє, чи стосується питання вітамінів/БАДів:

✅ Релевантні теми: вітаміни, мінерали, БАДи, спортивне харчування, імунітет, схуднення
❌ Нерелевантні: ліки, діагнози, загальні розмови, інші товари

2. Векторний пошук

Створення embedding запиту через OpenAI text-embedding-3-small
Пошук у Pinecone з фільтрами: status=true, quantity>0
Мінімальний score схожості: 0.7

3. Гарантовані бренди

Бот завжди намагається включити товари брендів:

Biotus
My Nutri Week

4. Мінімум товарів

Якщо знайдено менше 3 товарів, додаються популярні товари.

5. Генерація відповіді

GPT-4o-mini генерує відповідь українською з урахуванням:

Контексту розмови (6 останніх повідомлень)
Знайдених товарів
Системних інструкцій

Приклади використання

Приклад 1: Першій запит

Запит:

{
  "message": "Привіт! Потрібні вітаміни для імунітету"
}

Відповідь:

Вітаю! 👋

Я - ваш персональний консультант з вітамінів та біологічно активних добавок.

Для підтримки імунітету рекомендую наступні товари:

📋 Рекомендовані товари:

1. **Вітамін C 1000мг** від Biotus
   - Ціна: 350 грн
   - Форма: капсули
   - Опис: Потужний антиоксидант для підтримки імунітету

2. **Цинк + Вітамін D3** від My Nutri Week
   - Ціна: 280 грн
   - Форма: таблетки
   - Опис: Комплекс для зміцнення захисних функцій організму

3. **Імуно Комплекс** від Nature's Bounty
   - Ціна: 420 грн
   - Форма: капсули
   - Опис: Збалансована формула вітамінів та мінералів

💡 Додаткові поради:
Приймайте вітаміни регулярно, бажано під час їжі. Рекомендую проконсультуватися з лікарем щодо дозування.

Приклад 2: Нерелевантний запит

Запит:

{
  "message": "Яка погода сьогодні?"
}

Відповідь:

Вибачте, але я спеціалізуюсь виключно на консультаціях щодо вітамінів, мінералів та біологічно активних добавок (БАДів).

Я з радістю допоможу вам з:
- Підбором вітамінів для здоров'я
- Рекомендаціями БАДів для різних потреб
- Інформацією про наявні товари в магазині
- Порадами щодо застосування добавок

Чи можу я допомогти вам знайти потрібні вітаміни або добавки?

Обмеження та особливості

Обмеження

Максимальна довжина повідомлення: 500 символів
Історія зберігається тільки в пам'яті (втрачається при перезапуску)
Старі сесії автоматично видаляються через 24 години
Не надає медичних рекомендацій і не діагностує хвороби

Особливості

Відповідає тільки українською, незалежно від мови запиту
Завжди включає мінімум 3 товари
Пріоритет брендам Biotus та My Nutri Week
Не вигадує інформацію - тільки з Pinecone

Розробка

Структура коду

// TypeScript інтерфейси
src/types/product.ts

// Конфігурації
src/config/pinecone.ts
src/config/openai.ts

// Сервіси
src/services/vectorSearch.ts  // Пошук товарів
src/services/chatbot.ts        // Логіка бота

// Утиліти
src/utils/prompts.ts           // Промпти українською
src/utils/validation.ts        // Валідація

// Сервер
src/index.ts

Скрипти

npm run dev      # Режим розробки з hot-reload
npm run build    # Компіляція TypeScript
npm start        # Запуск production версії
npm run lint     # Перевірка коду

Production deployment

Docker (рекомендовано)

Створіть Dockerfile:

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["npm", "start"]

Збірка та запуск:

docker build -t vitamin-chatbot .
docker run -p 3000:3000 --env-file .env vitamin-chatbot

Змінні середовища для production

NODE_ENV=production
PORT=3000
PINECONE_API_KEY=***
OPENAI_API_KEY=***
PINECONE_INDEX_NAME=vitamins-catalog-v2

Troubleshooting

Помилка: "PINECONE_API_KEY не знайдено"

Переконайтесь, що .env файл створено і містить правильні ключі.

Помилка: "Індекс vitamins-catalog-v2 не знайдено"

Перевірте назву індексу в Pinecone та .env файлі.

Бот повертає мало товарів

Перевірте:

Чи є товари в Pinecone з status=true та quantity>0
Знизьте SIMILARITY_THRESHOLD в .env

Повільні відповіді

Перевірте мережеве з'єднання з Pinecone та OpenAI
Розгляньте можливість кешування популярних запитів

Ліцензія

MIT

Автор

Створено для українського магазину вітамінів 🇺🇦

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
CARD_FORMAT_CHANGES.md		CARD_FORMAT_CHANGES.md
FRONTEND_API.md		FRONTEND_API.md
IMPROVEMENTS.md		IMPROVEMENTS.md
README.md		README.md
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Чат-бот підтримки для українського магазину вітамінів 🇺🇦

Особливості

Технології

Структура проекту

Швидкий старт

1. Встановлення залежностей

2. Налаштування змінних середовища

3. Запуск сервера

Режим розробки (з автоматичним перезапуском):

Production режим:

API Endpoints

GET /

GET /health

POST /chat

DELETE /chat/:sessionId

GET /stats

Структура метаданих товарів у Pinecone

Логіка роботи бота

1. Валідація релевантності

2. Векторний пошук

3. Гарантовані бренди

4. Мінімум товарів

5. Генерація відповіді

Приклади використання

Приклад 1: Першій запит

Приклад 2: Нерелевантний запит

Обмеження та особливості

Обмеження

Особливості

Розробка

Структура коду

Скрипти

Production deployment

Docker (рекомендовано)

Змінні середовища для production

Troubleshooting

Помилка: "PINECONE_API_KEY не знайдено"

Помилка: "Індекс vitamins-catalog-v2 не знайдено"

Бот повертає мало товарів

Повільні відповіді

Ліцензія

Автор

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`GET /`

`GET /health`

`POST /chat`

`DELETE /chat/:sessionId`

`GET /stats`

Packages